@guilz-dev/belay 0.2.0 → 0.3.0

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

@@ -1,7 +1,14 @@
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
+import { repoLocalStateDirFor } from '../../config-io.js';
 import { normalizeJudgeProvider, scrubOptionsFromConfig } from '../config.js';
+import { resolveJudgeCredential } from '../judge-api-key.js';
+import { hasValidCloudConsent, isCloudJudgeConfig } from '../judge-config.js';
+import { rejectDeprecatedJudgeModelAuto } from '../judge-model-policy.js';
+import { detectJudgeRuntimeCapabilities } from '../judge-runtime-detection.js';
 import { createDeterministicJudgeStub, createFailClosedJudge, createOllamaJudge, createOpenAiCompatibleJudge, } from './judge.js';
+import { getJudgeProviderSpec, inferProviderIdFromConfig, isRemovedProviderId, normalizeLegacyProviderId, } from './judge-catalog.js';
+import { createClaudeCliJudge, createCodexCliJudge, createCursorCliJudge } from './judge-cli.js';
 const FIXTURE_MODELS_URL = new URL('../../../fixtures/judge-models.json', import.meta.url);
 let cachedPinnedModels = null;
 export function resetPinnedJudgeModelsCache() {
@@ -24,33 +31,99 @@ export async function loadPinnedJudgeModels() {
         return cachedPinnedModels;
     }
 }
