@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/adapters/shared/gate-runtime.js

@@ -1,22 +1,37 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { compactApprovals, createApprovalRecordWithEnvelope } from '../../core/approval.js';
-import { buildReplayHint, buildRetryInstructionForConfig, getExecutionLeaseMs, replayShellCommand, validateReplayEnvelope, } from '../../core/approval-replay.js';
-import { consumeApprovedAfterCliReplay, gateApprovalStoreFromDeps, recordApproval, } from '../../core/approval-service.js';
+import { buildReplayHint, buildRetryInstructionForConfig, canAutoReplay, getExecutionLeaseMs, validateReplayEnvelope, } from '../../core/approval-replay.js';
+import { claimApprovedForReplay, gateApprovalStoreFromDeps, recordApproval, } from '../../core/approval-service.js';
 import { issueApprovalToken } from '../../core/approval-token.js';
 import { buildAuditActionSnapshot, buildAuditReplayContext, } from '../../core/audit-replay-context.js';
+import { mutateApprovalStateWithRetry } from '../../core/capability/approval-state-mutation.js';
+import { APPROVAL_STATE_VERSION_V3 } from '../../core/capability/approval-v3.js';
+import { isEgressProxyActive } from '../../core/capability/boundary-egress.js';
+import { isBoundaryCleanupError, safeBoundaryCleanupResourceId, } from '../../core/capability/boundary-run.js';
+import { resolveBoundaryDriverContext, runBoundaryAgentCommand, } from '../../core/capability/boundary-session.js';
+import { hashCapabilityRequests } from '../../core/capability/capability-request-hash.js';
+import { recordGateApprovalAsk, scheduleGateShadowAudit, } from '../../core/capability/gate-shadow-audit.js';
+import { canConsumeCapabilityGrantLease } from '../../core/capability/grant-consumption.js';
+import { approvalGrantBundleExhausted, consumeApprovedRecordGrantBundle, consumeGrantLeasesForRequests, decrementApprovalLegacyGrant, grantsFromApproval, validateAndConsumeGrantBundle, validateGrantBundleForLeaseReuse, } from '../../core/capability/grant-lease.js';
+import { loadClassifierAuthorization } from '../../core/capability/grant-loader.js';
 import { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload, fsScopeAllowlistPath, isCapabilityBrokerDemotionActive, loadFsScopeAllowlistSync, loadTrustedWorkspaceRootsSync, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from '../../core/capability/index.js';
 import { resolveLayeredConfig, teamConfigPath } from '../../core/config-layers.js';
+import { effectPlanAuditFields, hashEffectPlan } from '../../core/effect-ir/audit.js';
+import { buildCapabilityEffectPlan } from '../../core/effect-ir/build.js';
 import { classifyResultToGateVerdict, unnormalizedGateVerdict, } from '../../core/gate-contract.js';
 import { classifyGatedActionAsync, extractAgentAssessment, GateNormalizationError, gateEnabledForAction, normalizeGatedAction, } from '../../core/gate-engine.js';
-import { approvalCommandMatch, approvedApprovalsFile, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { approvalCommandMatch, approvedApprovalsFile, belayStateDir, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, hashValue, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { extractJudgeFallbackReason, formatJudgeInfrastructureDenyMessage, inferProviderIdFromFallbackReason, isJudgeInfrastructureFailure, } from '../../core/judge-fallback-hints.js';
 import { notifyDeny } from '../../core/notify.js';
 import { canonicalPath } from '../../core/path-utils.js';
+import { recoveryFailClosedResult, recoveryFailReasonFromSkip, } from '../../core/recovery/fail-closed.js';
 import { fingerprintReplayPayload } from '../../core/replay-scrub.js';
 import { loadStandingAllow, resolveStandingAllowMatch, standingAllowFile, } from '../../core/standing-allow.js';
-import { isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
+import { FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
+import { egressStatus } from '../../services/egress-service.js';
 import { protectedArtifactRoots } from '../layouts/protected-paths.js';
 const EMPTY_APPROVALS = {
     version: 1,
@@ -33,6 +48,16 @@ function adapterIdFromContext(ctx) {
     }
     return undefined;
 }
+const REPLAY_AUDIT_FAILURE_NOTE = ' Audit recording failed; inspect audit storage before the next approval.';
+async function appendReplayAuditSafely(ctx, deps, event) {
+    try {
+        await deps.appendAudit(ctx, event);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function loadJsonFile(filePath, fallback) {
     try {
         const raw = await readFile(filePath, 'utf8');
@@ -66,10 +91,12 @@ export function createDefaultGateRuntimeDeps() {
                 ? pendingApprovalsFile(ctx.config, repoLocalStateDir)
                 : approvedApprovalsFile(ctx.config, repoLocalStateDir);
             const loaded = await loadJsonFile(filePath, EMPTY_APPROVALS);
+            const version = loaded.version === 3 ? 3 : loaded.version === 2 ? 2 : 1;
             return {
                 filePath,
                 state: {
-                    version: loaded.version === 2 ? 2 : 1,
+                    version,
+                    ...(loaded.revision !== undefined ? { revision: loaded.revision } : {}),
                     approvals: Array.isArray(loaded.approvals) ? loaded.approvals : [],
                 },
             };
@@ -78,6 +105,16 @@ export function createDefaultGateRuntimeDeps() {
             await mkdir(path.dirname(filePath), { recursive: true });
             await writeFile(filePath, `${JSON.stringify(compactApprovals(state), null, 2)}\n`, 'utf8');
         },
+        async replayApprovedShell(ctx, command, cwd, timeoutMs) {
+            return runBoundaryAgentCommand({
+                repoRoot: ctx.repoRoot,
+                config: ctx.config,
+                command,
+                cwd,
+                timeoutMs,
+                runOptions: { mountReadOnly: false },
+            });
+        },
     };
 }
 export async function resolveGateConfig(ctx, deps) {
@@ -126,16 +163,7 @@ function gateAuditEventName(kind) {
     return 'subagentGate';
 }
 async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, scopeHint) {
-    const pending = await deps.loadApprovals(ctx, 'pending-approvals.json');
-    pending.state = compactApprovals(pending.state);
-    const existing = pending.state.approvals.find((approval) => approval.kind === kind &&
-        approval.fingerprint === result.fingerprint &&
-        approval.repoRoot === ctx.repoRoot);
-    if (existing) {
-        await deps.writeApprovals(pending.filePath, pending.state);
-        return existing;
-    }
-    const approval = createApprovalRecordWithEnvelope({
+    const candidate = createApprovalRecordWithEnvelope({
         kind,
         fingerprint: result.fingerprint,
         repoRoot: ctx.repoRoot,
@@ -145,11 +173,32 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, sco
         approvalId: `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`,
         approvalInput,
         scopeHint,
+        capabilityRequests: result.capabilityRequests,
+        effectPlanHash: result.effectPlan ? hashEffectPlan(result.effectPlan) : undefined,
+    });
+    const outcome = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'pending-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const existing = compacted.approvals.find((approval) => approval.kind === kind &&
+                approval.fingerprint === result.fingerprint &&
+                approval.repoRoot === ctx.repoRoot);
+            if (existing) {
+                return { state: compacted, result: { approval: existing, created: false } };
+            }
+            compacted.version = APPROVAL_STATE_VERSION_V3;
+            compacted.approvals.push(candidate);
+            return { state: compacted, result: { approval: candidate, created: true } };
+        },
     });
-    pending.state.version = 2;
-    pending.state.approvals.push(approval);
-    await deps.writeApprovals(pending.filePath, pending.state);
-    return approval;
+    if (!outcome) {
+        throw new Error('Failed to persist pending approval');
+    }
+    return outcome;
+}
+function approvalCorrelationId(approvalId) {
+    return createHash('sha256').update(approvalId).digest('hex').slice(0, 16);
 }
 function extractShellCommandFromPayload(payload) {
     const toolInput = payload.tool_input;
@@ -207,27 +256,93 @@ function deriveWorkspaceRootScopeHint(params) {
     }
     return { scope: 'workspace-root', path: validation.normalizedPath };
 }
-async function consumeApprovedApproval(ctx, deps, kind, fingerprint) {
-    const approved = await deps.loadApprovals(ctx, 'approved-approvals.json');
-    approved.state = compactApprovals(approved.state);
-    const index = approved.state.approvals.findIndex((approval) => approval.kind === kind &&
-        approval.fingerprint === fingerprint &&
-        approval.repoRoot === ctx.repoRoot);
-    if (index === -1) {
-        await deps.writeApprovals(approved.filePath, approved.state);
+async function consumeApprovedApproval(ctx, deps, kind, fingerprint, requests) {
+    const consumed = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const matchIndex = compacted.approvals.findIndex((approval) => approval.kind === kind &&
+                approval.fingerprint === fingerprint &&
+                approval.repoRoot === ctx.repoRoot);
+            if (matchIndex === -1) {
+                return { state: compacted, result: null };
+            }
+            const approval = compacted.approvals[matchIndex];
+            if (approval.executionLeaseExpiresAt) {
+                if (approval.grantBundleVersion === 1) {
+                    const validated = validateGrantBundleForLeaseReuse(approval, requests);
+                    if (!validated.ok) {
+                        compacted.approvals.splice(matchIndex, 1);
+                        return {
+                            state: compacted,
+                            result: { status: 'invalid_bundle', approval, reason: validated.reason },
+                        };
+                    }
+                }
+                return {
+                    state: compacted,
+                    result: { status: 'consumed', approval, firstExecution: false },
+                };
+            }
+            if (approvalGrantBundleExhausted(approval) && !approval.executionLeaseExpiresAt) {
+                compacted.approvals.splice(matchIndex, 1);
+                return { state: compacted, result: null };
+            }
+            let updatedApproval = approval;
+            const bundle = grantsFromApproval(approval);
+            if (approval.grantBundleVersion === 1) {
+                const validated = validateAndConsumeGrantBundle(approval, requests);
+                if (!validated.ok) {
+                    compacted.approvals.splice(matchIndex, 1);
+                    return {
+                        state: compacted,
+                        result: { status: 'invalid_bundle', approval, reason: validated.reason },
+                    };
+                }
+                updatedApproval = validated.approval;
+            }
+            else if (bundle.length > 0) {
+                const consumed = consumeApprovedRecordGrantBundle(approval);
+                if (!consumed.consumed) {
+                    return { state: compacted, result: null };
+                }
+                updatedApproval = consumed.approval;
+            }
+            else if (approval.grant) {
+                updatedApproval = decrementApprovalLegacyGrant(approval);
+            }
+            compacted.approvals[matchIndex] = {
+                ...updatedApproval,
+                executionLeaseExpiresAt: new Date(Date.now() + getExecutionLeaseMs(ctx.config)).toISOString(),
+            };
+            return {
+                state: compacted,
+                result: { status: 'consumed', approval: updatedApproval, firstExecution: true },
+            };
+        },
+    });
+    if (!consumed) {
         return null;
     }
-    const approval = approved.state.approvals[index];
-    if (approval.executionLeaseExpiresAt) {
-        await deps.writeApprovals(approved.filePath, approved.state);
-        return approval;
+    return consumed;
+}
+async function discardApprovedApproval(ctx, deps, approvalId) {
+    const discarded = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const index = compacted.approvals.findIndex((approval) => approval.approvalId === approvalId);
+            if (index !== -1) {
+                compacted.approvals.splice(index, 1);
+            }
+            return { state: compacted, result: true };
+        },
+    });
+    if (discarded !== true) {
+        throw new Error(`Failed to discard rejected approval ${approvalId}`);
     }
-    approved.state.approvals[index] = {
-        ...approval,
-        executionLeaseExpiresAt: new Date(Date.now() + getExecutionLeaseMs(ctx.config)).toISOString(),
-    };
-    await deps.writeApprovals(approved.filePath, approved.state);
-    return approval;
 }
 export async function evaluateGatedAction(ctx, deps, params) {
     let action;
@@ -243,65 +358,124 @@ export async function evaluateGatedAction(ctx, deps, params) {
         });
     }
     catch {
-        const verdict = unnormalizedGateVerdict({
-            reason: 'normalization_failed',
-            mode: ctx.config.mode,
-            user_message: 'belay could not normalize this gated action. Run belay doctor, then retry.',
-            agent_message: 'Belay denied this action because the hook payload could not be normalized.',
-        });
+        const scrubbedInput = scrubValue({
+            kind: params.kind,
+            cwd: params.cwd,
+            command: params.command,
+            payload: params.payload,
+            toolName: params.toolName,
+        }, scrubOptionsFromConfig(ctx.config));
+        const inputFingerprint = hashValue(`unnormalized-gated-action:v1:${canonicalStringify(scrubbedInput)}`);
+        const verdict = {
+            ...unnormalizedGateVerdict({
+                reason: 'normalization_failed',
+                mode: ctx.config.mode,
+                user_message: 'belay could not normalize this gated action. Run belay doctor, then retry.',
+                agent_message: 'Belay denied this action because the hook payload could not be normalized.',
+            }),
+            fingerprint: inputFingerprint,
+            effectPlan: buildCapabilityEffectPlan({
+                actionKind: params.kind,
+                summary: params.command ?? params.toolName ?? params.kind,
+                inputFingerprint,
+                requests: [],
+                effectFree: false,
+            }),
+        };
         await deps.appendAudit(ctx, {
             event: gateAuditEventName(params.kind),
             kind: params.kind,
+            fingerprint: verdict.fingerprint,
             verdict: verdict.verdict,
             reason: verdict.reason,
             mode: ctx.config.mode,
+            ...effectPlanAuditFields(verdict.effectPlan),
             wouldBlock: true,
             permission: 'deny',
         });
         return verdict;
     }
     if (!gateEnabledForAction(ctx.config, action)) {
-        return classifyResultToGateVerdict({
-            result: {
-                verdict: 'allow',
-                reason: 'gate_disabled',
-                fingerprint: 'gate_disabled',
-                assessment: {
-                    reversibility: 'reversible',
-                    external: false,
-                    blastRadius: 'none',
-                    confidence: 1,
-                    signals: ['gate_disabled'],
-                },
+        const result = {
+            verdict: 'allow',
+            reason: 'gate_disabled',
+            fingerprint: 'gate_disabled',
+            assessment: {
+                reversibility: 'reversible',
+                external: false,
+                blastRadius: 'none',
+                confidence: 1,
+                signals: ['gate_disabled'],
             },
+            effectPlan: buildCapabilityEffectPlan({
+                actionKind: action.kind,
+                summary: action.command ?? action.toolName ?? action.kind,
+                inputFingerprint: 'gate_disabled',
+                requests: [],
+                effectFree: false,
+            }),
+        };
+        return classifyResultToGateVerdict({
+            result,
             mode: ctx.config.mode,
             permission: 'allow',
             wouldBlock: false,
         });
     }
     const classifierOptions = runtimeClassifierOptions(ctx, ctx.config);
-    const predicted = await classifyGatedActionAsync(action, ctx.config, classifierOptions);
+    const approvedForAuth = await deps.loadApprovals(ctx, 'approved-approvals.json');
+    const authorization = await loadClassifierAuthorization({
+        repoRoot: ctx.repoRoot,
+        config: ctx.config,
+        approvedState: compactApprovals(approvedForAuth.state),
+    });
+    const egress = await egressStatus({ targetDir: ctx.repoRoot });
+    const egressProxyActive = isEgressProxyActive({
+        config: ctx.config,
+        running: egress.running,
+        foreignProxy: egress.foreignProxy,
+        repoRootMismatch: egress.repoRootMismatch,
+    });
+    const enrichedClassifierOptions = {
+        ...classifierOptions,
+        ...authorization,
+        egressProxyActive,
+    };
+    const predicted = await classifyGatedActionAsync(action, ctx.config, enrichedClassifierOptions);
     let result = predicted;
     let predictedAssessment;
     let observedAssessment;
     let transactionalLayer;
-    if (isTransactionalEligible(ctx.config, params.kind, predicted) &&
+    const recoveryCandidate = isTransactionalEligible(ctx.config, params.kind, predicted) &&
         params.kind === 'shell' &&
-        params.command) {
+        Boolean(params.command);
+    if (recoveryCandidate && params.command) {
         const transactional = ctx.config.policy.transactional;
+        const boundaryDriverId = ctx.config.capability?.boundaryDriver ??
+            (ctx.config.sandbox.runtime === 'container' ? 'container' : 'host-integration');
+        const boundaryContext = await resolveBoundaryDriverContext({
+            repoRoot: ctx.repoRoot,
+            config: ctx.config,
+            driverId: boundaryDriverId,
+            egressProxyRunning: egressProxyActive,
+        });
         const txResult = await runTransactionalExecution({
             command: params.command,
             cwd: params.cwd,
             repoRoot: ctx.repoRoot,
-            stateDir: path.join(ctx.layout.repoLocalStateDir(ctx.repoRoot), 'transactional'),
+            stateDir: belayStateDir(ctx.config, ctx.layout.repoLocalStateDir(ctx.repoRoot)),
             timeoutMs: transactional.timeoutMs,
             predicted,
             diffContext: {
                 repoRoot: ctx.repoRoot,
                 sensitivePaths: ctx.config.classifier.sensitivePaths,
-                protectedRoots: classifierOptions.protectedArtifactRoots ?? [],
+                protectedRoots: enrichedClassifierOptions.protectedArtifactRoots ?? [],
                 maxDeletionCount: transactional.maxDeletionCount,
             },
+            boundaryContext,
+            dirtyIgnoreRoots: protectedArtifactRoots(ctx.layout, ctx.repoRoot, ctx.config.controlPlane.enabled ? configuredControlPlaneDir(ctx.config) : null),
+            fileCheckpoint: transactional.fileCheckpoint,
+            checkpoint: transactional.checkpoint,
         });
         if (!txResult.skipped && txResult.observed) {
             result = txResult.result;
@@ -309,16 +483,49 @@ export async function evaluateGatedAction(ctx, deps, params) {
             observedAssessment = txResult.observed.assessment;
             transactionalLayer = {
                 transactional: true,
+                transactionalBackend: txResult.transactionalBackend,
+                resourceKind: txResult.resourceKind,
+                baselineTreeHash: txResult.baselineTreeHash,
+                snapshotFileCount: txResult.snapshotFileCount,
+                snapshotSourceBytes: txResult.snapshotSourceBytes,
+                snapshotWorkspaceBytes: txResult.snapshotWorkspaceBytes,
+                snapshotCopyStrategy: txResult.snapshotCopyStrategy,
+                snapshotPrepareMs: txResult.snapshotPrepareMs,
+                executionRoute: `boundary:${boundaryContext.driverId}`,
+                enforcementStatus: 'mediated_unattested',
                 transactionalReason: txResult.observed.reason,
                 transactionalCategories: txResult.observed.categories,
                 transactionalChangeCount: txResult.observed.changes.length,
                 transactionalTimedOut: txResult.timedOut === true,
+                ...(txResult.recoveryCheckpointId
+                    ? {
+                        recoveryCheckpointId: txResult.recoveryCheckpointId,
+                        recoveryBackend: txResult.recoveryBackend,
+                        recoveryProofHash: txResult.recoveryProofHash,
+                        recoveryState: txResult.recoveryState,
+                    }
+                    : {}),
             };
         }
-        else if (txResult.skipReason) {
+        else {
+            const skipReason = txResult.skipReason ?? 'recovery_observation_failed';
+            const failReason = skipReason === FILE_CHECKPOINT_ISOLATION_UNAVAILABLE
+                ? FILE_CHECKPOINT_ISOLATION_UNAVAILABLE
+                : recoveryFailReasonFromSkip(skipReason);
+            result = recoveryFailClosedResult(predicted, failReason, [skipReason]);
             transactionalLayer = {
                 transactional: false,
-                transactionalSkipReason: txResult.skipReason,
+                transactionalBackend: txResult.transactionalBackend,
+                resourceKind: txResult.resourceKind,
+                baselineTreeHash: txResult.baselineTreeHash,
+                snapshotFileCount: txResult.snapshotFileCount,
+                snapshotSourceBytes: txResult.snapshotSourceBytes,
+                snapshotWorkspaceBytes: txResult.snapshotWorkspaceBytes,
+                snapshotCopyStrategy: txResult.snapshotCopyStrategy,
+                snapshotPrepareMs: txResult.snapshotPrepareMs,
+                transactionalSkipReason: skipReason,
+                transactionalSkipDetail: txResult.skipDetail,
+                recoveryFailClosed: true,
             };
         }
     }
@@ -353,7 +560,7 @@ export async function evaluateGatedAction(ctx, deps, params) {
             fingerprint: result.fingerprint,
             repoRoot: ctx.repoRoot,
         },
-        classifierOptions,
+        classifierOptions: enrichedClassifierOptions,
         scopeHintPayload: params.payload,
     });
 }
@@ -392,9 +599,58 @@ export async function gateUnmappedToolVerdict(ctx, deps, toolName, payload) {
         },
     });
 }
+async function consumeCapabilityGrantIfUsed(ctx, deps, result) {
+    if (result.reason !== 'capability_grant' &&
+        result.authorizationDecision?.matchedRule !== 'grant.exact') {
+        return true;
+    }
+    if (!canConsumeCapabilityGrantLease(result)) {
+        return false;
+    }
+    const requests = result.capabilityRequests ?? [];
+    if (!requests.length) {
+        return true;
+    }
+    const consumed = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const lease = consumeGrantLeasesForRequests(compacted, requests);
+            if (!lease.consumed) {
+                return null;
+            }
+            return { state: lease.state, result: true };
+        },
+    });
+    return consumed === true;
+}
 async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {}) {
+    if (!result.effectPlan) {
+        result = {
+            ...result,
+            effectPlan: buildCapabilityEffectPlan({
+                actionKind: kind,
+                summary: result.normalizedCommand ?? result.summary ?? kind,
+                inputFingerprint: result.fingerprint,
+                requests: result.capabilityRequests ?? [],
+                effectFree: result.reason === 'read_only',
+            }),
+        };
+    }
     const replayContext = buildAuditReplayContext(kind, result, auditExtras.replayAction);
     const actionSnapshot = buildAuditActionSnapshot(kind, result, auditExtras.replayAction);
+    const providerId = String(ctx.config.judge?.providerId ?? 'cursor');
+    const stateDir = belayStateDir(ctx.config, ctx.layout.repoLocalStateDir(ctx.repoRoot));
+    const capabilityAudit = scheduleGateShadowAudit({
+        repoRoot: ctx.repoRoot,
+        config: ctx.config,
+        providerId,
+        result,
+        command: auditExtras.replayAction?.command ??
+            (kind === 'shell' ? auditExtras.approvalInput?.input : undefined),
+        stateDir,
+    });
     const gateBase = {
         event: gateAuditEventName(kind),
         kind,
@@ -406,10 +662,92 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         mode: ctx.config.mode,
         schemaVersion: result.axes ? 2 : 1,
         ...(result.axes ?? {}),
+        ...capabilityAudit,
         ...auditExtras.transactionalLayer,
         ...(replayContext ? { replayContext } : {}),
         ...(actionSnapshot ? { actionSnapshot } : {}),
     };
+    const denyWithPendingApproval = async (failure) => {
+        const { approval, created } = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput, deriveWorkspaceRootScopeHint({
+            result,
+            replayAction: auditExtras.replayAction,
+            payloadForScopeHint: auditExtras.scopeHintPayload,
+            options: auditExtras.classifierOptions ?? {},
+        }));
+        if (created) {
+            await recordGateApprovalAsk(stateDir, result.reason, false);
+        }
+        let approvalToken;
+        try {
+            approvalToken = await issueApprovalToken({
+                approvalId: approval.approvalId,
+                fingerprint: approval.fingerprint,
+                repoRoot: approval.repoRoot,
+                issuedAt: approval.createdAt,
+                expiresAt: approval.expiresAt,
+            }, configuredControlPlaneDir(ctx.config));
+        }
+        catch {
+            approvalToken = undefined;
+        }
+        const denialReason = failure?.reason ?? result.reason;
+        if (ctx.config.notifications.webhookUrl || ctx.config.notifications.commandHook) {
+            await notifyDeny(ctx.config.notifications, {
+                approvalId: approval.approvalId,
+                reason: denialReason,
+                summary: result.normalizedCommand ?? result.summary ?? '',
+                repoRoot: ctx.repoRoot,
+                fingerprint: result.fingerprint,
+                approvalToken,
+            });
+        }
+        const failureAuditFields = typeof failure?.auditFields === 'function'
+            ? failure.auditFields(approval)
+            : failure?.auditFields;
+        await deps.appendAudit(ctx, {
+            ...gateBase,
+            verdict: failure ? 'deny_pending_approval' : result.verdict,
+            reason: denialReason,
+            approvalId: approval.approvalId,
+            ...(failure?.grantBundleFailureReason
+                ? { grantBundleFailureReason: failure.grantBundleFailureReason }
+                : {}),
+            ...failureAuditFields,
+            wouldBlock: true,
+            permission: 'deny',
+        });
+        const adapter = adapterIdFromContext(ctx);
+        const autoReplayShell = kind === 'shell' && canAutoReplay(ctx.config, kind, adapter);
+        return classifyResultToGateVerdict({
+            result: failure
+                ? { ...result, verdict: 'deny_pending_approval', reason: denialReason }
+                : result,
+            mode: ctx.config.mode,
+            permission: 'deny',
+            wouldBlock: true,
+            approvalId: approval.approvalId,
+            user_message: failure?.userMessage(approval.approvalId) ??
+                `Belay blocked this high-risk action. Approval ID: ${approval.approvalId}. ${buildRetryInstructionForConfig(ctx.config, ctx.config.tokenPrefix, approval.approvalId, kind, adapter)} For details, run belay explain or /belay why.`,
+            agent_message: failure?.agentMessage ??
+                (autoReplayShell
+                    ? `Belay denied this action as ${result.reason}. Wait for approval; Belay will replay the exact shell action automatically. Do not retry unless replay fails.`
+                    : `Belay denied this action as ${result.reason}. Wait for approval, then retry the exact same action once.`),
+        });
+    };
+    const denyReplayMismatch = async (approval, mismatchKind, messages) => {
+        await discardApprovedApproval(ctx, deps, approval.approvalId);
+        return denyWithPendingApproval({
+            reason: 'approval_replay_mismatch',
+            auditFields: (replacement) => ({
+                rejectedApprovalId: approval.approvalId,
+                rejectedApprovalCorrelationId: approvalCorrelationId(approval.approvalId),
+                replacementApprovalCorrelationId: approvalCorrelationId(replacement.approvalId),
+                replayMismatchKind: mismatchKind,
+            }),
+            userMessage: (approvalId) => `${messages.user} New approval ID: ${approvalId}.`,
+            agentMessage: `${messages.agent} Wait for the new exact approval, then retry once.`,
+        });
+    };
     if (result.reason === TRANSACTIONAL_ALREADY_APPLIED) {
         const userMessage = 'Belay executed this command safely in an isolated git worktree. Observed-safe file changes are already applied; do not retry the same command.';
         const agentMessage = 'Belay already applied the observed-safe effects of this shell command in isolation. Do not run it again.';
@@ -470,40 +808,56 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             entry.fingerprint === result.fingerprint &&
             entry.repoRoot === ctx.repoRoot);
         if (!shouldSkipBrokerApprovedRecord(brokerActive, matchedApproval?.reason)) {
+            if (matchedApproval?.capabilityRequestHash &&
+                (!result.capabilityRequests?.length ||
+                    matchedApproval.capabilityRequestHash !==
+                        hashCapabilityRequests(result.capabilityRequests))) {
+                return denyReplayMismatch(matchedApproval, 'capability_requests', {
+                    user: 'Belay denied this action because capability requests changed after approval. Re-approve the exact action or run belay explain.',
+                    agent: 'Belay denied this action because capability requests changed after approval.',
+                });
+            }
+            if (matchedApproval?.effectPlanHash &&
+                (!result.effectPlan || matchedApproval.effectPlanHash !== hashEffectPlan(result.effectPlan))) {
+                return denyReplayMismatch(matchedApproval, 'effect_plan', {
+                    user: 'Belay denied this action because the effect plan changed after approval. Re-approve the exact action or run belay explain.',
+                    agent: 'Belay denied this action because the effect plan changed after approval.',
+                });
+            }
             if (matchedApproval &&
                 auditExtras.replayAction &&
                 !validateReplayEnvelope(matchedApproval, auditExtras.replayAction)) {
-                await deps.appendAudit(ctx, {
-                    ...gateBase,
-                    verdict: 'deny_pending_approval',
-                    reason: 'approval_replay_mismatch',
-                    approvalId: matchedApproval.approvalId,
-                    wouldBlock: true,
-                    permission: 'deny',
-                });
-                return classifyResultToGateVerdict({
-                    result: {
-                        ...result,
-                        verdict: 'deny_pending_approval',
-                        reason: 'approval_replay_mismatch',
-                    },
-                    mode: ctx.config.mode,
-                    permission: 'deny',
-                    wouldBlock: true,
-                    approvalId: matchedApproval.approvalId,
-                    user_message: 'Belay denied this action because it does not match the approved replay envelope. Re-approve the exact action or run belay explain.',
-                    agent_message: 'Belay denied this action because cwd, tool, or payload changed after approval.',
+                return denyReplayMismatch(matchedApproval, 'replay_envelope', {
+                    user: 'Belay denied this action because it does not match the approved replay envelope. Re-approve the exact action or run belay explain.',
+                    agent: 'Belay denied this action because cwd, tool, or payload changed after approval.',
                 });
             }
-            approved = await consumeApprovedApproval(ctx, deps, kind, result.fingerprint);
+            approved = await consumeApprovedApproval(ctx, deps, kind, result.fingerprint, result.capabilityRequests ?? []);
         }
     }
-    if (approved) {
+    if (approved?.status === 'invalid_bundle') {
+        return denyWithPendingApproval({
+            reason: 'capability_grant_unavailable',
+            grantBundleFailureReason: approved.reason,
+            auditFields: (replacement) => ({
+                rejectedApprovalId: approved.approval.approvalId,
+                rejectedApprovalCorrelationId: approvalCorrelationId(approved.approval.approvalId),
+                replacementApprovalCorrelationId: approvalCorrelationId(replacement.approvalId),
+            }),
+            userMessage: (approvalId) => `Belay denied this action because its approved capability bundle did not exactly match the current request. New approval ID: ${approvalId}. Re-approve the exact action or run belay explain.`,
+            agentMessage: `Belay denied this action because the approved capability bundle failed exact validation (${approved.reason}). Wait for the new exact approval, then retry once.`,
+        });
+    }
+    if (approved?.status === 'consumed') {
+        if (approved.firstExecution) {
+            await recordGateApprovalAsk(stateDir, result.reason, true);
+        }
         await deps.appendAudit(ctx, {
             ...gateBase,
             verdict: 'allow',
             reason: 'approved_once',
-            approvalId: approved.approvalId,
+            approvalId: approved.approval.approvalId,
+            authorizationMode: approved.approval.grantBundleVersion === 1 ? 'exact_bundle' : 'legacy_approval',
             wouldBlock: false,
             permission: 'allow',
         });
@@ -512,10 +866,32 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             mode: ctx.config.mode,
             permission: 'allow',
             wouldBlock: false,
-            approvalId: approved.approvalId,
+            approvalId: approved.approval.approvalId,
         });
     }
     if (result.verdict === 'allow' || result.verdict === 'allow_flagged') {
+        const grantConsumed = await consumeCapabilityGrantIfUsed(ctx, deps, result);
+        if (!grantConsumed) {
+            await deps.appendAudit(ctx, {
+                ...gateBase,
+                verdict: 'deny_pending_approval',
+                reason: 'capability_grant_unavailable',
+                wouldBlock: true,
+                permission: 'deny',
+            });
+            return classifyResultToGateVerdict({
+                result: {
+                    ...result,
+                    verdict: 'deny_pending_approval',
+                    reason: 'capability_grant_unavailable',
+                },
+                mode: ctx.config.mode,
+                permission: 'deny',
+                wouldBlock: true,
+                user_message: 'Belay denied this action because the capability grant could not be consumed. Re-approve or run belay explain.',
+                agent_message: 'Belay denied this action because the capability grant was missing, expired, or already used.',
+            });
+        }
         await deps.appendAudit(ctx, {
             ...gateBase,
             verdict: result.verdict,
@@ -545,58 +921,62 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             wouldBlock: true,
         });
     }
