@guilz-dev/belay 0.9.0 → 0.9.2

package/dist/commands/doctor.js

@@ -3,12 +3,14 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { getClaudeManagedHookEntries } from '../adapters/claude/hooks.js';
 import { getCodexManagedHookEntries } from '../adapters/codex/hooks.js';
+import { hasDuplicateCursorShellGates } from '../adapters/cursor/hooks.js';
 import { getAdapterLayout } from '../adapters/layouts/index.js';
 import { protectedArtifactRoots } from '../adapters/layouts/protected-paths.js';
 import { resolveScopedPaths } from '../adapters/layouts/scope.js';
 import { cleanupOrphanApprovalState } from '../cleanup-orphans.js';
 import { approvedApprovalsPath, belayStateDir, detectAdapterName, loadLayeredConfig, pendingApprovalsPath, repoLocalStateDirFor, writeConfigFile, } from '../config-io.js';
 import { approvalSigningKeyPath } from '../core/approval-token.js';
+import { auditRecordHasLegacyCorrelationPlaceholders } from '../core/audit-legacy-archive.js';
 import { detectFenceDrift, summarizeAuditVisibility } from '../core/audit-summary.js';
 import { inspectBoundaryAttestationFile } from '../core/capability/boundary-attestation-sign.js';
 import { boundaryAttestationPath, boundarySessionStatus, } from '../core/capability/boundary-session.js';
@@ -24,7 +26,7 @@ import { probeFileCloneStrategy } from '../core/transactional/file-clone.js';
 import { isGitWorktreeAvailable } from '../core/transactional/git-worktree.js';
 import { getManagedHookEntries } from '../defaults.js';
 import { resolveNodeBinary } from '../node-resolution.js';
-import { readInstalledRuntimeProvenance } from '../runtime-provenance.js';
+import { matchesAuditCohort, readInstalledRuntimeProvenance } from '../runtime-provenance.js';
 import { egressStatus } from '../services/egress-service.js';
 import { sandboxStatus } from '../services/sandbox-service.js';
 import { PACKAGE_VERSION } from '../version.js';
@@ -98,6 +100,14 @@ export async function doctorProject(options = {}) {
                 ? `Install scope: global (hooks/runtime at ${scopedPaths.hooksDir})`
                 : 'Install scope: project');
             notes.push(`Config mode: ${loadedConfig.mode}`);
+            const dogfoodActive = loadedConfig.mode === 'audit' && loadedConfig.policy.unknownLocalEffect === 'deny';
+            const allGatesDisabled = !loadedConfig.gates.shell &&
+                !loadedConfig.gates.toolShell &&
+                !loadedConfig.gates.fileMutation &&
+                !loadedConfig.gates.subagent;
+            if (dogfoodActive && allGatesDisabled) {
+                issues.push('Dogfood audit mode is active but all gates are disabled; gate events will not be recorded. Enable gates.shell, gates.toolShell, gates.fileMutation, and/or gates.subagent.');
+            }
             notes.push('Verdict engine (Tier0 + Tier1; location × opacity × effect × confidence). Audit records include schemaVersion 2 axes when available.');
             const repoLocalDir = repoLocalStateDirFor(repoRoot, loadedConfig);
             if (loadedConfig.controlPlane.enabled) {
@@ -181,6 +191,9 @@ export async function doctorProject(options = {}) {
                     issues.push(`Missing managed hook for ${event}: ${definition.command}${matcherSuffix}`);
                 }
             }
