@guilz-dev/belay 0.6.0 → 0.8.0

package/dist/cli.js

@@ -10,6 +10,7 @@ import { formatHarvestReport, harvestApplyProject, harvestListProject } from './
 import { formatMetricsReport, metricsProject } from './commands/metrics.js';
 import { formatQualityReport, qualityCheck } from './commands/quality.js';
 import { formatRecoverReport, recoverProject } from './commands/recover.js';
+import { formatRecoveryCheckpointResult, recoveryCheckpointCommand, } from './commands/recovery-checkpoints.js';
 import { formatReport, reportProject } from './commands/report.js';
 import { revokeApproval } from './commands/revoke.js';
 import { formatSessionStatusReport, sessionStartProject, sessionStatusProject, } from './commands/session.js';
@@ -433,6 +434,23 @@ function parseArgs(argv) {
             }
             throw new Error('harvest requires subcommand: list or apply');
         }
+        if (command === 'recover' && !options.recoverSubcommand) {
+            if (token === 'advice' ||
+                token === 'status' ||
+                token === 'list' ||
+                token === 'show' ||
+                token === 'apply') {
+                options.recoverSubcommand = token;
+                continue;
+            }
+            throw new Error('recover requires subcommand: advice, status, list, show, or apply');
+        }
+        if (command === 'recover' &&
+            (options.recoverSubcommand === 'show' || options.recoverSubcommand === 'apply') &&
+            !options.recoverCheckpointId) {
+            options.recoverCheckpointId = token;
+            continue;
+        }
         if (command === 'judge' && !options.judgeSubcommand) {
             if (token === 'status' ||
                 token === 'list' ||
@@ -527,8 +545,10 @@ Usage:
   ${c} metrics [--target <dir>] [--json]
   ${c} quality [--target <dir>] [--corpus <path>] [--json]
   ${c} report [--target <dir>] [--since <iso>] [--until <iso>] [--limit <n>] [--json]
-  ${c} recover [--target <dir>] [--since <iso>] [--fingerprint <fp>] [--command "<text>"] [--limit <n>] [--json]
+  ${c} recover [advice] [--target <dir>] [--since <iso>] [--fingerprint <fp>] [--command "<text>"] [--limit <n>] [--json]
     (--limit picks the Nth recover candidate after priority ranking: local_mutation first, then recency; 1 = highest priority, default 1)
+  ${c} recover <status|list> [--target <dir>] [--json]
+  ${c} recover <show|apply> <checkpoint-id> [--target <dir>] [--json]
   ${c} audit <query|summarize|replay> [--target <dir>] [--json] [--since <iso>] [--until <iso>] [--verdict <v>] [--reason <r>] [--kind <k>] [--fingerprint <fp>] [--event <e>] [--location <v>] [--opacity <v>] [--effect <v>] [--confidence <v>] [--limit <n>] [--config <path>]
   ${c} simulate --config <path> [--target <dir>] [--json]
   ${c} status [--target <dir>] [--json]
@@ -825,6 +845,22 @@ async function main() {
             throw new Error('harvest requires subcommand: list or apply');
         }
         if (command === 'recover') {
+            if (options.recoverSubcommand && options.recoverSubcommand !== 'advice') {
+                const result = await recoveryCheckpointCommand({
+                    targetDir: options.targetDir,
+                    subcommand: options.recoverSubcommand,
+                    checkpointId: options.recoverCheckpointId,
+                });
+                if (options.json) {
+                    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(formatRecoveryCheckpointResult(result));
+                }
+                if (!result.ok)
+                    process.exitCode = 2;
+                return;
+            }
             const report = await recoverProject({
                 targetDir: options.targetDir,
                 since: options.since,

package/dist/commands/approve.js

@@ -1,10 +1,12 @@
 import path from 'node:path';
 import { loadApprovalState, loadConfigFile } from '../config-io.js';
-import { canAutoReplay, getExecutionLeaseMs, replayShellCommand } from '../core/approval-replay.js';
-import { consumeApprovedAfterCliReplay, createGateApprovalStore, recordApproval, } from '../core/approval-service.js';
+import { canAutoReplay, getExecutionLeaseMs } from '../core/approval-replay.js';
+import { claimApprovedForReplay, createGateApprovalStore, recordApproval, } from '../core/approval-service.js';
+import { runBoundaryAgentCommand } from '../core/capability/boundary-session.js';
 import { JUDGE_CLOUD_CONSENT_REASON } from '../core/capability/reasons.js';
 import { recordCapabilityApproval } from '../core/capability-approval.js';
 import { recordEgressApproval } from '../core/egress-approval.js';
+import { RECOVERY_RESTORE_REASON } from '../core/recovery/checkpoint.js';
 import { createEgressApprovalStore } from '../services/egress-service.js';
 import { createCapabilityApprovalStore } from '../services/sandbox-service.js';
 export async function approvePending(options) {
@@ -12,6 +14,19 @@ export async function approvePending(options) {
     const config = await loadConfigFile(repoRoot);
     const pending = await loadApprovalState(repoRoot, 'pending-approvals.json', config);
     const match = pending.approvals.find((approval) => approval.approvalId === options.approvalId);
+    if (match?.reason === RECOVERY_RESTORE_REASON) {
+        if (options.scope && options.scope !== 'once') {
+            return { ok: false, message: 'Recovery restore approvals support one-shot scope only.' };
+        }
+        const result = await recordApproval({
+            approvalId: options.approvalId,
+            config,
+            token: options.token,
+            requireSignedToken: true,
+            store: createGateApprovalStore(repoRoot, config),
+        });
+        return { ok: result.ok, message: result.message };
+    }
     if (match?.reason === JUDGE_CLOUD_CONSENT_REASON) {
         const result = await recordCapabilityApproval({
             approvalId: options.approvalId,
@@ -73,22 +88,31 @@ export async function approvePending(options) {
                 message: 'CLI replay is only supported for shell approvals. Retry the original tool or subagent action manually.',
             };
         }
-        const replayResult = await replayShellCommand(approval.input, approval.cwd ?? repoRoot, getExecutionLeaseMs(config));
-        const output = [replayResult.stdout, replayResult.stderr].filter(Boolean).join('\n').trim();
+        const claimed = await claimApprovedForReplay({
+            approvalId: options.approvalId,
+            store: approvalStore,
+        });
+        if (!claimed) {
+            return { ok: false, message: 'Approval could not be claimed for replay.' };
+        }
+        const replayResult = await runBoundaryAgentCommand({
+            repoRoot,
+            config,
+            command: claimed.input ?? approval.input,
+            cwd: claimed.cwd ?? repoRoot,
+            timeoutMs: getExecutionLeaseMs(config),
+            runOptions: { mountReadOnly: false },
+        });
         if (replayResult.exitCode === 0) {
-            await consumeApprovedAfterCliReplay({
-                approvalId: options.approvalId,
-                store: approvalStore,
-            });
             return {
                 ok: true,
-                message: `Belay replay succeeded for ${options.approvalId}. Do not retry via hooks; the one-shot grant was consumed.${output ? `\n${output}` : ''}`,
+                message: `Belay replay succeeded for ${options.approvalId}. Do not retry via hooks; the one-shot grant was consumed.`,
             };
         }
         const timeoutNote = replayResult.timedOut ? ' Replay timed out.' : '';
         return {
             ok: false,
-            message: `Belay replay failed for ${options.approvalId} (exit ${replayResult.exitCode}).${timeoutNote} Approval remains active for one hook retry.${output ? `\n${output}` : ''}`,
+            message: `Belay replay failed for ${options.approvalId} (exit ${replayResult.exitCode}).${timeoutNote} The one-shot approval was consumed before replay and was not re-armed.`,
         };
     }
     return { ok: result.ok, message: result.message };

package/dist/commands/doctor.js

@@ -7,6 +7,7 @@ import { getAdapterLayout } from '../adapters/layouts/index.js';
 import { resolveScopedPaths } from '../adapters/layouts/scope.js';
 import { cleanupOrphanApprovalState } from '../cleanup-orphans.js';
 import { approvedApprovalsPath, belayStateDir, detectAdapterName, loadLayeredConfig, pendingApprovalsPath, repoLocalStateDirFor, } from '../config-io.js';
+import { approvalSigningKeyPath } from '../core/approval-token.js';
 import { detectFenceDrift, summarizeAuditVisibility } from '../core/audit-summary.js';
 import { inspectBoundaryAttestationFile } from '../core/capability/boundary-attestation-sign.js';
 import { boundaryAttestationPath, boundarySessionStatus, } from '../core/capability/boundary-session.js';
@@ -14,6 +15,9 @@ import { defaultControlPlaneDir } from '../core/config.js';
 import { verifyIntegrityManifest } from '../core/integrity.js';
 import { diagnoseJudge, stopJudgeSessionBrokers } from '../core/judge-doctor.js';
 import { resolveJudgeTransport } from '../core/judge-runtime-detection.js';
+import { listRecoveryCheckpoints } from '../core/recovery/checkpoint.js';
+import { recoveryApprovalSetupNotes, recoveryNotificationConfigured, recoveryNotificationSetupWarning, summarizeRecoveryCheckpointDiagnostics, } from '../core/recovery/operator-guidance.js';
+import { probeFileCloneStrategy } from '../core/transactional/file-clone.js';
 import { getManagedHookEntries } from '../defaults.js';
 import { resolveNodeBinary } from '../node-resolution.js';
 import { egressStatus } from '../services/egress-service.js';
@@ -78,6 +82,13 @@ export async function doctorProject(options = {}) {
             for (const entry of layered.provenance) {
                 notes.push(`Config layer [${entry.source}]: ${entry.path}`);
             }
+            const ignoredShellOverrideLists = [
+                ...(loadedConfig.overrides.allow.length > 0 ? ['overrides.allow'] : []),
+                ...(loadedConfig.overrides.external.length > 0 ? ['overrides.external'] : []),
+            ];
+            if (ignoredShellOverrideLists.length > 0) {
+                warnings.push(`Legacy shell ${ignoredShellOverrideLists.join(' and ')} ${ignoredShellOverrideLists.length === 1 ? 'is' : 'are'} deprecated and ignored. Remove the command list; inspect the EffectPlan and correct effect semantics or resource scope instead.`);
+            }
             if (loadedConfig.version !== 4) {
                 warnings.push(`Config version is ${loadedConfig.version}; expected 4. Run belay upgrade to migrate.`);
             }
@@ -290,6 +301,45 @@ export async function doctorProject(options = {}) {
                 warnings.push('Transactional execution is enabled but this directory is not a git repository. Transactional worktrees will be skipped until git is available.');
             }
         }
+        const fileCheckpoint = loadedConfig.policy.transactional.fileCheckpoint;
+        if (fileCheckpoint.enabled) {
+            const copyStrategy = await probeFileCloneStrategy();
+            notes.push(`File checkpoint: enabled (copyStrategy=${copyStrategy}, non-Git=${fileCheckpoint.allowNonGit}, maxFiles=${fileCheckpoint.maxFiles}, maxSourceBytes=${fileCheckpoint.maxSourceBytes}, maxWorkspaceBytes=${fileCheckpoint.maxWorkspaceBytes}, prepareTimeoutMs=${fileCheckpoint.prepareTimeoutMs}, copyConcurrency=${fileCheckpoint.copyConcurrency}).`);
+            if (!loadedConfig.policy.transactional.enabled) {
+                warnings.push('File checkpoint is enabled but transactional execution is disabled; dirty Git workspaces cannot use the backend.');
+            }
+            if (!loadedConfig.policy.transactional.checkpoint?.enabled) {
+                warnings.push('File checkpoint is enabled but durable Recovery checkpointing is disabled; backend selection will fail closed.');
+            }
+        }
+        if (loadedConfig.policy.transactional.checkpoint?.enabled) {
+            notes.push('Recovery checkpoint: enabled — repo-local pre-images are persisted before observed-safe transactional apply.');
+            notes.push(...recoveryApprovalSetupNotes());
+            if (!recoveryNotificationConfigured(loadedConfig)) {
+                warnings.push(recoveryNotificationSetupWarning());
+            }
+            const signingKeyPath = approvalSigningKeyPath(loadedConfig.controlPlane.enabled
+                ? belayStateDir(loadedConfig, repoLocalDir)
+                : (loadedConfig.controlPlane.configDir ?? defaultControlPlaneDir()));
+            if (!existsSync(signingKeyPath)) {
+                notes.push(`Approval signing key not yet created at ${signingKeyPath}; it will be generated on the first signed recovery approval request.`);
+            }
+            if (!loadedConfig.policy.transactional.enabled) {
+                warnings.push('Recovery checkpoint is enabled but transactional execution is disabled; checkpoints will not be created until transactional execution is enabled.');
+            }
+            try {
+                const stateDir = belayStateDir(loadedConfig, repoLocalDir);
+                const checkpoints = await listRecoveryCheckpoints(stateDir, repoRoot);
+                if (checkpoints.length > 0) {
+                    notes.push(`Recovery checkpoints in this repository: ${checkpoints.length}.`);
+                }
+                const advisories = summarizeRecoveryCheckpointDiagnostics(checkpoints);
+                warnings.push(...advisories);
+            }
+            catch {
+                // Checkpoint inspection is advisory only.
+            }
+        }
         if (loadedConfig.sandbox.enabled) {
             const sandbox = await sandboxStatus({ targetDir: repoRoot });
             notes.push(`Sandbox capability broker: enabled (runtime=${loadedConfig.sandbox.runtime}, fs-scope entries=${sandbox.fsScopeAllowlistCount}, full-isolation=${sandbox.l1FullActive}).`);
@@ -305,6 +355,10 @@ export async function doctorProject(options = {}) {
         }
         const boundaryDriver = loadedConfig.capability?.boundaryDriver ??
             (loadedConfig.sandbox.runtime === 'container' ? 'container' : null);
+        if (loadedConfig.policy.transactional.fileCheckpoint.enabled &&
+            boundaryDriver !== 'container') {
+            warnings.push('File checkpoint requires an attested workspace-isolating boundary driver; configure the container boundary and run belay session start.');
+        }
         if (loadedConfig.capability || boundaryDriver === 'container') {
             const attestationPath = boundaryAttestationPath(repoRoot, loadedConfig);
             const attestationFormat = await inspectBoundaryAttestationFile(attestationPath);
@@ -323,6 +377,10 @@ export async function doctorProject(options = {}) {
             else if (!session.fresh) {
                 warnings.push('Boundary attestation is stale or expired. Run belay session start to refresh.');
             }
+            else if (loadedConfig.policy.transactional.fileCheckpoint.enabled &&
+                session.attestation.isolatesWorkspaceMounts !== true) {
+                warnings.push('File checkpoint is enabled but the fresh boundary attestation does not prove workspace-mount isolation. Run belay session start with a compatible boundary.');
+            }
             else if (session.attestation.probeSignals.includes('repo-mount-ro-default')) {
                 notes.push('Container boundary defaults to read-only directory mounts; predicted writes use read-write mounts for the working directory only.');
             }

package/dist/commands/dogfood.js

@@ -45,7 +45,7 @@ async function promoteDogfoodToEnforce(repoRoot, configPath, force, adapter = 'c
             message: [
                 'Dogfood metrics do not recommend enforce yet.',
                 ...metrics.dogfood.notes,
-                'Re-run belay metrics, tune overrides.allow, or pass --force to override.',
+                'Re-run belay metrics, correct EffectPlan semantics or resource scope, or pass --force to override.',
             ].join(' '),
         };
     }

package/dist/commands/explain.js

@@ -106,8 +106,8 @@ export function formatExplainReport(report) {
         report.policy.transactional.enabled
             ? `Transactional band: [${report.policy.transactional.minConfidence}, ${report.policy.transactional.maxConfidence})`
             : 'Transactional band: not configured',
-        `Overrides allow: ${report.overrides.allow.join(', ') || '(none)'}`,
-        `Overrides external: ${report.overrides.external.join(', ') || '(none)'}`,
+        `Legacy overrides allow (deprecated, ignored): ${report.overrides.allow.join(', ') || '(none)'}`,
+        `Legacy overrides external (deprecated, ignored): ${report.overrides.external.join(', ') || '(none)'}`,
         '',
         `Verdict: ${result.verdict}`,
         `Reason: ${result.reason}`,

package/dist/commands/harvest.d.ts

@@ -17,7 +17,6 @@ export declare function harvestListProject(options?: HarvestListOptions): Promis
 export declare function harvestReportFromRecords(records: AuditRecord[], options?: {
     since?: string;
     until?: string;
-    allowPatterns?: string[];
 }): HarvestReport;
 export declare function formatHarvestReport(report: HarvestReport): string;
 export declare function harvestApplyProject(options: HarvestApplyOptions): Promise<{

package/dist/commands/harvest.js

@@ -1,6 +1,5 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { loadConfigFile } from '../config-io.js';
 import { parseAuditNdjson } from '../core/audit-metrics.js';
 import { toAuditRecord } from '../core/audit-query.js';
 import { applyHarvestReview, buildHarvestReport, filterRecordsForHarvest, } from '../core/harvest.js';
@@ -8,16 +7,14 @@ import { parseCorpusCases } from '../corpus/types.js';
 import { loadAuditRecords } from './audit.js';
 export async function harvestListProject(options = {}) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
-    const config = await loadConfigFile(repoRoot);
     const records = await loadAuditRecords(repoRoot);
     return harvestReportFromRecords(records, {
         since: options.since,
         until: options.until,
-        allowPatterns: config.overrides.allow,
     });
 }
 export function harvestReportFromRecords(records, options = {}) {
-    return buildHarvestReport(filterRecordsForHarvest(records, { since: options.since, until: options.until }), { allowPatterns: options.allowPatterns });
+    return buildHarvestReport(filterRecordsForHarvest(records, { since: options.since, until: options.until }));
 }
 export function formatHarvestReport(report) {
     const lines = [

package/dist/commands/metrics.js

@@ -38,6 +38,12 @@ export function formatMetricsReport(report) {
     if (report.approvalLatency.count > 0) {
         lines.push(`Approval latency: median ${report.approvalLatency.medianMs ?? 0}ms, p95 ${report.approvalLatency.p95Ms ?? 0}ms (${report.approvalLatency.count} samples)`);
     }
+    if (Object.keys(report.gateEventsByRuntime).length > 0) {
+        lines.push('', 'Gate events by runtime:');
+        for (const [runtime, count] of Object.entries(report.gateEventsByRuntime).sort((left, right) => right[1] - left[1])) {
+            lines.push(`- ${runtime}: ${count}`);
+        }
+    }
     if (report.bypassAttemptCount > 0) {
         lines.push(`Bypass attempts detected: ${report.bypassAttemptCount}`);
     }

package/dist/commands/quality.js

@@ -18,9 +18,7 @@ export async function qualityCheck(options = {}) {
         mode: config.mode,
         unknownLocalEffect: config.policy.unknownLocalEffect,
     });
-    const harvest = harvestReportFromRecords(auditRecords, {
-        allowPatterns: config.overrides.allow,
-    });
+    const harvest = harvestReportFromRecords(auditRecords);
     const notes = [
         'Overall ok reflects corpus hard gates only; audit and harvest signals are advisory.',
         'Recursive quality loop: corpus hard gates are the FN/FP safety boundary.',

package/dist/commands/recovery-checkpoints.d.ts

@@ -0,0 +1,164 @@
+export type RecoveryCheckpointSubcommand = 'status' | 'list' | 'show' | 'apply';
+export declare function recoveryCheckpointCommand(options: {
+    targetDir?: string;
+    subcommand: RecoveryCheckpointSubcommand;
+    checkpointId?: string;
+}): Promise<{
+    ok: boolean;
+    subcommand: string;
+    repoRoot: string;
+    backend: string;
+    availableBackends: string[];
+    backendCounts: {
+        [k: string]: number;
+    };
+    fileCheckpoint: {
+        enabled: boolean;
+        allowNonGit: boolean;
+        isolation: string | null;
+        copyStrategy: import("../core/transactional/file-clone.js").FileCloneStrategy | undefined;
+        probe: string;
+    };
+    enabled: boolean;
+    checkpointCount: number;
+    storageBytes: number;
+    recoverableCount: number;
+    needsManualRepairCount: number;
+    verifiedReceiptCount: number;
+    states: {
+        [k: string]: number;
+    };
+    advisories: string[];
+    limits: {
+        enabled: boolean;
+        appliedRetentionHours: number;
+        restoredRetentionHours: number;
+        maxCheckpoints: number;
+        maxBytes: number;
+    };
+    checkpoints?: undefined;
+    manifest?: undefined;
+    state?: undefined;
+    manifestHash?: undefined;
+    receipt?: undefined;
+    verdict?: undefined;
+    checkpointId?: undefined;
+    approvalId?: undefined;
+    paths?: undefined;
+    auditRecorded?: undefined;
+    message?: undefined;
+} | {
+    ok: boolean;
+    subcommand: string;
+    repoRoot: string;
+    checkpoints: import("../core/index.js").RecoveryCheckpointSummary[];
+    backend?: undefined;
+    availableBackends?: undefined;
+    backendCounts?: undefined;
+    fileCheckpoint?: undefined;
+    enabled?: undefined;
+    checkpointCount?: undefined;
+    storageBytes?: undefined;
+    recoverableCount?: undefined;
+    needsManualRepairCount?: undefined;
+    verifiedReceiptCount?: undefined;
+    states?: undefined;
+    advisories?: undefined;
+    limits?: undefined;
+    manifest?: undefined;
+    state?: undefined;
+    manifestHash?: undefined;
+    receipt?: undefined;
+    verdict?: undefined;
+    checkpointId?: undefined;
+    approvalId?: undefined;
+    paths?: undefined;
+    auditRecorded?: undefined;
+    message?: undefined;
+} | {
+    ok: boolean;
+    subcommand: string;
+    manifest: import("../core/index.js").RecoveryCheckpointManifest;
+    state: import("../core/recovery/types.js").RecoveryCheckpointStateV1;
+    manifestHash: string;
+    receipt: import("../core/index.js").RecoveryReceiptV1 | undefined;
+    repoRoot?: undefined;
+    backend?: undefined;
+    availableBackends?: undefined;
+    backendCounts?: undefined;
+    fileCheckpoint?: undefined;
+    enabled?: undefined;
+    checkpointCount?: undefined;
+    storageBytes?: undefined;
+    recoverableCount?: undefined;
+    needsManualRepairCount?: undefined;
+    verifiedReceiptCount?: undefined;
+    states?: undefined;
+    advisories?: undefined;
+    limits?: undefined;
+    checkpoints?: undefined;
+    verdict?: undefined;
+    checkpointId?: undefined;
+    approvalId?: undefined;
+    paths?: undefined;
+    auditRecorded?: undefined;
+    message?: undefined;
+} | {
+    ok: boolean;
+    subcommand: string;
+    verdict: string;
+    checkpointId: string;
+    approvalId: string;
+    manifestHash: string;
+    paths: string[];
+    auditRecorded: boolean;
+    message: string;
+    repoRoot?: undefined;
+    backend?: undefined;
+    availableBackends?: undefined;
+    backendCounts?: undefined;
+    fileCheckpoint?: undefined;
+    enabled?: undefined;
+    checkpointCount?: undefined;
+    storageBytes?: undefined;
+    recoverableCount?: undefined;
+    needsManualRepairCount?: undefined;
+    verifiedReceiptCount?: undefined;
+    states?: undefined;
+    advisories?: undefined;
+    limits?: undefined;
+    checkpoints?: undefined;
+    manifest?: undefined;
+    state?: undefined;
+    receipt?: undefined;
+} | {
+    auditRecorded: boolean;
+    message: string;
+    manifestHash: string;
+    changeCount: number;
+    ok: boolean;
+    subcommand: string;
+    verdict: string;
+    checkpointId: string;
+    repoRoot?: undefined;
+    backend?: undefined;
+    availableBackends?: undefined;
+    backendCounts?: undefined;
+    fileCheckpoint?: undefined;
+    enabled?: undefined;
+    checkpointCount?: undefined;
+    storageBytes?: undefined;
+    recoverableCount?: undefined;
+    needsManualRepairCount?: undefined;
+    verifiedReceiptCount?: undefined;
+    states?: undefined;
+    advisories?: undefined;
+    limits?: undefined;
+    checkpoints?: undefined;
+    manifest?: undefined;
+    state?: undefined;
+    receipt?: undefined;
+    approvalId?: undefined;
+    paths?: undefined;
+}>;
+export declare function formatRecoveryCheckpointResult(result: Record<string, unknown>): string;