@guilz-dev/belay 0.1.1 → 0.3.0

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

@@ -0,0 +1,178 @@
+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() {
+    cachedPinnedModels = null;
+}
+export async function loadPinnedJudgeModels() {
+    if (cachedPinnedModels) {
+        return cachedPinnedModels;
+    }
+    try {
+        const raw = await readFile(fileURLToPath(FIXTURE_MODELS_URL), 'utf8');
+        cachedPinnedModels = JSON.parse(raw);
+        return cachedPinnedModels;
+    }
+    catch {
+        cachedPinnedModels = {
+            'openai-compatible': { autoResolved: 'composer-2.5' },
+            ollama: { ciPin: 'gemma4:e2b' },
+        };
+        return cachedPinnedModels;
+    }
+}
+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 process.env.BELAY_JUDGE_MODEL_RESOLVED?.trim() || undefined;
+}
+/** @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: resolved,
+            });
+        }
+        if (isCloudJudgeConfig(judgeConfig) && !hasValidCloudConsent(judgeConfig)) {
+            return createFailClosedJudge({
+                reason: 'openai_compatible_consent_missing',
+                fallbackReason: 'cloud_consent_missing',
+                modelRequested: judgeConfig.model,
+                modelResolved: resolved,
+            });
+        }
+        const repoRoot = options.repoRoot ?? process.cwd();
+        const repoLocalStateDir = repoLocalStateDirFor(repoRoot, config);
+        return createOpenAiCompatibleJudge({
+            endpoint,
+            modelRequested: judgeConfig.model,
+            modelResolved: resolved,
+            timeoutMs: judgeConfig.timeoutMs,
+            sensitivePaths: config.classifier.sensitivePaths,
+            scrubOptions: scrubOptionsFromConfig(config),
+            resolveApiKey: async () => resolveJudgeCredential({
+                judge: judgeConfig,
+                catalogSpec: catalogSpec ?? undefined,
+                repoRoot,
+                repoLocalStateDir,
+                config,
+            }),
+        });
+    }
+    if (provider === 'ollama') {
+        return createOllamaJudge({
+            model: judgeConfig.model,
+            baseUrl: judgeConfig.endpoint ?? 'http://127.0.0.1:11434',
+            timeoutMs: judgeConfig.timeoutMs,
+            keepAlive: judgeConfig.keepAlive,
+        });
+    }
+    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) {
+    const id = judge.providerId ?? judge.provider;
+    return `${id}/${judge.model}`;
+}

package/dist/core/{v2 → 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/{v2 → verdict}/judge.js

@@ -1,36 +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,"destroys_outside_repo":boolean,"destroys_history_or_secrets":boolean,"reason":string}
-Default all three booleans to true when unsure. reason should be a short snake_case label.
+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: CREATE/MODIFY/DELETE on database, network endpoint, cloud, remote git, registry, queue. READ/QUERY/GET is NOT a change.
-destroys_outside_repo: DELETE/OVERWRITE files OUTSIDE the current repository working tree.
-destroys_history_or_secrets: DELETE/OVERWRITE .git directory OR secret/credential files (.env, *.pem, id_rsa, credentials).
+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' ||
-            typeof parsed.destroys_outside_repo !== 'boolean' ||
-            typeof parsed.destroys_history_or_secrets !== 'boolean') {
+        const localRecoverable = parseLocalRecoverable(parsed);
+        if (localRecoverable === null) {
             return null;
         }
         return {
-            external_change: parsed.external_change !== false,
-            destroys_outside_repo: parsed.destroys_outside_repo !== false,
-            destroys_history_or_secrets: parsed.destroys_history_or_secrets !== false,
+            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,
             reason: typeof parsed.reason === 'string' ? parsed.reason : 'tier1_llm',
         };
     }
@@ -45,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',
@@ -53,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',
@@ -192,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 = {
@@ -260,5 +327,5 @@ export function createOpenAiCompatibleJudge(options) {
 /** @deprecated Use createOpenAiCompatibleJudge */
 export const createCursorJudge = createOpenAiCompatibleJudge;
 export function tier1RequiresAsk(verdict) {
-    return (verdict.external_change || verdict.destroys_outside_repo || verdict.destroys_history_or_secrets);
+    return !verdict.local_recoverable || verdict.destroys_history_or_secrets;
 }

package/dist/core/{v2 → verdict}/launcher-resolve.js

@@ -1,6 +1,50 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 const MAX_RESOLVE_DEPTH = 8;
+const PNPM_BUILTIN_COMMANDS = new Set([
+    'add',
+    'audit',
+    'cache',
+    'config',
+    'deploy',
+    'dlx',
+    'exec',
+    'fetch',
+    'help',
+    'import',
+    'init',
+    'install',
+    'i',
+    'licenses',
+    'link',
+    'list',
+    'outdated',
+    'pack',
+    'patch',
+    'patch-commit',
+    'patch-remove',
+    'publish',
+    'prune',
+    'rebuild',
+    'remove',
+    'rm',
+    'store',
+    'unlink',
+    'update',
+    'up',
+    'why',
+]);
+const PNPM_EXEC_LIKE_HEADS = new Set([
+    'vitest',
+    'vite',
+    'biome',
+    'eslint',
+    'jest',
+    'mocha',
+    'tsc',
+    'tsx',
+    'node',
+]);
 function readPackageJson(dir) {
     const packagePath = path.join(dir, 'package.json');
     if (!existsSync(packagePath)) {
@@ -57,6 +101,15 @@ function npmScriptName(tokens) {
     if (launcher[0] === 'pnpm' && launcher[1] === 'run' && launcher[2]) {
         return launcher[2];
     }
+    if (launcher[0] === 'pnpm' && launcher[1] === 'test') {
+        return 'test';
+    }
+    if (launcher[0] === 'pnpm' &&
+        launcher[1] &&
+        !launcher[1].startsWith('-') &&
+        !PNPM_BUILTIN_COMMANDS.has(launcher[1])) {
+        return launcher[1];
+    }
     if (launcher[0] === 'npm' && launcher[1] && launcher[1] !== 'run' && launcher[1] !== 'install') {
         return null;
     }
@@ -176,11 +229,29 @@ export function resolveLauncherRecipe(params) {
     const tokens = params.tokens;
     const scriptName = npmScriptName(tokens);
     if (scriptName) {
-        return resolveNpmRecipe(params.cwd, params.repoRoot, scriptName, forwardedArgs(tokens));
+        const resolution = resolveNpmRecipe(params.cwd, params.repoRoot, scriptName, forwardedArgs(tokens));
+        if (tokens[0] === 'pnpm' &&
+            tokens[1] &&
+            PNPM_EXEC_LIKE_HEADS.has(tokens[1]) &&
+            resolution.reason === 'npm_script_undefined') {
+            return {
+                recipes: [tokens.slice(1).join(' ')],
+                opaque: false,
+                reason: 'pnpm_exec_like',
+            };
+        }
+        return resolution;
     }
     if (tokens[0] === 'make' && tokens[1] && !tokens[1].startsWith('-')) {
         return resolveMakeRecipe(params.cwd, params.repoRoot, tokens[1]);
     }
+    if (tokens[0] === 'pnpm' && tokens[1] && PNPM_EXEC_LIKE_HEADS.has(tokens[1])) {
+        return {
+            recipes: [tokens.slice(1).join(' ')],
+            opaque: false,
+            reason: 'pnpm_exec_like',
+        };
+    }
     return null;
 }
 export function isRoutineLauncher(tokens) {

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/{v2 → 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;