-export function resolveCloudModel(requested, pinned) {
-    if (requested === 'auto') {
-        const envResolved = process.env.BELAY_JUDGE_MODEL_RESOLVED?.trim();
-        return {
-            requested,
-            resolved: envResolved || pinned.autoResolved,
-        };
+export function resolveJudgeModel(judge) {
+    rejectDeprecatedJudgeModelAuto(judge.model);
+    const requested = judge.model;
+    const envOverride = testJudgeModelOverride();
+    return { requested, resolved: envOverride || requested };
+}
+function testJudgeModelOverride() {
+    if (!process.env.VITEST && !process.env.VITEST_WORKER_ID) {
+        return undefined;
     }
-    return { requested, resolved: requested };
+    return process.env.BELAY_JUDGE_MODEL_RESOLVED?.trim() || undefined;
 }
-/** @deprecated Use resolveCloudModel */
+/** @deprecated Use resolveJudgeModel */
+export const resolveCloudModel = (requested, _pinned) => {
+    rejectDeprecatedJudgeModelAuto(requested);
+    const envResolved = testJudgeModelOverride();
+    return {
+        requested,
+        resolved: envResolved || requested,
+    };
+};
+/** @deprecated Use resolveJudgeModel */
 export const resolveCursorModel = resolveCloudModel;
+function providerIdFromJudge(judge) {
+    if (judge.providerId) {
+        const normalized = normalizeLegacyProviderId(judge.providerId);
+        if (normalized) {
+            return normalized;
+        }
+    }
+    return inferProviderIdFromConfig(judge);
+}
+function createCliJudgeForProvider(providerId, judgeConfig, config) {
+    const { resolved } = resolveJudgeModel(judgeConfig);
+    const options = {
+        modelRequested: judgeConfig.model,
+        modelResolved: resolved,
+        timeoutMs: judgeConfig.timeoutMs,
+        sensitivePaths: config.classifier.sensitivePaths,
+        scrubOptions: scrubOptionsFromConfig(config),
+    };
+    if (providerId === 'codex') {
+        return createCodexCliJudge(options);
+    }
+    if (providerId === 'cursor') {
+        return createCursorCliJudge(options);
+    }
+    return createClaudeCliJudge(options);
+}
 export function createJudgeFromConfig(config, options = {}) {
+    if (process.env.BELAY_DETERMINISTIC_JUDGE === '1') {
+        return createDeterministicJudgeStub();
+    }
     const judgeConfig = config.judge;
+    if (judgeConfig.providerId && isRemovedProviderId(String(judgeConfig.providerId))) {
+        const { resolved } = resolveJudgeModel(judgeConfig);
+        return createFailClosedJudge({
+            reason: 'judge_provider_removed',
+            fallbackReason: 'provider_migration_required',
+            modelRequested: judgeConfig.model,
+            modelResolved: resolved,
+        });
+    }
     const provider = normalizeJudgeProvider(judgeConfig.provider);
+    const providerId = providerIdFromJudge(judgeConfig);
+    const catalogSpec = getJudgeProviderSpec(providerId);
+    const { resolved } = resolveJudgeModel(judgeConfig);
+    const runtime = detectJudgeRuntimeCapabilities(providerId);
     if (provider === 'openai-compatible') {
         const endpoint = judgeConfig.endpoint?.trim();
+        if (!endpoint && runtime.cliTransport) {
+            if (providerId === 'codex' || providerId === 'cursor') {
+                return createCliJudgeForProvider(providerId, judgeConfig, config);
+            }
+        }
         if (!endpoint) {
             return createFailClosedJudge({
                 reason: 'openai_compatible_endpoint_missing',
                 fallbackReason: 'missing_endpoint',
                 modelRequested: judgeConfig.model,
-                modelResolved: judgeConfig.model,
+                modelResolved: resolved,
+            });
+        }
+        if (isCloudJudgeConfig(judgeConfig) && !hasValidCloudConsent(judgeConfig)) {
+            return createFailClosedJudge({
+                reason: 'openai_compatible_consent_missing',
+                fallbackReason: 'cloud_consent_missing',
+                modelRequested: judgeConfig.model,
+                modelResolved: resolved,
             });
         }
-        const pinned = options.pinnedModels ?? { autoResolved: 'composer-2.5' };
-        const { resolved } = resolveCloudModel(judgeConfig.model, pinned);
+        const repoRoot = options.repoRoot ?? process.cwd();
+        const repoLocalStateDir = repoLocalStateDirFor(repoRoot, config);
         return createOpenAiCompatibleJudge({
             endpoint,
             modelRequested: judgeConfig.model,
@@ -58,6 +131,13 @@ export function createJudgeFromConfig(config, options = {}) {
             timeoutMs: judgeConfig.timeoutMs,
             sensitivePaths: config.classifier.sensitivePaths,
             scrubOptions: scrubOptionsFromConfig(config),
+            resolveApiKey: async () => resolveJudgeCredential({
+                judge: judgeConfig,
+                catalogSpec: catalogSpec ?? undefined,
+                repoRoot,
+                repoLocalStateDir,
+                config,
+            }),
         });
     }
     if (provider === 'ollama') {
@@ -68,8 +148,31 @@ export function createJudgeFromConfig(config, options = {}) {
             keepAlive: judgeConfig.keepAlive,
         });
     }
-    return createDeterministicJudgeStub();
+    if (provider === 'anthropic') {
+        if (runtime.cliTransport) {
+            return createClaudeCliJudge({
+                modelRequested: judgeConfig.model,
+                modelResolved: resolved,
+                timeoutMs: judgeConfig.timeoutMs,
+                sensitivePaths: config.classifier.sensitivePaths,
+                scrubOptions: scrubOptionsFromConfig(config),
+            });
+        }
+        return createFailClosedJudge({
+            reason: 'anthropic_not_implemented',
+            fallbackReason: 'anthropic_runtime_unavailable',
+            modelRequested: judgeConfig.model,
+            modelResolved: resolved,
+        });
+    }
+    return createFailClosedJudge({
+        reason: 'unsupported_judge_provider',
+        fallbackReason: 'unsupported_provider',
+        modelRequested: judgeConfig.model,
+        modelResolved: resolved,
+    });
 }
 export function judgeConfigSummary(judge) {
-    return `${judge.provider}/${judge.model}`;
+    const id = judge.providerId ?? judge.provider;
+    return `${id}/${judge.model}`;
 }

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

@@ -1,17 +1,32 @@
 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' | '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;
 }
 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;
+    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 +50,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 { relativeWithinRepo, resolveMutationTarget } 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,54 @@ 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 relative = relativeWithinRepo(params.repoRoot, resolved);
+        if (relative !== null &&
+            matchesSensitivePath(relative.replaceAll('\\', '/'), params.sensitivePaths)) {
+            return {
+                local_recoverable: false,
+                destroys_outside_repo: false,
+                destroys_history_or_secrets: true,
+                reason: 'sensitive_path_mutation',
+            };
+        }
+        if (relative === null && 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 +258,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 +327,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/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;

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;