+            if (hasDuplicateCursorShellGates(hooksFile, process.platform, hooksDir, repoRoot)) {
+                warnings.push('Duplicate Cursor Shell preToolUse gates detected. Run belay upgrade to dedupe managed hooks.');
+            }
         }
         else if (adapterName === 'codex') {
             // Codex hooks live in TOML (.codex/config.toml). Verify belay's managed command strings
@@ -280,9 +293,14 @@ export async function doctorProject(options = {}) {
         const metrics = await metricsProject({ targetDir: repoRoot });
         const cohortIdentity = metrics.currentCohort.identity;
         const cohortAuditRecords = cohortIdentity
-            ? auditRecords.filter((record) => record.runtimeBuildStamp === cohortIdentity.runtimeBuildStamp &&
-                record.configFingerprint === cohortIdentity.configFingerprint)
+            ? auditRecords.filter((record) => matchesAuditCohort(record, cohortIdentity))
             : [];
+        const gateDecisionRecords = cohortAuditRecords.filter((record) => record.kind === 'shell' || record.kind === 'tool' || record.kind === 'subagent');
+        if (gateDecisionRecords
+            .slice(0, 200)
+            .some((record) => auditRecordHasLegacyCorrelationPlaceholders(record))) {
+            warnings.push('Gate audit records contain scrub placeholders in correlation fields (<timestamp>, <high-entropy>, <approval-id>). Historical metrics are unreliable until a schema v3 cohort is collected.');
+        }
         const auditVisibility = summarizeAuditVisibility(cohortAuditRecords);
         const drift = detectFenceDrift(auditVisibility, {
             threshold: loadedConfig.policy.fenceWarnThreshold,

package/dist/core/audit-analysis.js

@@ -1,4 +1,4 @@
-import { inferWouldBlock, isGateRecord, parseTimestamp } from './audit-query.js';
+import { auditFingerprint, inferWouldBlock, isGateRecord, parseTimestamp } from './audit-query.js';
 const WRAPPER_TERMS = ['bash -c', 'sh -c', 'eval ', 'source ', 'node -e', '| bash', '| sh'];
 function normalizeSummary(summary) {
     return summary.replace(/\s+/g, ' ').trim().toLowerCase();
@@ -26,7 +26,7 @@ export function detectBypassAttempts(records, windowMs = 5 * 60_000) {
     const recentDenies = [];
     for (const record of records) {
         const timestampMs = parseTimestamp(record.timestamp) ?? 0;
-        if (isGateRecord(record) && inferWouldBlock(record) && record.fingerprint) {
+        if (isGateRecord(record) && inferWouldBlock(record) && auditFingerprint(record)) {
             recentDenies.push({ timestampMs, record });
             continue;
         }
@@ -233,10 +233,13 @@ export function computeAvailabilityAskCounts(records) {
 export function computeRepeatedFingerprintAsks(records, minCount = 2, limit = 10) {
     const grouped = new Map();
     for (const record of records) {
-        if (!isGateRecord(record) || !inferWouldBlock(record) || !record.fingerprint) {
+        if (!isGateRecord(record) || !inferWouldBlock(record)) {
+            continue;
+        }
+        const fingerprint = auditFingerprint(record);
+        if (!fingerprint) {
             continue;
         }
-        const fingerprint = record.fingerprint;
         const existing = grouped.get(fingerprint);
         if (existing) {
             existing.askCount += 1;

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

@@ -1,2 +1,3 @@
 import type { BelayConfigV4 } from './config.js';
+export { AUDIT_SCHEMA_VERSION, appendAuditRecord, approvalCorrelationId, isValidAuditFingerprint, isValidAuditTimestamp, parseAuditNdjsonLine, serializeAuditRecordV3, } from './audit-serialize.js';
 export declare function appendCliAuditEvent(repoRoot: string, config: BelayConfigV4, event: Record<string, unknown>): Promise<void>;

package/dist/core/audit-io.js

@@ -1,22 +1,24 @@
-import { appendFile, mkdir } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveActiveAuditCohort } from '../runtime-provenance.js';
+import { appendAuditRecord } from './audit-serialize.js';
+import { scrubOptionsFromConfig } from './config.js';
+export { AUDIT_SCHEMA_VERSION, appendAuditRecord, approvalCorrelationId, isValidAuditFingerprint, isValidAuditTimestamp, parseAuditNdjsonLine, serializeAuditRecordV3, } from './audit-serialize.js';
 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 cohort = await resolveActiveAuditCohort(repoRoot, config);
-    const line = JSON.stringify({
-        ts: new Date().toISOString(),
+    await appendAuditRecord(auditPath, {
         source: 'belay-cli',
         ...(cohort
             ? {
                 runtimeBuildStamp: cohort.runtimeBuildStamp,
+                runtimeArtifactHash: cohort.runtimeArtifactHash,
+                decisionConfigFingerprint: cohort.decisionConfigFingerprint,
+                boundaryProfile: cohort.boundaryProfile,
                 configFingerprint: cohort.configFingerprint,
             }
             : {}),
         ...event,
-    });
-    await appendFile(auditPath, `${line}\n`, 'utf8');
+    }, scrubOptionsFromConfig(config));
 }

package/dist/core/audit-legacy-archive.d.ts

@@ -0,0 +1,7 @@
+import type { BelayConfigV3 } from './config.js';
+export declare function auditLogHasLegacyScrubPlaceholders(sample: string): boolean;
+export declare function auditRecordHasLegacyCorrelationPlaceholders(record: Record<string, unknown>): boolean;
+export declare function archiveLegacyAuditLogIfNeeded(repoRoot: string, config: BelayConfigV3): Promise<{
+    archived: boolean;
+    archivedPath?: string;
+}>;

package/dist/core/audit-legacy-archive.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { open, rename } from 'node:fs/promises';
+import path from 'node:path';
+const LEGACY_PLACEHOLDER_PATTERNS = [
+    /"(?:timestamp|ts)"\s*:\s*"<timestamp>"/,
+    /"(?:fingerprint|commandFingerprint|effectIRHash|payloadHash|configFingerprint|runtimeArtifactHash|decisionConfigFingerprint|receiptHash)"\s*:\s*"<high-entropy>"/,
+    /"approvalId"\s*:\s*"<approval-id>"/,
+];
+const AUDIT_SCAN_CHUNK_BYTES = 64 * 1024;
+const AUDIT_SCAN_OVERLAP_CHARS = 256;
+export function auditLogHasLegacyScrubPlaceholders(sample) {
+    return LEGACY_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(sample));
+}
+export function auditRecordHasLegacyCorrelationPlaceholders(record) {
+    return (record.timestamp === '<timestamp>' ||
+        record.fingerprint === '<high-entropy>' ||
+        record.approvalId === '<approval-id>');
+}
+async function auditFileHasLegacyScrubPlaceholders(auditPath) {
+    const handle = await open(auditPath, 'r');
+    const buffer = Buffer.allocUnsafe(AUDIT_SCAN_CHUNK_BYTES);
+    let carry = '';
+    let position = 0;
+    try {
+        while (true) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+            if (bytesRead === 0) {
+                return false;
+            }
+            const sample = carry + buffer.toString('utf8', 0, bytesRead);
+            if (auditLogHasLegacyScrubPlaceholders(sample)) {
+                return true;
+            }
+            carry = sample.slice(-AUDIT_SCAN_OVERLAP_CHARS);
+            position += bytesRead;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function archiveLegacyAuditLogIfNeeded(repoRoot, config) {
+    const auditPath = path.isAbsolute(config.audit.logPath)
+        ? config.audit.logPath
+        : path.join(repoRoot, config.audit.logPath);
+    if (!existsSync(auditPath)) {
+        return { archived: false };
+    }
+    if (!(await auditFileHasLegacyScrubPlaceholders(auditPath))) {
+        return { archived: false };
+    }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const archivePath = `${auditPath}.legacy-${timestamp}.ndjson`;
+    await rename(auditPath, archivePath);
+    return { archived: true, archivedPath: archivePath };
+}

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

@@ -4,6 +4,10 @@ import type { AvailabilityAskCounts, ReasonApprovalRatio, RepeatedFingerprintAsk
 /** Minimum gate events before recommending enforce with zero would-block rate. */
 export declare const MIN_GATE_EVENTS_FOR_ENFORCE = 20;
 export interface AuditCohortIdentity {
+    runtimeArtifactHash: string;
+    decisionConfigFingerprint: string;
+    boundaryProfile: string;
+    /** Display / forensics metadata — not used for v3 cohort matching when artifact hash is present. */
     runtimeBuildStamp: string;
     configFingerprint: string;
 }

package/dist/core/audit-metrics.js

@@ -1,3 +1,4 @@
+import { matchesAuditCohort } from '../runtime-provenance.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 { computeRecoveryMetrics, } from './audit-recovery-metrics.js';
@@ -106,8 +107,7 @@ export function computeAuditMetrics(records, options = {}) {
         .slice(0, 10);
     const activeCohort = options.activeCohort ?? null;
     const cohortRecords = activeCohort
-        ? auditRecords.filter((record) => record.runtimeBuildStamp === activeCohort.runtimeBuildStamp &&
-            record.configFingerprint === activeCohort.configFingerprint)
+        ? auditRecords.filter((record) => matchesAuditCohort(record, activeCohort))
         : [];
     const cohortGateRecords = cohortRecords.filter((record) => {
         const event = typeof record.event === 'string' ? record.event : '';

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

@@ -1,6 +1,8 @@
 import type { ApprovalRoundTrip, AuditFilter, AuditRecord } from './audit-types.js';
 export declare function toAuditRecord(value: Record<string, unknown>): AuditRecord;
 export declare function parseTimestamp(value?: string): number | null;
+export declare function auditFingerprint(record: AuditRecord): string | undefined;
+export declare function auditApprovalCorrelationId(record: AuditRecord): string | undefined;
 export declare function isGateRecord(record: AuditRecord): boolean;
 export declare function isShellGateRecord(record: AuditRecord): boolean;
 export declare function isApprovalRecorded(record: AuditRecord): boolean;

package/dist/core/audit-query.js

@@ -1,3 +1,4 @@
+import { isValidApprovalCorrelationId, isValidAuditFingerprint, isValidAuditTimestamp, } from './audit-serialize.js';
 import { GATE_EVENTS } from './audit-types.js';
 export function toAuditRecord(value) {
     const record = { ...value };
@@ -7,12 +8,25 @@ export function toAuditRecord(value) {
     return record;
 }
 export function parseTimestamp(value) {
-    if (!value) {
+    if (!value || !isValidAuditTimestamp(value)) {
         return null;
     }
     const parsed = Date.parse(value);
     return Number.isNaN(parsed) ? null : parsed;
 }
+export function auditFingerprint(record) {
+    if (typeof record.fingerprint !== 'string' || !isValidAuditFingerprint(record.fingerprint)) {
+        return undefined;
+    }
+    return record.fingerprint;
+}
+export function auditApprovalCorrelationId(record) {
+    if (typeof record.approvalCorrelationId === 'string' &&
+        isValidApprovalCorrelationId(record.approvalCorrelationId)) {
+        return record.approvalCorrelationId;
+    }
+    return undefined;
+}
 export function isGateRecord(record) {
     return typeof record.event === 'string' && GATE_EVENTS.has(record.event);
 }
@@ -89,28 +103,36 @@ export function filterAuditRecords(records, filter = {}) {
 }
 export function buildApprovalRoundTrips(records) {
     const trips = [];
+    const pendingByCorrelationId = new Map();
     const pendingByApprovalId = new Map();
     const pendingByFingerprint = new Map();
     for (const record of records) {
         const timestamp = record.timestamp ?? '';
-        if (isGateRecord(record) && inferWouldBlock(record) && record.fingerprint) {
+        const fingerprint = auditFingerprint(record);
+        const correlationId = auditApprovalCorrelationId(record);
+        if (isGateRecord(record) && inferWouldBlock(record) && fingerprint) {
             const trip = {
                 denyTimestamp: timestamp,
-                fingerprint: record.fingerprint,
+                fingerprint,
                 reason: record.reason ?? 'unknown',
                 summary: record.summary ?? '',
                 kind: record.kind ?? 'unknown',
                 approvalId: record.approvalId,
+                approvalCorrelationId: correlationId,
             };
             trips.push(trip);
-            if (record.approvalId) {
+            if (correlationId) {
+                pendingByCorrelationId.set(correlationId, trip);
+            }
+            if (record.approvalId && !String(record.approvalId).startsWith('<')) {
                 pendingByApprovalId.set(record.approvalId, trip);
             }
-            pendingByFingerprint.set(record.fingerprint, trip);
+            pendingByFingerprint.set(fingerprint, trip);
             continue;
         }
-        if (isApprovalRecorded(record) && record.approvalId) {
-            const trip = pendingByApprovalId.get(record.approvalId);
+        if (isApprovalRecorded(record)) {
+            const trip = (correlationId ? pendingByCorrelationId.get(correlationId) : undefined) ??
+                (record.approvalId ? pendingByApprovalId.get(record.approvalId) : undefined);
             if (trip) {
                 trip.approvalTimestamp = timestamp;
                 const denyMs = parseTimestamp(trip.denyTimestamp);
@@ -123,9 +145,11 @@ export function buildApprovalRoundTrips(records) {
         }
         if (isGateRecord(record) &&
             record.reason === 'approved_once' &&
-            record.fingerprint &&
+            fingerprint &&
             record.permission === 'allow') {
-            const trip = pendingByFingerprint.get(record.fingerprint);
+            const trip = correlationId
+                ? pendingByCorrelationId.get(correlationId)
+                : pendingByFingerprint.get(fingerprint);
             if (trip) {
                 trip.executeTimestamp = timestamp;
             }

package/dist/core/audit-recovery-metrics.js

@@ -1,3 +1,4 @@
+import { matchesAuditCohort } from '../runtime-provenance.js';
 import { GATE_EVENTS } from './audit-types.js';
 const RESTORE_EVENTS = new Set(['recoveryApplied', 'recoveryConflict', 'recoveryRejected']);
 const STABLE_FAILURE_REASON = /^[a-z][a-z0-9_]*$/;
@@ -35,8 +36,7 @@ function isRecoveryRestoreRecord(record) {
     return RESTORE_EVENTS.has(event);
 }
 function matchesCohort(record, cohort) {
-    return (record.runtimeBuildStamp === cohort.runtimeBuildStamp &&
-        record.configFingerprint === cohort.configFingerprint);
+    return matchesAuditCohort(record, cohort);
 }
 function emptySnapshotMetrics() {
     return {

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

@@ -0,0 +1,9 @@
+import type { ScrubOptions } from './types.js';
+export declare const AUDIT_SCHEMA_VERSION = 3;
+export declare function approvalCorrelationId(approvalId: string): string;
+export declare function isValidApprovalCorrelationId(value: string): boolean;
+export declare function isValidAuditTimestamp(value: string): boolean;
+export declare function isValidAuditFingerprint(value: string): boolean;
+export declare function serializeAuditRecordV3(record: Record<string, unknown>, options: ScrubOptions): Record<string, unknown>;
+export declare function parseAuditNdjsonLine(line: string): Record<string, unknown> | null;
+export declare function appendAuditRecord(auditPath: string, record: Record<string, unknown>, options: ScrubOptions): Promise<void>;

package/dist/core/audit-serialize.js

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { scrubString, scrubValue } from './scrub.js';
+export const AUDIT_SCHEMA_VERSION = 3;
+const ISO8601_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const HEX64_PATTERN = /^[a-f0-9]{64}$/;
+const SCRUB_PLACEHOLDERS = new Set(['<timestamp>', '<high-entropy>', '<approval-id>', '<uuid>']);
+const PRESERVED_HASH_FIELDS = new Set([
+    'fingerprint',
+    'commandFingerprint',
+    'effectIRHash',
+    'payloadHash',
+    'configFingerprint',
+    'runtimeArtifactHash',
+    'decisionConfigFingerprint',
+    'receiptHash',
+]);
+const PRESERVED_LITERAL_FIELDS = new Set([
+    'timestamp',
+    'approvalCorrelationId',
+    'runtimeVersion',
+    'runtimeBuildStamp',
+    'boundaryProfile',
+    'schemaVersion',
+    'imageId',
+    'mirrorBackend',
+    'wouldMediate',
+    'exitCode',
+    'timedOut',
+]);
+const SCRUBBED_CONTAINER_FIELDS = new Set([
+    'summary',
+    'command',
+    'payload',
+    'replayContext',
+    'actionSnapshot',
+    'assessment',
+    'predictedAssessment',
+    'observedAssessment',
+]);
+export function approvalCorrelationId(approvalId) {
+    return createHash('sha256').update(approvalId).digest('hex').slice(0, 16);
+}
+export function isValidApprovalCorrelationId(value) {
+    return /^[a-f0-9]{16}$/.test(value);
+}
+export function isValidAuditTimestamp(value) {
+    if (SCRUB_PLACEHOLDERS.has(value) || !ISO8601_PATTERN.test(value)) {
+        return false;
+    }
+    return !Number.isNaN(Date.parse(value));
+}
+export function isValidAuditFingerprint(value) {
+    return HEX64_PATTERN.test(value) && !SCRUB_PLACEHOLDERS.has(value);
+}
+function isValidPreservedHashField(field, value) {
+    if (field === 'receiptHash') {
+        return HEX64_PATTERN.test(value);
+    }
+    if (field === 'imageId') {
+        return /^sha256:[a-f0-9]{64}$/.test(value);
+    }
+    return isValidAuditFingerprint(value);
+}
+function scrubAuditContainer(value, options) {
+    return scrubValue(value, {
+        ...options,
+        maskHighEntropyStrings: true,
+    });
+}
+function serializeAuditField(key, value, options) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (key === 'approvalId') {
+        return undefined;
+    }
+    if (key === 'ts' && typeof value === 'string' && isValidAuditTimestamp(value)) {
+        return undefined;
+    }
+    if (PRESERVED_LITERAL_FIELDS.has(key)) {
+        if (key === 'timestamp' && typeof value === 'string' && isValidAuditTimestamp(value)) {
+            return value;
+        }
+        if (key === 'approvalCorrelationId' &&
+            typeof value === 'string' &&
+            isValidApprovalCorrelationId(value)) {
+            return value;
+        }
+        if ((key === 'runtimeVersion' || key === 'runtimeBuildStamp' || key === 'boundaryProfile') &&
+            typeof value === 'string' &&
+            value.length > 0) {
+            return value;
+        }
+        if (key === 'schemaVersion' && typeof value === 'number') {
+            return value;
+        }
+        if (key === 'mirrorBackend' && value === 'file_copy') {
+            return value;
+        }
+        if (key === 'wouldMediate' && value === true) {
+            return true;
+        }
+        if (key === 'exitCode' && (value === null || Number.isSafeInteger(value))) {
+            return value;
+        }
+        if (key === 'timedOut' && typeof value === 'boolean') {
+            return value;
+        }
+        if (key === 'imageId' && typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value)) {
+            return value;
+        }
+        return undefined;
+    }
+    if (PRESERVED_HASH_FIELDS.has(key) && typeof value === 'string') {
+        return isValidPreservedHashField(key, value) ? value : undefined;
+    }
+    if (SCRUBBED_CONTAINER_FIELDS.has(key)) {
+        return scrubAuditContainer(value, options);
+    }
+    if (typeof value === 'string') {
+        return scrubString(value, { ...options, maskHighEntropyStrings: true });
+    }
+    if (value !== null && typeof value === 'object') {
+        return scrubAuditContainer(value, options);
+    }
+    return value;
+}
+export function serializeAuditRecordV3(record, options) {
+    const timestamp = typeof record.timestamp === 'string' && isValidAuditTimestamp(record.timestamp)
+        ? record.timestamp
+        : typeof record.ts === 'string' && isValidAuditTimestamp(record.ts)
+            ? record.ts
+            : new Date().toISOString();
+    const serialized = {
+        schemaVersion: AUDIT_SCHEMA_VERSION,
+        timestamp,
+    };
+    if (typeof record.approvalId === 'string' && record.approvalId.length > 0) {
+        serialized.approvalCorrelationId = approvalCorrelationId(record.approvalId);
+    }
+    else if (typeof record.approvalCorrelationId === 'string' &&
+        isValidApprovalCorrelationId(record.approvalCorrelationId)) {
+        serialized.approvalCorrelationId = record.approvalCorrelationId;
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (key === 'timestamp' || key === 'ts' || key === 'approvalId' || key === 'schemaVersion') {
+            continue;
+        }
+        const next = serializeAuditField(key, value, options);
+        if (next !== undefined) {
+            serialized[key] = next;
+        }
+    }
+    return serialized;
+}
+export function parseAuditNdjsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed.ts === 'string' && parsed.timestamp === undefined) {
+            parsed.timestamp = parsed.ts;
+            delete parsed.ts;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function appendAuditRecord(auditPath, record, options) {
+    await mkdir(path.dirname(auditPath), { recursive: true });
+    const line = JSON.stringify(serializeAuditRecordV3(record, options));
+    await appendFile(auditPath, `${line}\n`, 'utf8');
+}

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

@@ -69,6 +69,7 @@ export interface ApprovalRoundTrip {
     approvalTimestamp?: string;
     executeTimestamp?: string;
     approvalId?: string;
+    approvalCorrelationId?: string;
     fingerprint: string;
     reason: string;
     summary: string;

package/dist/core/capability/policy-engine.js

@@ -40,17 +40,11 @@ function effectPathIsLocal(target, context) {
     const resolved = resolveCapabilityPath(target, context.cwd);
     return (resolveWorkspaceRootMatch(context.repoRoot, [...(context.trustedWorkspaceRoots ?? [])], resolved) !== null);
 }
-function effectPathIsHighStakes(target, context) {
+function effectPathIsSecretOrCredentialPath(target, context) {
     const resolved = resolveCapabilityPath(target, context.cwd);
     if (HIGH_STAKES_EFFECT_PATHS.some((pattern) => pattern.test(resolved))) {
         return true;
     }
-    if (context.protectedArtifactRoots?.some((root) => pathWithinRoot(canonicalPath(root), resolved))) {
-        return true;
-    }
-    if (isGitMetadataPath(resolved, context.repoRoot)) {
-        return true;
-    }
     const workspaceMatch = resolveWorkspaceRootMatch(context.repoRoot, [...(context.trustedWorkspaceRoots ?? [])], resolved);
     if (!workspaceMatch) {
         return false;
@@ -59,6 +53,24 @@ function effectPathIsHighStakes(target, context) {
         ...(context.sensitivePaths ?? []),
     ]);
 }
+function effectPathIsControlPlaneArtifactPath(target, context) {
+    const resolved = resolveCapabilityPath(target, context.cwd);
+    return (context.protectedArtifactRoots?.some((root) => pathWithinRoot(canonicalPath(root), resolved)) ??
+        false);
+}
+function effectPathIsHighStakes(target, context) {
+    if (effectPathIsSecretOrCredentialPath(target, context)) {
+        return true;
+    }
+    if (effectPathIsControlPlaneArtifactPath(target, context)) {
+        return true;
+    }
+    const resolved = resolveCapabilityPath(target, context.cwd);
+    if (isGitMetadataPath(resolved, context.repoRoot)) {
+        return true;
+    }
+    return false;
+}
 /**
  * Policy for a lowered shell effect. It intentionally ignores executable
  * command names, segment heads, command text, and config allowlists.
@@ -115,12 +127,13 @@ export function evaluateEffectRequirementPolicy(requirement, context) {
     }
     switch (requirement.action) {
         case 'fs.read':
-            if (requirement.resource.kind === 'path' &&
-                effectPathIsHighStakes(requirement.resource.path, context)) {
-                return effectDecision('ask', 'high_stakes_path', 'effect.fs_read_high_stakes', [
-                    ...signals,
-                    'sensitive_path_read',
-                ]);
+            if (requirement.resource.kind === 'path') {
+                if (effectPathIsSecretOrCredentialPath(requirement.resource.path, context)) {
+                    return effectDecision('ask', 'high_stakes_path', 'effect.fs_read_high_stakes', [
+                        ...signals,
+                        'sensitive_path_read',
+                    ]);
+                }
             }
             return effectDecision('allow', 'read_only', 'effect.fs_read', signals);
         case 'fs.write':
@@ -130,6 +143,12 @@ export function evaluateEffectRequirementPolicy(requirement, context) {
             if (requirement.resource.kind !== 'path') {
                 return effectDecision('ask', 'indeterminate_effect', 'effect.fs_write_unknown', signals);
             }
+            if (effectPathIsControlPlaneArtifactPath(requirement.resource.path, context)) {
+                return effectDecision('ask', 'control_plane_mutation', 'effect.control_plane_write', [
+                    ...signals,
+                    'control_plane_path',
+                ]);
+            }
             if (effectPathIsHighStakes(requirement.resource.path, context)) {
                 return effectDecision('ask', 'high_stakes_path', 'effect.fs_write_high_stakes', [
                     ...signals,

package/dist/core/decision-config-fingerprint.d.ts

@@ -0,0 +1,3 @@
+import type { BelayConfigV3 } from './config.js';
+/** Hash of config fields that affect authorization decisions (excludes mode, audit paths, judge, notifications). */
+export declare function hashDecisionConfig(config: BelayConfigV3): string;

package/dist/core/decision-config-fingerprint.js

@@ -0,0 +1,6 @@
+import { canonicalStringify, hashValue } from './fingerprint.js';
+/** Hash of config fields that affect authorization decisions (excludes mode, audit paths, judge, notifications). */
+export function hashDecisionConfig(config) {
+    const { mode: _mode, notifications: _notifications, audit: _audit, judge: _judge, redaction: _redaction, installScope: _installScope, overrides: _overrides, tokenPrefix: _tokenPrefix, approvalTtlMinutes: _approvalTtlMinutes, ...decisionRelevant } = config;
+    return hashValue(canonicalStringify(decisionRelevant));
+}