onto-mcp 0.3.0

package/dist/core-runtime/cli/review-invoke-auto-resolution.test.js

@@ -0,0 +1,268 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { resolveExecutionRealizationHandoff, detectClaudeCodeHost, detectCodexAvailable, } from "./review-invoke.js";
+// ─── Helpers ───
+const originalEnv = { ...process.env };
+function clearEnv() {
+    delete process.env.CLAUDECODE;
+    // Don't touch PATH/HOME globally — we override them in tests that need to.
+}
+function restoreEnv() {
+    for (const k of Object.keys(process.env)) {
+        if (!(k in originalEnv))
+            delete process.env[k];
+    }
+    for (const [k, v] of Object.entries(originalEnv)) {
+        process.env[k] = v;
+    }
+}
+function createTmpHome() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "onto-auto-resolution-test-"));
+    fs.mkdirSync(path.join(home, ".codex"), { recursive: true });
+    return {
+        home,
+        cleanup: () => fs.rmSync(home, { recursive: true, force: true }),
+    };
+}
+// ─── detectClaudeCodeHost ───
+describe("detectClaudeCodeHost", () => {
+    beforeEach(() => {
+        clearEnv();
+    });
+    afterEach(() => {
+        restoreEnv();
+    });
+    it("returns true when CLAUDECODE=1", () => {
+        process.env.CLAUDECODE = "1";
+        expect(detectClaudeCodeHost()).toBe(true);
+    });
+    it("returns false when CLAUDECODE unset", () => {
+        expect(detectClaudeCodeHost()).toBe(false);
+    });
+    it("returns false when CLAUDECODE=0 or other value", () => {
+        process.env.CLAUDECODE = "0";
+        expect(detectClaudeCodeHost()).toBe(false);
+        process.env.CLAUDECODE = "true";
+        expect(detectClaudeCodeHost()).toBe(false);
+    });
+});
+// ─── detectCodexAvailable ───
+describe("detectCodexAvailable", () => {
+    let tmp = null;
+    const originalPath = process.env.PATH;
+    const originalHome = process.env.HOME;
+    beforeEach(() => {
+        tmp = createTmpHome();
+        process.env.HOME = tmp.home;
+    });
+    afterEach(() => {
+        if (tmp)
+            tmp.cleanup();
+        tmp = null;
+        if (originalPath !== undefined)
+            process.env.PATH = originalPath;
+        if (originalHome !== undefined)
+            process.env.HOME = originalHome;
+    });
+    it("returns false when codex binary not on PATH", () => {
+        const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-empty-path-"));
+        process.env.PATH = emptyDir;
+        try {
+            expect(detectCodexAvailable()).toBe(false);
+        }
+        finally {
+            fs.rmSync(emptyDir, { recursive: true, force: true });
+        }
+    });
+    it("returns false when binary on PATH but auth.json missing", () => {
+        const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-bin-"));
+        const fakeCodex = path.join(binDir, "codex");
+        fs.writeFileSync(fakeCodex, "#!/bin/sh\necho fake\n");
+        fs.chmodSync(fakeCodex, 0o755);
+        process.env.PATH = binDir;
+        // HOME has tmp with .codex dir but no auth.json
+        try {
+            expect(detectCodexAvailable()).toBe(false);
+        }
+        finally {
+            fs.rmSync(binDir, { recursive: true, force: true });
+        }
+    });
+    it("returns true when both binary and auth.json exist", () => {
+        const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-bin-"));
+        const fakeCodex = path.join(binDir, "codex");
+        fs.writeFileSync(fakeCodex, "#!/bin/sh\necho fake\n");
+        fs.chmodSync(fakeCodex, 0o755);
+        process.env.PATH = binDir;
+        fs.writeFileSync(path.join(tmp.home, ".codex", "auth.json"), "{}");
+        try {
+            expect(detectCodexAvailable()).toBe(true);
+        }
+        finally {
+            fs.rmSync(binDir, { recursive: true, force: true });
+        }
+    });
+});
+// ─── resolveExecutionRealizationHandoff ───
+describe("resolveExecutionRealizationHandoff", () => {
+    let tmp = null;
+    const originalPath = process.env.PATH;
+    const originalHome = process.env.HOME;
+    beforeEach(() => {
+        clearEnv();
+        tmp = createTmpHome();
+        process.env.HOME = tmp.home;
+        // Default: empty PATH (codex not available) unless test sets it.
+        process.env.PATH = "/tmp/none-existing-dir";
+    });
+    afterEach(() => {
+        if (tmp)
+            tmp.cleanup();
+        tmp = null;
+        if (originalPath !== undefined)
+            process.env.PATH = originalPath;
+        else
+            delete process.env.PATH;
+        if (originalHome !== undefined)
+            process.env.HOME = originalHome;
+        restoreEnv();
+    });
+    it("E1 explicit --codex → self", () => {
+        const out = resolveExecutionRealizationHandoff({
+            explicitCodex: true,
+            prepareOnly: false,
+            ontoConfig: {},
+        });
+        expect(out.type).toBe("self");
+        if (out.type === "self") {
+            expect(out.profile.host_runtime).toBe("codex");
+        }
+    });
+    it("E1b prepare-only on Claude host → self with Claude profile (artifact seam)", () => {
+        // coordinator-state-machine calls reviewPrepareOnly(--prepare-only) from within
+        // a Claude Code session; it must receive the Claude profile so prepared session
+        // artifacts get recorded as agent-teams+claude, not subagent+codex. This is the
+        // artifact seam fix (review consensus #1, 2026-04-16).
+        process.env.CLAUDECODE = "1";
+        const out = resolveExecutionRealizationHandoff({
+            explicitCodex: false,
+            prepareOnly: true,
+            ontoConfig: {},
+        });
+        expect(out.type).toBe("self");
+        if (out.type === "self") {
+            expect(out.profile.host_runtime).toBe("claude");
+            expect(out.profile.execution_realization).toBe("agent-teams");
+        }
+    });
+    it("E2 env ONTO_HOST_RUNTIME=claude → coordinator_start with agent-teams default", () => {
+        process.env.ONTO_HOST_RUNTIME = "claude";
+        const out = resolveExecutionRealizationHandoff({
+            explicitCodex: false,
+            prepareOnly: false,
+            ontoConfig: {},
+        });
+        expect(out.type).toBe("coordinator_start");
+        if (out.type === "coordinator_start") {
+            expect(out.profile.execution_realization).toBe("agent-teams");
+        }
+    });
+    it("E2c env ONTO_HOST_RUNTIME=codex → self", () => {
+        process.env.ONTO_HOST_RUNTIME = "codex";
+        const out = resolveExecutionRealizationHandoff({
+            explicitCodex: false,
+            prepareOnly: false,
+            ontoConfig: {},
+        });
+        expect(out.type).toBe("self");
+        if (out.type === "self") {
+            expect(out.profile.host_runtime).toBe("codex");
+        }
+    });
+    it("E3 auto + CLAUDECODE=1 → coordinator_start with agent-teams", () => {
+        process.env.CLAUDECODE = "1";
+        const out = resolveExecutionRealizationHandoff({
+            explicitCodex: false,
+            prepareOnly: false,
+            ontoConfig: {},
+        });
+        expect(out.type).toBe("coordinator_start");
+        if (out.type === "coordinator_start") {
+            expect(out.profile.execution_realization).toBe("agent-teams");
+        }
+    });
+    it("E4 auto + codex available + no CLAUDECODE → self", () => {
+        const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-bin-"));
+        const fakeCodex = path.join(binDir, "codex");
+        fs.writeFileSync(fakeCodex, "#!/bin/sh\n");
+        fs.chmodSync(fakeCodex, 0o755);
+        process.env.PATH = binDir;
+        fs.writeFileSync(path.join(tmp.home, ".codex", "auth.json"), "{}");
+        try {
+            const out = resolveExecutionRealizationHandoff({
+                explicitCodex: false,
+                prepareOnly: false,
+                ontoConfig: {},
+            });
+            expect(out.type).toBe("self");
+            if (out.type === "self") {
+                expect(out.profile.host_runtime).toBe("codex");
+            }
+        }
+        finally {
+            fs.rmSync(binDir, { recursive: true, force: true });
+        }
+    });
+    it("E5 auto + both CLAUDECODE and codex available → stay-in-host (Claude wins)", () => {
+        process.env.CLAUDECODE = "1";
+        const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "onto-bin-"));
+        const fakeCodex = path.join(binDir, "codex");
+        fs.writeFileSync(fakeCodex, "#!/bin/sh\n");
+        fs.chmodSync(fakeCodex, 0o755);
+        process.env.PATH = binDir;
+        fs.writeFileSync(path.join(tmp.home, ".codex", "auth.json"), "{}");
+        try {
+            const out = resolveExecutionRealizationHandoff({
+                explicitCodex: false,
+                prepareOnly: false,
+                ontoConfig: {},
+            });
+            expect(out.type).toBe("coordinator_start");
+            if (out.type === "coordinator_start") {
+                expect(out.profile.execution_realization).toBe("agent-teams");
+            }
+        }
+        finally {
+            fs.rmSync(binDir, { recursive: true, force: true });
+        }
+    });
+    it("E6 auto + nothing available → no_host", () => {
+        const out = resolveExecutionRealizationHandoff({
+            explicitCodex: false,
+            prepareOnly: false,
+            ontoConfig: {},
+        });
+        expect(out).toEqual({ type: "no_host" });
+    });
+    it("E7 external_http_provider=litellm → ts_inline_http self-execute", () => {
+        // LiteLLM wiring is live via the P4 auto-detection branch —
+        // `resolveExecutionPlan` sees `external_http_provider` set, routes to
+        // the S1 external HTTP path, and the handoff returns `self` so the
+        // invoking process runs the executor in-band.
+        const out = resolveExecutionRealizationHandoff({
+            explicitCodex: false,
+            prepareOnly: false,
+            ontoConfig: {
+                external_http_provider: "litellm",
+                llm_base_url: "http://proxy.local",
+                litellm: { model: "llama-8b" },
+            },
+        });
+        expect(out).toEqual({
+            type: "self",
+            profile: { execution_realization: "ts_inline_http", host_runtime: "litellm" },
+        });
+    });
+});

