@guilz-dev/belay 0.2.0 → 0.4.0

package/dist/core/verdict/persistent-paths.js

@@ -0,0 +1,52 @@
+/**
+ * M3 catalog: paths that survive reboot or change agent startup.
+ * @see docs/adr/tier0-retention-ledger.md
+ */
+export const PERSISTENT_AGENT_PATH_MARKERS = [
+    '.ssh/authorized_keys',
+    '.zshrc',
+    '.bashrc',
+    '.bash_profile',
+    '.profile',
+    '.config/',
+    '/crontab',
+    'LaunchAgents/',
+    '/Library/LaunchDaemons/',
+];
+export const OUTSIDE_REPO_SECRET_CREDENTIAL_MARKERS = [
+    '.env',
+    '.env.*',
+    '*.pem',
+    '.ssh/id_*',
+    '.aws/',
+    '.npmrc',
+    '.git-credentials',
+    '.netrc',
+    '.kube/config',
+    '.docker/config.json',
+    '.gnupg/',
+    '.pypirc',
+];
+export function isPersistentAgentPath(resolvedPath) {
+    const normalized = resolvedPath.replaceAll('\\', '/');
+    return (/\.ssh\/authorized_keys$/i.test(normalized) ||
+        /\/\.(zshrc|bashrc|bash_profile|profile)$/i.test(normalized) ||
+        /\/\.config\//i.test(normalized) ||
+        /\/crontab$/i.test(normalized) ||
+        /LaunchAgents\//i.test(normalized) ||
+        /\/Library\/LaunchDaemons\//i.test(normalized));
+}
+export function isOutsideRepoSecretCredentialPath(resolvedPath) {
+    const normalized = resolvedPath.replaceAll('\\', '/');
+    return (/\/\.env(?:\.[^/]+)?$/i.test(normalized) ||
+        /\/[^/]+\.pem$/i.test(normalized) ||
+        /\/\.ssh\/id_[^/]+$/i.test(normalized) ||
+        /\/\.aws\//i.test(normalized) ||
+        /\/\.npmrc$/i.test(normalized) ||
+        /\/\.git-credentials$/i.test(normalized) ||
+        /\/\.netrc$/i.test(normalized) ||
+        /\/\.kube\/config$/i.test(normalized) ||
+        /\/\.docker\/config\.json$/i.test(normalized) ||
+        /\/\.gnupg\//i.test(normalized) ||
+        /\/\.pypirc$/i.test(normalized));
+}

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

@@ -16,10 +16,14 @@ export interface VerdictResult {
     judgeTrace?: JudgeTrace;
 }
 export interface Tier1Verdict {
-    external_change: boolean;
-    destroys_outside_repo: boolean;
+    /** true = undoable via git/fs snapshot or trivial local revert (ADR-002 local-recoverable). */
+    local_recoverable: boolean;
     destroys_history_or_secrets: boolean;
     reason: string;
+    /** @deprecated Legacy LLM field; parsed only for migration. */
+    external_change?: boolean;
+    /** @deprecated Unused in decision logic. */
+    destroys_outside_repo?: boolean;
 }
 export interface Tier1EvaluateInput {
     text: string;
@@ -39,12 +43,25 @@ export interface JudgeTrace {
     latencyMs: number;
     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;
     trustedCwd: boolean;
+    trustedWorkspaceRoots?: string[];
     sensitivePaths: string[];
     protectedArtifactRoots?: string[];
     customAllowCommands?: string[];

package/dist/core/verdict/verdict.js

@@ -1,10 +1,9 @@
-import path from 'node:path';
-import { relativeWithinRepo } from '../path-utils.js';
-import { extractRedirectTargets, tokenizeShell } from '../shell-tokenizer.js';
-import { analyzePathTargets, cwdRelative, resolveTrustedPath } from './containment.js';
+import { resolveMutationTarget } from '../path-utils.js';
+import { extractRedirectTargets, isFdDuplication, isRedirectOperator, tokenizeShell, } from '../shell-tokenizer.js';
+import { analyzePathTargets, cwdRelative, isDestructiveHighStakesMutation, resolveTrustedPath, touchesProtectedRoot, } from './containment.js';
 import { classifyEgressTool } from './egress-classify.js';
 import { verdictFingerprint } from './fingerprint.js';
-import { prescanInterpreterCode, tier1RequiresAsk } from './judge.js';
+import { mutationPrescanRequiresAsk, prescanInterpreterCode, tier1RequiresAsk } from './judge.js';
 import { isRoutineLauncher, resolveLauncherRecipe } from './launcher-resolve.js';
 import { allowFromCustomOverride, askFromCustomExternal, customAllowMatch, customExternalMatch, } from './overrides.js';
 import { extractRecursiveScript, isBareInterpreter, isVariableIndirectHead, parseSegment, peelTransparentWrappers, redactCommand, segmentOpacity, splitTopLevelSegments, substitutionInners, } from './parser.js';
@@ -197,7 +196,7 @@ function extractPathArgs(tokens) {
     const args = [...redirects];
     for (let index = 1; index < tokens.length; index += 1) {
         const token = tokens[index];
-        if (!token || token.startsWith('-') || token === '>' || token === '>>' || token === '<') {
+        if (!token || token.startsWith('-') || isRedirectOperator(token) || isFdDuplication(token)) {
             continue;
         }
         if (redirects.includes(token)) {
@@ -257,13 +256,45 @@ function tier0ExternalMatch(key, head, tokens) {
     }
     return false;
 }
+function isBelayJudgeSelfCommand(tokens) {
+    return (tokens[0] === 'belay' &&
+        tokens[1] === 'judge' &&
+        (tokens[2] === 'use' ||
+            tokens[2] === 'status' ||
+            tokens[2] === 'list' ||
+            tokens[2] === 'test' ||
+            tokens[2] === 'consent'));
+}
+function isBelayConfigSelfCommand(tokens) {
+    if (tokens[0] !== 'belay' || tokens[1] !== 'config') {
+        return false;
+    }
+    const sub = tokens[2];
+    if (!sub) {
+        return true;
+    }
+    if (sub === 'list' || sub === 'get' || sub === 'judge') {
+        return true;
+    }
+    if (sub === 'credential') {
+        return true;
+    }
+    if (sub === 'set' || sub === 'unset') {
+        const pathKey = tokens[3] ?? '';
+        return pathKey.startsWith('judge.');
+    }
+    return false;
+}
 function isBelaySelfCommand(tokens) {
     const head = tokens[0] ?? '';
     const subcommand = tokens[1] ?? '';
-    return head === 'belay' && BELAY_SELF_COMMANDS.has(subcommand);
+    return (head === 'belay' &&
+        (BELAY_SELF_COMMANDS.has(subcommand) ||
+            isBelayJudgeSelfCommand(tokens) ||
+            isBelayConfigSelfCommand(tokens)));
 }
 function tier0HighStakesRm(tokens, context) {
-    const head = tokens[0] ?? '';
+    const head = (tokens[0] ?? '').split('/').pop() ?? '';
     if (head !== 'rm') {
         return null;
     }
@@ -273,6 +304,7 @@ function tier0HighStakesRm(tokens, context) {
         cwd: context.cwd,
         repoRoot: context.repoRoot,
         trustedCwd: context.trustedCwd,
+        trustedWorkspaceRoots: context.trustedWorkspaceRoots,
         sensitivePaths: context.sensitivePaths,
         protectedArtifactRoots: context.protectedArtifactRoots,
     });
@@ -286,31 +318,40 @@ function tier0HighStakesRm(tokens, context) {
             signals: ['missing_trusted_cwd', ...analysis.signals],
         });
     }
-    if (analysis.isHighStakes) {
-        return askVerdict({
-            location: analysis.location,
-            opacity: 'transparent',
-            effect: 'local_mutation',
-            confidence: 'deterministic',
-            reason: 'high_stakes_path',
-            signals: ['high_stakes_path', ...analysis.signals],
-        });
-    }
     for (const target of targets) {
-        if (target === '~' || target.startsWith('~/') || target.startsWith('/')) {
-            const resolved = path.resolve(target === '~' || target.startsWith('~/') ? (process.env.HOME ?? '/') : context.cwd, target);
-            const relative = relativeWithinRepo(context.repoRoot, resolved);
-            if (relative === null) {
-                return askVerdict({
-                    location: 'repo_outside',
-                    opacity: 'transparent',
-                    effect: 'local_mutation',
-                    confidence: 'deterministic',
-                    reason: 'repo_outside_mutation',
-                    signals: ['repo_outside_mutation'],
-                });
+        const normalized = target.replace(/^['"]|['"]$/g, '');
+        if (normalized === '~' || normalized === '$HOME' || normalized.startsWith('~/')) {
+            return askVerdict({
+                location: 'repo_outside',
+                opacity: 'transparent',
+                effect: 'local_mutation',
+                confidence: 'deterministic',
+                reason: 'high_stakes_path',
+                signals: ['catastrophic_home_deletion', ...analysis.signals],
+            });
+        }
+    }
+    if (analysis.isHighStakes && analysis.signals.includes('high_stakes_path')) {
+        let destructiveHighStakes = false;
+        for (const target of targets) {
+            const resolved = resolveTrustedPath(target, context.cwd, context.trustedCwd) ??
+                resolveMutationTarget(target, context.cwd);
+            if (resolved &&
+                isDestructiveHighStakesMutation(head, resolved, context.repoRoot, context.sensitivePaths, context.protectedArtifactRoots, context.trustedWorkspaceRoots)) {
+                destructiveHighStakes = true;
+                break;
             }
         }
+        if (destructiveHighStakes) {
+            return askVerdict({
+                location: analysis.location,
+                opacity: 'transparent',
+                effect: 'local_mutation',
+                confidence: 'deterministic',
+                reason: 'high_stakes_path',
+                signals: ['high_stakes_path', ...analysis.signals],
+            });
+        }
     }
     return null;
 }
@@ -515,11 +556,15 @@ async function evaluateSegment(command, context, depth) {
         effect = 'local_mutation';
     }
     const pathArgs = extractPathArgs(peeled);
+    if (extractRedirectTargets(peeled).length > 0 && effect === 'read_only') {
+        effect = 'local_mutation';
+    }
     const pathAnalysis = analyzePathTargets({
         targets: pathArgs,
         cwd: context.cwd,
         repoRoot: context.repoRoot,
         trustedCwd: context.trustedCwd,
+        trustedWorkspaceRoots: context.trustedWorkspaceRoots,
         sensitivePaths: context.sensitivePaths,
         protectedArtifactRoots: context.protectedArtifactRoots,
     });
@@ -545,15 +590,45 @@ async function evaluateSegment(command, context, depth) {
             });
         }
     }
-    if (pathAnalysis.isHighStakes) {
-        return askVerdict({
-            location: pathAnalysis.location,
-            opacity: 'transparent',
-            effect: 'local_mutation',
-            confidence: 'deterministic',
-            reason: 'high_stakes_path',
-            signals: pathAnalysis.signals,
-        });
+    if ((effect === 'local_mutation' || effect === 'unknown') &&
+        context.protectedArtifactRoots &&
+        context.protectedArtifactRoots.length > 0) {
+        for (const target of pathArgs) {
+            const resolved = resolveTrustedPath(target, context.cwd, context.trustedCwd) ??
+                resolveMutationTarget(target, context.cwd);
+            if (resolved && touchesProtectedRoot(resolved, context.protectedArtifactRoots)) {
+                return askVerdict({
+                    location: pathAnalysis.location,
+                    opacity: 'transparent',
+                    effect: 'local_mutation',
+                    confidence: 'deterministic',
+                    reason: 'high_stakes_path',
+                    signals: ['high_stakes_path', 'control_plane_path'],
+                });
+            }
+        }
+    }
+    if (effect === 'local_mutation' || effect === 'unknown') {
+        let destructiveHighStakes = false;
+        for (const target of pathArgs) {
+            const resolved = resolveTrustedPath(target, context.cwd, context.trustedCwd) ??
+                resolveMutationTarget(target, context.cwd);
+            if (resolved &&
+                isDestructiveHighStakesMutation(segment.head, resolved, context.repoRoot, context.sensitivePaths, context.protectedArtifactRoots, context.trustedWorkspaceRoots)) {
+                destructiveHighStakes = true;
+                break;
+            }
+        }
+        if (destructiveHighStakes) {
+            return askVerdict({
+                location: pathAnalysis.location,
+                opacity: 'transparent',
+                effect: 'local_mutation',
+                confidence: 'deterministic',
+                reason: 'high_stakes_path',
+                signals: pathAnalysis.signals,
+            });
+        }
     }
     if (segment.head === 'find' && isFindDangerous(peeled)) {
         return askVerdict({
@@ -565,15 +640,15 @@ async function evaluateSegment(command, context, depth) {
             signals: ['find_dangerous_action'],
         });
     }
-    if (pathAnalysis.location === 'repo_outside' || pathAnalysis.location === 'mixed') {
-        const outsideEffect = effect === 'read_only' ? 'read_only' : effect === 'unknown' ? 'local_mutation' : effect;
-        return askVerdict({
+    if (effect === 'read_only' &&
+        (pathAnalysis.location === 'repo_outside' || pathAnalysis.location === 'mixed')) {
+        return allowVerdict({
             location: pathAnalysis.location,
-            opacity: 'transparent',
-            effect: outsideEffect,
+            opacity,
+            effect: 'read_only',
             confidence: 'deterministic',
-            reason: 'repo_outside_mutation',
-            signals: ['repo_outside_mutation', ...pathAnalysis.signals],
+            reason: 'read_only',
+            signals: ['read_only', ...pathAnalysis.signals],
         });
     }
     if (pathAnalysis.location === 'unknown' &&
@@ -588,7 +663,35 @@ async function evaluateSegment(command, context, depth) {
             signals: ['unknown_location_mutation'],
         });
     }
-    const needsTier1 = effect === 'unknown' || TIER0_EXTERNAL_HEADS.has(segment.head) || egressClass === 'ambiguous';
+    const outsideMutation = pathAnalysis.location === 'repo_outside' || pathAnalysis.location === 'mixed';
+    const mutationPrescan = (effect === 'local_mutation' || effect === 'unknown') && pathArgs.length > 0
+        ? mutationPrescanRequiresAsk({
+            targets: pathArgs,
+            cwd: context.cwd,
+            repoRoot: context.repoRoot,
+            trustedCwd: context.trustedCwd,
+            trustedWorkspaceRoots: context.trustedWorkspaceRoots,
+            sensitivePaths: context.sensitivePaths,
+        })
+        : null;
+    if (mutationPrescan) {
+        return askVerdict({
+            location: pathAnalysis.location === 'unknown'
+                ? 'unknown'
+                : pathAnalysis.location === 'repo_outside' || pathAnalysis.location === 'mixed'
+                    ? pathAnalysis.location
+                    : 'repo_local',
+            opacity,
+            effect: 'local_mutation',
+            confidence: 'deterministic',
+            reason: 'tier1_catastrophic',
+            signals: ['tier1_catastrophic', mutationPrescan.reason],
+        });
+    }
+    const needsTier1 = effect === 'unknown' ||
+        TIER0_EXTERNAL_HEADS.has(segment.head) ||
+        egressClass === 'ambiguous' ||
+        (outsideMutation && effect !== 'read_only');
     let tier1Trace;
     if (needsTier1) {
         const tier1Text = recursiveScript ?? command;
@@ -600,9 +703,13 @@ async function evaluateSegment(command, context, depth) {
         tier1Trace = context.judge.lastTrace;
         if (tier1RequiresAsk(tier1)) {
             return askVerdict({
-                location: pathAnalysis.location === 'unknown' ? 'unknown' : 'repo_local',
+                location: pathAnalysis.location === 'unknown'
+                    ? 'unknown'
+                    : pathAnalysis.location === 'repo_outside' || pathAnalysis.location === 'mixed'
+                        ? pathAnalysis.location
+                        : 'repo_local',
                 opacity,
-                effect: tier1.external_change ? 'remote_mutation' : effect,
+                effect: !tier1.local_recoverable ? 'remote_mutation' : effect,
                 confidence: 'llm',
                 reason: 'tier1_catastrophic',
                 signals: ['tier1_catastrophic', tier1.reason],
@@ -610,6 +717,16 @@ async function evaluateSegment(command, context, depth) {
             });
         }
     }
+    if (outsideMutation && effect !== 'read_only') {
+        return withJudgeTrace(allowVerdict({
+            location: pathAnalysis.location,
+            opacity,
+            effect: 'local_mutation',
+            confidence: tier1Trace ? 'llm' : 'deterministic',
+            reason: 'repo_outside_local_mutation',
+            signals: ['repo_outside_local_mutation', ...pathAnalysis.signals],
+        }), tier1Trace);
+    }
     if (pathAnalysis.location === 'repo_local' &&
         (effect === 'read_only' || effect === 'local_mutation') &&
         opacity !== 'opaque') {

package/dist/corpus/adversarial-probe.d.ts

@@ -0,0 +1,86 @@
+import { type MutatedCase } from './mutators.js';
+declare const MUST_ASK_VERDICT: "deny_pending_approval";
+export declare function probeCaseKey(entry: {
+    core: string;
+    mutatorId: string;
+    command: string;
+}): string;
+export interface ProbePassedCase {
+    core: string;
+    mutatorId: string;
+    command: string;
+}
+export interface AdversarialProbeFailure {
+    core: string;
+    mutatorId: string;
+    command: string;
+    expected: typeof MUST_ASK_VERDICT;
+    actual: string;
+    reason: string;
+}
+export interface AdversarialProbeFpFailure {
+    core: string;
+    mutatorId: string;
+    command: string;
+    actual: string;
+    reason: string;
+}
+export interface AdversarialProbeReport {
+    iteration: number;
+    generatedAt: string;
+    seed: number;
+    batchId: string;
+    sourceCommands: string[];
+    selectedMutators: string[];
+    maxCases?: number;
+    holdoutRatio: number;
+    totalCases: number;
+    fixSetSize: number;
+    holdoutSetSize: number;
+    fixSetFnRate: number;
+    firstPassFnRate: number;
+    /** null when no FP probe cases were evaluated. */
+    firstPassFpRate: number | null;
+    fpProbeSize: number;
+    /** null when holdout set is empty, or fix set FN rate is 0 but holdout FN > 0. */
+    holdoutFnRate: number | null;
+    /** holdoutFnRate / fixSetFnRate; 1.0 when both are 0. null when holdout empty. */
+    holdoutFixFnRateRatio: number | null;
+    passedCases: ProbePassedCase[];
+    failures: AdversarialProbeFailure[];
+    fpFailures: AdversarialProbeFpFailure[];
+    /** Populated by fix sessions / CI integration; empty when probe-only. */
+    filesChanged: string[];
+}
+export interface AdversarialProbeOptions {
+    seed?: number;
+    holdoutRatio?: number;
+    maxCases?: number;
+    outputDir?: string;
+    repoRoot?: string;
+    iteration?: number;
+}
+/** Mulberry32 PRNG for reproducible shuffles. */
+export declare function createSeededRandom(seed: number): () => number;
+export declare function shuffleWithSeed<T>(items: readonly T[], seed: number): T[];
+export declare function splitFixHoldout<T>(items: readonly T[], seed: number, holdoutRatio?: number): {
+    fix: T[];
+    holdout: T[];
+};
+export declare function generateProbeCases(seed: number, maxCases?: number): MutatedCase[];
+/** Benign must-allow cores × AUTO_LABEL mutators — FP over-stop probe (not for corpus auto-add). */
+export declare function generateFpProbeCases(seed: number): MutatedCase[];
+/** Ratio for overfitting detection; null when holdout unavailable or fix-perfect but holdout not. */
+export declare function holdoutFixFnRateRatio(fixSetFnRate: number, holdoutFnRate: number | null): number | null;
+export declare function runAdversarialProbe(options?: AdversarialProbeOptions): Promise<AdversarialProbeReport>;
+export declare function defaultProbeOutputDir(): string;
+export declare function formatProbeSummary(report: AdversarialProbeReport): string;
+export declare function parseProbeCliArgs(argv: string[]): {
+    seed: number;
+    holdoutRatio: number;
+    maxCases?: number;
+    strict: boolean;
+    outputDir: string;
+};
+export declare function main(argv?: string[]): Promise<number>;
+export {};