open-multi-agent-kit 0.96.2 → 0.98.0

package/dist/core/recovery-checkpoint.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"recovery-checkpoint.d.ts","sourceRoot":"","sources":["../../src/core/recovery-checkpoint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `omk.recovery.checkpoint` — pure decision algorithms for native worktree/\n * conversation recovery checkpoints.\n *\n * This module is intentionally side-effect free: it never reads the filesystem,\n * never shells out to git, and never mutates a worktree. It validates a\n * file-backed {@link RecoveryCheckpoint}, classifies a restore preflight against\n * an externally-observed worktree snapshot, decides how OMK-created untracked\n * files should be disposed (delete vs quarantine), and produces a\n * conversation/code/both restore plan. The caller is responsible for gathering\n * the observed state (git status, per-file hashes) and for executing the plan.\n *\n * Derived clean-room from the lane C plan\n * (`.omk/runs/omk-package-hardening-plan/recovery-readseek.md`) and the\n * adoption algorithm plan; no legacy package source is imported or copied.\n *\n * Dependency-free apart from `node:path` (pure path math, no I/O).\n */\n\nimport { isAbsolute } from \"node:path\";\n\nexport const RECOVERY_CHECKPOINT_SCHEMA_VERSION = \"omk.recovery.checkpoint.v1\";\n\nexport type RecoveryVcs = \"git\" | \"none\";\nexport type TouchedFileMode = \"tracked\" | \"untracked\" | \"deleted\";\n\nexport interface RecoveryCheckpointSession {\n\treadonly sessionFile?: string;\n\treadonly leafId: string | null;\n\treadonly branchPathIds: readonly string[];\n\treadonly contextHash: string;\n}\n\nexport interface RecoveryTouchedFile {\n\treadonly path: string;\n\treadonly beforeSha256?: string;\n\treadonly afterSha256?: string;\n\treadonly mode: TouchedFileMode;\n}\n\nexport interface RecoveryCheckpointWorkspace {\n\treadonly repoRoot: string;\n\treadonly vcs: RecoveryVcs;\n\treadonly head?: string;\n\treadonly statusPorcelainSha256: string;\n\treadonly touchedFiles: readonly RecoveryTouchedFile[];\n\treadonly reversePatchArtifact?: string;\n}\n\nexport interface RecoveryCheckpointTool {\n\treadonly turnIndex: number;\n\treadonly beforeToolCallId?: string;\n\treadonly afterToolCallId?: string;\n\treadonly mutatingTools: readonly string[];\n}\n\nexport interface RecoveryCheckpointLedger {\n\treadonly eventId: string;\n\treadonly previousEventHash: string;\n\treadonly eventHash: string;\n}\n\nexport interface RecoveryCheckpoint {\n\treadonly schemaVersion: typeof RECOVERY_CHECKPOINT_SCHEMA_VERSION;\n\treadonly checkpointId: string;\n\treadonly createdAt: string;\n\treadonly session: RecoveryCheckpointSession;\n\treadonly workspace: RecoveryCheckpointWorkspace;\n\treadonly tool?: RecoveryCheckpointTool;\n\treadonly ledger: RecoveryCheckpointLedger;\n}\n\nexport interface RecoveryCheckpointValidation {\n\treadonly ok: boolean;\n\treadonly errors: readonly string[];\n\treadonly checkpoint?: RecoveryCheckpoint;\n}\n\nconst HEX64 = /^[0-9a-f]{64}$/i;\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isNonEmptyString(value: unknown): value is string {\n\treturn typeof value === \"string\" && value.length > 0;\n}\n\nfunction isHex64(value: unknown): value is string {\n\treturn typeof value === \"string\" && HEX64.test(value);\n}\n\nfunction isIsoTimestamp(value: unknown): value is string {\n\treturn typeof value === \"string\" && value.length > 0 && !Number.isNaN(Date.parse(value));\n}\n\n/** A touched-file path must be repo-relative and must not escape the repo root. */\nexport function isUnsafeTouchedPath(path: unknown): boolean {\n\tif (typeof path !== \"string\" || path.length === 0) return true;\n\tif (isAbsolute(path)) return true;\n\tconst normalized = path.replace(/\\\\/g, \"/\");\n\treturn normalized.split(\"/\").some((segment) => segment === \"..\");\n}\n\nfunction normalizeRelPath(path: string): string {\n\treturn path.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\");\n}\n\nfunction validateTouchedFile(value: unknown, index: number, errors: string[]): void {\n\tconst label = `workspace.touchedFiles[${index}]`;\n\tif (!isPlainObject(value)) {\n\t\terrors.push(`${label} must be an object`);\n\t\treturn;\n\t}\n\tif (isUnsafeTouchedPath(value.path)) {\n\t\terrors.push(`${label}.path must be a repo-relative path without '..' segments`);\n\t}\n\tconst mode = value.mode;\n\tif (mode !== \"tracked\" && mode !== \"untracked\" && mode !== \"deleted\") {\n\t\terrors.push(`${label}.mode must be one of tracked|untracked|deleted`);\n\t\treturn;\n\t}\n\tif (value.beforeSha256 !== undefined && !isHex64(value.beforeSha256)) {\n\t\terrors.push(`${label}.beforeSha256 must be a 64-char hex digest when present`);\n\t}\n\tif (value.afterSha256 !== undefined && !isHex64(value.afterSha256)) {\n\t\terrors.push(`${label}.afterSha256 must be a 64-char hex digest when present`);\n\t}\n\tif (mode === \"untracked\") {\n\t\tif (!isHex64(value.afterSha256)) errors.push(`${label}.afterSha256 is required for untracked files`);\n\t\tif (value.beforeSha256 !== undefined) errors.push(`${label}.beforeSha256 must be absent for untracked files`);\n\t}\n\tif (mode === \"deleted\") {\n\t\tif (!isHex64(value.beforeSha256)) errors.push(`${label}.beforeSha256 is required for deleted files`);\n\t\tif (value.afterSha256 !== undefined) errors.push(`${label}.afterSha256 must be absent for deleted files`);\n\t}\n\tif (mode === \"tracked\" && !isHex64(value.afterSha256)) {\n\t\terrors.push(`${label}.afterSha256 is required for tracked files`);\n\t}\n}\n\nfunction validateSession(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"session must be an object\");\n\t\treturn;\n\t}\n\tif (value.leafId !== null && typeof value.leafId !== \"string\") {\n\t\terrors.push(\"session.leafId must be a string or null\");\n\t}\n\tif (!Array.isArray(value.branchPathIds) || value.branchPathIds.some((id) => typeof id !== \"string\")) {\n\t\terrors.push(\"session.branchPathIds must be an array of strings\");\n\t}\n\tif (!isHex64(value.contextHash)) {\n\t\terrors.push(\"session.contextHash must be a 64-char hex digest\");\n\t}\n\tif (value.sessionFile !== undefined && typeof value.sessionFile !== \"string\") {\n\t\terrors.push(\"session.sessionFile must be a string when present\");\n\t}\n}\n\nfunction validateWorkspace(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"workspace must be an object\");\n\t\treturn;\n\t}\n\tif (!isNonEmptyString(value.repoRoot)) errors.push(\"workspace.repoRoot must be a non-empty string\");\n\tif (value.vcs !== \"git\" && value.vcs !== \"none\") errors.push(\"workspace.vcs must be one of git|none\");\n\tif (value.head !== undefined && typeof value.head !== \"string\") {\n\t\terrors.push(\"workspace.head must be a string when present\");\n\t}\n\tif (!isHex64(value.statusPorcelainSha256)) {\n\t\terrors.push(\"workspace.statusPorcelainSha256 must be a 64-char hex digest\");\n\t}\n\tif (value.reversePatchArtifact !== undefined && typeof value.reversePatchArtifact !== \"string\") {\n\t\terrors.push(\"workspace.reversePatchArtifact must be a string when present\");\n\t}\n\tif (!Array.isArray(value.touchedFiles)) {\n\t\terrors.push(\"workspace.touchedFiles must be an array\");\n\t\treturn;\n\t}\n\tvalue.touchedFiles.forEach((entry, index) => {\n\t\tvalidateTouchedFile(entry, index, errors);\n\t});\n}\n\nfunction validateTool(value: unknown, errors: string[]): void {\n\tif (value === undefined) return;\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"tool must be an object when present\");\n\t\treturn;\n\t}\n\tif (typeof value.turnIndex !== \"number\" || !Number.isInteger(value.turnIndex) || value.turnIndex < 0) {\n\t\terrors.push(\"tool.turnIndex must be a non-negative integer\");\n\t}\n\tif (!Array.isArray(value.mutatingTools) || value.mutatingTools.some((t) => typeof t !== \"string\")) {\n\t\terrors.push(\"tool.mutatingTools must be an array of strings\");\n\t}\n\tif (value.beforeToolCallId !== undefined && typeof value.beforeToolCallId !== \"string\") {\n\t\terrors.push(\"tool.beforeToolCallId must be a string when present\");\n\t}\n\tif (value.afterToolCallId !== undefined && typeof value.afterToolCallId !== \"string\") {\n\t\terrors.push(\"tool.afterToolCallId must be a string when present\");\n\t}\n}\n\nfunction validateLedger(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"ledger must be an object\");\n\t\treturn;\n\t}\n\tif (!isNonEmptyString(value.eventId)) errors.push(\"ledger.eventId must be a non-empty string\");\n\tif (!isHex64(value.previousEventHash)) errors.push(\"ledger.previousEventHash must be a 64-char hex digest\");\n\tif (!isHex64(value.eventHash)) errors.push(\"ledger.eventHash must be a 64-char hex digest\");\n}\n\n/**\n * Validate an untrusted value as a {@link RecoveryCheckpoint}. Pure and\n * fail-closed: any structural problem yields `ok: false` with explicit errors\n * and no `checkpoint` payload.\n */\nexport function validateRecoveryCheckpoint(value: unknown): RecoveryCheckpointValidation {\n\tconst errors: string[] = [];\n\tif (!isPlainObject(value)) {\n\t\treturn { ok: false, errors: [\"checkpoint must be an object\"] };\n\t}\n\tif (value.schemaVersion !== RECOVERY_CHECKPOINT_SCHEMA_VERSION) {\n\t\terrors.push(`schemaVersion must be ${RECOVERY_CHECKPOINT_SCHEMA_VERSION}`);\n\t}\n\tif (!isNonEmptyString(value.checkpointId)) errors.push(\"checkpointId must be a non-empty string\");\n\tif (!isIsoTimestamp(value.createdAt)) errors.push(\"createdAt must be an ISO-8601 timestamp\");\n\tvalidateSession(value.session, errors);\n\tvalidateWorkspace(value.workspace, errors);\n\tvalidateTool(value.tool, errors);\n\tvalidateLedger(value.ledger, errors);\n\n\tif (errors.length > 0) return { ok: false, errors };\n\treturn { ok: true, errors: [], checkpoint: value as unknown as RecoveryCheckpoint };\n}\n\n/**\n * The ledger anchor as independently re-read from the hash-chained ledger.\n * Compared against the checkpoint's embedded anchor before any mutation.\n */\nexport interface ObservedLedgerAnchor {\n\treadonly eventId: string;\n\treadonly previousEventHash: string;\n\treadonly eventHash: string;\n}\n\nexport interface LedgerAnchorVerification {\n\treadonly ok: boolean;\n\treadonly mismatches: readonly string[];\n}\n\n/**\n * Compare a checkpoint's embedded ledger anchor with the anchor observed in the\n * live ledger. A mismatch means the checkpoint references an event that no\n * longer matches the durable audit trail (tamper or divergence) and the restore\n * must fail closed.\n */\nexport function verifyCheckpointLedgerAnchor(\n\tcheckpoint: RecoveryCheckpoint,\n\tobserved: ObservedLedgerAnchor,\n): LedgerAnchorVerification {\n\tconst mismatches: string[] = [];\n\tif (checkpoint.ledger.eventId !== observed.eventId) {\n\t\tmismatches.push(`eventId mismatch: checkpoint=${checkpoint.ledger.eventId} ledger=${observed.eventId}`);\n\t}\n\tif (checkpoint.ledger.previousEventHash !== observed.previousEventHash) {\n\t\tmismatches.push(\"previousEventHash mismatch between checkpoint and ledger\");\n\t}\n\tif (checkpoint.ledger.eventHash !== observed.eventHash) {\n\t\tmismatches.push(\"eventHash mismatch between checkpoint and ledger\");\n\t}\n\treturn { ok: mismatches.length === 0, mismatches };\n}\n\nexport interface ObservedTouchedFile {\n\treadonly path: string;\n\treadonly exists: boolean;\n\treadonly sha256?: string;\n\treadonly isSymlink?: boolean;\n\t/** True when the path (or its symlink target) resolves outside the repo root. */\n\treadonly escapesRepo?: boolean;\n}\n\nexport interface ObservedWorktree {\n\treadonly head?: string;\n\treadonly statusPorcelainSha256?: string;\n\t/** Current dirty paths (repo-relative) from `git status --porcelain`. */\n\treadonly dirtyPaths: readonly string[];\n\treadonly touchedFiles: readonly ObservedTouchedFile[];\n}\n\nexport interface RestorePreflightOptions {\n\t/** Allow restoring even though HEAD moved since the checkpoint. */\n\treadonly allowNonHeadRestore?: boolean;\n}\n\nexport type RestorePreflightVerdict = \"clean\" | \"blocked\";\n\nexport type RestorePreflightIssueCode =\n\t| \"unrelated-dirty-path\"\n\t| \"touched-hash-mismatch\"\n\t| \"missing-touched-file\"\n\t| \"symlink-escape\"\n\t| \"head-mismatch\";\n\nexport interface RestorePreflightIssue {\n\treadonly code: RestorePreflightIssueCode;\n\treadonly path?: string;\n\treadonly detail: string;\n}\n\nexport interface RestorePreflightResult {\n\treadonly verdict: RestorePreflightVerdict;\n\treadonly issues: readonly RestorePreflightIssue[];\n\treadonly unrelatedDirtyPaths: readonly string[];\n\treadonly hashMismatches: readonly string[];\n\treadonly symlinkEscapes: readonly string[];\n\treadonly headChanged: boolean;\n}\n\n/**\n * Classify whether a code restore can proceed against the live worktree.\n *\n * Fail-closed rules (from the lane C restore algorithm):\n *  - any dirty path outside the recorded touched set blocks the restore;\n *  - any touched file whose current hash differs from the recorded `afterSha256`\n *    blocks the restore;\n *  - any symlink escaping the repo root blocks the restore;\n *  - a moved HEAD blocks the restore unless `allowNonHeadRestore` is set.\n */\nexport function classifyRestorePreflight(\n\tcheckpoint: RecoveryCheckpoint,\n\tobserved: ObservedWorktree,\n\toptions: RestorePreflightOptions = {},\n): RestorePreflightResult {\n\tconst issues: RestorePreflightIssue[] = [];\n\tconst touchedByPath = new Map<string, RecoveryTouchedFile>();\n\tfor (const file of checkpoint.workspace.touchedFiles) {\n\t\ttouchedByPath.set(normalizeRelPath(file.path), file);\n\t}\n\n\tconst unrelatedDirtyPaths: string[] = [];\n\tfor (const dirty of observed.dirtyPaths) {\n\t\tif (!touchedByPath.has(normalizeRelPath(dirty))) {\n\t\t\tunrelatedDirtyPaths.push(dirty);\n\t\t\tissues.push({\n\t\t\t\tcode: \"unrelated-dirty-path\",\n\t\t\t\tpath: dirty,\n\t\t\t\tdetail: \"dirty path is outside the checkpoint's recorded touched files\",\n\t\t\t});\n\t\t}\n\t}\n\n\tconst observedByPath = new Map<string, ObservedTouchedFile>();\n\tfor (const file of observed.touchedFiles) {\n\t\tobservedByPath.set(normalizeRelPath(file.path), file);\n\t}\n\n\tconst hashMismatches: string[] = [];\n\tconst symlinkEscapes: string[] = [];\n\tfor (const expected of checkpoint.workspace.touchedFiles) {\n\t\tconst key = normalizeRelPath(expected.path);\n\t\tconst current = observedByPath.get(key);\n\t\tif (!current) {\n\t\t\tissues.push({\n\t\t\t\tcode: \"missing-touched-file\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"no observed state was provided for a recorded touched file\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (current.escapesRepo === true || (current.isSymlink === true && current.escapesRepo !== false)) {\n\t\t\tsymlinkEscapes.push(expected.path);\n\t\t\tissues.push({\n\t\t\t\tcode: \"symlink-escape\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"touched path is a symlink resolving outside the repo root\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (expected.mode === \"deleted\") {\n\t\t\tif (current.exists) {\n\t\t\t\thashMismatches.push(expected.path);\n\t\t\t\tissues.push({\n\t\t\t\t\tcode: \"touched-hash-mismatch\",\n\t\t\t\t\tpath: expected.path,\n\t\t\t\t\tdetail: \"expected a deleted file to be absent but it is present\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (!current.exists) {\n\t\t\tissues.push({\n\t\t\t\tcode: \"missing-touched-file\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"recorded touched file is missing from the worktree\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (current.sha256 !== expected.afterSha256) {\n\t\t\thashMismatches.push(expected.path);\n\t\t\tissues.push({\n\t\t\t\tcode: \"touched-hash-mismatch\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"current file hash differs from the recorded post-edit hash\",\n\t\t\t});\n\t\t}\n\t}\n\n\tconst headChanged =\n\t\tcheckpoint.workspace.vcs === \"git\" &&\n\t\tcheckpoint.workspace.head !== undefined &&\n\t\tobserved.head !== undefined &&\n\t\tcheckpoint.workspace.head !== observed.head;\n\tif (headChanged && options.allowNonHeadRestore !== true) {\n\t\tissues.push({\n\t\t\tcode: \"head-mismatch\",\n\t\t\tdetail: \"HEAD moved since the checkpoint; pass allowNonHeadRestore to override\",\n\t\t});\n\t}\n\n\treturn {\n\t\tverdict: issues.length === 0 ? \"clean\" : \"blocked\",\n\t\tissues,\n\t\tunrelatedDirtyPaths,\n\t\thashMismatches,\n\t\tsymlinkEscapes,\n\t\theadChanged,\n\t};\n}\n\nexport type UntrackedDisposition = \"delete\" | \"quarantine\" | \"skip\";\n\nexport interface UntrackedDispositionDecision {\n\treadonly disposition: UntrackedDisposition;\n\treadonly reason: string;\n}\n\nexport interface ObservedUntrackedFile {\n\treadonly exists: boolean;\n\treadonly sha256?: string;\n}\n\n/**\n * Decide how an OMK-created untracked file should be handled on restore.\n *\n *  - `skip`: the file is already gone, nothing to undo.\n *  - `delete`: the file still exactly matches what OMK created, safe to remove.\n *  - `quarantine`: the file changed since OMK created it; move it under the\n *    recovery quarantine directory rather than destroying user edits.\n */\nexport function decideUntrackedDisposition(\n\ttouched: RecoveryTouchedFile,\n\tobserved: ObservedUntrackedFile,\n): UntrackedDispositionDecision {\n\tif (touched.mode !== \"untracked\") {\n\t\treturn { disposition: \"skip\", reason: \"disposition only applies to untracked files\" };\n\t}\n\tif (!observed.exists) {\n\t\treturn { disposition: \"skip\", reason: \"untracked file is already absent\" };\n\t}\n\tif (isHex64(touched.afterSha256) && observed.sha256 === touched.afterSha256) {\n\t\treturn { disposition: \"delete\", reason: \"current hash matches the OMK-created hash\" };\n\t}\n\treturn { disposition: \"quarantine\", reason: \"current hash differs from the OMK-created hash\" };\n}\n\nexport type RestoreMode = \"conversation\" | \"code\" | \"both\";\n\nexport type RestorePhaseKind = \"conversation\" | \"code\";\nexport type RestorePhaseAction = \"navigate-tree\" | \"apply-reverse-patch\";\n\nexport interface RestorePlanPhase {\n\treadonly phase: RestorePhaseKind;\n\treadonly action: RestorePhaseAction;\n\treadonly targetLeafId?: string | null;\n\treadonly recordedPaths?: readonly string[];\n}\n\nexport interface RestorePlan {\n\treadonly mode: RestoreMode;\n\treadonly status: \"ready\" | \"blocked\";\n\treadonly phases: readonly RestorePlanPhase[];\n\treadonly blockers: readonly string[];\n\t/** For `both`: the leaf to keep if the conversation phase fails after code restore. */\n\treadonly preservePreviousLeafId?: string | null;\n\treadonly inDoubtPolicy?: \"preserve-previous-leaf\";\n}\n\nexport interface PlanRestoreInput {\n\treadonly mode: RestoreMode;\n\treadonly checkpoint: RecoveryCheckpoint;\n\t/** Required for `code` and `both` modes. */\n\treadonly preflight?: RestorePreflightResult;\n\t/** The current session leaf, preserved for manual recovery in `both` mode. */\n\treadonly currentLeafId?: string | null;\n}\n\nfunction codePhase(checkpoint: RecoveryCheckpoint): RestorePlanPhase {\n\treturn {\n\t\tphase: \"code\",\n\t\taction: \"apply-reverse-patch\",\n\t\trecordedPaths: checkpoint.workspace.touchedFiles.map((file) => file.path),\n\t};\n}\n\nfunction conversationPhase(checkpoint: RecoveryCheckpoint): RestorePlanPhase {\n\treturn { phase: \"conversation\", action: \"navigate-tree\", targetLeafId: checkpoint.session.leafId };\n}\n\nfunction collectPreflightBlockers(preflight: RestorePreflightResult | undefined): string[] {\n\tif (!preflight) return [\"code restore requires a preflight classification\"];\n\tif (preflight.verdict === \"clean\") return [];\n\treturn preflight.issues.map((issue) => (issue.path ? `${issue.code}: ${issue.path}` : issue.code));\n}\n\n/**\n * Build a restore plan for the requested mode.\n *\n *  - `conversation`: navigate the session tree to the checkpoint leaf; no file\n *    writes, so no worktree preflight is required.\n *  - `code`: apply the recorded reverse patch path-by-path; requires a clean\n *    preflight.\n *  - `both`: restore code first, then navigate the tree; requires a clean\n *    preflight. If the second (conversation) phase fails at execution time the\n *    caller marks the operation `in_doubt` and keeps `preservePreviousLeafId`.\n */\nexport function planRestore(input: PlanRestoreInput): RestorePlan {\n\tconst { mode, checkpoint, preflight } = input;\n\tif (mode === \"conversation\") {\n\t\treturn { mode, status: \"ready\", phases: [conversationPhase(checkpoint)], blockers: [] };\n\t}\n\n\tconst blockers = collectPreflightBlockers(preflight);\n\tif (mode === \"code\") {\n\t\tif (blockers.length > 0) return { mode, status: \"blocked\", phases: [], blockers };\n\t\treturn { mode, status: \"ready\", phases: [codePhase(checkpoint)], blockers: [] };\n\t}\n\n\t// mode === \"both\"\n\tconst preservePreviousLeafId = input.currentLeafId ?? null;\n\tif (blockers.length > 0) {\n\t\treturn {\n\t\t\tmode,\n\t\t\tstatus: \"blocked\",\n\t\t\tphases: [],\n\t\t\tblockers,\n\t\t\tpreservePreviousLeafId,\n\t\t\tinDoubtPolicy: \"preserve-previous-leaf\",\n\t\t};\n\t}\n\treturn {\n\t\tmode,\n\t\tstatus: \"ready\",\n\t\tphases: [codePhase(checkpoint), conversationPhase(checkpoint)],\n\t\tblockers: [],\n\t\tpreservePreviousLeafId,\n\t\tinDoubtPolicy: \"preserve-previous-leaf\",\n\t};\n}\n"]}

package/dist/core/recovery-checkpoint.js

@@ -1,382 +0,0 @@
-/**
- * `omk.recovery.checkpoint` — pure decision algorithms for native worktree/
- * conversation recovery checkpoints.
- *
- * This module is intentionally side-effect free: it never reads the filesystem,
- * never shells out to git, and never mutates a worktree. It validates a
- * file-backed {@link RecoveryCheckpoint}, classifies a restore preflight against
- * an externally-observed worktree snapshot, decides how OMK-created untracked
- * files should be disposed (delete vs quarantine), and produces a
- * conversation/code/both restore plan. The caller is responsible for gathering
- * the observed state (git status, per-file hashes) and for executing the plan.
- *
- * Derived clean-room from the lane C plan
- * (`.omk/runs/omk-package-hardening-plan/recovery-readseek.md`) and the
- * adoption algorithm plan; no legacy package source is imported or copied.
- *
- * Dependency-free apart from `node:path` (pure path math, no I/O).
- */
-import { isAbsolute } from "node:path";
-export const RECOVERY_CHECKPOINT_SCHEMA_VERSION = "omk.recovery.checkpoint.v1";
-const HEX64 = /^[0-9a-f]{64}$/i;
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isNonEmptyString(value) {
-    return typeof value === "string" && value.length > 0;
-}
-function isHex64(value) {
-    return typeof value === "string" && HEX64.test(value);
-}
-function isIsoTimestamp(value) {
-    return typeof value === "string" && value.length > 0 && !Number.isNaN(Date.parse(value));
-}
-/** A touched-file path must be repo-relative and must not escape the repo root. */
-export function isUnsafeTouchedPath(path) {
-    if (typeof path !== "string" || path.length === 0)
-        return true;
-    if (isAbsolute(path))
-        return true;
-    const normalized = path.replace(/\\/g, "/");
-    return normalized.split("/").some((segment) => segment === "..");
-}
-function normalizeRelPath(path) {
-    return path.replace(/\\/g, "/").replace(/^\.\//, "");
-}
-function validateTouchedFile(value, index, errors) {
-    const label = `workspace.touchedFiles[${index}]`;
-    if (!isPlainObject(value)) {
-        errors.push(`${label} must be an object`);
-        return;
-    }
-    if (isUnsafeTouchedPath(value.path)) {
-        errors.push(`${label}.path must be a repo-relative path without '..' segments`);
-    }
-    const mode = value.mode;
-    if (mode !== "tracked" && mode !== "untracked" && mode !== "deleted") {
-        errors.push(`${label}.mode must be one of tracked|untracked|deleted`);
-        return;
-    }
-    if (value.beforeSha256 !== undefined && !isHex64(value.beforeSha256)) {
-        errors.push(`${label}.beforeSha256 must be a 64-char hex digest when present`);
-    }
-    if (value.afterSha256 !== undefined && !isHex64(value.afterSha256)) {
-        errors.push(`${label}.afterSha256 must be a 64-char hex digest when present`);
-    }
-    if (mode === "untracked") {
-        if (!isHex64(value.afterSha256))
-            errors.push(`${label}.afterSha256 is required for untracked files`);
-        if (value.beforeSha256 !== undefined)
-            errors.push(`${label}.beforeSha256 must be absent for untracked files`);
-    }
-    if (mode === "deleted") {
-        if (!isHex64(value.beforeSha256))
-            errors.push(`${label}.beforeSha256 is required for deleted files`);
-        if (value.afterSha256 !== undefined)
-            errors.push(`${label}.afterSha256 must be absent for deleted files`);
-    }
-    if (mode === "tracked" && !isHex64(value.afterSha256)) {
-        errors.push(`${label}.afterSha256 is required for tracked files`);
-    }
-}
-function validateSession(value, errors) {
-    if (!isPlainObject(value)) {
-        errors.push("session must be an object");
-        return;
-    }
-    if (value.leafId !== null && typeof value.leafId !== "string") {
-        errors.push("session.leafId must be a string or null");
-    }
-    if (!Array.isArray(value.branchPathIds) || value.branchPathIds.some((id) => typeof id !== "string")) {
-        errors.push("session.branchPathIds must be an array of strings");
-    }
-    if (!isHex64(value.contextHash)) {
-        errors.push("session.contextHash must be a 64-char hex digest");
-    }
-    if (value.sessionFile !== undefined && typeof value.sessionFile !== "string") {
-        errors.push("session.sessionFile must be a string when present");
-    }
-}
-function validateWorkspace(value, errors) {
-    if (!isPlainObject(value)) {
-        errors.push("workspace must be an object");
-        return;
-    }
-    if (!isNonEmptyString(value.repoRoot))
-        errors.push("workspace.repoRoot must be a non-empty string");
-    if (value.vcs !== "git" && value.vcs !== "none")
-        errors.push("workspace.vcs must be one of git|none");
-    if (value.head !== undefined && typeof value.head !== "string") {
-        errors.push("workspace.head must be a string when present");
-    }
-    if (!isHex64(value.statusPorcelainSha256)) {
-        errors.push("workspace.statusPorcelainSha256 must be a 64-char hex digest");
-    }
-    if (value.reversePatchArtifact !== undefined && typeof value.reversePatchArtifact !== "string") {
-        errors.push("workspace.reversePatchArtifact must be a string when present");
-    }
-    if (!Array.isArray(value.touchedFiles)) {
-        errors.push("workspace.touchedFiles must be an array");
-        return;
-    }
-    value.touchedFiles.forEach((entry, index) => {
-        validateTouchedFile(entry, index, errors);
-    });
-}
-function validateTool(value, errors) {
-    if (value === undefined)
-        return;
-    if (!isPlainObject(value)) {
-        errors.push("tool must be an object when present");
-        return;
-    }
-    if (typeof value.turnIndex !== "number" || !Number.isInteger(value.turnIndex) || value.turnIndex < 0) {
-        errors.push("tool.turnIndex must be a non-negative integer");
-    }
-    if (!Array.isArray(value.mutatingTools) || value.mutatingTools.some((t) => typeof t !== "string")) {
-        errors.push("tool.mutatingTools must be an array of strings");
-    }
-    if (value.beforeToolCallId !== undefined && typeof value.beforeToolCallId !== "string") {
-        errors.push("tool.beforeToolCallId must be a string when present");
-    }
-    if (value.afterToolCallId !== undefined && typeof value.afterToolCallId !== "string") {
-        errors.push("tool.afterToolCallId must be a string when present");
-    }
-}
-function validateLedger(value, errors) {
-    if (!isPlainObject(value)) {
-        errors.push("ledger must be an object");
-        return;
-    }
-    if (!isNonEmptyString(value.eventId))
-        errors.push("ledger.eventId must be a non-empty string");
-    if (!isHex64(value.previousEventHash))
-        errors.push("ledger.previousEventHash must be a 64-char hex digest");
-    if (!isHex64(value.eventHash))
-        errors.push("ledger.eventHash must be a 64-char hex digest");
-}
-/**
- * Validate an untrusted value as a {@link RecoveryCheckpoint}. Pure and
- * fail-closed: any structural problem yields `ok: false` with explicit errors
- * and no `checkpoint` payload.
- */
-export function validateRecoveryCheckpoint(value) {
-    const errors = [];
-    if (!isPlainObject(value)) {
-        return { ok: false, errors: ["checkpoint must be an object"] };
-    }
-    if (value.schemaVersion !== RECOVERY_CHECKPOINT_SCHEMA_VERSION) {
-        errors.push(`schemaVersion must be ${RECOVERY_CHECKPOINT_SCHEMA_VERSION}`);
-    }
-    if (!isNonEmptyString(value.checkpointId))
-        errors.push("checkpointId must be a non-empty string");
-    if (!isIsoTimestamp(value.createdAt))
-        errors.push("createdAt must be an ISO-8601 timestamp");
-    validateSession(value.session, errors);
-    validateWorkspace(value.workspace, errors);
-    validateTool(value.tool, errors);
-    validateLedger(value.ledger, errors);
-    if (errors.length > 0)
-        return { ok: false, errors };
-    return { ok: true, errors: [], checkpoint: value };
-}
-/**
- * Compare a checkpoint's embedded ledger anchor with the anchor observed in the
- * live ledger. A mismatch means the checkpoint references an event that no
- * longer matches the durable audit trail (tamper or divergence) and the restore
- * must fail closed.
- */
-export function verifyCheckpointLedgerAnchor(checkpoint, observed) {
-    const mismatches = [];
-    if (checkpoint.ledger.eventId !== observed.eventId) {
-        mismatches.push(`eventId mismatch: checkpoint=${checkpoint.ledger.eventId} ledger=${observed.eventId}`);
-    }
-    if (checkpoint.ledger.previousEventHash !== observed.previousEventHash) {
-        mismatches.push("previousEventHash mismatch between checkpoint and ledger");
-    }
-    if (checkpoint.ledger.eventHash !== observed.eventHash) {
-        mismatches.push("eventHash mismatch between checkpoint and ledger");
-    }
-    return { ok: mismatches.length === 0, mismatches };
-}
-/**
- * Classify whether a code restore can proceed against the live worktree.
- *
- * Fail-closed rules (from the lane C restore algorithm):
- *  - any dirty path outside the recorded touched set blocks the restore;
- *  - any touched file whose current hash differs from the recorded `afterSha256`
- *    blocks the restore;
- *  - any symlink escaping the repo root blocks the restore;
- *  - a moved HEAD blocks the restore unless `allowNonHeadRestore` is set.
- */
-export function classifyRestorePreflight(checkpoint, observed, options = {}) {
-    const issues = [];
-    const touchedByPath = new Map();
-    for (const file of checkpoint.workspace.touchedFiles) {
-        touchedByPath.set(normalizeRelPath(file.path), file);
-    }
-    const unrelatedDirtyPaths = [];
-    for (const dirty of observed.dirtyPaths) {
-        if (!touchedByPath.has(normalizeRelPath(dirty))) {
-            unrelatedDirtyPaths.push(dirty);
-            issues.push({
-                code: "unrelated-dirty-path",
-                path: dirty,
-                detail: "dirty path is outside the checkpoint's recorded touched files",
-            });
-        }
-    }
-    const observedByPath = new Map();
-    for (const file of observed.touchedFiles) {
-        observedByPath.set(normalizeRelPath(file.path), file);
-    }
-    const hashMismatches = [];
-    const symlinkEscapes = [];
-    for (const expected of checkpoint.workspace.touchedFiles) {
-        const key = normalizeRelPath(expected.path);
-        const current = observedByPath.get(key);
-        if (!current) {
-            issues.push({
-                code: "missing-touched-file",
-                path: expected.path,
-                detail: "no observed state was provided for a recorded touched file",
-            });
-            continue;
-        }
-        if (current.escapesRepo === true || (current.isSymlink === true && current.escapesRepo !== false)) {
-            symlinkEscapes.push(expected.path);
-            issues.push({
-                code: "symlink-escape",
-                path: expected.path,
-                detail: "touched path is a symlink resolving outside the repo root",
-            });
-            continue;
-        }
-        if (expected.mode === "deleted") {
-            if (current.exists) {
-                hashMismatches.push(expected.path);
-                issues.push({
-                    code: "touched-hash-mismatch",
-                    path: expected.path,
-                    detail: "expected a deleted file to be absent but it is present",
-                });
-            }
-            continue;
-        }
-        if (!current.exists) {
-            issues.push({
-                code: "missing-touched-file",
-                path: expected.path,
-                detail: "recorded touched file is missing from the worktree",
-            });
-            continue;
-        }
-        if (current.sha256 !== expected.afterSha256) {
-            hashMismatches.push(expected.path);
-            issues.push({
-                code: "touched-hash-mismatch",
-                path: expected.path,
-                detail: "current file hash differs from the recorded post-edit hash",
-            });
-        }
-    }
-    const headChanged = checkpoint.workspace.vcs === "git" &&
-        checkpoint.workspace.head !== undefined &&
-        observed.head !== undefined &&
-        checkpoint.workspace.head !== observed.head;
-    if (headChanged && options.allowNonHeadRestore !== true) {
-        issues.push({
-            code: "head-mismatch",
-            detail: "HEAD moved since the checkpoint; pass allowNonHeadRestore to override",
-        });
-    }
-    return {
-        verdict: issues.length === 0 ? "clean" : "blocked",
-        issues,
-        unrelatedDirtyPaths,
-        hashMismatches,
-        symlinkEscapes,
-        headChanged,
-    };
-}
-/**
- * Decide how an OMK-created untracked file should be handled on restore.
- *
- *  - `skip`: the file is already gone, nothing to undo.
- *  - `delete`: the file still exactly matches what OMK created, safe to remove.
- *  - `quarantine`: the file changed since OMK created it; move it under the
- *    recovery quarantine directory rather than destroying user edits.
- */
-export function decideUntrackedDisposition(touched, observed) {
-    if (touched.mode !== "untracked") {
-        return { disposition: "skip", reason: "disposition only applies to untracked files" };
-    }
-    if (!observed.exists) {
-        return { disposition: "skip", reason: "untracked file is already absent" };
-    }
-    if (isHex64(touched.afterSha256) && observed.sha256 === touched.afterSha256) {
-        return { disposition: "delete", reason: "current hash matches the OMK-created hash" };
-    }
-    return { disposition: "quarantine", reason: "current hash differs from the OMK-created hash" };
-}
-function codePhase(checkpoint) {
-    return {
-        phase: "code",
-        action: "apply-reverse-patch",
-        recordedPaths: checkpoint.workspace.touchedFiles.map((file) => file.path),
-    };
-}
-function conversationPhase(checkpoint) {
-    return { phase: "conversation", action: "navigate-tree", targetLeafId: checkpoint.session.leafId };
-}
-function collectPreflightBlockers(preflight) {
-    if (!preflight)
-        return ["code restore requires a preflight classification"];
-    if (preflight.verdict === "clean")
-        return [];
-    return preflight.issues.map((issue) => (issue.path ? `${issue.code}: ${issue.path}` : issue.code));
-}
-/**
- * Build a restore plan for the requested mode.
- *
- *  - `conversation`: navigate the session tree to the checkpoint leaf; no file
- *    writes, so no worktree preflight is required.
- *  - `code`: apply the recorded reverse patch path-by-path; requires a clean
- *    preflight.
- *  - `both`: restore code first, then navigate the tree; requires a clean
- *    preflight. If the second (conversation) phase fails at execution time the
- *    caller marks the operation `in_doubt` and keeps `preservePreviousLeafId`.
- */
-export function planRestore(input) {
-    const { mode, checkpoint, preflight } = input;
-    if (mode === "conversation") {
-        return { mode, status: "ready", phases: [conversationPhase(checkpoint)], blockers: [] };
-    }
-    const blockers = collectPreflightBlockers(preflight);
-    if (mode === "code") {
-        if (blockers.length > 0)
-            return { mode, status: "blocked", phases: [], blockers };
-        return { mode, status: "ready", phases: [codePhase(checkpoint)], blockers: [] };
-    }
-    // mode === "both"
-    const preservePreviousLeafId = input.currentLeafId ?? null;
-    if (blockers.length > 0) {
-        return {
-            mode,
-            status: "blocked",
-            phases: [],
-            blockers,
-            preservePreviousLeafId,
-            inDoubtPolicy: "preserve-previous-leaf",
-        };
-    }
-    return {
-        mode,
-        status: "ready",
-        phases: [codePhase(checkpoint), conversationPhase(checkpoint)],
-        blockers: [],
-        preservePreviousLeafId,
-        inDoubtPolicy: "preserve-previous-leaf",
-    };
-}
-//# sourceMappingURL=recovery-checkpoint.js.map

package/dist/core/recovery-checkpoint.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recovery-checkpoint.js","sourceRoot":"","sources":["../../src/core/recovery-checkpoint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `omk.recovery.checkpoint` — pure decision algorithms for native worktree/\n * conversation recovery checkpoints.\n *\n * This module is intentionally side-effect free: it never reads the filesystem,\n * never shells out to git, and never mutates a worktree. It validates a\n * file-backed {@link RecoveryCheckpoint}, classifies a restore preflight against\n * an externally-observed worktree snapshot, decides how OMK-created untracked\n * files should be disposed (delete vs quarantine), and produces a\n * conversation/code/both restore plan. The caller is responsible for gathering\n * the observed state (git status, per-file hashes) and for executing the plan.\n *\n * Derived clean-room from the lane C plan\n * (`.omk/runs/omk-package-hardening-plan/recovery-readseek.md`) and the\n * adoption algorithm plan; no legacy package source is imported or copied.\n *\n * Dependency-free apart from `node:path` (pure path math, no I/O).\n */\n\nimport { isAbsolute } from \"node:path\";\n\nexport const RECOVERY_CHECKPOINT_SCHEMA_VERSION = \"omk.recovery.checkpoint.v1\";\n\nexport type RecoveryVcs = \"git\" | \"none\";\nexport type TouchedFileMode = \"tracked\" | \"untracked\" | \"deleted\";\n\nexport interface RecoveryCheckpointSession {\n\treadonly sessionFile?: string;\n\treadonly leafId: string | null;\n\treadonly branchPathIds: readonly string[];\n\treadonly contextHash: string;\n}\n\nexport interface RecoveryTouchedFile {\n\treadonly path: string;\n\treadonly beforeSha256?: string;\n\treadonly afterSha256?: string;\n\treadonly mode: TouchedFileMode;\n}\n\nexport interface RecoveryCheckpointWorkspace {\n\treadonly repoRoot: string;\n\treadonly vcs: RecoveryVcs;\n\treadonly head?: string;\n\treadonly statusPorcelainSha256: string;\n\treadonly touchedFiles: readonly RecoveryTouchedFile[];\n\treadonly reversePatchArtifact?: string;\n}\n\nexport interface RecoveryCheckpointTool {\n\treadonly turnIndex: number;\n\treadonly beforeToolCallId?: string;\n\treadonly afterToolCallId?: string;\n\treadonly mutatingTools: readonly string[];\n}\n\nexport interface RecoveryCheckpointLedger {\n\treadonly eventId: string;\n\treadonly previousEventHash: string;\n\treadonly eventHash: string;\n}\n\nexport interface RecoveryCheckpoint {\n\treadonly schemaVersion: typeof RECOVERY_CHECKPOINT_SCHEMA_VERSION;\n\treadonly checkpointId: string;\n\treadonly createdAt: string;\n\treadonly session: RecoveryCheckpointSession;\n\treadonly workspace: RecoveryCheckpointWorkspace;\n\treadonly tool?: RecoveryCheckpointTool;\n\treadonly ledger: RecoveryCheckpointLedger;\n}\n\nexport interface RecoveryCheckpointValidation {\n\treadonly ok: boolean;\n\treadonly errors: readonly string[];\n\treadonly checkpoint?: RecoveryCheckpoint;\n}\n\nconst HEX64 = /^[0-9a-f]{64}$/i;\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isNonEmptyString(value: unknown): value is string {\n\treturn typeof value === \"string\" && value.length > 0;\n}\n\nfunction isHex64(value: unknown): value is string {\n\treturn typeof value === \"string\" && HEX64.test(value);\n}\n\nfunction isIsoTimestamp(value: unknown): value is string {\n\treturn typeof value === \"string\" && value.length > 0 && !Number.isNaN(Date.parse(value));\n}\n\n/** A touched-file path must be repo-relative and must not escape the repo root. */\nexport function isUnsafeTouchedPath(path: unknown): boolean {\n\tif (typeof path !== \"string\" || path.length === 0) return true;\n\tif (isAbsolute(path)) return true;\n\tconst normalized = path.replace(/\\\\/g, \"/\");\n\treturn normalized.split(\"/\").some((segment) => segment === \"..\");\n}\n\nfunction normalizeRelPath(path: string): string {\n\treturn path.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\");\n}\n\nfunction validateTouchedFile(value: unknown, index: number, errors: string[]): void {\n\tconst label = `workspace.touchedFiles[${index}]`;\n\tif (!isPlainObject(value)) {\n\t\terrors.push(`${label} must be an object`);\n\t\treturn;\n\t}\n\tif (isUnsafeTouchedPath(value.path)) {\n\t\terrors.push(`${label}.path must be a repo-relative path without '..' segments`);\n\t}\n\tconst mode = value.mode;\n\tif (mode !== \"tracked\" && mode !== \"untracked\" && mode !== \"deleted\") {\n\t\terrors.push(`${label}.mode must be one of tracked|untracked|deleted`);\n\t\treturn;\n\t}\n\tif (value.beforeSha256 !== undefined && !isHex64(value.beforeSha256)) {\n\t\terrors.push(`${label}.beforeSha256 must be a 64-char hex digest when present`);\n\t}\n\tif (value.afterSha256 !== undefined && !isHex64(value.afterSha256)) {\n\t\terrors.push(`${label}.afterSha256 must be a 64-char hex digest when present`);\n\t}\n\tif (mode === \"untracked\") {\n\t\tif (!isHex64(value.afterSha256)) errors.push(`${label}.afterSha256 is required for untracked files`);\n\t\tif (value.beforeSha256 !== undefined) errors.push(`${label}.beforeSha256 must be absent for untracked files`);\n\t}\n\tif (mode === \"deleted\") {\n\t\tif (!isHex64(value.beforeSha256)) errors.push(`${label}.beforeSha256 is required for deleted files`);\n\t\tif (value.afterSha256 !== undefined) errors.push(`${label}.afterSha256 must be absent for deleted files`);\n\t}\n\tif (mode === \"tracked\" && !isHex64(value.afterSha256)) {\n\t\terrors.push(`${label}.afterSha256 is required for tracked files`);\n\t}\n}\n\nfunction validateSession(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"session must be an object\");\n\t\treturn;\n\t}\n\tif (value.leafId !== null && typeof value.leafId !== \"string\") {\n\t\terrors.push(\"session.leafId must be a string or null\");\n\t}\n\tif (!Array.isArray(value.branchPathIds) || value.branchPathIds.some((id) => typeof id !== \"string\")) {\n\t\terrors.push(\"session.branchPathIds must be an array of strings\");\n\t}\n\tif (!isHex64(value.contextHash)) {\n\t\terrors.push(\"session.contextHash must be a 64-char hex digest\");\n\t}\n\tif (value.sessionFile !== undefined && typeof value.sessionFile !== \"string\") {\n\t\terrors.push(\"session.sessionFile must be a string when present\");\n\t}\n}\n\nfunction validateWorkspace(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"workspace must be an object\");\n\t\treturn;\n\t}\n\tif (!isNonEmptyString(value.repoRoot)) errors.push(\"workspace.repoRoot must be a non-empty string\");\n\tif (value.vcs !== \"git\" && value.vcs !== \"none\") errors.push(\"workspace.vcs must be one of git|none\");\n\tif (value.head !== undefined && typeof value.head !== \"string\") {\n\t\terrors.push(\"workspace.head must be a string when present\");\n\t}\n\tif (!isHex64(value.statusPorcelainSha256)) {\n\t\terrors.push(\"workspace.statusPorcelainSha256 must be a 64-char hex digest\");\n\t}\n\tif (value.reversePatchArtifact !== undefined && typeof value.reversePatchArtifact !== \"string\") {\n\t\terrors.push(\"workspace.reversePatchArtifact must be a string when present\");\n\t}\n\tif (!Array.isArray(value.touchedFiles)) {\n\t\terrors.push(\"workspace.touchedFiles must be an array\");\n\t\treturn;\n\t}\n\tvalue.touchedFiles.forEach((entry, index) => {\n\t\tvalidateTouchedFile(entry, index, errors);\n\t});\n}\n\nfunction validateTool(value: unknown, errors: string[]): void {\n\tif (value === undefined) return;\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"tool must be an object when present\");\n\t\treturn;\n\t}\n\tif (typeof value.turnIndex !== \"number\" || !Number.isInteger(value.turnIndex) || value.turnIndex < 0) {\n\t\terrors.push(\"tool.turnIndex must be a non-negative integer\");\n\t}\n\tif (!Array.isArray(value.mutatingTools) || value.mutatingTools.some((t) => typeof t !== \"string\")) {\n\t\terrors.push(\"tool.mutatingTools must be an array of strings\");\n\t}\n\tif (value.beforeToolCallId !== undefined && typeof value.beforeToolCallId !== \"string\") {\n\t\terrors.push(\"tool.beforeToolCallId must be a string when present\");\n\t}\n\tif (value.afterToolCallId !== undefined && typeof value.afterToolCallId !== \"string\") {\n\t\terrors.push(\"tool.afterToolCallId must be a string when present\");\n\t}\n}\n\nfunction validateLedger(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"ledger must be an object\");\n\t\treturn;\n\t}\n\tif (!isNonEmptyString(value.eventId)) errors.push(\"ledger.eventId must be a non-empty string\");\n\tif (!isHex64(value.previousEventHash)) errors.push(\"ledger.previousEventHash must be a 64-char hex digest\");\n\tif (!isHex64(value.eventHash)) errors.push(\"ledger.eventHash must be a 64-char hex digest\");\n}\n\n/**\n * Validate an untrusted value as a {@link RecoveryCheckpoint}. Pure and\n * fail-closed: any structural problem yields `ok: false` with explicit errors\n * and no `checkpoint` payload.\n */\nexport function validateRecoveryCheckpoint(value: unknown): RecoveryCheckpointValidation {\n\tconst errors: string[] = [];\n\tif (!isPlainObject(value)) {\n\t\treturn { ok: false, errors: [\"checkpoint must be an object\"] };\n\t}\n\tif (value.schemaVersion !== RECOVERY_CHECKPOINT_SCHEMA_VERSION) {\n\t\terrors.push(`schemaVersion must be ${RECOVERY_CHECKPOINT_SCHEMA_VERSION}`);\n\t}\n\tif (!isNonEmptyString(value.checkpointId)) errors.push(\"checkpointId must be a non-empty string\");\n\tif (!isIsoTimestamp(value.createdAt)) errors.push(\"createdAt must be an ISO-8601 timestamp\");\n\tvalidateSession(value.session, errors);\n\tvalidateWorkspace(value.workspace, errors);\n\tvalidateTool(value.tool, errors);\n\tvalidateLedger(value.ledger, errors);\n\n\tif (errors.length > 0) return { ok: false, errors };\n\treturn { ok: true, errors: [], checkpoint: value as unknown as RecoveryCheckpoint };\n}\n\n/**\n * The ledger anchor as independently re-read from the hash-chained ledger.\n * Compared against the checkpoint's embedded anchor before any mutation.\n */\nexport interface ObservedLedgerAnchor {\n\treadonly eventId: string;\n\treadonly previousEventHash: string;\n\treadonly eventHash: string;\n}\n\nexport interface LedgerAnchorVerification {\n\treadonly ok: boolean;\n\treadonly mismatches: readonly string[];\n}\n\n/**\n * Compare a checkpoint's embedded ledger anchor with the anchor observed in the\n * live ledger. A mismatch means the checkpoint references an event that no\n * longer matches the durable audit trail (tamper or divergence) and the restore\n * must fail closed.\n */\nexport function verifyCheckpointLedgerAnchor(\n\tcheckpoint: RecoveryCheckpoint,\n\tobserved: ObservedLedgerAnchor,\n): LedgerAnchorVerification {\n\tconst mismatches: string[] = [];\n\tif (checkpoint.ledger.eventId !== observed.eventId) {\n\t\tmismatches.push(`eventId mismatch: checkpoint=${checkpoint.ledger.eventId} ledger=${observed.eventId}`);\n\t}\n\tif (checkpoint.ledger.previousEventHash !== observed.previousEventHash) {\n\t\tmismatches.push(\"previousEventHash mismatch between checkpoint and ledger\");\n\t}\n\tif (checkpoint.ledger.eventHash !== observed.eventHash) {\n\t\tmismatches.push(\"eventHash mismatch between checkpoint and ledger\");\n\t}\n\treturn { ok: mismatches.length === 0, mismatches };\n}\n\nexport interface ObservedTouchedFile {\n\treadonly path: string;\n\treadonly exists: boolean;\n\treadonly sha256?: string;\n\treadonly isSymlink?: boolean;\n\t/** True when the path (or its symlink target) resolves outside the repo root. */\n\treadonly escapesRepo?: boolean;\n}\n\nexport interface ObservedWorktree {\n\treadonly head?: string;\n\treadonly statusPorcelainSha256?: string;\n\t/** Current dirty paths (repo-relative) from `git status --porcelain`. */\n\treadonly dirtyPaths: readonly string[];\n\treadonly touchedFiles: readonly ObservedTouchedFile[];\n}\n\nexport interface RestorePreflightOptions {\n\t/** Allow restoring even though HEAD moved since the checkpoint. */\n\treadonly allowNonHeadRestore?: boolean;\n}\n\nexport type RestorePreflightVerdict = \"clean\" | \"blocked\";\n\nexport type RestorePreflightIssueCode =\n\t| \"unrelated-dirty-path\"\n\t| \"touched-hash-mismatch\"\n\t| \"missing-touched-file\"\n\t| \"symlink-escape\"\n\t| \"head-mismatch\";\n\nexport interface RestorePreflightIssue {\n\treadonly code: RestorePreflightIssueCode;\n\treadonly path?: string;\n\treadonly detail: string;\n}\n\nexport interface RestorePreflightResult {\n\treadonly verdict: RestorePreflightVerdict;\n\treadonly issues: readonly RestorePreflightIssue[];\n\treadonly unrelatedDirtyPaths: readonly string[];\n\treadonly hashMismatches: readonly string[];\n\treadonly symlinkEscapes: readonly string[];\n\treadonly headChanged: boolean;\n}\n\n/**\n * Classify whether a code restore can proceed against the live worktree.\n *\n * Fail-closed rules (from the lane C restore algorithm):\n *  - any dirty path outside the recorded touched set blocks the restore;\n *  - any touched file whose current hash differs from the recorded `afterSha256`\n *    blocks the restore;\n *  - any symlink escaping the repo root blocks the restore;\n *  - a moved HEAD blocks the restore unless `allowNonHeadRestore` is set.\n */\nexport function classifyRestorePreflight(\n\tcheckpoint: RecoveryCheckpoint,\n\tobserved: ObservedWorktree,\n\toptions: RestorePreflightOptions = {},\n): RestorePreflightResult {\n\tconst issues: RestorePreflightIssue[] = [];\n\tconst touchedByPath = new Map<string, RecoveryTouchedFile>();\n\tfor (const file of checkpoint.workspace.touchedFiles) {\n\t\ttouchedByPath.set(normalizeRelPath(file.path), file);\n\t}\n\n\tconst unrelatedDirtyPaths: string[] = [];\n\tfor (const dirty of observed.dirtyPaths) {\n\t\tif (!touchedByPath.has(normalizeRelPath(dirty))) {\n\t\t\tunrelatedDirtyPaths.push(dirty);\n\t\t\tissues.push({\n\t\t\t\tcode: \"unrelated-dirty-path\",\n\t\t\t\tpath: dirty,\n\t\t\t\tdetail: \"dirty path is outside the checkpoint's recorded touched files\",\n\t\t\t});\n\t\t}\n\t}\n\n\tconst observedByPath = new Map<string, ObservedTouchedFile>();\n\tfor (const file of observed.touchedFiles) {\n\t\tobservedByPath.set(normalizeRelPath(file.path), file);\n\t}\n\n\tconst hashMismatches: string[] = [];\n\tconst symlinkEscapes: string[] = [];\n\tfor (const expected of checkpoint.workspace.touchedFiles) {\n\t\tconst key = normalizeRelPath(expected.path);\n\t\tconst current = observedByPath.get(key);\n\t\tif (!current) {\n\t\t\tissues.push({\n\t\t\t\tcode: \"missing-touched-file\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"no observed state was provided for a recorded touched file\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (current.escapesRepo === true || (current.isSymlink === true && current.escapesRepo !== false)) {\n\t\t\tsymlinkEscapes.push(expected.path);\n\t\t\tissues.push({\n\t\t\t\tcode: \"symlink-escape\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"touched path is a symlink resolving outside the repo root\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (expected.mode === \"deleted\") {\n\t\t\tif (current.exists) {\n\t\t\t\thashMismatches.push(expected.path);\n\t\t\t\tissues.push({\n\t\t\t\t\tcode: \"touched-hash-mismatch\",\n\t\t\t\t\tpath: expected.path,\n\t\t\t\t\tdetail: \"expected a deleted file to be absent but it is present\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (!current.exists) {\n\t\t\tissues.push({\n\t\t\t\tcode: \"missing-touched-file\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"recorded touched file is missing from the worktree\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (current.sha256 !== expected.afterSha256) {\n\t\t\thashMismatches.push(expected.path);\n\t\t\tissues.push({\n\t\t\t\tcode: \"touched-hash-mismatch\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"current file hash differs from the recorded post-edit hash\",\n\t\t\t});\n\t\t}\n\t}\n\n\tconst headChanged =\n\t\tcheckpoint.workspace.vcs === \"git\" &&\n\t\tcheckpoint.workspace.head !== undefined &&\n\t\tobserved.head !== undefined &&\n\t\tcheckpoint.workspace.head !== observed.head;\n\tif (headChanged && options.allowNonHeadRestore !== true) {\n\t\tissues.push({\n\t\t\tcode: \"head-mismatch\",\n\t\t\tdetail: \"HEAD moved since the checkpoint; pass allowNonHeadRestore to override\",\n\t\t});\n\t}\n\n\treturn {\n\t\tverdict: issues.length === 0 ? \"clean\" : \"blocked\",\n\t\tissues,\n\t\tunrelatedDirtyPaths,\n\t\thashMismatches,\n\t\tsymlinkEscapes,\n\t\theadChanged,\n\t};\n}\n\nexport type UntrackedDisposition = \"delete\" | \"quarantine\" | \"skip\";\n\nexport interface UntrackedDispositionDecision {\n\treadonly disposition: UntrackedDisposition;\n\treadonly reason: string;\n}\n\nexport interface ObservedUntrackedFile {\n\treadonly exists: boolean;\n\treadonly sha256?: string;\n}\n\n/**\n * Decide how an OMK-created untracked file should be handled on restore.\n *\n *  - `skip`: the file is already gone, nothing to undo.\n *  - `delete`: the file still exactly matches what OMK created, safe to remove.\n *  - `quarantine`: the file changed since OMK created it; move it under the\n *    recovery quarantine directory rather than destroying user edits.\n */\nexport function decideUntrackedDisposition(\n\ttouched: RecoveryTouchedFile,\n\tobserved: ObservedUntrackedFile,\n): UntrackedDispositionDecision {\n\tif (touched.mode !== \"untracked\") {\n\t\treturn { disposition: \"skip\", reason: \"disposition only applies to untracked files\" };\n\t}\n\tif (!observed.exists) {\n\t\treturn { disposition: \"skip\", reason: \"untracked file is already absent\" };\n\t}\n\tif (isHex64(touched.afterSha256) && observed.sha256 === touched.afterSha256) {\n\t\treturn { disposition: \"delete\", reason: \"current hash matches the OMK-created hash\" };\n\t}\n\treturn { disposition: \"quarantine\", reason: \"current hash differs from the OMK-created hash\" };\n}\n\nexport type RestoreMode = \"conversation\" | \"code\" | \"both\";\n\nexport type RestorePhaseKind = \"conversation\" | \"code\";\nexport type RestorePhaseAction = \"navigate-tree\" | \"apply-reverse-patch\";\n\nexport interface RestorePlanPhase {\n\treadonly phase: RestorePhaseKind;\n\treadonly action: RestorePhaseAction;\n\treadonly targetLeafId?: string | null;\n\treadonly recordedPaths?: readonly string[];\n}\n\nexport interface RestorePlan {\n\treadonly mode: RestoreMode;\n\treadonly status: \"ready\" | \"blocked\";\n\treadonly phases: readonly RestorePlanPhase[];\n\treadonly blockers: readonly string[];\n\t/** For `both`: the leaf to keep if the conversation phase fails after code restore. */\n\treadonly preservePreviousLeafId?: string | null;\n\treadonly inDoubtPolicy?: \"preserve-previous-leaf\";\n}\n\nexport interface PlanRestoreInput {\n\treadonly mode: RestoreMode;\n\treadonly checkpoint: RecoveryCheckpoint;\n\t/** Required for `code` and `both` modes. */\n\treadonly preflight?: RestorePreflightResult;\n\t/** The current session leaf, preserved for manual recovery in `both` mode. */\n\treadonly currentLeafId?: string | null;\n}\n\nfunction codePhase(checkpoint: RecoveryCheckpoint): RestorePlanPhase {\n\treturn {\n\t\tphase: \"code\",\n\t\taction: \"apply-reverse-patch\",\n\t\trecordedPaths: checkpoint.workspace.touchedFiles.map((file) => file.path),\n\t};\n}\n\nfunction conversationPhase(checkpoint: RecoveryCheckpoint): RestorePlanPhase {\n\treturn { phase: \"conversation\", action: \"navigate-tree\", targetLeafId: checkpoint.session.leafId };\n}\n\nfunction collectPreflightBlockers(preflight: RestorePreflightResult | undefined): string[] {\n\tif (!preflight) return [\"code restore requires a preflight classification\"];\n\tif (preflight.verdict === \"clean\") return [];\n\treturn preflight.issues.map((issue) => (issue.path ? `${issue.code}: ${issue.path}` : issue.code));\n}\n\n/**\n * Build a restore plan for the requested mode.\n *\n *  - `conversation`: navigate the session tree to the checkpoint leaf; no file\n *    writes, so no worktree preflight is required.\n *  - `code`: apply the recorded reverse patch path-by-path; requires a clean\n *    preflight.\n *  - `both`: restore code first, then navigate the tree; requires a clean\n *    preflight. If the second (conversation) phase fails at execution time the\n *    caller marks the operation `in_doubt` and keeps `preservePreviousLeafId`.\n */\nexport function planRestore(input: PlanRestoreInput): RestorePlan {\n\tconst { mode, checkpoint, preflight } = input;\n\tif (mode === \"conversation\") {\n\t\treturn { mode, status: \"ready\", phases: [conversationPhase(checkpoint)], blockers: [] };\n\t}\n\n\tconst blockers = collectPreflightBlockers(preflight);\n\tif (mode === \"code\") {\n\t\tif (blockers.length > 0) return { mode, status: \"blocked\", phases: [], blockers };\n\t\treturn { mode, status: \"ready\", phases: [codePhase(checkpoint)], blockers: [] };\n\t}\n\n\t// mode === \"both\"\n\tconst preservePreviousLeafId = input.currentLeafId ?? null;\n\tif (blockers.length > 0) {\n\t\treturn {\n\t\t\tmode,\n\t\t\tstatus: \"blocked\",\n\t\t\tphases: [],\n\t\t\tblockers,\n\t\t\tpreservePreviousLeafId,\n\t\t\tinDoubtPolicy: \"preserve-previous-leaf\",\n\t\t};\n\t}\n\treturn {\n\t\tmode,\n\t\tstatus: \"ready\",\n\t\tphases: [codePhase(checkpoint), conversationPhase(checkpoint)],\n\t\tblockers: [],\n\t\tpreservePreviousLeafId,\n\t\tinDoubtPolicy: \"preserve-previous-leaf\",\n\t};\n}\n"]}

package/dist/core/sandbox-policy-v2.d.ts

@@ -1,49 +0,0 @@
-import type { NetworkAccessRequest, PathAccessKind, SandboxDecision, SandboxPathResolver, SandboxPolicy } from "./sandbox/policy.ts";
-export interface PathAccessRequestV2 {
-    readonly kind: PathAccessKind;
-    readonly path: string;
-}
-export interface PolicyDiagnostic {
-    readonly code: string;
-    readonly message: string;
-    readonly severity: "info" | "warn" | "block";
-}
-export interface PathDecisionV2 {
-    readonly requestedPath: string;
-    readonly candidate: string;
-    readonly kind: PathAccessKind;
-    readonly action: "allow" | "block";
-    readonly rule: string;
-    readonly reason: string;
-    readonly matchedPattern?: string;
-}
-export interface EnvDecisionV2 {
-    readonly action: "allow" | "block";
-    readonly rule: string;
-    readonly reason: string;
-    /** Denied variable NAMES only. Values are never recorded. */
-    readonly deniedNames: readonly string[];
-}
-export interface SandboxPolicyV2Decision {
-    readonly action: "allow" | "confirm" | "block";
-    readonly rule: string;
-    readonly reason: string;
-    readonly diagnostics: readonly PolicyDiagnostic[];
-    readonly pathDecisions: readonly PathDecisionV2[];
-    readonly networkDecision?: SandboxDecision;
-    readonly envDecision?: EnvDecisionV2;
-}
-export interface SandboxPolicyV2Input {
-    readonly policy: SandboxPolicy;
-    readonly pathRequests?: readonly PathAccessRequestV2[];
-    readonly networkRequest?: NetworkAccessRequest;
-    readonly env?: Readonly<Record<string, string | undefined>>;
-    readonly resolver?: SandboxPathResolver;
-}
-/**
- * Public: evaluate path / env / network requests against a sandbox policy.
- * Path and env checks are fail-closed. Audit mode downgrades a would-block
- * outcome to confirm; enforce mode keeps it block.
- */
-export declare function evaluateSandboxPolicyV2(input: SandboxPolicyV2Input): SandboxPolicyV2Decision;
-//# sourceMappingURL=sandbox-policy-v2.d.ts.map

package/dist/core/sandbox-policy-v2.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sandbox-policy-v2.d.ts","sourceRoot":"","sources":["../../src/core/sandbox-policy-v2.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACX,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,MAAM,qBAAqB,CAAC;AA+D7B,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,SAAS,cAAc,EAAE,CAAC;IAClD,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAuQD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,oBAAoB,GAAG,uBAAuB,CAqE5F","sourcesContent":["/**\n * Lane SA3 - Sandbox Policy V2.\n * allow: SIZE_OK - legacy evaluator; this change only keeps strip-only TypeScript compatibility.\n *\n * Pure fail-closed evaluator that composes path / env / network checks for a\n * sandbox policy. It layers general glob matching (via `minimatch`), realpath\n * normalization (when a resolver is provided), denied-env fail-closed\n * semantics, and IPv4 / IPv6 loopback detection on top of the existing\n * `SandboxPolicy` types. It does not spawn, resolve through the filesystem on\n * its own, or log env values.\n */\nimport path from \"node:path\";\nimport { minimatch } from \"minimatch\";\nimport type {\n\tNetworkAccessRequest,\n\tPathAccessKind,\n\tSandboxDecision,\n\tSandboxPathResolver,\n\tSandboxPolicy,\n} from \"./sandbox/policy.ts\";\n\n/** Exact sensitive environment variable names (do not end in a standard suffix). */\nconst SENSITIVE_ENV_EXACT = new Set<string>([\n\t\"AWS_ACCESS_KEY_ID\",\n\t\"AWS_SECRET_ACCESS_KEY\",\n\t\"AWS_SESSION_TOKEN\",\n\t\"GITHUB_TOKEN\",\n\t\"GH_TOKEN\",\n\t\"GITLAB_TOKEN\",\n\t\"NPM_TOKEN\",\n\t\"NODE_AUTH_TOKEN\",\n]);\n\n/** Sensitive environment variable name suffixes. */\nconst SENSITIVE_ENV_REGEX =\n\t/(^|_)(API_KEY|API_TOKEN|ACCESS_TOKEN|SECRET|SECRET_KEY|PRIVATE_KEY|PASSWORD|PASSWD|TOKEN)$/i;\n\n/**\n * Environment variable names that are always denied because they inject code\n * or redirect runtime loader behavior. Denial is fail-closed: presence of any\n * of these names blocks the policy evaluation regardless of value.\n */\nconst ENV_DENY_NAMES = new Set<string>([\n\t\"LD_PRELOAD\",\n\t\"LD_LIBRARY_PATH\",\n\t\"LD_AUDIT\",\n\t\"LD_BIND_NOW\",\n\t\"LD_PROFILE\",\n\t\"DYLD_INSERT_LIBRARIES\",\n\t\"DYLD_LIBRARY_PATH\",\n\t\"DYLD_FALLBACK_LIBRARY_PATH\",\n\t\"NODE_OPTIONS\",\n\t\"NODE_PATH\",\n\t\"NODE_REPL_EXTERNAL_MODULE\",\n\t\"NODE_EXTRA_CA_CERTS\",\n\t\"NODE_TLS_REJECT_UNAUTHORIZED\",\n\t\"PYTHONPATH\",\n\t\"PYTHONHOME\",\n\t\"PYTHONSTARTUP\",\n\t\"PYTHONINSPECT\",\n\t\"PERL5LIB\",\n\t\"PERLLIB\",\n\t\"PERL5OPT\",\n\t\"RUBYLIB\",\n\t\"RUBYOPT\",\n\t\"RUBYPATH\",\n\t\"JAVA_TOOL_OPTIONS\",\n\t\"_JAVA_OPTIONS\",\n\t\"JDK_JAVA_OPTIONS\",\n\t\"MAVEN_OPTS\",\n]);\n\n/**\n * Matches a URL / DSN with embedded userinfo (`scheme://user:pass@host`).\n * Used for value-based denial; only the variable NAME is ever recorded.\n */\nconst AUTH_URL_REGEX = /^[a-z][a-z0-9+.-]*:\\/\\/[^\\s/@:]+:[^\\s/@]+@[^\\s/@]/i;\n\n/** Path patterns that look like credential / key material on disk. */\nconst SENSITIVE_PATH_REGEX =\n\t/(?:^|[/\\\\])(?:\\.env(?:\\..*)?|auth\\.json|oauth\\.json|\\.netrc|\\.npmrc|\\.pgpass|credentials|id_rsa|id_dsa|id_ecdsa|id_ed25519|.*(?:token|private[_-]?key|credential).*)$/i;\n\nexport interface PathAccessRequestV2 {\n\treadonly kind: PathAccessKind;\n\treadonly path: string;\n}\n\nexport interface PolicyDiagnostic {\n\treadonly code: string;\n\treadonly message: string;\n\treadonly severity: \"info\" | \"warn\" | \"block\";\n}\n\nexport interface PathDecisionV2 {\n\treadonly requestedPath: string;\n\treadonly candidate: string;\n\treadonly kind: PathAccessKind;\n\treadonly action: \"allow\" | \"block\";\n\treadonly rule: string;\n\treadonly reason: string;\n\treadonly matchedPattern?: string;\n}\n\nexport interface EnvDecisionV2 {\n\treadonly action: \"allow\" | \"block\";\n\treadonly rule: string;\n\treadonly reason: string;\n\t/** Denied variable NAMES only. Values are never recorded. */\n\treadonly deniedNames: readonly string[];\n}\n\nexport interface SandboxPolicyV2Decision {\n\treadonly action: \"allow\" | \"confirm\" | \"block\";\n\treadonly rule: string;\n\treadonly reason: string;\n\treadonly diagnostics: readonly PolicyDiagnostic[];\n\treadonly pathDecisions: readonly PathDecisionV2[];\n\treadonly networkDecision?: SandboxDecision;\n\treadonly envDecision?: EnvDecisionV2;\n}\n\nexport interface SandboxPolicyV2Input {\n\treadonly policy: SandboxPolicy;\n\treadonly pathRequests?: readonly PathAccessRequestV2[];\n\treadonly networkRequest?: NetworkAccessRequest;\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\treadonly resolver?: SandboxPathResolver;\n}\n\nfunction isSensitiveEnvName(name: string): boolean {\n\tif (SENSITIVE_ENV_EXACT.has(name)) return true;\n\treturn SENSITIVE_ENV_REGEX.test(name);\n}\n\nfunction normalizePathValue(value: string): string {\n\tconst resolved = path.resolve(value);\n\tlet normalized = resolved.replace(/\\\\/g, \"/\");\n\tif (normalized.length > 1) normalized = normalized.replace(/\\/+$/, \"\");\n\treturn normalized;\n}\n\nfunction ruleHasGlob(pattern: string): boolean {\n\treturn /[*?[\\]{}]/.test(pattern);\n}\n\nfunction matchesRule(pattern: string, candidate: string): boolean {\n\tconst normPattern = normalizePathValue(pattern);\n\tconst normCandidate = normalizePathValue(candidate);\n\tif (ruleHasGlob(normPattern)) {\n\t\tif (minimatch(normCandidate, normPattern)) return true;\n\t\t// also accept recursive prefix form even if the writer omitted `/**`\n\t\treturn minimatch(normCandidate, `${normPattern}/**`);\n\t}\n\treturn normCandidate === normPattern || normCandidate.startsWith(`${normPattern}/`);\n}\n\nfunction matchesAny(patterns: readonly string[], candidate: string): { match: boolean; pattern?: string } {\n\tfor (const pattern of patterns) {\n\t\tif (matchesRule(pattern, candidate)) return { match: true, pattern };\n\t}\n\treturn { match: false };\n}\n\nfunction isInsideRoot(root: string, candidate: string): boolean {\n\tconst normRoot = normalizePathValue(root);\n\tconst normCandidate = normalizePathValue(candidate);\n\treturn normCandidate === normRoot || normCandidate.startsWith(`${normRoot}/`);\n}\n\nfunction isSensitivePath(value: string): boolean {\n\treturn SENSITIVE_PATH_REGEX.test(value.replace(/\\\\/g, \"/\"));\n}\n\n/** True for IPv4 / IPv6 loopback and localhost hostnames. */\nfunction isLoopbackHost(host: string): boolean {\n\tconst h = host\n\t\t.toLowerCase()\n\t\t.replace(/^\\[|\\]$/g, \"\")\n\t\t.trim();\n\tif (h === \"localhost\") return true;\n\tif (h === \"127.0.0.1\" || h === \"::1\" || h === \"0:0:0:0:0:0:0:1\") return true;\n\tif (h === \"::ffff:127.0.0.1\" || h === \"::ffff:7f00:1\") return true;\n\tif (/^127\\./.test(h)) return true;\n\treturn false;\n}\n\nfunction normalizeNetworkLoopback(request: NetworkAccessRequest): NetworkAccessRequest {\n\tlet host = request.host;\n\tif (!host && request.url) {\n\t\ttry {\n\t\t\thost = new URL(request.url).hostname;\n\t\t} catch {\n\t\t\thost = undefined;\n\t\t}\n\t}\n\tif (host && isLoopbackHost(host)) {\n\t\treturn { ...request, host, loopback: true };\n\t}\n\treturn request;\n}\n\nfunction hostFromRequest(request: NetworkAccessRequest): string | undefined {\n\tif (request.host) return request.host.toLowerCase();\n\tif (!request.url) return undefined;\n\ttry {\n\t\treturn new URL(request.url).hostname.toLowerCase();\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction hostMatches(patterns: readonly string[], host: string): boolean {\n\tconst h = host.replace(/\\.$/, \"\");\n\tfor (const raw of patterns) {\n\t\tconst p = raw.toLowerCase().replace(/\\.$/, \"\");\n\t\tif (h === p || h.endsWith(`.${p}`)) return true;\n\t}\n\treturn false;\n}\n\nfunction decideNetworkV2(policy: SandboxPolicy, request: NetworkAccessRequest): SandboxDecision {\n\tif (policy.mode === \"off\") return { allowed: true, rule: \"sandbox.off\", reason: \"Sandbox policy is disabled.\" };\n\tif (request.browser || request.unixSocketPath) {\n\t\treturn {\n\t\t\tallowed: false,\n\t\t\trule: \"network.socket_or_browser\",\n\t\t\treason: \"Browser and Unix socket access is denied by default.\",\n\t\t};\n\t}\n\tif (policy.network.mode === \"none\") {\n\t\treturn { allowed: false, rule: \"network.none\", reason: \"Network access is disabled by policy.\" };\n\t}\n\tif (request.loopback) {\n\t\tif (\n\t\t\tpolicy.network.mode === \"loopback\" ||\n\t\t\tpolicy.network.mode === \"domain-allowlist\" ||\n\t\t\tpolicy.network.mode === \"all-explicit\"\n\t\t) {\n\t\t\treturn { allowed: true, rule: \"network.loopback\", reason: \"Loopback access is allowed.\" };\n\t\t}\n\t\treturn { allowed: false, rule: \"network.loopback_denied\", reason: \"Loopback access is denied.\" };\n\t}\n\tconst host = hostFromRequest(request);\n\tif (!host)\n\t\treturn {\n\t\t\tallowed: false,\n\t\t\trule: \"network.unknown_host\",\n\t\t\treason: \"Network host could not be resolved from request.\",\n\t\t};\n\tif (hostMatches(policy.network.deniedDomains, host)) {\n\t\treturn { allowed: false, rule: \"network.domain_deny\", reason: \"Host matches a denied domain.\" };\n\t}\n\tif (policy.network.mode === \"all-explicit\") {\n\t\treturn {\n\t\t\tallowed: true,\n\t\t\trule: \"network.explicit_all\",\n\t\t\treason: \"Explicit network profile allows outbound host access.\",\n\t\t};\n\t}\n\tif (policy.network.mode === \"domain-allowlist\" && hostMatches(policy.network.allowedDomains, host)) {\n\t\treturn { allowed: true, rule: \"network.domain_allow\", reason: \"Host matches an allowed domain.\" };\n\t}\n\treturn { allowed: false, rule: \"network.domain_not_allowed\", reason: \"Host is not allowed by network policy.\" };\n}\n\nfunction decidePathV2(\n\tpolicy: SandboxPolicy,\n\trequest: PathAccessRequestV2,\n\tresolver: SandboxPathResolver | undefined,\n): PathDecisionV2 {\n\tconst requested = request.path;\n\tconst base = (\n\t\trule: string,\n\t\treason: string,\n\t\tcandidate: string,\n\t\taction: \"allow\" | \"block\",\n\t\tmatchedPattern?: string,\n\t): PathDecisionV2 => ({\n\t\trequestedPath: requested,\n\t\tcandidate,\n\t\tkind: request.kind,\n\t\taction,\n\t\trule,\n\t\treason,\n\t\tmatchedPattern,\n\t});\n\tconst block = (rule: string, reason: string, candidate: string, matchedPattern?: string): PathDecisionV2 =>\n\t\tbase(rule, reason, candidate, \"block\", matchedPattern);\n\tconst allow = (rule: string, reason: string, candidate: string): PathDecisionV2 =>\n\t\tbase(rule, reason, candidate, \"allow\");\n\n\tif (requested.includes(\"\\0\")) {\n\t\treturn block(\"path.invalid\", \"Path contains a NUL byte.\", requested);\n\t}\n\n\tlet candidate: string;\n\tlet isSymlink = false;\n\tif (resolver) {\n\t\tconst resolved = resolver(requested);\n\t\tif (resolved.error) {\n\t\t\treturn block(\"path.resolve_error\", resolved.error, requested);\n\t\t}\n\t\tcandidate = resolved.realPath ?? resolved.nearestExistingParentRealPath ?? normalizePathValue(requested);\n\t\tisSymlink = resolved.isSymlink === true;\n\t} else {\n\t\tcandidate = normalizePathValue(requested);\n\t}\n\n\tif (isSensitivePath(requested) || isSensitivePath(candidate)) {\n\t\treturn block(\"path.sensitive\", \"Sensitive credential-like path is denied.\", candidate);\n\t}\n\n\tif (!isInsideRoot(policy.filesystem.root, candidate)) {\n\t\treturn block(\"path.root_escape\", \"Resolved path is outside the sandbox root.\", candidate);\n\t}\n\n\tif (isSymlink && !policy.filesystem.followSymlinks) {\n\t\treturn block(\"path.symlink\", \"Symlink traversal is denied by policy.\", candidate);\n\t}\n\n\tif (request.kind === \"read\") {\n\t\tconst denied = matchesAny(policy.filesystem.readDeny, candidate);\n\t\tif (denied.match) {\n\t\t\treturn block(\"path.read_deny\", \"Read path matches a deny rule.\", candidate, denied.pattern);\n\t\t}\n\t\tconst deniedRequested = matchesAny(policy.filesystem.readDeny, requested);\n\t\tif (deniedRequested.match) {\n\t\t\treturn block(\"path.read_deny\", \"Read path matches a deny rule.\", candidate, deniedRequested.pattern);\n\t\t}\n\t\tif (matchesAny(policy.filesystem.readAllow, candidate).match) {\n\t\t\treturn allow(\"path.read_allow\", \"Read path is allowed.\", candidate);\n\t\t}\n\t\treturn block(\"path.read_not_allowed\", \"Read path is not in an allow rule.\", candidate);\n\t}\n\n\tconst denyWriteCandidate = matchesAny(policy.filesystem.denyWrite, candidate);\n\tif (denyWriteCandidate.match) {\n\t\treturn block(\n\t\t\t\"path.deny_write\",\n\t\t\t\"Write path matches an unoverrideable denyWrite rule.\",\n\t\t\tcandidate,\n\t\t\tdenyWriteCandidate.pattern,\n\t\t);\n\t}\n\tconst denyWriteRequested = matchesAny(policy.filesystem.denyWrite, requested);\n\tif (denyWriteRequested.match) {\n\t\treturn block(\n\t\t\t\"path.deny_write\",\n\t\t\t\"Write path matches an unoverrideable denyWrite rule.\",\n\t\t\tcandidate,\n\t\t\tdenyWriteRequested.pattern,\n\t\t);\n\t}\n\tif (\n\t\tmatchesAny(policy.filesystem.writeAllow, candidate).match ||\n\t\tmatchesAny(policy.filesystem.tempWrite, candidate).match\n\t) {\n\t\treturn allow(\"path.write_allow\", \"Write path is allowed.\", candidate);\n\t}\n\treturn block(\"path.write_not_allowed\", \"Write path is not in an allow rule.\", candidate);\n}\n\nfunction decideEnvV2(env: Readonly<Record<string, string | undefined>>): EnvDecisionV2 {\n\tconst denied: string[] = [];\n\tfor (const [name, value] of Object.entries(env)) {\n\t\tif (value === undefined) continue;\n\t\tif (ENV_DENY_NAMES.has(name)) {\n\t\t\tdenied.push(name);\n\t\t\tcontinue;\n\t\t}\n\t\tif (isSensitiveEnvName(name)) {\n\t\t\tdenied.push(name);\n\t\t\tcontinue;\n\t\t}\n\t\tif (AUTH_URL_REGEX.test(value)) {\n\t\t\t// Value-based denial: the value embeds credentials. Record NAME only.\n\t\t\tdenied.push(name);\n\t\t}\n\t}\n\tif (denied.length > 0) {\n\t\treturn {\n\t\t\taction: \"block\",\n\t\t\trule: \"env.denied_pattern\",\n\t\t\treason: `Environment contains denied variable(s): ${denied.join(\", \")}.`,\n\t\t\tdeniedNames: denied,\n\t\t};\n\t}\n\treturn { action: \"allow\", rule: \"env.allow\", reason: \"No denied environment variables.\", deniedNames: [] };\n}\n\n/**\n * Public: evaluate path / env / network requests against a sandbox policy.\n * Path and env checks are fail-closed. Audit mode downgrades a would-block\n * outcome to confirm; enforce mode keeps it block.\n */\nexport function evaluateSandboxPolicyV2(input: SandboxPolicyV2Input): SandboxPolicyV2Decision {\n\tconst { policy } = input;\n\tconst diagnostics: PolicyDiagnostic[] = [];\n\tconst pathDecisions: PathDecisionV2[] = [];\n\tlet envDecision: EnvDecisionV2 | undefined;\n\tlet networkDecision: SandboxDecision | undefined;\n\tlet worst: \"allow\" | \"block\" = \"block\";\n\n\tif (policy.mode === \"off\") {\n\t\treturn {\n\t\t\taction: \"allow\",\n\t\t\trule: \"sandbox.off\",\n\t\t\treason: \"Sandbox policy is disabled.\",\n\t\t\tdiagnostics,\n\t\t\tpathDecisions,\n\t\t};\n\t}\n\n\t// Default to allow and escalate to block on any failed check.\n\tworst = \"allow\";\n\n\tif (input.env) {\n\t\tenvDecision = decideEnvV2(input.env);\n\t\tif (envDecision.action === \"block\") {\n\t\t\tworst = \"block\";\n\t\t\tdiagnostics.push({\n\t\t\t\tcode: envDecision.rule,\n\t\t\t\tmessage: `Denied env name(s): ${envDecision.deniedNames.join(\", \")}`,\n\t\t\t\tseverity: \"block\",\n\t\t\t});\n\t\t}\n\t}\n\n\tfor (const request of input.pathRequests ?? []) {\n\t\tconst decision = decidePathV2(policy, request, input.resolver);\n\t\tpathDecisions.push(decision);\n\t\tif (decision.action === \"block\") {\n\t\t\tworst = \"block\";\n\t\t\tdiagnostics.push({ code: decision.rule, message: decision.reason, severity: \"block\" });\n\t\t}\n\t}\n\n\tif (input.networkRequest) {\n\t\tconst normalized = normalizeNetworkLoopback(input.networkRequest);\n\t\tnetworkDecision = decideNetworkV2(policy, normalized);\n\t\tif (!networkDecision.allowed) {\n\t\t\tworst = \"block\";\n\t\t\tdiagnostics.push({ code: networkDecision.rule, message: networkDecision.reason, severity: \"block\" });\n\t\t}\n\t}\n\n\tlet action: \"allow\" | \"confirm\" | \"block\";\n\tlet rule: string;\n\tlet reason: string;\n\tif (worst === \"allow\") {\n\t\taction = \"allow\";\n\t\trule = \"policy.composite_allow\";\n\t\treason = \"All sandbox checks passed.\";\n\t} else if (policy.mode === \"audit\") {\n\t\taction = \"confirm\";\n\t\trule = \"policy.audit_block\";\n\t\treason = \"Audit mode: a would-block check is downgraded to confirm.\";\n\t} else {\n\t\taction = \"block\";\n\t\trule = \"policy.block\";\n\t\treason = \"One or more sandbox checks blocked the request.\";\n\t}\n\n\treturn { action, rule, reason, diagnostics, pathDecisions, networkDecision, envDecision };\n}\n"]}