@guilz-dev/belay 0.6.0 → 0.8.0

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

@@ -1,12 +1,200 @@
 import { createHash } from 'node:crypto';
 import path from 'node:path';
+import { isGitMetadataPath } from '../git-resource-identity.js';
 import { matchesSensitivePath } from '../glob.js';
+import { parseNetworkEndpoint } from '../network-endpoint.js';
 import { canonicalPath, pathWithinRoot, resolveWorkspaceRootMatch } from '../path-utils.js';
+import { tokenizeShell } from '../shell-tokenizer.js';
 import { BOUNDARY_GRANT_ISSUER_CONTAINER, isPathWithinBoundaryMount, materializeContainerBoundaryGrant, } from './boundary-grant-materialize.js';
 import { boundaryVerifiedAllowEnabled } from './boundary-profile.js';
 import { isGrantScopeTooBroad } from './grant.js';
 import { broadGrantTargetsRequest, grantMatchesRequest } from './grant-match.js';
 import { CAPABILITY_REQUEST_VERSION, } from './request.js';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '0:0:0:0:0:0:0:1']);
+const DESTRUCTIVE_EFFECT_SIGNALS = new Set([
+    'git_history_destructive',
+    'git.destructive_history_write',
+    'git.destructive_worktree_write',
+]);
+const HIGH_STAKES_EFFECT_PATHS = [
+    /(?:^|[/\\])(?:\.env(?:\..*)?|credentials?(?:\.json)?|secrets?|authorized_keys|id_(?:rsa|dsa|ecdsa|ed25519)|[^/\\]+\.pem|\.ssh[/\\]config|\.zshrc|\.bashrc|\.git-credentials|\.npmrc|\.netrc|\.kube[/\\]config|\.docker[/\\]config\.json|\.gnupg(?:[/\\].*)?|\.pypirc)(?:$|[/\\])/i,
+    /(?:^|[/\\])application_default_credentials\.json$/i,
+    /(?:^|[/\\])\.config[/\\]gcloud[/\\](?:application_default_credentials\.json|credentials\.db|access_tokens\.db|legacy_credentials(?:[/\\].*)?)$/i,
+    /(?:^|[/\\])\.aws[/\\](?:credentials|config)$/i,
+    /(?:^|[/\\])\.azure[/\\](?:accessTokens\.json|azureProfile\.json|msal_token_cache\.(?:bin|json)|service_principal_entries\.json)$/i,
+    /(?:^|[/\\])\.terraform\.d[/\\]credentials\.tfrc\.json$/i,
+    /(?:^|[/\\])\.config[/\\]gh[/\\]hosts\.ya?ml$/i,
+    /(?:^|[/\\])\.oci[/\\]config$/i,
+    /(?:^|[/\\])\.config[/\\]doctl[/\\]config\.ya?ml$/i,
+];
+function effectDecision(effectDisposition, reason, matchedRule, signals) {
+    return {
+        effectDisposition,
+        outcome: effectDisposition === 'ask' ? 'require_approval' : 'allow',
+        reason,
+        signals: [...signals],
+        matchedRule,
+    };
+}
+function effectPathIsLocal(target, context) {
+    const resolved = resolveCapabilityPath(target, context.cwd);
+    return (resolveWorkspaceRootMatch(context.repoRoot, [...(context.trustedWorkspaceRoots ?? [])], resolved) !== null);
+}
+function effectPathIsHighStakes(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;
+    }
+    return matchesSensitivePath(workspaceMatch.relativePath.replaceAll('\\', '/'), [
+        ...(context.sensitivePaths ?? []),
+    ]);
+}
+/**
+ * Policy for a lowered shell effect. It intentionally ignores executable
+ * command names, segment heads, command text, and config allowlists.
+ */
+export function evaluateEffectRequirementPolicy(requirement, context) {
+    const signals = [...requirement.evidence.signals];
+    const capabilityRequest = context.capabilityRequest ?? {
+        version: CAPABILITY_REQUEST_VERSION,
+        principal: { repoRoot: context.repoRoot },
+        action: requirement.action,
+        resource: requirement.resource,
+        context: {
+            cwd: context.cwd,
+            inputFingerprint: 'effect-plan',
+            hookKind: 'shell',
+            analysisBasis: [...requirement.evidence.basis],
+        },
+        evidence: {
+            level: requirement.evidence.level,
+            signals,
+        },
+    };
+    if (signals.includes('forged_grant')) {
+        return effectDecision('ask', 'grant_forgery', 'forbid.grant_forgery', [
+            ...signals,
+            'grant_forgery',
+        ]);
+    }
+    if (context.grants?.some((grant) => isGrantScopeTooBroad(grant) && broadGrantTargetsRequest(grant, capabilityRequest))) {
+        return effectDecision('ask', 'grant_scope_too_broad', 'forbid.broad_grant', [
+            ...signals,
+            'grant_scope_too_broad',
+        ]);
+    }
+    const matchedGrant = requirement.resource.kind === 'executable'
+        ? null
+        : findFreshGrant(capabilityRequest, [...(context.grants ?? [])]);
+    if (matchedGrant) {
+        return effectDecision('allow', 'capability_grant', 'grant.exact', grantDecisionSignals(capabilityRequest, matchedGrant));
+    }
+    if (requirement.evidence.level === 'indeterminate' ||
+        requirement.action === 'indeterminate' ||
+        requirement.tag === 'indeterminate') {
+        return effectDecision('ask', 'indeterminate_effect', 'effect.indeterminate', [
+            ...signals,
+            'indeterminate',
+        ]);
+    }
+    if (signals.some((signal) => DESTRUCTIVE_EFFECT_SIGNALS.has(signal))) {
+        return effectDecision('ask', 'git_history_destructive', 'effect.destructive', signals);
+    }
+    if (signals.includes('belay_control_plane_command')) {
+        return effectDecision('allow', 'belay_control_plane_command', 'effect.belay_control_plane_command', signals);
+    }
+    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',
+                ]);
+            }
+            return effectDecision('allow', 'read_only', 'effect.fs_read', signals);
+        case 'fs.write':
+            if (requirement.resource.kind === 'package-cache') {
+                return effectDecision('allow_flagged', 'repo_local_mutation', 'effect.package_cache_write', signals);
+            }
+            if (requirement.resource.kind !== 'path') {
+                return effectDecision('ask', 'indeterminate_effect', 'effect.fs_write_unknown', signals);
+            }
+            if (effectPathIsHighStakes(requirement.resource.path, context)) {
+                return effectDecision('ask', 'high_stakes_path', 'effect.fs_write_high_stakes', [
+                    ...signals,
+                    'tier1_catastrophic',
+                    ...(!effectPathIsLocal(requirement.resource.path, context)
+                        ? ['outside_repo_secret_credential_path']
+                        : []),
+                ]);
+            }
+            return effectPathIsLocal(requirement.resource.path, context)
+                ? effectDecision('allow_flagged', 'repo_local_mutation', 'effect.fs_write_local', signals)
+                : effectDecision('ask', 'outside_repo_mutation', 'effect.fs_write_outside', signals);
+        case 'process.exec':
+            if (requirement.resource.kind !== 'executable') {
+                return effectDecision('ask', 'indeterminate_effect', 'effect.process_unknown', signals);
+            }
+            if (requirement.resource.operation === 'inspect') {
+                return effectDecision('allow', 'read_only', 'effect.process_inspect', signals);
+            }
+            if (requirement.resource.operation === 'spawn') {
+                return effectDecision('allow_flagged', 'repo_local_mutation', 'effect.process_spawn', signals);
+            }
+            return effectDecision('ask', 'high_stakes_path', 'effect.process_signal', signals);
+        case 'network.connect': {
+            if (requirement.tag === 'network.acquire' ||
+                requirement.resource.kind !== 'network' ||
+                !requirement.resource.mode ||
+                !requirement.resource.payload) {
+                return effectDecision('ask', 'external_effect', 'effect.network_unknown', signals);
+            }
+            const loopback = LOOPBACK_HOSTS.has(requirement.resource.host.replace(/^\[|\]$/g, '').toLowerCase());
+            if (requirement.resource.payload === 'secret') {
+                return effectDecision('ask', 'high_stakes_path', 'effect.network_secret_payload', [
+                    ...signals,
+                    'secret_payload_send',
+                ]);
+            }
+            if (loopback && requirement.resource.mode === 'mutate') {
+                return effectDecision('allow_flagged', 'repo_local_mutation', 'effect.network_loopback_mutation', signals);
+            }
+            if (requirement.resource.mode === 'read' && requirement.resource.payload === 'none') {
+                return effectDecision('allow', 'read_only', 'effect.network_read', signals);
+            }
+            return effectDecision('ask', 'external_effect', 'effect.network_remote_mutation', signals);
+        }
+        case 'git.ref.write':
+            if (requirement.resource.kind !== 'git-ref' || !requirement.resource.scope) {
+                return effectDecision('ask', 'indeterminate_effect', 'effect.git_ref_unknown', signals);
+            }
+            if (requirement.resource.scope === 'remote') {
+                return effectDecision('ask', 'external_effect', 'effect.git_ref_remote', signals);
+            }
+            if (requirement.resource.repoPath &&
+                !effectPathIsLocal(requirement.resource.repoPath, context)) {
+                return effectDecision('ask', 'outside_repo_mutation', 'effect.git_ref_outside', signals);
+            }
+            return effectDecision('allow_flagged', 'repo_local_mutation', 'effect.git_ref_local', signals);
+        case 'secret.read':
+            return effectDecision('ask', 'high_stakes_path', 'effect.secret_read', signals);
+        case 'control_plane.write':
+            return effectDecision('ask', 'control_plane_mutation', 'effect.control_plane_write', signals);
+        default:
+            return effectDecision('ask', 'indeterminate_effect', 'effect.unknown', signals);
+    }
+}
 function enrichAuthWithMaterializedGrants(request, config, auth) {
     if (!auth?.attestation || !boundaryVerifiedAllowEnabled(auth.attestation)) {
         return auth;
@@ -116,21 +304,27 @@ function resourcePathForShellAnalysis(analysis) {
     const resolved = targets.map((target) => analysis.resolvedPathTargets?.length
         ? canonicalPath(target)
         : resolveCapabilityPath(target, analysis.cwd));
+    const [first] = resolved;
+    if (!first) {
+        return null;
+    }
     if (analysis.effect === 'local_mutation') {
         const outside = resolved.find((candidate) => !pathWithinRoot(repoRoot, candidate));
-        return outside ?? resolved[resolved.length - 1];
+        return outside ?? resolved.at(-1) ?? first;
     }
-    return resolved[0];
+    return first;
 }
 function resourceForShellAnalysis(analysis) {
     if (isGitRefWrite(analysis)) {
         return { kind: 'git-ref', ref: 'push' };
     }
-    if (analysis.egressClass === 'ambiguous' ||
-        analysis.egressClass === 'read' ||
-        analysis.egressClass === 'destructive' ||
-        analysis.location === 'external') {
-        return { kind: 'network', host: '*', protocol: 'unknown' };
+    if (isNetworkShellAnalysis(analysis)) {
+        const exact = exactNetworkResources(analysis);
+        return ((exact.length === 1 ? exact[0] : undefined) ?? {
+            kind: 'network',
+            host: '*',
+            protocol: 'unknown',
+        });
     }
     const resourcePath = resourcePathForShellAnalysis(analysis);
     if (resourcePath) {
@@ -138,8 +332,114 @@ function resourceForShellAnalysis(analysis) {
     }
     return { kind: 'executable', command: analysis.segmentHead };
 }
+function isNetworkShellAnalysis(analysis) {
+    return (analysis.egressClass === 'ambiguous' ||
+        analysis.egressClass === 'read' ||
+        analysis.egressClass === 'destructive' ||
+        analysis.location === 'external');
+}
+const SCP_STYLE_COMMANDS = new Set(['git', 'rsync', 'scp']);
+const PACKAGE_SPEC_COMMANDS = new Set(['bun', 'npm', 'npx', 'pnpm', 'yarn']);
+const NETWORK_VALUE_OPTIONS = new Set(['--registry', '--url']);
+const GIT_OPTIONS_WITH_VALUE = new Set([
+    '-C',
+    '-b',
+    '-c',
+    '-o',
+    '--branch',
+    '--config',
+    '--depth',
+    '--filter',
+    '--git-dir',
+    '--namespace',
+    '--origin',
+    '--reference',
+    '--separate-git-dir',
+    '--upload-pack',
+    '--work-tree',
+]);
+function gitRemoteOperand(tokens) {
+    let cursor = 1;
+    while (cursor < tokens.length) {
+        const token = tokens[cursor];
+        if (!token) {
+            return null;
+        }
+        if (GIT_OPTIONS_WITH_VALUE.has(token)) {
+            cursor += 2;
+            continue;
+        }
+        if (token.startsWith('-')) {
+            cursor += 1;
+            continue;
+        }
+        break;
+    }
+    const subcommand = tokens[cursor];
+    if (!subcommand) {
+        return null;
+    }
+    const positionals = [];
+    let skipOptionValue = false;
+    for (const token of tokens.slice(cursor + 1)) {
+        if (skipOptionValue) {
+            skipOptionValue = false;
+            continue;
+        }
+        if (GIT_OPTIONS_WITH_VALUE.has(token)) {
+            skipOptionValue = true;
+            continue;
+        }
+        if (token.startsWith('-')) {
+            continue;
+        }
+        positionals.push(token);
+    }
+    if (['clone', 'fetch', 'ls-remote', 'pull', 'push'].includes(subcommand)) {
+        return positionals[0] ?? null;
+    }
+    if (subcommand === 'remote' && positionals[0] === 'add') {
+        return positionals[2] ?? null;
+    }
+    if (subcommand === 'submodule' && positionals[0] === 'add') {
+        return positionals[1] ?? null;
+    }
+    return null;
+}
+function exactNetworkResources(analysis) {
+    const resources = new Map();
+    const shellTokens = tokenizeShell(analysis.command);
+    const gitRemote = analysis.segmentHead === 'git' ? gitRemoteOperand(shellTokens) : null;
+    for (const rawToken of shellTokens) {
+        const optionSeparator = rawToken.startsWith('-') ? rawToken.indexOf('=') : -1;
+        const optionName = optionSeparator === -1 ? null : rawToken.slice(0, optionSeparator);
+        const token = optionSeparator !== -1 && optionName && NETWORK_VALUE_OPTIONS.has(optionName)
+            ? rawToken.slice(optionSeparator + 1)
+            : rawToken;
+        const endpoint = parseNetworkEndpoint(token, {
+            allowHostedGitShorthand: PACKAGE_SPEC_COMMANDS.has(analysis.segmentHead),
+            allowScpStyle: SCP_STYLE_COMMANDS.has(analysis.segmentHead) &&
+                (analysis.segmentHead !== 'git' || rawToken === gitRemote),
+        });
+        if (!endpoint) {
+            continue;
+        }
+        const resource = { kind: 'network', ...endpoint };
+        resources.set(`${resource.host}:${resource.port ?? ''}:${resource.protocol}`, resource);
+    }
+    return [...resources.values()];
+}
 export function buildShellCapabilityRequest(analysis) {
-    return {
+    const [request] = buildShellCapabilityRequests(analysis);
+    if (!request) {
+        throw new Error('shell analysis produced no capability request');
+    }
+    return request;
+}
+export function buildShellCapabilityRequests(analysis) {
+    const resources = isNetworkShellAnalysis(analysis) ? exactNetworkResources(analysis) : [];
+    const selectedResources = resources.length > 0 ? resources : [resourceForShellAnalysis(analysis)];
+    return selectedResources.map((resource) => ({
         version: CAPABILITY_REQUEST_VERSION,
         principal: {
             adapter: analysis.adapter,
@@ -147,7 +447,7 @@ export function buildShellCapabilityRequest(analysis) {
             sessionHash: hashSession(`${analysis.repoRoot}:${analysis.cwd}`),
         },
         action: actionForShellAnalysis(analysis),
-        resource: resourceForShellAnalysis(analysis),
+        resource,
         context: {
             cwd: analysis.cwd,
             inputFingerprint: analysis.inputFingerprint,
@@ -163,7 +463,7 @@ export function buildShellCapabilityRequest(analysis) {
             level: evidenceLevelForOpacity(analysis.opacity),
             signals: [...analysis.signals],
         },
-    };
+    }));
 }
 function actionForFileMutation(analysis) {
     if (analysis.locationLabel === 'control_plane') {
@@ -233,6 +533,16 @@ function shellLocationFromRequest(request) {
 function isRepoLocalShellLocation(request) {
     return shellLocationFromRequest(request) === 'repo_local';
 }
+function isRepoLocalPackageExec(request) {
+    if (request.action !== 'process.exec' || request.resource.kind !== 'executable') {
+        return false;
+    }
+    if (!request.evidence.signals.includes('package_exec.local_bin_resolved')) {
+        return false;
+    }
+    const commandPath = canonicalPath(request.resource.command);
+    return path.isAbsolute(commandPath) && pathWithinRoot(request.principal.repoRoot, commandPath);
+}
 function isRepoLocalRoutineWrite(request, sensitivePaths) {
     if (!isRepoLocalShellLocation(request)) {
         return false;
@@ -297,6 +607,14 @@ function builtInRule(request, context) {
             matchedRule: 'builtin.subagent',
         };
     }
+    if (isRepoLocalPackageExec(request)) {
+        return {
+            outcome: 'allow',
+            reason: 'read_only',
+            signals: [...request.evidence.signals, 'repo_local_exec'],
+            matchedRule: 'builtin.repo_local_exec',
+        };
+    }
     if (request.action === 'secret.read' || request.action === 'git.ref.write') {
         return {
             outcome: 'require_approval',
@@ -456,14 +774,69 @@ export function getDefaultPolicyEngine() {
 export function policyDecisionRequiresAsk(decision) {
     return decision.outcome === 'require_approval' || decision.outcome === 'deny';
 }
+function policyOutcomeRank(outcome) {
+    switch (outcome) {
+        case 'deny':
+            return 3;
+        case 'require_approval':
+            return 2;
+        case 'allow':
+            return 1;
+        default:
+            return 0;
+    }
+}
+export function combinePolicyDecisions(decisions) {
+    if (!decisions.length) {
+        return {
+            outcome: 'allow',
+            reason: 'read_only',
+            signals: [],
+            matchedRule: 'plan.conjunction',
+        };
+    }
+    const sorted = [...decisions].sort((left, right) => policyOutcomeRank(right.outcome) - policyOutcomeRank(left.outcome));
+    const worst = sorted[0];
+    if (!worst) {
+        return {
+            outcome: 'allow',
+            reason: 'read_only',
+            signals: [],
+            matchedRule: 'plan.conjunction',
+        };
+    }
+    return worst;
+}
+export function evaluateCapabilityRequestsPolicy(requests, config, auth, trustedWorkspaceRoots) {
+    let workingAuth = auth;
+    const decisions = [];
+    for (const request of requests) {
+        const enriched = enrichAuthWithMaterializedGrants(request, config, workingAuth);
+        const decision = getDefaultPolicyEngine().evaluate(request, buildAuthorizationContext(config, trustedWorkspaceRoots, enriched));
+        decisions.push(decision);
+        const previousCount = workingAuth?.grants?.length ?? 0;
+        const nextCount = enriched?.grants?.length ?? 0;
+        if (nextCount > previousCount) {
+            workingAuth = enriched;
+        }
+    }
+    return {
+        decisions,
+        decision: combinePolicyDecisions(decisions),
+    };
+}
 export function evaluateShellPolicy(analysis, config, auth) {
-    const request = buildShellCapabilityRequest(analysis);
-    const enriched = enrichAuthWithMaterializedGrants(request, config, {
+    const requests = buildShellCapabilityRequests(analysis);
+    const enrichedAuth = {
         ...auth,
         sensitivePaths: auth?.sensitivePaths ?? analysis.sensitivePaths,
-    });
-    const decision = getDefaultPolicyEngine().evaluate(request, buildAuthorizationContext(config, analysis.trustedWorkspaceRoots, enriched));
-    return { request, decision };
+    };
+    const { decision } = evaluateCapabilityRequestsPolicy(requests, config, enrichedAuth, analysis.trustedWorkspaceRoots);
+    const [request] = requests;
+    if (!request) {
+        throw new Error('shell analysis produced no capability request');
+    }
+    return { request, requests, decision };
 }
 export function evaluateFileMutationPolicy(analysis, config, auth) {
     const request = buildFileMutationCapabilityRequest(analysis);

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

@@ -2,6 +2,10 @@ export declare const CAPABILITY_REQUEST_VERSION: 1;
 export type CapabilityAction = 'fs.read' | 'fs.write' | 'process.exec' | 'network.connect' | 'secret.read' | 'git.ref.write' | 'control_plane.write' | 'indeterminate';
 export type CapabilityEvidenceLevel = 'certain' | 'possible' | 'indeterminate';
 export type CapabilityHookKind = 'shell' | 'tool' | 'subagent';
+export type NetworkMode = 'read' | 'mutate' | 'ambiguous';
+export type NetworkPayload = 'none' | 'present' | 'secret';
+export type ProcessOperation = 'inspect' | 'spawn' | 'signal';
+export type GitRefScope = 'local' | 'remote';
 export interface CapabilityPrincipal {
     adapter?: string;
     repoRoot: string;
@@ -15,12 +19,20 @@ export type CapabilityResource = {
     host: string;
     port?: number;
     protocol?: string;
+    mode?: NetworkMode;
+    payload?: NetworkPayload;
 } | {
     kind: 'executable';
     command: string;
+    operation?: ProcessOperation;
+} | {
+    kind: 'package-cache';
+    manager: 'npm' | 'pnpm';
 } | {
     kind: 'git-ref';
     ref: string;
+    scope?: GitRefScope;
+    repoPath?: string;
 } | {
     kind: 'unknown';
 };

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

@@ -1,4 +1,3 @@
-export { evaluateSegmentShellPolicy, type SegmentShellPolicyInput, } from '../verdict/shell-policy.js';
 export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
 export { type CapabilityAuthorizationMetadata, policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
 export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, type FileMutationCapabilityAnalysis, policyDecisionRequiresAsk, type ShellCapabilityAnalysis, type SubagentCapabilityAnalysis, } from './policy-engine.js';

package/dist/core/capability/resolver.js

@@ -1,4 +1,3 @@
-export { evaluateSegmentShellPolicy, } from '../verdict/shell-policy.js';
 export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
 export { policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
 export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, policyDecisionRequiresAsk, } from './policy-engine.js';

package/dist/core/config.d.ts

@@ -46,6 +46,15 @@ export interface BelayModelAssistConfig {
     model?: string;
     timeoutMs?: number;
 }
+export interface BelayFileCheckpointConfig {
+    enabled: boolean;
+    allowNonGit: boolean;
+    maxFiles: number;
+    maxSourceBytes: number;
+    maxWorkspaceBytes: number;
+    prepareTimeoutMs: number;
+    copyConcurrency: number;
+}
 export interface BelayTransactionalConfig {
     enabled: boolean;
     minConfidence: number;
@@ -55,6 +64,14 @@ export interface BelayTransactionalConfig {
     gates: {
         shell: boolean;
     };
+    fileCheckpoint: BelayFileCheckpointConfig;
+    checkpoint?: {
+        enabled: boolean;
+        appliedRetentionHours: number;
+        restoredRetentionHours: number;
+        maxCheckpoints: number;
+        maxBytes: number;
+    };
 }
 export interface BelayPolicyConfig {
     unknownLocalEffect: UnknownLocalEffectPolicy;
@@ -196,6 +213,9 @@ export type BelayConfig = BelayConfigV4;
 export declare const DEFAULT_FENCE_WARN_THRESHOLD = 0.5;
 export declare const DEFAULT_CONFIDENCE_THRESHOLDS: BelayConfidenceThresholds;
 export declare const DEFAULT_MODEL_ASSIST: BelayModelAssistConfig;
+export declare const DEFAULT_FILE_CHECKPOINT: BelayFileCheckpointConfig;
+export declare function normalizeFileCheckpointConfig(raw: Partial<BelayFileCheckpointConfig> | undefined): BelayFileCheckpointConfig;
+export declare const DEFAULT_RECOVERY_CHECKPOINT: NonNullable<BelayTransactionalConfig['checkpoint']>;
 export declare const DEFAULT_TRANSACTIONAL_V3: BelayTransactionalConfig;
 export declare const LEGACY_POLICY_V3: BelayPolicyConfig;
 /** Fresh install defaults: recoverable-first with opaque/unparseable fail-closed. */

package/dist/core/config.js

@@ -51,6 +51,46 @@ export const DEFAULT_MODEL_ASSIST = {
     enabled: false,
     timeoutMs: 3000,
 };
+export const DEFAULT_FILE_CHECKPOINT = {
+    enabled: false,
+    allowNonGit: false,
+    maxFiles: 100_000,
+    maxSourceBytes: 2_147_483_648,
+    maxWorkspaceBytes: 4_294_967_296,
+    prepareTimeoutMs: 30_000,
+    copyConcurrency: 8,
+};
+function clampCopyConcurrency(value) {
+    return Math.min(32, Math.max(1, Math.floor(value)));
+}
+export function normalizeFileCheckpointConfig(raw) {
+    return {
+        enabled: raw?.enabled === true,
+        allowNonGit: raw?.allowNonGit === true,
+        maxFiles: typeof raw?.maxFiles === 'number' && raw.maxFiles > 0
+            ? Math.floor(raw.maxFiles)
+            : DEFAULT_FILE_CHECKPOINT.maxFiles,
+        maxSourceBytes: typeof raw?.maxSourceBytes === 'number' && raw.maxSourceBytes > 0
+            ? Math.floor(raw.maxSourceBytes)
+            : DEFAULT_FILE_CHECKPOINT.maxSourceBytes,
+        maxWorkspaceBytes: typeof raw?.maxWorkspaceBytes === 'number' && raw.maxWorkspaceBytes > 0
+            ? Math.floor(raw.maxWorkspaceBytes)
+            : DEFAULT_FILE_CHECKPOINT.maxWorkspaceBytes,
+        prepareTimeoutMs: typeof raw?.prepareTimeoutMs === 'number' && raw.prepareTimeoutMs > 0
+            ? Math.floor(raw.prepareTimeoutMs)
+            : DEFAULT_FILE_CHECKPOINT.prepareTimeoutMs,
+        copyConcurrency: typeof raw?.copyConcurrency === 'number' && raw.copyConcurrency > 0
+            ? clampCopyConcurrency(raw.copyConcurrency)
+            : DEFAULT_FILE_CHECKPOINT.copyConcurrency,
+    };
+}
+export const DEFAULT_RECOVERY_CHECKPOINT = {
+    enabled: false,
+    appliedRetentionHours: 7 * 24,
+    restoredRetentionHours: 24,
+    maxCheckpoints: 20,
+    maxBytes: 1024 * 1024 * 1024,
+};
 export const DEFAULT_TRANSACTIONAL_V3 = {
     enabled: false,
     minConfidence: DEFAULT_CONFIDENCE_THRESHOLDS.flag,
@@ -60,6 +100,8 @@ export const DEFAULT_TRANSACTIONAL_V3 = {
     gates: {
         shell: true,
     },
+    fileCheckpoint: { ...DEFAULT_FILE_CHECKPOINT },
+    checkpoint: { ...DEFAULT_RECOVERY_CHECKPOINT },
 };
 export const LEGACY_POLICY_V3 = {
     unknownLocalEffect: 'allow_flagged',
@@ -696,6 +738,26 @@ export function normalizeConfig(config) {
                     gates: {
                         shell: v4.policy?.transactional?.gates?.shell !== false,
                     },
+                    fileCheckpoint: normalizeFileCheckpointConfig(v4.policy?.transactional?.fileCheckpoint),
+                    checkpoint: {
+                        enabled: v4.policy?.transactional?.checkpoint?.enabled === true,
+                        appliedRetentionHours: typeof v4.policy?.transactional?.checkpoint?.appliedRetentionHours === 'number' &&
+                            v4.policy.transactional.checkpoint.appliedRetentionHours > 0
+                            ? v4.policy.transactional.checkpoint.appliedRetentionHours
+                            : DEFAULT_RECOVERY_CHECKPOINT.appliedRetentionHours,
+                        restoredRetentionHours: typeof v4.policy?.transactional?.checkpoint?.restoredRetentionHours === 'number' &&
+                            v4.policy.transactional.checkpoint.restoredRetentionHours > 0
+                            ? v4.policy.transactional.checkpoint.restoredRetentionHours
+                            : DEFAULT_RECOVERY_CHECKPOINT.restoredRetentionHours,
+                        maxCheckpoints: typeof v4.policy?.transactional?.checkpoint?.maxCheckpoints === 'number' &&
+                            v4.policy.transactional.checkpoint.maxCheckpoints > 0
+                            ? Math.floor(v4.policy.transactional.checkpoint.maxCheckpoints)
+                            : DEFAULT_RECOVERY_CHECKPOINT.maxCheckpoints,
+                        maxBytes: typeof v4.policy?.transactional?.checkpoint?.maxBytes === 'number' &&
+                            v4.policy.transactional.checkpoint.maxBytes > 0
+                            ? Math.floor(v4.policy.transactional.checkpoint.maxBytes)
+                            : DEFAULT_RECOVERY_CHECKPOINT.maxBytes,
+                    },
                 };
             })(),
         },
@@ -875,8 +937,6 @@ export function scrubOptionsFromConfig(config) {
 export function classifierOptionsFromConfig(config) {
     return {
         strictChains: config.classifier.strictChains,
-        customExternalCommands: config.overrides.external,
-        customAllowCommands: config.overrides.allow,
         sensitivePaths: config.classifier.sensitivePaths,
         unknownLocalEffect: config.policy.unknownLocalEffect,
         unparseableShell: config.policy.unparseableShell,

package/dist/core/effect-ir/audit.d.ts

@@ -0,0 +1,9 @@
+import type { PolicyDecision } from '../capability/policy-types.js';
+import type { CapabilityRequestV1 } from '../capability/request.js';
+import type { EffectPlan } from './types.js';
+export declare function hashEffectPlan(plan: EffectPlan): string;
+export declare function effectPlanAuditFields(plan: EffectPlan | undefined, policy?: {
+    capabilityRequests?: readonly CapabilityRequestV1[];
+    decisions?: readonly PolicyDecision[];
+    authorizationDecision?: PolicyDecision;
+}): Record<string, unknown>;