@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/core/verdict/launcher-resolve.js

@@ -245,6 +245,13 @@ export function resolveLauncherRecipe(params) {
     if (tokens[0] === 'make' && tokens[1] && !tokens[1].startsWith('-')) {
         return resolveMakeRecipe(params.cwd, params.repoRoot, tokens[1]);
     }
+    if (tokens[0] === 'pnpm' && tokens[1] === 'exec' && tokens[2]) {
+        return {
+            recipes: [tokens.slice(2).join(' ')],
+            opaque: false,
+            reason: 'pnpm_exec',
+        };
+    }
     if (tokens[0] === 'pnpm' && tokens[1] && PNPM_EXEC_LIKE_HEADS.has(tokens[1])) {
         return {
             recipes: [tokens.slice(1).join(' ')],
@@ -254,7 +261,16 @@ export function resolveLauncherRecipe(params) {
     }
     return null;
 }
+const READ_ONLY_LAUNCHER_SUFFIXES = new Set(['--version', '-v', '--help', '-h']);
+function isReadOnlyLauncherInvocation(tokens) {
+    const head = tokens[1];
+    return Boolean(head && READ_ONLY_LAUNCHER_SUFFIXES.has(head));
+}
+export { isReadOnlyLauncherInvocation };
 export function isRoutineLauncher(tokens) {
+    if ((tokens[0] === 'pnpm' || tokens[0] === 'npm') && isReadOnlyLauncherInvocation(tokens)) {
+        return false;
+    }
     return ((tokens[0] === 'npm' && (tokens[1] === 'run' || tokens[1] === 'test')) ||
         tokens[0] === 'pnpm' ||
         tokens[0] === 'make');

package/dist/core/verdict/parser.js

@@ -160,7 +160,12 @@ export function splitTopLevelSegments(command) {
         }
     };
     for (const token of tokens) {
-        if (token === '&&' || token === '||' || token === ';' || token === '|' || token === '&') {
+        if (token === '&&' ||
+            token === '||' ||
+            token === ';' ||
+            token === '|' ||
+            token === '&' ||
+            token === '|&') {
             flush();
             continue;
         }

package/dist/core/verdict/prescan.d.ts

@@ -0,0 +1,15 @@
+import type { Tier1Verdict } from './types.js';
+export declare function prescanInterpreterCode(code: string): Tier1Verdict | null;
+export interface MutationPrescanParams {
+    targets: string[];
+    cwd: string;
+    repoRoot: string;
+    trustedCwd: boolean;
+    trustedWorkspaceRoots?: string[];
+    sensitivePaths: string[];
+}
+/** ADR-002 M3: structural prescan for sensitive / persistent mutation targets (shell redirects, etc.). */
+export declare function prescanMutationTargets(params: MutationPrescanParams): Tier1Verdict | null;
+/** Returns prescan verdict when structural M3 rules require ask (before async judge shadow). */
+export declare function mutationPrescanRequiresAsk(params: MutationPrescanParams): Tier1Verdict | null;
+export declare function tier1RequiresAsk(verdict: Tier1Verdict): boolean;

package/dist/core/verdict/prescan.js

@@ -0,0 +1,68 @@
+import { matchesSensitivePath } from '../glob.js';
+import { resolveMutationTarget, resolveWorkspaceRootMatch } from '../path-utils.js';
+import { resolveTrustedPath } from './containment.js';
+import { isOutsideRepoSecretCredentialPath, isPersistentAgentPath } from './persistent-paths.js';
+const SECRET_PATTERNS = [/\.env\b/i, /\.pem\b/i, /id_rsa\b/i, /credentials/i, /secrets?\b/i];
+const DESTRUCTIVE_VERBS = /\b(rm|rmtree|unlink|delete|truncate|shred|destroy|drop)\b/i;
+const GIT_PATTERNS = /\.git\b/i;
+export function prescanInterpreterCode(code) {
+    const normalized = code.replaceAll('\\', '/');
+    const hitsSecret = SECRET_PATTERNS.some((pattern) => pattern.test(normalized));
+    const hitsGit = GIT_PATTERNS.test(normalized);
+    const hitsDestructive = DESTRUCTIVE_VERBS.test(normalized);
+    if ((hitsSecret || hitsGit) && hitsDestructive) {
+        return {
+            local_recoverable: true,
+            destroys_outside_repo: false,
+            destroys_history_or_secrets: true,
+            reason: 'prescan_destructive_secret',
+        };
+    }
+    return null;
+}
+/** ADR-002 M3: structural prescan for sensitive / persistent mutation targets (shell redirects, etc.). */
+export function prescanMutationTargets(params) {
+    for (const target of params.targets) {
+        const resolved = resolveTrustedPath(target, params.cwd, params.trustedCwd) ??
+            resolveMutationTarget(target, params.cwd);
+        if (!resolved) {
+            continue;
+        }
+        const workspaceMatch = resolveWorkspaceRootMatch(params.repoRoot, params.trustedWorkspaceRoots, resolved);
+        if (workspaceMatch !== null &&
+            matchesSensitivePath(workspaceMatch.relativePath.replaceAll('\\', '/'), params.sensitivePaths)) {
+            return {
+                local_recoverable: false,
+                destroys_outside_repo: false,
+                destroys_history_or_secrets: true,
+                reason: 'sensitive_path_mutation',
+            };
+        }
+        if ((workspaceMatch === null || workspaceMatch.kind === 'trusted') &&
+            isOutsideRepoSecretCredentialPath(resolved)) {
+            return {
+                local_recoverable: false,
+                destroys_outside_repo: false,
+                destroys_history_or_secrets: true,
+                reason: 'outside_repo_secret_credential_path',
+            };
+        }
+        if (isPersistentAgentPath(resolved)) {
+            return {
+                local_recoverable: false,
+                destroys_outside_repo: false,
+                destroys_history_or_secrets: true,
+                reason: 'persistent_agent_path',
+            };
+        }
+    }
+    return null;
+}
+/** Returns prescan verdict when structural M3 rules require ask (before async judge shadow). */
+export function mutationPrescanRequiresAsk(params) {
+    const prescan = prescanMutationTargets(params);
+    return prescan && tier1RequiresAsk(prescan) ? prescan : null;
+}
+export function tier1RequiresAsk(verdict) {
+    return !verdict.local_recoverable || verdict.destroys_history_or_secrets;
+}

package/dist/core/verdict/shell-policy.d.ts

@@ -0,0 +1,25 @@
+import { type ShellCapabilityAnalysis } from '../capability/policy-engine.js';
+import type { PolicyDecision } from '../capability/policy-types.js';
+import type { CapabilityRequestV1 } from '../capability/request.js';
+import type { VerdictContext, VerdictEffect, VerdictLocation, VerdictOpacity } from './types.js';
+export interface SegmentShellPolicyInput {
+    command: string;
+    segmentHead: string;
+    effect: VerdictEffect;
+    location: VerdictLocation;
+    opacity: VerdictOpacity;
+    egressClass?: ShellCapabilityAnalysis['egressClass'];
+    pathArgs: string[];
+    resolvedPathTargets?: string[];
+    signals: string[];
+    context: VerdictContext;
+}
+export declare function evaluateSegmentShellPolicy(input: SegmentShellPolicyInput): {
+    request: CapabilityRequestV1;
+    decision: PolicyDecision;
+};
+/** Attach capability metadata without influencing the verdict (audit / shadow only). */
+export declare function shellPolicyMetadata(input: SegmentShellPolicyInput): {
+    capabilityRequests: CapabilityRequestV1[];
+    authorizationDecision: PolicyDecision;
+};

package/dist/core/verdict/shell-policy.js

@@ -0,0 +1,40 @@
+import { evaluateShellPolicy } from '../capability/policy-engine.js';
+import { cwdRelative } from './containment.js';
+import { verdictFingerprint } from './fingerprint.js';
+import { redactCommand } from './parser.js';
+function toShellCapabilityAnalysis(input) {
+    const relative = cwdRelative(input.context.repoRoot, input.context.cwd);
+    return {
+        command: input.command,
+        hookKind: 'shell',
+        segmentHead: input.segmentHead,
+        effect: input.effect,
+        location: input.location,
+        opacity: input.opacity,
+        egressClass: input.egressClass,
+        pathArgs: input.pathArgs,
+        resolvedPathTargets: input.resolvedPathTargets,
+        signals: input.signals,
+        cwd: input.context.cwd,
+        repoRoot: input.context.repoRoot,
+        inputFingerprint: verdictFingerprint(relative, redactCommand(input.command)),
+        trustedWorkspaceRoots: input.context.trustedWorkspaceRoots,
+        sensitivePaths: input.context.sensitivePaths,
+        protectedArtifactRoots: input.context.protectedArtifactRoots,
+    };
+}
+export function evaluateSegmentShellPolicy(input) {
+    return evaluateShellPolicy(toShellCapabilityAnalysis(input), input.context.config, {
+        grants: input.context.grants,
+        attestation: input.context.attestation,
+        egressProxyActive: input.context.egressProxyActive,
+    });
+}
+/** Attach capability metadata without influencing the verdict (audit / shadow only). */
+export function shellPolicyMetadata(input) {
+    const result = evaluateSegmentShellPolicy(input);
+    return {
+        capabilityRequests: [result.request],
+        authorizationDecision: result.decision,
+    };
+}

package/dist/core/verdict/shell-semantics.d.ts

@@ -0,0 +1,24 @@
+import type { ParsedSegment } from './parser.js';
+import type { VerdictEffect } from './types.js';
+export interface ShellCommandSemantics {
+    effect: VerdictEffect;
+    pathTargets: string[];
+    scopeTargets?: string[];
+    signals: string[];
+    egressClass?: 'read' | 'destructive' | 'ambiguous';
+    requiresAsk?: {
+        reason: string;
+        signals: string[];
+    };
+    effectiveCwd?: string;
+    gitWorkTree?: string;
+    normalizedKey?: string;
+    isReadOnly?: boolean;
+}
+declare const READ_ONLY_KEYS: Set<string>;
+declare const PURE_READ_ONLY_KEYS: Set<string>;
+declare const LOCAL_MUTATION_KEYS: Set<string>;
+export declare const LOCAL_ROUTINE_HEADS: Set<string>;
+export declare function isPureReadOnlySemantics(segment: ParsedSegment, semantics: ShellCommandSemantics): boolean;
+export declare function analyzeShellCommandSemantics(tokens: string[], segment: ParsedSegment, cwd: string): ShellCommandSemantics;
+export { LOCAL_MUTATION_KEYS, PURE_READ_ONLY_KEYS, READ_ONLY_KEYS };

package/dist/core/verdict/shell-semantics.js

@@ -0,0 +1,225 @@
+import path from 'node:path';
+import { extractRedirectTargets } from '../shell-tokenizer.js';
+import { classifyGitCommand } from './git-classifier.js';
+const READ_ONLY_KEYS = new Set([
+    'cat',
+    'cd',
+    'echo',
+    'head',
+    'ls',
+    'pwd',
+    'rg',
+    'sort',
+    'tail',
+    'wc',
+    'which',
+    'find',
+    'grep',
+    'jq',
+    'stat',
+    'file',
+    'du',
+    'readlink',
+    'realpath',
+    'basename',
+    'dirname',
+    'uname',
+    'whoami',
+    'id',
+    'printenv',
+    'test',
+    'printf',
+    'cut',
+    'tr',
+    'uniq',
+    'cmp',
+    'comm',
+    'shasum',
+    'md5sum',
+]);
+const PURE_READ_ONLY_KEYS = new Set([
+    'echo',
+    'pwd',
+    'which',
+    'grep',
+    'jq',
+    'stat',
+    'file',
+    'du',
+    'readlink',
+    'realpath',
+    'basename',
+    'dirname',
+    'uname',
+    'whoami',
+    'id',
+    'printenv',
+    'test',
+    'printf',
+    'cut',
+    'tr',
+    'uniq',
+    'cmp',
+    'comm',
+    'shasum',
+    'md5sum',
+]);
+const LOCAL_MUTATION_KEYS = new Set([
+    'chmod',
+    'cp',
+    'mkdir',
+    'mv',
+    'rm',
+    'sed',
+    'tee',
+    'touch',
+    'truncate',
+]);
+export const LOCAL_ROUTINE_HEADS = new Set([
+    'tsc',
+    'vitest',
+    'vite',
+    'webpack',
+    'esbuild',
+    'rollup',
+    'jest',
+    'mocha',
+    'cargo',
+    'go',
+    'make',
+    'cmake',
+    'biome',
+    'eslint',
+]);
+function looksLikePathToken(token) {
+    if (!token || token.startsWith('-')) {
+        return false;
+    }
+    return (token.includes('/') || token.includes('\\') || token.startsWith('.') || token.includes('...'));
+}
+function filterRoutinePathTargets(head, targets) {
+    if (!LOCAL_ROUTINE_HEADS.has(head)) {
+        return targets;
+    }
+    return targets.filter((target) => looksLikePathToken(target));
+}
+function extractFilePathOperands(tokens) {
+    const redirects = extractRedirectTargets(tokens);
+    const args = [...redirects];
+    for (let index = 1; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token || token.startsWith('-')) {
+            continue;
+        }
+        if (redirects.includes(token)) {
+            continue;
+        }
+        args.push(token);
+    }
+    return args;
+}
+function isRsyncRemoteOperand(token) {
+    if (/^rsync:\/\/.+/.test(token)) {
+        return true;
+    }
+    if (/^(?:[^@\s/:]+@)?(?:\[[^\]]+\]|[^:/\s]+)::/.test(token)) {
+        return true;
+    }
+    if (!/^[A-Za-z]:[\\/]/.test(token) &&
+        /^(?:[^@\s/:]+@)?(?:\[[^\]]+\]|[^:/\s]+):[^:].*/.test(token)) {
+        return true;
+    }
+    if (/^\/\/.+\//.test(token)) {
+        return true;
+    }
+    return false;
+}
+function classifyRsync(tokens) {
+    const args = tokens.slice(1);
+    const pathTargets = args.filter((token) => token && !token.startsWith('-'));
+    const signals = ['rsync'];
+    const destructive = args.some((token) => token.startsWith('--delete') ||
+        token === '--del' ||
+        token === '--remove-source-files' ||
+        token.startsWith('--remove-source-files='));
+    if (destructive) {
+        return {
+            effect: 'local_mutation',
+            pathTargets,
+            signals: [...signals, 'rsync.destructive'],
+            requiresAsk: {
+                reason: 'rsync_destructive',
+                signals: ['rsync.destructive', 'rsync.delete'],
+            },
+        };
+    }
+    const remote = pathTargets.some((token) => isRsyncRemoteOperand(token));
+    if (remote) {
+        return {
+            effect: 'remote_mutation',
+            pathTargets,
+            signals: [...signals, 'rsync.remote'],
+            egressClass: 'ambiguous',
+        };
+    }
+    return {
+        effect: 'local_mutation',
+        pathTargets,
+        signals: [...signals, 'rsync.local'],
+    };
+}
+export function isPureReadOnlySemantics(segment, semantics) {
+    return (semantics.isReadOnly === true ||
+        PURE_READ_ONLY_KEYS.has(segment.head) ||
+        PURE_READ_ONLY_KEYS.has(segment.key) ||
+        PURE_READ_ONLY_KEYS.has(semantics.normalizedKey ?? ''));
+}
+export function analyzeShellCommandSemantics(tokens, segment, cwd) {
+    const head = segment.head;
+    const basename = path.basename(tokens[0] ?? head);
+    if (basename === 'git') {
+        const gitSemantics = classifyGitCommand(tokens, cwd);
+        if (gitSemantics) {
+            return {
+                effect: gitSemantics.effect,
+                pathTargets: gitSemantics.pathTargets,
+                scopeTargets: gitSemantics.scopeTargets,
+                signals: gitSemantics.signals,
+                egressClass: gitSemantics.egressClass,
+                requiresAsk: gitSemantics.requiresAsk,
+                effectiveCwd: gitSemantics.effectiveCwd,
+                gitWorkTree: gitSemantics.gitWorkTree,
+                normalizedKey: gitSemantics.normalizedKey,
+                isReadOnly: gitSemantics.isReadOnly,
+            };
+        }
+    }
+    if (head === 'rsync') {
+        return classifyRsync(tokens);
+    }
+    let effect = 'unknown';
+    let pathTargets = extractFilePathOperands(tokens);
+    pathTargets = filterRoutinePathTargets(head, pathTargets);
+    const signals = [];
+    if (READ_ONLY_KEYS.has(segment.key) || READ_ONLY_KEYS.has(head)) {
+        effect = 'read_only';
+    }
+    else if (LOCAL_MUTATION_KEYS.has(segment.key) || LOCAL_MUTATION_KEYS.has(head)) {
+        effect = 'local_mutation';
+    }
+    else if (LOCAL_ROUTINE_HEADS.has(head)) {
+        effect = 'local_mutation';
+        signals.push('routine_local');
+    }
+    if (extractRedirectTargets(tokens).length > 0 && effect === 'read_only') {
+        effect = 'local_mutation';
+    }
+    return {
+        effect,
+        pathTargets,
+        signals,
+        normalizedKey: segment.key,
+        isReadOnly: effect === 'read_only',
+    };
+}
+export { LOCAL_MUTATION_KEYS, PURE_READ_ONLY_KEYS, READ_ONLY_KEYS };

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

@@ -1,3 +1,6 @@
+import type { PolicyDecision } from '../capability/policy-types.js';
+import type { CapabilityRequestV1 } from '../capability/request.js';
+import type { BelayConfigV4 } from '../config.js';
 export type VerdictPermission = 'allow' | 'ask';
 export type VerdictLocation = 'repo_local' | 'repo_outside' | 'external' | 'mixed' | 'unknown';
 export type VerdictOpacity = 'transparent' | 'recursive' | 'opaque' | 'unparseable';
@@ -14,6 +17,8 @@ export interface VerdictResult {
     fingerprint: string;
     signals: string[];
     judgeTrace?: JudgeTrace;
+    capabilityRequests?: CapabilityRequestV1[];
+    authorizationDecision?: PolicyDecision;
 }
 export interface Tier1Verdict {
     /** true = undoable via git/fs snapshot or trivial local revert (ADR-002 local-recoverable). */
@@ -33,6 +38,7 @@ export interface Tier1EvaluateInput {
     };
     innerCode?: string;
 }
+/** @deprecated Sync gate path no longer invokes Tier1 judge. Retained for shadow tooling. */
 export interface Tier1Judge {
     evaluate(input: Tier1EvaluateInput): Promise<Tier1Verdict>;
 }
@@ -41,23 +47,40 @@ export interface JudgeTrace {
     modelRequested: string;
     modelResolved: string;
     latencyMs: number;
+    transport?: 'http' | 'ollama-http' | 'codex-cli' | 'cursor-cli' | 'claude-cli' | 'codex-cli-session' | 'cursor-cli-session' | 'claude-cli-session' | 'cursor-acp' | 'unavailable';
     outboundRedacted?: boolean;
     fallbackReason?: string;
+    judgeSessionUsed?: boolean;
+    judgeSessionReused?: boolean;
+    judgeSessionRefHash?: string;
+    judgeSessionResetReason?: string;
+    judgeFallbackReason?: string;
+    judgeConnectMs?: number;
+    judgeEvalMs?: number;
+    judgeParseMs?: number;
+    judgeShadowCompared?: boolean;
+    judgeShadowMismatch?: boolean;
+    judgeShadowMismatchRateWindow?: number;
+    judgeKillSwitchTriggered?: boolean;
 }
 export type VerdictMode = 'enforce' | 'audit';
 export interface VerdictContext {
     cwd: string;
     repoRoot: string;
+    config: BelayConfigV4;
     trustedCwd: boolean;
+    trustedWorkspaceRoots?: string[];
     sensitivePaths: string[];
     protectedArtifactRoots?: string[];
     customAllowCommands?: string[];
     customExternalCommands?: string[];
-    judge: Tier1Judge;
     mode: VerdictMode;
     unknownLocalEffect: 'allow_flagged' | 'deny';
     unparseableShell: 'allow_flagged' | 'deny';
     maxRecursionDepth?: number;
+    grants?: import('../capability/grant.js').CapabilityGrantV1[];
+    attestation?: import('../capability/attestation.js').BoundaryAttestation | null;
+    egressProxyActive?: boolean;
 }
 export interface InternalSegmentVerdict {
     permission: VerdictPermission;
@@ -68,4 +91,6 @@ export interface InternalSegmentVerdict {
     reason: string;
     signals: string[];
     judgeTrace?: JudgeTrace;
+    capabilityRequests?: CapabilityRequestV1[];
+    authorizationDecision?: PolicyDecision;
 }