{"record":{"id":"9ec29a828382c784","repo":"paperclipai/paperclip","slug":"native-runner-authority-archive-incomplete","errorCode":"native_runner_authority_archive_incomplete","errorMessage":"native_runner_authority_archive_incomplete","messagePattern":"native_runner_authority_archive_incomplete","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/live/runnerd-codex-transport.ts","lineNumber":343,"sourceCode":"    mkdirSync(archive, { mode: 0o700 });\n  }\n  assertRealDirectory(archive);\n  const activeControlPlane = resolve(root, \"control-plane\");\n  if (existsSync(activeControlPlane)) {\n    assertRealDirectory(activeControlPlane);\n    if (existsSync(archivedControlPlane)) {\n      throw new Error(\"native_runner_authority_archive_conflict\");\n    }\n    renameSync(activeControlPlane, archivedControlPlane);\n  }\n  if (existsSync(runnerStatePath)) {\n    if (existsSync(archivedRunnerState)) {\n      throw new Error(\"native_runner_authority_archive_conflict\");\n    }\n    renameSync(runnerStatePath, archivedRunnerState);\n  }\n  if (!existsSync(archivedControlPlane) || !existsSync(archivedRunnerState)) {\n    throw new Error(\"native_runner_authority_archive_incomplete\");\n  }\n  return controlPlaneState;\n}\n\nasync function rotateExternalAuthorityEpoch(\n  root: string,\n  controlPlaneState: Record<string, unknown>,\n  desired: DurableRecoveryIdentity,\n  readRunnerState: () => Promise<Record<string, unknown>>,\n  archiveRunnerState: (input: {\n    archiveKey: string;\n    priorIdentity: DurableRecoveryIdentity;\n  }) => Promise<Record<string, unknown>>,\n): Promise<Record<string, unknown>> {\n  const priorIdentity = controlPlaneIdentity(controlPlaneState);\n  if (\n    priorIdentity.runnerInstanceId !== desired.runnerInstanceId ||\n    priorIdentity.environmentLeaseId !== desired.environmentLeaseId ||","sourceCodeStart":325,"sourceCodeEnd":361,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/live/runnerd-codex-transport.ts#L325-L361","documentation":"After renaming the active control-plane directory and the runner state file into the archive, rotateLocalAuthorityEpoch verifies that both archived paths exist. If either rename silently failed or the source paths were missing, the durable transaction marker is incomplete, so the function throws this error. This is a post-condition check guaranteeing the archive is recoverable before the rotation returns.","triggerScenarios":"Calling rotateLocalAuthorityEpoch when, after the rename steps, either the archived control-plane directory or the archived runner-state file does not exist on disk — typically because the source path was absent (renameSync skipped or failed) or the filesystem operation failed silently.","commonSituations":"External deletion of active control-plane/runner-state files between checks and renames; network/overlay filesystems where renames are unreliable; a partially cleaned data root missing one of the two active paths; a prior crash left the root in a half-rotated state.","solutions":["Inspect the root directory and confirm which of control-plane / runner state exists actively vs archived","Restore the missing source file from backup or let the controller re-create it, then retry the rotation","Check filesystem health/mount type if renames report success but files are missing","Avoid sharing the same data root across concurrent runnerd processes"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if (!existsSync(activeControlPlanePath) || !existsSync(runnerStatePath)) {\n  throw new Error(\"active authority files missing; rotation would produce an incomplete archive\");\n}","typeGuard":"const hasCompleteActiveAuthority = (root: string) =>\n  existsSync(resolve(root, \"control-plane\")) && existsSync(resolve(root, \"runner-state\"));","tryCatchPattern":"try {\n  rotateLocalAuthorityEpoch(root, desired);\n} catch (err) {\n  if ((err as Error).message === \"native_runner_authority_archive_incomplete\") {\n    restoreAuthorityFromBackup(root); // or rebuild state\n  } else throw err;\n}","preventionTips":["Verify both active paths exist before rotating","Avoid network/overlay filesystems for durable runner state","Back up control-plane and runner state before rotation"],"tags":["filesystem","durability","invariant"],"backgroundTag":"internal-invariant-violation","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}