@guilz-dev/belay 0.2.0 → 0.4.0

package/dist/core/verdict/judge-shadow.d.ts

@@ -0,0 +1,24 @@
+import type { BelayJudgeShadowConfig } from './judge-runtime-config.js';
+import type { Tier1Verdict } from './types.js';
+export interface JudgeShadowState {
+    compared: number;
+    mismatches: number;
+    dailyCount: number;
+    dailyKey: string;
+    killSwitchTriggered: boolean;
+    mismatchWindow: boolean[];
+}
+export declare function setJudgeShadowClockForTests(next: () => Date): void;
+export declare function setJudgeShadowRandomForTests(next: () => number): void;
+export declare function resetJudgeShadowState(repoRoot?: string): void;
+export declare function isJudgeSessionKillSwitchActive(repoRoot: string, stateDir?: string): Promise<boolean>;
+export declare function triggerJudgeSessionKillSwitch(repoRoot: string, stateDir?: string, reason?: string): Promise<void>;
+export declare function shouldRunShadowComparison(repoRoot: string, providerId: string, config: BelayJudgeShadowConfig): boolean;
+export declare function verdictsEquivalent(a: Tier1Verdict, b: Tier1Verdict): boolean;
+export declare function recordShadowComparison(repoRoot: string, config: BelayJudgeShadowConfig, mismatch: boolean): {
+    compared: boolean;
+    mismatch: boolean;
+    mismatchRateWindow: number;
+    killSwitchTriggered: boolean;
+};
+export declare function judgeShadowAuditFields(repoRoot: string): Record<string, unknown>;

package/dist/core/verdict/judge-shadow.js

@@ -0,0 +1,116 @@
+import { isJudgeSessionKillSwitchPersisted, persistJudgeSessionKillSwitch, } from './judge-session-kill-switch.js';
+const shadowStates = new Map();
+let clock = () => new Date();
+let random = Math.random;
+export function setJudgeShadowClockForTests(next) {
+    clock = next;
+}
+export function setJudgeShadowRandomForTests(next) {
+    random = next;
+}
+export function resetJudgeShadowState(repoRoot) {
+    if (repoRoot) {
+        shadowStates.delete(repoRoot);
+        return;
+    }
+    shadowStates.clear();
+}
+function dailyKeyFor(date) {
+    return date.toISOString().slice(0, 10);
+}
+function getShadowState(repoRoot) {
+    const existing = shadowStates.get(repoRoot);
+    if (existing) {
+        const key = dailyKeyFor(clock());
+        if (existing.dailyKey !== key) {
+            existing.dailyCount = 0;
+            existing.dailyKey = key;
+        }
+        return existing;
+    }
+    const created = {
+        compared: 0,
+        mismatches: 0,
+        dailyCount: 0,
+        dailyKey: dailyKeyFor(clock()),
+        killSwitchTriggered: false,
+        mismatchWindow: [],
+    };
+    shadowStates.set(repoRoot, created);
+    return created;
+}
+export async function isJudgeSessionKillSwitchActive(repoRoot, stateDir) {
+    if (getShadowState(repoRoot).killSwitchTriggered) {
+        return true;
+    }
+    if (stateDir) {
+        return isJudgeSessionKillSwitchPersisted(stateDir);
+    }
+    return false;
+}
+export async function triggerJudgeSessionKillSwitch(repoRoot, stateDir, reason = 'shadow_mismatch') {
+    getShadowState(repoRoot).killSwitchTriggered = true;
+    if (stateDir) {
+        await persistJudgeSessionKillSwitch(stateDir, reason);
+    }
+}
+export function shouldRunShadowComparison(repoRoot, providerId, config) {
+    if (!config.enabled) {
+        return false;
+    }
+    if (!config.providerAllowlist.includes(providerId)) {
+        return false;
+    }
+    const state = getShadowState(repoRoot);
+    if (state.killSwitchTriggered) {
+        return false;
+    }
+    if (state.dailyCount >= config.dailyRequestCap) {
+        return false;
+    }
+    const rate = Math.min(config.sampleRate, config.sampleRateMax);
+    return random() < rate;
+}
+export function verdictsEquivalent(a, b) {
+    return (a.local_recoverable === b.local_recoverable &&
+        a.destroys_history_or_secrets === b.destroys_history_or_secrets);
+}
+export function recordShadowComparison(repoRoot, config, mismatch) {
+    const state = getShadowState(repoRoot);
+    state.compared += 1;
+    state.dailyCount += 1;
+    if (mismatch) {
+        state.mismatches += 1;
+    }
+    state.mismatchWindow.push(mismatch);
+    if (state.mismatchWindow.length > config.windowSize) {
+        state.mismatchWindow.shift();
+    }
+    const windowComparisons = state.mismatchWindow.length;
+    const windowMismatches = state.mismatchWindow.filter(Boolean).length;
+    const mismatchRateWindow = windowComparisons === 0 ? 0 : windowMismatches / windowComparisons;
+    if (windowComparisons >= Math.min(10, config.windowSize) &&
+        mismatchRateWindow > config.mismatchRateThreshold) {
+        state.killSwitchTriggered = true;
+    }
+    return {
+        compared: true,
+        mismatch,
+        mismatchRateWindow,
+        killSwitchTriggered: state.killSwitchTriggered,
+    };
+}
+export function judgeShadowAuditFields(repoRoot) {
+    const state = shadowStates.get(repoRoot);
+    if (!state) {
+        return {};
+    }
+    const windowComparisons = state.mismatchWindow.length;
+    const windowMismatches = state.mismatchWindow.filter(Boolean).length;
+    return {
+        judgeShadowCompared: state.compared > 0,
+        judgeShadowMismatch: state.mismatches > 0,
+        judgeShadowMismatchRateWindow: windowComparisons === 0 ? 0 : windowMismatches / windowComparisons,
+        judgeKillSwitchTriggered: state.killSwitchTriggered,
+    };
+}

