@guilz-dev/belay 0.8.1 → 0.9.0

package/dist/core/effect-ir/normalize.js

@@ -6,6 +6,22 @@ export function normalizeEffectTags(tags) {
     }
     return [...set].sort();
 }
+/**
+ * Joins opacity evidence without allowing a later analysis stage to weaken an
+ * earlier uncertainty classification.
+ */
+export function joinEffectOpacity(...opacities) {
+    if (opacities.includes('unparseable')) {
+        return 'unparseable';
+    }
+    if (opacities.includes('opaque')) {
+        return 'opaque';
+    }
+    if (opacities.includes('recursive')) {
+        return 'recursive';
+    }
+    return 'transparent';
+}
 export function mergeRequirements(...groups) {
     const seen = new Map();
     for (const group of groups) {
@@ -45,13 +61,7 @@ export function mergeEffectPlans(...plans) {
         return present[0];
     }
     const children = present.flatMap((plan) => plan.root.kind === 'merge' ? [...plan.root.children] : [plan.root]);
-    const opacity = present.some((plan) => plan.opacity === 'unparseable')
-        ? 'unparseable'
-        : present.some((plan) => plan.opacity === 'opaque')
-            ? 'opaque'
-            : present.some((plan) => plan.opacity === 'recursive')
-                ? 'recursive'
-                : 'transparent';
+    const opacity = joinEffectOpacity(...present.map((plan) => plan.opacity));
     const fingerprints = present.map((plan) => plan.inputFingerprint).sort();
     return {
         version: 1,

package/dist/core/effect-ir/shell-build.js

@@ -1,5 +1,5 @@
 import { collectRequirements } from './build.js';
-import { mergeRequirements } from './normalize.js';
+import { joinEffectOpacity, mergeRequirements } from './normalize.js';
 /**
  * Build a canonical EffectPlan from shell segments that have already been
  * semantically analyzed. This function only assembles and normalizes effects;
@@ -16,7 +16,7 @@ export function buildShellEffectPlan(params) {
         version: 1,
         root,
         inputFingerprint: params.inputFingerprint,
-        opacity: mergeOpacity(params.segments.map((segment) => segment.opacity)),
+        opacity: joinEffectOpacity(...params.segments.map((segment) => segment.opacity)),
         disposition: requirements.length === 0 ? 'effect_free' : 'effects',
         completeness,
         signals: [
@@ -63,15 +63,3 @@ function mergeNodes(nodes) {
     }
     return { kind: 'merge', children: nodes };
 }
-function mergeOpacity(opacities) {
-    if (opacities.includes('unparseable')) {
-        return 'unparseable';
-    }
-    if (opacities.includes('opaque')) {
-        return 'opaque';
-    }
-    if (opacities.includes('recursive')) {
-        return 'recursive';
-    }
-    return 'transparent';
-}

package/dist/core/effect-ir/shell-lower.js

@@ -5,7 +5,8 @@ import { isFdDuplication, isRedirectOperator, tokenizeShell } from '../shell-tok
 import { decodeEgressEffects } from '../verdict/egress-classify.js';
 import { decodeGitEffects } from '../verdict/git-classifier.js';
 import { resolveLauncherRecipe } from '../verdict/launcher-resolve.js';
-import { extractRecursiveScript, parseSegment, redactCommand, segmentOpacity, splitStructuralShellSegments, structuralSubstitutionInners, } from '../verdict/parser.js';
+import { extractRecursiveScript, isCommandInspection, isDynamicRecursiveEvaluation, parseSegment, redactCommand, segmentOpacity, splitStructuralShellSegments, structuralSubstitutionInners, } from '../verdict/parser.js';
+import { joinEffectOpacity } from './normalize.js';
 import { classifyPackageAcquisitionSpec, innerRecipeFromPeel, peelPackageExecArgv, resolveLocalBin, } from './package-exec.js';
 import { buildShellEffectPlan, } from './shell-build.js';
 const MAX_LOWER_DEPTH = 8;
@@ -61,7 +62,7 @@ function lowerTopLevelSegments(command, context) {
                 ...(requiresCwd
                     ? {
                         completeness: 'partial',
-                        opacity: result.opacity === 'unparseable' ? 'unparseable' : 'opaque',
+                        opacity: joinEffectOpacity(result.opacity, 'opaque'),
                     }
                     : {}),
                 signals: [...new Set([...result.signals, 'shell.cwd_unknown'])],
@@ -117,6 +118,12 @@ function requiresKnownCwd(requirementValue) {
         requirementValue.resource.kind === 'executable' &&
         requirementValue.resource.operation === 'spawn');
 }
+function joinNestedOpacity(outer, nested) {
+    const nestedOpacity = nested.completeness === 'partial' && nested.opacity === 'transparent'
+        ? 'recursive'
+        : nested.opacity;
+    return joinEffectOpacity(outer, nestedOpacity);
+}
 function lowerSegment(command, context) {
     const commandRedacted = redactCommand(command);
     const rawTokens = tokenizeShell(command);
@@ -134,20 +141,20 @@ function lowerSegment(command, context) {
         requirements.push(requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, commandRedacted, [
             'shell.env_wrapper_incomplete',
         ]));
-        opacity = 'opaque';
+        opacity = joinEffectOpacity(opacity, 'opaque');
     }
-    if (path.basename((environment.commandTokens ?? rawTokens)[0] ?? '') === 'xargs') {
+    if (parsed.encounteredXargs) {
         requirements.push(requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, commandRedacted, [
             'shell.xargs_stdin_dynamic',
         ]));
         signals.add('shell.xargs_stdin_dynamic');
-        opacity = 'opaque';
+        opacity = joinEffectOpacity(opacity, 'opaque');
     }
     if (context.depth >= MAX_LOWER_DEPTH) {
         requirements.push(requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, commandRedacted, [
             'shell.lower_depth_exceeded',
         ]));
-        return shellSegment(commandRedacted, head, requirements, 'opaque', signals);
+        return shellSegment(commandRedacted, head, requirements, joinEffectOpacity(opacity, 'opaque'), signals);
     }
     const packageExec = peelPackageExecArgv(tokens);
     if (packageExec) {
@@ -156,7 +163,7 @@ function lowerSegment(command, context) {
             signals.add(signal);
         }
         if (packageExec.opaque) {
-            opacity = 'opaque';
+            opacity = joinEffectOpacity(opacity, 'opaque');
         }
         const innerRecipe = packageExecInnerIsMetadata(packageExec)
             ? null
@@ -173,16 +180,18 @@ function lowerSegment(command, context) {
                 for (const signal of nestedSegment.signals) {
                     signals.add(signal);
                 }
-                if (nestedSegment.completeness === 'partial') {
-                    opacity = nestedSegment.opacity === 'unparseable' ? 'unparseable' : 'recursive';
-                }
+                opacity = joinNestedOpacity(opacity, nestedSegment);
             }
         }
         return shellSegment(commandRedacted, head, requirements, opacity, signals);
     }
     const recursiveScript = extractRecursiveScript(tokens);
-    if (recursiveScript) {
-        requirements.push(processRequirement(head || 'sh', 'spawn', commandRedacted, ['shell.recursive_wrapper']));
+    if (recursiveScript && opacity !== 'opaque' && opacity !== 'unparseable') {
+        const dynamicEvaluation = isDynamicRecursiveEvaluation(tokens);
+        requirements.push(processRequirement(head || 'sh', 'spawn', commandRedacted, [
+            'shell.recursive_wrapper',
+            ...(dynamicEvaluation ? ['dynamic_shell_evaluation'] : []),
+        ]));
         const nested = lowerTopLevelSegments(recursiveScript, {
             ...context,
             command: recursiveScript,
@@ -196,6 +205,9 @@ function lowerSegment(command, context) {
             }
         }
         signals.add('shell.recursive_wrapper');
+        if (dynamicEvaluation) {
+            signals.add('dynamic_shell_evaluation');
+        }
         return shellSegment(commandRedacted, head, requirements, 'recursive', signals);
     }
     const launcher = resolveLauncherRecipe({
@@ -219,16 +231,14 @@ function lowerSegment(command, context) {
                 for (const signal of nestedSegment.signals) {
                     signals.add(signal);
                 }
-                if (nestedSegment.completeness === 'partial') {
-                    opacity = nestedSegment.opacity === 'unparseable' ? 'unparseable' : 'recursive';
-                }
+                opacity = joinNestedOpacity(opacity, nestedSegment);
             }
         }
         if (launcher.opaque || launcher.recipes.length === 0) {
             requirements.push(requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, commandRedacted, [
                 `launcher.${launcher.reason}`,
             ]));
-            opacity = 'opaque';
+            opacity = joinEffectOpacity(opacity, 'opaque');
         }
         return shellSegment(commandRedacted, head, requirements, opacity, signals);
     }
@@ -270,7 +280,7 @@ function lowerSegment(command, context) {
     const environmentSignals = effectChangingEnvironmentSignals(head, env, environment.changedNames);
     if (environmentSignals.length > 0) {
         requirements.push(requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, commandRedacted, environmentSignals));
-        opacity = 'opaque';
+        opacity = joinEffectOpacity(opacity, 'opaque');
         for (const signal of environmentSignals) {
             signals.add(signal);
         }
@@ -281,7 +291,7 @@ function lowerSegment(command, context) {
         ensureRequirement(requirements, requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, commandRedacted, [
             'pipe_to_shell',
         ]));
-        opacity = 'opaque';
+        opacity = joinEffectOpacity(opacity, 'opaque');
     }
     if (opacity === 'unparseable' || opacity === 'opaque') {
         ensureRequirement(requirements, requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, commandRedacted, [
@@ -356,9 +366,63 @@ function packageExecInnerIsMetadata(peel) {
     const args = peel.innerTokens.slice(1);
     return (args.length > 0 && args.every((arg) => ['--help', '--version', '-V', '-h', '-v'].includes(arg)));
 }
+const METADATA_ONLY_FLAGS = new Set(['--version', '-v', '-V', '--help', '-h']);
+function isMetadataOnlyArgv(argv) {
+    return argv.length > 0 && argv.every((token) => METADATA_ONLY_FLAGS.has(token));
+}
+function executableBaseName(head) {
+    return path.basename(head);
+}
+const RAILS_READ_ONLY_SUBCOMMANDS = new Set(['routes', 'middleware', 'stats', 'about', 'version']);
+function railsReadOnlySubcommand(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand.startsWith('-')) {
+        return false;
+    }
+    return RAILS_READ_ONLY_SUBCOMMANDS.has(subcommand);
+}
+function decodeRuntimeMetadataProcess(head, args, segment) {
+    if (head === 'bundle') {
+        if (args.length === 1 && isMetadataOnlyArgv(args)) {
+            return [processRequirement(head, 'inspect', segment, ['process.inspect.runtime_metadata'])];
+        }
+        if (args[0] === 'exec' && args.length >= 2) {
+            const innerHead = args[1] ?? '';
+            const innerArgs = args.slice(2);
+            const innerBase = executableBaseName(innerHead);
+            if ((innerBase === 'rails' || innerBase === 'rake') && railsReadOnlySubcommand(innerArgs)) {
+                return [
+                    processRequirement(innerHead, 'inspect', segment, ['process.inspect.rails_read_only']),
+                ];
+            }
+            if (isMetadataOnlyArgv(innerArgs)) {
+                return [
+                    processRequirement(innerHead, 'inspect', segment, [
+                        'process.inspect.bundle_exec_metadata',
+                    ]),
+                ];
+            }
+        }
+        return null;
+    }
+    if ((head === 'ruby' || head === 'yarn') && args.length >= 1 && isMetadataOnlyArgv(args)) {
+        return [processRequirement(head, 'inspect', segment, ['process.inspect.runtime_metadata'])];
+    }
+    if (head === 'make' && args.includes('-n')) {
+        return [processRequirement(head, 'inspect', segment, ['process.inspect.make_dry_run'])];
+    }
+    const base = executableBaseName(head);
+    if ((base === 'rails' || base === 'rake') && railsReadOnlySubcommand(args)) {
+        return [processRequirement(head, 'inspect', segment, ['process.inspect.rails_read_only'])];
+    }
+    return null;
+}
 function decodeProcessOrFilesystem(params) {
     const { tokens, head, env, cwd, repoRoot, segment } = params;
     const args = tokens.slice(1);
+    if (isCommandInspection(tokens)) {
+        return [processRequirement(head, 'inspect', segment, ['process.inspect.command_lookup'])];
+    }
     if (head === 'lsof') {
         return validLsof(args)
             ? [processRequirement(head, 'inspect', segment, ['process.inspect.lsof'])]
@@ -432,7 +496,11 @@ function decodeProcessOrFilesystem(params) {
     if (head === 'prisma') {
         return decodePrisma(args, env, repoRoot, segment);
     }
-    if ((head === 'npm' || head === 'pnpm') && args.length === 1 && args[0] === '--version') {
+    const runtimeMetadata = decodeRuntimeMetadataProcess(head, args, segment);
+    if (runtimeMetadata) {
+        return runtimeMetadata;
+    }
+    if ((head === 'npm' || head === 'pnpm') && args.length === 1 && isMetadataOnlyArgv(args)) {
         return [processRequirement(head, 'inspect', segment, ['process.inspect.package_manager'])];
     }
     if (head === 'belay') {
@@ -544,12 +612,9 @@ function decodeBelay(args, repoRoot, segment) {
     return [processRequirement('belay', 'spawn', segment, ['process.known_local_spawn'])];
 }
 function decodeTsc(args, cwd, segment) {
-    const inspect = args.length > 0 && args.every((arg) => ['--help', '--version', '-h', '-v'].includes(arg));
-    const requirements = [
-        processRequirement('tsc', inspect ? 'inspect' : 'spawn', segment, [
-            inspect ? 'process.inspect.tsc_metadata' : 'process.known_local_spawn',
-        ]),
-    ];
+    const metadataOnly = args.length > 0 && args.every((arg) => ['--help', '--version', '-h', '-v'].includes(arg));
+    const requirements = [];
+    let hasOutput = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index] ?? '';
         const inline = arg.match(/^--(?:outDir|outFile)=(.+)$/)?.[1];
@@ -558,11 +623,21 @@ function decodeTsc(args, cwd, segment) {
         if (!output) {
             continue;
         }
+        hasOutput = true;
         addWriteEffects(requirements, resolvePathOperand(output, cwd), segment, ['tsc.output']);
         if (separate) {
             index += 1;
         }
     }
+    const typecheckOnly = args.includes('--noEmit') && !hasOutput;
+    const inspect = metadataOnly || typecheckOnly;
+    requirements.unshift(processRequirement('tsc', inspect ? 'inspect' : 'spawn', segment, [
+        metadataOnly
+            ? 'process.inspect.tsc_metadata'
+            : typecheckOnly
+                ? 'process.inspect.tsc_typecheck'
+                : 'process.known_local_spawn',
+    ]));
     return requirements;
 }
 function decodeCopyMove(head, args, cwd, segment) {

package/dist/core/gate-contract.d.ts

@@ -1,4 +1,5 @@
-import type { Assessment, ClassifyResult, HookVerdict } from './types.js';
+import type { Assessment, ClassifyResult, HookVerdict, MediatedExecutionResult } from './types.js';
+export type { MediatedExecutionResult } from './types.js';
 export declare const GATE_CONTRACT_VERSION: 1;
 export type GatedActionKind = 'shell' | 'subagent' | 'tool';
 export interface GatedAction {
@@ -34,6 +35,8 @@ export interface GateVerdict extends GatePermissionResponse {
     effectPlan?: ClassifyResult['effectPlan'];
     effectPlanPolicyDecisions?: ClassifyResult['effectPlanPolicyDecisions'];
     boundaryProfile?: string;
+    wouldMediate?: boolean;
+    mediatedExecution?: MediatedExecutionResult;
 }
 export declare function isGatedAction(value: unknown): value is GatedAction;
 export declare function classifyResultToGateVerdict(params: {

package/dist/core/gate-contract.js

@@ -31,6 +31,8 @@ export function classifyResultToGateVerdict(params) {
         effectPlan: result.effectPlan,
         effectPlanPolicyDecisions: result.effectPlanPolicyDecisions,
         boundaryProfile: result.boundaryProfile,
+        wouldMediate: result.wouldMediate,
+        mediatedExecution: result.mediatedExecution,
     };
 }
 export function unnormalizedGateVerdict(params) {

package/dist/core/process-runner.d.ts

@@ -1,10 +1,17 @@
 import { type SpawnOptionsWithoutStdio } from 'node:child_process';
+import type { ScrubOptions } from './types.js';
 export interface ShellRunResult {
     exitCode: number | null;
     signal: string | null;
     timedOut: boolean;
-    stdout?: string;
-    stderr?: string;
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+}
+export interface ProcessOutputPolicy {
+    /** Scrub credential context before the irreversible output-tail cap is applied. */
+    scrubOptions: ScrubOptions;
 }
 export declare function windowsProcessTreeKillArgs(pid: number): string[];
-export declare function runProcessWithBoundedOutput(file: string, args: string[], options: SpawnOptionsWithoutStdio, timeoutMs: number): Promise<ShellRunResult>;
+export declare function runProcessWithBoundedOutput(file: string, args: string[], options: SpawnOptionsWithoutStdio, timeoutMs: number, outputPolicy?: ProcessOutputPolicy): Promise<ShellRunResult>;

package/dist/core/process-runner.js

@@ -1,11 +1,36 @@
 import { spawn } from 'node:child_process';
-const PROCESS_OUTPUT_TAIL_BYTES = 16_384;
+import { appendBoundedOutputTail, decodeBoundedOutputTail, OUTPUT_TAIL_LIMIT_BYTES, } from './bounded-output.js';
+import { createStreamingScrubber } from './scrub.js';
 const EXIT_OUTPUT_GRACE_MS = 25;
 const TIMEOUT_KILL_GRACE_MS = 250;
 const WINDOWS_TASKKILL_TIMEOUT_MS = 5_000;
-function appendOutputTail(current, chunk) {
-    const next = Buffer.concat([current, Buffer.from(chunk)]);
-    return next.length > PROCESS_OUTPUT_TAIL_BYTES ? next.subarray(-PROCESS_OUTPUT_TAIL_BYTES) : next;
+class ScrubbedOutputTail {
+    #scrubber;
+    #tail = Buffer.alloc(0);
+    #tailTruncated = false;
+    #rawBytes = 0;
+    constructor(options) {
+        this.#scrubber = createStreamingScrubber(options);
+    }
+    append(chunk) {
+        const bytes = Buffer.from(chunk);
+        this.#rawBytes += bytes.length;
+        this.#appendSafe(this.#scrubber.write(bytes));
+    }
+    finish() {
+        this.#appendSafe(this.#scrubber.end());
+        return {
+            value: decodeBoundedOutputTail(this.#tail),
+            truncated: this.#rawBytes > OUTPUT_TAIL_LIMIT_BYTES || this.#tailTruncated,
+        };
+    }
+    #appendSafe(value) {
+        if (!value)
+            return;
+        const output = appendBoundedOutputTail(this.#tail, value);
+        this.#tail = output.tail;
+        this.#tailTruncated ||= output.truncated;
+    }
 }
 export function windowsProcessTreeKillArgs(pid) {
     return ['/pid', String(pid), '/t', '/f'];
@@ -36,7 +61,7 @@ function forceKillWindowsProcessTree(pid, fallback) {
         taskkill.on('close', (code) => finish(code === 0));
     });
 }
-export function runProcessWithBoundedOutput(file, args, options, timeoutMs) {
+export function runProcessWithBoundedOutput(file, args, options, timeoutMs, outputPolicy) {
     return new Promise((resolve) => {
         const detached = process.platform !== 'win32';
         const child = spawn(file, args, {
@@ -46,15 +71,35 @@ export function runProcessWithBoundedOutput(file, args, options, timeoutMs) {
         });
         let stdout = Buffer.alloc(0);
         let stderr = Buffer.alloc(0);
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        const scrubbedStdout = outputPolicy
+            ? new ScrubbedOutputTail(outputPolicy.scrubOptions)
+            : undefined;
+        const scrubbedStderr = outputPolicy
+            ? new ScrubbedOutputTail(outputPolicy.scrubOptions)
+            : undefined;
         let timedOut = false;
         let settled = false;
         let windowsCleanupPending = false;
         let exitTimer;
         child.stdout.on('data', (chunk) => {
-            stdout = appendOutputTail(stdout, chunk);
+            if (scrubbedStdout) {
+                scrubbedStdout.append(chunk);
+                return;
+            }
+            const output = appendBoundedOutputTail(stdout, chunk);
+            stdout = output.tail;
+            stdoutTruncated ||= output.truncated;
         });
         child.stderr.on('data', (chunk) => {
-            stderr = appendOutputTail(stderr, chunk);
+            if (scrubbedStderr) {
+                scrubbedStderr.append(chunk);
+                return;
+            }
+            const output = appendBoundedOutputTail(stderr, chunk);
+            stderr = output.tail;
+            stderrTruncated ||= output.truncated;
         });
         const finish = (exitCode, signal) => {
             if (settled) {
@@ -67,12 +112,16 @@ export function runProcessWithBoundedOutput(file, args, options, timeoutMs) {
             }
             child.stdout.destroy();
             child.stderr.destroy();
+            const safeStdout = scrubbedStdout?.finish();
+            const safeStderr = scrubbedStderr?.finish();
             resolve({
                 exitCode,
                 signal: signal ? String(signal) : null,
                 timedOut,
-                stdout: stdout.toString('utf8'),
-                stderr: stderr.toString('utf8'),
+                stdout: safeStdout?.value ?? decodeBoundedOutputTail(stdout),
+                stderr: safeStderr?.value ?? decodeBoundedOutputTail(stderr),
+                stdoutTruncated: safeStdout?.truncated ?? stdoutTruncated,
+                stderrTruncated: safeStderr?.truncated ?? stderrTruncated,
             });
         };
         const kill = (signal) => {
@@ -104,7 +153,14 @@ export function runProcessWithBoundedOutput(file, args, options, timeoutMs) {
             }, TIMEOUT_KILL_GRACE_MS);
         }, timeoutMs);
         child.on('error', (error) => {
-            stderr = appendOutputTail(stderr, error.message);
+            if (scrubbedStderr) {
+                scrubbedStderr.append(error.message);
+                finish(1, null);
+                return;
+            }
+            const output = appendBoundedOutputTail(stderr, error.message);
+            stderr = output.tail;
+            stderrTruncated ||= output.truncated;
             finish(1, null);
         });
         child.on('exit', (exitCode, signal) => {

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

@@ -17,8 +17,11 @@ export declare function prepareRecoveryCheckpoint(params: {
     protectedRoots?: string[];
     config: CheckpointConfig;
     backend?: RecoveryBackend;
+    /** Snapshot-time resource identity; re-validated before manifest commit. */
+    expectedResourceIdentity?: string;
 }): Promise<PreparedRecoveryCheckpoint>;
 export declare function discardPreparedRecoveryCheckpoint(stateDir: string, checkpointId: string): Promise<boolean>;
+export declare function markRecoveryCheckpointNeedsManualRepair(stateDir: string, checkpointId: string, detail: string): Promise<void>;
 export declare function listRecoveryCheckpoints(stateDir: string, repoRoot?: string): Promise<RecoveryCheckpointSummary[]>;
 export declare function recoveryCheckpointStorageBytes(stateDir: string, repoRoot?: string): Promise<number>;
 export declare function showRecoveryCheckpoint(stateDir: string, checkpointId: string, expectedRepoRoot?: string): Promise<import("./artifact-store.js").RecoveryArtifact>;

package/dist/core/recovery/checkpoint.js

@@ -4,13 +4,31 @@ import { mkdir, readdir, readFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { canonicalStringify, hashValue } from '../fingerprint.js';
 import { canonicalPath } from '../path-utils.js';
+import { isGitWorktreeAvailable } from '../transactional/git-worktree.js';
 import { artifactRepoRoot, atomicWriteJson, checkpointDir, checkpointIds, checkpointIdsForRepo, checkpointsRoot, cleanupOrphanedStaging, directorySize, fsyncPath, markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, RECOVERY_CHECKPOINT_CORRUPT, readRecoveryArtifact, writeRecoveryState, } from './artifact-store.js';
 import { matchRecoverySide, reconcileRecoveryCheckpoint } from './reconcile.js';
 import { currentRecoveryResourceIdentity } from './resource-identity.js';
 import { RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, recoveryRestoreBinding, restoreRecoveryCheckpoint, } from './restore.js';
 import { assertRecoverySafeTarget, captureRecoverySnapshot, withoutRecoveryBlob, } from './snapshot-node.js';
-function recoveryProofProbeSignals(backend) {
+async function resolveRecoveryResourceKind(backend, repoRoot) {
+    if (backend === 'git_worktree') {
+        return 'git_repository';
+    }
+    if (await isGitWorktreeAvailable(repoRoot)) {
+        return 'git_repository';
+    }
+    return 'directory';
+}
+function recoveryProofProbeSignals(backend, resourceKind) {
     if (backend === 'file_checkpoint') {
+        if (resourceKind === 'directory') {
+            return [
+                'non_git_workspace',
+                'non_git_file_checkpoint',
+                'file_checkpoint',
+                'observed_repo_local_diff',
+            ];
+        }
         return ['dirty_git_worktree', 'file_checkpoint', 'observed_repo_local_diff'];
     }
     return ['clean_git_worktree', 'observed_repo_local_diff'];
@@ -45,6 +63,7 @@ async function garbageCollect(stateDir, config, repoRoot) {
 }
 export async function prepareRecoveryCheckpoint(params) {
     const backend = params.backend ?? 'git_worktree';
+    const resourceKind = await resolveRecoveryResourceKind(backend, params.repoRoot);
     await mkdir(checkpointsRoot(params.stateDir), { recursive: true, mode: 0o700 });
     await cleanupOrphanedStaging(params.stateDir);
     await garbageCollect(params.stateDir, params.config, params.repoRoot);
@@ -88,6 +107,10 @@ export async function prepareRecoveryCheckpoint(params) {
             });
         }
         const createdAt = new Date().toISOString();
+        const repoIdentity = await currentRecoveryResourceIdentity(params.repoRoot, resourceKind);
+        if (params.expectedResourceIdentity && repoIdentity !== params.expectedResourceIdentity) {
+            throw new Error('recovery_checkpoint_repo_mismatch');
+        }
         const proof = {
             version: 1,
             backend,
@@ -97,15 +120,15 @@ export async function prepareRecoveryCheckpoint(params) {
             effectClosure: 'repo_local_fs_observed',
             issuedAt: createdAt,
             expiresAt: new Date(Date.now() + params.config.appliedRetentionHours * 60 * 60 * 1000).toISOString(),
-            probeSignals: recoveryProofProbeSignals(backend),
+            probeSignals: recoveryProofProbeSignals(backend, resourceKind),
         };
         const manifest = {
             version: 2,
             checkpointId,
             backend,
             repoRoot: canonicalPath(params.repoRoot),
-            resourceKind: 'git_repository',
-            repoIdentity: await currentRecoveryResourceIdentity(params.repoRoot, 'git_repository'),
+            resourceKind,
+            repoIdentity,
             commandFingerprint: params.commandFingerprint,
             createdAt,
             expiresAt: proof.expiresAt,
@@ -144,6 +167,10 @@ export async function discardPreparedRecoveryCheckpoint(stateDir, checkpointId)
     await rm(loaded.artifactDir, { recursive: true, force: true });
     return true;
 }
+export async function markRecoveryCheckpointNeedsManualRepair(stateDir, checkpointId, detail) {
+    const loaded = await readRecoveryArtifact(stateDir, checkpointId);
+    await writeRecoveryState(loaded.artifactDir, 'needs_manual_repair', loaded.manifestHash, detail);
+}
 export async function listRecoveryCheckpoints(stateDir, repoRoot) {
     await cleanupOrphanedStaging(stateDir);
     const summaries = [];
@@ -176,6 +203,7 @@ export async function listRecoveryCheckpoints(stateDir, repoRoot) {
                 state,
                 ...(loaded.state.detail ? { stateDetail: loaded.state.detail } : {}),
                 backend: loaded.manifest.backend,
+                resourceKind: loaded.manifest.version === 2 ? loaded.manifest.resourceKind : 'git_repository',
                 repoRoot: loaded.manifest.repoRoot,
                 commandFingerprint: loaded.manifest.commandFingerprint,
                 createdAt: loaded.manifest.createdAt,
@@ -202,6 +230,7 @@ export async function listRecoveryCheckpoints(stateDir, repoRoot) {
                     checkpointId: id,
                     state: 'corrupt',
                     backend: manifest.backend,
+                    resourceKind: manifest.version === 2 ? manifest.resourceKind : 'git_repository',
                     repoRoot: manifest.repoRoot,
                     commandFingerprint: manifest.commandFingerprint,
                     createdAt: manifest.createdAt,

package/dist/core/recovery/types.d.ts

@@ -86,6 +86,7 @@ export interface RecoveryCheckpointSummary {
     /** Operator-facing detail from durable checkpoint state (e.g. mixed-state reason). */
     stateDetail?: string;
     backend: RecoveryBackend;
+    resourceKind: 'git_repository' | 'directory';
     repoRoot: string;
     commandFingerprint: string;
     createdAt: string;

package/dist/core/scrub.d.ts

@@ -1,3 +1,20 @@
 import type { ScrubOptions } from './types.js';
 export declare function scrubString(value: string, options?: ScrubOptions): string;
+export interface StreamingScrubber {
+    /** Raw, undecided UTF-8 bytes retained between writes. */
+    readonly bufferedBytes: number;
+    write(chunk: Buffer | string): string;
+    end(): string;
+}
+export declare const STREAMING_SCRUBBER_MAX_BUFFER_BYTES = 256;
+/**
+ * Creates a deterministic scrubber for unbounded process output.
+ *
+ * Only bounded, undecided grammar prefixes are retained. Once a bounded sensitive marker is
+ * recognized, the scrubber enters a suppression state before consuming any unbounded whitespace,
+ * credential value, or URL authority. URL authorities are conservatively hidden in full because a
+ * streaming parser cannot know whether an arbitrarily long username will later be followed by a
+ * password separator without retaining it.
+ */
+export declare function createStreamingScrubber(options?: ScrubOptions): StreamingScrubber;
 export declare function scrubValue(value: unknown, options?: ScrubOptions): unknown;