@guilz-dev/belay 0.6.0 → 0.7.0

package/dist/commands/recovery-checkpoints.js

@@ -0,0 +1,347 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { ensureBelayStateDir, loadConfigFile } from '../config-io.js';
+import { compactApprovals, createApprovalRecordWithEnvelope } from '../core/approval.js';
+import { createGateApprovalStore } from '../core/approval-service.js';
+import { issueApprovalToken } from '../core/approval-token.js';
+import { appendCliAuditEvent } from '../core/audit-io.js';
+import { mutateApprovalStateWithRetry } from '../core/capability/approval-state-mutation.js';
+import { boundarySessionStatus } from '../core/capability/boundary-session.js';
+import { configuredControlPlaneDir, DEFAULT_RECOVERY_CHECKPOINT } from '../core/config.js';
+import { notifyDeny } from '../core/notify.js';
+import { canonicalPath } from '../core/path-utils.js';
+import { listRecoveryCheckpoints, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, recoveryCheckpointStorageBytes, recoveryRestoreBinding, restoreRecoveryCheckpoint, showRecoveryCheckpoint, } from '../core/recovery/checkpoint.js';
+import { formatRecoveryStateDiagnostic, recoveryNotificationConfigured, recoveryNotificationSetupWarning, summarizeRecoveryCheckpointDiagnostics, } from '../core/recovery/operator-guidance.js';
+import { probeFileCloneStrategy } from '../core/transactional/file-clone.js';
+async function appendRecoveryAudit(repoRoot, config, event) {
+    try {
+        await appendCliAuditEvent(repoRoot, config, event);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function consumeRecoveryApproval(params) {
+    const store = createGateApprovalStore(params.repoRoot, params.config);
+    return mutateApprovalStateWithRetry({
+        load: store.loadApproved,
+        write: store.writeApproved,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const index = compacted.approvals.findIndex((entry) => entry.kind === 'tool' &&
+                entry.reason === RECOVERY_RESTORE_REASON &&
+                entry.fingerprint === params.fingerprint &&
+                entry.repoRoot === params.repoRoot);
+            if (index === -1)
+                return null;
+            const [approval] = compacted.approvals.splice(index, 1);
+            return approval ? { state: compacted, result: approval } : null;
+        },
+    });
+}
+async function clearRecoveryPending(params) {
+    const store = createGateApprovalStore(params.repoRoot, params.config);
+    await mutateApprovalStateWithRetry({
+        load: store.loadPending,
+        write: store.writePending,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const remaining = compacted.approvals.filter((entry) => !(entry.kind === 'tool' &&
+                entry.reason === RECOVERY_RESTORE_REASON &&
+                entry.fingerprint === params.fingerprint &&
+                entry.repoRoot === params.repoRoot));
+            if (remaining.length === compacted.approvals.length)
+                return null;
+            compacted.approvals = remaining;
+            return { state: compacted, result: undefined };
+        },
+    });
+}
+async function ensureRecoveryPending(params) {
+    const store = createGateApprovalStore(params.repoRoot, params.config);
+    const request = createApprovalRecordWithEnvelope({
+        kind: 'tool',
+        fingerprint: params.fingerprint,
+        repoRoot: params.repoRoot,
+        reason: RECOVERY_RESTORE_REASON,
+        summary: `Restore recovery checkpoint ${params.checkpointId}`,
+        approvalTtlMinutes: params.config.approvalTtlMinutes,
+        approvalId: `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`,
+        approvalInput: {
+            input: 'recovery.restore',
+            inputKind: 'tool',
+            cwd: params.repoRoot,
+            toolName: 'recovery.restore',
+            payload: {
+                checkpointId: params.checkpointId,
+                manifestHash: params.manifestHash,
+                postStateHash: params.postStateHash,
+                paths: params.paths,
+            },
+        },
+    });
+    const result = await mutateApprovalStateWithRetry({
+        load: store.loadPending,
+        write: store.writePending,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const existing = compacted.approvals.find((entry) => entry.kind === 'tool' &&
+                entry.reason === RECOVERY_RESTORE_REASON &&
+                entry.fingerprint === params.fingerprint &&
+                entry.repoRoot === params.repoRoot);
+            if (existing)
+                return { state: compacted, result: existing };
+            compacted.approvals.push(request);
+            return { state: compacted, result: request };
+        },
+    });
+    if (!result)
+        throw new Error('recovery_approval_state_busy');
+    return result;
+}
+export async function recoveryCheckpointCommand(options) {
+    const repoRoot = canonicalPath(path.resolve(options.targetDir ?? process.cwd()));
+    const config = await loadConfigFile(repoRoot);
+    const stateDir = await ensureBelayStateDir(config, repoRoot);
+    const checkpointConfig = config.policy.transactional.checkpoint ?? DEFAULT_RECOVERY_CHECKPOINT;
+    if (options.subcommand === 'status') {
+        const checkpoints = await listRecoveryCheckpoints(stateDir, repoRoot);
+        const states = Object.fromEntries([...new Set(checkpoints.map((checkpoint) => checkpoint.state))].map((state) => [
+            state,
+            checkpoints.filter((checkpoint) => checkpoint.state === state).length,
+        ]));
+        const advisories = summarizeRecoveryCheckpointDiagnostics(checkpoints);
+        const backendCounts = Object.fromEntries([...new Set(checkpoints.map((checkpoint) => checkpoint.backend))].map((backend) => [
+            backend,
+            checkpoints.filter((checkpoint) => checkpoint.backend === backend).length,
+        ]));
+        const checkpointBackends = Object.keys(backendCounts);
+        const fileCheckpointConfig = config.policy.transactional.fileCheckpoint;
+        const configuredBoundary = config.capability?.boundaryDriver ??
+            (config.sandbox.runtime === 'container' ? 'container' : null);
+        let isolation = configuredBoundary;
+        let isolationAvailable = false;
+        if (configuredBoundary) {
+            try {
+                const session = await boundarySessionStatus({ repoRoot, config });
+                isolationAvailable =
+                    session.fresh === true && session.attestation?.isolatesWorkspaceMounts === true;
+                isolation = isolationAvailable ? (session.attestation?.driver ?? configuredBoundary) : null;
+            }
+            catch {
+                isolation = null;
+            }
+        }
+        const copyStrategy = fileCheckpointConfig.enabled ? await probeFileCloneStrategy() : null;
+        const fileCheckpointAvailable = fileCheckpointConfig.enabled &&
+            config.policy.transactional.enabled &&
+            checkpointConfig.enabled &&
+            isolationAvailable;
+        return {
+            ok: true,
+            subcommand: 'status',
+            repoRoot,
+            backend: checkpointBackends.length === 1
+                ? checkpointBackends[0]
+                : checkpointBackends.length > 1
+                    ? 'mixed'
+                    : 'git_worktree',
+            availableBackends: ['git_worktree', 'file_checkpoint'],
+            backendCounts,
+            fileCheckpoint: {
+                enabled: fileCheckpointConfig.enabled,
+                allowNonGit: fileCheckpointConfig.allowNonGit,
+                isolation,
+                copyStrategy: copyStrategy ?? undefined,
+                probe: fileCheckpointAvailable ? 'available' : 'unavailable',
+            },
+            enabled: checkpointConfig.enabled,
+            checkpointCount: checkpoints.length,
+            storageBytes: await recoveryCheckpointStorageBytes(stateDir, repoRoot),
+            recoverableCount: checkpoints.filter((checkpoint) => checkpoint.state === 'applied').length,
+            needsManualRepairCount: checkpoints.filter((checkpoint) => checkpoint.state === 'needs_manual_repair').length,
+            verifiedReceiptCount: checkpoints.filter((checkpoint) => checkpoint.receiptHash).length,
+            states,
+            advisories,
+            limits: checkpointConfig,
+        };
+    }
+    if (options.subcommand === 'list') {
+        return {
+            ok: true,
+            subcommand: 'list',
+            repoRoot,
+            checkpoints: await listRecoveryCheckpoints(stateDir, repoRoot),
+        };
+    }
+    if (!options.checkpointId) {
+        throw new Error(`recover ${options.subcommand} requires a checkpoint id`);
+    }
+    if (options.subcommand === 'show') {
+        const loaded = await showRecoveryCheckpoint(stateDir, options.checkpointId, repoRoot);
+        return {
+            ok: true,
+            subcommand: 'show',
+            manifest: loaded.manifest,
+            state: loaded.state,
+            manifestHash: loaded.manifestHash,
+            receipt: loaded.receipt,
+        };
+    }
+    let binding;
+    try {
+        binding = await recoveryRestoreBinding(stateDir, options.checkpointId, repoRoot);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : RECOVERY_CHECKPOINT_CORRUPT;
+        await appendRecoveryAudit(repoRoot, config, {
+            event: reason === RECOVERY_RESTORE_CONFLICT
+                ? 'recoveryConflict'
+                : reason === RECOVERY_CHECKPOINT_CORRUPT
+                    ? 'recoveryCorrupt'
+                    : 'recoveryRejected',
+            recoveryCheckpointId: options.checkpointId,
+            reason,
+        });
+        throw error;
+    }
+    const approval = await consumeRecoveryApproval({
+        repoRoot,
+        config,
+        fingerprint: binding.fingerprint,
+    });
+    if (!approval) {
+        const request = await ensureRecoveryPending({
+            repoRoot,
+            config,
+            fingerprint: binding.fingerprint,
+            checkpointId: options.checkpointId,
+            manifestHash: binding.manifestHash,
+            postStateHash: binding.postStateHash,
+            paths: binding.paths,
+        });
+        try {
+            const current = await recoveryRestoreBinding(stateDir, options.checkpointId, repoRoot);
+            if (current.fingerprint !== binding.fingerprint) {
+                throw new Error(RECOVERY_RESTORE_CONFLICT);
+            }
+        }
+        catch (error) {
+            await clearRecoveryPending({ repoRoot, config, fingerprint: binding.fingerprint }).catch(() => { });
+            throw error;
+        }
+        const notificationConfigured = recoveryNotificationConfigured(config);
+        if (notificationConfigured) {
+            const approvalToken = await issueApprovalToken({
+                approvalId: request.approvalId,
+                fingerprint: request.fingerprint,
+                repoRoot: request.repoRoot,
+                issuedAt: request.createdAt,
+                expiresAt: request.expiresAt,
+            }, configuredControlPlaneDir(config));
+            await notifyDeny(config.notifications, {
+                approvalId: request.approvalId,
+                reason: request.reason,
+                summary: request.summary,
+                repoRoot: request.repoRoot,
+                fingerprint: request.fingerprint,
+                approvalToken,
+            });
+        }
+        const auditRecorded = await appendRecoveryAudit(repoRoot, config, {
+            event: 'recoveryApprovalRequested',
+            recoveryCheckpointId: options.checkpointId,
+            approvalId: request.approvalId,
+            manifestHash: binding.manifestHash,
+            postStateHash: binding.postStateHash,
+            pathCount: binding.paths.length,
+        });
+        return {
+            ok: false,
+            subcommand: 'apply',
+            verdict: 'deny_pending_approval',
+            checkpointId: options.checkpointId,
+            approvalId: request.approvalId,
+            manifestHash: binding.manifestHash,
+            paths: binding.paths,
+            auditRecorded,
+            message: notificationConfigured
+                ? `Signed out-of-band approval required for ${request.approvalId}. Use the token delivered through the configured notification channel, then run \`belay approve ${request.approvalId} --token <signed-token>\` and repeat this command.`
+                : `${recoveryNotificationSetupWarning()} Pending approval id: ${request.approvalId}.`,
+        };
+    }
+    try {
+        const result = await restoreRecoveryCheckpoint(stateDir, options.checkpointId, repoRoot);
+        await clearRecoveryPending({ repoRoot, config, fingerprint: binding.fingerprint }).catch(() => { });
+        const auditRecorded = await appendRecoveryAudit(repoRoot, config, {
+            event: 'recoveryApplied',
+            recoveryCheckpointId: options.checkpointId,
+            approvalId: approval.approvalId,
+            manifestHash: result.manifestHash,
+            changeCount: result.changeCount,
+        });
+        return {
+            ok: true,
+            subcommand: 'apply',
+            verdict: 'restored',
+            checkpointId: options.checkpointId,
+            ...result,
+            auditRecorded,
+            message: `Recovery checkpoint ${options.checkpointId} restored.`,
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : 'recovery_restore_failed';
+        await appendRecoveryAudit(repoRoot, config, {
+            event: reason === RECOVERY_RESTORE_CONFLICT ? 'recoveryConflict' : 'recoveryRejected',
+            recoveryCheckpointId: options.checkpointId,
+            approvalId: approval.approvalId,
+            reason,
+        });
+        throw error;
+    }
+}
+export function formatRecoveryCheckpointResult(result) {
+    if (result.subcommand === 'status') {
+        const lines = [
+            `belay recover status for ${result.repoRoot}`,
+            `Backend: ${result.backend}`,
+            `Checkpointing: ${result.enabled ? 'enabled' : 'disabled'}`,
+            `Checkpoints: ${result.checkpointCount} (${result.recoverableCount} recoverable)`,
+            `Needs manual repair: ${result.needsManualRepairCount ?? 0}`,
+            `Verified receipts: ${result.verifiedReceiptCount}`,
+            `Storage: ${result.storageBytes} bytes`,
+            `States: ${JSON.stringify(result.states)}`,
+        ];
+        const advisories = result.advisories;
+        if (advisories && advisories.length > 0) {
+            lines.push('', 'Advisories:');
+            for (const advisory of advisories) {
+                lines.push(`- ${advisory}`);
+            }
+        }
+        lines.push('');
+        return `${lines.join('\n')}\n`;
+    }
+    if (result.subcommand === 'list') {
+        const checkpoints = result.checkpoints;
+        if (checkpoints.length === 0)
+            return 'No recovery checkpoints found.\n';
+        const lines = checkpoints.map((item) => {
+            const diagnostic = formatRecoveryStateDiagnostic(item.state, item.stateDetail);
+            const base = `${item.checkpointId}\t${item.state}\t${item.changeCount} changes\treceipt:${item.receiptHash?.slice(0, 12) ?? '-'}\t${item.createdAt}`;
+            return diagnostic ? `${base}\n  ${diagnostic}` : base;
+        });
+        return `${lines.join('\n')}\n`;
+    }
+    if (result.subcommand === 'show') {
+        const state = result.state;
+        const diagnostic = state?.state !== undefined
+            ? formatRecoveryStateDiagnostic(state.state, state.detail)
+            : null;
+        const payload = diagnostic ? { ...result, diagnostic } : result;
+        return `${JSON.stringify(payload, null, 2)}\n`;
+    }
+    return `${String(result.message ?? 'Recovery command completed.')}\n`;
+}

package/dist/commands/revoke.js

@@ -1,20 +1,32 @@
 import path from 'node:path';
-import { loadApprovalState, loadConfigFile, saveApprovalState } from '../config-io.js';
+import { loadApprovalState, loadConfigFile, pendingApprovalsPath, saveApprovalState, } from '../config-io.js';
 import { compactApprovals } from '../core/approval.js';
+import { mutateApprovalStateWithRetry } from '../core/capability/approval-state-mutation.js';
 export async function revokeApproval(options) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
     const config = await loadConfigFile(repoRoot);
-    const pending = await loadApprovalState(repoRoot, 'pending-approvals.json', config);
-    const compacted = compactApprovals(pending);
-    const index = compacted.approvals.findIndex((approval) => approval.approvalId === options.approvalId);
-    if (index === -1) {
+    const revoked = await mutateApprovalStateWithRetry({
+        load: async () => ({
+            filePath: pendingApprovalsPath(repoRoot, config),
+            state: await loadApprovalState(repoRoot, 'pending-approvals.json', config),
+        }),
+        write: async (_filePath, state) => saveApprovalState(repoRoot, 'pending-approvals.json', state, config),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const index = compacted.approvals.findIndex((approval) => approval.approvalId === options.approvalId);
+            if (index === -1) {
+                return null;
+            }
+            compacted.approvals.splice(index, 1);
+            return { state: compacted, result: true };
+        },
+    });
+    if (revoked !== true) {
         return {
             ok: false,
             message: `Pending approval ${options.approvalId} not found or already expired.`,
         };
     }
-    compacted.approvals.splice(index, 1);
-    await saveApprovalState(repoRoot, 'pending-approvals.json', compacted, config);
     return {
         ok: true,
         message: `Revoked pending approval ${options.approvalId}.`,

package/dist/commands/status.js

@@ -23,6 +23,11 @@ export async function statusProject(options = {}) {
         dogfood: operational.dogfood,
         health,
         visibility,
+        fileCheckpoint: {
+            ...config.policy.transactional.fileCheckpoint,
+            transactionalEnabled: config.policy.transactional.enabled,
+            durableCheckpointEnabled: config.policy.transactional.checkpoint?.enabled === true,
+        },
     };
 }
 export function formatStatusReport(report) {
@@ -51,6 +56,8 @@ export function formatStatusReport(report) {
         `Dogfood: ${report.dogfood.active ? 'active' : 'inactive'} (mode=${report.dogfood.mode}, unknownLocalEffect=${report.dogfood.unknownLocalEffect})`,
         `Metrics: ${report.dogfood.gateEvents} gate events, ${report.dogfood.wouldBlockCount} would-block (${(report.dogfood.wouldBlockRate * 100).toFixed(1)}%)`,
         `Ready for enforce: ${report.dogfood.readyForEnforce ? 'yes' : 'not yet'}`,
+        `File checkpoint: ${report.fileCheckpoint.enabled ? 'enabled' : 'disabled'} (transactional=${report.fileCheckpoint.transactionalEnabled}, durable=${report.fileCheckpoint.durableCheckpointEnabled}, nonGit=${report.fileCheckpoint.allowNonGit})`,
+        `File checkpoint limits: files=${report.fileCheckpoint.maxFiles}, sourceBytes=${report.fileCheckpoint.maxSourceBytes}, workspaceBytes=${report.fileCheckpoint.maxWorkspaceBytes}, prepareTimeoutMs=${report.fileCheckpoint.prepareTimeoutMs}, copyConcurrency=${report.fileCheckpoint.copyConcurrency}`,
         '',
         'Audit visibility:',
         `  Gate events: ${report.visibility.gateEvents}`,

package/dist/config-io.js

@@ -1,8 +1,10 @@
+import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { chmod, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, open, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { getAdapterLayout } from './adapters/layouts/index.js';
 import { compactApprovals, isExpired, mergeApprovalStates } from './core/approval.js';
+import { mutateApprovalStateWithRetry } from './core/capability/approval-state-mutation.js';
 import { approvedApprovalsFile, belayStateDir, configuredControlPlaneDir, mergeConfig, pendingApprovalsFile, } from './core/config.js';
 import { resolveLayeredConfig, teamConfigPath, } from './core/config-layers.js';
 export function resolveAdapterName(config) {
@@ -106,12 +108,32 @@ async function repoLocalApprovalsEmpty(repoRoot, config) {
     return true;
 }
 async function writeApprovalStateFile(filePath, state) {
-    await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
-    await writeFile(filePath, `${JSON.stringify(compactApprovals(state), null, 2)}\n`, {
-        encoding: 'utf8',
-        mode: 0o600,
-    });
-    await chmod(filePath, 0o600);
+    const directory = path.dirname(filePath);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    let handle = null;
+    try {
+        handle = await open(tempPath, 'wx', 0o600);
+        await handle.writeFile(`${JSON.stringify(compactApprovals(state), null, 2)}\n`, 'utf8');
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        await rename(tempPath, filePath);
+        await chmod(filePath, 0o600);
+        const directoryHandle = await open(directory, 'r');
+        try {
+            await directoryHandle.sync().catch(() => undefined);
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+    finally {
+        if (handle) {
+            await handle.close().catch(() => undefined);
+        }
+        await unlink(tempPath).catch(() => undefined);
+    }
 }
 async function migrateApprovalFilesBetween(sourceDir, targetDir) {
     await mkdir(targetDir, { recursive: true, mode: 0o700 });
@@ -121,20 +143,29 @@ async function migrateApprovalFilesBetween(sourceDir, targetDir) {
         if (!existsSync(from)) {
             continue;
         }
-        if (!existsSync(to)) {
-            if (await isCorruptApprovalStateFile(from)) {
-                continue;
-            }
-            await copyFile(from, to);
-            await chmod(to, 0o600);
+        if ((await isCorruptApprovalStateFile(from)) ||
+            (existsSync(to) && (await isCorruptApprovalStateFile(to)))) {
             continue;
         }
-        if ((await isCorruptApprovalStateFile(from)) || (await isCorruptApprovalStateFile(to))) {
-            continue;
-        }
-        const targetState = await readApprovalStateFileStrict(to);
         const sourceState = await readApprovalStateFileStrict(from);
-        await writeApprovalStateFile(to, mergeApprovalStates(targetState, sourceState));
+        const migrated = await mutateApprovalStateWithRetry({
+            load: async () => ({
+                filePath: to,
+                state: existsSync(to)
+                    ? await readApprovalStateFileStrict(to)
+                    : { version: 1, approvals: [] },
+            }),
+            write: writeApprovalStateFile,
+            mutate: (targetState) => ({
+                state: targetState.approvals.length === 0
+                    ? sourceState
+                    : mergeApprovalStates(targetState, sourceState),
+                result: true,
+            }),
+        });
+        if (migrated !== true) {
+            throw new Error(`Failed to migrate approval state to ${to}`);
+        }
     }
 }
 export async function migrateRepoLocalApprovalsToControlPlane(repoRoot, config) {

package/dist/conformance/guarantee-table.js

@@ -65,6 +65,12 @@ export const GUARANTEE_SCENARIOS = {
             command: 'git status',
             permission: 'allow',
         },
+        {
+            id: 'l2-allow-dirty-git-file-checkpoint',
+            command: 'touch notes.txt',
+            permission: 'allow',
+            substrate: 'dirty_git_file_checkpoint',
+        },
         {
             id: 'l2-deny-read-egress',
             command: 'curl https://example.com',

package/dist/conformance/types.d.ts

@@ -5,4 +5,5 @@ export interface LayerConformanceScenario {
     reason?: string;
     kind?: 'shell' | 'tool';
     toolPayload?: Record<string, unknown>;
+    substrate?: 'clean_git_worktree' | 'dirty_git_file_checkpoint' | 'non_git_file_checkpoint';
 }

package/dist/core/approval-replay.d.ts

@@ -40,6 +40,6 @@ export declare function buildReplayEnvelopeFields(input: ReplayEnvelopeInput): P
 export declare function hasReplayEnvelope(approval: ApprovalRecord): boolean;
 export declare function validateReplayEnvelope(approval: ApprovalRecord, action: ReplayActionContext): boolean;
 export declare function canAutoReplay(config: BelayConfigV4, kind: ApprovalRecord['kind'], adapter?: ReplayAdapterId): boolean;
-export declare function buildRetryInstructionForConfig(config: BelayConfigV4, tokenPrefix: string, approvalId: string): string;
+export declare function buildRetryInstructionForConfig(config: BelayConfigV4, tokenPrefix: string, approvalId: string, kind?: ApprovalRecord['kind'], adapter?: ReplayAdapterId): string;
 export declare function buildApprovalRecordedMessage(config: BelayConfigV4, approval: ApprovalRecord, adapter?: ReplayAdapterId): string;
 export declare function buildReplayHint(config: BelayConfigV4, approval: ApprovalRecord, adapter?: ReplayAdapterId): ApprovalReplayHint | null;

package/dist/core/approval-replay.js

@@ -103,7 +103,10 @@ export function canAutoReplay(config, kind, adapter) {
     }
     return kind === 'shell' && scopes?.shell !== false;
 }
-export function buildRetryInstructionForConfig(config, tokenPrefix, approvalId) {
+export function buildRetryInstructionForConfig(config, tokenPrefix, approvalId, kind, adapter) {
+    if (kind === 'shell' && canAutoReplay(config, kind, adapter)) {
+        return `To approve and run this exact shell action once, send ${tokenPrefix} ${approvalId}. No follow-up prompt is required.`;
+    }
     if (approvalFlow(config) === 'one_step') {
         return `To allow this action once, send ${tokenPrefix} ${approvalId}. After approval, retry the same action unchanged.`;
     }

package/dist/core/approval-service.d.ts

@@ -26,11 +26,16 @@ export declare function recordApproval(params: {
     message: string;
     approval?: ApprovalStateFile['approvals'][number];
 }>;
-/** CLI `--replay` already executed the shell command; drop the one-shot grant. */
+/** @deprecated Replay callers must claim before execution with `claimApprovedForReplay`. */
 export declare function consumeApprovedAfterCliReplay(params: {
     approvalId: string;
     store: ApprovalStore;
 }): Promise<void>;
+/** Atomically spend and return a one-shot approval before executing its replay. */
+export declare function claimApprovedForReplay(params: {
+    approvalId: string;
+    store: ApprovalStore;
+}): Promise<ApprovalStateFile['approvals'][number] | null>;
 export declare function createGateApprovalStore(repoRoot: string, config: BelayConfigV3): ApprovalStore;
 export declare function gateApprovalStoreFromDeps(deps: {
     loadApprovals: (fileName: 'pending-approvals.json' | 'approved-approvals.json') => Promise<{