@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/config-io.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmod, copyFile, mkdir, readFile, 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';
@@ -42,13 +42,49 @@ export function approvedApprovalsPath(repoRoot, config) {
 export { belayStateDir };
 export async function ensureBelayStateDir(config, repoRoot) {
     const stateDir = belayStateDir(config, repoLocalStateDirFor(repoRoot, config));
-    await mkdir(stateDir, { recursive: true });
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
     return stateDir;
 }
 const APPROVAL_STATE_FILES = ['pending-approvals.json', 'approved-approvals.json'];
 function approvalFilesExist(dir) {
     return APPROVAL_STATE_FILES.some((fileName) => existsSync(path.join(dir, fileName)));
 }
+async function isCorruptApprovalStateFile(filePath) {
+    const raw = await readFile(filePath, 'utf8');
+    try {
+        JSON.parse(raw);
+        return false;
+    }
+    catch (error) {
+        return error instanceof SyntaxError;
+    }
+}
+function normalizeApprovalStateFile(parsed) {
+    const version = parsed.version === 3 ? 3 : parsed.version === 2 ? 2 : 1;
+    return {
+        version,
+        revision: typeof parsed.revision === 'number' ? parsed.revision : undefined,
+        approvals: Array.isArray(parsed.approvals) ? parsed.approvals : [],
+    };
+}
+/** Gate reads: corrupt JSON is treated as empty state (fail-closed). */
+async function readApprovalStateFileForGate(filePath) {
+    const raw = await readFile(filePath, 'utf8');
+    try {
+        return normalizeApprovalStateFile(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return { version: 1, approvals: [] };
+        }
+        throw error;
+    }
+}
+/** Migration reads: corrupt JSON must not be treated as empty. */
+async function readApprovalStateFileStrict(filePath) {
+    const raw = await readFile(filePath, 'utf8');
+    return normalizeApprovalStateFile(JSON.parse(raw));
+}
 async function repoLocalApprovalsEmpty(repoRoot, config) {
     const repoLocalDir = repoLocalStateDirFor(repoRoot, config);
     if (!approvalFilesExist(repoLocalDir)) {
@@ -59,27 +95,26 @@ async function repoLocalApprovalsEmpty(repoRoot, config) {
         if (!existsSync(filePath)) {
             continue;
         }
-        const state = await readApprovalStateFile(filePath);
+        if (await isCorruptApprovalStateFile(filePath)) {
+            return false;
+        }
+        const state = await readApprovalStateFileForGate(filePath);
         if (state.approvals.length > 0) {
             return false;
         }
     }
     return true;
 }
-async function readApprovalStateFile(filePath) {
-    const raw = await readFile(filePath, 'utf8');
-    const parsed = JSON.parse(raw);
-    return {
-        version: parsed.version === 2 ? 2 : 1,
-        approvals: Array.isArray(parsed.approvals) ? parsed.approvals : [],
-    };
-}
 async function writeApprovalStateFile(filePath, state) {
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, `${JSON.stringify(compactApprovals(state), null, 2)}\n`, 'utf8');
+    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);
 }
 async function migrateApprovalFilesBetween(sourceDir, targetDir) {
-    await mkdir(targetDir, { recursive: true });
+    await mkdir(targetDir, { recursive: true, mode: 0o700 });
     for (const fileName of APPROVAL_STATE_FILES) {
         const from = path.join(sourceDir, fileName);
         const to = path.join(targetDir, fileName);
@@ -87,11 +122,18 @@ async function migrateApprovalFilesBetween(sourceDir, targetDir) {
             continue;
         }
         if (!existsSync(to)) {
+            if (await isCorruptApprovalStateFile(from)) {
+                continue;
+            }
             await copyFile(from, to);
+            await chmod(to, 0o600);
+            continue;
+        }
+        if ((await isCorruptApprovalStateFile(from)) || (await isCorruptApprovalStateFile(to))) {
             continue;
         }
-        const targetState = await readApprovalStateFile(to);
-        const sourceState = await readApprovalStateFile(from);
+        const targetState = await readApprovalStateFileStrict(to);
+        const sourceState = await readApprovalStateFileStrict(from);
         await writeApprovalStateFile(to, mergeApprovalStates(targetState, sourceState));
     }
 }
