@guilz-dev/belay 0.2.0 → 0.4.0

package/dist/core/verdict/judge-provider-matrix.js

@@ -0,0 +1,66 @@
+export const JUDGE_PROVIDER_SESSION_MATRIX = {
+    cursor: {
+        providerId: 'cursor',
+        supportsSession: true,
+        resumeFlag: '--resume',
+        createChatFlag: null,
+        readOnlyArgs: ['--mode', 'ask', '--sandbox', 'enabled', '--trust'],
+        rejectedUnsafeOptions: ['--force', '--yolo', '--dangerously-skip-permissions'],
+        failureModes: [
+            'parse_error',
+            'non_json_response',
+            'timeout',
+            'cli_nonzero_exit',
+            'io_error',
+            'version_mismatch',
+        ],
+        notes: 'Pilot provider: ask mode + sandbox enabled; resume via --resume <chatId>.',
+    },
+    codex: {
+        providerId: 'codex',
+        supportsSession: false,
+        resumeFlag: null,
+        createChatFlag: null,
+        readOnlyArgs: ['--sandbox', 'read-only'],
+        rejectedUnsafeOptions: ['--dangerously-bypass-approvals-and-sandbox'],
+        failureModes: ['unsupported_resume', 'parse_error', 'timeout'],
+        notes: 'Session transport disabled by default; spawn read-only exec remains canonical.',
+    },
+    claude: {
+        providerId: 'claude',
+        supportsSession: false,
+        resumeFlag: '--continue',
+        createChatFlag: null,
+        readOnlyArgs: ['--permission-mode', 'plan', '--tools', '', '--bare'],
+        rejectedUnsafeOptions: ['--dangerously-skip-permissions'],
+        failureModes: ['unsupported_resume', 'parse_error', 'timeout'],
+        notes: 'Session transport gated behind allowlist after capability verification.',
+    },
+};
+export function providerSupportsSession(providerId, allowlist) {
+    const capability = JUDGE_PROVIDER_SESSION_MATRIX[providerId];
+    return capability.supportsSession && allowlist.includes(providerId);
+}
+export function assertReadOnlyInvocationArgs(providerId, args) {
+    const capability = JUDGE_PROVIDER_SESSION_MATRIX[providerId];
+    for (const unsafe of capability.rejectedUnsafeOptions) {
+        if (args.includes(unsafe)) {
+            return { ok: false, reason: 'unsafe_option_rejected' };
+        }
+    }
+    for (let index = 0; index < capability.readOnlyArgs.length; index += 2) {
+        const flag = capability.readOnlyArgs[index];
+        const value = capability.readOnlyArgs[index + 1];
+        if (!flag) {
+            continue;
+        }
+        const flagIndex = args.indexOf(flag);
+        if (flagIndex === -1) {
+            return { ok: false, reason: 'unsafe_option_rejected' };
+        }
+        if (value !== undefined && args[flagIndex + 1] !== value) {
+            return { ok: false, reason: 'unsafe_option_rejected' };
+        }
+    }
+    return { ok: true };
+}

package/dist/core/verdict/judge-runtime-config.d.ts

@@ -0,0 +1,42 @@
+import type { JudgeProviderId } from './judge-catalog.js';
+export interface BelayJudgeSessionConfig {
+    enabled: boolean;
+    maxTurns: number;
+    maxAgeMs: number;
+    maxIdleMs: number;
+    maxPromptBytes: number;
+    providerAllowlist: JudgeProviderId[];
+    connectTimeoutMs: number;
+    evalTimeoutMs: number | null;
+    parseTimeoutMs: number;
+    maxSessionsPerProvider: number;
+}
+export interface BelayJudgeShadowConfig {
+    enabled: boolean;
+    sampleRate: number;
+    sampleRateMax: number;
+    dailyRequestCap: number;
+    mismatchRateThreshold: number;
+    providerAllowlist: JudgeProviderId[];
+    windowSize: number;
+}
+export interface BelayJudgeRuntimeConfig {
+    session: BelayJudgeSessionConfig;
+    shadow: BelayJudgeShadowConfig;
+}
+export declare const JUDGE_LATENCY_SLO: {
+    /** Target: Tier1 p95 at least 40% below spawn baseline. */
+    readonly tier1P95ReductionTarget: 0.4;
+    /** Reference spawn baseline (ms) from dogfood measurement. */
+    readonly spawnBaselineP95Ms: 25000;
+    readonly spawnBaselineP50Ms: 1300;
+    readonly tier0BaselineP95Ms: 60;
+    /** Session path must not exceed spawn p95 when enabled. */
+    readonly sessionMaxP95Ms: 15000;
+};
+export declare const DEFAULT_JUDGE_SESSION_CONFIG: BelayJudgeSessionConfig;
+export declare const DEFAULT_JUDGE_SHADOW_CONFIG: BelayJudgeShadowConfig;
+export declare const DEFAULT_JUDGE_RUNTIME_CONFIG: BelayJudgeRuntimeConfig;
+export declare function normalizeJudgeRuntimeConfig(runtime: Partial<BelayJudgeRuntimeConfig> | undefined): BelayJudgeRuntimeConfig;
+export declare function normalizeJudgeSessionConfig(session: Partial<BelayJudgeSessionConfig> | undefined): BelayJudgeSessionConfig;
+export declare function resolveSessionEvalTimeoutMs(sessionConfig: BelayJudgeSessionConfig, judgeTimeoutMs: number): number;