package/dist/core/verdict/judge-transport.d.ts

@@ -0,0 +1,40 @@
+import type { JudgeProviderId } from './judge-catalog.js';
+import { type CliInvocation, type CliJudgeRunCommand } from './judge-cli.js';
+import type { BelayJudgeRuntimeConfig } from './judge-runtime-config.js';
+import { type JudgeFallbackReason, type JudgeSessionResetReason } from './judge-session-guard.js';
+import type { Tier1Verdict } from './types.js';
+export interface JudgeTransportContext {
+    providerId: Exclude<JudgeProviderId, 'ollama'>;
+    model: string;
+    repoRoot: string;
+    stateDir: string;
+    judgeMode: string;
+    runtime: BelayJudgeRuntimeConfig;
+    judgeTimeoutMs: number;
+}
+export interface JudgeTransportEvaluateRequest {
+    prompt: string;
+    context: JudgeTransportContext;
+}
+export interface JudgeTransportEvaluateResult {
+    raw: string;
+    verdict: Tier1Verdict | null;
+    transport: 'spawn' | 'session';
+    sessionUsed: boolean;
+    sessionReused: boolean;
+    fallbackReason?: JudgeFallbackReason;
+    sessionResetReason?: JudgeSessionResetReason;
+    shadowCompared?: boolean;
+    shadowMismatch?: boolean;
+    shadowMismatchRateWindow?: number;
+    killSwitchTriggered?: boolean;
+    sessionRefHash?: string;
+    connectMs: number;
+    evalMs: number;
+    parseMs: number;
+}
+export interface JudgeTransportBridgeOptions {
+    runCommand?: CliJudgeRunCommand;
+}
+export declare function evaluateWithJudgeTransport(request: JudgeTransportEvaluateRequest, options?: JudgeTransportBridgeOptions): Promise<JudgeTransportEvaluateResult>;
+export declare function buildTransportInvocation(providerId: Exclude<JudgeProviderId, 'ollama'>, prompt: string, model: string): CliInvocation;