package/dist/core-runtime/cli/review-invoke-coordinator-topology.test.js

@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { tryResolveTopologyForHandoff } from "./review-invoke.js";
+// ---------------------------------------------------------------------------
+// Coordinator handoff descriptor invariants (P9.3, 2026-04-21):
+//
+// (1) `tryResolveTopologyForHandoff` attempts axis-first resolution
+//     unconditionally; the former opt-in gate (config.review presence)
+//     is gone. Every review invocation that reaches a reachable host
+//     ships a descriptor.
+// (2) Resolvable topology → non-null descriptor with all 6 static
+//     attributes, minus plan_trace (handoff payload stays compact).
+// (3) Descriptor is JSON-serializable with deterministic shape —
+//     downstream coordinator consumers parse it unmodified.
+// (4) Returns null ONLY when ontoConfig is undefined (defensive) or
+//     the resolver itself returns `no_host` (axis + main_native
+//     degrade both failed, i.e. no Claude or Codex host reachable).
+// ---------------------------------------------------------------------------
+const ORIGINAL_ENV = { ...process.env };
+function restoreEnv() {
+    for (const k of Object.keys(process.env)) {
+        if (!(k in ORIGINAL_ENV))
+            delete process.env[k];
+    }
+    for (const [k, v] of Object.entries(ORIGINAL_ENV)) {
+        process.env[k] = v;
+    }
+}
+describe("tryResolveTopologyForHandoff — null paths", () => {
+    beforeEach(() => {
+        delete process.env.CLAUDECODE;
+        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    });
+    afterEach(restoreEnv);
+    it("undefined ontoConfig → null (defensive guard)", () => {
+        expect(tryResolveTopologyForHandoff(undefined)).toBeNull();
+    });
+    it("no host signals → null (resolver returns no_host)", () => {
+        // No CLAUDECODE, no codex session. With no reachable host even the
+        // main_native degrade cannot map — resolver returns no_host and the
+        // handoff payload omits the topology field.
+        expect(tryResolveTopologyForHandoff({})).toBeNull();
+    });
+    it("review block declares unreachable subagent → null (axis + degrade both fail)", () => {
+        // No CLAUDECODE, no experimental, no codex, no litellm. Axis-first
+        // derives `cc-teams-codex-subprocess` which fails requirements; the
+        // main_native degrade then fails to map (no host) → no_host.
+        expect(tryResolveTopologyForHandoff({
+            review: {
+                subagent: { provider: "codex", model_id: "gpt-5.4" },
+            },
+        })).toBeNull();
+    });
+});
+describe("tryResolveTopologyForHandoff — always-on axis-first (P9.3)", () => {
+    beforeEach(() => {
+        delete process.env.CLAUDECODE;
+        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    });
+    afterEach(restoreEnv);
+    it("plain CC session without review block → cc-main-agent-subagent descriptor via main_native degrade", () => {
+        // P9.3 invariant: every review invocation produces a descriptor
+        // when a host is reachable, even without an explicit `review:`
+        // axis block. Main_native degrade maps to cc-main-agent-subagent
+        // under CLAUDECODE=1.
+        process.env.CLAUDECODE = "1";
+        const descriptor = tryResolveTopologyForHandoff({});
+        expect(descriptor).not.toBeNull();
+        expect(descriptor.id).toBe("cc-main-agent-subagent");
+    });
+    it("empty `review: {}` ALSO resolves via main_native degrade under CC host", () => {
+        // The former M2 opt-in guard is gone — empty review blocks are no
+        // longer distinct from absent ones at dispatch time. Both produce
+        // the same cc-main-agent-subagent descriptor on CLAUDECODE=1.
+        process.env.CLAUDECODE = "1";
+        const descriptor = tryResolveTopologyForHandoff({
+            review: {},
+        });
+        expect(descriptor).not.toBeNull();
+        expect(descriptor.id).toBe("cc-main-agent-subagent");
+    });
+});
+describe("tryResolveTopologyForHandoff — resolved descriptor", () => {
+    beforeEach(() => {
+        delete process.env.CLAUDECODE;
+        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    });
+    afterEach(restoreEnv);
+    it("cc-main-agent-subagent resolves to descriptor with 6 static attributes", () => {
+        process.env.CLAUDECODE = "1";
+        const descriptor = tryResolveTopologyForHandoff({
+            review: { subagent: { provider: "main-native" } },
+        });
+        expect(descriptor).not.toBeNull();
+        expect(descriptor.id).toBe("cc-main-agent-subagent");
+        expect(descriptor.teamlead_location).toBe("onto-main");
+        expect(descriptor.lens_spawn_mechanism).toBe("claude-agent-tool");
+        expect(descriptor.max_concurrent_lenses).toBe(10);
+        expect(descriptor.transport_rank).toBe("S2");
+        expect(descriptor.deliberation_channel).toBe("synthesizer-only");
+    });
+    it("cc-teams-lens-agent-deliberation resolves when triple opt-in met", () => {
+        process.env.CLAUDECODE = "1";
+        process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
+        // P9.2 (2026-04-21): deliberation topology is selected through the
+        // `config.review` axis block (`lens_deliberation: sendmessage-a2a`)
+        // + `lens_agent_teams_mode: true` double opt-in.
+        const descriptor = tryResolveTopologyForHandoff({
+            review: {
+                subagent: { provider: "main-native" },
+                lens_deliberation: "sendmessage-a2a",
+            },
+            lens_agent_teams_mode: true,
+        });
+        expect(descriptor).not.toBeNull();
+        expect(descriptor.id).toBe("cc-teams-lens-agent-deliberation");
+        expect(descriptor.deliberation_channel).toBe("sendmessage-a2a");
+        expect(descriptor.lens_spawn_mechanism).toBe("claude-teamcreate-member");
+    });
+    it("descriptor does NOT include plan_trace (compact handoff JSON)", () => {
+        process.env.CLAUDECODE = "1";
+        const descriptor = tryResolveTopologyForHandoff({
+            review: { subagent: { provider: "main-native" } },
+        });
+        expect(descriptor).not.toBeNull();
+        expect(Object.keys(descriptor)).not.toContain("plan_trace");
+    });
+    it("descriptor is JSON round-trip stable", () => {
+        process.env.CLAUDECODE = "1";
+        const descriptor = tryResolveTopologyForHandoff({
+            review: { subagent: { provider: "main-native" } },
+        });
+        const json = JSON.stringify(descriptor);
+        const parsed = JSON.parse(json);
+        expect(parsed).toEqual(descriptor);
+    });
+});