package/dist/core/verdict/judge-runtime-config.js

@@ -0,0 +1,92 @@
+export const JUDGE_LATENCY_SLO = {
+    /** Target: Tier1 p95 at least 40% below spawn baseline. */
+    tier1P95ReductionTarget: 0.4,
+    /** Reference spawn baseline (ms) from dogfood measurement. */
+    spawnBaselineP95Ms: 25_000,
+    spawnBaselineP50Ms: 1_300,
+    tier0BaselineP95Ms: 60,
+    /** Session path must not exceed spawn p95 when enabled. */
+    sessionMaxP95Ms: 15_000,
+};
+export const DEFAULT_JUDGE_SESSION_CONFIG = {
+    enabled: false,
+    maxTurns: 32,
+    maxAgeMs: 30 * 60 * 1000,
+    maxIdleMs: 5 * 60 * 1000,
+    maxPromptBytes: 64 * 1024,
+    providerAllowlist: ['cursor'],
+    connectTimeoutMs: 5_000,
+    evalTimeoutMs: null,
+    parseTimeoutMs: 2_000,
+    maxSessionsPerProvider: 1,
+};
+export const DEFAULT_JUDGE_SHADOW_CONFIG = {
+    enabled: false,
+    sampleRate: 0.01,
+    sampleRateMax: 0.05,
+    dailyRequestCap: 500,
+    mismatchRateThreshold: 0.02,
+    providerAllowlist: ['cursor'],
+    windowSize: 100,
+};
+export const DEFAULT_JUDGE_RUNTIME_CONFIG = {
+    session: { ...DEFAULT_JUDGE_SESSION_CONFIG },
+    shadow: { ...DEFAULT_JUDGE_SHADOW_CONFIG },
+};
+const CLI_PROVIDER_IDS = ['codex', 'cursor', 'claude'];
+function normalizeProviderAllowlist(value, fallback) {
+    if (!Array.isArray(value)) {
+        return [...fallback];
+    }
+    const allowed = value
+        .map((entry) => String(entry).trim())
+        .filter((entry) => CLI_PROVIDER_IDS.includes(entry));
+    return allowed.length > 0 ? [...new Set(allowed)] : [...fallback];
+}
+function normalizePositiveInt(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : fallback;
+}
+function normalizeRate(value, fallback, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        return fallback;
+    }
+    return Math.min(value, max);
+}
+export function normalizeJudgeRuntimeConfig(runtime) {
+    const session = runtime?.session ?? {};
+    const shadow = runtime?.shadow ?? {};
+    return {
+        session: normalizeJudgeSessionConfig(session),
+        shadow: {
+            enabled: shadow.enabled === true,
+            sampleRate: normalizeRate(shadow.sampleRate, DEFAULT_JUDGE_SHADOW_CONFIG.sampleRate, 1),
+            sampleRateMax: normalizeRate(shadow.sampleRateMax, DEFAULT_JUDGE_SHADOW_CONFIG.sampleRateMax, 1),
+            dailyRequestCap: normalizePositiveInt(shadow.dailyRequestCap, DEFAULT_JUDGE_SHADOW_CONFIG.dailyRequestCap),
+            mismatchRateThreshold: normalizeRate(shadow.mismatchRateThreshold, DEFAULT_JUDGE_SHADOW_CONFIG.mismatchRateThreshold, 1),
+            providerAllowlist: normalizeProviderAllowlist(shadow.providerAllowlist, DEFAULT_JUDGE_SHADOW_CONFIG.providerAllowlist),
+            windowSize: normalizePositiveInt(shadow.windowSize, DEFAULT_JUDGE_SHADOW_CONFIG.windowSize),
+        },
+    };
+}
+export function normalizeJudgeSessionConfig(session) {
+    const input = session ?? {};
+    return {
+        enabled: input.enabled === true,
+        maxTurns: normalizePositiveInt(input.maxTurns, DEFAULT_JUDGE_SESSION_CONFIG.maxTurns),
+        maxAgeMs: normalizePositiveInt(input.maxAgeMs, DEFAULT_JUDGE_SESSION_CONFIG.maxAgeMs),
+        maxIdleMs: normalizePositiveInt(input.maxIdleMs, DEFAULT_JUDGE_SESSION_CONFIG.maxIdleMs),
+        maxPromptBytes: normalizePositiveInt(input.maxPromptBytes, DEFAULT_JUDGE_SESSION_CONFIG.maxPromptBytes),
+        providerAllowlist: normalizeProviderAllowlist(input.providerAllowlist, DEFAULT_JUDGE_SESSION_CONFIG.providerAllowlist),
+        connectTimeoutMs: normalizePositiveInt(input.connectTimeoutMs, DEFAULT_JUDGE_SESSION_CONFIG.connectTimeoutMs),
+        evalTimeoutMs: typeof input.evalTimeoutMs === 'number' && input.evalTimeoutMs > 0
+            ? Math.floor(input.evalTimeoutMs)
+            : null,
+        parseTimeoutMs: normalizePositiveInt(input.parseTimeoutMs, DEFAULT_JUDGE_SESSION_CONFIG.parseTimeoutMs),
+        maxSessionsPerProvider: normalizePositiveInt(input.maxSessionsPerProvider, DEFAULT_JUDGE_SESSION_CONFIG.maxSessionsPerProvider),
+    };
+}
+export function resolveSessionEvalTimeoutMs(sessionConfig, judgeTimeoutMs) {
+    return sessionConfig.evalTimeoutMs ?? judgeTimeoutMs;
+}

