@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/core/effect-ir/types.d.ts

@@ -0,0 +1,55 @@
+import type { CapabilityAction, CapabilityEvidenceLevel, CapabilityResource } from '../capability/request.js';
+import type { VerdictOpacity } from '../verdict/types.js';
+export declare const EFFECT_PLAN_VERSION: 1;
+export type EffectTag = 'fs.read' | 'fs.write' | 'process.exec' | 'network.connect' | 'network.acquire' | 'git.ref.write' | 'secret.read' | 'control_plane.write' | 'read_only' | 'indeterminate';
+export type LauncherPhase = 'invoke' | 'resolve' | 'acquire' | 'cache_read' | 'cache_write' | 'delegate';
+export type PackageExecLauncher = 'npx' | 'npm' | 'pnpm';
+export interface EffectEvidence {
+    level: CapabilityEvidenceLevel;
+    signals: readonly string[];
+    basis: readonly string[];
+}
+export interface EffectProvenance {
+    segment?: string;
+    launcher?: PackageExecLauncher;
+    phase?: LauncherPhase;
+    innerCommand?: string;
+    innerArgv?: readonly string[];
+}
+export interface EffectRequirement {
+    tag: EffectTag;
+    action: CapabilityAction;
+    resource: CapabilityResource;
+    evidence: EffectEvidence;
+    provenance: EffectProvenance;
+    /** All contributing sources after requirement de-duplication. */
+    provenances?: readonly EffectProvenance[];
+}
+export interface ExecEffectNode {
+    kind: 'exec';
+    commandRedacted: string;
+    segmentHead: string;
+    requirements: readonly EffectRequirement[];
+}
+export interface LauncherEffectNode {
+    kind: 'launcher';
+    launcher: PackageExecLauncher | 'npm' | 'pnpm' | 'make';
+    phase: LauncherPhase;
+    opaque: boolean;
+    reason: string;
+    children: readonly EffectNode[];
+}
+export interface MergeEffectNode {
+    kind: 'merge';
+    children: readonly EffectNode[];
+}
+export type EffectNode = ExecEffectNode | LauncherEffectNode | MergeEffectNode;
+export interface EffectPlan {
+    version: typeof EFFECT_PLAN_VERSION;
+    root: EffectNode;
+    inputFingerprint: string;
+    opacity: VerdictOpacity;
+    disposition: 'effects' | 'effect_free';
+    completeness: 'complete' | 'partial';
+    signals: readonly string[];
+}

package/dist/core/effect-ir/types.js

@@ -0,0 +1 @@
+export const EFFECT_PLAN_VERSION = 1;

package/dist/core/egress/allowlist.d.ts

@@ -3,5 +3,6 @@ import type { EgressAllowlistEntry, EgressAllowlistFile } from './types.js';
 export declare function egressAllowlistPath(config: BelayConfigV3, repoLocalStateDir: string): string;
 export declare function loadEgressAllowlist(filePath: string): Promise<EgressAllowlistFile>;
 export declare function saveEgressAllowlist(filePath: string, state: EgressAllowlistFile): Promise<void>;
+export declare function mutateEgressAllowlist(filePath: string, mutate: (state: EgressAllowlistFile) => EgressAllowlistFile): Promise<EgressAllowlistFile>;
 export declare function isHostAllowlisted(host: string, allowlist: EgressAllowlistFile): boolean;
 export declare function addDomainToAllowlist(allowlist: EgressAllowlistFile, entry: EgressAllowlistEntry): EgressAllowlistFile;