@@ -167,7 +209,7 @@ export async function loadApprovalState(repoRoot, fileName, config) {
     if (!existsSync(filePath)) {
         return { version: 1, approvals: [] };
     }
-    return readApprovalStateFile(filePath);
+    return readApprovalStateFileForGate(filePath);
 }
 export async function saveApprovalState(repoRoot, fileName, state, config) {
     const filePath = fileName === 'pending-approvals.json'

package/dist/conformance/guarantee-posture.d.ts

@@ -0,0 +1,21 @@
+import type { BoundaryAttestation } from '../core/capability/attestation.js';
+import type { BelayConfigV4 } from '../core/config.js';
+import type { LayerProfileId } from './types.js';
+export interface GuaranteePosture {
+    configuredProfile: LayerProfileId;
+    attestedProfile: LayerProfileId;
+    attestationFresh: boolean;
+    l1FullConfigured: boolean;
+    l1FullAttested: boolean;
+    postureMismatch: boolean;
+}
+export declare function resolveConfiguredProfile(config: BelayConfigV4, egressProxyRunning: boolean): LayerProfileId;
+export declare function resolveAttestedProfile(params: {
+    attestation: BoundaryAttestation | null;
+    l1FullConfigured: boolean;
+}): LayerProfileId;
+export declare function evaluateGuaranteePosture(params: {
+    config: BelayConfigV4;
+    attestation: BoundaryAttestation | null;
+    egressProxyRunning: boolean;
+}): GuaranteePosture;

package/dist/conformance/guarantee-posture.js

@@ -0,0 +1,46 @@
+import { isAttestationFresh } from '../core/capability/attestation.js';
+import { evaluateL1FullStatus } from '../core/capability/broker.js';
+export function resolveConfiguredProfile(config, egressProxyRunning) {
+    const l1Full = evaluateL1FullStatus({ config, egressProxyRunning });
+    if (l1Full.active) {
+        return 'l1-full';
+    }
+    if (config.egress.enabled) {
+        return 'l1-partial-egress';
+    }
+    if (config.policy.transactional.enabled) {
+        return 'l1-l2-transactional';
+    }
+    return 'l3-l4-only';
+}
+export function resolveAttestedProfile(params) {
+    if (!params.attestation || !isAttestationFresh(params.attestation)) {
+        return 'l3-l4-only';
+    }
+    if (params.l1FullConfigured &&
+        params.attestation.deniesUngrantedEffects &&
+        params.attestation.materializesGrants) {
+        return 'l1-full';
+    }
+    return 'l3-l4-only';
+}
+export function evaluateGuaranteePosture(params) {
+    const l1Full = evaluateL1FullStatus({
+        config: params.config,
+        egressProxyRunning: params.egressProxyRunning,
+    });
+    const configuredProfile = resolveConfiguredProfile(params.config, params.egressProxyRunning);
+    const attestedProfile = resolveAttestedProfile({
+        attestation: params.attestation,
+        l1FullConfigured: l1Full.active,
+    });
+    return {
+        configuredProfile,
+        attestedProfile,
+        attestationFresh: params.attestation ? isAttestationFresh(params.attestation) : false,
+        l1FullConfigured: l1Full.active,
+        l1FullAttested: attestedProfile === 'l1-full' &&
+            Boolean(params.attestation?.deniesUngrantedEffects && params.attestation.materializesGrants),
+        postureMismatch: configuredProfile === 'l1-full' && attestedProfile !== 'l1-full',
+    };
+}

package/dist/conformance/guarantee-table.d.ts

@@ -1,4 +1,5 @@
 import type { LayerConformanceScenario, LayerProfileId } from './types.js';
+export { evaluateGuaranteePosture, type GuaranteePosture } from './guarantee-posture.js';
 export type { LayerConformanceScenario, LayerProfileId } from './types.js';
 export interface GuaranteeTableRow {
     profile: LayerProfileId;

package/dist/conformance/guarantee-table.js

@@ -1,3 +1,4 @@
+export { evaluateGuaranteePosture } from './guarantee-posture.js';
 /** Normative rows — keep in sync with docs/guarantee-table.md */
 export const GUARANTEE_TABLE_ROWS = [
     {
@@ -33,9 +34,10 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l3-allow-read-egress',
+            id: 'l3-deny-read-egress',
             command: 'curl https://example.com',
-            permission: 'allow',
+            permission: 'deny',
+            reason: 'external_effect',
         },
     ],
     'l1-partial-egress': [
@@ -45,9 +47,10 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l1p-allow-read-egress',
+            id: 'l1p-deny-read-egress',
             command: 'curl https://example.com',
-            permission: 'allow',
+            permission: 'deny',
+            reason: 'external_effect',
         },
         {
             id: 'l1p-deny-write-egress',
@@ -63,9 +66,10 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l2-allow-read-egress',
+            id: 'l2-deny-read-egress',
             command: 'curl https://example.com',
-            permission: 'allow',
+            permission: 'deny',
+            reason: 'external_effect',
         },
     ],
     'l1-full': [
@@ -75,9 +79,10 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l1f-allow-read-egress',
+            id: 'l1f-deny-read-egress',
             command: 'curl https://example.com',
-            permission: 'allow',
+            permission: 'deny',
+            reason: 'external_effect',
         },
         {
             id: 'l1f-deny-write-egress',
@@ -90,7 +95,7 @@ export const GUARANTEE_SCENARIOS = {
             id: 'l1f-deny-outside-repo',
             command: 'echo hi > ../../outside.txt',
             permission: 'deny',
-            reason: 'outside_repo_redirect',
+            reason: 'outside_repo_mutation',
         },
         {
             id: 'l1f-deny-outside-repo-write',

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

@@ -0,0 +1,7 @@
+export declare const DEFAULT_CLI_REPLAY_TIMEOUT_MS = 300000;
+export declare function replayShellCommand(command: string, cwd: string, timeoutMs?: number): Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}>;

package/dist/core/approval-replay-cli.js

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+export const DEFAULT_CLI_REPLAY_TIMEOUT_MS = 300_000;
+export async function replayShellCommand(command, cwd, timeoutMs = DEFAULT_CLI_REPLAY_TIMEOUT_MS) {
+    const resolvedCwd = path.resolve(cwd);
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, {
+            cwd: resolvedCwd,
+            shell: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env },
+        });
+        const stdout = [];
+        const stderr = [];
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.stdout?.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
+        child.stderr?.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: timedOut ? 124 : (code ?? 1),
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                ...(timedOut ? { timedOut: true } : {}),
+            });
+        });
+    });
+}

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

