@guilz-dev/belay 0.3.0 → 0.4.0

package/dist/commands/tui.js

@@ -0,0 +1,150 @@
+/**
+ * Zero-dependency terminal UI helpers for the interactive `belay config` wizard.
+ *
+ * Everything here is built on Node's built-in `readline`/`tty` only — no runtime
+ * dependencies — so it stays aligned with belay's zero-dependency posture.
+ *
+ * This module is intentionally TTY-only. Callers are responsible for non-TTY
+ * fallback behavior.
+ */
+import { stdin as input, stdout as output } from 'node:process';
+import readline from 'node:readline';
+const isColorEnabled = () => isInteractiveTTY() && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+const symbol = (pretty, plain) => (isColorEnabled() ? pretty : plain);
+const wrap = (open, close) => (s) => isColorEnabled() ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+export const c = {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    italic: wrap(3, 23),
+    underline: wrap(4, 24),
+    inverse: wrap(7, 27),
+    cyan: wrap(36, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    red: wrap(31, 39),
+    gray: wrap(90, 39),
+};
+/** A select wizard only makes sense when both stdin and stdout are real TTYs. */
+export function isInteractiveTTY() {
+    return Boolean(input.isTTY && output.isTTY);
+}
+const symPointer = () => symbol('❯', '>');
+const symCheck = () => symbol('✓', 'v');
+const symBar = () => symbol('│', '|');
+const symQuestion = () => '?';
+/** Top banner shown once at the start of the wizard. */
+export function intro(title, subtitle) {
+    output.write('\n');
+    output.write(`${c.green(symBar())} ${c.bold(title)}\n`);
+    if (subtitle) {
+        output.write(`${c.green(symBar())} ${c.dim(subtitle)}\n`);
+    }
+    output.write(`${c.green(symBar())}\n`);
+}
+/** Closing line shown once at the end of the wizard. */
+export function outro(message) {
+    output.write(`${c.green(symBar())}\n`);
+    output.write(`${c.green(symCheck())} ${message}\n\n`);
+}
+/** Collapsed one-line summary of an answered question. */
+export function summary(label, value) {
+    output.write(`${c.green(symCheck())} ${c.dim(label)}  ${c.cyan(value)}\n`);
+}
+/**
+ * Interactive single-choice prompt driven by arrow keys (or j/k). Resolves with
+ * the selected choice value. Must only be called in an interactive TTY.
+ */
+export function selectPrompt(opts) {
+    if (!isInteractiveTTY()) {
+        throw new Error('selectPrompt requires an interactive TTY.');
+    }
+    const { message, choices } = opts;
+    if (choices.length === 0) {
+        throw new Error('selectPrompt requires at least one choice.');
+    }
+    const startIndex = Math.max(0, choices.findIndex((ch) => ch.value === opts.defaultValue));
+    return new Promise((resolve, reject) => {
+        let index = startIndex;
+        let rendered = 0;
+        const lineFor = (ch, active) => {
+            const label = ch.label ?? ch.value;
+            if (active) {
+                const hint = ch.hint ? ` ${c.dim(ch.hint)}` : '';
+                return `${c.cyan(symPointer())} ${c.cyan(c.underline(label))}${hint}`;
+            }
+            return `  ${c.dim(label)}`;
+        };
+        const clearRendered = () => {
+            if (rendered > 0) {
+                output.write(`\x1b[${rendered}A`);
+            }
+            output.write('\x1b[J');
+        };
+        const render = () => {
+            clearRendered();
+            const lines = [
+                `${c.green(symQuestion())} ${c.bold(message)}`,
+                ...choices.map((ch, i) => lineFor(ch, i === index)),
+            ];
+            output.write(`${lines.join('\n')}\n`);
+            rendered = lines.length;
+        };
+        const cleanup = () => {
+            input.off('keypress', onKey);
+            if (input.isTTY && typeof input.setRawMode === 'function') {
+                input.setRawMode(false);
+            }
+            input.pause();
+            output.write('\x1b[?25h'); // show cursor
+        };
+        const finish = () => {
+            clearRendered();
+            cleanup();
+            const chosen = choices[index];
+            summary(message, chosen.label ?? chosen.value);
+            resolve(chosen.value);
+        };
+        const onKey = (_str, key) => {
+            if (!key)
+                return;
+            if (key.ctrl && key.name === 'c') {
+                clearRendered();
+                cleanup();
+                output.write('\n');
+                reject(new Error('Cancelled.'));
+                return;
+            }
+            if (key.name === 'up' || key.name === 'k') {
+                index = (index - 1 + choices.length) % choices.length;
+                render();
+            }
+            else if (key.name === 'down' || key.name === 'j') {
+                index = (index + 1) % choices.length;
+                render();
+            }
+            else if (key.name === 'return' || key.name === 'enter') {
+                finish();
+            }
+        };
+        readline.emitKeypressEvents(input);
+        if (input.isTTY && typeof input.setRawMode === 'function') {
+            input.setRawMode(true);
+        }
+        input.resume();
+        output.write('\x1b[?25l'); // hide cursor
+        input.on('keypress', onKey);
+        render();
+    });
+}
+/** Interactive yes/no prompt rendered as a two-row arrow-key selection. */
+export async function confirmPrompt(message, defaultValue) {
+    const value = await selectPrompt({
+        message,
+        defaultValue: defaultValue ? 'yes' : 'no',
+        choices: [
+            { value: 'yes', label: 'Yes' },
+            { value: 'no', label: 'No' },
+        ],
+    });
+    return value === 'yes';
+}

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,7 +42,7 @@ 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'];
@@ -75,11 +75,15 @@ async function readApprovalStateFile(filePath) {
     };
 }
 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);
