@guilz-dev/belay 0.6.0 → 0.7.0

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

@@ -1,32 +1,36 @@
-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 { resolveBoundaryDriverContext } from '../../core/capability/boundary-session.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 { consumeGrantLease, findMatchingGrant, grantsFromApprovedState, } from '../../core/capability/grant-lease.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, belayStateDir, 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 = {
@@ -44,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');
@@ -91,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) {
@@ -139,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 { approval: existing, created: false };
-    }
-    const approval = createApprovalRecordWithEnvelope({
+    const candidate = createApprovalRecordWithEnvelope({
         kind,
         fingerprint: result.fingerprint,
         repoRoot: ctx.repoRoot,
@@ -159,12 +174,31 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, sco
         approvalInput,
         scopeHint,
         capabilityRequests: result.capabilityRequests,
+        effectPlanHash: result.effectPlan ? hashEffectPlan(result.effectPlan) : undefined,
     });
-    pending.state.version = APPROVAL_STATE_VERSION_V3;
-    pending.state.revision = (pending.state.revision ?? 0) + 1;
-    pending.state.approvals.push(approval);
-    await deps.writeApprovals(pending.filePath, pending.state);
-    return { approval, created: true };
+    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 } };
+        },
+    });
+    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;
@@ -222,21 +256,7 @@ function deriveWorkspaceRootScopeHint(params) {
     }
     return { scope: 'workspace-root', path: validation.normalizedPath };
 }
-async function consumeApprovedApproval(ctx, deps, kind, fingerprint) {
-    const loaded = await deps.loadApprovals(ctx, 'approved-approvals.json');
-    loaded.state = compactApprovals(loaded.state);
-    const index = loaded.state.approvals.findIndex((approval) => approval.kind === kind &&
-        approval.fingerprint === fingerprint &&
-        approval.repoRoot === ctx.repoRoot);
-    if (index === -1) {
-        await deps.writeApprovals(loaded.filePath, loaded.state);
-        return null;
-    }
-    const approval = loaded.state.approvals[index];
-    if (approval.executionLeaseExpiresAt) {
-        await deps.writeApprovals(loaded.filePath, loaded.state);
-        return { approval, firstExecution: false };
-    }
+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),
@@ -246,30 +266,83 @@ async function consumeApprovedApproval(ctx, deps, kind, fingerprint) {
                 approval.fingerprint === fingerprint &&
                 approval.repoRoot === ctx.repoRoot);
             if (matchIndex === -1) {
-                return null;
+                return { state: compacted, result: null };
             }
             const approval = compacted.approvals[matchIndex];
-            if (approval.grant && approval.grant.usesRemaining <= 0) {
+            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] = {
-                ...approval,
+                ...updatedApproval,
                 executionLeaseExpiresAt: new Date(Date.now() + getExecutionLeaseMs(ctx.config)).toISOString(),
-                grant: approval.grant
-                    ? {
-                        ...approval.grant,
-                        usesRemaining: Math.max(0, approval.grant.usesRemaining - 1),
-                    }
-                    : undefined,
             };
-            return { state: compacted, result: approval };
+            return {
+                state: compacted,
+                result: { status: 'consumed', approval: updatedApproval, firstExecution: true },
+            };
         },
     });
     if (!consumed) {
         return null;
     }
-    return { approval: consumed, firstExecution: true };
+    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}`);
+    }
 }
 export async function evaluateGatedAction(ctx, deps, params) {
     let action;
@@ -285,37 +358,65 @@ 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,
@@ -362,7 +463,7 @@ export async function evaluateGatedAction(ctx, deps, params) {
             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: {
@@ -373,6 +474,8 @@ export async function evaluateGatedAction(ctx, deps, params) {
             },
             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;
@@ -380,20 +483,48 @@ 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 {
             const skipReason = txResult.skipReason ?? 'recovery_observation_failed';
-            result = recoveryFailClosedResult(predicted, recoveryFailReasonFromSkip(skipReason), [
-                skipReason,
-            ]);
+            const failReason = skipReason === FILE_CHECKPOINT_ISOLATION_UNAVAILABLE
+                ? FILE_CHECKPOINT_ISOLATION_UNAVAILABLE
+                : recoveryFailReasonFromSkip(skipReason);
+            result = recoveryFailClosedResult(predicted, failReason, [skipReason]);
             transactionalLayer = {
                 transactional: false,
+                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,
             };
         }
@@ -473,20 +604,19 @@ async function consumeCapabilityGrantIfUsed(ctx, deps, result) {
         result.authorizationDecision?.matchedRule !== 'grant.exact') {
         return true;
     }
-    const request = result.capabilityRequests?.[0];
-    if (!request) {
+    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 grant = findMatchingGrant(grantsFromApprovedState(compacted, ctx.repoRoot), request);
-            if (!grant) {
-                return null;
-            }
-            const lease = consumeGrantLease(compacted, grant.grantId);
+            const lease = consumeGrantLeasesForRequests(compacted, requests);
             if (!lease.consumed) {
                 return null;
             }
@@ -496,6 +626,18 @@ async function consumeCapabilityGrantIfUsed(ctx, deps, result) {
     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');
@@ -520,11 +662,92 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         mode: ctx.config.mode,
         schemaVersion: result.axes ? 2 : 1,
         ...(result.axes ?? {}),
-        ...auditExtras.transactionalLayer,
         ...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.';
@@ -585,61 +808,47 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             entry.fingerprint === result.fingerprint &&
             entry.repoRoot === ctx.repoRoot);
         if (!shouldSkipBrokerApprovedRecord(brokerActive, matchedApproval?.reason)) {
-            if (matchedApproval &&
-                matchedApproval.capabilityRequestHash &&
-                result.capabilityRequests?.length &&
-                matchedApproval.capabilityRequestHash !== hashCapabilityRequests(result.capabilityRequests)) {
-                await deps.appendAudit(ctx, {
-                    ...gateBase,
-                    verdict: 'deny_pending_approval',
-                    reason: 'approval_replay_mismatch',
-                    approvalId: matchedApproval.approvalId,
-                    wouldBlock: true,
-                    permission: 'deny',
+            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.',
                 });
-                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 capability requests changed after approval. Re-approve the exact action or run belay explain.',
-                    agent_message: '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);
         }
@@ -648,6 +857,7 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             verdict: 'allow',
             reason: 'approved_once',
             approvalId: approved.approval.approvalId,
+            authorizationMode: approved.approval.grantBundleVersion === 1 ? 'exact_bundle' : 'legacy_approval',
             wouldBlock: false,
             permission: 'allow',
         });
@@ -740,61 +950,33 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             agent_message: denyMessages.agent_message,
         });
     }
-    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;
-    }
-    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. ` +
@@ -837,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',
@@ -901,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',
@@ -914,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 } : {}),
     };
@@ -951,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
@@ -970,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',