package/dist/core/verdict/judge-session-broker.d.ts

@@ -0,0 +1,48 @@
+import type { JudgeProviderId } from './judge-catalog.js';
+import type { CliInvocation, CliJudgeRunCommand } from './judge-cli.js';
+import type { BelayJudgeSessionConfig } from './judge-runtime-config.js';
+import { type JudgeSessionBudget, type JudgeSessionKeyParts, type JudgeSessionResetReason } from './judge-session-guard.js';
+export type BrokerSessionState = 'idle' | 'busy';
+export interface BrokerSessionRecord {
+    keyParts: JudgeSessionKeyParts;
+    budget: JudgeSessionBudget;
+    state: BrokerSessionState;
+    providerResumeId?: string;
+    lastResetReason?: JudgeSessionResetReason;
+}
+export interface BrokerEvaluateRequest {
+    keyParts: JudgeSessionKeyParts;
+    invocation: CliInvocation;
+    promptBytes: number;
+}
+export interface BrokerEvaluateResult {
+    raw: string;
+    reused: boolean;
+    resetReason?: JudgeSessionResetReason;
+    providerResumeId?: string;
+}
+type RunCommand = CliJudgeRunCommand;
+export interface JudgeSessionBrokerOptions {
+    config: BelayJudgeSessionConfig;
+    runCommand: RunCommand;
+    extractResumeId?: (providerId: Exclude<JudgeProviderId, 'ollama'>, raw: string) => string | null;
+}
+export declare class JudgeSessionBroker {
+    private readonly sessions;
+    private readonly mutexes;
+    private readonly options;
+    constructor(options: JudgeSessionBrokerOptions);
+    listSessions(): BrokerSessionRecord[];
+    invalidateSession(sessionKey: string, reason: JudgeSessionResetReason): void;
+    stopAll(reason?: JudgeSessionResetReason): number;
+    evaluate(request: BrokerEvaluateRequest, timeoutMs: number): Promise<BrokerEvaluateResult>;
+    private evaluateExclusive;
+    private enforceProviderSessionCap;
+    private buildResumeInvocation;
+}
+export declare function extractProviderResumeId(providerId: Exclude<JudgeProviderId, 'ollama'>, raw: string): string | null;
+export declare function getRepoJudgeSessionBroker(repoRoot: string, options: JudgeSessionBrokerOptions): JudgeSessionBroker;
+export declare function stopRepoJudgeSessionBroker(repoRoot: string, reason?: JudgeSessionResetReason): number;
+export declare function resetJudgeSessionBrokersForTests(): void;
+export declare function listRepoJudgeSessionBrokers(): string[];
+export {};