-    const approval = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput, deriveWorkspaceRootScopeHint({
-        result,
-        replayAction: auditExtras.replayAction,
-        payloadForScopeHint: auditExtras.scopeHintPayload,
-        options: auditExtras.classifierOptions ?? {},
-    }));
-    let approvalToken;
-    try {
-        approvalToken = await issueApprovalToken({
-            approvalId: approval.approvalId,
-            fingerprint: approval.fingerprint,
-            repoRoot: approval.repoRoot,
-            issuedAt: approval.createdAt,
-            expiresAt: approval.expiresAt,
-        }, configuredControlPlaneDir(ctx.config));
-    }
-    catch {
-        approvalToken = undefined;
+    if (isJudgeInfrastructureFailure(result)) {
+        const fallbackReason = extractJudgeFallbackReason(result);
+        const providerId = inferProviderIdFromFallbackReason(fallbackReason, String(ctx.config.judge.providerId ?? 'cursor'));
+        const denyMessages = formatJudgeInfrastructureDenyMessage({
+            providerId,
+            fallbackReason,
+            command: result.normalizedCommand ?? result.summary,
+        });
+        await deps.appendAudit(ctx, {
+            ...gateBase,
+            verdict: result.verdict,
+            reason: 'judge_transport_unavailable',
+            judgeFallbackReason: fallbackReason,
+            wouldBlock: true,
+            permission: 'deny',
+        });
+        return classifyResultToGateVerdict({
+            result: {
+                ...result,
+                verdict: 'deny_pending_approval',
+                reason: 'judge_transport_unavailable',
+            },
+            mode: ctx.config.mode,
+            permission: 'deny',
+            wouldBlock: true,
+            user_message: denyMessages.user_message,
+            agent_message: denyMessages.agent_message,
+        });
     }
-    if (ctx.config.notifications.webhookUrl || ctx.config.notifications.commandHook) {
-        await notifyDeny(ctx.config.notifications, {
-            approvalId: approval.approvalId,
+    if (result.reason === FILE_CHECKPOINT_ISOLATION_UNAVAILABLE) {
+        const userMessage = 'Belay cannot run file_checkpoint because attested workspace isolation is unavailable. Run `belay session start`, then retry.';
+        const agentMessage = 'Belay denied this action because file_checkpoint lacks a fresh matching workspace-isolation attestation. Ask the operator to run `belay session start`, then retry the exact action.';
+        await deps.appendAudit(ctx, {
+            ...gateBase,
+            verdict: result.verdict,
             reason: result.reason,
-            summary: result.normalizedCommand ?? result.summary ?? '',
-            repoRoot: ctx.repoRoot,
-            fingerprint: result.fingerprint,
-            approvalToken,
+            wouldBlock: true,
+            permission: 'deny',
+        });
+        return classifyResultToGateVerdict({
+            result,
+            mode: ctx.config.mode,
+            permission: 'deny',
+            wouldBlock: true,
+            user_message: userMessage,
+            agent_message: agentMessage,
         });
     }
-    await deps.appendAudit(ctx, {
-        ...gateBase,
-        verdict: result.verdict,
-        reason: result.reason,
-        approvalId: approval.approvalId,
-        wouldBlock: true,
-        permission: 'deny',
-    });
-    return classifyResultToGateVerdict({
-        result,
-        mode: ctx.config.mode,
-        permission: 'deny',
-        wouldBlock: true,
-        approvalId: approval.approvalId,
-        user_message: `Belay blocked this high-risk action. Approval ID: ${approval.approvalId}. ${buildRetryInstructionForConfig(ctx.config, ctx.config.tokenPrefix, approval.approvalId)} For details, run belay explain or /belay why.`,
-        agent_message: `Belay denied this action as ${result.reason}. Wait for approval, then retry the exact same action once.`,
-    });
+    return denyWithPendingApproval();
 }
 export async function processApprovalPrompt(ctx, deps, prompt) {
     const approvalId = approvalCommandMatch(prompt, ctx.config.tokenPrefix);
     if (!approvalId) {
         return { continue: true };
     }
+    const hasFollowupInstruction = prompt.split(/\r?\n/).filter((line) => line.trim().length > 0).length > 1;
     const adapter = adapterIdFromContext(ctx);
     if (ctx.config.approvalSigning.required) {
         const message = `Signed approval token required for ${approvalId}. Editor prompt approval is disabled in this configuration. ` +
@@ -639,62 +1019,68 @@ export async function processApprovalPrompt(ctx, deps, prompt) {
         };
     }
     const replay = recorded.approval ? buildReplayHint(ctx.config, recorded.approval, adapter) : null;
-    const shouldFallbackReplay = adapter === 'cursor' &&
-        replay?.kind === 'shell' &&
+    const shouldReplayApprovedShell = replay?.kind === 'shell' &&
         replay.autoReplay === true &&
         Boolean(recorded.approval?.input) &&
         (!process.env.VITEST || process.env.BELAY_TEST_APPROVAL_REPLAY === '1');
-    if (shouldFallbackReplay && recorded.approval) {
+    if (shouldReplayApprovedShell && recorded.approval) {
         const approvalStore = gateApprovalStoreFromDeps({
             loadApprovals: (fileName) => deps.loadApprovals(ctx, fileName),
             writeApprovals: (filePath, state) => deps.writeApprovals(filePath, state),
         });
+        let claimed;
+        try {
+            claimed = await claimApprovedForReplay({ approvalId, store: approvalStore });
+        }
+        catch {
+            return {
+                continue: false,
+                user_message: `Belay approval ${approvalId} could not be claimed for one-step replay. ` +
+                    'The shell action was not started.',
+            };
+        }
+        if (!claimed) {
+            return {
+                continue: false,
+                user_message: `Belay approval ${approvalId} could not be claimed for one-step replay.`,
+            };
+        }
         let replayResult;
         try {
-            replayResult = await replayShellCommand(recorded.approval.input ?? '', recorded.approval.cwd ?? ctx.repoRoot, getExecutionLeaseMs(ctx.config));
+            replayResult = await deps.replayApprovedShell(ctx, claimed.input ?? '', claimed.cwd ?? ctx.repoRoot, getExecutionLeaseMs(ctx.config));
         }
         catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            await deps.appendAudit(ctx, {
+            const cleanupUnconfirmed = isBoundaryCleanupError(error);
+            const auditRecorded = await appendReplayAuditSafely(ctx, deps, {
                 event: 'approval',
                 kind: 'approval',
                 verdict: 'allow',
                 approvalId,
-                reason: 'approval_replay_error',
+                reason: cleanupUnconfirmed
+                    ? 'approval_replay_cleanup_unconfirmed'
+                    : 'approval_replay_error',
                 summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
             });
-            return {
-                continue: false,
-                user_message: `Belay approval recorded for ${approvalId}, but one-step shell replay could not start (${detail}). ` +
-                    'Approval remains active for one hook retry.',
-            };
-        }
-        const output = [replayResult.stdout, replayResult.stderr].filter(Boolean).join('\n').trim();
-        if (replayResult.exitCode === 0) {
-            try {
-                await consumeApprovedAfterCliReplay({
-                    approvalId: approvalId,
-                    store: approvalStore,
-                });
-            }
-            catch (error) {
-                const detail = error instanceof Error ? error.message : String(error);
-                await deps.appendAudit(ctx, {
-                    event: 'approval',
-                    kind: 'approval',
-                    verdict: 'allow',
-                    approvalId,
-                    reason: 'approval_replay_consume_error',
-                    summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
-                });
+            if (cleanupUnconfirmed) {
+                const resourceId = safeBoundaryCleanupResourceId(error);
                 return {
                     continue: false,
-                    user_message: `Belay approval recorded for ${approvalId}, and one-step shell replay succeeded, but approval finalization failed (${detail}). ` +
-                        'Approval remains active for one hook retry.' +
-                        (output ? `\n${output}` : ''),
+                    user_message: `Belay approval recorded for ${approvalId}. The one-step shell replay started, but cleanup could not be confirmed; the container may still be running.` +
+                        (resourceId ? ` Container: ${resourceId}.` : '') +
+                        ' Inspect Docker and remove the container manually if it is still present. ' +
+                        'The one-shot approval was consumed and was not re-armed.' +
+                        (auditRecorded ? '' : REPLAY_AUDIT_FAILURE_NOTE),
                 };
             }
-            await deps.appendAudit(ctx, {
+            return {
+                continue: false,
+                user_message: `Belay approval recorded for ${approvalId}, but one-step shell replay could not start. ` +
+                    'The one-shot approval was consumed before replay and was not re-armed.' +
+                    (auditRecorded ? '' : REPLAY_AUDIT_FAILURE_NOTE),
+            };
+        }
+        if (replayResult.exitCode === 0 && !replayResult.timedOut) {
+            const auditRecorded = await appendReplayAuditSafely(ctx, deps, {
                 event: 'approval',
                 kind: 'approval',
                 verdict: 'allow',
@@ -703,12 +1089,12 @@ export async function processApprovalPrompt(ctx, deps, prompt) {
                 summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
             });
             return {
-                continue: false,
+                continue: true,
                 user_message: `Belay approval recorded for ${approvalId}. One-step shell replay succeeded; no manual retry required.` +
-                    (output ? `\n${output}` : ''),
+                    (auditRecorded ? '' : REPLAY_AUDIT_FAILURE_NOTE),
             };
         }
-        await deps.appendAudit(ctx, {
+        const auditRecorded = await appendReplayAuditSafely(ctx, deps, {
             event: 'approval',
             kind: 'approval',
             verdict: 'allow',
@@ -716,16 +1102,18 @@ export async function processApprovalPrompt(ctx, deps, prompt) {
             reason: 'approval_replay_failed',
             summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
         });
-        const timeoutNote = replayResult.timedOut ? ' Replay timed out.' : '';
+        const failureSummary = replayResult.timedOut
+            ? ' One-step shell replay timed out.'
+            : ` One-step shell replay failed (exit ${replayResult.exitCode}).`;
         return {
             continue: false,
-            user_message: `Belay approval recorded for ${approvalId}, but one-step shell replay failed (exit ${replayResult.exitCode}).${timeoutNote} ` +
-                `Approval remains active for one hook retry.` +
-                (output ? `\n${output}` : ''),
+            user_message: `Belay approval recorded for ${approvalId}.${failureSummary} ` +
+                'The one-shot approval was consumed before replay and was not re-armed.' +
+                (auditRecorded ? '' : REPLAY_AUDIT_FAILURE_NOTE),
         };
     }
     return {
-        continue: false,
+        continue: replay !== null || hasFollowupInstruction,
         user_message: recorded.message,
         ...(replay ? { replay } : {}),
     };
@@ -753,15 +1141,18 @@ export function gateVerdictToClaudePreToolUseResponse(verdict) {
 }
 export function gateVerdictToClaudeUserPromptResponse(verdict) {
     if (verdict.continue) {
-        return {};
+        return verdict.user_message
+            ? {
+                hookSpecificOutput: {
+                    hookEventName: 'UserPromptSubmit',
+                    additionalContext: verdict.user_message,
+                },
+            }
+            : {};
     }
     return {
-        hookSpecificOutput: {
-            hookEventName: 'UserPromptSubmit',
-            continue: false,
-            user_message: verdict.user_message,
-            ...(verdict.replay ? { replay: verdict.replay } : {}),
-        },
+        decision: 'block',
+        reason: verdict.user_message,
     };
 }
 // Codex PreToolUse deny contract is identical to Claude's
@@ -772,7 +1163,14 @@ export function gateVerdictToCodexPreToolUseResponse(verdict) {
 // Codex UserPromptSubmit blocks via `decision: "block"` (per developers.openai.com/codex/hooks).
 export function gateVerdictToCodexUserPromptResponse(verdict) {
     if (verdict.continue) {
-        return {};
+        return verdict.user_message
+            ? {
+                hookSpecificOutput: {
+                    hookEventName: 'UserPromptSubmit',
+                    additionalContext: verdict.user_message,
+                },
+            }
+            : {};
     }
     return {
         decision: 'block',