@guilz-dev/belay 0.2.0 → 0.4.0

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[];

package/dist/core/audit-analysis.js

@@ -145,3 +145,114 @@ export function countVerdicts(records) {
     }
     return counts;
 }
+export function computeWouldBlockByReason(records) {
+    const counts = {};
+    for (const record of records) {
+        if (!isGateRecord(record) || !inferWouldBlock(record)) {
+            continue;
+        }
+        const reason = record.reason ?? 'unknown';
+        counts[reason] = (counts[reason] ?? 0) + 1;
+    }
+    return counts;
+}
+/** Approval ratios are candidate signals from operator behavior — not corpus ground truth. */
+export function computeApprovalRatioByReason(records, roundTrips) {
+    const wouldBlockByReason = new Map();
+    const approvedByReason = new Map();
+    for (const record of records) {
+        if (!isGateRecord(record) || !inferWouldBlock(record)) {
+            continue;
+        }
+        const reason = record.reason ?? 'unknown';
+        wouldBlockByReason.set(reason, (wouldBlockByReason.get(reason) ?? 0) + 1);
+    }
+    for (const trip of roundTrips) {
+        if (!trip.approvalTimestamp) {
+            continue;
+        }
+        approvedByReason.set(trip.reason, (approvedByReason.get(trip.reason) ?? 0) + 1);
+    }
+    return [...wouldBlockByReason.entries()]
+        .map(([reason, wouldBlockCount]) => {
+        const approvedAfterDenyCount = approvedByReason.get(reason) ?? 0;
+        return {
+            reason,
+            wouldBlockCount,
+            approvedAfterDenyCount,
+            approvalRate: wouldBlockCount > 0 ? approvedAfterDenyCount / wouldBlockCount : 0,
+        };
+    })
+        .sort((left, right) => right.wouldBlockCount - left.wouldBlockCount);
+}
+function judgeFallbackReason(record) {
+    return typeof record.judgeFallbackReason === 'string' ? record.judgeFallbackReason : '';
+}
+function isJudgeTimeoutFallback(fallback) {
+    return fallback.includes('timeout');
+}
+export function isAvailabilityCausedAsk(record) {
+    if (!isGateRecord(record) || !inferWouldBlock(record)) {
+        return false;
+    }
+    if (record.reason === 'missing_trusted_cwd') {
+        return true;
+    }
+    return judgeFallbackReason(record).length > 0;
+}
+export function computeAvailabilityAskCounts(records) {
+    const counts = {
+        total: 0,
+        missingTrustedCwd: 0,
+        judgeTimeout: 0,
+        judgeFallback: 0,
+    };
+    for (const record of records) {
+        if (!isGateRecord(record) || !inferWouldBlock(record)) {
+            continue;
+        }
+        if (record.reason === 'missing_trusted_cwd') {
+            counts.missingTrustedCwd += 1;
+            counts.total += 1;
+            continue;
+        }
+        const fallback = judgeFallbackReason(record);
+        if (!fallback) {
+            continue;
+        }
+        if (isJudgeTimeoutFallback(fallback)) {
+            counts.judgeTimeout += 1;
+        }
+        else {
+            counts.judgeFallback += 1;
+        }
+        counts.total += 1;
+    }
+    return counts;
+}
+export function computeRepeatedFingerprintAsks(records, minCount = 2, limit = 10) {
+    const grouped = new Map();
+    for (const record of records) {
+        if (!isGateRecord(record) || !inferWouldBlock(record) || !record.fingerprint) {
+            continue;
+        }
+        const fingerprint = record.fingerprint;
+        const existing = grouped.get(fingerprint);
+        if (existing) {
+            existing.askCount += 1;
+            existing.summary = record.summary ?? existing.summary;
+            existing.reason = record.reason ?? existing.reason;
+            continue;
+        }
+        grouped.set(fingerprint, {
+            fingerprint,
+            summary: record.summary ?? '',
+            reason: record.reason ?? 'unknown',
+            askCount: 1,
+        });
+    }
+    return [...grouped.values()]
+        .filter((entry) => entry.askCount >= minCount)
+        .sort((left, right) => right.askCount - left.askCount)
+        .slice(0, limit);
+}

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

@@ -0,0 +1,2 @@
+import type { BelayConfigV4 } from './config.js';
+export declare function appendCliAuditEvent(repoRoot: string, config: BelayConfigV4, event: Record<string, unknown>): Promise<void>;

package/dist/core/audit-io.js