package/dist/core/verdict/judge-session-broker.js

@@ -0,0 +1,195 @@
+import { buildJudgeSessionKey, evaluateSessionReuse, } from './judge-session-guard.js';
+import { MutexRegistry } from './judge-session-mutex.js';
+export class JudgeSessionBroker {
+    sessions = new Map();
+    mutexes = new MutexRegistry();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    listSessions() {
+        return [...this.sessions.values()];
+    }
+    invalidateSession(sessionKey, reason) {
+        const session = this.sessions.get(sessionKey);
+        if (session) {
+            session.lastResetReason = reason;
+            session.state = 'idle';
+        }
+        this.sessions.delete(sessionKey);
+    }
+    stopAll(reason = 'manual_stop') {
+        const count = this.sessions.size;
+        for (const session of this.sessions.values()) {
+            session.lastResetReason = reason;
+            session.state = 'idle';
+        }
+        this.sessions.clear();
+        this.mutexes.clear();
+        return count;
+    }
+    async evaluate(request, timeoutMs) {
+        const sessionKey = buildJudgeSessionKey(request.keyParts);
+        return this.mutexes.forKey(sessionKey).run(() => this.evaluateExclusive(request, timeoutMs));
+    }
+    async evaluateExclusive(request, timeoutMs) {
+        const sessionKey = buildJudgeSessionKey(request.keyParts);
+        const providerId = request.keyParts.providerId;
+        const existing = this.sessions.get(sessionKey);
+        const reuseDecision = evaluateSessionReuse(existing?.keyParts ?? null, request.keyParts, existing?.budget ?? null, this.options.config, Date.now(), request.promptBytes);
+        const resetReason = reuseDecision.canReuse ? undefined : reuseDecision.resetReason;
+        let session = existing;
+        if (!reuseDecision.canReuse || !session) {
+            session = {
+                keyParts: request.keyParts,
+                budget: {
+                    turnCount: 0,
+                    createdAtMs: Date.now(),
+                    lastUsedAtMs: Date.now(),
+                    promptBytes: 0,
+                },
+                state: 'busy',
+                lastResetReason: resetReason ?? 'initial',
+            };
+            this.enforceProviderSessionCap(providerId, sessionKey);
+            this.sessions.set(sessionKey, session);
+        }
+        else {
+            session.state = 'busy';
+            session.budget.lastUsedAtMs = Date.now();
+        }
+        const invocation = reuseDecision.canReuse && session.providerResumeId
+            ? this.buildResumeInvocation(request.invocation, providerId, session.providerResumeId)
+            : request.invocation;
+        const resumed = reuseDecision.canReuse && Boolean(session.providerResumeId);
+        try {
+            const raw = await this.options.runCommand(invocation, timeoutMs);
+            session.budget.turnCount += 1;
+            session.budget.promptBytes += request.promptBytes;
+            session.budget.lastUsedAtMs = Date.now();
+            session.state = 'idle';
+            const extracted = this.options.extractResumeId?.(providerId, raw) ??
+                extractProviderResumeId(providerId, raw) ??
+                undefined;
+            if (extracted) {
+                session.providerResumeId = extracted;
+            }
+            return {
+                raw,
+                reused: resumed,
+                resetReason: session.lastResetReason,
+                providerResumeId: session.providerResumeId,
+            };
+        }
+        catch (error) {
+            session.state = 'idle';
+            session.lastResetReason = 'cli_error';
+            this.sessions.delete(sessionKey);
+            throw error;
+        }
+    }
+    enforceProviderSessionCap(providerId, keepKey) {
+        const cap = this.options.config.maxSessionsPerProvider;
+        const sameProvider = [...this.sessions.entries()].filter(([, record]) => record.keyParts.providerId === providerId);
+        if (sameProvider.length < cap) {
+            return;
+        }
+        for (const [key] of sameProvider) {
+            if (key === keepKey) {
+                continue;
+            }
+            this.sessions.delete(key);
+            if (this.sessions.size < cap) {
+                break;
+            }
+        }
+    }
+    buildResumeInvocation(base, providerId, resumeId) {
+        if (providerId === 'cursor') {
+            const args = [...base.args];
+            const modelIndex = args.indexOf('--model');
+            const model = modelIndex >= 0 ? args[modelIndex + 1] : undefined;
+            const prompt = args[args.length - 1];
+            return {
+                binary: base.binary,
+                args: [
+                    '--print',
+                    '--output-format',
+                    'json',
+                    '--mode',
+                    'ask',
+                    '--sandbox',
+                    'enabled',
+                    '--trust',
+                    '--resume',
+                    resumeId,
+                    ...(model ? ['--model', model] : []),
+                    prompt,
+                ],
+            };
+        }
+        if (providerId === 'claude') {
+            return {
+                ...base,
+                args: [...base.args, '--continue', resumeId],
+            };
+        }
+        return base;
+    }
+}
+export function extractProviderResumeId(providerId, raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        const candidates = [
+            parsed.chat_id,
+            parsed.chatId,
+            parsed.session_id,
+            parsed.sessionId,
+            parsed.result?.chat_id,
+            parsed.result?.session_id,
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === 'string' && candidate.trim()) {
+                return candidate.trim();
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    if (providerId === 'cursor') {
+        const match = raw.match(/"chat_id"\s*:\s*"([^"]+)"/);
+        if (match?.[1]) {
+            return match[1];
+        }
+    }
+    return null;
+}
+const repoBrokers = new Map();
+export function getRepoJudgeSessionBroker(repoRoot, options) {
+    const existing = repoBrokers.get(repoRoot);
+    if (existing) {
+        return existing;
+    }
+    const broker = new JudgeSessionBroker(options);
+    repoBrokers.set(repoRoot, broker);
+    return broker;
+}
+export function stopRepoJudgeSessionBroker(repoRoot, reason = 'manual_stop') {
+    const broker = repoBrokers.get(repoRoot);
+    if (!broker) {
+        return 0;
+    }
+    const count = broker.stopAll(reason);
+    repoBrokers.delete(repoRoot);
+    return count;
+}
+export function resetJudgeSessionBrokersForTests() {
+    for (const broker of repoBrokers.values()) {
+        broker.stopAll('manual_stop');
+    }
+    repoBrokers.clear();
+}
+export function listRepoJudgeSessionBrokers() {
+    return [...repoBrokers.keys()];
+}

