{"record":{"id":"e0c2f1a97440d98e","repo":"paperclipai/paperclip","slug":"native-runner-authority-archive-unsafe","errorCode":"native_runner_authority_archive_unsafe","errorMessage":"native_runner_authority_archive_unsafe","messagePattern":"native_runner_authority_archive_unsafe","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/live/runnerd-codex-transport.ts","lineNumber":213,"sourceCode":"}\n\nfunction assertSuspendedRunnerState(\n  state: Record<string, unknown>,\n  expected: DurableRecoveryIdentity,\n): void {\n  if (\n    state.schema !== \"paperclip.runner.durable.state.v1\" ||\n    !recoveryIdentityMatches(state, expected) ||\n    state.lifecycle !== \"suspended\"\n  ) {\n    throw new Error(\"native_runner_authority_rotation_requires_settled_state\");\n  }\n}\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(","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/live/runnerd-codex-transport.ts#L195-L231","documentation":"assertRealDirectory() verifies that a required state-root path (runtime state root, archive directory, control-plane dir, or maintenance state dir) is a real directory and not a symlink, using lstatSync. It throws native_runner_authority_archive_unsafe when the path is missing as a directory, is a symlink, or is a regular file. This prevents authority rotation and quarantine operations from following links or operating on unexpected file types.","triggerScenarios":"quarantineLocalRuntimeState, latestArchivedControlPlaneState, rotateLocalAuthorityEpoch, rotateExternalAuthorityEpoch, or readMaintenanceState is given a path that is a symlink, a plain file, or not a directory at all.","commonSituations":"State root configured to a symlinked path (common with dotfile managers or mounted volumes); someone replaced the state directory with a file; the directory was deleted while the runner was down; tmpfs/bind-mount layouts in containers.","solutions":["Run `ls -la` on the configured state root; replace symlinks with real directories (or copy contents into a real directory)","Recreate the missing directory with `mkdir -p` and correct ownership/permissions (0700)","Fix the runner state-root configuration to point at an actual directory","If the layout is unrecoverable, move the directory aside and let the runner re-initialize fresh state"],"exampleFix":"// before\nPAPERCLIP_RUNNER_STATE_ROOT=~/dotfiles/runner-state  # symlink\n// after\nmkdir -p ~/var/paperclip/runner-state && cp -a ~/dotfiles/runner-state/. ~/var/paperclip/runner-state/\nPAPERCLIP_RUNNER_STATE_ROOT=~/var/paperclip/runner-state","handlingStrategy":"validation","validationCode":"import { lstatSync } from \"node:fs\";\nfunction isRealDirectory(p: string): boolean {\n  try {\n    const m = lstatSync(p);\n    return m.isDirectory();\n  } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  runner.start();\n} catch (err) {\n  if (err.code === \"native_runner_authority_archive_unsafe\") {\n    logger.error(\"state root is not a real directory (symlink/file/missing)\", { path });\n    recreateStateRoot();\n  } else throw err;\n}","preventionTips":["Pre-create the state root as a real directory with mode 0700","Avoid symlinked paths (dotfile managers, mounts) for state roots","Smoke-check the state root layout before starting/resuming the runner","In containers, use plain bind mounts of real directories"],"tags":["filesystem","security","directory","codex"],"backgroundTag":"path-is-not-a-directory","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"}