package/dist/core/verdict/judge-transport.js

@@ -0,0 +1,258 @@
+import { hashJudgeSessionRef } from './judge-audit.js';
+import { recordJudgeLatency } from './judge-baseline.js';
+import { evaluateViaJudgeBroker, invalidateJudgeSession } from './judge-broker-service.js';
+import { buildCliInvocation, CliRunError, parseCliJudgeOutput, runCliJsonWithTimeouts, } from './judge-cli.js';
+import { resolveCliVersionFingerprint } from './judge-cli-fingerprint.js';
+import { assertReadOnlyInvocationArgs, providerSupportsSession } from './judge-provider-matrix.js';
+import { resolveSessionEvalTimeoutMs } from './judge-runtime-config.js';
+import { buildJudgeSessionKey, exceedsPromptBudget, guardFailClosedFallbackReason, } from './judge-session-guard.js';
+import { isJudgeSessionKillSwitchActive, recordShadowComparison, shouldRunShadowComparison, triggerJudgeSessionKillSwitch, verdictsEquivalent, } from './judge-shadow.js';
+function isEvalTimeoutError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /timed out/i.test(message);
+}
+function classifyParseFailure(providerId, raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return 'non_json_response';
+    }
+    if (parseCliJudgeOutput(providerId, trimmed)) {
+        return 'parse_error';
+    }
+    try {
+        JSON.parse(trimmed);
+        return 'parse_error';
+    }
+    catch {
+        return 'non_json_response';
+    }
+}
+function spawnFallbackReason(providerId, error) {
+    if (error instanceof CliRunError) {
+        if (error.kind === 'timeout') {
+            return 'eval_timeout';
+        }
+        if (error.kind === 'exit_nonzero') {
+            return `${providerId}_cli_nonzero`;
+        }
+        if (error.kind === 'spawn_error') {
+            return `${providerId}_cli_spawn_error`;
+        }
+    }
+    if (isEvalTimeoutError(error)) {
+        return 'eval_timeout';
+    }
+    return `${providerId}_cli_unavailable`;
+}
+function parseWithBudget(providerId, raw) {
+    const started = Date.now();
+    const verdict = parseCliJudgeOutput(providerId, raw);
+    const parseMs = Date.now() - started;
+    recordJudgeLatency('tier1_parse', parseMs);
+    return { verdict, parseMs };
+}
+async function runSpawnTransport(request, runCommand) {
+    const { context, prompt } = request;
+    const sessionConfig = context.runtime.session;
+    const invocation = buildCliInvocation(context.providerId, prompt, context.model);
+    const readOnly = assertReadOnlyInvocationArgs(context.providerId, invocation.args);
+    if (!readOnly.ok) {
+        return {
+            raw: '',
+            verdict: null,
+            transport: 'spawn',
+            sessionUsed: false,
+            sessionReused: false,
+            fallbackReason: 'unsafe_option_rejected',
+            connectMs: 0,
+            evalMs: 0,
+            parseMs: 0,
+        };
+    }
+    const evalTimeoutMs = resolveSessionEvalTimeoutMs(sessionConfig, context.judgeTimeoutMs);
+    let raw = '';
+    let evalMs = 0;
+    const evalStarted = Date.now();
+    try {
+        raw = await runCommand(invocation, evalTimeoutMs);
+        evalMs = Date.now() - evalStarted;
+        recordJudgeLatency('tier1_spawn', evalMs);
+    }
+    catch (error) {
+        evalMs = Date.now() - evalStarted;
+        return {
+            raw: '',
+            verdict: null,
+            transport: 'spawn',
+            sessionUsed: false,
+            sessionReused: false,
+            fallbackReason: spawnFallbackReason(context.providerId, error),
+            connectMs: 0,
+            evalMs,
+            parseMs: 0,
+        };
+    }
+    const parsed = parseWithBudget(context.providerId, raw);
+    return {
+        raw,
+        verdict: parsed.verdict,
+        transport: 'spawn',
+        sessionUsed: false,
+        sessionReused: false,
+        fallbackReason: parsed.verdict ? undefined : classifyParseFailure(context.providerId, raw),
+        connectMs: 0,
+        evalMs,
+        parseMs: parsed.parseMs,
+    };
+}
+async function runSessionTransport(request, runCommand) {
+    const { context, prompt } = request;
+    const sessionConfig = context.runtime.session;
+    const connectStarted = Date.now();
+    if (!sessionConfig.enabled ||
+        !providerSupportsSession(context.providerId, sessionConfig.providerAllowlist) ||
+        (await isJudgeSessionKillSwitchActive(context.repoRoot, context.stateDir))) {
+        return runSpawnTransport(request, runCommand);
+    }
+    let cliVersion = 'unknown';
+    try {
+        cliVersion = await resolveCliVersionFingerprint(context.providerId, sessionConfig.connectTimeoutMs);
+    }
+    catch {
+        return {
+            ...(await runSpawnTransport(request, runCommand)),
+            fallbackReason: 'connect_timeout',
+            sessionUsed: false,
+            sessionReused: false,
+        };
+    }
+    const connectMs = Date.now() - connectStarted;
+    recordJudgeLatency('tier1_connect', connectMs);
+    const promptBytes = Buffer.byteLength(prompt, 'utf8');
+    if (exceedsPromptBudget(promptBytes, sessionConfig)) {
+        const spawnResult = await runSpawnTransport(request, runCommand);
+        return {
+            ...spawnResult,
+            sessionUsed: false,
+            sessionReused: false,
+            sessionResetReason: 'max_prompt_bytes_exceeded',
+            fallbackReason: 'guard_reset',
+        };
+    }
+    const keyParts = {
+        providerId: context.providerId,
+        model: context.model,
+        repoRoot: context.repoRoot,
+        judgeMode: context.judgeMode,
+        cliVersion,
+    };
+    const sessionKey = buildJudgeSessionKey(keyParts);
+    const sessionRefHash = hashJudgeSessionRef(sessionKey);
+    const invocation = buildCliInvocation(context.providerId, prompt, context.model);
+    const readOnly = assertReadOnlyInvocationArgs(context.providerId, invocation.args);
+    if (!readOnly.ok) {
+        return runSpawnTransport(request, runCommand);
+    }
+    const evalTimeoutMs = resolveSessionEvalTimeoutMs(sessionConfig, context.judgeTimeoutMs);
+    const evalStarted = Date.now();
+    let brokerResult;
+    try {
+        brokerResult = await evaluateViaJudgeBroker({
+            stateDir: context.stateDir,
+            repoRoot: context.repoRoot,
+            sessionConfig,
+            request: {
+                keyParts,
+                invocation,
+                promptBytes,
+            },
+            timeoutMs: evalTimeoutMs,
+            runCommand,
+        });
+    }
+    catch (error) {
+        const spawnResult = await runSpawnTransport(request, runCommand);
+        return {
+            ...spawnResult,
+            transport: 'session',
+            sessionUsed: true,
+            sessionReused: false,
+            fallbackReason: spawnFallbackReason(context.providerId, error),
+            sessionResetReason: 'cli_error',
+            sessionRefHash,
+        };
+    }
+    const evalMs = Date.now() - evalStarted;
+    recordJudgeLatency('tier1_session', evalMs);
+    recordJudgeLatency('tier1_eval', evalMs);
+    const parsed = parseWithBudget(context.providerId, brokerResult.raw);
+    if (!parsed.verdict) {
+        const parseReason = classifyParseFailure(context.providerId, brokerResult.raw);
+        await invalidateJudgeSession({
+            stateDir: context.stateDir,
+            repoRoot: context.repoRoot,
+            sessionConfig,
+            sessionKey,
+            reason: parseReason === 'non_json_response' ? 'non_json_response' : 'parse_failure',
+        });
+        const spawnResult = await runSpawnTransport(request, runCommand);
+        return {
+            ...spawnResult,
+            transport: 'session',
+            sessionUsed: true,
+            sessionReused: brokerResult.reused,
+            fallbackReason: guardFailClosedFallbackReason(parseReason === 'non_json_response' ? 'non_json_response' : 'parse_failure'),
+            sessionResetReason: parseReason === 'non_json_response' ? 'non_json_response' : 'parse_failure',
+            sessionRefHash,
+        };
+    }
+    return {
+        raw: brokerResult.raw,
+        verdict: parsed.verdict,
+        transport: 'session',
+        sessionUsed: true,
+        sessionReused: brokerResult.reused,
+        sessionResetReason: brokerResult.resetReason,
+        sessionRefHash,
+        connectMs,
+        evalMs,
+        parseMs: parsed.parseMs,
+    };
+}
+export async function evaluateWithJudgeTransport(request, options = {}) {
+    const runCommand = options.runCommand ??
+        ((invocation, timeoutMs) => runCliJsonWithTimeouts(invocation, { evalTimeoutMs: timeoutMs }));
+    const { context } = request;
+    const useSession = context.runtime.session.enabled &&
+        providerSupportsSession(context.providerId, context.runtime.session.providerAllowlist) &&
+        !(await isJudgeSessionKillSwitchActive(context.repoRoot, context.stateDir));
+    const primary = useSession
+        ? await runSessionTransport(request, runCommand)
+        : await runSpawnTransport(request, runCommand);
+    if (!shouldRunShadowComparison(context.repoRoot, context.providerId, context.runtime.shadow)) {
+        return primary;
+    }
+    const shadowSpawn = primary.transport === 'session' ? await runSpawnTransport(request, runCommand) : primary;
+    if (!primary.verdict || !shadowSpawn.verdict) {
+        return primary;
+    }
+    const shadow = recordShadowComparison(context.repoRoot, context.runtime.shadow, !verdictsEquivalent(primary.verdict, shadowSpawn.verdict));
+    if (shadow.killSwitchTriggered) {
+        await triggerJudgeSessionKillSwitch(context.repoRoot, context.stateDir);
+    }
+    return {
+        ...primary,
+        shadowCompared: shadow.compared,
+        shadowMismatch: shadow.mismatch,
+        shadowMismatchRateWindow: shadow.mismatchRateWindow,
+        killSwitchTriggered: shadow.killSwitchTriggered,
+        verdict: shadow.mismatch ? shadowSpawn.verdict : primary.verdict,
+        fallbackReason: shadow.mismatch ? 'shadow_forced_spawn' : primary.fallbackReason,
+        transport: shadow.mismatch ? 'spawn' : primary.transport,
+        sessionUsed: shadow.mismatch ? false : primary.sessionUsed,
+        sessionReused: shadow.mismatch ? false : primary.sessionReused,
+    };
+}
+export function buildTransportInvocation(providerId, prompt, model) {
+    return buildCliInvocation(providerId, prompt, model);
+}

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

