@guilz-dev/belay 0.3.0 → 0.4.0

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/index.d.ts

@@ -2,4 +2,5 @@ export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAl
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
 export { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload } from './paths.js';
 export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from './reasons.js';
-export type { CapabilityApprovalScope, FsScopeAllowlistEntry, FsScopeAllowlistFile, } from './types.js';
+export { addTrustedWorkspaceRoot, isBroadTrustedWorkspaceRoot, isHighStakesTrustedWorkspaceRoot, isPathWithinTrustedWorkspaceRoots, loadTrustedWorkspaceRoots, loadTrustedWorkspaceRootsSync, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from './trusted-workspace-roots.js';
+export type { CapabilityApprovalScope, FsScopeAllowlistEntry, FsScopeAllowlistFile, TrustedWorkspaceRootEntry, TrustedWorkspaceRootsFile, } from './types.js';

package/dist/core/capability/index.js

@@ -2,3 +2,4 @@ export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAl
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
 export { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload } from './paths.js';
 export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from './reasons.js';
+export { addTrustedWorkspaceRoot, isBroadTrustedWorkspaceRoot, isHighStakesTrustedWorkspaceRoot, isPathWithinTrustedWorkspaceRoots, loadTrustedWorkspaceRoots, loadTrustedWorkspaceRootsSync, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from './trusted-workspace-roots.js';

package/dist/core/capability/paths.d.ts

@@ -1,2 +1,2 @@
-export declare function collectOutsideRepoPaths(command: string, cwd: string, repoRoot: string): string[];
-export declare function collectOutsideRepoPathsFromToolPayload(payload: Record<string, unknown>, cwd: string, repoRoot: string): string[];
+export declare function collectOutsideRepoPaths(command: string, cwd: string, repoRoot: string, trustedWorkspaceRoots?: string[]): string[];
+export declare function collectOutsideRepoPathsFromToolPayload(payload: Record<string, unknown>, cwd: string, repoRoot: string, trustedWorkspaceRoots?: string[]): string[];

package/dist/core/capability/paths.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { relativeWithinRepo, resolveMutationTarget } from '../path-utils.js';
+import { resolveMutationTarget, resolveWorkspaceRootMatch } from '../path-utils.js';
 import { extractRedirectTargets, tokenizeShell } from '../shell-tokenizer.js';
 function applyPatchTargets(patch) {
     const targets = [];
@@ -42,25 +42,25 @@ function extractToolPatch(payload) {
     }
     return null;
 }
-function addOutsideRepoPath(paths, token, cwd, repoRoot) {
+function addOutsideRepoPath(paths, token, cwd, repoRoot, trustedWorkspaceRoots = []) {
     const resolved = resolveMutationTarget(token, cwd);
-    if (resolved && relativeWithinRepo(repoRoot, resolved) === null) {
+    if (resolved && resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
         paths.add(resolved);
     }
 }
-export function collectOutsideRepoPaths(command, cwd, repoRoot) {
+export function collectOutsideRepoPaths(command, cwd, repoRoot, trustedWorkspaceRoots = []) {
     const tokens = tokenizeShell(command);
     const redirects = extractRedirectTargets(tokens);
     const paths = new Set();
     for (const token of tokens.slice(1)) {
-        addOutsideRepoPath(paths, token, cwd, repoRoot);
+        addOutsideRepoPath(paths, token, cwd, repoRoot, trustedWorkspaceRoots);
     }
     for (const redirect of redirects) {
-        addOutsideRepoPath(paths, redirect, cwd, repoRoot);
+        addOutsideRepoPath(paths, redirect, cwd, repoRoot, trustedWorkspaceRoots);
     }
     return [...paths];
 }
-export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot) {
+export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot, trustedWorkspaceRoots = []) {
     const toolKind = String(payload.tool_name ?? '')
         .trim()
         .toLowerCase();
@@ -68,7 +68,7 @@ export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot) {
     const filePath = extractToolFilePath(payload);
     if (filePath) {
         const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-        if (relativeWithinRepo(repoRoot, resolved) === null) {
+        if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
             paths.add(resolved);
         }
         return [...paths];
@@ -78,7 +78,7 @@ export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot) {
         if (patch) {
             for (const target of applyPatchTargets(patch)) {
                 const resolved = path.isAbsolute(target) ? target : path.resolve(cwd, target);
-                if (relativeWithinRepo(repoRoot, resolved) === null) {
+                if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
                     paths.add(resolved);
                 }
             }

package/dist/core/capability/trusted-workspace-roots.d.ts

@@ -0,0 +1,25 @@
+import type { BelayConfigV3 } from '../config.js';
+import type { TrustedWorkspaceRootEntry, TrustedWorkspaceRootsFile } from './types.js';
+export declare function trustedWorkspaceRootsPath(config: BelayConfigV3, repoLocalStateDir: string): string;
+export declare function loadTrustedWorkspaceRoots(filePath: string): Promise<TrustedWorkspaceRootsFile>;
+export declare function loadTrustedWorkspaceRootsSync(filePath: string): TrustedWorkspaceRootsFile;
+export declare function saveTrustedWorkspaceRoots(filePath: string, state: TrustedWorkspaceRootsFile): Promise<void>;
+export declare function normalizeTrustedWorkspaceRootPath(targetPath: string): string;
+export interface TrustedWorkspaceRootValidationParams {
+    candidatePath: string;
+    repoRoot: string;
+    controlPlaneDir?: string | null;
+    protectedRoots?: string[];
+    requireExistingDirectory?: boolean;
+    requireNonGit?: boolean;
+}
+export interface TrustedWorkspaceRootValidationResult {
+    ok: boolean;
+    normalizedPath: string;
+    reason?: 'not_directory' | 'broad_root' | 'high_stakes' | 'inside_repo' | 'inside_git_repo' | 'control_plane_overlap' | 'protected_root_overlap';
+}
+export declare function isBroadTrustedWorkspaceRoot(targetPath: string): boolean;
+export declare function isHighStakesTrustedWorkspaceRoot(targetPath: string): boolean;
+export declare function validateTrustedWorkspaceRootCandidate(params: TrustedWorkspaceRootValidationParams): TrustedWorkspaceRootValidationResult;
+export declare function isPathWithinTrustedWorkspaceRoots(absolutePath: string, roots: TrustedWorkspaceRootsFile): boolean;
+export declare function addTrustedWorkspaceRoot(roots: TrustedWorkspaceRootsFile, entry: TrustedWorkspaceRootEntry): TrustedWorkspaceRootsFile;

package/dist/core/capability/trusted-workspace-roots.js

@@ -0,0 +1,149 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { belayStateDir } from '../config.js';
+import { canonicalPath, containingGitRoot, pathWithinRoot, resolveWorkspaceRootMatch, } from '../path-utils.js';
+export function trustedWorkspaceRootsPath(config, repoLocalStateDir) {
+    return path.join(belayStateDir(config, repoLocalStateDir), 'trusted-workspace-roots.json');
+}
+export async function loadTrustedWorkspaceRoots(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, roots: [] };
+    }
+    const raw = JSON.parse(await readFile(filePath, 'utf8'));
+    return { version: 1, roots: sanitizeTrustedWorkspaceRootEntries(raw.roots) };
+}
+export function loadTrustedWorkspaceRootsSync(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, roots: [] };
+    }
+    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    return { version: 1, roots: sanitizeTrustedWorkspaceRootEntries(raw.roots) };
+}
+export async function saveTrustedWorkspaceRoots(filePath, state) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export function normalizeTrustedWorkspaceRootPath(targetPath) {
+    return canonicalPath(targetPath);
+}
+function sanitizeTrustedWorkspaceRootEntries(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object') {
+            return [];
+        }
+        const record = entry;
+        if (typeof record.path !== 'string' || !record.path.trim()) {
+            return [];
+        }
+        const approvedAt = typeof record.approvedAt === 'string' ? record.approvedAt : new Date(0).toISOString();
+        const approvalId = typeof record.approvalId === 'string' ? record.approvalId : 'unknown';
+        const source = record.source === 'approval' ? 'approval' : undefined;
+        return [
+            {
+                path: path.resolve(record.path),
+                approvedAt,
+                approvalId,
+                ...(source ? { source } : {}),
+            },
+        ];
+    });
+}
+const SYSTEM_HIGH_STAKES_PREFIXES = [
+    '/etc',
+    '/private/etc',
+    '/bin',
+    '/sbin',
+    '/usr',
+    '/opt',
+    '/System',
+    '/Library',
+];
+const HOME_HIGH_STAKES_SEGMENTS = ['.ssh', '.gnupg', '.aws', '.kube', '.docker', '.config'];
+function isDirectoryPath(targetPath) {
+    try {
+        return statSync(targetPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isBroadTrustedWorkspaceRoot(targetPath) {
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    const root = normalizeTrustedWorkspaceRootPath(targetPath);
+    if (root === normalizeTrustedWorkspaceRootPath(path.parse(root).root)) {
+        return true;
+    }
+    if (home && normalizeTrustedWorkspaceRootPath(home) === root) {
+        return true;
+    }
+    return false;
+}
+export function isHighStakesTrustedWorkspaceRoot(targetPath) {
+    const normalized = normalizeTrustedWorkspaceRootPath(targetPath);
+    if (SYSTEM_HIGH_STAKES_PREFIXES.some((prefix) => normalized === normalizeTrustedWorkspaceRootPath(prefix) ||
+        pathWithinRoot(normalizeTrustedWorkspaceRootPath(prefix), normalized))) {
+        return true;
+    }
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    if (!home) {
+        return false;
+    }
+    const homeRoot = normalizeTrustedWorkspaceRootPath(home);
+    if (!pathWithinRoot(homeRoot, normalized)) {
+        return false;
+    }
+    return HOME_HIGH_STAKES_SEGMENTS.some((segment) => pathWithinRoot(path.join(homeRoot, segment), normalized));
+}
+export function validateTrustedWorkspaceRootCandidate(params) {
+    const normalizedPath = normalizeTrustedWorkspaceRootPath(params.candidatePath);
+    if (params.requireExistingDirectory !== false && !isDirectoryPath(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'not_directory' };
+    }
+    if (isBroadTrustedWorkspaceRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'broad_root' };
+    }
+    if (isHighStakesTrustedWorkspaceRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'high_stakes' };
+    }
+    if (resolveWorkspaceRootMatch(params.repoRoot, [], normalizedPath) !== null) {
+        return { ok: false, normalizedPath, reason: 'inside_repo' };
+    }
+    if (params.requireNonGit !== false && containingGitRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'inside_git_repo' };
+    }
+    const normalizedControlPlane = params.controlPlaneDir?.trim()
+        ? normalizeTrustedWorkspaceRootPath(params.controlPlaneDir)
+        : null;
+    if (normalizedControlPlane &&
+        (pathWithinRoot(normalizedControlPlane, normalizedPath) ||
+            pathWithinRoot(normalizedPath, normalizedControlPlane))) {
+        return { ok: false, normalizedPath, reason: 'control_plane_overlap' };
+    }
+    if ((params.protectedRoots ?? []).some((root) => {
+        const normalizedRoot = normalizeTrustedWorkspaceRootPath(root);
+        return (pathWithinRoot(normalizedRoot, normalizedPath) ||
+            pathWithinRoot(normalizedPath, normalizedRoot));
+    })) {
+        return { ok: false, normalizedPath, reason: 'protected_root_overlap' };
+    }
+    return { ok: true, normalizedPath };
+}
+export function isPathWithinTrustedWorkspaceRoots(absolutePath, roots) {
+    const resolved = normalizeTrustedWorkspaceRootPath(absolutePath);
+    return roots.roots.some((entry) => {
+        const root = path.resolve(entry.path);
+        return resolved === root || pathWithinRoot(root, resolved);
+    });
+}
+export function addTrustedWorkspaceRoot(roots, entry) {
+    const normalized = normalizeTrustedWorkspaceRootPath(entry.path);
+    const filtered = roots.roots.filter((existing) => normalizeTrustedWorkspaceRootPath(existing.path) !== normalized);
+    return {
+        version: 1,
+        roots: [...filtered, { ...entry, path: normalized }],
+    };
+}