@@ -0,0 +1,45 @@
+import type { ApprovalFlow, BelayConfigV4 } from './config.js';
+import type { ApprovalRecord } from './types.js';
+export type { ApprovalFlow } from './config.js';
+export type ReplayAdapterId = 'cursor' | 'claude' | 'codex';
+export { DEFAULT_CLI_REPLAY_TIMEOUT_MS, replayShellCommand } from './approval-replay-cli.js';
+export interface ApprovalReplayHint {
+    kind: 'shell' | 'tool' | 'subagent';
+    input: string;
+    cwd?: string;
+    toolName?: string;
+    fingerprint: string;
+    approvalId: string;
+    autoReplay: boolean;
+    fallbackToTwoStep: boolean;
+}
+export interface ReplayEnvelopeInput {
+    kind: ApprovalRecord['kind'];
+    cwd?: string;
+    toolName?: string;
+    command?: string;
+    input?: string;
+    inputKind?: 'shell' | 'tool' | 'subagent';
+    payload?: Record<string, unknown>;
+    fingerprint: string;
+    repoRoot: string;
+}
+export interface ReplayActionContext {
+    kind: ApprovalRecord['kind'];
+    cwd?: string;
+    toolName?: string;
+    command?: string;
+    payload?: Record<string, unknown>;
+    fingerprint: string;
+    repoRoot: string;
+}
+export declare function replayPayloadHash(kind: ApprovalRecord['kind'], payload: Record<string, unknown> | undefined, repoRoot: string): string | undefined;
+export declare function getExecutionLeaseMs(config: BelayConfigV4): number;
+export declare function approvalFlow(config: BelayConfigV4): ApprovalFlow;
+export declare function buildReplayEnvelopeFields(input: ReplayEnvelopeInput): Partial<ApprovalRecord>;
+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 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

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import { canonicalStringify, hashValue } from './fingerprint.js';
+export { DEFAULT_CLI_REPLAY_TIMEOUT_MS, replayShellCommand } from './approval-replay-cli.js';
+const MAX_PAYLOAD_JSON_BYTES = 16_384;
+export function replayPayloadHash(kind, payload, repoRoot) {
+    if (!payload || Object.keys(payload).length === 0) {
+        return undefined;
+    }
+    const json = canonicalStringify(payload);
+    return hashValue(`payload:${kind}:${json}:${repoRoot}`);
+}
+const DEFAULT_REPLAY_CAPABILITIES = {
+    shell: true,
+    tool: false,
+    subagent: false,
+};
+const ADAPTER_REPLAY_CAPABLE = {
+    cursor: { ...DEFAULT_REPLAY_CAPABILITIES },
+    claude: { ...DEFAULT_REPLAY_CAPABILITIES },
+    codex: { ...DEFAULT_REPLAY_CAPABILITIES },
+};
+export function getExecutionLeaseMs(config) {
+    const ms = config.approval?.executionLeaseMs;
+    return typeof ms === 'number' && ms > 0 ? ms : 60_000;
+}
+export function approvalFlow(config) {
+    return config.approval?.flow === 'two_step' ? 'two_step' : 'one_step';
+}
+export function buildReplayEnvelopeFields(input) {
+    const fields = {};
+    const cmd = input.command ?? input.input ?? '';
+    if (cmd) {
+        fields.input = cmd;
+        fields.inputKind = input.inputKind ?? input.kind;
+    }
+    if (input.cwd) {
+        fields.cwd = path.resolve(input.cwd);
+    }
+    if (input.toolName) {
+        fields.toolName = input.toolName;
+    }
+    if (input.payload && Object.keys(input.payload).length > 0) {
+        const json = canonicalStringify(input.payload);
+        if (Buffer.byteLength(json, 'utf8') <= MAX_PAYLOAD_JSON_BYTES) {
+            fields.payloadJson = json;
+        }
+        fields.payloadHash = replayPayloadHash(input.kind, input.payload, input.repoRoot);
+    }
+    return fields;
+}
+export function hasReplayEnvelope(approval) {
+    return Boolean(approval.cwd || approval.toolName || approval.payloadHash);
+}
+export function validateReplayEnvelope(approval, action) {
+    if (!hasReplayEnvelope(approval)) {
+        return true;
+    }
+    if (approval.kind !== action.kind) {
+        return false;
+    }
+    if (approval.fingerprint !== action.fingerprint) {
+        return false;
+    }
+    if (approval.repoRoot !== action.repoRoot) {
+        return false;
+    }
+    if (approval.cwd && path.resolve(approval.cwd) !== path.resolve(action.cwd ?? '')) {
+        return false;
+    }
+    if (approval.toolName && approval.toolName !== action.toolName) {
+        return false;
+    }
+    if (approval.payloadHash) {
+        const hash = replayPayloadHash(action.kind, action.payload, action.repoRoot);
+        if (!hash || approval.payloadHash !== hash) {
+            return false;
+        }
+    }
+    return true;
+}
+export function canAutoReplay(config, kind, adapter) {
+    if (config.approvalSigning?.required) {
+        return false;
+    }
+    if (approvalFlow(config) !== 'one_step') {
+        return false;
+    }
+    if (kind !== 'shell' && kind !== 'tool' && kind !== 'subagent') {
+        return false;
+    }
+    const scopes = config.approval?.autoReplayScopes;
+    if (kind === 'shell' && scopes?.shell === false) {
+        return false;
+    }
+    if (kind === 'tool' && scopes?.tool !== true) {
+        return false;
+    }
+    if (kind === 'subagent' && scopes?.subagent !== true) {
+        return false;
+    }
+    if (adapter) {
+        return ADAPTER_REPLAY_CAPABLE[adapter][kind] === true;
+    }
+    return kind === 'shell' && scopes?.shell !== false;
+}
+export function buildRetryInstructionForConfig(config, tokenPrefix, approvalId) {
+    if (approvalFlow(config) === 'one_step') {
+        return `To allow this action once, send ${tokenPrefix} ${approvalId}. After approval, retry the same action unchanged.`;
+    }
+    return `To allow the next matching action once, send ${tokenPrefix} ${approvalId} and then retry the original action unchanged.`;
+}
+export function buildApprovalRecordedMessage(config, approval, adapter) {
+    if (!canAutoReplay(config, approval.kind, adapter)) {
+        return `Belay approval recorded for ${approval.approvalId}. Retry the original action once before it expires.`;
+    }
+    if (approval.kind === 'shell' && approval.input) {
+        return (`Belay approval recorded for ${approval.approvalId}. ` +
+            `Retry this shell command unchanged: ${approval.input}`);
+    }
+    return `Belay approval recorded for ${approval.approvalId}. Retry the original action once before it expires.`;
+}
+export function buildReplayHint(config, approval, adapter) {
+    if (approvalFlow(config) !== 'one_step') {
+        return null;
+    }
+    const input = approval.input ?? approval.summary;
+    if (!input) {
+        return null;
+    }
+    const autoReplay = canAutoReplay(config, approval.kind, adapter);
+    return {
+        kind: approval.kind,
+        input,
+        cwd: approval.cwd,
+        toolName: approval.toolName,
+        fingerprint: approval.fingerprint,
+        approvalId: approval.approvalId,
+        autoReplay,
+        fallbackToTwoStep: !autoReplay,
+    };
+}

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

