@guilz-dev/belay 0.3.0 → 0.4.0

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

@@ -1,4 +1,4 @@
-export type CapabilityApprovalScope = 'once' | 'path';
+export type CapabilityApprovalScope = 'once' | 'path' | 'workspace-root';
 export interface FsScopeAllowlistEntry {
     path: string;
     approvedAt: string;
@@ -8,3 +8,13 @@ export interface FsScopeAllowlistFile {
     version: 1;
     paths: FsScopeAllowlistEntry[];
 }
+export interface TrustedWorkspaceRootEntry {
+    path: string;
+    approvedAt: string;
+    approvalId: string;
+    source?: 'approval';
+}
+export interface TrustedWorkspaceRootsFile {
+    version: 1;
+    roots: TrustedWorkspaceRootEntry[];
+}

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

@@ -1,5 +1,5 @@
 import type { CapabilityApprovalScope } from './capability/types.js';
-import type { BelayConfigV3 } from './config.js';
+import { type BelayConfigV3 } from './config.js';
 import type { ApprovalStateFile } from './types.js';
 export interface CapabilityApprovalStore {
     loadPending: () => Promise<{
@@ -13,6 +13,7 @@ export interface CapabilityApprovalStore {
     writePending: (filePath: string, state: ApprovalStateFile) => Promise<void>;
     writeApproved: (filePath: string, state: ApprovalStateFile) => Promise<void>;
     allowlistPath: string;
+    trustedRootsPath: string;
 }
 export declare function recordCapabilityApproval(params: {
     approvalId: string;

package/dist/core/capability-approval.js

@@ -1,11 +1,13 @@
 import { recordApproval } from './approval-service.js';
 import { addPathToAllowlist, loadFsScopeAllowlist, normalizeAllowlistPath, saveFsScopeAllowlist, } from './capability/allowlist.js';
 import { FS_SCOPE_REASONS } from './capability/reasons.js';
+import { addTrustedWorkspaceRoot, loadTrustedWorkspaceRoots, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, validateTrustedWorkspaceRootCandidate, } from './capability/trusted-workspace-roots.js';
+import { resolveControlPlaneDir } from './config.js';
 export async function recordCapabilityApproval(params) {
     const pending = await params.store.loadPending();
     const match = pending.state.approvals.find((approval) => approval.approvalId === params.approvalId);
     if (params.scope === 'path') {
-        if (!match || !FS_SCOPE_REASONS.has(match.reason)) {
+        if (!match || match.kind !== 'shell' || !FS_SCOPE_REASONS.has(match.reason)) {
             return {
                 ok: false,
                 message: 'Path scope approvals apply only to pending outside-repo shell actions (outside_repo_mutation / outside_repo_redirect).',
@@ -18,6 +20,85 @@ export async function recordCapabilityApproval(params) {
             };
         }
     }
+    if (params.scope === 'workspace-root') {
+        if (!match || !FS_SCOPE_REASONS.has(match.reason)) {
+            return {
+                ok: false,
+                message: 'workspace-root scope approvals apply only to pending outside-repo actions (outside_repo_mutation / outside_repo_redirect).',
+            };
+        }
+        if (!params.scopePath?.trim()) {
+            return {
+                ok: false,
+                message: 'approve --scope workspace-root requires --path <absolute-directory-path>.',
+            };
+        }
+        if (!match.scopeHint || match.scopeHint.scope !== 'workspace-root') {
+            return {
+                ok: false,
+                message: 'workspace-root approval requires a pending scope hint. Re-run the original blocked action to mint a scoped approval.',
+            };
+        }
+        const normalizedPath = normalizeTrustedWorkspaceRootPath(params.scopePath.trim());
+        const normalizedHint = normalizeTrustedWorkspaceRootPath(match.scopeHint.path);
+        if (normalizedPath !== normalizedHint) {
+            return {
+                ok: false,
+                message: `workspace-root approval path must exactly match the suggested path: ${normalizedHint}`,
+            };
+        }
+        const validation = validateTrustedWorkspaceRootCandidate({
+            candidatePath: normalizedPath,
+            repoRoot: match.repoRoot,
+            controlPlaneDir: params.config.controlPlane.enabled
+                ? resolveControlPlaneDir(params.config)
+                : undefined,
+            requireExistingDirectory: true,
+            requireNonGit: true,
+        });
+        if (!validation.ok) {
+            if (validation.reason === 'not_directory') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval requires an existing directory path.',
+                };
+            }
+            if (validation.reason === 'broad_root') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: broad roots (/, drive root, HOME) are not allowed.',
+                };
+            }
+            if (validation.reason === 'high_stakes') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: high-stakes directories cannot be trusted roots.',
+                };
+            }
+            if (validation.reason === 'inside_repo') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: the path is already inside the repository root.',
+                };
+            }
+            if (validation.reason === 'inside_git_repo') {
+                return {
+                    ok: false,
+                    message: `workspace-root approval rejected: ${normalizedPath} is under a git repository.`,
+                };
+            }
+            if (validation.reason === 'control_plane_overlap') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: control plane paths cannot be trusted roots.',
+                };
+            }
+            return {
+                ok: false,
+                message: 'workspace-root approval rejected by trusted-root policy.',
+            };
+        }
+    }
     const result = await recordApproval({
         approvalId: params.approvalId,
         config: params.config,
@@ -25,9 +106,26 @@ export async function recordCapabilityApproval(params) {
         requireSignedToken: params.requireSignedToken ?? false,
         store: params.store,
     });
-    if (!result.ok || params.scope !== 'path' || !params.scopePath?.trim()) {
+    if (!result.ok ||
+        (params.scope !== 'path' && params.scope !== 'workspace-root') ||
+        !params.scopePath?.trim()) {
         return { ok: result.ok, message: result.message };
     }
+    if (params.scope === 'workspace-root') {
+        const trustedRoots = await loadTrustedWorkspaceRoots(params.store.trustedRootsPath);
+        const normalizedPath = normalizeTrustedWorkspaceRootPath(params.scopePath.trim());
+        const updated = addTrustedWorkspaceRoot(trustedRoots, {
+            path: normalizedPath,
+            approvedAt: new Date().toISOString(),
+            approvalId: params.approvalId,
+            source: 'approval',
+        });
+        await saveTrustedWorkspaceRoots(params.store.trustedRootsPath, updated);
+        return {
+            ok: true,
+            message: `${result.message} Trusted workspace root ${normalizedPath} added.`,
+        };
+    }
     const allowlist = await loadFsScopeAllowlist(params.store.allowlistPath);
     const normalizedPath = normalizeAllowlistPath(params.scopePath.trim());
     const updated = addPathToAllowlist(allowlist, {

package/dist/core/classify-subagent.js

@@ -1,4 +1,5 @@
 import { canonicalStringify, subagentFingerprint } from './fingerprint.js';
+import { subagentFingerprintSource } from './replay-scrub.js';
 import { scrubValue } from './scrub.js';
 const EXTERNAL_TERMS = ['deploy', 'production', 'publish', 'release', 'ship', 'notify', 'email'];
 function extractSubagentText(payload, options) {
@@ -22,26 +23,7 @@ function extractSubagentText(payload, options) {
     return canonicalStringify(scrubValue(payload, options.scrubOptions));
 }
 function fingerprintSource(payload, options) {
-    const toolInput = payload.tool_input;
-    if (toolInput && typeof toolInput === 'object') {
-        const input = toolInput;
-        return scrubValue({
-            description: input.description ?? '',
-            prompt: input.prompt ?? '',
-        }, options.scrubOptions);
-    }
-    const task = payload.task;
-    if (typeof task === 'string') {
-        return scrubValue({ task }, options.scrubOptions);
-    }
-    if (task && typeof task === 'object') {
-        const taskObj = task;
-        return scrubValue({
-            description: taskObj.description ?? '',
-            prompt: taskObj.prompt ?? '',
-        }, options.scrubOptions);
-    }
-    return scrubValue(payload, options.scrubOptions);
+    return subagentFingerprintSource(payload, options.scrubOptions ?? {});
 }
 export function classifySubagent(payload, repoRoot, options = {}) {
     const kind = payload.tool_name === 'Task' ? 'Task' : String(payload.subagent_type ?? 'generalPurpose');

package/dist/core/classify-tool.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { canonicalStringify, toolFingerprint } from './fingerprint.js';
 import { matchesSensitivePath } from './glob.js';
-import { pathWithinRoot, relativeWithinRepo } from './path-utils.js';
+import { pathWithinRoot, resolveWorkspaceRootMatch } from './path-utils.js';
 import { scrubValue } from './scrub.js';
 import { classifyShell, resolveClassifierTrustedCwd } from './verdict/adapter.js';
 import { mutationPrescanRequiresAsk, tier1RequiresAsk } from './verdict/judge.js';
@@ -87,6 +87,7 @@ async function classifyFileMutationWithTier1(params) {
         cwd: params.cwd,
         repoRoot: params.repoRoot,
         trustedCwd,
+        trustedWorkspaceRoots: params.options.trustedWorkspaceRoots,
         sensitivePaths: params.options.sensitivePaths ?? params.config.classifier.sensitivePaths,
     });
     if (prescan) {
@@ -243,8 +244,8 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                 },
             };
         }
-        const relativePath = relativeWithinRepo(repoRoot, resolvedPath);
-        if (relativePath === null) {
+        const workspaceMatch = resolveWorkspaceRootMatch(repoRoot, options.trustedWorkspaceRoots, resolvedPath);
+        if (workspaceMatch === null) {
             signals.push('outside_repo_path');
             return classifyFileMutationWithTier1({
                 toolName,
@@ -260,6 +261,34 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                 locationLabel: 'outside_repo',
             });
         }
+        if (workspaceMatch.kind === 'trusted') {
+            signals.push('trusted_workspace_root');
+        }
+        const trustedCwd = resolveClassifierTrustedCwd(cwd, options);
+        const workspacePrescan = mutationPrescanRequiresAsk({
+            targets: [filePath],
+            cwd,
+            repoRoot,
+            trustedCwd,
+            trustedWorkspaceRoots: options.trustedWorkspaceRoots,
+            sensitivePaths,
+        });
+        if (workspacePrescan) {
+            return classifyFileMutationWithTier1({
+                toolName,
+                toolKind,
+                filePath,
+                resolvedPath,
+                repoRoot,
+                cwd,
+                config,
+                options,
+                signals,
+                isDelete: FILE_DELETE_TOOL_NAMES.has(toolKind),
+                locationLabel: 'sensitive_path',
+            });
+        }
+        const relativePath = workspaceMatch.relativePath;
         if (matchesSensitivePath(relativePath, sensitivePaths)) {
             signals.push('sensitive_path');
             return classifyFileMutationWithTier1({

package/dist/core/config.d.ts

@@ -1,4 +1,5 @@
 import type { ClassifierOptions, ControlPlaneIntegrity, ScrubOptions, UnknownLocalEffectPolicy, UnparseableShellPolicy } from './types.js';
+import { type BelayJudgeRuntimeConfig } from './verdict/judge-runtime-config.js';
 export type BelayMode = 'enforce' | 'audit';
 export type { UnknownLocalEffectPolicy };
 export interface BelayConfigV1 {
@@ -102,6 +103,7 @@ export interface BelayJudgeConfig {
     keepAlive: string | null;
     cloudConsent?: JudgeCloudConsent;
     credential?: JudgeCredentialConfig;
+    runtime?: BelayJudgeRuntimeConfig;
 }
 export declare const DEFAULT_JUDGE_LOCAL_OLLAMA: BelayJudgeConfig;
 export declare const DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE: BelayJudgeConfig;
@@ -137,6 +139,17 @@ export interface BelayApprovalSigningConfig {
     /** When true, out-of-band approvals must present a signed token. */
     required: boolean;
 }
+export type ApprovalFlow = 'one_step' | 'two_step';
+export interface BelayApprovalAutoReplayScopes {
+    shell: boolean;
+    tool: boolean;
+    subagent: boolean;
+}
+export interface BelayApprovalConfig {
+    flow: ApprovalFlow;
+    autoReplayScopes: BelayApprovalAutoReplayScopes;
+    executionLeaseMs: number;
+}
 export interface BelayEgressConfig {
     enabled: boolean;
     listenHost: string;
@@ -160,6 +173,7 @@ export interface BelayConfigV4 {
     controlPlane: BelayControlPlaneConfig;
     notifications: BelayNotificationsConfig;
     approvalSigning: BelayApprovalSigningConfig;
+    approval: BelayApprovalConfig;
     egress: BelayEgressConfig;
     sandbox: BelaySandboxConfig;
     audit: BelayConfigV2['audit'];
@@ -184,6 +198,7 @@ export declare const DEFAULT_CONTROL_PLANE_V3: BelayControlPlaneConfig;
 export declare const DEFAULT_SANDBOX_V3: BelaySandboxConfig;
 export declare const DEFAULT_NOTIFICATIONS_V3: BelayNotificationsConfig;
 export declare const DEFAULT_APPROVAL_SIGNING_V3: BelayApprovalSigningConfig;
+export declare const DEFAULT_APPROVAL_CONFIG: BelayApprovalConfig;
 export declare const DEFAULT_EGRESS_V3: BelayEgressConfig;
 export declare function normalizeEgressListenHost(host: string): string;
 export declare const DEFAULT_CONFIG_V2: BelayConfigV2;
@@ -217,6 +232,9 @@ type RawConfigInput = Partial<{
     controlPlane: Partial<BelayControlPlaneConfig>;
     notifications: Partial<BelayNotificationsConfig>;
     approvalSigning: Partial<BelayApprovalSigningConfig>;
+    approval: Partial<BelayApprovalConfig> & {
+        autoReplayScopes?: Partial<BelayApprovalAutoReplayScopes>;
+    };
     egress: Partial<BelayEgressConfig>;
     sandbox: Partial<BelaySandboxConfig>;
     audit: Partial<BelayConfigV2['audit']>;

package/dist/core/config.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { warnDeprecatedJudgeModelAuto } from './judge-model-policy.js';
 import { getJudgeProviderSpec, inferProviderIdFromConfig, isRemovedProviderId, normalizeLegacyProviderId, warnRemovedProviderId, } from './verdict/judge-catalog.js';
+import { normalizeJudgeRuntimeConfig, } from './verdict/judge-runtime-config.js';
 export const DEFAULT_JUDGE_LOCAL_OLLAMA = {
     provider: 'ollama',
     providerId: 'ollama',
@@ -95,6 +96,15 @@ export const DEFAULT_NOTIFICATIONS_V3 = {};
 export const DEFAULT_APPROVAL_SIGNING_V3 = {
     required: false,
 };
+export const DEFAULT_APPROVAL_CONFIG = {
+    flow: 'one_step',
+    autoReplayScopes: {
+        shell: true,
+        tool: false,
+        subagent: false,
+    },
+    executionLeaseMs: 60_000,
+};
 export const DEFAULT_EGRESS_V3 = {
     enabled: false,
     listenHost: '127.0.0.1',
@@ -148,6 +158,7 @@ export const DEFAULT_CONFIG_V4 = {
     controlPlane: { ...DEFAULT_CONTROL_PLANE_V3 },
     notifications: { ...DEFAULT_NOTIFICATIONS_V3 },
     approvalSigning: { ...DEFAULT_APPROVAL_SIGNING_V3 },
+    approval: { ...DEFAULT_APPROVAL_CONFIG },
     egress: { ...DEFAULT_EGRESS_V3 },
     sandbox: { ...DEFAULT_SANDBOX_V3 },
     audit: { ...DEFAULT_CONFIG_V2.audit },
@@ -190,6 +201,7 @@ export function migrateV2ToV3(v2, rawOverrides) {
         controlPlane: { ...LEGACY_CONTROL_PLANE_V3 },
         notifications: { ...DEFAULT_NOTIFICATIONS_V3 },
         approvalSigning: { ...DEFAULT_APPROVAL_SIGNING_V3 },
+        approval: { ...DEFAULT_APPROVAL_CONFIG },
         egress: { ...DEFAULT_EGRESS_V3 },
         sandbox: { ...DEFAULT_SANDBOX_V3 },
         audit: v2.audit,
@@ -283,6 +295,7 @@ export function normalizeJudgeConfig(judge) {
                     : null,
             ...(judge.cloudConsent ? { cloudConsent: judge.cloudConsent } : {}),
             ...(judge.credential ? { credential: judge.credential } : {}),
+            runtime: normalizeJudgeRuntimeConfig(judge.runtime),
         };
     }
     let providerId = rawProviderId && normalizeLegacyProviderId(rawProviderId)
@@ -333,6 +346,7 @@ export function normalizeJudgeConfig(judge) {
             ...(judge.credential.ref ? { ref: judge.credential.ref } : {}),
         };
     }
+    normalized.runtime = normalizeJudgeRuntimeConfig(judge.runtime);
     return normalized;
 }
 export function rejectTeamLayerJudgeSecrets(judge, source) {
@@ -395,6 +409,14 @@ function mergeV3FromRaw(base, raw) {
             ...base.approvalSigning,
             ...(raw.approvalSigning ?? {}),
         },
+        approval: {
+            ...base.approval,
+            ...(raw.approval ?? {}),
+            autoReplayScopes: {
+                ...base.approval.autoReplayScopes,
+                ...(raw.approval?.autoReplayScopes ?? {}),
+            },
+        },
         egress: {
             ...base.egress,
             ...(raw.egress ?? {}),
@@ -446,6 +468,14 @@ function normalizeV3Raw(raw) {
         approvalSigning: {
             required: raw.approvalSigning?.required === true,
         },
+        approval: {
+            ...DEFAULT_APPROVAL_CONFIG,
+            ...(raw.approval ?? {}),
+            autoReplayScopes: {
+                ...DEFAULT_APPROVAL_CONFIG.autoReplayScopes,
+                ...(raw.approval?.autoReplayScopes ?? {}),
+            },
+        },
         egress: {
             ...DEFAULT_EGRESS_V3,
             ...(raw.egress ?? {}),
@@ -676,6 +706,17 @@ export function normalizeConfig(config) {
         approvalSigning: {
             required: v4.approvalSigning?.required === true,
         },
+        approval: {
+            flow: v4.approval?.flow === 'two_step' ? 'two_step' : DEFAULT_APPROVAL_CONFIG.flow,
+            autoReplayScopes: {
+                shell: v4.approval?.autoReplayScopes?.shell !== false,
+                tool: v4.approval?.autoReplayScopes?.tool === true,
+                subagent: v4.approval?.autoReplayScopes?.subagent === true,
+            },
+            executionLeaseMs: typeof v4.approval?.executionLeaseMs === 'number' && v4.approval.executionLeaseMs > 0
+                ? v4.approval.executionLeaseMs
+                : DEFAULT_APPROVAL_CONFIG.executionLeaseMs,
+        },
         egress: {
             enabled: v4.egress?.enabled === true,
             listenHost: normalizeEgressListenHost(typeof v4.egress?.listenHost === 'string' && v4.egress.listenHost.trim()
@@ -752,6 +793,14 @@ export function mergeConfig(existing, defaults = DEFAULT_CONFIG_V4) {
             ...defaults.approvalSigning,
             ...migrated.approvalSigning,
         },
+        approval: {
+            ...defaults.approval,
+            ...migrated.approval,
+            autoReplayScopes: {
+                ...defaults.approval.autoReplayScopes,
+                ...migrated.approval.autoReplayScopes,
+            },
+        },
         egress: {
             ...defaults.egress,
             ...migrated.egress,

package/dist/core/gate-engine.js

@@ -167,28 +167,28 @@ function applyFsScopePeripheralPolicy(outsideRepoPaths, result, options) {
     return result;
 }
 function applySandboxOutsideBoundary(command, action, result, options) {
-    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot);
+    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot, options.trustedWorkspaceRoots);
     return applySandboxFsScopeBoundary(outsideRepoPaths, result, options, {
         redirect: command.includes('>'),
     });
 }
 function applyShellPeripheralPolicy(command, action, result, options) {
-    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot);
+    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot, options.trustedWorkspaceRoots);
     return applyFsScopePeripheralPolicy(outsideRepoPaths, result, options);
 }
-function outsideRepoPathsForToolAction(action) {
+function outsideRepoPathsForToolAction(action, options) {
     const payload = action.payload ?? {};
-    const paths = new Set(collectOutsideRepoPathsFromToolPayload(payload, action.cwd, action.repoRoot));
+    const paths = new Set(collectOutsideRepoPathsFromToolPayload(payload, action.cwd, action.repoRoot, options.trustedWorkspaceRoots));
     const command = shellCommandFromPayload(payload);
     if (command) {
-        for (const resolved of collectOutsideRepoPaths(command, action.cwd, action.repoRoot)) {
+        for (const resolved of collectOutsideRepoPaths(command, action.cwd, action.repoRoot, options.trustedWorkspaceRoots)) {
             paths.add(resolved);
         }
     }
     return [...paths];
 }
 function applyToolSandboxPolicies(action, result, options) {
-    const outsideRepoPaths = outsideRepoPathsForToolAction(action);
+    const outsideRepoPaths = outsideRepoPathsForToolAction(action, options);
     const command = shellCommandFromPayload(action.payload ?? {});
     let next = applySandboxFsScopeBoundary(outsideRepoPaths, result, options, {
         redirect: command.includes('>'),

package/dist/core/harvest.d.ts

@@ -0,0 +1,53 @@
+import type { CorpusCase } from '../corpus/types.js';
+import type { AuditRecord } from './audit-types.js';
+export declare const HARVEST_REPORT_SCHEMA_VERSION = 1;
+export type HarvestCandidateSource = 'deny_then_approve' | 'repeated_ask' | 'read_style_signal' | 'overrides_allow';
+export type HarvestReviewOutcome = 'provably-benign' | 'accepted-benign' | 'reject';
+export interface HarvestCandidate {
+    kind: 'shell';
+    command: string;
+    fingerprint: string;
+    reason: string;
+    sources: HarvestCandidateSource[];
+    askCount: number;
+    approvedAfterDeny: boolean;
+}
+export type AvailabilitySignal = 'missing_trusted_cwd' | 'judge_timeout' | 'judge_fallback';
+export interface AvailabilityQueueItem {
+    kind: 'shell';
+    command: string;
+    fingerprint: string;
+    reason: string;
+    availabilitySignal: AvailabilitySignal;
+    judgeFallbackReason?: string;
+    askCount: number;
+}
+export interface HarvestReport {
+    schemaVersion: typeof HARVEST_REPORT_SCHEMA_VERSION;
+    /** Initial harvest scope — shell audit traces only. */
+    scope: 'shell';
+    candidates: HarvestCandidate[];
+    availabilityQueue: AvailabilityQueueItem[];
+}
+export declare function extractAvailabilityQueue(records: AuditRecord[]): AvailabilityQueueItem[];
+/** Shell gate rows plus approval events — matches what `belay harvest list` needs. */
+export declare function filterRecordsForHarvest(records: AuditRecord[], options?: {
+    since?: string;
+    until?: string;
+}): AuditRecord[];
+export declare function extractHarvestCandidates(records: AuditRecord[], options?: {
+    allowPatterns?: string[];
+}): HarvestCandidate[];
+export declare function buildHarvestReport(records: AuditRecord[], options?: {
+    allowPatterns?: string[];
+}): HarvestReport;
+export declare function applyHarvestReview(cases: CorpusCase[], params: {
+    command: string;
+    outcome: HarvestReviewOutcome;
+    reason?: string;
+}): {
+    cases: CorpusCase[];
+    applied: boolean;
+    ok: boolean;
+    message: string;
+};