@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/commands/config.js

@@ -8,11 +8,14 @@ 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 { 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';
 import { readKeyFromStdin } from './stdin-key.js';
+import { confirmPrompt, intro, isInteractiveTTY, selectPrompt } from './tui.js';
 export const BELAY_CONFIG_SUBCOMMANDS = [
     'list',
     'get',
@@ -29,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();
@@ -96,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) {
@@ -106,7 +117,9 @@ function listJudgeFields(judge) {
     return entries;
 }
 function warnCloudConsentIfNeeded(judge) {
-    if (isCloudJudgeConfig(judge) && !hasValidCloudConsent(judge)) {
+    if (isCloudJudgeConfig(judge) &&
+        resolveJudgeTransport(judge) === 'http' &&
+        !hasValidCloudConsent(judge)) {
         process.stderr.write('Warning: Cloud judge saved without recorded consent. Tier1 cloud judge will fail closed until consent is granted (belay judge consent + belay approve, or TTY --accept-cloud-judge).\n');
     }
 }
@@ -177,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) {
@@ -285,46 +328,196 @@ export async function runBelayConfigCredential(options) {
     }
     throw new Error('credential requires action: mode, set, or clear.');
 }
-async function collectCloudJudgeWizardAnswers(ask, judgeProviderId) {
-    if (judgeProviderId === 'ollama') {
-        return { acceptCloud: false };
+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 judgeCredentialMode = parseYesNo(await ask('Use project env for credentials? [y=project | n=apiKey] (y): '), true)
-        ? 'project'
-        : 'apiKey';
-    const optionalEndpoint = (await ask('Judge endpoint URL (optional): ')).trim();
-    const judgeEndpoint = optionalEndpoint || undefined;
-    if (judgeCredentialMode === 'apiKey') {
-        const key = await ask('Paste API key (hidden input not available in all shells): ');
-        if (key.trim()) {
-            process.env.BELAY_CONFIG_WIZARD_JUDGE_KEY = key.trim();
+    const values = options.choices.map((choice) => choice.value).join(' | ');
+    return `${options.message} [${values}] (${options.defaultValue}): `;
+}
+function formatConfirmPrompt(message, defaultValue) {
+    return `${message} [y | n] (${defaultValue ? 'y' : 'n'}): `;
+}
+function parseSelectAnswer(raw, options) {
+    const normalized = raw.trim().toLowerCase();
+    if (!normalized) {
+        return options.defaultValue;
+    }
+    const found = options.choices.find((choice) => {
+        if (choice.value.toLowerCase() === normalized) {
+            return true;
         }
+        return choice.label?.trim().toLowerCase() === normalized;
+    });
+    if (!found) {
+        throw new Error(`Invalid choice for ${options.message}: ${raw}`);
     }
-    let acceptCloud = false;
-    if (judgeEndpoint) {
-        acceptCloud = parseYesNo(await ask('Accept cloud judge egress (redacted commands leave the repo)? [y | n] (n): '), false);
-    }
-    return { judgeCredentialMode, judgeEndpoint, acceptCloud };
+    return found.value;
 }
-async function withConfigPrompter(fn, prompts) {
-    if (prompts) {
-        let index = 0;
-        const ask = async (message) => {
-            if (index >= prompts.length) {
-                throw new Error(`unexpected config prompt: ${message}`);
-            }
-            return prompts[index++];
-        };
-        return fn(ask);
-    }
+async function askTextLazy(message) {
     const rl = readline.createInterface({ input, output });
     try {
-        return await fn((message) => rl.question(message));
+        return (await rl.question(message)).trimEnd();
     }
     finally {
         rl.close();
     }
 }
+function createTestPrompter(prompts) {
+    let index = 0;
+    const nextPrompt = (message) => {
+        if (index >= prompts.length) {
+            throw new Error(`unexpected config prompt: ${message}`);
+        }
+        return prompts[index++];
+    };
+    return {
+        askText: async (message) => nextPrompt(message),
+        askSelect: async (options, parseRaw) => {
+            const raw = nextPrompt(formatSelectPrompt(options));
+            return parseRaw ? parseRaw(raw, options) : parseSelectAnswer(raw, options);
+        },
+        askConfirm: async (message, defaultValue) => parseYesNo(nextPrompt(formatConfirmPrompt(message, defaultValue)), defaultValue),
+    };
+}
+function createReadlinePrompter() {
+    return {
+        askText: askTextLazy,
+        askSelect: async (options, parseRaw) => {
+            const raw = await askTextLazy(formatSelectPrompt(options));
+            return parseRaw ? parseRaw(raw, options) : parseSelectAnswer(raw, options);
+        },
+        askConfirm: async (message, defaultValue) => parseYesNo(await askTextLazy(formatConfirmPrompt(message, defaultValue)), defaultValue),
+    };
+}
+function createTuiPrompter() {
+    return {
+        askText: askTextLazy,
+        askSelect: selectPrompt,
+        askConfirm: confirmPrompt,
+    };
+}
+async function withConfigWizardPrompter(options, fn) {
+    if (options.prompts) {
+        return fn(createTestPrompter(options.prompts));
+    }
+    if (isInteractiveTTY()) {
+        return fn(createTuiPrompter());
+    }
+    return fn(createReadlinePrompter());
+}
+function writeConfigWizardBanner(options, title) {
+    if (options.skipBanner) {
+        return;
+    }
+    if (isInteractiveTTY()) {
+        intro(title);
+        return;
+    }
+    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.askSelect(buildJudgeCredentialModeSelectOptions(judgeProviderId));
+    const transportMode = await prompter.askSelect(buildJudgeTransportSelectOptions(judgeProviderId));
+    let judgeEndpoint;
+    if (transportMode === 'http') {
+        judgeEndpoint = await askJudgeHttpEndpoint(prompter);
+    }
+    if (judgeCredentialMode === 'apiKey') {
+        process.env.BELAY_CONFIG_WIZARD_JUDGE_KEY = await askJudgeCredentialStoreKey(prompter);
+    }
+    let acceptCloud = false;
+    if (judgeEndpoint) {
+        acceptCloud = await prompter.askConfirm('Accept cloud judge egress (redacted commands leave the repo)?', false);
+    }
+    return { judgeCredentialMode, judgeEndpoint, acceptCloud };
+}
 export async function resolveBelayConfigInteractiveMode(repoRoot) {
     try {
         return (await isBelayFloorInstalled({ targetDir: repoRoot })) ? 'judge-only' : 'full';
@@ -333,16 +526,26 @@ export async function resolveBelayConfigInteractiveMode(repoRoot) {
         return 'full';
     }
 }
-async function runBelayConfigFullWithPrompter(ask, options) {
-    if (!options.skipBanner) {
-        output.write('belay config\n');
-    }
-    const adapter = parseAdapter(await ask('Adapter [cursor | claude | codex] (cursor): '));
-    const scope = parseScope(await ask('Install scope [project | global] (project): '));
-    const withSkill = parseYesNo(await ask('Install SKILL.md and slash commands? [y | n] (y): '), true);
+async function runBelayConfigFullWithWizard(prompter, options) {
+    writeConfigWizardBanner(options, 'belay config');
+    const adapter = await prompter.askSelect({
+        message: 'Adapter',
+        defaultValue: 'cursor',
+        choices: [{ value: 'cursor' }, { value: 'claude' }, { value: 'codex' }],
+    });
+    const scope = await prompter.askSelect({
+        message: 'Install scope',
+        defaultValue: 'project',
+        choices: [{ value: 'project' }, { value: 'global' }],
+    });
+    const withSkill = await prompter.askConfirm('Install SKILL.md and slash commands?', true);
     const defaultJudgeProviderId = defaultJudgeProviderForAdapter(adapter);
-    const judgeProviderId = parseJudgeProviderId(await ask(`Judge provider [${JUDGE_PROVIDER_IDS.join(' | ')}] (${defaultJudgeProviderId}): `), defaultJudgeProviderId);
-    const { judgeCredentialMode, judgeEndpoint, acceptCloud } = await collectCloudJudgeWizardAnswers(ask, judgeProviderId);
+    const judgeProviderId = await prompter.askSelect({
+        message: 'Judge provider',
+        defaultValue: defaultJudgeProviderId,
+        choices: JUDGE_PROVIDER_IDS.map((providerId) => ({ value: providerId })),
+    }, (raw, selectOptions) => parseJudgeProviderId(raw, selectOptions.defaultValue));
+    const { judgeCredentialMode, judgeEndpoint, acceptCloud } = await collectCloudJudgeWizardAnswers(prompter, judgeProviderId);
     const initOptions = buildInitOptionsFromConfigAnswers({
         adapter,
         scope,
@@ -362,19 +565,22 @@ async function runBelayConfigFullWithPrompter(ask, options) {
     }
     return result;
 }
-async function runBelayConfigJudgeOnlyWithPrompter(ask, options, repoRoot, config, adapter) {
-    if (!options.skipBanner) {
-        output.write('belay config (judge only)\n');
-    }
+async function runBelayConfigJudgeOnlyWithWizard(prompter, options, repoRoot, config, adapter) {
+    writeConfigWizardBanner(options, 'belay config (judge only)');
     const defaultJudgeProviderId = defaultJudgeProviderForAdapter(adapter);
-    const judgeProviderId = parseJudgeProviderId(await ask(`Judge provider [${JUDGE_PROVIDER_IDS.join(' | ')}] (${defaultJudgeProviderId}): `), defaultJudgeProviderId);
-    const { judgeCredentialMode, judgeEndpoint, acceptCloud } = await collectCloudJudgeWizardAnswers(ask, judgeProviderId);
+    const judgeProviderId = await prompter.askSelect({
+        message: 'Judge provider',
+        defaultValue: defaultJudgeProviderId,
+        choices: JUDGE_PROVIDER_IDS.map((providerId) => ({ value: providerId })),
+    }, (raw, selectOptions) => parseJudgeProviderId(raw, selectOptions.defaultValue));
+    const { judgeCredentialMode, judgeEndpoint, acceptCloud } = await collectCloudJudgeWizardAnswers(prompter, judgeProviderId);
     const patch = resolveJudgeUsePatch(config.judge, {
         providerId: judgeProviderId,
         endpoint: judgeEndpoint,
         credentialMode: judgeCredentialMode,
         acceptCloud: acceptCloud && Boolean(judgeEndpoint),
-        interactiveTTY: true,
+        // `prompts` is a scripted stand-in for interactive responses in tests.
+        interactiveTTY: isInteractiveTTY() || Boolean(options.prompts),
         interactiveConsentApproved: acceptCloud && Boolean(judgeEndpoint),
     });
     if (patch.errors.length > 0) {
@@ -399,13 +605,13 @@ async function runBelayConfigJudgeOnlyWithPrompter(ask, options, repoRoot, confi
     return { repoRoot, adapter };
 }
 export async function runBelayConfigFullInteractive(options = {}) {
-    return withConfigPrompter((ask) => runBelayConfigFullWithPrompter(ask, options), options.prompts);
+    return withConfigWizardPrompter(options, (prompter) => runBelayConfigFullWithWizard(prompter, options));
 }
 export async function runBelayConfigJudgeOnlyInteractive(options = {}) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
     const config = await loadConfigFile(repoRoot);
     const adapter = resolveAdapterName(config);
-    return withConfigPrompter((ask) => runBelayConfigJudgeOnlyWithPrompter(ask, options, repoRoot, config, adapter), options.prompts);
+    return withConfigWizardPrompter(options, (prompter) => runBelayConfigJudgeOnlyWithWizard(prompter, options, repoRoot, config, adapter));
 }
 export async function runBelayConfigInteractive(options = {}) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
@@ -427,16 +633,16 @@ export async function runBelayConfigInteractive(options = {}) {
                 skipBanner: true,
             });
         }
-        return withConfigPrompter(async (ask) => {
-            output.write('belay config\n');
-            const judgeOnly = parseYesNo(await ask('Configure judge only? [Y/n]: '), true);
-            if (judgeOnly) {
-                const config = await loadConfigFile(repoRoot);
-                const adapter = resolveAdapterName(config);
-                return runBelayConfigJudgeOnlyWithPrompter(ask, { ...options, skipBanner: true }, repoRoot, config, adapter);
+        return withConfigWizardPrompter(options, async (prompter) => {
+            writeConfigWizardBanner(options, 'belay config');
+            const judgeOnly = await prompter.askConfirm('Configure judge only?', true);
+            if (!judgeOnly) {
+                return runBelayConfigFullWithWizard(prompter, { ...options, skipBanner: true });
             }
-            return runBelayConfigFullWithPrompter(ask, { ...options, skipBanner: true });
-        }, options.prompts);
+            const config = await loadConfigFile(repoRoot);
+            const adapter = resolveAdapterName(config);
+            return runBelayConfigJudgeOnlyWithWizard(prompter, { ...options, skipBanner: true }, repoRoot, config, adapter);
+        });
     }
     return runBelayConfigFullInteractive(options);
 }

package/dist/commands/doctor.js

@@ -8,9 +8,12 @@ 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 { 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 } from '../core/judge-doctor.js';
+import { diagnoseJudge, stopJudgeSessionBrokers } from '../core/judge-doctor.js';
+import { resolveJudgeTransport } from '../core/judge-runtime-detection.js';
 import { getManagedHookEntries } from '../defaults.js';
 import { resolveNodeBinary } from '../node-resolution.js';
 import { egressStatus } from '../services/egress-service.js';
@@ -78,7 +81,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);
@@ -239,6 +244,16 @@ export async function doctorProject(options = {}) {
         else {
             notes.push('No orphan approval cleanup actions were needed.');
         }
+        const judgeStateDir = belayStateDir(loadedConfig, repoLocalDir);
+        if (options.dryRun !== true) {
+            const stoppedBrokers = await stopJudgeSessionBrokers(repoRoot, judgeStateDir);
+            if (stoppedBrokers > 0) {
+                notes.push(`Stopped judge session broker artifacts for ${repoRoot}.`);
+            }
+        }
+        else {
+            notes.push('Dry run: would stop judge session broker and clear kill switch if present.');
+        }
     }
     let dogfood = null;
     if (loadedConfig) {
@@ -284,6 +299,36 @@ 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.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 (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());
@@ -11,11 +12,16 @@ export async function explainCommand(options) {
             const latest = [...pending.approvals].sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))[0];
             const inputKind = latest.inputKind ??
                 (latest.kind === 'egress' || latest.kind === 'capability' ? 'shell' : latest.kind);
+            const payload = latest.payloadJson !== undefined
+                ? JSON.parse(latest.payloadJson)
+                : undefined;
             const classified = await classifyForReport({
                 targetDir: repoRoot,
-                cwd: options.cwd,
+                cwd: latest.cwd ?? options.cwd,
                 kind: inputKind,
                 command: latest.input ?? latest.summary,
+                toolName: latest.toolName,
+                payload,
             });
             return {
                 repoRoot: classified.repoRoot,
@@ -129,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/harvest.d.ts

@@ -0,0 +1,29 @@
+import type { AuditRecord } from '../core/audit-types.js';
+import { type HarvestReport, type HarvestReviewOutcome } from '../core/harvest.js';
+export interface HarvestListOptions {
+    targetDir?: string;
+    since?: string;
+    until?: string;
+    json?: boolean;
+}
+export interface HarvestApplyOptions {
+    targetDir?: string;
+    command: string;
+    outcome: HarvestReviewOutcome;
+    reason?: string;
+    corpusPath?: string;
+}
+export declare function harvestListProject(options?: HarvestListOptions): Promise<HarvestReport>;
+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<{
+    ok: boolean;
+    message: string;
+    corpusPath: string;
+}>;
+/** Parse audit ndjson for tests without full project layout. */
+export declare function harvestReportFromNdjson(raw: string): HarvestReport;

package/dist/commands/harvest.js

@@ -0,0 +1,72 @@
+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';
+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 });
+}
+export function formatHarvestReport(report) {
+    const lines = [
+        `belay harvest (scope: ${report.scope} audit traces only)`,
+        `Schema: v${report.schemaVersion}`,
+        '',
+        `Benign candidates (${report.candidates.length}):`,
+    ];
+    if (report.candidates.length === 0) {
+        lines.push('- (none)');
+    }
+    else {
+        for (const candidate of report.candidates) {
+            lines.push(`- ${JSON.stringify(candidate.command)} [${candidate.sources.join(', ')}] asks=${candidate.askCount} approved=${candidate.approvedAfterDeny ? 'yes' : 'no'} fp=${candidate.fingerprint.slice(0, 12)}…`);
+        }
+    }
+    lines.push('', `Availability queue (${report.availabilityQueue.length}):`);
+    if (report.availabilityQueue.length === 0) {
+        lines.push('- (none)');
+    }
+    else {
+        for (const entry of report.availabilityQueue) {
+            lines.push(`- ${JSON.stringify(entry.command)} signal=${entry.availabilitySignal} asks=${entry.askCount} (${entry.reason})`);
+        }
+    }
+    lines.push('', 'Candidates are review-only signals — approve in audit does not auto-promote to corpus.', 'Time filters (--since/--until) keep paired deny/approval rows for round-trip detection.', 'Use: belay harvest apply --command "<text>" --outcome provably-benign|accepted-benign|reject');
+    return lines.join('\n');
+}
+export async function harvestApplyProject(options) {
+    const repoRoot = path.resolve(options.targetDir ?? process.cwd());
+    const corpusPath = path.resolve(repoRoot, options.corpusPath ?? path.join('corpus', 'shell-commands.json'));
+    const raw = await readFile(corpusPath, 'utf8');
+    const cases = parseCorpusCases(JSON.parse(raw));
+    const result = applyHarvestReview(cases, {
+        command: options.command,
+        outcome: options.outcome,
+        reason: options.reason,
+    });
+    if (result.applied) {
+        await writeFile(corpusPath, `${JSON.stringify(result.cases, null, 2)}\n`, 'utf8');
+    }
+    return {
+        ok: result.ok,
+        message: result.message,
+        corpusPath: path.relative(repoRoot, corpusPath) || corpusPath,
+    };
+}
+/** Parse audit ndjson for tests without full project layout. */
+export function harvestReportFromNdjson(raw) {
+    const records = parseAuditNdjson(raw).map((entry) => toAuditRecord(entry));
+    return harvestReportFromRecords(records);
+}