@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/core/approval.js

@@ -1,5 +1,8 @@
-/** 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 { attachCapabilityEnvelope } from './capability/approval-v3.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();
 }
@@ -13,10 +16,14 @@ export function isExecutionLeaseExpired(approval) {
     return Date.parse(approval.executionLeaseExpiresAt) <= Date.now();
 }
 export function compactApprovals(state) {
-    return {
+    const compacted = {
         version: state.version,
         approvals: state.approvals.filter((approval) => !isExpired(approval) && !isExecutionLeaseExpired(approval)),
     };
+    if (state.revision !== undefined) {
+        compacted.revision = state.revision;
+    }
+    return compacted;
 }
 export function mergeApprovalStates(target, source) {
     const byId = new Map();
@@ -29,7 +36,12 @@ export function mergeApprovalStates(target, source) {
         }
     }
     return compactApprovals({
-        version: target.version === 2 || source.version === 2 ? 2 : 1,
+        version: target.version === 3 || source.version === 3
+            ? 3
+            : target.version === 2 || source.version === 2
+                ? 2
+                : 1,
+        revision: Math.max(target.revision ?? 0, source.revision ?? 0),
         approvals: [...byId.values()],
     });
 }
@@ -49,8 +61,35 @@ 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,
+        capabilityRequests: params.capabilityRequests,
+    });
 }
 export function createApprovalRecord(params) {
     const createdAt = nowIso();
@@ -69,5 +108,20 @@ export function createApprovalRecord(params) {
         record.input = params.input;
         record.inputKind = params.inputKind ?? params.kind;
     }
-    return record;
+    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 attachCapabilityEnvelope(record, params.capabilityRequests);
 }

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

package/dist/core/audit-replay-context.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+export function hashReplayPayload(payload) {
+    return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+export function buildAuditActionSnapshot(kind, result, replayAction) {
+    if (!replayAction?.cwd) {
+        return undefined;
+    }
+    const replayKind = replayAction.kind;
+    const resolvedKind = replayKind === 'shell' || replayKind === 'tool' || replayKind === 'subagent' ? replayKind : kind;
+    const normalizedAction = result.normalizedCommand ?? replayAction.command ?? result.summary ?? '';
+    if (!normalizedAction.trim()) {
+        return undefined;
+    }
+    return {
+        schemaVersion: 1,
+        kind: resolvedKind,
+        cwd: replayAction.cwd,
+        normalizedAction,
+        ...(replayAction.toolName ? { toolName: replayAction.toolName } : {}),
+        ...(replayAction.payload ? { payloadHash: hashReplayPayload(replayAction.payload) } : {}),
+    };
+}
+export function parseAuditActionSnapshot(record) {
+    const raw = record.actionSnapshot;
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const snapshot = raw;
+    if (snapshot.schemaVersion !== 1) {
+        return null;
+    }
+    if (typeof snapshot.cwd !== 'string' || !snapshot.cwd.trim()) {
+        return null;
+    }
+    const kind = snapshot.kind;
+    if (kind !== 'shell' && kind !== 'tool' && kind !== 'subagent') {
+        return null;
+    }
+    if (typeof snapshot.normalizedAction !== 'string' || !snapshot.normalizedAction.trim()) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        kind,
+        cwd: snapshot.cwd,
+        normalizedAction: snapshot.normalizedAction,
+        ...(typeof snapshot.toolName === 'string' ? { toolName: snapshot.toolName } : {}),
+        ...(typeof snapshot.payloadHash === 'string' ? { payloadHash: snapshot.payloadHash } : {}),
+    };
+}
+export function buildAuditReplayContext(kind, result, replayAction) {
+    if (!replayAction?.cwd) {
+        return undefined;
+    }
+    const replayKind = replayAction.kind;
+    const resolvedKind = replayKind === 'shell' || replayKind === 'tool' || replayKind === 'subagent' ? replayKind : kind;
+    return {
+        cwd: replayAction.cwd,
+        kind: resolvedKind,
+        command: replayAction.command ?? result.normalizedCommand ?? result.summary,
+        ...(replayAction.toolName ? { toolName: replayAction.toolName } : {}),
+        ...(replayAction.payload ? { payload: replayAction.payload } : {}),
+    };
+}
+export function parseAuditReplayContext(record) {
+    const raw = record.replayContext;
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const ctx = raw;
+    if (typeof ctx.cwd !== 'string' || !ctx.cwd.trim()) {
+        return null;
+    }
+    const kind = ctx.kind;
+    if (kind !== 'shell' && kind !== 'tool' && kind !== 'subagent') {
+        return null;
+    }
+    return {
+        cwd: ctx.cwd,
+        kind,
+        ...(typeof ctx.command === 'string' ? { command: ctx.command } : {}),
+        ...(typeof ctx.toolName === 'string' ? { toolName: ctx.toolName } : {}),
+        ...(ctx.payload && typeof ctx.payload === 'object' && !Array.isArray(ctx.payload)
+            ? { payload: ctx.payload }
+            : {}),
+    };
+}

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

@@ -1,5 +1,7 @@
+import type { AuditActionSnapshot, AuditReplayContext } from './audit-replay-context.js';
 import type { Assessment } from './types.js';
-export declare const AUDIT_METRICS_SCHEMA_VERSION = 2;
+export type { AuditActionSnapshot, AuditReplayContext } from './audit-replay-context.js';
+export declare const AUDIT_METRICS_SCHEMA_VERSION = 3;
 export declare const GATE_EVENTS: Set<string>;
 export interface AuditRecord {
     timestamp?: string;
@@ -11,6 +13,7 @@ export interface AuditRecord {
     summary?: string;
     approvalId?: string;
     wouldBlock?: boolean;
+    judgeFallbackReason?: string;
     permission?: string;
     mode?: string;
     assessment?: Assessment;
@@ -21,6 +24,8 @@ export interface AuditRecord {
     transactionalCategories?: string[];
     transactionalChangeCount?: number;
     transactionalSkipReason?: string;
+    replayContext?: AuditReplayContext;
+    actionSnapshot?: AuditActionSnapshot;
     [key: string]: unknown;
 }
 export interface AuditFilter {
@@ -63,3 +68,21 @@ export interface NoisyRuleCandidate {
     approvedCount: number;
     approvalRate: number;
 }
+export interface ReasonApprovalRatio {
+    reason: string;
+    wouldBlockCount: number;
+    approvedAfterDenyCount: number;
+    approvalRate: number;
+}
+export interface RepeatedFingerprintAsk {
+    fingerprint: string;
+    summary: string;
+    reason: string;
+    askCount: number;
+}
+export interface AvailabilityAskCounts {
+    total: number;
+    missingTrustedCwd: number;
+    judgeTimeout: number;
+    judgeFallback: number;
+}

package/dist/core/audit-types.js

@@ -1,2 +1,2 @@
-export const AUDIT_METRICS_SCHEMA_VERSION = 2;
+export const AUDIT_METRICS_SCHEMA_VERSION = 3;
 export const GATE_EVENTS = new Set(['beforeShellExecution', 'preToolUse', 'subagentGate']);

package/dist/core/capability/approval-state-mutation.d.ts

@@ -0,0 +1,13 @@
+import type { ApprovalStateFile } from '../types.js';
+export declare function mutateApprovalStateWithRetry<T>(params: {
+    load: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    write: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    mutate: (state: ApprovalStateFile) => {
+        state: ApprovalStateFile;
+        result: T;
+    } | null;
+    maxRetries?: number;
+}): Promise<T | null>;

package/dist/core/capability/approval-state-mutation.js

@@ -0,0 +1,92 @@
+import { constants } from 'node:fs';
+import { open, readFile, unlink } from 'node:fs/promises';
+import { upgradeApprovalStateToV3 } from './approval-v3.js';
+const DEFAULT_RETRIES = 8;
+const LOCK_STALE_MS = 5 * 60_000;
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function isStaleApprovalLock(lockPath) {
+    try {
+        const raw = await readFile(lockPath, 'utf8');
+        const [pidText, timestampText] = raw.trim().split(':');
+        const timestamp = Number(timestampText);
+        if (Number.isFinite(timestamp) && Date.now() - timestamp > LOCK_STALE_MS) {
+            return true;
+        }
+        const pid = Number(pidText);
+        if (!Number.isFinite(pid)) {
+            return true;
+        }
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+async function acquireApprovalStateLock(lockPath, maxRetries) {
+    for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+        try {
+            const handle = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+            await handle.writeFile(`${process.pid}:${Date.now()}`);
+            await handle.close();
+            return async () => {
+                await unlink(lockPath).catch(() => { });
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST') {
+                throw error;
+            }
+            if (await isStaleApprovalLock(lockPath)) {
+                await unlink(lockPath).catch(() => { });
+            }
+            await sleep(5 + attempt * 8);
+        }
+    }
+    throw new Error(`Failed to acquire approval state lock: ${lockPath}`);
+}
+export async function mutateApprovalStateWithRetry(params) {
+    const maxRetries = params.maxRetries ?? DEFAULT_RETRIES;
+    for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+        const loaded = await params.load();
+        const lockPath = `${loaded.filePath}.lock`;
+        let release = null;
+        try {
+            release = await acquireApprovalStateLock(lockPath, maxRetries);
+            const base = upgradeApprovalStateToV3(loaded.state);
+            const revision = base.revision ?? 0;
+            const outcome = params.mutate(base);
+            if (!outcome) {
+                return null;
+            }
+            const next = {
+                ...outcome.state,
+                version: 3,
+                revision: revision + 1,
+            };
+            const verifyBeforeWrite = upgradeApprovalStateToV3((await params.load()).state);
+            if ((verifyBeforeWrite.revision ?? 0) !== revision) {
+                continue;
+            }
+            await params.write(loaded.filePath, next);
+            const verify = upgradeApprovalStateToV3((await params.load()).state);
+            if ((verify.revision ?? 0) === revision + 1) {
+                return outcome.result;
+            }
+        }
+        finally {
+            if (release) {
+                await release();
+            }
+        }
+    }
+    return null;
+}

package/dist/core/capability/approval-v3.d.ts

@@ -0,0 +1,15 @@
+import type { ApprovalRecord, ApprovalStateFile } from '../types.js';
+import type { CapabilityGrantV1 } from './grant.js';
+import type { CapabilityRequestV1 } from './request.js';
+export declare const APPROVAL_STATE_VERSION_V3: 3;
+export declare function normalizeApprovalStateVersion(state: ApprovalStateFile): ApprovalStateFile;
+export declare function upgradeApprovalStateToV3(state: ApprovalStateFile): ApprovalStateFile;
+export declare function attachCapabilityEnvelope(approval: ApprovalRecord, capabilityRequests?: CapabilityRequestV1[]): ApprovalRecord;
+export declare function mintCapabilityGrant(params: {
+    approval: ApprovalRecord;
+    capabilityRequests: CapabilityRequestV1[];
+    issuer?: string;
+    maxUses?: number;
+}): CapabilityGrantV1 | null;
+export declare function mintGrantForApprovedRecord(approval: ApprovalRecord): ApprovalRecord;
+export declare function newGrantId(): string;