@guilz-dev/belay 0.6.0 → 0.7.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';
@@ -290,6 +294,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 +348,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 +370,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/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;