package/dist/core/egress/allowlist.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { withStateFileLock } from '../capability/approval-state-mutation.js';
 import { belayStateDir } from '../config.js';
 export function egressAllowlistPath(config, repoLocalStateDir) {
     return path.join(belayStateDir(config, repoLocalStateDir), 'egress-allowlist.json');
@@ -19,6 +20,13 @@ export async function saveEgressAllowlist(filePath, state) {
     await mkdir(path.dirname(filePath), { recursive: true });
     await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
 }
+export async function mutateEgressAllowlist(filePath, mutate) {
+    return withStateFileLock(filePath, async () => {
+        const updated = mutate(await loadEgressAllowlist(filePath));
+        await saveEgressAllowlist(filePath, updated);
+        return updated;
+    });
+}
 export function isHostAllowlisted(host, allowlist) {
     const normalized = host.toLowerCase();
     return allowlist.domains.some((entry) => entry.host.toLowerCase() === normalized);

package/dist/core/egress-approval.js

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

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

@@ -29,6 +29,11 @@ export interface GateVerdict extends GatePermissionResponse {
     wouldBlock: boolean;
     mode: 'enforce' | 'audit';
     axes?: ClassifyResult['axes'];
+    capabilityRequests?: ClassifyResult['capabilityRequests'];
+    authorizationDecision?: ClassifyResult['authorizationDecision'];
+    effectPlan?: ClassifyResult['effectPlan'];
+    effectPlanPolicyDecisions?: ClassifyResult['effectPlanPolicyDecisions'];
+    boundaryProfile?: string;
 }
 export declare function isGatedAction(value: unknown): value is GatedAction;
 export declare function classifyResultToGateVerdict(params: {

package/dist/core/gate-contract.js

@@ -26,6 +26,11 @@ export function classifyResultToGateVerdict(params) {
         user_message,
         agent_message,
         axes: result.axes,
+        capabilityRequests: result.capabilityRequests,
+        authorizationDecision: result.authorizationDecision,
+        effectPlan: result.effectPlan,
+        effectPlanPolicyDecisions: result.effectPlanPolicyDecisions,
+        boundaryProfile: result.boundaryProfile,
     };
 }
 export function unnormalizedGateVerdict(params) {

package/dist/core/gate-engine.js

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

package/dist/core/index.d.ts

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

package/dist/core/index.js

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

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

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

package/dist/core/judge-doctor.js

@@ -2,20 +2,30 @@ import { repoLocalStateDirFor } from '../config-io.js';
 import { normalizeJudgeProvider, scrubOptionsFromConfig } from './config.js';
 import { resolveJudgeCredential } from './judge-api-key.js';
 import { hasValidCloudConsent } from './judge-config.js';
+import { formatJudgeRecoveryHint, inferProviderIdFromFallbackReason, } from './judge-fallback-hints.js';
 import { discoverJudgeModels, modelPresenceFromDiscovery, } from './judge-model-discovery.js';
 import { detectJudgeRuntimeCapabilities, resolveJudgeTransport } from './judge-runtime-detection.js';
 import { createOllamaJudge, createOpenAiCompatibleJudge } from './verdict/judge.js';
 import { stopJudgeBrokerDaemon } from './verdict/judge-broker-service.js';
 import { getJudgeProviderCapabilities, getJudgeProviderSpec, isRemovedProviderId, normalizeLegacyProviderId, } from './verdict/judge-catalog.js';
 import { createJudgeFromConfig, resolveJudgeModel } from './verdict/judge-factory.js';
+import { resolveJudgeSmokeProbeTimeoutMs } from './verdict/judge-runtime-config.js';
 import { listRepoJudgeSessionBrokers, stopRepoJudgeSessionBroker, } from './verdict/judge-session-broker.js';
 import { clearJudgeSessionKillSwitch } from './verdict/judge-session-kill-switch.js';
+function judgeShadowAdvisory(warnings, message) {
+    warnings.push(`[judge shadow advisory] ${message}`);
+}
 export async function diagnoseJudge(config, repoRoot = process.cwd(), options = {}) {
     const shouldRunLiveProbe = options.liveProbe === true && !process.env.VITEST && !process.env.VITEST_WORKER_ID;
     const issues = [];
     const warnings = [];
     const notes = [];
     const judge = config.judge;
+    const gateMode = judge.mode ?? 'shadow';
+    notes.push(`Judge gate mode: ${gateMode} (sync Tier1 removed from hook gate; judge is shadow/async only)`);
+    if (gateMode === 'off') {
+        notes.push('Judge shadow is disabled (judge.mode=off).');
+    }
     const provider = normalizeJudgeProvider(judge.provider);
     const rawProviderId = judge.providerId ? String(judge.providerId) : undefined;
     if (rawProviderId && isRemovedProviderId(rawProviderId)) {
@@ -36,15 +46,19 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
     const capabilities = getJudgeProviderCapabilities(providerId);
     const transport = resolveJudgeTransport(judge);
     const runtime = detectJudgeRuntimeCapabilities(providerId);
+    const cursorAcpEnabled = transport === 'cursor-cli' &&
+        providerId === 'cursor' &&
+        config.judge.runtime?.session.enabled === true;
+    const effectiveTransport = cursorAcpEnabled ? 'cursor-acp' : transport;
     notes.push(`Judge providerId: ${providerId}`);
     notes.push(`Judge driver: ${provider}`);
     notes.push(`Judge model requested: ${judge.model}`);
-    notes.push(`Judge transport: ${transport}`);
+    notes.push(`Judge transport: ${effectiveTransport}`);
     if (config.policy.modelAssist.enabled) {
         warnings.push('policy.modelAssist is enabled but is not wired to v2 Tier1. Use top-level judge instead.');
     }
     if (capabilities?.requiresConsent && !hasValidCloudConsent(judge) && transport === 'http') {
-        issues.push('Cloud judge consent is not recorded. Tier1 cloud judge will fail closed until consent is granted.');
+        judgeShadowAdvisory(warnings, 'Cloud judge consent is not recorded. Shadow cloud judge will fail until consent is granted.');
     }
     else if (judge.cloudConsent?.accepted) {
         notes.push(`Cloud consent: accepted ${judge.cloudConsent.at} by ${judge.cloudConsent.by}`);
@@ -74,12 +88,12 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
     if (providerId === 'ollama') {
         notes.push(`Ollama endpoint: ${endpoint}`);
         if (discovery.modelIds.length === 0) {
-            issues.push(`Ollama endpoint unreachable or returned no models. Tier1 will fail closed.`);
+            judgeShadowAdvisory(warnings, 'Ollama endpoint unreachable or returned no models. Shadow judge will not run.');
         }
         else {
             const hasModel = modelCheck.status === 'found';
             if (!hasModel) {
-                issues.push(`Ollama model "${judge.model}" is not present. Pull it before enforce mode.`);
+                judgeShadowAdvisory(warnings, `Ollama model "${judge.model}" is not present. Pull it before enabling shadow comparisons.`);
             }
             else {
                 notes.push(`Ollama model "${judge.model}" is available.`);
@@ -103,7 +117,7 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
             context: { cwd: process.cwd(), repoRoot: process.cwd() },
         });
         if (warmResult.reason === 'ollama_unavailable' || warmResult.reason === 'ollama_parse_error') {
-            issues.push(`Ollama warm call failed: ${warmResult.reason}`);
+            judgeShadowAdvisory(warnings, `Ollama warm call failed: ${warmResult.reason}`);
         }
         else {
             notes.push('Ollama warm call succeeded.');
@@ -111,24 +125,29 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
         return { issues, warnings, notes, modelCheck };
     }
     if (transport === 'unavailable') {
-        issues.push('No judge transport is available (configure endpoint or install native CLI). Tier1 will fail closed to ask.');
+        judgeShadowAdvisory(warnings, 'No judge transport is available (configure endpoint or install native CLI). Shadow judge will not run.');
         return { issues, warnings, notes, modelCheck };
     }
     if (transport.endsWith('-cli')) {
         if (!runtime.cliTransport) {
-            issues.push(`Native CLI transport (${transport}) is not available. Tier1 judge will fail closed to ask.`);
+            judgeShadowAdvisory(warnings, `Native CLI transport (${transport}) is not available. Shadow judge will not run.`);
         }
         else if (!keyInfo.key && keyInfo.sourceKind !== 'host-session') {
-            issues.push('Judge API key is not set for the configured credential mode. Tier1 cloud judge will fail closed to ask.');
+            judgeShadowAdvisory(warnings, 'Judge API key is not set for the configured credential mode. Shadow cloud judge will not run.');
         }
         else {
-            notes.push(`Native CLI transport available: ${transport}`);
+            notes.push(cursorAcpEnabled
+                ? 'Cursor ACP transport available.'
+                : `Native CLI transport available: ${transport}`);
+            if (cursorAcpEnabled) {
+                notes.push(`Cursor ACP session transport enabled (max ${config.judge.runtime?.session.maxTurns ?? 'unknown'} turns).`);
+            }
             if (shouldRunLiveProbe) {
                 const smokeConfig = {
                     ...config,
                     judge: {
                         ...judge,
-                        timeoutMs: Math.min(judge.timeoutMs, 5000),
+                        timeoutMs: resolveJudgeSmokeProbeTimeoutMs(judge.timeoutMs),
                     },
                 };
                 const smokeJudge = createJudgeFromConfig(smokeConfig, { repoRoot });
@@ -140,10 +159,16 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
                     smokeJudge.lastTrace?.fallbackReason ??
                     smokeResult.reason;
                 if (smokeJudge.lastTrace?.provider === 'fallback') {
-                    issues.push(`Native CLI transport smoke probe failed (${smokeFallback}). Tier1 will fail closed to ask.`);
+                    const recoveryHint = formatJudgeRecoveryHint(inferProviderIdFromFallbackReason(smokeFallback, providerId), smokeFallback);
+                    const smokeLabel = cursorAcpEnabled ? 'Cursor ACP' : 'Native CLI transport';
+                    judgeShadowAdvisory(warnings, recoveryHint
+                        ? `${smokeLabel} smoke probe failed (${smokeFallback}). ${recoveryHint}`
+                        : `${smokeLabel} smoke probe failed (${smokeFallback}).`);
                 }
                 else {
-                    notes.push('Native CLI transport smoke probe succeeded.');
+                    notes.push(cursorAcpEnabled
+                        ? 'Cursor ACP smoke probe succeeded.'
+                        : 'Native CLI transport smoke probe succeeded.');
                 }
             }
         }
@@ -153,7 +178,7 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
         notes.push(`HTTP endpoint: ${judge.endpoint}`);
     }
     if (!keyInfo.key) {
-        issues.push('Judge API key is not set for the configured credential mode. Tier1 cloud judge will fail closed to ask.');
+        judgeShadowAdvisory(warnings, 'Judge API key is not set for the configured credential mode. Shadow cloud judge will not run.');
     }
     else {
         notes.push(`Credential source: ${keyInfo.source ?? keyInfo.sourceKind}`);
@@ -188,7 +213,7 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
         });
         if (dryRun.reason.startsWith('openai_compatible_') ||
             dryRun.reason === 'outbound_scrub_failed') {
-            issues.push(`HTTP judge dry-run failed: ${dryRun.reason}`);
+            judgeShadowAdvisory(warnings, `HTTP judge dry-run failed: ${dryRun.reason}`);
         }
         else {
             notes.push('HTTP judge dry-run succeeded.');

package/dist/core/judge-fallback-hints.d.ts

@@ -0,0 +1,13 @@
+import type { ClassifyResult } from './types.js';
+export declare function extractJudgeFallbackReason(result: Pick<ClassifyResult, 'axes' | 'assessment'>): string | undefined;
+export declare function isJudgeInfrastructureFailure(result: Pick<ClassifyResult, 'axes' | 'assessment' | 'reason'>): boolean;
+export declare function inferProviderIdFromFallbackReason(fallbackReason: string | undefined, fallbackProviderId?: string): string;
+export declare function formatJudgeRecoveryHint(providerId: string, fallbackReason?: string): string | null;
+export declare function formatJudgeInfrastructureDenyMessage(params: {
+    providerId: string;
+    fallbackReason?: string;
+    command?: string;
+}): {
+    user_message: string;
+    agent_message: string;
+};