@@ -88,6 +92,7 @@ async function migrateApprovalFilesBetween(sourceDir, targetDir) {
         }
         if (!existsSync(to)) {
             await copyFile(from, to);
+            await chmod(to, 0o600);
             continue;
         }
         const targetState = await readApprovalStateFile(to);

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,10 @@
+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 { 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);
@@ -35,7 +37,50 @@ export async function recordApproval(params) {
     await store.writeApproved(approved.filePath, approved.state);
     return {
         ok: true,
-        message: `Belay approval recorded for ${approvalId}. Retry the original action once before it expires.`,
+        message: buildApprovalRecordedMessage(config, approval, adapter),
         approval,
     };
 }
+/** 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,23 @@ 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'];
+}): ApprovalRecord;
 export declare function createApprovalRecord(params: {
     kind: ApprovalRecord['kind'];
     fingerprint: string;
@@ -19,4 +35,9 @@ export declare function createApprovalRecord(params: {
     approvalId: string;
     input?: string;
     inputKind?: 'shell' | 'tool' | 'subagent';
+    cwd?: string;
+    toolName?: string;
+    payloadHash?: string;
+    payloadJson?: string;
+    scopeHint?: ApprovalRecord['scopeHint'];
 }): ApprovalRecord;

package/dist/core/approval.js

@@ -1,5 +1,7 @@
-/** Cursor may invoke the same shell gate more than once per retry; lease covers that window. */
-export const APPROVAL_EXECUTION_LEASE_MS = 60_000;
+import { buildReplayEnvelopeFields } from './approval-replay.js';
+import { DEFAULT_APPROVAL_CONFIG } from './config.js';
+/** @deprecated Use `DEFAULT_APPROVAL_CONFIG.executionLeaseMs` */
+export const APPROVAL_EXECUTION_LEASE_MS = DEFAULT_APPROVAL_CONFIG.executionLeaseMs;
 export function nowIso() {
     return new Date().toISOString();
 }
@@ -49,8 +51,34 @@ export function approvalCommandMatch(prompt, tokenPrefix) {
     }
     return null;
 }
