@guilz-dev/belay 0.6.0 → 0.7.0

package/dist/core/egress-approval.js

@@ -1,23 +1,15 @@
 import { randomUUID } from 'node:crypto';
 import { compactApprovals, createApprovalRecord } from './approval.js';
 import { issueApprovalToken } from './approval-token.js';
+import { mutateApprovalStateWithRetry } from './capability/approval-state-mutation.js';
 import { configuredControlPlaneDir } from './config.js';
-import { addDomainToAllowlist, loadEgressAllowlist, saveEgressAllowlist, } from './egress/allowlist.js';
+import { addDomainToAllowlist, mutateEgressAllowlist } from './egress/allowlist.js';
 import { parseHostFromSummary } from './egress/fingerprint.js';
 import { notifyDeny } from './notify.js';
 export async function ensurePendingEgressApproval(params) {
     const { config, repoRoot, policyResult, store } = params;
-    const pending = await store.loadPending();
-    pending.state = compactApprovals(pending.state);
-    const existing = pending.state.approvals.find((approval) => approval.kind === 'egress' &&
-        approval.fingerprint === policyResult.fingerprint &&
-        approval.repoRoot === repoRoot);
-    if (existing) {
-        await store.writePending(pending.filePath, pending.state);
-        return { approvalId: existing.approvalId, approval: existing, created: false };
-    }
     const approvalId = `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`;
-    const approval = createApprovalRecord({
+    const candidate = createApprovalRecord({
         kind: 'egress',
         fingerprint: policyResult.fingerprint,
         repoRoot,
@@ -26,44 +18,47 @@ export async function ensurePendingEgressApproval(params) {
         approvalTtlMinutes: config.approvalTtlMinutes,
         approvalId,
     });
-    pending.state.approvals.push(approval);
-    await store.writePending(pending.filePath, pending.state);
-    return { approvalId, approval, created: true };
-}
-const consumeLocks = new Map();
-async function withConsumeLock(key, fn) {
-    const previous = consumeLocks.get(key) ?? Promise.resolve();
-    let release;
-    const gate = new Promise((resolve) => {
-        release = resolve;
+    const outcome = await mutateApprovalStateWithRetry({
+        load: store.loadPending,
+        write: store.writePending,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const existing = compacted.approvals.find((approval) => approval.kind === 'egress' &&
+                approval.fingerprint === policyResult.fingerprint &&
+                approval.repoRoot === repoRoot);
+            if (existing) {
+                return {
+                    state: compacted,
+                    result: { approvalId: existing.approvalId, approval: existing, created: false },
+                };
+            }
+            compacted.approvals.push(candidate);
+            return {
+                state: compacted,
+                result: { approvalId, approval: candidate, created: true },
+            };
+        },
     });
-    consumeLocks.set(key, previous.then(() => gate));
-    await previous;
-    try {
-        return await fn();
-    }
-    finally {
-        release();
-        if (consumeLocks.get(key) === gate) {
-            consumeLocks.delete(key);
-        }
+    if (!outcome) {
+        throw new Error('Failed to persist pending egress approval');
     }
+    return outcome;
 }
 export async function consumeApprovedEgress(params) {
-    const lockKey = `${params.repoRoot}:${params.fingerprint}`;
-    return withConsumeLock(lockKey, async () => {
-        const approved = await params.store.loadApproved();
-        approved.state = compactApprovals(approved.state);
-        const index = approved.state.approvals.findIndex((approval) => approval.kind === 'egress' &&
-            approval.fingerprint === params.fingerprint &&
-            approval.repoRoot === params.repoRoot);
-        if (index === -1) {
-            await params.store.writeApproved(approved.filePath, approved.state);
-            return null;
-        }
-        const [approval] = approved.state.approvals.splice(index, 1);
-        await params.store.writeApproved(approved.filePath, approved.state);
-        return approval;
+    return mutateApprovalStateWithRetry({
+        load: params.store.loadApproved,
+        write: params.store.writeApproved,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const index = compacted.approvals.findIndex((approval) => approval.kind === 'egress' &&
+                approval.fingerprint === params.fingerprint &&
+                approval.repoRoot === params.repoRoot);
+            if (index === -1) {
+                return null;
+            }
+            const [approval] = compacted.approvals.splice(index, 1);
+            return { state: compacted, result: approval ?? null };
+        },
     });
 }
 export async function notifyEgressDeny(params) {
@@ -98,8 +93,8 @@ export async function recordEgressApproval(params) {
     const { recordApproval } = await import('./approval-service.js');
     const pending = await params.store.loadPending();
     const match = pending.state.approvals.find((approval) => approval.approvalId === params.approvalId);
-    const host = match ? parseHostFromSummary(match.summary) : null;
-    if (params.scope === 'domain' && match && !host) {
+    const pendingHost = match ? parseHostFromSummary(match.summary) : null;
+    if (params.scope === 'domain' && match && !pendingHost) {
         return {
             ok: false,
             message: `Cannot add domain to egress allowlist: could not parse host from summary "${match.summary}".`,
@@ -112,16 +107,15 @@ export async function recordEgressApproval(params) {
         requireSignedToken: params.requireSignedToken ?? false,
         store: params.store,
     });
+    const host = result.approval ? parseHostFromSummary(result.approval.summary) : pendingHost;
     if (!result.ok || params.scope !== 'domain' || !host) {
         return { ok: result.ok, message: result.message };
     }
-    const allowlist = await loadEgressAllowlist(params.store.allowlistPath);
-    const updated = addDomainToAllowlist(allowlist, {
+    await mutateEgressAllowlist(params.store.allowlistPath, (allowlist) => addDomainToAllowlist(allowlist, {
         host,
         approvedAt: new Date().toISOString(),
         approvalId: params.approvalId,
-    });
-    await saveEgressAllowlist(params.store.allowlistPath, updated);
+    }));
     return {
         ok: true,
         message: `${result.message} Domain ${host} added to egress allowlist.`,

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

@@ -31,6 +31,8 @@ export interface GateVerdict extends GatePermissionResponse {
     axes?: ClassifyResult['axes'];
     capabilityRequests?: ClassifyResult['capabilityRequests'];
     authorizationDecision?: ClassifyResult['authorizationDecision'];
+    effectPlan?: ClassifyResult['effectPlan'];
+    effectPlanPolicyDecisions?: ClassifyResult['effectPlanPolicyDecisions'];
     boundaryProfile?: string;
 }
 export declare function isGatedAction(value: unknown): value is GatedAction;

package/dist/core/gate-contract.js

@@ -28,6 +28,8 @@ export function classifyResultToGateVerdict(params) {
         axes: result.axes,
         capabilityRequests: result.capabilityRequests,
         authorizationDecision: result.authorizationDecision,
+        effectPlan: result.effectPlan,
+        effectPlanPolicyDecisions: result.effectPlanPolicyDecisions,
         boundaryProfile: result.boundaryProfile,
     };
 }

package/dist/core/gate-engine.js

@@ -4,6 +4,7 @@ import { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload, } from
 import { classifySubagent } from './classify-subagent.js';
 import { classifyToolUse } from './classify-tool.js';
 import { classifierOptionsFromConfig } from './config.js';
+import { buildCapabilityEffectPlan } from './effect-ir/build.js';
 import { GATE_CONTRACT_VERSION } from './gate-contract.js';
 import { mergeAgentAssessment } from './judgment.js';
 import { classifyShell } from './verdict/adapter.js';
@@ -200,7 +201,7 @@ function applyToolSandboxPolicies(action, result, options) {
 export async function classifyGatedAction(action, config, extraOptions = {}) {
     const limitResult = checkGatedActionLimits(action);
     if (limitResult) {
-        return limitResult;
+        return attachEffectPlan(action, limitResult);
     }
     const options = { ...classifierOptionsFromConfig(config), ...extraOptions };
     if (action.kind === 'shell') {
@@ -212,36 +213,52 @@ export async function classifyGatedAction(action, config, extraOptions = {}) {
         result = applySandboxOutsideBoundary(command, action, result, options);
         result = applyShellPeripheralPolicy(command, action, result, options);
         if (!action.agentAssessment) {
-            return result;
+            return attachEffectPlan(action, result);
         }
         const merged = mergeAgentAssessment(result.assessment, action.agentAssessment);
         if (!merged.mismatch) {
-            return { ...result, assessment: merged.assessment };
+            return attachEffectPlan(action, { ...result, assessment: merged.assessment });
         }
-        return {
+        return attachEffectPlan(action, {
             ...result,
             verdict: 'deny_pending_approval',
             reason: 'agent_assessment_mismatch',
             assessment: merged.assessment,
-        };
+        });
     }
     if (action.kind === 'subagent') {
-        return classifySubagent(action.payload ?? {}, action.repoRoot, options, config);
+        return attachEffectPlan(action, classifySubagent(action.payload ?? {}, action.repoRoot, options, config));
     }
     let result = await classifyToolUse(action.payload ?? {}, action.repoRoot, action.cwd, config, options);
     result = applyToolSandboxPolicies(action, result, options);
     if (!action.agentAssessment) {
-        return result;
+        return attachEffectPlan(action, result);
     }
     const merged = mergeAgentAssessment(result.assessment, action.agentAssessment);
     if (!merged.mismatch) {
-        return { ...result, assessment: merged.assessment };
+        return attachEffectPlan(action, { ...result, assessment: merged.assessment });
     }
-    return {
+    return attachEffectPlan(action, {
         ...result,
         verdict: 'deny_pending_approval',
         reason: 'agent_assessment_mismatch',
         assessment: merged.assessment,
+    });
+}
+function attachEffectPlan(action, result) {
+    if (result.effectPlan) {
+        return result;
+    }
+    const summary = result.normalizedCommand ?? result.summary ?? action.command ?? action.kind;
+    return {
+        ...result,
+        effectPlan: buildCapabilityEffectPlan({
+            actionKind: action.kind,
+            summary,
+            inputFingerprint: result.fingerprint,
+            requests: result.capabilityRequests ?? [],
+            effectFree: result.reason === 'read_only',
+        }),
     };
 }
 export async function classifyGatedActionAsync(action, config, extraOptions = {}) {

package/dist/core/index.d.ts

@@ -3,7 +3,7 @@ export type { ApprovalReplayHint, ReplayActionContext, ReplayAdapterId, } from '
 /** @deprecated Use `buildRetryInstructionForConfig` */
 export { approvalFlow, buildApprovalRecordedMessage, buildReplayEnvelopeFields, buildReplayHint, buildRetryInstructionForConfig, buildRetryInstructionForConfig as buildRetryInstruction, canAutoReplay, getExecutionLeaseMs, replayShellCommand, validateReplayEnvelope, } from './approval-replay.js';
 export type { ApprovalStore } from './approval-service.js';
-export { consumeApprovedAfterCliReplay, createGateApprovalStore, gateApprovalStoreFromDeps, recordApproval, } from './approval-service.js';
+export { claimApprovedForReplay, consumeApprovedAfterCliReplay, createGateApprovalStore, gateApprovalStoreFromDeps, recordApproval, } from './approval-service.js';
 export type { AuditMetricsReport } from './audit-metrics.js';
 export { computeAuditMetrics, parseAuditNdjson } from './audit-metrics.js';
 export { classifySubagent } from './classify-subagent.js';
@@ -16,6 +16,8 @@ export { classifyResultToGateVerdict, GATE_CONTRACT_VERSION, isGatedAction, unno
 export { classifyGatedAction, GateNormalizationError, gateEnabledForAction, normalizeGatedAction, } from './gate-engine.js';
 export { matchesSensitivePath } from './glob.js';
 export { canonicalPath, hasOutsideRepoPath, normalizeToken, pathWithinRoot, relativeWithinRepo, resolveMutationTarget, } from './path-utils.js';
+export type { RecoveryBackend, RecoveryCheckpointEntry, RecoveryCheckpointEntryV1, RecoveryCheckpointEntryV2, RecoveryCheckpointManifest, RecoveryCheckpointManifestV1, RecoveryCheckpointManifestV2, RecoveryCheckpointState, RecoveryCheckpointSummary, RecoveryFileSnapshotV1, RecoveryFileSnapshotV2, RecoveryProofV1, RecoveryReceiptV1, } from './recovery/index.js';
+export { listRecoveryCheckpoints, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_CHECKPOINT_QUOTA, RECOVERY_RESTORE_CONFLICT, recoveryCheckpointStorageBytes, recoveryRestoreBinding, restoreRecoveryCheckpoint, showRecoveryCheckpoint, } from './recovery/index.js';
 export { fingerprintReplayPayload, subagentFingerprintSource } from './replay-scrub.js';
 export { scrubString, scrubValue } from './scrub.js';
 export { findCommandSubstitutions, MAX_SUBSTITUTION_DEPTH } from './shell-substitution.js';

package/dist/core/index.js

@@ -1,7 +1,7 @@
 export { APPROVAL_EXECUTION_LEASE_MS, approvalCommandMatch, compactApprovals, createApprovalRecord, createApprovalRecordWithEnvelope, isExecutionLeaseExpired, isExpired, mergeApprovalStates, nowIso, } from './approval.js';
 /** @deprecated Use `buildRetryInstructionForConfig` */
 export { approvalFlow, buildApprovalRecordedMessage, buildReplayEnvelopeFields, buildReplayHint, buildRetryInstructionForConfig, buildRetryInstructionForConfig as buildRetryInstruction, canAutoReplay, getExecutionLeaseMs, replayShellCommand, validateReplayEnvelope, } from './approval-replay.js';
-export { consumeApprovedAfterCliReplay, createGateApprovalStore, gateApprovalStoreFromDeps, recordApproval, } from './approval-service.js';
+export { claimApprovedForReplay, consumeApprovedAfterCliReplay, createGateApprovalStore, gateApprovalStoreFromDeps, recordApproval, } from './approval-service.js';
 export { computeAuditMetrics, parseAuditNdjson } from './audit-metrics.js';
 export { classifySubagent } from './classify-subagent.js';
 export { classifyToolUse } from './classify-tool.js';
@@ -12,6 +12,7 @@ export { classifyResultToGateVerdict, GATE_CONTRACT_VERSION, isGatedAction, unno
 export { classifyGatedAction, GateNormalizationError, gateEnabledForAction, normalizeGatedAction, } from './gate-engine.js';
 export { matchesSensitivePath } from './glob.js';
 export { canonicalPath, hasOutsideRepoPath, normalizeToken, pathWithinRoot, relativeWithinRepo, resolveMutationTarget, } from './path-utils.js';
+export { listRecoveryCheckpoints, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_CHECKPOINT_QUOTA, RECOVERY_RESTORE_CONFLICT, recoveryCheckpointStorageBytes, recoveryRestoreBinding, restoreRecoveryCheckpoint, showRecoveryCheckpoint, } from './recovery/index.js';
 export { fingerprintReplayPayload, subagentFingerprintSource } from './replay-scrub.js';
 export { scrubString, scrubValue } from './scrub.js';
 export { findCommandSubstitutions, MAX_SUBSTITUTION_DEPTH } from './shell-substitution.js';

package/dist/core/judge-cloud-consent.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { loadApprovalState, saveApprovalState } from '../config-io.js';
+import { loadApprovalState, pendingApprovalsPath, saveApprovalState } from '../config-io.js';
 import { compactApprovals, createApprovalRecord } from './approval.js';
+import { mutateApprovalStateWithRetry } from './capability/approval-state-mutation.js';
 import { JUDGE_CLOUD_CONSENT_REASON } from './capability/reasons.js';
 export { JUDGE_CLOUD_CONSENT_REASON };
 export function judgeCloudConsentFingerprint(providerId, endpoint) {
@@ -10,18 +11,8 @@ export async function ensurePendingJudgeCloudConsentApproval(params) {
     const { repoRoot, config, providerId, endpoint } = params;
     const normalizedEndpoint = endpoint.trim();
     const fingerprint = judgeCloudConsentFingerprint(providerId, normalizedEndpoint);
-    const pending = await loadApprovalState(repoRoot, 'pending-approvals.json', config);
-    const compacted = compactApprovals(pending);
-    const existing = compacted.approvals.find((approval) => approval.kind === 'capability' &&
-        approval.reason === JUDGE_CLOUD_CONSENT_REASON &&
-        approval.fingerprint === fingerprint &&
-        approval.repoRoot === repoRoot);
-    if (existing) {
-        await saveApprovalState(repoRoot, 'pending-approvals.json', compacted, config);
-        return { approvalId: existing.approvalId, created: false };
-    }
     const approvalId = `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`;
-    const approval = createApprovalRecord({
+    const candidate = createApprovalRecord({
         kind: 'capability',
         fingerprint,
         repoRoot,
@@ -32,7 +23,30 @@ export async function ensurePendingJudgeCloudConsentApproval(params) {
         input: `belay judge use ${providerId} --endpoint ${normalizedEndpoint}`,
         inputKind: 'shell',
     });
-    compacted.approvals.push(approval);
-    await saveApprovalState(repoRoot, 'pending-approvals.json', compacted, config);
-    return { approvalId, created: true };
+    const outcome = await mutateApprovalStateWithRetry({
+        load: async () => ({
+            filePath: pendingApprovalsPath(repoRoot, config),
+            state: await loadApprovalState(repoRoot, 'pending-approvals.json', config),
+        }),
+        write: async (_filePath, state) => saveApprovalState(repoRoot, 'pending-approvals.json', state, config),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const existing = compacted.approvals.find((approval) => approval.kind === 'capability' &&
+                approval.reason === JUDGE_CLOUD_CONSENT_REASON &&
+                approval.fingerprint === fingerprint &&
+                approval.repoRoot === repoRoot);
+            if (existing) {
+                return {
+                    state: compacted,
+                    result: { approvalId: existing.approvalId, created: false },
+                };
+            }
+            compacted.approvals.push(candidate);
+            return { state: compacted, result: { approvalId, created: true } };
+        },
+    });
+    if (!outcome) {
+        throw new Error('Failed to persist cloud judge consent approval');
+    }
+    return outcome;
 }

package/dist/core/network-endpoint.d.ts

@@ -0,0 +1,10 @@
+export interface NetworkEndpoint {
+    host: string;
+    port?: number;
+    protocol: string;
+}
+export interface NetworkEndpointParseOptions {
+    allowHostedGitShorthand?: boolean;
+    allowScpStyle?: boolean;
+}
+export declare function parseNetworkEndpoint(spec: string, options?: NetworkEndpointParseOptions): NetworkEndpoint | null;

package/dist/core/network-endpoint.js

@@ -0,0 +1,51 @@
+const SUPPORTED_URL_PROTOCOLS = new Set(['http:', 'https:', 'ssh:', 'git:']);
+const NON_NETWORK_COLON_PREFIXES = new Set([
+    'catalog',
+    'exec',
+    'file',
+    'link',
+    'npm',
+    'patch',
+    'portal',
+    'workspace',
+]);
+const HOSTED_GIT_PREFIXES = {
+    bitbucket: 'bitbucket.org',
+    github: 'github.com',
+    gitlab: 'gitlab.com',
+};
+export function parseNetworkEndpoint(spec, options = {}) {
+    const normalized = spec.trim().replace(/^git\+/, '');
+    if (options.allowHostedGitShorthand) {
+        const hostedGit = normalized.match(/^([a-z]+):(.+)$/i);
+        const hostedGitHost = hostedGit?.[1]
+            ? HOSTED_GIT_PREFIXES[hostedGit[1].toLowerCase()]
+            : undefined;
+        if (hostedGitHost && hostedGit?.[2]) {
+            return { host: hostedGitHost, protocol: 'git' };
+        }
+    }
+    try {
+        const url = new URL(normalized);
+        if (SUPPORTED_URL_PROTOCOLS.has(url.protocol) && url.hostname) {
+            return {
+                host: url.hostname,
+                ...(url.port ? { port: Number(url.port) } : {}),
+                protocol: url.protocol.slice(0, -1),
+            };
+        }
+    }
+    catch { }
+    if (!options.allowScpStyle || /^[A-Za-z]:[\\/]/.test(normalized)) {
+        return null;
+    }
+    const scpStyle = normalized.match(/^(?:([^@/\s:]+)@)?([^:/\s]+):(.+)$/);
+    if (!scpStyle) {
+        return null;
+    }
+    const [, , host, remotePath] = scpStyle;
+    if (!host || !remotePath || NON_NETWORK_COLON_PREFIXES.has(host.toLowerCase())) {
+        return null;
+    }
+    return { host: host.toLowerCase(), protocol: 'ssh' };
+}

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

@@ -0,0 +1,10 @@
+import { type SpawnOptionsWithoutStdio } from 'node:child_process';
+export interface ShellRunResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    stdout?: string;
+    stderr?: string;
+}
+export declare function windowsProcessTreeKillArgs(pid: number): string[];
+export declare function runProcessWithBoundedOutput(file: string, args: string[], options: SpawnOptionsWithoutStdio, timeoutMs: number): Promise<ShellRunResult>;

package/dist/core/process-runner.js

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+const PROCESS_OUTPUT_TAIL_BYTES = 16_384;
+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;
+}
+export function windowsProcessTreeKillArgs(pid) {
+    return ['/pid', String(pid), '/t', '/f'];
+}
+function forceKillWindowsProcessTree(pid, fallback) {
+    return new Promise((resolve) => {
+        const taskkill = spawn('taskkill', windowsProcessTreeKillArgs(pid), {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        let settled = false;
+        const finish = (succeeded) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            if (!succeeded) {
+                fallback();
+            }
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            taskkill.kill();
+            finish(false);
+        }, WINDOWS_TASKKILL_TIMEOUT_MS);
+        taskkill.on('error', () => finish(false));
+        taskkill.on('close', (code) => finish(code === 0));
+    });
+}
+export function runProcessWithBoundedOutput(file, args, options, timeoutMs) {
+    return new Promise((resolve) => {
+        const detached = process.platform !== 'win32';
+        const child = spawn(file, args, {
+            ...options,
+            detached,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let timedOut = false;
+        let settled = false;
+        let windowsCleanupPending = false;
+        let exitTimer;
+        child.stdout.on('data', (chunk) => {
+            stdout = appendOutputTail(stdout, chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr = appendOutputTail(stderr, chunk);
+        });
+        const finish = (exitCode, signal) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeoutTimer);
+            if (exitTimer) {
+                clearTimeout(exitTimer);
+            }
+            child.stdout.destroy();
+            child.stderr.destroy();
+            resolve({
+                exitCode,
+                signal: signal ? String(signal) : null,
+                timedOut,
+                stdout: stdout.toString('utf8'),
+                stderr: stderr.toString('utf8'),
+            });
+        };
+        const kill = (signal) => {
+            try {
+                if (detached && child.pid) {
+                    process.kill(-child.pid, signal);
+                    return;
+                }
+                child.kill(signal);
+            }
+            catch {
+                // The process may already have exited between the state check and kill.
+            }
+        };
+        const timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            if (process.platform === 'win32' && child.pid) {
+                windowsCleanupPending = true;
+                void forceKillWindowsProcessTree(child.pid, () => child.kill('SIGKILL')).then(() => {
+                    windowsCleanupPending = false;
+                    finish(child.exitCode, child.signalCode ?? 'SIGKILL');
+                });
+                return;
+            }
+            kill('SIGTERM');
+            setTimeout(() => {
+                kill('SIGKILL');
+                finish(null, 'SIGKILL');
+            }, TIMEOUT_KILL_GRACE_MS);
+        }, timeoutMs);
+        child.on('error', (error) => {
+            stderr = appendOutputTail(stderr, error.message);
+            finish(1, null);
+        });
+        child.on('exit', (exitCode, signal) => {
+            clearTimeout(timeoutTimer);
+            if (windowsCleanupPending) {
+                return;
+            }
+            exitTimer = setTimeout(() => finish(exitCode, signal), EXIT_OUTPUT_GRACE_MS);
+        });
+        child.on('close', (exitCode, signal) => {
+            if (windowsCleanupPending) {
+                return;
+            }
+            finish(exitCode, signal);
+        });
+    });
+}

package/dist/core/recover-advice.js

@@ -1,5 +1,6 @@
 export const RECOVER_DISCLAIMER = [
-    'Advisory only — belay does not run recovery commands.',
+    'Advisory only — this report is not proof that the selected action executed. Only a checkpoint receipt shown by `belay recover list` is an executable recovery point.',
+    '`belay recover advice` does not run recovery commands; checkpoint restore requires a separate one-shot human approval.',
     'Advice is based on what belay observed through hooks; actions outside hook scope may not be visible.',
     'Recovery commands themselves pass through belay hooks — destructive undo steps may be blocked again.',
 ];

package/dist/core/recovery/artifact-store.d.ts

@@ -0,0 +1,29 @@
+import type { RecoveryCheckpointManifest, RecoveryCheckpointState, RecoveryCheckpointStateV1, RecoveryReceiptV1 } from './types.js';
+export declare const RECOVERY_CHECKPOINT_CORRUPT = "recovery_checkpoint_corrupt";
+export interface PreparedRecoveryCheckpoint {
+    checkpointId: string;
+    manifest: RecoveryCheckpointManifest;
+    manifestHash: string;
+    proofHash: string;
+}
+export interface RecoveryArtifact {
+    artifactDir: string;
+    manifest: RecoveryCheckpointManifest;
+    state: RecoveryCheckpointStateV1;
+    manifestHash: string;
+    receipt?: RecoveryReceiptV1;
+}
+export declare function checkpointsRoot(stateDir: string): string;
+export declare function checkpointDir(stateDir: string, checkpointId: string): string;
+export declare function fsyncPath(filePath: string): Promise<void>;
+export declare function atomicWriteJson(filePath: string, value: unknown): Promise<void>;
+export declare function writeRecoveryState(artifactDir: string, state: RecoveryCheckpointState, manifestHash: string, detail?: string): Promise<void>;
+export declare function directorySize(root: string): Promise<number>;
+export declare function readRecoveryArtifact(stateDir: string, checkpointId: string): Promise<RecoveryArtifact>;
+export declare function ensureRecoveryReceipt(artifactDir: string, manifest: RecoveryCheckpointManifest, manifestHash: string): Promise<RecoveryReceiptV1>;
+export declare function checkpointIds(stateDir: string): Promise<string[]>;
+export declare function artifactRepoRoot(stateDir: string, checkpointId: string): Promise<string | null>;
+export declare function checkpointIdsForRepo(stateDir: string, repoRoot: string): Promise<string[]>;
+export declare function cleanupOrphanedStaging(stateDir: string): Promise<void>;
+export declare function markRecoveryCheckpointApplying(stateDir: string, checkpoint: PreparedRecoveryCheckpoint): Promise<void>;
+export declare function markRecoveryCheckpointApplied(stateDir: string, checkpoint: PreparedRecoveryCheckpoint): Promise<RecoveryReceiptV1>;