@@ -1,17 +1,45 @@
 import type { ScrubOptions } from '../types.js';
 import type { Tier1Judge, Tier1Verdict } from './types.js';
+export type Tier1JudgeTransport = 'http' | 'ollama-http' | 'codex-cli' | 'cursor-cli' | 'claude-cli' | 'codex-cli-session' | 'cursor-cli-session' | 'claude-cli-session' | 'unavailable';
 export interface Tier1JudgeTrace {
-    provider: 'openai-compatible' | 'ollama' | 'fallback';
+    provider: 'openai-compatible' | 'ollama' | 'anthropic' | 'fallback';
     modelRequested: string;
     modelResolved: string;
     latencyMs: number;
+    transport?: Tier1JudgeTransport;
     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 interface TracedTier1Judge extends Tier1Judge {
     lastTrace?: Tier1JudgeTrace;
 }
+export declare function buildTier1Prompt(text: string): string;
+export declare function parseTier1Json(raw: string): Tier1Verdict | null;
 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 Tier1 LLM). */
+export declare function mutationPrescanRequiresAsk(params: MutationPrescanParams): Tier1Verdict | null;
 /** Conservative stub: Tier1 defers to Tier0; returns safe negatives for structural suite. */
 export declare function createDeterministicJudgeStub(): TracedTier1Judge;
 /** Fail-closed judge for when Tier1 is required but unavailable. */