package/dist/core/verdict/judge-session-guard.d.ts

@@ -0,0 +1,27 @@
+import type { JudgeProviderId } from './judge-catalog.js';
+import type { BelayJudgeSessionConfig } from './judge-runtime-config.js';
+export type JudgeSessionResetReason = 'provider_mismatch' | 'model_mismatch' | 'repo_mismatch' | 'mode_mismatch' | 'cli_version_mismatch' | 'max_turns_exceeded' | 'max_age_exceeded' | 'max_idle_exceeded' | 'max_prompt_bytes_exceeded' | 'parse_failure' | 'non_json_response' | 'cli_error' | 'timeout' | 'kill_switch' | 'manual_stop' | 'budget_exhausted' | 'session_disabled' | 'provider_not_allowlisted' | 'initial';
+export type JudgeFallbackReason = 'session_disabled' | 'provider_not_allowlisted' | 'session_unavailable' | 'guard_reset' | 'parse_error' | 'non_json_response' | 'cli_error' | 'timeout' | 'connect_timeout' | 'eval_timeout' | 'parse_timeout' | 'version_mismatch' | 'kill_switch' | 'shadow_forced_spawn' | 'unsafe_option_rejected' | 'broker_busy_reset' | `${Exclude<JudgeProviderId, 'ollama'>}_cli_spawn_error` | `${Exclude<JudgeProviderId, 'ollama'>}_cli_nonzero` | `${Exclude<JudgeProviderId, 'ollama'>}_cli_unavailable` | `${Exclude<JudgeProviderId, 'ollama'>}_cli_parse_error`;
+export interface JudgeSessionKeyParts {
+    providerId: JudgeProviderId;
+    model: string;
+    repoRoot: string;
+    judgeMode: string;
+    cliVersion: string;
+}
+export interface JudgeSessionBudget {
+    turnCount: number;
+    createdAtMs: number;
+    lastUsedAtMs: number;
+    promptBytes: number;
+}
+export interface JudgeSessionGuardDecision {
+    canReuse: boolean;
+    resetReason?: JudgeSessionResetReason;
+    sessionKey: string;
+}
+export declare function buildJudgeSessionKey(parts: JudgeSessionKeyParts): string;
+export declare function evaluateSessionReuse(existing: JudgeSessionKeyParts | null, requested: JudgeSessionKeyParts, budget: JudgeSessionBudget | null, config: BelayJudgeSessionConfig, now?: number, incomingPromptBytes?: number): JudgeSessionGuardDecision;
+export declare function exceedsPromptBudget(promptBytes: number, config: BelayJudgeSessionConfig, existingBudget?: JudgeSessionBudget | null): boolean;
+export declare function guardFailClosedFallbackReason(resetReason: JudgeSessionResetReason): JudgeFallbackReason;
+export declare function transportFallbackToFailClosedReason(providerId: Exclude<JudgeProviderId, 'ollama'>, fallback: JudgeFallbackReason | undefined): string;

