@guilz-dev/belay 0.2.0 → 0.4.0

package/dist/core/types.d.ts

@@ -67,8 +67,15 @@ export interface ClassifierOptions {
     /** When true with sandbox enabled, outside-repo rules defer to fs-scope allowlist. */
     brokerFsScope?: boolean;
     fsScopeAllowlist?: FsScopeAllowlistFile;
+    trustedWorkspaceRoots?: string[];
     /** Test override: inject Tier1 judge without changing config.judge. */
     tier1Judge?: import('./verdict/types.js').Tier1Judge;
+    /** When false, path resolution stays fail-closed (opaque cd chains). Default: Boolean(cwd). */
+    trustedCwd?: boolean;
+}
+export interface ApprovalScopeHint {
+    scope: 'workspace-root';
+    path: string;
 }
 export interface ApprovalRecord {
     approvalId: string;
@@ -85,6 +92,16 @@ export interface ApprovalRecord {
     /** Original gated input for explain-last-ask (ApprovalState v2). */
     input?: string;
     inputKind?: 'shell' | 'tool' | 'subagent';
+    /** Replay envelope: working directory when the action was gated. */
+    cwd?: string;
+    /** Replay envelope: tool name for tool/subagent actions. */
+    toolName?: string;
+    /** Replay envelope: canonical payload hash for strict replay validation. */
+    payloadHash?: string;
+    /** Replay envelope: scrubbed payload JSON for explain (size-capped at write time). */
+    payloadJson?: string;
+    /** Optional scope hint for structured capability approvals. */
+    scopeHint?: ApprovalScopeHint;
 }
 export interface ApprovalStateFile {
     version: 1 | 2;

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

@@ -1,6 +1,7 @@
 import type { BelayConfigV4 } from '../config.js';
 import type { ClassifierOptions, ClassifyResult } from '../types.js';
 import type { Tier1Judge, VerdictContext, VerdictResult } from './types.js';
+export declare function resolveClassifierTrustedCwd(cwd: string, options?: Pick<ClassifierOptions, 'trustedCwd'>, explicit?: boolean): boolean;
 export declare function buildVerdictContext(params: {
     cwd: string;
     repoRoot: string;

package/dist/core/verdict/adapter.js

@@ -1,6 +1,13 @@
 import { judgeTraceAuditFields } from './judge-audit.js';
+import { recordJudgeLatency } from './judge-baseline.js';
 import { createJudgeFromConfig } from './judge-factory.js';
 import { verdict } from './verdict.js';
+export function resolveClassifierTrustedCwd(cwd, options, explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    return options?.trustedCwd ?? Boolean(cwd);
+}
 export function buildVerdictContext(params) {
     const protectedArtifactRoots = [
         ...(params.options?.protectedArtifactRoots ?? []),
@@ -9,12 +16,15 @@ export function buildVerdictContext(params) {
     return {
         cwd: params.cwd,
         repoRoot: params.repoRoot,
-        trustedCwd: params.trustedCwd ?? Boolean(params.cwd),
+        trustedCwd: resolveClassifierTrustedCwd(params.cwd, params.options, params.trustedCwd),
+        trustedWorkspaceRoots: params.options?.trustedWorkspaceRoots ?? [],
         sensitivePaths: params.options?.sensitivePaths ?? params.config.classifier.sensitivePaths,
         protectedArtifactRoots: protectedArtifactRoots.length > 0 ? [...new Set(protectedArtifactRoots)] : undefined,
         customAllowCommands: params.options?.customAllowCommands ?? params.config.overrides.allow,
         customExternalCommands: params.options?.customExternalCommands ?? params.config.overrides.external,
-        judge: params.judge ?? params.options?.tier1Judge ?? createJudgeFromConfig(params.config),
+        judge: params.judge ??
+            params.options?.tier1Judge ??
+            createJudgeFromConfig(params.config, { repoRoot: params.repoRoot }),
         mode: params.config.mode,
         unknownLocalEffect: params.options?.unknownLocalEffect ?? params.config.policy.unknownLocalEffect,
         unparseableShell: params.options?.unparseableShell ?? params.config.policy.unparseableShell,
@@ -22,7 +32,12 @@ export function buildVerdictContext(params) {
 }
 export async function classifyShell(command, cwd, repoRoot, config, options = {}, judge) {
     const context = buildVerdictContext({ cwd, repoRoot, config, options, judge });
+    const started = Date.now();
     const result = await verdict(command, context);
+    const elapsed = Date.now() - started;
+    if (result.confidence !== 'llm') {
+        recordJudgeLatency('tier0', elapsed);
+    }
     return verdictToClassifyResult(result);
 }
 function mapLegacyReason(result) {

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

@@ -1,3 +1,4 @@
+export { isOutsideRepoSecretCredentialPath, isPersistentAgentPath } from './persistent-paths.js';
 import type { VerdictLocation } from './types.js';
 export interface PathTargetAnalysis {
     location: VerdictLocation;
@@ -5,9 +6,13 @@ export interface PathTargetAnalysis {
     signals: string[];
 }
 export declare function resolveTrustedPath(token: string, trustedCwd: string, trusted: boolean): string | null;
-export declare function locationForPath(resolvedPath: string | null, repoRoot: string): VerdictLocation;
+export declare function locationForPath(resolvedPath: string | null, repoRoot: string, trustedWorkspaceRoots?: string[]): VerdictLocation;
 export declare function isGitPath(resolvedPath: string, repoRoot: string): boolean;
-export declare function isHighStakesPath(resolvedPath: string, repoRoot: string, sensitivePaths: string[], protectedRoots?: string[]): boolean;
+export declare function isHighStakesPath(resolvedPath: string, repoRoot: string, sensitivePaths: string[], protectedRoots?: string[], trustedWorkspaceRoots?: string[]): boolean;
+/** ADR-002 M3: destructive shell head on git/sensitive path (not broad category ask). */
+export declare function isDestructiveMutationHead(head: string): boolean;
+export declare function touchesProtectedRoot(resolvedPath: string, protectedRoots: string[]): boolean;
+export declare function isDestructiveHighStakesMutation(head: string, resolvedPath: string, repoRoot: string, sensitivePaths: string[], protectedRoots?: string[], trustedWorkspaceRoots?: string[]): boolean;
 export declare function analyzePathTargets(params: {
     targets: string[];
     cwd: string;
@@ -15,5 +20,6 @@ export declare function analyzePathTargets(params: {
     trustedCwd: boolean;
     sensitivePaths: string[];
     protectedArtifactRoots?: string[];
+    trustedWorkspaceRoots?: string[];
 }): PathTargetAnalysis;
 export declare function cwdRelative(repoRoot: string, cwd: string): string;

package/dist/core/verdict/containment.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { matchesSensitivePath } from '../glob.js';
-import { canonicalPath, pathWithinRoot, relativeWithinRepo, resolveMutationTarget, } from '../path-utils.js';
+import { canonicalPath, pathWithinRoot, relativeWithinRepo, resolveMutationTarget, resolveWorkspaceRootMatch, } from '../path-utils.js';
+import { isOutsideRepoSecretCredentialPath } from './persistent-paths.js';
+export { isOutsideRepoSecretCredentialPath, isPersistentAgentPath } from './persistent-paths.js';
 function expandHome(token) {
     if (token === '~' || token.startsWith('~/')) {
         const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
@@ -24,11 +26,11 @@ export function resolveTrustedPath(token, trustedCwd, trusted) {
     }
     return canonicalPath(path.resolve(trustedCwd, expanded));
 }
-export function locationForPath(resolvedPath, repoRoot) {
+export function locationForPath(resolvedPath, repoRoot, trustedWorkspaceRoots = []) {
     if (!resolvedPath) {
         return 'unknown';
     }
-    if (pathWithinRoot(repoRoot, resolvedPath)) {
+    if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolvedPath)) {
         return 'repo_local';
     }
     return 'repo_outside';
@@ -39,19 +41,52 @@ export function isGitPath(resolvedPath, repoRoot) {
         return false;
     }
     const normalized = relative.replaceAll('\\', '/');
-    return normalized === '.git' || normalized.startsWith('.git/');
+    return (normalized === '.git' ||
+        normalized.startsWith('.git/') ||
+        normalized.endsWith('/.git') ||
+        normalized.includes('/.git/'));
 }
-export function isHighStakesPath(resolvedPath, repoRoot, sensitivePaths, protectedRoots = []) {
+export function isHighStakesPath(resolvedPath, repoRoot, sensitivePaths, protectedRoots = [], trustedWorkspaceRoots = []) {
     if (isGitPath(resolvedPath, repoRoot)) {
         return true;
     }
-    const relative = relativeWithinRepo(repoRoot, resolvedPath);
-    const checkPath = relative ?? resolvedPath;
-    if (matchesSensitivePath(checkPath.replaceAll('\\', '/'), sensitivePaths)) {
+    const workspaceMatch = resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolvedPath);
+    if (workspaceMatch !== null &&
+        matchesSensitivePath(workspaceMatch.relativePath.replaceAll('\\', '/'), sensitivePaths)) {
+        return true;
+    }
+    if ((workspaceMatch === null || workspaceMatch.kind === 'trusted') &&
+        isOutsideRepoSecretCredentialPath(resolvedPath)) {
         return true;
     }
     return protectedRoots.some((root) => pathWithinRoot(root, resolvedPath));
 }
+const DESTRUCTIVE_MUTATION_HEADS = new Set([
+    'rm',
+    'shred',
+    'truncate',
+    'dd',
+    'chmod',
+    'chown',
+    'mv',
+    'cp',
+]);
+/** ADR-002 M3: destructive shell head on git/sensitive path (not broad category ask). */
+export function isDestructiveMutationHead(head) {
+    return DESTRUCTIVE_MUTATION_HEADS.has(head);
+}
+export function touchesProtectedRoot(resolvedPath, protectedRoots) {
+    return protectedRoots.some((root) => pathWithinRoot(root, resolvedPath) || root === resolvedPath);
+}
+export function isDestructiveHighStakesMutation(head, resolvedPath, repoRoot, sensitivePaths, protectedRoots = [], trustedWorkspaceRoots = []) {
+    if (touchesProtectedRoot(resolvedPath, protectedRoots)) {
+        return true;
+    }
+    if (!isDestructiveMutationHead(head)) {
+        return false;
+    }
+    return isHighStakesPath(resolvedPath, repoRoot, sensitivePaths, [], trustedWorkspaceRoots);
+}
 export function analyzePathTargets(params) {
     const signals = [];
     if (!params.trustedCwd || !params.cwd) {
@@ -66,10 +101,10 @@ export function analyzePathTargets(params) {
     for (const target of params.targets) {
         const resolved = resolveTrustedPath(target, params.cwd, params.trustedCwd) ??
             resolveMutationTarget(target, params.cwd);
-        const location = locationForPath(resolved, params.repoRoot);
+        const location = locationForPath(resolved, params.repoRoot, params.trustedWorkspaceRoots);
         locations.add(location);
         if (resolved &&
-            isHighStakesPath(resolved, params.repoRoot, params.sensitivePaths, params.protectedArtifactRoots)) {
+            isHighStakesPath(resolved, params.repoRoot, params.sensitivePaths, params.protectedArtifactRoots, params.trustedWorkspaceRoots)) {
             isHighStakes = true;
             signals.push('high_stakes_path');
         }

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

@@ -1,2 +1,3 @@
 import type { JudgeTrace } from './types.js';
+export declare function hashJudgeSessionRef(value: string): string;
 export declare function judgeTraceAuditFields(trace?: JudgeTrace): Record<string, unknown>;

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

@@ -1,3 +1,7 @@
+import { createHash } from 'node:crypto';
+export function hashJudgeSessionRef(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
 export function judgeTraceAuditFields(trace) {
     if (!trace) {
         return {};
@@ -10,6 +14,33 @@ export function judgeTraceAuditFields(trace) {
         ...(trace.outboundRedacted !== undefined
             ? { judgeOutboundRedacted: trace.outboundRedacted }
             : {}),
-        ...(trace.fallbackReason ? { judgeFallbackReason: trace.fallbackReason } : {}),
+        ...(trace.judgeFallbackReason
+            ? { judgeFallbackReason: trace.judgeFallbackReason }
+            : trace.fallbackReason
+                ? { judgeFallbackReason: trace.fallbackReason }
+                : {}),
+        ...(trace.judgeSessionUsed !== undefined ? { judgeSessionUsed: trace.judgeSessionUsed } : {}),
+        ...(trace.judgeSessionReused !== undefined
+            ? { judgeSessionReused: trace.judgeSessionReused }
+            : {}),
+        ...(trace.judgeSessionRefHash ? { judgeSessionRefHash: trace.judgeSessionRefHash } : {}),
+        ...(trace.judgeSessionResetReason
+            ? { judgeSessionResetReason: trace.judgeSessionResetReason }
+            : {}),
+        ...(trace.judgeConnectMs !== undefined ? { judgeConnectMs: trace.judgeConnectMs } : {}),
+        ...(trace.judgeEvalMs !== undefined ? { judgeEvalMs: trace.judgeEvalMs } : {}),
+        ...(trace.judgeParseMs !== undefined ? { judgeParseMs: trace.judgeParseMs } : {}),
+        ...(trace.judgeShadowCompared !== undefined
+            ? { judgeShadowCompared: trace.judgeShadowCompared }
+            : {}),
+        ...(trace.judgeShadowMismatch !== undefined
+            ? { judgeShadowMismatch: trace.judgeShadowMismatch }
+            : {}),
+        ...(trace.judgeShadowMismatchRateWindow !== undefined
+            ? { judgeShadowMismatchRateWindow: trace.judgeShadowMismatchRateWindow }
+            : {}),
+        ...(trace.judgeKillSwitchTriggered !== undefined
+            ? { judgeKillSwitchTriggered: trace.judgeKillSwitchTriggered }
+            : {}),
     };
 }

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

@@ -0,0 +1,20 @@
+import { JUDGE_LATENCY_SLO } from './judge-runtime-config.js';
+export type JudgeLatencyPhase = 'tier0' | 'tier1_spawn' | 'tier1_session' | 'tier1_connect' | 'tier1_eval' | 'tier1_parse';
+export interface JudgeLatencySample {
+    phase: JudgeLatencyPhase;
+    latencyMs: number;
+    at: number;
+}
+export interface JudgeLatencyPercentiles {
+    p50: number;
+    p95: number;
+    count: number;
+}
+export declare function resetJudgeLatencySamples(): void;
+export declare function recordJudgeLatency(phase: JudgeLatencyPhase, latencyMs: number, at?: number): void;
+export declare function judgeLatencyPercentiles(phase: JudgeLatencyPhase): JudgeLatencyPercentiles;
+export declare function judgeLatencySloReport(): {
+    slo: typeof JUDGE_LATENCY_SLO;
+    measured: Record<JudgeLatencyPhase, JudgeLatencyPercentiles>;
+    sessionMeetsTarget: boolean;
+};

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

@@ -0,0 +1,48 @@
+import { JUDGE_LATENCY_SLO } from './judge-runtime-config.js';
+const samples = [];
+const MAX_SAMPLES = 2_000;
+export function resetJudgeLatencySamples() {
+    samples.length = 0;
+}
+export function recordJudgeLatency(phase, latencyMs, at = Date.now()) {
+    if (!Number.isFinite(latencyMs) || latencyMs < 0) {
+        return;
+    }
+    samples.push({ phase, latencyMs, at });
+    if (samples.length > MAX_SAMPLES) {
+        samples.splice(0, samples.length - MAX_SAMPLES);
+    }
+}
+function percentile(values, p) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[Math.max(0, index)] ?? 0;
+}
+export function judgeLatencyPercentiles(phase) {
+    const values = samples
+        .filter((sample) => sample.phase === phase)
+        .map((sample) => sample.latencyMs);
+    return {
+        p50: percentile(values, 50),
+        p95: percentile(values, 95),
+        count: values.length,
+    };
+}
+export function judgeLatencySloReport() {
+    const measured = {
+        tier0: judgeLatencyPercentiles('tier0'),
+        tier1_spawn: judgeLatencyPercentiles('tier1_spawn'),
+        tier1_session: judgeLatencyPercentiles('tier1_session'),
+        tier1_connect: judgeLatencyPercentiles('tier1_connect'),
+        tier1_eval: judgeLatencyPercentiles('tier1_eval'),
+        tier1_parse: judgeLatencyPercentiles('tier1_parse'),
+    };
+    const spawnP95 = measured.tier1_spawn.count > 0 ? measured.tier1_spawn.p95 : JUDGE_LATENCY_SLO.spawnBaselineP95Ms;
+    const sessionP95 = measured.tier1_session.count > 0 ? measured.tier1_session.p95 : spawnP95;
+    const targetP95 = spawnP95 * (1 - JUDGE_LATENCY_SLO.tier1P95ReductionTarget);
+    const sessionMeetsTarget = sessionP95 <= targetP95 && sessionP95 <= JUDGE_LATENCY_SLO.sessionMaxP95Ms;
+    return { slo: JUDGE_LATENCY_SLO, measured, sessionMeetsTarget };
+}

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

@@ -0,0 +1,42 @@
+import type { CliJudgeRunCommand } from './judge-cli.js';
+import type { BelayJudgeSessionConfig } from './judge-runtime-config.js';
+import { type BrokerEvaluateRequest, type BrokerEvaluateResult, JudgeSessionBroker, stopRepoJudgeSessionBroker } from './judge-session-broker.js';
+import type { JudgeSessionResetReason } from './judge-session-guard.js';
+export declare const JUDGE_BROKER_SOCKET = "judge-broker.sock";
+export declare const JUDGE_BROKER_STATUS = "judge-broker.json";
+export declare const JUDGE_BROKER_PID = "judge-broker.pid";
+export declare const JUDGE_BROKER_SESSION = "judge-broker-session.json";
+export interface JudgeBrokerStatus {
+    pid: number;
+    repoRoot: string;
+    socketPath: string;
+    startedAt: string;
+}
+export interface JudgeBrokerPaths {
+    stateDir: string;
+    socketPath: string;
+    statusPath: string;
+    pidPath: string;
+    sessionConfigPath: string;
+}
+export declare function judgeBrokerPaths(stateDir: string): JudgeBrokerPaths;
+export declare function ensureJudgeBrokerDaemon(stateDir: string, repoRoot: string, sessionConfig: BelayJudgeSessionConfig): Promise<JudgeBrokerPaths>;
+export declare function cleanupJudgeBrokerArtifacts(paths: JudgeBrokerPaths): Promise<void>;
+export declare function stopJudgeBrokerDaemon(stateDir: string): Promise<number>;
+export declare function evaluateViaJudgeBroker(options: {
+    stateDir: string;
+    repoRoot: string;
+    sessionConfig: BelayJudgeSessionConfig;
+    request: BrokerEvaluateRequest;
+    timeoutMs: number;
+    runCommand?: CliJudgeRunCommand;
+}): Promise<BrokerEvaluateResult>;
+export declare function resetJudgeBrokerForTests(): void;
+export declare function invalidateJudgeSession(options: {
+    stateDir: string;
+    repoRoot: string;
+    sessionConfig: BelayJudgeSessionConfig;
+    sessionKey: string;
+    reason: JudgeSessionResetReason;
+}): Promise<void>;
+export { JudgeSessionBroker, stopRepoJudgeSessionBroker };

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

@@ -0,0 +1,279 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runCliJsonWithTimeouts } from './judge-cli.js';
+import { normalizeJudgeSessionConfig } from './judge-runtime-config.js';
+import { getRepoJudgeSessionBroker, JudgeSessionBroker, resetJudgeSessionBrokersForTests, stopRepoJudgeSessionBroker, } from './judge-session-broker.js';
+export const JUDGE_BROKER_SOCKET = 'judge-broker.sock';
+export const JUDGE_BROKER_STATUS = 'judge-broker.json';
+export const JUDGE_BROKER_PID = 'judge-broker.pid';
+export const JUDGE_BROKER_SESSION = 'judge-broker-session.json';
+export function judgeBrokerPaths(stateDir) {
+    return {
+        stateDir,
+        socketPath: path.join(stateDir, JUDGE_BROKER_SOCKET),
+        statusPath: path.join(stateDir, JUDGE_BROKER_STATUS),
+        pidPath: path.join(stateDir, JUDGE_BROKER_PID),
+        sessionConfigPath: path.join(stateDir, JUDGE_BROKER_SESSION),
+    };
+}
+function daemonScriptPath() {
+    return fileURLToPath(new URL('../../judge-broker-daemon.js', import.meta.url));
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function useInProcessBroker(env = process.env) {
+    return Boolean(env.VITEST || env.VITEST_WORKER_ID || env.BELAY_JUDGE_BROKER_IN_PROCESS === '1');
+}
+async function readBrokerStatus(statusPath) {
+    if (!existsSync(statusPath)) {
+        return null;
+    }
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const raw = JSON.parse(await readFile(statusPath, 'utf8'));
+        if (typeof raw.pid !== 'number' || typeof raw.socketPath !== 'string') {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+async function readBrokerSessionConfig(sessionConfigPath) {
+    if (!existsSync(sessionConfigPath)) {
+        return null;
+    }
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const raw = JSON.parse(await readFile(sessionConfigPath, 'utf8'));
+        return normalizeJudgeSessionConfig({ ...raw, enabled: true });
+    }
+    catch {
+        return null;
+    }
+}
+function brokerSessionConfigPayload(sessionConfig) {
+    return JSON.stringify(normalizeJudgeSessionConfig({ ...sessionConfig, enabled: true }));
+}
+async function writeBrokerSessionConfig(paths, sessionConfig) {
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(paths.sessionConfigPath, brokerSessionConfigPayload(sessionConfig), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+async function connectBrokerSocket(socketPath, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(socketPath);
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('judge broker connect timed out'));
+        }, timeoutMs);
+        socket.once('connect', () => {
+            clearTimeout(timer);
+            resolve(socket);
+        });
+        socket.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+async function rpcEvaluate(socketPath, request, timeoutMs, connectTimeoutMs) {
+    const socket = await connectBrokerSocket(socketPath, connectTimeoutMs);
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const payload = JSON.stringify({
+        type: 'evaluate',
+        id,
+        request,
+        timeoutMs,
+    });
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('judge broker evaluate timed out'));
+        }, timeoutMs + connectTimeoutMs);
+        const onData = (chunk) => {
+            buffer += String(chunk);
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line.trim()) {
+                    continue;
+                }
+                try {
+                    const message = JSON.parse(line);
+                    if (message.id !== id) {
+                        continue;
+                    }
+                    clearTimeout(timer);
+                    socket.destroy();
+                    if (message.type === 'error') {
+                        reject(new Error(message.error ?? 'judge broker error'));
+                        return;
+                    }
+                    if (message.result) {
+                        resolve(message.result);
+                    }
+                }
+                catch {
+                    // wait for more data
+                }
+            }
+        };
+        socket.on('data', onData);
+        socket.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        socket.write(`${payload}\n`);
+    });
+}
+export async function ensureJudgeBrokerDaemon(stateDir, repoRoot, sessionConfig) {
+    const paths = judgeBrokerPaths(stateDir);
+    const brokerSessionConfig = normalizeJudgeSessionConfig({ ...sessionConfig, enabled: true });
+    const nextConfigPayload = brokerSessionConfigPayload(brokerSessionConfig);
+    const existingConfig = await readBrokerSessionConfig(paths.sessionConfigPath);
+    const configChanged = existingConfig !== null && brokerSessionConfigPayload(existingConfig) !== nextConfigPayload;
+    const status = await readBrokerStatus(paths.statusPath);
+    if (status && isProcessAlive(status.pid) && existsSync(paths.socketPath) && !configChanged) {
+        await writeBrokerSessionConfig(paths, brokerSessionConfig);
+        return paths;
+    }
+    if (status?.pid && isProcessAlive(status.pid)) {
+        await stopJudgeBrokerDaemon(stateDir);
+    }
+    else {
+        await cleanupJudgeBrokerArtifacts(paths);
+    }
+    await writeBrokerSessionConfig(paths, brokerSessionConfig);
+    const child = spawn(process.execPath, [daemonScriptPath()], {
+        detached: true,
+        stdio: 'ignore',
+        env: {
+            ...process.env,
+            BELAY_JUDGE_BROKER_REPO_ROOT: repoRoot,
+            BELAY_JUDGE_BROKER_STATE_DIR: stateDir,
+        },
+    });
+    child.unref();
+    const deadline = Date.now() + sessionConfig.connectTimeoutMs;
+    while (Date.now() < deadline) {
+        if (existsSync(paths.socketPath)) {
+            const live = await readBrokerStatus(paths.statusPath);
+            if (live && isProcessAlive(live.pid)) {
+                return paths;
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw new Error('judge broker daemon failed to start');
+}
+export async function cleanupJudgeBrokerArtifacts(paths) {
+    for (const artifact of [
+        paths.socketPath,
+        paths.statusPath,
+        paths.pidPath,
+        paths.sessionConfigPath,
+    ]) {
+        if (existsSync(artifact)) {
+            await unlink(artifact).catch(() => undefined);
+        }
+    }
+}
+export async function stopJudgeBrokerDaemon(stateDir) {
+    const paths = judgeBrokerPaths(stateDir);
+    const status = await readBrokerStatus(paths.statusPath);
+    if (status?.pid && isProcessAlive(status.pid)) {
+        try {
+            process.kill(status.pid, 'SIGTERM');
+        }
+        catch {
+            // already stopped
+        }
+    }
+    await cleanupJudgeBrokerArtifacts(paths);
+    return status?.pid ? 1 : 0;
+}
+export async function evaluateViaJudgeBroker(options) {
+    const runCommand = options.runCommand ??
+        ((invocation, timeout) => runCliJsonWithTimeouts(invocation, { evalTimeoutMs: timeout }));
+    if (useInProcessBroker()) {
+        const broker = getRepoJudgeSessionBroker(options.repoRoot, {
+            config: options.sessionConfig,
+            runCommand,
+        });
+        return broker.evaluate(options.request, options.timeoutMs);
+    }
+    const paths = await ensureJudgeBrokerDaemon(options.stateDir, options.repoRoot, options.sessionConfig);
+    return rpcEvaluate(paths.socketPath, options.request, options.timeoutMs, options.sessionConfig.connectTimeoutMs);
+}
+export function resetJudgeBrokerForTests() {
+    resetJudgeSessionBrokersForTests();
+}
+async function rpcInvalidate(socketPath, sessionKey, reason, connectTimeoutMs) {
+    const socket = await connectBrokerSocket(socketPath, connectTimeoutMs);
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const payload = JSON.stringify({ type: 'invalidate', id, sessionKey, reason });
+    await new Promise((resolve, reject) => {
+        let buffer = '';
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('judge broker invalidate timed out'));
+        }, connectTimeoutMs);
+        const onData = (chunk) => {
+            buffer += String(chunk);
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line.trim()) {
+                    continue;
+                }
+                try {
+                    const message = JSON.parse(line);
+                    if (message.id !== id) {
+                        continue;
+                    }
+                    clearTimeout(timer);
+                    socket.destroy();
+                    resolve();
+                }
+                catch {
+                    // wait for more data
+                }
+            }
+        };
+        socket.on('data', onData);
+        socket.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        socket.write(`${payload}\n`);
+    });
+}
+export async function invalidateJudgeSession(options) {
+    if (useInProcessBroker()) {
+        const broker = getRepoJudgeSessionBroker(options.repoRoot, {
+            config: { ...options.sessionConfig, enabled: true },
+            runCommand: (invocation, timeout) => runCliJsonWithTimeouts(invocation, { evalTimeoutMs: timeout }),
+        });
+        broker.invalidateSession(options.sessionKey, options.reason);
+        return;
+    }
+    const paths = await ensureJudgeBrokerDaemon(options.stateDir, options.repoRoot, options.sessionConfig);
+    await rpcInvalidate(paths.socketPath, options.sessionKey, options.reason, options.sessionConfig.connectTimeoutMs);
+}
+export { JudgeSessionBroker, stopRepoJudgeSessionBroker };