@@ -35,6 +63,10 @@ export interface OpenAiCompatibleJudgeOptions {
     modelResolved: string;
     timeoutMs: number;
     apiKey?: string;
+    resolveApiKey?: () => Promise<{
+        key: string | null;
+        source: string | null;
+    }>;
     sensitivePaths: string[];
     scrubOptions: ScrubOptions;
     fetchImpl?: typeof fetch;

package/dist/core/verdict/judge.js

@@ -1,34 +1,60 @@
+import { matchesSensitivePath } from '../glob.js';
+import { resolveMutationTarget, resolveWorkspaceRootMatch } from '../path-utils.js';
+import { resolveTrustedPath } from './containment.js';
 import { scrubOutboundForJudge } from './judge-outbound.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;
-const TIER1_PROMPT = `Answer ONLY with JSON: {"external_change":boolean,"reason":string}
+const TIER1_PROMPT = `Answer ONLY with JSON: {"local_recoverable":boolean,"destroys_history_or_secrets":boolean,"reason":string}
 reason should be a short snake_case label.
 
-external_change: true if this operation CREATEs, MODIFYs, DELETEs, or SENDs data to any system outside the local machine and its git repository working tree.
-READ/QUERY/GET/list/describe/SELECT/HTTP GET is NOT a change. Local build, test, and package install inside the repo are NOT external changes.
-If unsure, answer true.
+local_recoverable: true if a mistaken operation can be undone locally (git revert, fs snapshot, trivial manual revert).
+local_recoverable: false if remote/destructive (git push --force, aws s3 rm, secret send) OR persistent local harm (~/.ssh/authorized_keys, shell rc, crontab, ~/.config persistence).
+
+destroys_history_or_secrets: true if the operation deletes or corrupts git history (.git), overwrites secrets/credentials, or modifies persistent agent startup (shell rc, crontab, launchd, authorized_keys).
+
+Examples local_recoverable=true, destroys_history_or_secrets=false: IDE plan files under the user home, /tmp files, in-repo edits, READ/QUERY/GET.
+Examples local_recoverable=false OR destroys_history_or_secrets=true: remote mutations, credential paths, agent startup persistence, rm -rf .git.
+If genuinely ambiguous about recoverability or persistent harm, answer false.
 
 Command/code:
 `;
 function failClosedVerdict(reason) {
     return {
-        external_change: true,
+        local_recoverable: false,
         destroys_outside_repo: true,
         destroys_history_or_secrets: true,
+        external_change: true,
         reason,
     };
 }
-function parseTier1Json(raw) {
+function parseLocalRecoverable(parsed) {
+    if (typeof parsed.local_recoverable === 'boolean') {
+        return parsed.local_recoverable;
+    }
+    if (typeof parsed.external_change === 'boolean') {
+        return !parsed.external_change;
+    }
+    return null;
+}
+export function buildTier1Prompt(text) {
+    return `${TIER1_PROMPT}${text}`;
+}
+export function parseTier1Json(raw) {
     try {
         const parsed = JSON.parse(raw);
-        if (typeof parsed.external_change !== 'boolean') {
+        const localRecoverable = parseLocalRecoverable(parsed);
+        if (localRecoverable === null) {
             return null;
         }
         return {
+            local_recoverable: localRecoverable,
+            destroys_outside_repo: typeof parsed.destroys_outside_repo === 'boolean' ? parsed.destroys_outside_repo : false,
+            destroys_history_or_secrets: typeof parsed.destroys_history_or_secrets === 'boolean'
+                ? parsed.destroys_history_or_secrets
+                : false,
             external_change: parsed.external_change,
-            destroys_outside_repo: false,
-            destroys_history_or_secrets: false,
             reason: typeof parsed.reason === 'string' ? parsed.reason : 'tier1_llm',
         };
     }
@@ -43,7 +69,7 @@ export function prescanInterpreterCode(code) {
     const hitsDestructive = DESTRUCTIVE_VERBS.test(normalized);
     if ((hitsSecret || hitsGit) && hitsDestructive) {
         return {
-            external_change: false,
+            local_recoverable: true,
             destroys_outside_repo: false,
             destroys_history_or_secrets: true,
             reason: 'prescan_destructive_secret',
@@ -51,12 +77,55 @@ export function prescanInterpreterCode(code) {
     }
     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 Tier1 LLM). */
+export function mutationPrescanRequiresAsk(params) {
+    const prescan = prescanMutationTargets(params);
+    return prescan && tier1RequiresAsk(prescan) ? prescan : null;
+}
 /** Conservative stub: Tier1 defers to Tier0; returns safe negatives for structural suite. */
 export function createDeterministicJudgeStub() {
     return {
         evaluate() {
             return Promise.resolve({
-                external_change: false,
+                local_recoverable: true,
                 destroys_outside_repo: false,
                 destroys_history_or_secrets: false,
                 reason: 'deterministic_stub',
@@ -190,8 +259,9 @@ export function createOpenAiCompatibleJudge(options) {
                 };
                 return failClosedVerdict('outbound_scrub_failed');
             }
-            const { resolveJudgeApiKey } = await import('../judge-api-key.js');
-            const resolvedKey = resolveJudgeApiKey();
+            const resolvedKey = options.resolveApiKey
+                ? await options.resolveApiKey()
+                : { key: options.apiKey ?? null, source: null };
             const apiKey = options.apiKey ?? resolvedKey.key;
             if (!apiKey) {
                 judge.lastTrace = {
@@ -258,5 +328,5 @@ export function createOpenAiCompatibleJudge(options) {
 /** @deprecated Use createOpenAiCompatibleJudge */
 export const createCursorJudge = createOpenAiCompatibleJudge;
 export function tier1RequiresAsk(verdict) {
-    return verdict.external_change || verdict.destroys_history_or_secrets;
+    return !verdict.local_recoverable || verdict.destroys_history_or_secrets;
 }

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

@@ -0,0 +1,8 @@
+/**
+ * M3 catalog: paths that survive reboot or change agent startup.
+ * @see docs/adr/tier0-retention-ledger.md
+ */
+export declare const PERSISTENT_AGENT_PATH_MARKERS: readonly [".ssh/authorized_keys", ".zshrc", ".bashrc", ".bash_profile", ".profile", ".config/", "/crontab", "LaunchAgents/", "/Library/LaunchDaemons/"];
+export declare const OUTSIDE_REPO_SECRET_CREDENTIAL_MARKERS: readonly [".env", ".env.*", "*.pem", ".ssh/id_*", ".aws/", ".npmrc", ".git-credentials", ".netrc", ".kube/config", ".docker/config.json", ".gnupg/", ".pypirc"];
+export declare function isPersistentAgentPath(resolvedPath: string): boolean;
+export declare function isOutsideRepoSecretCredentialPath(resolvedPath: string): boolean;