package/dist/core/verdict/judge-session-guard.js

@@ -0,0 +1,91 @@
+export function buildJudgeSessionKey(parts) {
+    return [parts.providerId, parts.model, parts.repoRoot, parts.judgeMode, parts.cliVersion].join(':');
+}
+export function evaluateSessionReuse(existing, requested, budget, config, now = Date.now(), incomingPromptBytes = 0) {
+    const sessionKey = buildJudgeSessionKey(requested);
+    if (!config.enabled) {
+        return { canReuse: false, resetReason: 'session_disabled', sessionKey };
+    }
+    if (!config.providerAllowlist.includes(requested.providerId)) {
+        return { canReuse: false, resetReason: 'provider_not_allowlisted', sessionKey };
+    }
+    if (!existing || !budget) {
+        return { canReuse: false, resetReason: 'initial', sessionKey };
+    }
+    const existingKey = buildJudgeSessionKey(existing);
+    if (existingKey !== sessionKey) {
+        if (existing.providerId !== requested.providerId) {
+            return { canReuse: false, resetReason: 'provider_mismatch', sessionKey };
+        }
+        if (existing.model !== requested.model) {
+            return { canReuse: false, resetReason: 'model_mismatch', sessionKey };
+        }
+        if (existing.repoRoot !== requested.repoRoot) {
+            return { canReuse: false, resetReason: 'repo_mismatch', sessionKey };
+        }
+        if (existing.judgeMode !== requested.judgeMode) {
+            return { canReuse: false, resetReason: 'mode_mismatch', sessionKey };
+        }
+        if (existing.cliVersion !== requested.cliVersion) {
+            return { canReuse: false, resetReason: 'cli_version_mismatch', sessionKey };
+        }
+        return { canReuse: false, resetReason: 'provider_mismatch', sessionKey };
+    }
+    if (budget.turnCount >= config.maxTurns) {
+        return { canReuse: false, resetReason: 'max_turns_exceeded', sessionKey };
+    }
+    if (now - budget.createdAtMs >= config.maxAgeMs) {
+        return { canReuse: false, resetReason: 'max_age_exceeded', sessionKey };
+    }
+    if (now - budget.lastUsedAtMs >= config.maxIdleMs) {
+        return { canReuse: false, resetReason: 'max_idle_exceeded', sessionKey };
+    }
+    if (budget.promptBytes + incomingPromptBytes > config.maxPromptBytes) {
+        return { canReuse: false, resetReason: 'max_prompt_bytes_exceeded', sessionKey };
+    }
+    return { canReuse: true, sessionKey };
+}
+export function exceedsPromptBudget(promptBytes, config, existingBudget = null) {
+    const total = (existingBudget?.promptBytes ?? 0) + promptBytes;
+    return total > config.maxPromptBytes;
+}
+export function guardFailClosedFallbackReason(resetReason) {
+    switch (resetReason) {
+        case 'parse_failure':
+            return 'parse_error';
+        case 'non_json_response':
+            return 'non_json_response';
+        case 'cli_error':
+            return 'cli_error';
+        case 'timeout':
+            return 'timeout';
+        case 'cli_version_mismatch':
+            return 'version_mismatch';
+        case 'kill_switch':
+            return 'kill_switch';
+        case 'session_disabled':
+            return 'session_disabled';
+        case 'provider_not_allowlisted':
+            return 'provider_not_allowlisted';
+        case 'max_prompt_bytes_exceeded':
+            return 'guard_reset';
+        default:
+            return 'guard_reset';
+    }
+}
+export function transportFallbackToFailClosedReason(providerId, fallback) {
+    if (!fallback) {
+        return `${providerId}_cli_parse_error`;
+    }
+    if (fallback.endsWith('_cli_unavailable') || fallback.endsWith('_cli_parse_error')) {
+        return fallback;
+    }
+    switch (fallback) {
+        case 'non_json_response':
+        case 'parse_error':
+        case 'parse_timeout':
+            return `${providerId}_cli_parse_error`;
+        default:
+            return `${providerId}_cli_unavailable`;
+    }
+}

