@heretyc/subagent-mcp 2.6.0

package/dist/routing.js

@@ -0,0 +1,260 @@
+/**
+ * Routing-table loader and pure resolver for auto-mode launches.
+ *
+ * Loads dist/routing-table.json (copied from src/routing-table.json at build by
+ * scripts/copy-provider.mjs), then builds an ordered candidate list per the
+ * supplied overrides. NO spawning happens here — the attempt loop in index.ts
+ * consumes the candidate triples and reuses buildCommand/resolveExe/spawn.
+ *
+ * Contract: docs/spec/auto-mode/routing-table-contract.md.
+ * effort.ts / platform.ts are wrapped, never modified.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** Launch model enum accepted by buildCommand. */
+export const LAUNCH_MODELS = ["haiku", "sonnet", "opus", "opus-4-8", "gpt-5.5"];
+/** Launch effort enum accepted by buildCommand/resolveEffort. */
+export const LAUNCH_EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultracode"];
+/** Sentinel reported (and passed-through harmlessly) for haiku, whose effort is ignored. */
+export const HAIKU_EFFORT = "none";
+/**
+ * FULL table model id -> SHORT launch id. Only launchable models appear here.
+ * Non-launchable ids (gpt-5.5-pro, gpt-5.4-mini, claude-opus-4-7, unknown) are
+ * intentionally absent so buildCandidates skips them rather than coercing.
+ * For models with aliases (e.g., opus and opus-4-8 both refer to claude-opus-4-8),
+ * map to a Set of valid short ids to check membership during filtering.
+ */
+const FULL_TO_SHORT = {
+    "claude-opus-4-8": new Set(["opus", "opus-4-8"]),
+    "claude-sonnet-4-6": "sonnet",
+    "claude-haiku-4-5": "haiku",
+    "gpt-5.5": "gpt-5.5",
+    // Short ids may already appear in a hand-authored table; map them through.
+    haiku: "haiku",
+    sonnet: "sonnet",
+    opus: "opus",
+    "opus-4-8": "opus-4-8",
+};
+export const DEFAULT_BRANCH = "cost_efficiency";
+/** Resolve dist/routing-table.json relative to this module at runtime. */
+function defaultTablePath() {
+    return fileURLToPath(new URL("./routing-table.json", import.meta.url));
+}
+/**
+ * Load + parse the routing table. Never throws: ENOENT, parse error, or any
+ * read failure -> null (handler emits ERR_TABLE_MISSING).
+ *
+ * Fresh read per launch — NO process-lifetime cache. The file is tiny and
+ * launches are infrequent, so a table emitted AFTER server start (the profiler
+ * scenario) is picked up on the next launch with no restart
+ * (routing-table-contract.md). When `path` is given (tests) it is read directly.
+ */
+export function loadRoutingTable(path) {
+    return readTable(path ?? defaultTablePath());
+}
+function readTable(path) {
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Map a table model id to its launch provider. Claude ids -> "claude"; any
+ * GPT/codex-family id -> "codex"; unrecognised -> null (skip signal; never
+ * coerce). Non-launchable codex siblings (gpt-5.5-pro) still map to "codex" so
+ * the provider filter is correct; they are dropped later at the launch-enum step.
+ */
+export function mapModelToProvider(model) {
+    if (model === "haiku" ||
+        model === "sonnet" ||
+        model === "opus" ||
+        model === "opus-4-8" ||
+        model.startsWith("claude-")) {
+        return "claude";
+    }
+    if (model === "gpt-5.5" || model.startsWith("gpt-")) {
+        return "codex";
+    }
+    return null;
+}
+/**
+ * Normalize a table effort tier to the launch enum, mirroring src/effort.ts so
+ * the resolver never feeds an invalid combo into buildCommand.
+ *
+ * - haiku -> "none" sentinel (effort ignored by buildCommand; reported as-is).
+ * - `none` on effort-capable models is invalid routing data -> null (skip candidate).
+ * - ultracode is opus/opus-4-8 only; any other model clamps to "xhigh".
+ * - codex has no max/ultracode; both clamp to "xhigh".
+ * - unknown tier (not in the launch enum) -> null (skip candidate).
+ *
+ * `model` here is the SHORT launch id.
+ */
+export function normalizeEffort(provider, model, effort) {
+    // haiku ignores effort entirely; report the sentinel.
+    if (provider === "claude" && model === "haiku") {
+        return HAIKU_EFFORT;
+    }
+    const isOpus48 = provider === "claude" && (model === "opus" || model === "opus-4-8");
+    if (effort === "ultracode") {
+        return isOpus48 ? "ultracode" : "xhigh";
+    }
+    // Unknown tiers (not a launch-enum value, not handled above) -> skip.
+    if (typeof effort !== "string" || !LAUNCH_EFFORTS.includes(effort)) {
+        return null;
+    }
+    if (provider === "codex" && effort === "max") {
+        return "xhigh";
+    }
+    return effort;
+}
+/**
+ * Build the ordered candidate list for a launch.
+ *
+ * explicit (provider+model+effort all present): one candidate from the user's
+ * triple; the table is NOT read (works with a null table).
+ *
+ * auto/provider/provider_model: read performance.<task_category> as the pairings
+ * array directly (defensive .pairings unwrap), sort by rank asc, map each model
+ * to a launch id, normalize effort, and drop non-launchable / unknown-effort
+ * pairings. An empty result sets noCandidates:true.
+ */
+export function buildCandidates(table, taskCategory, overrides, branch = DEFAULT_BRANCH) {
+    const { provider, model, effort } = overrides;
+    // explicit: all three present — single direct attempt, no table read. The
+    // effort is normalized exactly like table rows (haiku -> "none", codex
+    // max -> xhigh, non-opus ultracode -> xhigh) so the candidate list is
+    // always validator-legal for the advanced-ruleset payload (io-contract.md).
+    if (provider && model && effort) {
+        return {
+            mode: "explicit",
+            candidates: [
+                { provider, model, effort: normalizeEffort(provider, model, effort) ?? effort },
+            ],
+        };
+    }
+    const mode = provider && model ? "provider_model" : provider ? "provider" : "auto";
+    const pairings = readPairings(table, taskCategory, branch);
+    const candidates = [];
+    for (const entry of pairings) {
+        const mappedProvider = mapModelToProvider(entry.model);
+        if (mappedProvider === null)
+            continue; // unknown id — skip, never coerce.
+        const shortModelOrSet = FULL_TO_SHORT[entry.model];
+        if (shortModelOrSet === undefined)
+            continue; // not in the launch enum — skip.
+        // Unwrap shortModel: handle both string and Set of aliases.
+        // For the returned candidate, use the canonical short id (opus-4-8 not opus).
+        // For matching user's model filter: check membership in the Set.
+        let shortModel;
+        if (shortModelOrSet instanceof Set) {
+            // Canonical form: "opus-4-8" for Opus models (prefer versioned).
+            shortModel = shortModelOrSet.has("opus-4-8") ? "opus-4-8" : Array.from(shortModelOrSet)[0];
+        }
+        else {
+            shortModel = shortModelOrSet;
+        }
+        // provider / provider_model filters operate on the mapped provider + short id.
+        if (provider && mappedProvider !== provider)
+            continue;
+        if (model) {
+            // Check membership: if shortModelOrSet is a Set, check if model is in it.
+            const modelMatches = shortModelOrSet instanceof Set
+                ? shortModelOrSet.has(model)
+                : shortModel === model;
+            if (!modelMatches)
+                continue;
+        }
+        const normEffort = normalizeEffort(mappedProvider, shortModel, entry.effort);
+        if (normEffort === null)
+            continue; // unknown effort tier — skip.
+        candidates.push({ provider: mappedProvider, model: shortModel, effort: normEffort });
+    }
+    if (candidates.length === 0) {
+        return { mode, candidates, noCandidates: true };
+    }
+    return { mode, candidates };
+}
+/** Read <branch>.<category> as the pairings array, sorted by rank asc. */
+function readPairings(table, taskCategory, branch = DEFAULT_BRANCH) {
+    if (!table || typeof table !== "object")
+        return [];
+    const perf = table[branch];
+    if (!perf || typeof perf !== "object")
+        return [];
+    let raw = perf[taskCategory];
+    // Defensive: tolerate a {pairings:[...]} wrapper even though the contract
+    // says the value IS the array directly.
+    if (raw && !Array.isArray(raw) && typeof raw === "object" && "pairings" in raw) {
+        raw = raw.pairings;
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const entries = raw.filter((e) => !!e && typeof e === "object" && typeof e.model === "string");
+    return [...entries].sort((a, b) => (a.rank ?? Number.MAX_SAFE_INTEGER) - (b.rank ?? Number.MAX_SAFE_INTEGER));
+}
+// The fixed 10 task categories + fallback_default. Maps directly to the
+// routing-table category keys (param-contract.md). Immutable taxonomy.
+export const TASK_CATEGORIES = [
+    "math_proof",
+    "security_review",
+    "debugging",
+    "quality_review",
+    "architecture",
+    "agentic_execution",
+    "data_analysis",
+    "coding",
+    "knowledge_synthesis",
+    "mechanical",
+    "fallback_default",
+];
+// Shared error hint blocks (resolution-matrix.md). Appended verbatim.
+export const AUTO_HINT = "Tip: omit provider/model/effort entirely and the server auto-selects the best provider/model/effort for this task_category, with automatic silent fallback.";
+export const SPLIT_HINT = "If unsure which category fits, do NOT pass one big amorphous task: break the work into smaller atomic steps that each map to a single task_category, and launch one agent per step.";
+/**
+ * Pure param-presence validator for launch_agent (resolution-matrix.md).
+ *
+ * Returns the exact error string for the first failing rule, or null when the
+ * presence combination is valid. Order MUST match resolution-matrix.md
+ * "Validation order": category, then effort-needs-both, then model-needs-provider,
+ * then the explicit provider↔model match rule. Exported (and side-effect-free:
+ * this module never spawns or opens a transport) so the matrix and the verbatim
+ * error text (incl. AUTO_HINT/SPLIT_HINT placement) are CI-asserted directly
+ * against the production logic (Rule 9), not a re-implementation.
+ */
+export function validatePresence(p) {
+    const { task_category, provider, model, effort, deadlock } = p;
+    // 1. task_category valid?
+    if (!task_category || !TASK_CATEGORIES.includes(task_category)) {
+        const got = task_category ? String(task_category) : "<none>";
+        return `Error: task_category is required and must be one of: math_proof, security_review, debugging, quality_review, architecture, agentic_execution, data_analysis, coding, knowledge_synthesis, mechanical, fallback_default. Got: ${got}.\n${SPLIT_HINT}\n${AUTO_HINT}`;
+    }
+    // 2. deadlock cannot be combined with provider/model/effort.
+    if (deadlock === true && (provider || model || effort)) {
+        return `Error: deadlock cannot be combined with provider, model, or effort. If repeated attempts at this task have failed, switch to pure auto mode — pass only prompt + task_category and let the server select — unless your assignment explicitly demands a specific model. Omit provider/model/effort and retry.\n${AUTO_HINT}`;
+    }
+    // 3. effort present must come with provider AND model (checked before model rule).
+    if (effort && !(provider && model)) {
+        return `Error: effort requires both provider and model. You passed effort=${effort} without a complete provider+model. Either pass provider+model+effort for a fully explicit launch, or omit all three.\n${AUTO_HINT}`;
+    }
+    // 4. model present must come with provider.
+    if (model && !provider) {
+        return `Error: provider is required when model is given. You passed model=${model} without provider. Either also pass provider, or omit both.\n${AUTO_HINT}`;
+    }
+    // 5. explicit mode only: provider+model must satisfy the existing match rule.
+    if (provider && model) {
+        if (provider === "claude" && !["haiku", "sonnet", "opus", "opus-4-8"].includes(model)) {
+            return `Error: Claude provider only supports haiku, sonnet, opus, or opus-4-8. Got: ${model}`;
+        }
+        if (provider === "codex" && model !== "gpt-5.5") {
+            return `Error: Codex provider only supports gpt-5.5. Got: ${model}`;
+        }
+    }
+    return null;
+}

package/dist/ruleset-scaffold.js

@@ -0,0 +1,2 @@
+// GENERATED by scripts/gen-ruleset-scaffold.mjs from src/advanced-ruleset.py — DO NOT EDIT.
+export const RULESET_SCAFFOLD = "#!/usr/bin/env python3\r\n\"\"\"advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.\r\n\r\n(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent\r\n    call. Slow rules slow every agent launch. Keep rules lean and low-latency —\r\n    no network calls, no heavy imports at module top. This is YOUR responsibility;\r\n    you have been warned.\r\n\r\n(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified\r\n    candidate list (reorder / filter / replace allowed). Template:\r\n    [\r\n      {\"provider\": \"claude\", \"model\": \"sonnet\",  \"effort\": \"high\",  \"rank\": 1},\r\n      {\"provider\": \"codex\",  \"model\": \"gpt-5.5\", \"effort\": \"xhigh\", \"rank\": 2}\r\n    ]\r\n    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);\r\n    gpt-5.5 (codex). Valid efforts: haiku -> \"none\" only; sonnet -> low|medium|high|xhigh|max;\r\n    opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> low|medium|high|xhigh.\r\n    \"rank\" on output is ignored. An EMPTY array vetoes the launch. Anything else\r\n    invalid fails the launch hard — the server validates strictly.\r\n\r\n(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):\r\n    stdin receives one JSON object:\r\n    { \"candidates\": [ {\"provider\",\"model\",\"effort\",\"rank\"} ... ],   # rank 1..N best->worst\r\n      \"context\": { \"task_category\": str, \"cwd\": str,\r\n                   \"selection_mode\": \"auto\"|\"provider\"|\"provider_model\"|\"explicit\",\r\n                   \"provider\": str|None, \"model\": str|None, \"effort\": str|None } }\r\n    OS environment variables are visible natively (os.environ).\r\n\r\nENV-CHECK MODE (no arguments): prints {\"ready\": true|false, \"load-rules\": true|false}.\r\nRuns once per MCP server process. load-rules false => ruleset silently disabled\r\nfor the rest of the process. Set LOAD_RULES = True below to activate.\r\n\"\"\"\r\nimport json\r\nimport sys\r\n\r\nLOAD_RULES = False\r\n\r\n# --- Requirements stub (scaffold itself is stdlib-only) ----------------------\r\n# List third-party distributions your rules import, e.g.:\r\n# REQUIREMENTS = [\"requests\", \"pyyaml\"]\r\n# Install with:  <python> -m pip install <name> ...\r\nREQUIREMENTS = []\r\n\r\ndef missing_requirements():\r\n    \"\"\"pip-check helper: returns the REQUIREMENTS entries not importable here.\"\"\"\r\n    import importlib.util\r\n    return [r for r in REQUIREMENTS\r\n            if importlib.util.find_spec(r.replace(\"-\", \"_\")) is None]\r\n\r\ndef env_check():\r\n    missing = missing_requirements()\r\n    json.dump({\"ready\": not missing, \"load-rules\": bool(LOAD_RULES)}, sys.stdout)\r\n\r\ndef apply_rules(candidates, context):\r\n    \"\"\"YOUR RULES HERE. Default: passthrough (returns the list unchanged).\"\"\"\r\n    return candidates\r\n\r\ndef route():\r\n    payload = json.load(sys.stdin)\r\n    out = apply_rules(payload.get(\"candidates\", []), payload.get(\"context\", {}))\r\n    json.dump(out, sys.stdout)\r\n\r\nif __name__ == \"__main__\":\r\n    if len(sys.argv) > 1 and sys.argv[1] == \"route\":\r\n        route()\r\n    else:\r\n        env_check()\r\n";

package/dist/ruleset.js

@@ -0,0 +1,319 @@
+/**
+ * advanced-ruleset.py execution gate — the user-editable python override hook
+ * with final authority over launch_agent model routing.
+ *
+ * Side-effect-free at import time (like routing.ts: no spawning, no transport,
+ * no FS reads at module scope) so unit tests can import dist/ruleset.js
+ * directly. index.ts instantiates ONE createRulesetGate() singleton next to
+ * deadlockWindow; the gate's latch is per-process, exactly the deadlock-window
+ * scoping: env-check SUCCESS latches enabled/disabled for the process lifetime,
+ * FAILURE never latches (re-run on the next launch_agent so an admin fix
+ * recovers without a restart).
+ *
+ * Contract: docs/spec/advanced-ruleset/.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { LAUNCH_MODELS, LAUNCH_EFFORTS, HAIKU_EFFORT } from "./routing.js";
+import { RULESET_SCAFFOLD } from "./ruleset-scaffold.js";
+/** Hardcoded per-execution timeout (2 minutes per the owner spec). Tests assert the value. */
+export const RULESET_TIMEOUT_MS = 120_000;
+/**
+ * Verbatim hard-fail message for ANY ruleset failure (missing interpreter,
+ * non-zero exit, invalid/non-serializable JSON, timeout). NO AUTO_HINT is ever
+ * appended — a deliberate, documented exception to the every-error-gets-hints
+ * convention (resolution-matrix.md): the admin must intervene, not the model.
+ */
+export const RULESET_HARD_FAIL_MSG = "subagent ruleset erroring. Please ask the system administrator to debug before continuing. It is highly discouraged to continue use of this chat session as the system is now operating outside safe parameters.";
+export const SCAFFOLD_FILENAME = "advanced-ruleset.py";
+/** Resolve dist/advanced-ruleset.py relative to this module — the routing-table.json sibling dir. */
+export function defaultScaffoldPath() {
+    return fileURLToPath(new URL("./advanced-ruleset.py", import.meta.url));
+}
+/**
+ * Recreate the scaffold when absent (runtime recovery for a deleted file). An
+ * existing file is NEVER touched — user edits are sacred. Throws on write
+ * failure; the gate methods catch any throw in the ruleset pipeline and map it
+ * to the hard-fail result.
+ */
+export function ensureScaffold(path = defaultScaffoldPath()) {
+    if (existsSync(path))
+        return;
+    writeFileSync(path, RULESET_SCAFFOLD);
+}
+/**
+ * Interpreter auto-detect order. SUBAGENT_RULESET_PYTHON (non-empty) is
+ * EXCLUSIVE — no fallback past it: a wrong override must surface as the hard
+ * fail, never be masked by PATH luck. Otherwise: py launcher (win32 only),
+ * python3, python.
+ */
+export function interpreterCandidates(env, platform) {
+    const override = env.SUBAGENT_RULESET_PYTHON;
+    if (override)
+        return [override];
+    return platform === "win32" ? ["py", "python3", "python"] : ["python3", "python"];
+}
+/**
+ * Run the script once. Mode discriminator is argv: no extra args = env check;
+ * ["route"] = routing mode (payload written to stdin, then end). OS env vars
+ * reach the script natively via process.env. Spawn failures are ASYNC
+ * (ENOENT/EACCES emit 'error' after spawn() returns) — same one-shot
+ * spawn-vs-error race discipline as the launch path in index.ts. The timeout
+ * kills the child (SIGKILL fallback after 2s on POSIX) and settles the promise
+ * immediately. stderr is collected for server-side logging only; the MCP
+ * caller only ever sees the verbatim hard-fail message.
+ */
+function execRuleset(interpreter, scriptPath, argvExtra, stdinText, timeoutMs) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(interpreter, [scriptPath, ...argvExtra], {
+                stdio: ["pipe", "pipe", "pipe"],
+                windowsHide: true,
+                env: process.env,
+            });
+        }
+        catch (e) {
+            resolve({ kind: "no-spawn", detail: e instanceof Error ? e.message : String(e) });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let spawned = false;
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(outcome);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch { }
+            if (process.platform !== "win32") {
+                setTimeout(() => {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch { }
+                }, 2000).unref();
+            }
+            finish({ kind: "failed", detail: `timeout after ${timeoutMs}ms` });
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.once("spawn", () => {
+            spawned = true;
+        });
+        child.once("error", (err) => {
+            // Pre-spawn error = interpreter not runnable (walk advances). A late
+            // error is folded into the close-path outcome instead.
+            if (!spawned) {
+                finish({ kind: "no-spawn", detail: err instanceof Error ? err.message : String(err) });
+            }
+        });
+        if (child.stdin) {
+            // EPIPE if the script exits without reading stdin — never crash on it.
+            child.stdin.on("error", () => { });
+            if (stdinText !== null)
+                child.stdin.write(stdinText);
+            child.stdin.end();
+        }
+        child.on("close", (code) => {
+            if (code !== 0) {
+                finish({
+                    kind: "failed",
+                    detail: `exit code ${code}${stderr.trim() ? `; stderr: ${stderr.trim()}` : ""}`,
+                });
+                return;
+            }
+            if (stdout.trim() === "") {
+                finish({ kind: "failed", detail: "empty stdout" });
+                return;
+            }
+            finish({ kind: "ok", stdout });
+        });
+    });
+}
+/** Env-check stdout shape: {"ready": bool, "load-rules": bool} (hyphenated key), extra keys ignored. */
+function parseEnvCheck(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const ready = parsed["ready"];
+    const loadRules = parsed["load-rules"];
+    if (typeof ready !== "boolean" || typeof loadRules !== "boolean")
+        return null;
+    return { ready, loadRules };
+}
+// Per-model effort legality, derived from the exported launch enums. Own
+// membership checks on purpose: resolveEffort (effort.ts) has a lenient default
+// that silently coerces unknown efforts to "high", so buildCommand throwing can
+// NOT be relied on to reject bad ruleset output.
+const SONNET_EFFORTS = LAUNCH_EFFORTS.filter((e) => e !== "ultracode");
+const CODEX_EFFORTS = LAUNCH_EFFORTS.filter((e) => e !== "ultracode" && e !== "max");
+function effortAllowed(model, effort) {
+    if (model === "haiku")
+        return effort === HAIKU_EFFORT;
+    if (model === "sonnet")
+        return SONNET_EFFORTS.includes(effort);
+    if (model === "opus" || model === "opus-4-8") {
+        return LAUNCH_EFFORTS.includes(effort);
+    }
+    // gpt-5.5 (the only remaining launch model).
+    return CODEX_EFFORTS.includes(effort);
+}
+/**
+ * Strict validation of routing-mode stdout: a bare JSON array of candidate
+ * objects, validated against the STATIC launch enums (not raw table rows — the
+ * returned list is consumed verbatim by the attempt loop, so every entry must
+ * be launchable; explicit mode has no table at all).
+ *
+ * Per element: string provider/model/effort; provider ∈ {claude, codex};
+ * model ∈ launch enum; provider↔model legality (claude↔{haiku,sonnet,opus,
+ * opus-4-8}, codex↔gpt-5.5); per-model effort legality incl. haiku→"none".
+ * Extra keys (incl. rank) are ignored on output; duplicates are allowed (the
+ * attempt loop just tries them in order). An EMPTY array is VALID — it is the
+ * limit case of the allowed filter operation and means "veto the launch"
+ * (index.ts owns the veto error). The error string here is for server-side
+ * stderr logging only.
+ */
+export function validateRulesetOutput(raw) {
+    if (!Array.isArray(raw)) {
+        return { ok: false, error: "output must be a bare JSON array of candidate objects" };
+    }
+    const candidates = [];
+    for (let i = 0; i < raw.length; i++) {
+        const el = raw[i];
+        if (!el || typeof el !== "object" || Array.isArray(el)) {
+            return { ok: false, error: `candidate ${i}: not an object` };
+        }
+        const entry = el;
+        const provider = entry.provider;
+        const model = entry.model;
+        const effort = entry.effort;
+        if (typeof provider !== "string" || typeof model !== "string" || typeof effort !== "string") {
+            return { ok: false, error: `candidate ${i}: provider, model, and effort must be strings` };
+        }
+        if (provider !== "claude" && provider !== "codex") {
+            return { ok: false, error: `candidate ${i}: unknown provider ${provider}` };
+        }
+        if (!LAUNCH_MODELS.includes(model)) {
+            return { ok: false, error: `candidate ${i}: unknown model ${model}` };
+        }
+        if (provider === "claude" && model === "gpt-5.5") {
+            return { ok: false, error: `candidate ${i}: claude does not support gpt-5.5` };
+        }
+        if (provider === "codex" && model !== "gpt-5.5") {
+            return { ok: false, error: `candidate ${i}: codex only supports gpt-5.5, got ${model}` };
+        }
+        if (!effortAllowed(model, effort)) {
+            return { ok: false, error: `candidate ${i}: effort ${effort} is not valid for ${provider}/${model}` };
+        }
+        candidates.push({ provider: provider, model, effort });
+    }
+    return { ok: true, candidates };
+}
+/**
+ * Per-process gate factory (deadlock.ts pattern: closure state, instantiated
+ * once at module scope in index.ts). The opts are injection seams for tests
+ * only; production uses the defaults.
+ */
+export function createRulesetGate(opts = {}) {
+    const scriptPath = opts.scriptPath ?? defaultScaffoldPath();
+    const env = opts.env ?? process.env;
+    const platform = (opts.platform ?? process.platform);
+    const timeoutMs = opts.timeoutMs ?? RULESET_TIMEOUT_MS;
+    const exec = opts.exec ?? execRuleset;
+    let state = "unknown";
+    // Remembered ONLY when the env-check latches success, so a failed walk is
+    // repeated in full on the next launch (admin may fix PATH without a restart).
+    let interpreter = null;
+    async function ensureReady() {
+        if (state !== "unknown") {
+            return { ok: true, active: state === "enabled" };
+        }
+        try {
+            ensureScaffold(scriptPath);
+        }
+        catch (e) {
+            console.error(`[ruleset] scaffold recreate failed: ${e instanceof Error ? e.message : String(e)}`);
+            return { ok: false };
+        }
+        const walk = interpreterCandidates(env, platform);
+        for (const candidate of walk) {
+            const outcome = await exec(candidate, scriptPath, [], null, timeoutMs);
+            if (outcome.kind === "no-spawn") {
+                continue; // interpreter not present/runnable — walk advances.
+            }
+            // First candidate that spawned IS the interpreter for this execution;
+            // its script-level failure is a ruleset failure, not a cue to walk on.
+            if (outcome.kind === "failed") {
+                console.error(`[ruleset] env-check failed (${candidate}): ${outcome.detail}`);
+                return { ok: false };
+            }
+            const parsed = parseEnvCheck(outcome.stdout);
+            if (parsed === null) {
+                console.error(`[ruleset] env-check output is not {"ready":bool,"load-rules":bool} (${candidate})`);
+                return { ok: false };
+            }
+            if (!parsed.ready) {
+                console.error(`[ruleset] env-check reported ready:false (${candidate})`);
+                return { ok: false };
+            }
+            interpreter = candidate;
+            state = parsed.loadRules ? "enabled" : "disabled";
+            return { ok: true, active: state === "enabled" };
+        }
+        console.error(`[ruleset] no python interpreter found (tried: ${walk.join(", ")})`);
+        return { ok: false };
+    }
+    async function applyRules(payload) {
+        try {
+            ensureScaffold(scriptPath);
+        }
+        catch (e) {
+            console.error(`[ruleset] scaffold recreate failed: ${e instanceof Error ? e.message : String(e)}`);
+            return { ok: false };
+        }
+        if (interpreter === null) {
+            // Defensive: applyRules is only reachable after ensureReady latched "enabled".
+            console.error("[ruleset] applyRules called before a successful env-check");
+            return { ok: false };
+        }
+        const outcome = await exec(interpreter, scriptPath, ["route"], JSON.stringify(payload), timeoutMs);
+        if (outcome.kind !== "ok") {
+            console.error(`[ruleset] routing mode failed: ${outcome.detail}`);
+            return { ok: false };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(outcome.stdout);
+        }
+        catch {
+            console.error("[ruleset] routing mode stdout is not valid JSON");
+            return { ok: false };
+        }
+        const validated = validateRulesetOutput(parsed);
+        if (!validated.ok) {
+            console.error(`[ruleset] invalid routing output: ${validated.error}`);
+            return { ok: false };
+        }
+        return { ok: true, candidates: validated.candidates };
+    }
+    return { ensureReady, applyRules };
+}