package/dist/core-runtime/cli/review-invoke-resolver-caching.test.js

@@ -0,0 +1,201 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { tryResolveTopologyForHandoff, tryTopologyDerivedExecutor, } from "./review-invoke.js";
+// ---------------------------------------------------------------------------
+// P9.3-m1 Resolver caching invariants (2026-04-21):
+//
+// `runReviewInvokeCli` resolves `resolveExecutionTopology` exactly once
+// per invocation and threads the result as `cached` to 3 downstream
+// consumers. This file protects the cache plumbing from future
+// regressions — a caller that accidentally drops the `cached` argument
+// (reverting to the 3x resolver-call pattern) would re-emit the full
+// `[topology]` STDERR trace, which these tests assert does NOT happen.
+//
+// The `[topology] signals:` line is the most stable counter because
+// `resolveExecutionTopology` emits it exactly once at the very start of
+// each invocation (see execution-topology-resolver.ts:413). When the
+// helpers honour `cached`, they skip the resolver entirely and this
+// line MUST NOT appear.
+// ---------------------------------------------------------------------------
+const FAKE_HOME = "/tmp/fake-onto-home";
+const CACHED_LITELLM_TOPOLOGY = {
+    id: "cc-teams-litellm-sessions",
+    teamlead_location: "claude-teamcreate",
+    lens_spawn_mechanism: "litellm-http",
+    max_concurrent_lenses: 3,
+    transport_rank: "S2",
+    deliberation_channel: "synthesizer-only",
+    plan_trace: ["cached-by-runReviewInvokeCli"],
+};
+const CACHED_CC_MAIN_TOPOLOGY = {
+    id: "cc-main-agent-subagent",
+    teamlead_location: "onto-main",
+    lens_spawn_mechanism: "claude-agent-tool",
+    max_concurrent_lenses: 3,
+    transport_rank: "S0",
+    deliberation_channel: "synthesizer-only",
+    plan_trace: ["cached-by-runReviewInvokeCli"],
+};
+describe("tryResolveTopologyForHandoff — cached topology bypass", () => {
+    const originalEnv = { ...process.env };
+    let stderrSpy;
+    beforeEach(() => {
+        delete process.env.CLAUDECODE;
+        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    });
+    afterEach(() => {
+        stderrSpy.mockRestore();
+        for (const k of Object.keys(process.env)) {
+            if (!(k in originalEnv))
+                delete process.env[k];
+        }
+        for (const [k, v] of Object.entries(originalEnv)) {
+            process.env[k] = v;
+        }
+    });
+    function signalsTraceLines() {
+        return stderrSpy.mock.calls
+            .map((c) => String(c[0]))
+            .filter((l) => l.startsWith("[topology] signals:"));
+    }
+    it("cached=ExecutionTopology → descriptor returned without re-running resolver", () => {
+        const descriptor = tryResolveTopologyForHandoff({}, CACHED_LITELLM_TOPOLOGY);
+        expect(descriptor).not.toBeNull();
+        expect(descriptor.id).toBe("cc-teams-litellm-sessions");
+        expect(descriptor.teamlead_location).toBe("claude-teamcreate");
+        expect(signalsTraceLines()).toHaveLength(0);
+    });
+    it("cached=null → returns null without re-running resolver", () => {
+        const descriptor = tryResolveTopologyForHandoff({}, null);
+        expect(descriptor).toBeNull();
+        expect(signalsTraceLines()).toHaveLength(0);
+    });
+    it("cached=undefined → legacy behaviour (resolver runs, emits signals)", () => {
+        // Two-argument call path preserved for test-harness compatibility;
+        // this branch is what existing tests exercise.
+        tryResolveTopologyForHandoff({});
+        expect(signalsTraceLines()).toHaveLength(1);
+    });
+});
+describe("tryTopologyDerivedExecutor — cached topology bypass", () => {
+    const originalEnv = { ...process.env };
+    let stderrSpy;
+    beforeEach(() => {
+        delete process.env.CLAUDECODE;
+        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    });
+    afterEach(() => {
+        stderrSpy.mockRestore();
+        for (const k of Object.keys(process.env)) {
+            if (!(k in originalEnv))
+                delete process.env[k];
+        }
+        for (const [k, v] of Object.entries(originalEnv)) {
+            process.env[k] = v;
+        }
+    });
+    function signalsTraceLines() {
+        return stderrSpy.mock.calls
+            .map((c) => String(c[0]))
+            .filter((l) => l.startsWith("[topology] signals:"));
+    }
+    it("cached=ExecutionTopology (binary-backed) → executor returned without re-running resolver", () => {
+        const result = tryTopologyDerivedExecutor({ llm_base_url: "http://localhost:4000" }, FAKE_HOME, CACHED_LITELLM_TOPOLOGY);
+        expect(result).not.toBeNull();
+        expect(result.bin).toBe("node");
+        expect(result.args[0]).toContain("inline-http-review-unit-executor.js");
+        expect(signalsTraceLines()).toHaveLength(0);
+    });
+    it("cached=ExecutionTopology (no standalone binary) → null without re-running resolver", () => {
+        const result = tryTopologyDerivedExecutor({}, FAKE_HOME, CACHED_CC_MAIN_TOPOLOGY);
+        expect(result).toBeNull();
+        expect(signalsTraceLines()).toHaveLength(0);
+    });
+    it("cached=null → null without re-running resolver", () => {
+        const result = tryTopologyDerivedExecutor({}, FAKE_HOME, null);
+        expect(result).toBeNull();
+        expect(signalsTraceLines()).toHaveLength(0);
+    });
+    it("cached=undefined → legacy behaviour (resolver runs, emits signals)", () => {
+        process.env.CLAUDECODE = "1";
+        tryTopologyDerivedExecutor({}, FAKE_HOME);
+        expect(signalsTraceLines()).toHaveLength(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// Integration-layer invariant: exercise the 3-consumer contract that
+// `runReviewInvokeCli` depends on. The stderr-based tests above prove
+// the helper-level contract; these tests prove the full-dispatch
+// consumer sequence (tryResolveTopologyForHandoff + tryTopologyDerivedExecutor
+// twice — the shape invoked by resolveExecutorConfig for default +
+// synthesize) adds up to ZERO resolver invocations when the cache is
+// threaded. If a future refactor drops the `cached` argument from any
+// consumer, the signals-line count will jump from 0 to 1-or-more and
+// this test will fail — catching the very regression class MINOR-1 of
+// the P9.3-m1 review flagged.
+// ---------------------------------------------------------------------------
+describe("runReviewInvokeCli full-dispatch consumer sequence — invariant", () => {
+    const originalEnv = { ...process.env };
+    let stderrSpy;
+    beforeEach(() => {
+        delete process.env.CLAUDECODE;
+        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    });
+    afterEach(() => {
+        stderrSpy.mockRestore();
+        for (const k of Object.keys(process.env)) {
+            if (!(k in originalEnv))
+                delete process.env[k];
+        }
+        for (const [k, v] of Object.entries(originalEnv)) {
+            process.env[k] = v;
+        }
+    });
+    function signalsTraceCount() {
+        return stderrSpy.mock.calls
+            .map((c) => String(c[0]))
+            .filter((l) => l.startsWith("[topology] signals:")).length;
+    }
+    it("3 consumers with shared cachedTopology → resolver runs 0 times", () => {
+        // Simulate the runReviewInvokeCli full-dispatch sequence:
+        // 1. runReviewInvokeCli resolves once at the top (we fabricate the
+        //    result here as `cachedTopology` — NOT included in the spy count).
+        // 2. tryResolveTopologyForHandoff(config, cachedTopology) — coordinator_start
+        //    path would have called this but it returns earlier; included here
+        //    for completeness of the 3-consumer contract.
+        // 3. tryTopologyDerivedExecutor ×2 (default + synthesize via
+        //    resolveExecutorConfig).
+        const cachedTopology = CACHED_LITELLM_TOPOLOGY;
+        const config = { llm_base_url: "http://localhost:4000" };
+        tryResolveTopologyForHandoff(config, cachedTopology);
+        tryTopologyDerivedExecutor(config, FAKE_HOME, cachedTopology);
+        tryTopologyDerivedExecutor(config, FAKE_HOME, cachedTopology);
+        // ZERO resolver calls: cache bypassed all 3 consumers.
+        expect(signalsTraceCount()).toBe(0);
+    });
+    it("regression probe: 3 consumers with cached=undefined → resolver runs 3 times", () => {
+        // This is the PRE-fix behaviour. If someone accidentally reverts the
+        // caching (drops the `cached` argument from all 3 consumers), the
+        // count would be 3 — proving the test catches the exact regression.
+        process.env.CLAUDECODE = "1";
+        const config = { llm_base_url: "http://localhost:4000" };
+        tryResolveTopologyForHandoff(config);
+        tryTopologyDerivedExecutor(config, FAKE_HOME);
+        tryTopologyDerivedExecutor(config, FAKE_HOME);
+        expect(signalsTraceCount()).toBe(3);
+    });
+    it("3 consumers with cachedTopology=null → resolver runs 0 times, all return null", () => {
+        // `null` propagation: all 3 consumers see cached=null and short-circuit
+        // without invoking the resolver.
+        const config = { llm_base_url: "http://localhost:4000" };
+        const descriptor = tryResolveTopologyForHandoff(config, null);
+        const exec1 = tryTopologyDerivedExecutor(config, FAKE_HOME, null);
+        const exec2 = tryTopologyDerivedExecutor(config, FAKE_HOME, null);
+        expect(descriptor).toBeNull();
+        expect(exec1).toBeNull();
+        expect(exec2).toBeNull();
+        expect(signalsTraceCount()).toBe(0);
+    });
+});