package/dist/core/verdict/judge-session-kill-switch.d.ts

@@ -0,0 +1,11 @@
+export declare const JUDGE_SESSION_KILL_FILE = "judge-session-kill.json";
+export interface JudgeSessionKillSwitchRecord {
+    triggered: boolean;
+    at: string;
+    reason?: string;
+}
+export declare function judgeSessionKillSwitchPath(stateDir: string): string;
+export declare function readJudgeSessionKillSwitch(stateDir: string): Promise<JudgeSessionKillSwitchRecord | null>;
+export declare function isJudgeSessionKillSwitchPersisted(stateDir: string): Promise<boolean>;
+export declare function persistJudgeSessionKillSwitch(stateDir: string, reason?: string): Promise<void>;
+export declare function clearJudgeSessionKillSwitch(stateDir: string): Promise<void>;

package/dist/core/verdict/judge-session-kill-switch.js

@@ -0,0 +1,43 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const JUDGE_SESSION_KILL_FILE = 'judge-session-kill.json';
+export function judgeSessionKillSwitchPath(stateDir) {
+    return path.join(stateDir, JUDGE_SESSION_KILL_FILE);
+}
+export async function readJudgeSessionKillSwitch(stateDir) {
+    const filePath = judgeSessionKillSwitchPath(stateDir);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(await readFile(filePath, 'utf8'));
+        return raw.triggered === true ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function isJudgeSessionKillSwitchPersisted(stateDir) {
+    const record = await readJudgeSessionKillSwitch(stateDir);
+    return record?.triggered === true;
+}
+export async function persistJudgeSessionKillSwitch(stateDir, reason = 'shadow_mismatch') {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const record = {
+        triggered: true,
+        at: new Date().toISOString(),
+        reason,
+    };
+    await writeFile(judgeSessionKillSwitchPath(stateDir), JSON.stringify(record), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export async function clearJudgeSessionKillSwitch(stateDir) {
+    const filePath = judgeSessionKillSwitchPath(stateDir);
+    if (!existsSync(filePath)) {
+        return;
+    }
+    await unlink(filePath);
+}

package/dist/core/verdict/judge-session-mutex.d.ts

@@ -0,0 +1,9 @@
+export declare class AsyncMutex {
+    private chain;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+export declare class MutexRegistry {
+    private readonly mutexes;
+    forKey(key: string): AsyncMutex;
+    clear(): void;
+}

package/dist/core/verdict/judge-session-mutex.js

@@ -0,0 +1,23 @@
+export class AsyncMutex {
+    chain = Promise.resolve();
+    run(fn) {
+        const next = this.chain.then(fn);
+        this.chain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}
+export class MutexRegistry {
+    mutexes = new Map();
+    forKey(key) {
+        const existing = this.mutexes.get(key);
+        if (existing) {
+            return existing;
+        }
+        const created = new AsyncMutex();
+        this.mutexes.set(key, created);
+        return created;
+    }
+    clear() {
+        this.mutexes.clear();
+    }
+}