{"record":{"id":"a1a0270e551404ee","repo":"paperclipai/paperclip","slug":"native-runner-state-quarantined","errorCode":"native_runner_state_quarantined","errorMessage":"native_runner_state_quarantined: ${detail}; the prior state was preserved for operator recovery","messagePattern":"native_runner_state_quarantined: (.+?); the prior state was preserved for operator recovery","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/paperclip-runner/src/live/runnerd-codex-transport.ts","lineNumber":226,"sourceCode":"}\n\nfunction assertRealDirectory(path: string): void {\n  const metadata = lstatSync(path);\n  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {\n    throw new Error(\"native_runner_authority_archive_unsafe\");\n  }\n}\n\nfunction quarantineLocalRuntimeState(root: string, reason: unknown): never {\n  assertRealDirectory(root);\n  const quarantine = resolve(\n    dirname(root),\n    `${basename(root)}.quarantine-${randomUUID()}`,\n  );\n  renameSync(root, quarantine);\n  mkdirSync(root, { mode: 0o700 });\n  const detail = reason instanceof Error ? reason.message : String(reason);\n  throw new Error(\n    `native_runner_state_quarantined: ${detail}; the prior state was preserved for operator recovery`,\n  );\n}\n\nfunction authorityArchiveDirectory(\n  root: string,\n  identity: DurableRecoveryIdentity,\n): string {\n  const digest = createHash(\"sha256\")\n    .update(JSON.stringify(identity))\n    .digest(\"hex\")\n    .slice(0, 24);\n  return resolve(root, \"authority-epochs\", `epoch-${digest}`);\n}\n\nfunction latestArchivedControlPlaneState(\n  root: string,\n  desired: DurableRecoveryIdentity,","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/live/runnerd-codex-transport.ts#L208-L244","documentation":"quarantineLocalRuntimeState() is the last-resort recovery path: when resuming (#resume) finds state it cannot safely load, it renames the entire state root to '<root>.quarantine-<uuid>', creates a fresh 0700 directory, and throws native_runner_state_quarantined with the original cause embedded. The old state is preserved at the quarantine path for operator recovery — nothing is deleted.","triggerScenarios":"#resume() encounters a state-loading/validation error (e.g. unsafe or unparseable state files) that makes continuing unsafe, triggering quarantine of the runtime state root before throwing.","commonSituations":"Corrupted or hand-edited state after a crash; state written by an incompatible runner version; operator experimentation with the state directory mid-run; disk-level corruption.","solutions":["Read the embedded detail after 'native_runner_state_quarantined:' — it names the original failure","Recover data from the sibling directory '<root>.quarantine-<uuid>' left next to the state root","After inspecting/reconciling, delete or move the quarantine directory and restart the runner with fresh state","Fix the root cause (version mismatch, manual edits, corruption) before resuming again, or it will re-quarantine"],"exampleFix":"// before\nls data/runner-state            # fresh empty dir\ncp -a data/runner-state.quarantine-<uuid>/control-plane data/runner-state/\n// after\nmv data/runner-state.quarantine-<uuid> data/runner-state.recovered &&\n# reconcile/inspect data/runner-state.recovered, then re-init data/runner-state cleanly","handlingStrategy":"try-catch","validationCode":"import { existsSync, readdirSync } from \"node:fs\";\nfunction findQuarantines(root: string): string[] {\n  return existsSync(root) ? readdirSync(root, { withFileTypes: false })\n    .filter((n) => n.startsWith(\".quarantine-\")) : [];\n}","typeGuard":null,"tryCatchPattern":"try {\n  await transport.resume();\n} catch (err) {\n  if (String(err.message).startsWith(\"native_runner_state_quarantined:\")) {\n    const cause = String(err.message).split(\":\")[1];\n    logger.error(\"runner state quarantined; original cause:\", { cause });\n    inspectQuarantineDirAndReinit();\n  } else throw err;\n}","preventionTips":["Never hand-edit runner state files","Pin a compatible runner version for the state schema in use","Back up the state root before upgrades","On resume failure, read the embedded cause in the quarantine error before restarting"],"tags":["filesystem","recovery","quarantine","codex"],"backgroundTag":"invalid-state-transition","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}