@@ -0,0 +1,14 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+export async function appendCliAuditEvent(repoRoot, config, event) {
+    const auditPath = path.isAbsolute(config.audit.logPath)
+        ? config.audit.logPath
+        : path.join(repoRoot, config.audit.logPath);
+    await mkdir(path.dirname(auditPath), { recursive: true });
+    const line = JSON.stringify({
+        ts: new Date().toISOString(),
+        source: 'belay-cli',
+        ...event,
+    });
+    await appendFile(auditPath, `${line}\n`, 'utf8');
+}

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

@@ -1,4 +1,5 @@
 import { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord } from './audit-query.js';
+import type { AvailabilityAskCounts, ReasonApprovalRatio, RepeatedFingerprintAsk } from './audit-types.js';
 /** Minimum gate events before recommending enforce with zero would-block rate. */
 export declare const MIN_GATE_EVENTS_FOR_ENFORCE = 20;
 export interface AuditMetricsReport {
@@ -9,6 +10,12 @@ export interface AuditMetricsReport {
     gateEvents: number;
     wouldBlockCount: number;
     wouldBlockRate: number;
+    classifierWouldBlockCount: number;
+    classifierWouldBlockRate: number;
+    wouldBlockByReason: Record<string, number>;
+    approvalRatioByReason: ReasonApprovalRatio[];
+    availabilityAsks: AvailabilityAskCounts;
+    repeatedFingerprintAsks: RepeatedFingerprintAsk[];
     byReason: Record<string, number>;
     byKind: Record<string, number>;
     byVerdict: Record<string, number>;

package/dist/core/audit-metrics.js

@@ -1,4 +1,4 @@
-import { bucketGateEventsByDay, computeApprovalLatencyStats, countVerdicts, detectBypassAttempts, detectNoisyRules, } from './audit-analysis.js';
+import { bucketGateEventsByDay, computeApprovalLatencyStats, computeApprovalRatioByReason, computeAvailabilityAskCounts, computeRepeatedFingerprintAsks, computeWouldBlockByReason, countVerdicts, detectBypassAttempts, detectNoisyRules, } from './audit-analysis.js';
 import { buildApprovalRoundTrips, filterAuditRecords, inferWouldBlock, isApprovalRecorded, toAuditRecord, } from './audit-query.js';
 import { AUDIT_METRICS_SCHEMA_VERSION, GATE_EVENTS } from './audit-types.js';
 /** Minimum gate events before recommending enforce with zero would-block rate. */
@@ -78,7 +78,13 @@ export function computeAuditMetrics(records, options = {}) {
     const approvalLatency = computeApprovalLatencyStats(roundTrips);
     const bypassAttempts = detectBypassAttempts(auditRecords);
     const noisyRuleCandidates = detectNoisyRules(auditRecords, roundTrips);
+    const wouldBlockByReason = computeWouldBlockByReason(auditRecords);
+    const approvalRatioByReason = computeApprovalRatioByReason(auditRecords, roundTrips);
+    const availabilityAsks = computeAvailabilityAskCounts(auditRecords);
+    const repeatedFingerprintAsks = computeRepeatedFingerprintAsks(auditRecords);
     const wouldBlockRate = gateEvents > 0 ? wouldBlockCount / gateEvents : 0;
+    const classifierWouldBlockCount = Math.max(0, wouldBlockCount - availabilityAsks.total);
+    const classifierWouldBlockRate = gateEvents > 0 ? classifierWouldBlockCount / gateEvents : 0;
     const topWouldBlockSummaries = [...summaryCounts.values()]
         .sort((left, right) => right.count - left.count)
         .slice(0, 10);
@@ -101,16 +107,16 @@ export function computeAuditMetrics(records, options = {}) {
             }
         }
         else {
-            notes.push(`${wouldBlockCount} would-block event(s) (${(wouldBlockRate * 100).toFixed(1)}% of gate traffic). Review top summaries and add overrides.allow where appropriate.`);
+            notes.push(`${wouldBlockCount} would-block event(s) (${(wouldBlockRate * 100).toFixed(1)}% of gate traffic; classifier-quality ${(classifierWouldBlockRate * 100).toFixed(1)}%). Review top summaries and add overrides.allow where appropriate.`);
             if (approvalRecordedCount > 0) {
                 notes.push(`${approvalRecordedCount} approval(s) recorded — these likely indicate actions operators wanted.`);
             }
             else {
                 notes.push('Review top would-block summaries and add overrides.allow for legitimate commands before switching to enforce.');
             }
-            if (wouldBlockRate < 0.05 && gateEvents >= 20) {
+            if (classifierWouldBlockRate < 0.05 && gateEvents >= 20 && availabilityAsks.total === 0) {
                 readyForEnforce = true;
-                notes.push('Would-block rate is below 5% with sufficient sample size — consider enforce mode.');
+                notes.push('Classifier-quality would-block rate is below 5% with sufficient sample size — consider enforce mode.');
             }
         }
     }
@@ -120,6 +126,14 @@ export function computeAuditMetrics(records, options = {}) {
     else {
         notes.push('Set policy.unknownLocalEffect to "deny" to dogfood fail-closed defaults.');
     }
+    if (availabilityAsks.total > 0) {
+        readyForEnforce = false;
+        notes.push(`${availabilityAsks.total} availability-caused ask(s) — tune infrastructure before corpus overrides.`);
+        notes.push('Ready for enforce withheld while availability-caused asks are present.');
+    }
+    if (repeatedFingerprintAsks.length > 0) {
+        notes.push(`${repeatedFingerprintAsks.length} repeated fingerprint ask pattern(s) — review standing-allow / cache candidates.`);
+    }
     if (noisyRuleCandidates.length > 0) {
         notes.push(`${noisyRuleCandidates.length} noisy rule candidate(s) — high deny-then-approve rate.`);
     }
@@ -131,6 +145,12 @@ export function computeAuditMetrics(records, options = {}) {
         gateEvents,
         wouldBlockCount,
         wouldBlockRate,
+        classifierWouldBlockCount,
+        classifierWouldBlockRate,
+        wouldBlockByReason,
+        approvalRatioByReason,
+        availabilityAsks,
+        repeatedFingerprintAsks,
         byReason,
         byKind,
         byVerdict,

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

@@ -2,6 +2,7 @@ import type { ApprovalRoundTrip, AuditFilter, AuditRecord } from './audit-types.
 export declare function toAuditRecord(value: Record<string, unknown>): AuditRecord;
 export declare function parseTimestamp(value?: string): number | null;
 export declare function isGateRecord(record: AuditRecord): boolean;
+export declare function isShellGateRecord(record: AuditRecord): boolean;
 export declare function isApprovalRecorded(record: AuditRecord): boolean;
 export declare function inferWouldBlock(record: AuditRecord): boolean;
 export declare function recordStringField(record: AuditRecord, field: 'effect' | 'reason' | 'permission' | 'verdict' | 'mode' | 'summary' | 'fingerprint' | 'location'): string;

package/dist/core/audit-query.js

@@ -16,6 +16,9 @@ export function parseTimestamp(value) {
 export function isGateRecord(record) {
     return typeof record.event === 'string' && GATE_EVENTS.has(record.event);
 }
+export function isShellGateRecord(record) {
+    return (isGateRecord(record) && (record.event === 'beforeShellExecution' || record.kind === 'shell'));
+}
 export function isApprovalRecorded(record) {
     return ((record.event === 'approval' ||
         (record.event === 'beforeSubmitPrompt' && record.reason === 'approval_recorded')) &&

package/dist/core/audit-replay-context.d.ts

@@ -0,0 +1,35 @@
+import type { GatedActionKind } from './gate-contract.js';
+import type { ClassifyResult } from './types.js';
+/** Preserved action context for simulate triage — not a safety gate. */
+export interface AuditReplayContext {
+    cwd: string;
+    kind: GatedActionKind;
+    command?: string;
+    toolName?: string;
+    payload?: Record<string, unknown>;
+}
+/** Classifier-facing action snapshot for high-fidelity simulate replay. */
+export interface AuditActionSnapshot {
+    schemaVersion: 1;
+    kind: GatedActionKind;
+    cwd: string;
+    normalizedAction: string;
+    toolName?: string;
+    payloadHash?: string;
+}
+export interface ReplayActionLike {
+    cwd?: string;
+    kind?: string;
+    command?: string;
+    toolName?: string;
+    payload?: Record<string, unknown>;
+}
+export declare function hashReplayPayload(payload: Record<string, unknown>): string;
+export declare function buildAuditActionSnapshot(kind: GatedActionKind, result: Pick<ClassifyResult, 'normalizedCommand' | 'summary'>, replayAction?: ReplayActionLike): AuditActionSnapshot | undefined;
+export declare function parseAuditActionSnapshot(record: {
+    actionSnapshot?: unknown;
+}): AuditActionSnapshot | null;
+export declare function buildAuditReplayContext(kind: GatedActionKind, result: Pick<ClassifyResult, 'normalizedCommand' | 'summary'>, replayAction?: ReplayActionLike): AuditReplayContext | undefined;
+export declare function parseAuditReplayContext(record: {
+    replayContext?: unknown;
+}): AuditReplayContext | null;