@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/cli.js

@@ -10,8 +10,10 @@ 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';
 import { formatSimulateReport, simulateProject } from './commands/simulate.js';
 import { revokeStandingAllow } from './commands/standing-allow.js';
 import { formatStatusReport, statusProject } from './commands/status.js';
@@ -381,7 +383,13 @@ function parseArgs(argv) {
             return { command: 'help', options };
         }
         if (token === '--') {
-            options.explainCommand = rest.slice(index + 1).join(' ');
+            const remainder = rest.slice(index + 1).join(' ');
+            if (command === 'session' && options.sessionSubcommand === 'start') {
+                options.sessionAgentCommand = remainder;
+            }
+            else {
+                options.explainCommand = remainder;
+            }
             break;
         }
         if (command === 'audit' && !options.auditSubcommand) {
@@ -405,6 +413,13 @@ function parseArgs(argv) {
             }
             throw new Error('sandbox requires subcommand: status');
         }
+        if (command === 'session' && !options.sessionSubcommand) {
+            if (token === 'start' || token === 'status') {
+                options.sessionSubcommand = token;
+                continue;
+            }
+            throw new Error('session requires subcommand: start or status');
+        }
         if (command === 'standing-allow' && !options.standingAllowSubcommand) {
             if (token === 'revoke') {
                 options.standingAllowSubcommand = token;
@@ -419,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' ||
@@ -513,14 +545,18 @@ 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]
   ${c} explain [--target <dir>] [--cwd <dir>] [--kind shell|tool|subagent] [--tool <name>] [--payload-json <json>] [--command <text>] [--json] [-- <command>]
   ${c} egress <start|stop|status|env> [--target <dir>] [--json]
   ${c} sandbox status [--target <dir>] [--json]
+  ${c} session <start|status> [--target <dir>] [--json]
+  ${c} session start [--target <dir>] [-- <agent command>]
   ${c} judge <status|list|use|test|bench|consent> [--target <dir>] [--json]
   ${c} judge test [--target <dir>] [--json] [--live-probe]
   ${c} judge use <ollama|codex|claude|cursor> [--model <id>] [--endpoint <url>] [--timeout <ms>] [--accept-cloud] [--cloud-consent-approval-id <id>] [--credential project|apiKey] [--key-stdin] [--key-env <NAME>]
@@ -809,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,
@@ -907,6 +959,32 @@ async function main() {
             process.exitCode = report.issues.length > 0 && report.sandboxEnabled ? 1 : 0;
             return;
         }
+        if (command === 'session') {
+            if (!options.sessionSubcommand) {
+                throw new Error('session requires subcommand: start or status');
+            }
+            if (options.sessionSubcommand === 'start') {
+                const result = await sessionStartProject({
+                    targetDir: options.targetDir,
+                    agentCommand: options.sessionAgentCommand,
+                });
+                process.stdout.write(`${result.message}\n`);
+                process.exitCode = result.ok ? 0 : 1;
+                return;
+            }
+            const report = await sessionStatusProject({
+                targetDir: options.targetDir,
+                json: options.json,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`${formatSessionStatusReport(report)}\n`);
+            }
+            process.exitCode = report.ok ? 0 : 1;
+            return;
+        }
         if (command === 'approve') {
             if (!options.approvalId) {
                 throw new Error('approve requires an approval ID.');

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/classify-for-report.js

@@ -36,7 +36,7 @@ export async function classifyForReport(params) {
         if (!params.command && !params.payload) {
             throw new Error('classify-for-report requires command or payload for subagent classification.');
         }
-        result = classifySubagent(payload, repoRoot, classifierOptions);
+        result = classifySubagent(payload, repoRoot, classifierOptions, config);
         input = params.command ?? JSON.stringify(payload);
     }
     else if (kind === 'tool') {

package/dist/commands/config.d.ts

@@ -1,5 +1,6 @@
 import { type JudgeProviderId } from '../core/verdict/judge-catalog.js';
 import type { AdapterName, InitOptions } from '../types.js';
+import { type SelectOptions } from './tui.js';
 export declare const BELAY_CONFIG_SUBCOMMANDS: readonly ["list", "get", "set", "unset", "credential", "judge"];
 export type BelayConfigSubcommand = (typeof BELAY_CONFIG_SUBCOMMANDS)[number];
 export interface BelayConfigOptions {
@@ -39,6 +40,13 @@ export interface BelayConfigInteractiveOptions {
     /** Suppress the interactive header when nested under runBelayConfigInteractive */
     skipBanner?: boolean;
 }
+export declare const JUDGE_CREDENTIAL_MODE_PROMPT = "Judge API key source";
+export declare const JUDGE_CREDENTIAL_STORE_KEY_PROMPT = "Paste API key to store locally (visible input; prefer belay config credential set --key-stdin): ";
+export declare const JUDGE_TRANSPORT_MODE_PROMPT = "How should Belay reach the judge?";
+export declare const JUDGE_HTTP_ENDPOINT_PROMPT = "Judge HTTP API URL:";
+export type JudgeTransportWizardMode = 'cli' | 'http';
+export declare function buildJudgeTransportSelectOptions(judgeProviderId: JudgeProviderId): SelectOptions<JudgeTransportWizardMode>;
+export declare function buildJudgeCredentialModeSelectOptions(judgeProviderId: JudgeProviderId): SelectOptions<'project' | 'apiKey'>;
 export declare function resolveBelayConfigInteractiveMode(repoRoot: string): Promise<'full' | 'judge-only'>;
 export declare function runBelayConfigFullInteractive(options?: BelayConfigInteractiveOptions): Promise<{
     repoRoot: string;

package/dist/commands/config.js

@@ -8,8 +8,9 @@ import { clearJudgeCredentialStore, writeJudgeCredentialStore } from '../core/cr
 import { refreshIntegrityIfPinned } from '../core/integrity.js';
 import { defaultJudgeProviderForAdapter, hasValidCloudConsent, isCloudJudgeConfig, resolveJudgeUsePatch, } from '../core/judge-config.js';
 import { rejectDeprecatedJudgeModelAuto } from '../core/judge-model-policy.js';
-import { resolveJudgeTransport } from '../core/judge-runtime-detection.js';
-import { isJudgeProviderId, JUDGE_PROVIDER_IDS, normalizeLegacyProviderId, } from '../core/verdict/judge-catalog.js';
+import { detectJudgeRuntimeCapabilities, resolveJudgeTransport, } from '../core/judge-runtime-detection.js';
+import { getJudgeProviderSpec, isJudgeProviderId, JUDGE_PROVIDER_IDS, normalizeLegacyProviderId, } from '../core/verdict/judge-catalog.js';
+import { normalizeJudgeRuntimeConfig } from '../core/verdict/judge-runtime-config.js';
 import { initProject } from '../installer.js';
 import { isBelayFloorInstalled } from './health-snapshot.js';
 import { judgeStatus } from './judge.js';
@@ -31,6 +32,8 @@ const JUDGE_CONFIG_PATHS = [
     'judge.timeoutMs',
     'judge.credential.mode',
     'judge.credential.ref',
+    'judge.runtime.session.enabled',
+    'judge.runtime.shadow.enabled',
 ];
 export function parseAdapter(value) {
     const normalized = (value?.trim() || 'cursor').toLowerCase();
@@ -98,6 +101,12 @@ function getJudgeField(judge, pathKey) {
         return judge.credential?.mode ?? null;
     if (pathKey === 'judge.credential.ref')
         return judge.credential?.ref ?? null;
+    if (pathKey === 'judge.runtime.session.enabled') {
+        return normalizeJudgeRuntimeConfig(judge.runtime).session.enabled;
+    }
+    if (pathKey === 'judge.runtime.shadow.enabled') {
+        return normalizeJudgeRuntimeConfig(judge.runtime).shadow.enabled;
+    }
     throw new Error(`Unknown judge config path: ${pathKey}`);
 }
 function listJudgeFields(judge) {
@@ -181,6 +190,36 @@ async function applyJudgeSet(repoRoot, config, pathKey, rawValue) {
         await persistJudge(repoRoot, config, judge, adapter);
         return judge;
     }
+    if (pathKey === 'judge.runtime.session.enabled') {
+        if (value !== 'true' && value !== 'false') {
+            throw new Error('judge.runtime.session.enabled must be true or false.');
+        }
+        const runtime = normalizeJudgeRuntimeConfig(config.judge.runtime);
+        const judge = normalizeJudgeConfig({
+            ...config.judge,
+            runtime: {
+                ...runtime,
+                session: { ...runtime.session, enabled: value === 'true' },
+            },
+        });
+        await persistJudge(repoRoot, config, judge, adapter);
+        return judge;
+    }
+    if (pathKey === 'judge.runtime.shadow.enabled') {
+        if (value !== 'true' && value !== 'false') {
+            throw new Error('judge.runtime.shadow.enabled must be true or false.');
+        }
+        const runtime = normalizeJudgeRuntimeConfig(config.judge.runtime);
+        const judge = normalizeJudgeConfig({
+            ...config.judge,
+            runtime: {
+                ...runtime,
+                shadow: { ...runtime.shadow, enabled: value === 'true' },
+            },
+        });
+        await persistJudge(repoRoot, config, judge, adapter);
+        return judge;
+    }
     throw new Error(`Unknown judge config path: ${pathKey}`);
 }
 async function applyJudgeUnset(repoRoot, config, pathKey) {
@@ -289,7 +328,75 @@ export async function runBelayConfigCredential(options) {
     }
     throw new Error('credential requires action: mode, set, or clear.');
 }
+export const JUDGE_CREDENTIAL_MODE_PROMPT = 'Judge API key source';
+export const JUDGE_CREDENTIAL_STORE_KEY_PROMPT = 'Paste API key to store locally (visible input; prefer belay config credential set --key-stdin): ';
+export const JUDGE_TRANSPORT_MODE_PROMPT = 'How should Belay reach the judge?';
+export const JUDGE_HTTP_ENDPOINT_PROMPT = 'Judge HTTP API URL:';
+const CLOUD_CLI_LABELS = {
+    codex: 'Codex CLI',
+    claude: 'Claude CLI',
+    cursor: 'Cursor CLI',
+};
+export function buildJudgeTransportSelectOptions(judgeProviderId) {
+    const cliLabel = CLOUD_CLI_LABELS[judgeProviderId];
+    const runtime = detectJudgeRuntimeCapabilities(judgeProviderId);
+    const cliHint = runtime.cliTransport
+        ? 'Uses your logged-in host session; no URL needed.'
+        : 'Host CLI not found on PATH — install it or choose custom HTTP API.';
+    return {
+        message: JUDGE_TRANSPORT_MODE_PROMPT,
+        defaultValue: 'cli',
+        choices: [
+            {
+                value: 'cli',
+                label: `Use ${cliLabel} (recommended)`,
+                hint: cliHint,
+            },
+            {
+                value: 'http',
+                label: 'Custom HTTP API endpoint',
+                hint: 'Requires a provider API URL and cloud egress consent.',
+            },
+        ],
+    };
+}
+export function buildJudgeCredentialModeSelectOptions(judgeProviderId) {
+    const spec = getJudgeProviderSpec(judgeProviderId);
+    const providerEnvVars = spec?.apiKeyEnvVars.filter((name) => name !== 'BELAY_JUDGE_API_KEY') ?? [];
+    const envNames = providerEnvVars.length > 0
+        ? ['BELAY_JUDGE_API_KEY', ...providerEnvVars].join(', ')
+        : 'BELAY_JUDGE_API_KEY';
+    const projectHint = providerEnvVars.length > 0
+        ? `Uses ${envNames} from the shell; does not read .env files. Or host CLI login when available.`
+        : 'Uses BELAY_JUDGE_API_KEY from the shell; does not read .env files.';
+    return {
+        message: JUDGE_CREDENTIAL_MODE_PROMPT,
+        defaultValue: 'project',
+        choices: [
+            {
+                value: 'project',
+                label: 'Environment variables or host CLI',
+                hint: projectHint,
+            },
+            {
+                value: 'apiKey',
+                label: 'Store in Belay credential store',
+                hint: 'Saved to credentials.json (mode 0600) on the next step.',
+            },
+        ],
+    };
+}
 function formatSelectPrompt(options) {
+    const hasDetails = options.choices.some((choice) => choice.hint || choice.label);
+    if (hasDetails) {
+        const lines = options.choices.map((choice) => {
+            const label = choice.label ?? choice.value;
+            const hint = choice.hint ? ` — ${choice.hint}` : '';
+            return `  ${choice.value}: ${label}${hint}`;
+        });
+        const values = options.choices.map((choice) => choice.value).join(' | ');
+        return `${options.message}\n${lines.join('\n')}\n[${values}] (${options.defaultValue}): `;
+    }
     const values = options.choices.map((choice) => choice.value).join(' | ');
     return `${options.message} [${values}] (${options.defaultValue}): `;
 }
@@ -374,20 +481,36 @@ function writeConfigWizardBanner(options, title) {
     }
     output.write(`${title}\n`);
 }
+async function askJudgeHttpEndpoint(prompter) {
+    while (true) {
+        const endpoint = (await prompter.askText(JUDGE_HTTP_ENDPOINT_PROMPT)).trim();
+        if (endpoint) {
+            return endpoint;
+        }
+        process.stderr.write('Warning: HTTP endpoint URL is required when using custom HTTP API. Paste a URL or re-run belay config and choose host CLI.\n');
+    }
+}
+async function askJudgeCredentialStoreKey(prompter) {
+    while (true) {
+        const key = (await prompter.askText(JUDGE_CREDENTIAL_STORE_KEY_PROMPT)).trim();
+        if (key) {
+            return key;
+        }
+        process.stderr.write('Warning: API key cannot be empty. Paste a key or re-run belay config and choose environment variables.\n');
+    }
+}
 async function collectCloudJudgeWizardAnswers(prompter, judgeProviderId) {
     if (judgeProviderId === 'ollama') {
         return { acceptCloud: false };
     }
-    const judgeCredentialMode = (await prompter.askConfirm('Use project env for credentials?', true))
-        ? 'project'
-        : 'apiKey';
-    const optionalEndpoint = (await prompter.askText('Judge endpoint URL (optional): ')).trim();
-    const judgeEndpoint = optionalEndpoint || undefined;
+    const judgeCredentialMode = await prompter.askSelect(buildJudgeCredentialModeSelectOptions(judgeProviderId));
+    const transportMode = await prompter.askSelect(buildJudgeTransportSelectOptions(judgeProviderId));
+    let judgeEndpoint;
+    if (transportMode === 'http') {
+        judgeEndpoint = await askJudgeHttpEndpoint(prompter);
+    }
     if (judgeCredentialMode === 'apiKey') {
-        const key = await prompter.askText('Paste API key (hidden input not available in all shells): ');
-        if (key.trim()) {
-            process.env.BELAY_CONFIG_WIZARD_JUDGE_KEY = key.trim();
-        }
+        process.env.BELAY_CONFIG_WIZARD_JUDGE_KEY = await askJudgeCredentialStoreKey(prompter);
     }
     let acceptCloud = false;
     if (judgeEndpoint) {

package/dist/commands/doctor.js

@@ -7,10 +7,17 @@ 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';
 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,7 +85,9 @@ export async function doctorProject(options = {}) {
             if (loadedConfig.version !== 4) {
                 warnings.push(`Config version is ${loadedConfig.version}; expected 4. Run belay upgrade to migrate.`);
             }
-            const judgeDoctor = await diagnoseJudge(loadedConfig);
+            const transport = resolveJudgeTransport(loadedConfig.judge);
+            const shouldProbe = transport.endsWith('-cli');
+            const judgeDoctor = await diagnoseJudge(loadedConfig, repoRoot, { liveProbe: shouldProbe });
             issues.push(...judgeDoctor.issues);
             warnings.push(...judgeDoctor.warnings);
             notes.push(...judgeDoctor.notes);
@@ -285,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}).`);
@@ -294,6 +342,44 @@ export async function doctorProject(options = {}) {
             for (const issue of sandbox.issues) {
                 warnings.push(issue);
             }
+            for (const advisory of sandbox.advisories) {
+                warnings.push(advisory);
+            }
+        }
+        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);
+            if (attestationFormat === 'legacy') {
+                warnings.push('Boundary attestation uses an unsigned legacy format. Run belay session start to re-sign it.');
+            }
+            else if (attestationFormat === 'invalid') {
+                warnings.push('Boundary attestation file is present but invalid. Run belay session start to regenerate it.');
+            }
+        }
+        if (boundaryDriver === 'container') {
+            const session = await boundarySessionStatus({ repoRoot, config: loadedConfig });
+            if (!session.attestation) {
+                warnings.push('Container boundary driver is configured but no attestation was found. Run belay session start.');
+            }
+            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.');
+            }
+            else if (session.attestation.probeSignals.includes('repo-mount-rw')) {
+                notes.push('Container boundary mounts the working directory read-write (repo-mount-rw). Policy grants scope widening; paths outside the mount are not container-enforced.');
+            }
         }
         if (loadedConfig.egress.enabled) {
             const egress = await egressStatus({ targetDir: repoRoot });

package/dist/commands/explain.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { loadApprovalState, loadConfigFile } from '../config-io.js';
 import { compactApprovals } from '../core/approval.js';
+import { extractJudgeFallbackReason, formatJudgeRecoveryHint, inferProviderIdFromFallbackReason, isJudgeInfrastructureFailure, } from '../core/judge-fallback-hints.js';
 import { classifyForReport } from './classify-for-report.js';
 export async function explainCommand(options) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
@@ -134,5 +135,14 @@ export function formatExplainReport(report) {
             ? 'Observed assessment: measured in an isolated git worktree at gate time. Observed-safe commands are applied once and the hook denies re-execution (transactional_already_applied).'
             : 'Observed assessment: not applicable (transactional path not eligible).',
     ];
-    return `${lines.join('\n')}\n`;
+    const recoveryLines = [];
+    if (isJudgeInfrastructureFailure(result)) {
+        const fallbackReason = extractJudgeFallbackReason(result);
+        const providerId = inferProviderIdFromFallbackReason(fallbackReason);
+        const recoveryHint = formatJudgeRecoveryHint(providerId, fallbackReason);
+        if (recoveryHint) {
+            recoveryLines.push('', 'Recovery:', `  ${recoveryHint}`, '  Then verify: belay judge test --live-probe');
+        }
+    }
+    return `${[...lines, ...recoveryLines].join('\n')}\n`;
 }

package/dist/commands/judge.js

@@ -63,10 +63,11 @@ export async function judgeStatus(options = {}) {
     });
     const { resolved } = resolveJudgeModel(judge);
     const transport = resolveJudgeTransport(judge);
+    const effectiveTransport = transport === 'cursor-cli' && judge.runtime?.session.enabled ? 'cursor-acp' : transport;
     const lines = [
         `Judge providerId : ${judge.providerId ?? '(inferred)'}`,
         `Judge driver     : ${judge.provider}`,
-        `Transport        : ${transport}`,
+        `Transport        : ${effectiveTransport}`,
         `Endpoint         : ${judge.endpoint ?? '(none)'}`,
         `Model            : ${resolved} (requested: ${judge.model})`,
         `Credential       : ${credential.mode} (${credential.sourceKind})${credential.source ? ` → ${credential.source}` : ''} ${credential.key ? '✓ set' : '✗ missing'}`,
@@ -82,7 +83,7 @@ export async function judgeStatus(options = {}) {
             endpoint: judge.endpoint,
             model: judge.model,
             modelResolved: resolved,
-            transport,
+            transport: effectiveTransport,
             credential,
             cloudConsent: judge.cloudConsent ?? null,
             cloudJudgeActive: isCloudJudgeConfig(judge) && hasValidCloudConsent(judge),