@@ -1,3 +1,4 @@
+import { type ReplayAdapterId } from './approval-replay.js';
 import type { BelayConfigV3 } from './config.js';
 import type { ApprovalStateFile } from './types.js';
 export interface ApprovalStore {
@@ -19,8 +20,22 @@ export declare function recordApproval(params: {
     token?: string;
     /** When true, require a signed token (out-of-band CLI path). Editor prompts skip this. */
     requireSignedToken?: boolean;
+    adapter?: ReplayAdapterId;
 }): Promise<{
     ok: boolean;
     message: string;
     approval?: ApprovalStateFile['approvals'][number];
 }>;
+/** CLI `--replay` already executed the shell command; drop the one-shot grant. */
+export declare function consumeApprovedAfterCliReplay(params: {
+    approvalId: string;
+    store: ApprovalStore;
+}): Promise<void>;
+export declare function createGateApprovalStore(repoRoot: string, config: BelayConfigV3): ApprovalStore;
+export declare function gateApprovalStoreFromDeps(deps: {
+    loadApprovals: (fileName: 'pending-approvals.json' | 'approved-approvals.json') => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    writeApprovals: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+}): ApprovalStore;

package/dist/core/approval-service.js

@@ -1,8 +1,11 @@
+import { approvedApprovalsPath, loadApprovalState, pendingApprovalsPath, saveApprovalState, } from '../config-io.js';
 import { compactApprovals } from './approval.js';
+import { buildApprovalRecordedMessage } from './approval-replay.js';
 import { verifyApprovalToken } from './approval-token.js';
+import { APPROVAL_STATE_VERSION_V3, mintGrantForApprovedRecord } from './capability/approval-v3.js';
 import { configuredControlPlaneDir } from './config.js';
 export async function recordApproval(params) {
-    const { approvalId, config, store, token, requireSignedToken = false } = params;
+    const { approvalId, config, store, token, requireSignedToken = false, adapter } = params;
     const pending = await store.loadPending();
     pending.state = compactApprovals(pending.state);
     const index = pending.state.approvals.findIndex((approval) => approval.approvalId === approvalId);
@@ -28,14 +31,60 @@ export async function recordApproval(params) {
     await store.writePending(pending.filePath, pending.state);
     const approved = await store.loadApproved();
     approved.state = compactApprovals(approved.state);
-    approved.state.approvals.push({
+    const approvedRecord = mintGrantForApprovedRecord({
         ...approval,
         approvedAt: new Date().toISOString(),
     });
+    approved.state.version = APPROVAL_STATE_VERSION_V3;
+    approved.state.revision = (approved.state.revision ?? 0) + 1;
+    approved.state.approvals.push(approvedRecord);
     await store.writeApproved(approved.filePath, approved.state);
     return {
         ok: true,
-        message: `Belay approval recorded for ${approvalId}. Retry the original action once before it expires.`,
-        approval,
+        message: buildApprovalRecordedMessage(config, approval, adapter),
+        approval: approvedRecord,
+    };
+}
+/** CLI `--replay` already executed the shell command; drop the one-shot grant. */
+export async function consumeApprovedAfterCliReplay(params) {
+    const approved = await params.store.loadApproved();
+    approved.state = compactApprovals(approved.state);
+    const remaining = approved.state.approvals.filter((approval) => approval.approvalId !== params.approvalId);
+    if (remaining.length === approved.state.approvals.length) {
+        return;
+    }
+    approved.state.approvals = remaining;
+    await params.store.writeApproved(approved.filePath, approved.state);
+}
+export function createGateApprovalStore(repoRoot, config) {
+    return {
+        async loadPending() {
+            const filePath = pendingApprovalsPath(repoRoot, config);
+            return {
+                filePath,
+                state: await loadApprovalState(repoRoot, 'pending-approvals.json', config),
+            };
+        },
+        async loadApproved() {
+            const filePath = approvedApprovalsPath(repoRoot, config);
+            return {
+                filePath,
+                state: await loadApprovalState(repoRoot, 'approved-approvals.json', config),
+            };
+        },
+        async writePending(_filePath, state) {
+            await saveApprovalState(repoRoot, 'pending-approvals.json', state, config);
+        },
+        async writeApproved(_filePath, state) {
+            await saveApprovalState(repoRoot, 'approved-approvals.json', state, config);
+        },
+    };
+}
+export function gateApprovalStoreFromDeps(deps) {
+    return {
+        loadPending: () => deps.loadApprovals('pending-approvals.json'),
+        loadApproved: () => deps.loadApprovals('approved-approvals.json'),
+        writePending: (filePath, state) => deps.writeApprovals(filePath, state),
+        writeApproved: (filePath, state) => deps.writeApprovals(filePath, state),
     };
 }

package/dist/core/approval.d.ts

@@ -1,6 +1,6 @@
 import type { ApprovalRecord, ApprovalStateFile } from './types.js';
-/** Cursor may invoke the same shell gate more than once per retry; lease covers that window. */
-export declare const APPROVAL_EXECUTION_LEASE_MS = 60000;
+/** @deprecated Use `DEFAULT_APPROVAL_CONFIG.executionLeaseMs` */
+export declare const APPROVAL_EXECUTION_LEASE_MS: number;
 export declare function nowIso(): string;
 export declare function isExpired(approval: ApprovalRecord): boolean;
 export declare function isExecutionLeaseExpired(approval: ApprovalRecord): boolean;
@@ -8,7 +8,24 @@ export declare function compactApprovals(state: ApprovalStateFile): ApprovalStat
 export declare function mergeApprovalStates(target: ApprovalStateFile, source: ApprovalStateFile): ApprovalStateFile;
 export declare function escapeRegex(value: string): string;
 export declare function approvalCommandMatch(prompt: string, tokenPrefix: string): string | null;
-export declare function buildRetryInstruction(tokenPrefix: string, approvalId: string): string;
+export declare function createApprovalRecordWithEnvelope(params: {
+    kind: ApprovalRecord['kind'];
+    fingerprint: string;
+    repoRoot: string;
+    reason: string;
+    summary: string;
+    approvalTtlMinutes: number;
+    approvalId: string;
+    approvalInput?: {
+        input: string;
+        inputKind: 'shell' | 'tool' | 'subagent';
+        cwd?: string;
+        toolName?: string;
+        payload?: Record<string, unknown>;
+    };
+    scopeHint?: ApprovalRecord['scopeHint'];
+    capabilityRequests?: ApprovalRecord['capabilityRequests'];
+}): ApprovalRecord;
 export declare function createApprovalRecord(params: {
     kind: ApprovalRecord['kind'];
     fingerprint: string;
@@ -19,4 +36,10 @@ export declare function createApprovalRecord(params: {
     approvalId: string;
     input?: string;
     inputKind?: 'shell' | 'tool' | 'subagent';
+    cwd?: string;
+    toolName?: string;
+    payloadHash?: string;
+    payloadJson?: string;
+    scopeHint?: ApprovalRecord['scopeHint'];
+    capabilityRequests?: ApprovalRecord['capabilityRequests'];
 }): ApprovalRecord;