-export function buildRetryInstruction(tokenPrefix, approvalId) {
-    return `To allow the next matching action once, send ${tokenPrefix} ${approvalId} and then retry the original action unchanged.`;
+export function createApprovalRecordWithEnvelope(params) {
+    const envelope = buildReplayEnvelopeFields({
+        kind: params.kind,
+        command: params.approvalInput?.input,
+        input: params.approvalInput?.input,
+        inputKind: params.approvalInput?.inputKind,
+        cwd: params.approvalInput?.cwd,
+        toolName: params.approvalInput?.toolName,
+        payload: params.approvalInput?.payload,
+        fingerprint: params.fingerprint,
+        repoRoot: params.repoRoot,
+    });
+    return createApprovalRecord({
+        kind: params.kind,
+        fingerprint: params.fingerprint,
+        repoRoot: params.repoRoot,
+        reason: params.reason,
+        summary: params.summary,
+        approvalTtlMinutes: params.approvalTtlMinutes,
+        approvalId: params.approvalId,
+        input: envelope.input ?? params.approvalInput?.input,
+        inputKind: envelope.inputKind ?? params.approvalInput?.inputKind,
+        cwd: envelope.cwd,
+        toolName: envelope.toolName ?? params.approvalInput?.toolName,
+        payloadHash: envelope.payloadHash,
+        payloadJson: envelope.payloadJson,
+        scopeHint: params.scopeHint,
+    });
 }
 export function createApprovalRecord(params) {
     const createdAt = nowIso();
@@ -69,5 +97,20 @@ export function createApprovalRecord(params) {
         record.input = params.input;
         record.inputKind = params.inputKind ?? params.kind;
     }
+    if (params.cwd) {
+        record.cwd = params.cwd;
+    }
+    if (params.toolName) {
+        record.toolName = params.toolName;
+    }
+    if (params.payloadHash) {
+        record.payloadHash = params.payloadHash;
+    }
+    if (params.payloadJson) {
+        record.payloadJson = params.payloadJson;
+    }
+    if (params.scopeHint) {
+        record.scopeHint = params.scopeHint;
+    }
     return record;
 }

package/dist/core/audit-analysis.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRoundTrip, AuditRecord, BypassAttempt, NoisyRuleCandidate } from './audit-types.js';
+import type { ApprovalRoundTrip, AuditRecord, AvailabilityAskCounts, BypassAttempt, NoisyRuleCandidate, ReasonApprovalRatio, RepeatedFingerprintAsk } from './audit-types.js';
 export declare function detectBypassAttempts(records: AuditRecord[], windowMs?: number): BypassAttempt[];
 export declare function detectNoisyRules(records: AuditRecord[], roundTrips: ApprovalRoundTrip[], minDenies?: number): NoisyRuleCandidate[];
 export declare function computeApprovalLatencyStats(roundTrips: ApprovalRoundTrip[]): {
@@ -8,3 +8,9 @@ export declare function computeApprovalLatencyStats(roundTrips: ApprovalRoundTri
 };
 export declare function bucketGateEventsByDay(records: AuditRecord[]): Record<string, number>;
 export declare function countVerdicts(records: AuditRecord[]): Record<string, number>;
+export declare function computeWouldBlockByReason(records: AuditRecord[]): Record<string, number>;
+/** Approval ratios are candidate signals from operator behavior — not corpus ground truth. */
+export declare function computeApprovalRatioByReason(records: AuditRecord[], roundTrips: ApprovalRoundTrip[]): ReasonApprovalRatio[];
+export declare function isAvailabilityCausedAsk(record: AuditRecord): boolean;
+export declare function computeAvailabilityAskCounts(records: AuditRecord[]): AvailabilityAskCounts;
+export declare function computeRepeatedFingerprintAsks(records: AuditRecord[], minCount?: number, limit?: number): RepeatedFingerprintAsk[];