deepdebug-local-agent 1.9.0 → 1.11.0

package/test/la-protocol-v2/agent2-supervisor.test.js

@@ -0,0 +1,185 @@
+// F3-08c (Local Agent half): the supervised mode (LOCAL_AGENT_AGENT2_CMD). A fake agent2 runs as a real PROCESS (helpers/fake-agent2-cli.js) started by the runner:
+// minimal environment, a new token at every start, health, crash and bounded restarts, stop with the link. Unit tests of the supervisor (health failure, RSS, stop)
+// use an injected spawn so they are fast and exact. NOT the real agent2: agent2-real-e2e.test.js does that, opt-in.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { closeAllFakes, okJson } from "./helpers/fake-llm.js";
+import { agent2Rig, CANARIES, TENANT, waitFor } from "./helpers/agent2-rig.js";
+import { createAgent2Supervisor, agent2ChildEnv } from "../../src/la-protocol-v2/jobs/agent2/supervisor.js";
+import { resolveAgent2RunnerConfig } from "../../src/la-protocol-v2/jobs/agent2/config.js";
+
+after(closeAllFakes);
+
+const HOME_TMP = fs.mkdtempSync(path.join(os.tmpdir(), "a2sup-home-"));   // the pidfile of a unit-tested supervisor goes here, never to the real ~/.deepdebug
+after(() => fs.rmSync(HOME_TMP, { recursive: true, force: true }));
+
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+const terminal = (r, jobId) => r.frames(jobId, "job.event").at(-1).payload;
+const childEnvOf = async (port) => (await (await fetch(`http://127.0.0.1:${port}/local/v1/_env`)).json());
+
+test("spawn: the process is started at the first job (not at boot), serves it, gets a MINIMAL environment, and stops with the link", async () => {
+    const SECRETS = { GITHUB_TOKEN: "ghp-CANARY-ENV-1", AWS_SECRET_ACCESS_KEY: "aws-CANARY-ENV-2", ANTHROPIC_API_KEY: "sk-CANARY-ENV-3", MY_TOKEN: "my-CANARY-ENV-4", LOCAL_AGENT_SIGNING_PUBLIC_KEYS: "kid=CANARY5", PLAIN_VAR: "plain-CANARY-6", JAVA_OPTS: "-Xms64m", LOCAL_AGENT_TOKEN: "la-token-CANARY-7-with-32-characters!!", SSH_AUTH_SOCK: "/tmp/ssh-agent.sock" };
+    const r = await agent2Rig({ spawn: {}, scenario: "ok_pr", env: { ...SECRETS, LOCAL_AGENT_AGENT2_ENV_PASSTHROUGH: "JAVA_OPTS,MY_TOKEN,not a name", LOCAL_AGENT_AGENT2_MAX_HEAP_MB: "512", LOCAL_AGENT_AGENT2_LA_URL: "http://127.0.0.1:5055" } });
+    assert.equal(r.link.agent2.supervisor.pid, null, "nothing runs at boot");
+    const a = r.assign();
+    assert.equal((await a.acked()).status, "accepted");
+    await r.done(a.p.jobId);
+    assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "pr_opened");
+    const pid = r.link.agent2.supervisor.pid;
+    assert.ok(pid && alive(pid));
+    // the model was reached only through the bridge of this agent
+    assert.equal(r.fakeLlm.requests.length, 1);
+    assert.equal(r.fakeLlm.requests[0].headers.authorization, `Bearer ${r.key}`);
+    // the environment the child got: an allowlist + what the runner sets
+    const e = await childEnvOf(r.fake.port);
+    for (const k of ["AGENT2_LOCAL_MODE", "AGENT2_LOCAL_BIND", "AGENT2_LOCAL_PORT", "AGENT2_LOCAL_API_TOKEN", "AGENT2_LOCAL_TENANT_ID", "AGENT2_LLM_BASE_URL", "AGENT2_LA_WORKSPACE_URL", "AGENT2_LA_CALLBACK_URL", "AGENT2_LA_CALLBACK_TOKEN", "PATH", "HOME", "JAVA_OPTS", "SSH_AUTH_SOCK"]) assert.ok(k in e.values, `missing ${k}`);
+    assert.equal(e.values.AGENT2_LOCAL_TENANT_ID, TENANT);
+    assert.equal(e.values.AGENT2_LOCAL_BIND, "127.0.0.1");
+    assert.equal(e.values.AGENT2_LLM_BASE_URL, `${r.link.agent2.bridge.baseUrl}/v1`, "the model is the loopback bridge, not the AI gateway");
+    assert.ok(e.values.AGENT2_LOCAL_API_TOKEN.length >= 32);
+    // agent2 reaches this agent's /workspace API THROUGH the bridge (which signs for it): the "workspace token" it holds is the bridge's, never LOCAL_AGENT_TOKEN
+    assert.equal(e.values.AGENT2_LA_WORKSPACE_URL, r.link.agent2.bridge.baseUrl, "the /workspace door is the bridge, not the LA's API");
+    assert.equal(e.values.AGENT2_LA_WORKSPACE_TOKEN, e.values.AGENT2_LA_CALLBACK_TOKEN, "one credential, the bridge's");
+    assert.notEqual(e.values.AGENT2_LA_WORKSPACE_TOKEN, SECRETS.LOCAL_AGENT_TOKEN);
+    assert.equal(e.values.DEEPDEBUG_POLICYGATE_TIMEOUT_MS, "13000", "agent2 waits longer than the channel's 10 s");
+    // the pidfile names the child while it runs (so a restart of THIS agent can end an orphan) and is gone when it stops
+    const rec = JSON.parse(fs.readFileSync(r.pidFile, "utf8"));
+    assert.equal(rec.pid, pid);
+    assert.equal(e.values.JAVA_TOOL_OPTIONS, "-Xmx512m");
+    for (const k of ["GITHUB_TOKEN", "AWS_SECRET_ACCESS_KEY", "ANTHROPIC_API_KEY", "MY_TOKEN", "LOCAL_AGENT_SIGNING_PUBLIC_KEYS", "PLAIN_VAR", "LOCAL_AGENT_TOKEN", "LOCAL_AGENT_RUNNER", "LOCAL_AGENT_LLM_KEY", "LOCAL_AGENT_DLP_MODE"]) assert.ok(!(k in e.values), `leaked into the child: ${k}`);
+    const dump = JSON.stringify(e.values);
+    for (const v of [r.key, "ghp-CANARY-ENV-1", "aws-CANARY-ENV-2", "sk-CANARY-ENV-3", "my-CANARY-ENV-4", "CANARY5", "plain-CANARY-6", "la-token-CANARY-7"]) assert.ok(!dump.includes(v), `value leaked: ${v}`);
+    assert.ok(r.logs.some((l) => /not a plain variable name/.test(l)));
+    // nothing the child printed (it is drained and dropped) nor its token is in the output of this agent
+    const all = r.everything();
+    assert.ok(!all.includes(e.values.AGENT2_LOCAL_API_TOKEN) && !all.includes(e.values.AGENT2_LA_CALLBACK_TOKEN));
+    // stops with the link
+    r.link.close();
+    await waitFor(() => !alive(pid), 8000);
+    await waitFor(() => !fs.existsSync(r.pidFile), 3000);
+    await r.stop();
+});
+
+test("spawn: a crash fails the job (infra) and the NEXT job gets a new process with a NEW token; the restart budget is bounded (then `unavailable`, no spawn loop)", async () => {
+    const r = await agent2Rig({ spawn: { args: ["--die-on-job"] }, scenario: "slow", env: { LOCAL_AGENT_AGENT2_MAX_RESTARTS: "1", LOCAL_AGENT_AGENT2_RESTART_BACKOFF_MS: "0", LOCAL_AGENT_AGENT2_STREAM_RECONNECTS: "0" } });
+    const sup = r.link.agent2.supervisor;
+    const tokens = [];
+    const pids = [];
+    for (let i = 0; i < 2; i++) {
+        const a = r.assign();
+        await a.acked();
+        await r.done(a.p.jobId, 10_000);
+        assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["failed", "infra"], `job ${i}`);
+        pids.push(sup.stats.starts);
+    }
+    assert.equal(sup.stats.starts, 2, "one start + one restart");
+    // the third job: the budget (maxRestarts=1 inside the window) is spent
+    const c = r.assign();
+    await c.acked();
+    await r.done(c.p.jobId, 10_000);
+    assert.deepEqual([terminal(r, c.p.jobId).state, terminal(r, c.p.jobId).errorCode], ["failed", "infra"]);
+    assert.equal(sup.stats.starts, 2, "no third process");
+    assert.equal(sup.stats.refusedRestartLimit, 1);
+    assert.ok(r.link.agent2.audit.tail(100).some((x) => x.event === "agent2_unavailable" && x.code === "restart_limit"));
+    void tokens; void pids;
+    await r.stop();
+});
+
+test("spawn: the API token and the callback token differ at every start (nothing from a dead process works)", async () => {
+    const cfg = { ...resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: "x", LOCAL_AGENT_AGENT2_RESTART_BACKOFF_MS: "0" }), healthIntervalMs: 60_000 };
+    const seen = [];
+    const procs = [];
+    const cb = [];
+    const sup = createAgent2Supervisor({ config: cfg, tenantId: TENANT, bridge: { listen: async () => ({ baseUrl: "http://127.0.0.1:1" }), setCallbackToken: (t) => cb.push(t) }, env: { HOME: HOME_TMP }, log: { warn() {}, info() {} },
+        spawnImpl: (cmd, args, opts) => { seen.push(opts.env.AGENT2_LOCAL_API_TOKEN); const p = fakeProc(); procs.push(p); return p; }, fetchImpl: async () => new Response(JSON.stringify({ status: "up" }), { status: 200 }) });
+    await sup.ensureReady();
+    procs[0].exited = true; procs[0].emit("exit", 1, null);
+    assert.equal(sup.state, "down");
+    await sup.ensureReady();
+    assert.equal(seen.length, 2);
+    assert.notEqual(seen[0], seen[1]);
+    assert.ok(seen[0].length >= 43 && seen[1].length >= 43);
+    assert.notEqual(cb[0], cb[1]);
+    await sup.stop();
+});
+
+test("spawn: a process that dies at once or never answers fails the job with infra (no hang), and the start timeout is honoured", async () => {
+    for (const args of [["--die-on-start"], ["--hang"]]) {
+        const r = await agent2Rig({ spawn: { args }, scenario: "no_change", env: { LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "1500" } });
+        const t0 = Date.now();
+        const a = r.assign();
+        await a.acked();
+        await r.done(a.p.jobId, 10_000);
+        assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["failed", "infra"], args[0]);
+        assert.ok(Date.now() - t0 < 6000, args[0]);
+        assert.equal(r.fakeLlm.requests.length, 0);
+        await r.stop();
+        await new Promise((x) => setTimeout(x, 50));
+    }
+});
+
+// ------------------------------------------------------------------------------------------------------ the supervisor, with an injected process
+
+function fakeProc() {
+    const c = new EventEmitter();
+    c.stdout = new EventEmitter(); c.stderr = new EventEmitter(); c.pid = 4242; c.killed = []; c.exited = false;
+    c.kill = (sig) => { c.killed.push(sig); if (sig === "SIGKILL" || sig === "SIGTERM") queueMicrotask(() => { c.exited = true; c.emit("exit", null, sig); }); return true; };
+    return c;
+}
+
+test("supervisor: health probes that keep failing kill the process and mark it down (the next job restarts it); a healthy one is left alone", async () => {
+    let healthy = true;
+    const proc = fakeProc();
+    const cfg = { ...resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: "x", LOCAL_AGENT_AGENT2_HEALTH_INTERVAL_MS: "100", LOCAL_AGENT_AGENT2_HEALTH_FAILURES: "2" }) };
+    cfg.healthIntervalMs = 100;
+    const downs = [];
+    const sup = createAgent2Supervisor({ config: cfg, tenantId: TENANT, bridge: { listen: async () => ({ baseUrl: "http://127.0.0.1:1" }), setCallbackToken() {} }, env: { HOME: HOME_TMP }, log: { warn() {}, info() {} },
+        spawnImpl: () => proc, fetchImpl: async () => new Response(JSON.stringify({ status: healthy ? "up" : "down" }), { status: 200 }) });
+    sup.on("down", (d) => downs.push(d.why));
+    await sup.ensureReady();
+    assert.equal(sup.state, "ready");
+    await new Promise((x) => setTimeout(x, 350));
+    assert.equal(downs.length, 0, "healthy: left alone");
+    healthy = false;
+    await waitFor(() => downs.length === 1, 3000);
+    assert.deepEqual(proc.killed.slice(0, 1), ["SIGKILL"]);
+    assert.equal(sup.state, "down");
+    await sup.stop();
+});
+
+test("supervisor: a process above LOCAL_AGENT_AGENT2_MAX_RSS_BYTES is killed; stop() is SIGTERM first, SIGKILL after the grace", async () => {
+    const proc = fakeProc();
+    const cfg = resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: "x", LOCAL_AGENT_AGENT2_MAX_RSS_BYTES: String(100 * 1024 * 1024) });
+    cfg.healthIntervalMs = 100;
+    const downs = [];
+    const sup = createAgent2Supervisor({ config: cfg, tenantId: TENANT, bridge: { listen: async () => ({ baseUrl: "http://127.0.0.1:1" }), setCallbackToken() {} }, env: { HOME: HOME_TMP }, log: { warn() {}, info() {} },
+        spawnImpl: () => proc, rssOf: async () => 500 * 1024 * 1024, fetchImpl: async () => new Response(JSON.stringify({ status: "up" }), { status: 200 }) });
+    sup.on("down", (d) => downs.push(d.why));
+    await sup.ensureReady();
+    await waitFor(() => downs.includes("rss"), 3000);
+    assert.equal(sup.stats.killedForRss, 1);
+    assert.deepEqual(proc.killed, ["SIGKILL"]);
+
+    const p2 = fakeProc();
+    p2.kill = (sig) => { p2.killed.push(sig); if (sig === "SIGKILL") queueMicrotask(() => p2.emit("exit", null, sig)); return true; };   // ignores SIGTERM
+    const cfg2 = { ...resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: "x", LOCAL_AGENT_AGENT2_STOP_GRACE_MS: "100" }), healthIntervalMs: 60_000, stopGraceMs: 100 };
+    const sup2 = createAgent2Supervisor({ config: cfg2, tenantId: TENANT, bridge: { listen: async () => ({ baseUrl: "http://127.0.0.1:1" }), setCallbackToken() {} }, env: { HOME: HOME_TMP }, log: { warn() {}, info() {} },
+        spawnImpl: () => p2, fetchImpl: async () => new Response(JSON.stringify({ status: "up" }), { status: 200 }) });
+    await sup2.ensureReady();
+    await sup2.stop();
+    assert.deepEqual(p2.killed, ["SIGTERM", "SIGKILL"]);
+});
+
+test("the request cap: a request text longer than the limit is cut on a character boundary before it is handed to agent2; the answer of the model never is", async () => {
+    const r = await agent2Rig({ scenario: "no_change", env: { LOCAL_AGENT_AGENT2_MAX_REQUEST_BYTES: "2048" }, behavior: okJson(CANARIES.answer) });
+    const big = `${CANARIES.request} ` + "ação ".repeat(900);
+    const a = r.assign({ inputs: [{ inline: big.slice(0, 4000), transient: true }] });
+    await a.acked(); await r.done(a.p.jobId);
+    const text = r.fake.jobs.get(a.p.jobId).request.text;
+    assert.ok(Buffer.byteLength(text) <= 2048 && !text.includes("�"));
+    await r.stop();
+});

package/test/la-protocol-v2/agent2-workspace-door.test.js

@@ -0,0 +1,142 @@
+// F3-08c: agent2's calls to the Local Agent's /workspace API go through the bridge, which vouches for them, so the API's signature check can stay on (LOCAL_AGENT_SIGNATURE_MODE=enforce,
+// the default). Before this, agent2 got 401 "unsigned request" from a real LA in enforce mode. In process: the real bridge + runner against the REAL perimeter middleware of the LA
+// (helpers/fake-la-api.js: auth, body parser, signature check) with a FAKE agent2. The real server process is covered by agent2-workspace-real-server.test.js.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import { closeAllFakes } from "./helpers/fake-llm.js";
+import { agent2Rig, TENANT, waitFor } from "./helpers/agent2-rig.js";
+import { startFakeLaApi } from "./helpers/fake-la-api.js";
+import { newKeyPair } from "./helpers/reference-cp.js";
+import { internalSignatureHeaders } from "../../src/utils/request-signing.js";
+
+after(closeAllFakes);
+
+const LA_TOKEN = "la-api-token-CANARY-0123456789abcdef0123456789";
+
+// laUrl is fixed when the runner is built, so the LA API is started first. It needs the CP's public key to verify nothing but the platform's signature: a key pair is made up front
+// (the ReferenceCp of the rig has its own: that one never signs a /workspace request in these tests)
+async function startAll({ laEnv = {}, scenario = "workspace", env = {} } = {}) {
+    const kp = newKeyPair();
+    const la = await startFakeLaApi({ env: laEnv, keyId: "vh-cp-test", publicKeyRaw: kp.publicKeyRaw });
+    const r = await agent2Rig({ scenario, env: { LOCAL_AGENT_AGENT2_LA_URL: la.url, ...(laEnv.LOCAL_AGENT_TOKEN ? { LOCAL_AGENT_TOKEN: laEnv.LOCAL_AGENT_TOKEN } : {}), ...env } });
+    return { r, la, stop: async () => { await r.stop(); await la.close(); } };
+}
+const run = async (r) => { const a = r.assign(); await a.acked(); await r.done(a.p.jobId); return { a, job: r.fake.jobs.get(a.p.jobId) }; };
+
+test("enforce (default): agent2's read_file and write_file pass through the bridge; a request straight to the API without the platform signature is still 401", async () => {
+    const { r, la, stop } = await startAll();
+    const { job } = await run(r);
+    assert.equal(job.record.read.status, 200);
+    assert.equal(job.record.read.json.content, "// hello from the LA");
+    assert.equal(job.record.read.json.root, r.root, "the job's root is what the API sees, whatever agent2 sent");
+    assert.equal(job.record.write.status, 200);
+    assert.equal(job.record.write.json.written, "src/out.txt");
+    const seen = la.requests.filter((q) => q.url.startsWith("/workspace/"));
+    assert.equal(seen.length, 2, "exactly the two calls that carried agent2's token");
+    for (const q of seen) {
+        assert.equal(q.signature.verified, true);
+        assert.equal(q.signature.internal, true, "vouched for by this process");
+        assert.equal(q.signature.tenantId, TENANT);
+        assert.equal(q.signature.workspaceId, "ws-1");
+        assert.equal(q.headers["x-workspace-id"], "ws-1");
+        assert.equal(q.headers["x-agent-token"], undefined, "no LOCAL_AGENT_TOKEN configured: none sent");
+        assert.equal(q.headers["x-vh-internal"].length, internalSignatureHeaders()["X-VH-Internal"].length);
+        assert.equal(q.headers.authorization, undefined);
+    }
+    // the same API, not through the bridge
+    for (const [name, headers] of [["no signature", {}], ["agent2's token", { "x-agent-token": r.callbackToken }], ["a guessed internal marker", { "x-vh-internal": internalSignatureHeaders()["X-VH-Internal"].replace(/./g, "a") }],
+        ["tenant header alone", { "x-vh-tenant-id": TENANT, "x-vh-workspace-id": "ws-1" }]]) {
+        const res = await fetch(`${la.url}/workspace/file-content?path=a`, { headers });
+        assert.equal(res.status, 401, name);
+        assert.equal((await res.json()).reason, "unsigned request", name);
+    }
+    assert.equal(la.requests.filter((q) => q.url.startsWith("/workspace/")).length, 2, "none of the refused calls reached a route");
+    await stop();
+});
+
+test("with LOCAL_AGENT_TOKEN the bridge adds the API's X-Agent-Token itself; agent2 never holds it; the API still refuses a caller without it", async () => {
+    const { r, la, stop } = await startAll({ laEnv: { LOCAL_AGENT_TOKEN: LA_TOKEN } });
+    const { job } = await run(r);
+    assert.equal(job.record.read.status, 200);
+    assert.equal(job.record.write.status, 200);
+    for (const q of la.requests.filter((x) => x.url.startsWith("/workspace/"))) assert.equal(q.headers["x-agent-token"], LA_TOKEN);
+    assert.equal((await fetch(`${la.url}/workspace/file-content?path=a`)).status, 401, "no X-Agent-Token");
+    assert.equal((await fetch(`${la.url}/workspace/file-content?path=a`, { headers: { "x-agent-token": LA_TOKEN } })).status, 401, "token but no signature");
+    const dump = r.everything();
+    assert.ok(!dump.includes(LA_TOKEN) && !JSON.stringify(job.record).includes(LA_TOKEN), "the API token is in no log, audit, stat or answer");
+    await stop();
+});
+
+test("the door: agent2's token opens it; no token / a wrong token / the LLM token do not; only /workspace paths; no traversal; the job's root only; methods and sizes bounded", async () => {
+    const { r, la, stop } = await startAll({ scenario: "stuck", env: { LOCAL_AGENT_AGENT2_WORKSPACE_MAX_BODY_BYTES: "4096" } });
+    const a = r.assign(); await a.acked(); await waitFor(() => r.fake.jobs.size === 1);
+    const job = r.fake.jobs.get(a.p.jobId);
+    const h = job.h;
+    const call = (m, p, b, o) => h.workspace(m, p, b, o);
+    assert.equal((await call("GET", "/workspace/file-content?path=a")).status, 200);
+    assert.equal((await call("GET", "/workspace/file-content?path=a", undefined, { tokenOverride: "" })).status, 401);
+    assert.equal((await call("GET", "/workspace/file-content?path=a", undefined, { tokenOverride: "z".repeat(43) })).status, 401);
+    assert.equal((await call("GET", "/workspace/file-content?path=a", undefined, { tokenOverride: job.llm.key })).status, 401, "the LLM token is not the door's");
+    assert.equal((await call("GET", "/workspace/file-content?path=a", undefined, { tokenOverride: undefined, headers: { authorization: `Bearer ${r.callbackToken}` } })).status, 200, "the bearer form works too");
+    // only /workspace; nothing else of the API
+    assert.equal((await call("POST", "/setup/run-command", { command: "id" })).status, 404);
+    assert.equal((await call("GET", "/health")).status, 404);
+    // traversal and encodings never reach the API (raw requests: fetch() would normalise the dots away before they leave)
+    const raw = (p) => new Promise((resolve, reject) => {
+        const q = http.request({ host: "127.0.0.1", port: r.bridgePort, method: "POST", path: p, headers: { "x-agent-token": r.callbackToken, "content-type": "application/json" } }, (res) => { res.resume(); res.on("end", () => resolve(res.statusCode)); });
+        q.on("error", reject); q.end("{}");
+    });
+    for (const p of ["/workspace/../setup/run-command", "/workspace/%2e%2e/setup/run-command", "/workspace/a/%2e%2e/b", "/workspace//x", "/workspace/a%20b", "/workspace/a\\b", "/workspace/./x", "/workspace/a/../../setup/run-command", "/workspace/x#frag"]) {
+        assert.equal(await raw(p), 403, p);
+    }
+    assert.equal(la.requests.filter((q) => q.url.startsWith("/setup/")).length, 0, "/setup/run-command was never reached");
+    // the root: the header it sends must be the job's; none is added for it
+    assert.equal((await call("GET", "/workspace/file-content?path=a", undefined, { headers: { "x-workspace-root": "/etc" } })).status, 403);
+    assert.equal((await call("GET", "/workspace/file-content?path=a", undefined, { headers: { "x-workspace-root": r.root } })).status, 200);
+    assert.equal((await call("GET", "/workspace/file-content?path=a", undefined, { headers: { "x-workspace-root": `${r.root}/../elsewhere` } })).status, 403);
+    // headers agent2 tries to inject are not forwarded
+    await call("GET", "/workspace/file-content?path=a", undefined, { headers: { "x-vh-internal": "x", "x-vh-tenant-id": "9d1f6a2c-0000-4000-8000-000000000000", "x-vh-workspace-id": "other", "x-workspace-id": "other", cookie: "c=1" } });
+    const last = la.requests.at(-1);
+    assert.equal(last.signature.tenantId, TENANT);
+    assert.equal(last.signature.workspaceId, "ws-1");
+    assert.equal(last.headers["x-workspace-id"], "ws-1");
+    assert.equal(last.headers.cookie, undefined);
+    // methods and sizes
+    assert.equal((await call("DELETE", "/workspace/thing")).status, 200);
+    assert.equal((await h.workspace("PATCH", "/workspace/thing", { a: 1 })).status, 405);
+    assert.equal((await call("POST", "/workspace/echo", { blob: "x".repeat(10_000) })).status, 413, "over LOCAL_AGENT_AGENT2_WORKSPACE_MAX_BODY_BYTES");
+    assert.equal((await call("POST", "/workspace/echo", { blob: "x".repeat(100) })).status, 200);
+    await r.cancel(a.p.jobId);
+    await stop();
+});
+
+test("the door is closed without a running job and after it; an unreachable API is a 502 (nothing leaks)", async () => {
+    const { r, la, stop } = await startAll();
+    const { a, job } = await run(r);
+    const afterJob = await job.h.workspace("GET", "/workspace/file-content?path=a");
+    assert.equal(afterJob.status, 409, "the job is over: no active job");
+    assert.deepEqual(afterJob.json.error.code, "no_active_job");
+    await stop();
+
+    const dead = await agent2Rig({ scenario: "workspace", env: { LOCAL_AGENT_AGENT2_LA_URL: "http://127.0.0.1:1" } });
+    const b = dead.assign(); await b.acked(); await dead.done(b.p.jobId);
+    assert.equal(dead.fake.jobs.get(b.p.jobId).record.read.status, 502);
+    assert.equal(dead.fake.jobs.get(b.p.jobId).record.read.json.error.code, "workspace_unreachable");
+    await dead.stop();
+    void a; void la;
+});
+
+test("a response is passed through as it is (status, content type, body); a hung API is cut at LOCAL_AGENT_AGENT2_WORKSPACE_TIMEOUT_MS", async () => {
+    const { r, la, stop } = await startAll({ scenario: "stuck", env: { LOCAL_AGENT_AGENT2_WORKSPACE_TIMEOUT_MS: "1000" } });
+    const a = r.assign(); await a.acked(); await waitFor(() => r.fake.jobs.size === 1);
+    const h = r.fake.jobs.get(a.p.jobId).h;
+    const res = await h.workspace("GET", "/workspace/file-content?path=a");
+    assert.deepEqual([res.status, res.json.ok], [200, true]);
+    const missing = await h.workspace("GET", "/workspace/nope");
+    assert.equal(missing.status, 404, "the API's own 404 comes back");
+    assert.equal((await h.workspace("GET", "/workspace/slow")).status, 200);
+    void la;
+    await r.cancel(a.p.jobId);
+    await stop();
+});

package/test/la-protocol-v2/agent2-workspace-real-server.test.js

@@ -0,0 +1,137 @@
+// F3-08c, the real thing for the /workspace door: the REAL Local Agent process (node src/server.js) in LOCAL_AGENT_SIGNATURE_MODE=enforce, a REAL v2 session against the reference
+// CP, LOCAL_AGENT_RUNNER=agent2 in attach mode with a FAKE agent2 that does what agent2 does to the repository: read_file and write_file through AGENT2_LA_WORKSPACE_URL.
+// Before F3-08c this was a 401 "unsigned request". Not proven here: the real agent2 jar, the real gateway, a model (the fake agent2 never calls one).
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { ReferenceCpServer, TENANT, AGENT, waitFor, uuid } from "./helpers/reference-cp.js";
+import { runAgent, freePort } from "./helpers/spawn-agent.js";
+import { startFakeAgent2 } from "./helpers/fake-agent2.js";
+import { keySet, mkKey, sha, closeAllFakes } from "./helpers/fake-llm.js";
+import { fileURLToPath } from "node:url";
+
+const CLI = fileURLToPath(new URL("./helpers/fake-agent2-cli.js", import.meta.url));
+
+after(closeAllFakes);
+
+async function scenario({ laToken }) {
+    const srv = await new ReferenceCpServer({ requireEnforce: true, capabilities: ["policy.check"] }).start();
+    const laPort = await freePort();
+    const bridgePort = await freePort();
+    const apiToken = crypto.randomBytes(32).toString("base64url");
+    const callbackToken = crypto.randomBytes(32).toString("base64url");
+    const fake = await startFakeAgent2({ token: apiToken, tenantId: TENANT, scenario: "workspace", llmBase: () => `http://127.0.0.1:${bridgePort}/v1`, callbackUrl: () => `http://127.0.0.1:${bridgePort}`, callbackToken: () => callbackToken,
+        workspaceUrl: () => `http://127.0.0.1:${bridgePort}`, workspaceToken: () => callbackToken });
+    const key = mkKey("RS");
+    const out = { direct: {}, jobId: uuid() };
+    let ws = null;
+    const state = { keySent: false, assigned: false };
+    const direct = async (name, headers = {}) => { const r = await fetch(`http://127.0.0.1:${laPort}/workspace/file-content?path=src%2Fhello.js`, { headers }); out.direct[name] = { status: r.status, body: await r.json().catch(() => null) }; };
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT }, ms: 40_000,
+            prepare: async (dir) => { ws = dir; fs.mkdirSync(path.join(dir, "src")); fs.writeFileSync(path.join(dir, "src", "hello.js"), "// REAL-SERVER-FILE-CANARY\nconsole.log('hi');\n"); },
+            env: {
+                PORT: String(laPort), TENANT_ID: TENANT, LOCAL_AGENT_PROTOCOL_V2: "true", LOCAL_AGENT_SIGNATURE_MODE: "enforce", LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${srv.keyId}=${srv.publicKeyRaw}`,
+                LOCAL_AGENT_DLP_MODE: "enforce", LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_CLIENT: "true", LOCAL_AGENT_JOBS: "true", LOCAL_AGENT_RUNNER: "agent2",
+                LOCAL_AGENT_AGENT2_URL: fake.baseUrl, LOCAL_AGENT_AGENT2_TOKEN: apiToken, LOCAL_AGENT_AGENT2_BRIDGE_PORT: String(bridgePort), LOCAL_AGENT_AGENT2_CALLBACK_TOKEN: callbackToken,
+                ...(laToken ? { LOCAL_AGENT_TOKEN: laToken } : {}),
+            },
+            until: async () => {
+                if (srv.cp.state !== "ready") return false;
+                if (!state.keySent) { state.keySent = true; srv.cp.sendData("config.update", { llmKey: keySet(key) }); return false; }
+                if (!state.assigned && srv.cp.acksFromLa.length >= 1) {
+                    state.assigned = true;
+                    srv.cp.sendData("job.assign", { jobId: out.jobId, kind: "fix", repoRef: { provider: "github", org: "acme", repo: "app", branch: "main" }, policy: { operationMode: "assist", automationLevel: 2, ceiling: "assist" },
+                        budget: { tokens: 50_000, seconds: 60 }, llm: { alias: "vh-claude-sonnet", keyRef: sha(key) }, incidentRef: { id: "inc-42" }, inputs: [{ inline: "please fix the login bug", transient: true }] }, { workspaceId: "default" });
+                    return false;
+                }
+                if (!srv.cp.received.some((f) => f.type === "job.result" && f.payload.jobId === out.jobId)) return false;
+                // the job is over: the file agent2 wrote is read before the harness removes the workspace
+                out.written = ws && fs.existsSync(path.join(ws, "src", "out.txt")) ? fs.readFileSync(path.join(ws, "src", "out.txt"), "utf8") : null;
+                // the API of this very process, straight, is still guarded by the signature check
+                await direct("none");
+                await direct("agent2Token", { "x-agent-token": callbackToken });
+                if (laToken) await direct("laTokenOnly", { "x-agent-token": laToken });
+                await direct("forgedMarker", { "x-vh-internal": "A".repeat(43), "x-vh-tenant-id": TENANT, "x-vh-workspace-id": "default" });
+                return true;
+            },
+        });
+        out.record = fake.jobs.get(out.jobId)?.record;
+        out.frames = srv.cp.received.filter((f) => f.payload && (f.payload.jobId === out.jobId));
+        out.cpErrors = [...srv.cp.errorsSent];
+        out.key = key;
+        out.wire = JSON.stringify(srv.cp.rawIn);
+    } finally { await fake.close(); await srv.stop(); }
+    return out;
+}
+
+test("REAL server, enforce: agent2's read_file and write_file reach the workspace through the bridge (they were 401); the same API called straight is still refused 401", async () => {
+    const o = await scenario({});
+    assert.ok(o.record, "the job reached agent2");
+    assert.equal(o.record.read.status, 200, JSON.stringify(o.record.read.json));
+    assert.match(String(o.record.read.json?.content ?? o.record.read.text), /REAL-SERVER-FILE-CANARY/);
+    assert.equal(o.record.write.status, 200, JSON.stringify(o.record.write.json));
+    assert.equal(o.written, "written by agent2 through the bridge", "the file really is in the customer's workspace");
+    assert.equal(o.record.noToken.status, 401);
+    assert.equal(o.record.badToken.status, 401);
+    assert.equal(o.record.otherApi.status, 404, "nothing else of the API is behind the bridge");
+    for (const name of ["none", "agent2Token", "forgedMarker"]) { assert.equal(o.direct[name].status, 401, name); assert.equal(o.direct[name].body.error, "invalid command signature", name); assert.equal(o.direct[name].body.reason, "unsigned request", name); }
+    const result = o.frames.find((f) => f.type === "job.result");
+    assert.equal(result.payload.outcome, "no_change");
+    assert.deepEqual(o.cpErrors, []);
+    assert.ok(!o.wire.includes("REAL-SERVER-FILE-CANARY") && !o.wire.includes(o.key), "the file content and the key never go to the control plane");
+});
+
+test("REAL server, enforce + LOCAL_AGENT_TOKEN: the bridge adds the API's X-Agent-Token; the token alone, or without the signature, is refused", async () => {
+    const laToken = `la-token-${crypto.randomBytes(24).toString("hex")}`;
+    const o = await scenario({ laToken });
+    assert.equal(o.record.read.status, 200, JSON.stringify(o.record.read.json));
+    assert.equal(o.record.write.status, 200, JSON.stringify(o.record.write.json));
+    assert.equal(o.written, "written by agent2 through the bridge");
+    assert.equal(o.direct.none.status, 401, "no X-Agent-Token");
+    assert.equal(o.direct.agent2Token.status, 401, "agent2's token is not the API's");
+    assert.equal(o.direct.laTokenOnly.status, 401, "the API's token without the platform signature");
+    assert.equal(o.direct.laTokenOnly.body.reason, "unsigned request");
+    assert.ok(!o.wire.includes(laToken) && !JSON.stringify(o.record).includes(laToken));
+});
+
+test("REAL server, spawn mode: SIGTERM to the agent stops the agent2 process it supervised (no orphan), and the pidfile goes with it", async () => {
+    const srv = await new ReferenceCpServer({ requireEnforce: true, capabilities: ["policy.check"] }).start();
+    const dir = fs.mkdtempSync(path.join(fs.realpathSync(process.env.TMPDIR || "/tmp"), "a2term-"));
+    const pidFile = path.join(dir, "agent2.pid");
+    const key = mkKey("TM");
+    const jobId = uuid();
+    const state = { keySent: false, assigned: false, agent2Pid: 0, termSent: false, dead: false };
+    const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT }, ms: 40_000,
+            prepare: async (d) => { fs.mkdirSync(path.join(d, "src")); fs.writeFileSync(path.join(d, "src", "hello.js"), "x\n"); },
+            env: {
+                PORT: String(await freePort()), TENANT_ID: TENANT, LOCAL_AGENT_PROTOCOL_V2: "true", LOCAL_AGENT_SIGNATURE_MODE: "enforce", LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${srv.keyId}=${srv.publicKeyRaw}`,
+                LOCAL_AGENT_DLP_MODE: "enforce", LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_CLIENT: "true", LOCAL_AGENT_JOBS: "true", LOCAL_AGENT_RUNNER: "agent2",
+                LOCAL_AGENT_AGENT2_CMD: JSON.stringify([process.execPath, CLI, "--scenario=no_change"]), LOCAL_AGENT_AGENT2_PORT: String(await freePort()), LOCAL_AGENT_AGENT2_PIDFILE: pidFile, LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "10000",
+            },
+            until: async ({ child }) => {
+                if (srv.cp.state !== "ready") return false;
+                if (!state.keySent) { state.keySent = true; srv.cp.sendData("config.update", { llmKey: keySet(key) }); return false; }
+                if (!state.assigned && srv.cp.acksFromLa.length >= 1) {
+                    state.assigned = true;
+                    srv.cp.sendData("job.assign", { jobId, kind: "fix", repoRef: { provider: "github", org: "acme", repo: "app", branch: "main" }, policy: { operationMode: "assist", automationLevel: 2, ceiling: "assist" },
+                        budget: { tokens: 50_000, seconds: 60 }, llm: { alias: "vh-claude-sonnet", keyRef: sha(key) }, incidentRef: { id: "inc-42" }, inputs: [{ inline: "please fix", transient: true }] }, { workspaceId: "default" });
+                    return false;
+                }
+                if (!srv.cp.received.some((f) => f.type === "job.result" && f.payload.jobId === jobId)) return false;
+                if (!state.agent2Pid) { state.agent2Pid = JSON.parse(fs.readFileSync(pidFile, "utf8")).pid; assert.ok(alive(state.agent2Pid), "agent2 runs while the agent runs"); }
+                if (!state.termSent) { state.termSent = true; child.kill("SIGTERM"); return false; }
+                state.dead = !alive(state.agent2Pid);
+                return state.dead;
+            },
+        });
+    } finally { await srv.stop(); if (state.agent2Pid) { try { process.kill(state.agent2Pid, "SIGKILL"); } catch { /* gone */ } } fs.rmSync(dir, { recursive: true, force: true }); }
+    assert.ok(state.agent2Pid, "an agent2 process was started");
+    assert.equal(state.dead, true, "the supervised agent2 did not outlive the SIGTERM of the agent");
+});

package/test/la-protocol-v2/contract-v21.test.js

@@ -15,8 +15,8 @@ const VECTORS = path.join(path.dirname(fileURLToPath(import.meta.url)), "../cont
 const load = (f) => JSON.parse(fs.readFileSync(path.join(VECTORS, f), "utf8")).vectors;
 const sha = (s) => crypto.createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex");
 
-test("the copy is revision 2.1 and every 2.1 vector group is present with at least its valid and invalid cases", () => {
-    assert.equal(contract.index.revision, "2.1");
+test("the copy is revision 2.2 (2.1 is a subset) and every 2.1 vector group is present with at least its valid and invalid cases", () => {
+    assert.equal(contract.index.revision, "2.2");
     const groups = [
         ["config.update", /^llm-key-/, 6, 27],       // (a): llm-key-* in config.update (the ack and register ones are checked below)
         ["webhook.forward", /^wh-chunk-/, 9, 24],    // (b)

package/test/la-protocol-v2/contract.test.js

@@ -82,10 +82,10 @@ for (const file of vectorFiles) {
     }
 }
 
-test("vectors: counts (294 frames = 67 valid + 227 invalid in this copy (contract 2.1), plus the bodies of file.list)", () => {
-    assert.equal(valid + invalid, 294);
-    assert.equal(valid, 67);
-    assert.equal(invalid, 227);
+test("vectors: counts (363 frames = 82 valid + 281 invalid in this copy (contract 2.2: + policy.check 5+20, policy.decision 5+16), plus the bodies of file.list)", () => {
+    assert.equal(valid + invalid, 363);
+    assert.equal(valid, 82);
+    assert.equal(invalid, 281);
     assert.equal(bodyVectors, 54, "file.list.body.vectors.json (F3-07c): 54 bodies");
 });
 
@@ -108,8 +108,8 @@ test("error codes: fatal and retryable sets mirror the gateway (LaV2ErrorCode)",
 });
 
 test("allowlist: the LA receives only cp->la/both types and sends only la->cp/both types; v1 commands are not types", () => {
-    assert.deepEqual([...contract.inboundTypes].sort(), ["ack", "approval.decision", "config.update", "content.request", "error", "job.assign", "job.cancel", "ready", "scan.upload", "webhook.forward"]);
-    assert.deepEqual([...contract.outboundTypes].sort(), ["ack", "alert", "audit.event", "content.index", "content.response", "error", "heartbeat", "hello", "incident.candidate", "job.event", "job.result", "log.stats", "register", "scan.uploaded"]);
+    assert.deepEqual([...contract.inboundTypes].sort(), ["ack", "approval.decision", "config.update", "content.request", "error", "job.assign", "job.cancel", "policy.decision", "ready", "scan.upload", "webhook.forward"]);
+    assert.deepEqual([...contract.outboundTypes].sort(), ["ack", "alert", "audit.event", "content.index", "content.response", "error", "heartbeat", "hello", "incident.candidate", "job.event", "job.result", "log.stats", "policy.check", "register", "scan.uploaded"]);
     for (const v1 of ["mcp.execute-command", "workspace.open", "health", "shell.exec", "__proto__", "constructor", "toString"]) {
         assert.equal(contract.canReceive(v1), false, v1);
         assert.equal(contract.canSend(v1), false, v1);
@@ -121,8 +121,9 @@ test("limits come from index.json and are the documented ones", () => {
         maxFrameBytes: 49152, chunkRawBytes: 32768, maxChunks: 64, maxContentBytes: 2097152, maxRetries: 3, ackTimeoutMs: 5000,
         handshakeTimeoutMs: 10000, heartbeatSeconds: 30, sessionDeadSeconds: 90, dedupeWindowSeconds: 600, clockSkewSeconds: 60,
         webhookChunkRawBytes: 16384, webhookMaxChunks: 64, webhookMaxBytes: 1048576, webhookSingleFrameRawBytes: 9216, webhookAssemblySeconds: 30, webhookMaxOpenAssemblies: 4,
+        policyCheckPerMinute: 120, policyCheckTimeoutMs: 10000,
     });
-    assert.equal(contract.index.revision, "2.1");
+    assert.equal(contract.index.revision, "2.2");
 });
 
 // ------------------------------------------------------------------------------------------------ strict JSON

package/test/la-protocol-v2/helpers/agent2-rig.js

@@ -0,0 +1,96 @@
+// Rig of the agent2 runner tests (F3-08c): the REAL v2 session + buildV2Link (every flag, LOCAL_AGENT_RUNNER=agent2 in attach mode) against the ReferenceCp, the key
+// holder, the LLM client and a fake AI gateway, with a FAKE agent2 (helpers/fake-agent2.js) in the place of the sidecar. What it proves is limited by those fakes.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import net from "node:net";
+import crypto from "node:crypto";
+import { ReferenceCp, TENANT, AGENT, uuid, waitFor } from "./reference-cp.js";
+import { signingFor } from "./la-rig.js";
+import { write, tmpDir } from "./content-rig.js";
+import { startFakeLlm, okJson, okMessages, byPath, sha, mkKey, keySet } from "./fake-llm.js";
+import { startFakeAgent2 } from "./fake-agent2.js";
+import { buildV2Link } from "../../../src/la-protocol-v2/runtime.js";
+
+export { TENANT, AGENT, uuid, waitFor, sha };
+export { okJson, okMessages, byPath };
+export const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+export const CANARIES = { request: "REQUEST-CANARY-5521", file: "FILE-CANARY-7714", answer: "ANSWER-CANARY-3306", cmd: "SECRET-COMMAND-CANARY" };
+
+export const freePort = () => new Promise((resolve) => { const s = net.createServer(); s.listen(0, "127.0.0.1", () => { const p = s.address().port; s.close(() => resolve(p)); }); });
+export const b64url = (b) => Buffer.from(b).toString("base64url");
+
+export const BASE_ENV = { LOCAL_AGENT_DLP_MODE: "enforce", LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_CLIENT: "true", LOCAL_AGENT_JOBS: "true",
+    LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_DLP_BLOCK_CLASSES: "private-key", LOCAL_AGENT_LLM_BACKOFF_MS: "0", LOCAL_AGENT_JOBS_EVENT_MIN_MS: "50", LOCAL_AGENT_JOBS_CANCEL_GRACE_MS: "1500", LOCAL_AGENT_AGENT2_CANCEL_WAIT_MS: "1000",
+    LOCAL_AGENT_AGENT2_HEALTH_INTERVAL_MS: "60000", LOCAL_AGENT_AGENT2_AUDIT_RETRY_MS: "20" };   // LOCAL_AGENT_AGENT2_PIDFILE is set per rig (below)
+
+/** A vhapr1 token as the gateway's HumanApprovalTokens would mint it (Ed25519 over the platform key). `subject` = what the token is bound to. */
+export function mintApprovalToken({ privateKey, keyId, tenantId = TENANT, workspaceId = "ws-1", subject, by = "u-edu", ttl = 600, iat = Math.floor(Date.now() / 1000), jti = crypto.randomBytes(12).toString("base64url"), typ = "vh-human-approval" }) {
+    const payload = b64url(JSON.stringify({ typ, tid: tenantId, wid: workspaceId, sha256: crypto.createHash("sha256").update(subject, "utf8").digest("hex"), iat, exp: iat + ttl, jti, by, decision: "dec-1" }));
+    const sig = crypto.sign(null, Buffer.from(`VH-HUMAN-APPROVAL-V1\n${keyId}\n${payload}`, "utf8"), privateKey);
+    return `vhapr1.${keyId}.${payload}.${b64url(sig)}`;
+}
+
+const CLI = fileURLToPath(new URL("./fake-agent2-cli.js", import.meta.url));
+
+export async function agent2Rig({ spawn = null, scenario = "ok_pr", env = {}, behavior = byPath({ chat: okJson(CANARIES.answer, { promptTokens: 40, completionTokens: 11, cost: "0.0042" }), messages: okMessages(CANARIES.answer, { promptTokens: 40, completionTokens: 11, cost: "0.0042" }) }), supportList = true, frameApprovalId = true, setKey = true, policy = null, cpPolicyCapability = true, noRunnerEnv = false, assignOver } = {}) {
+    const root = tmpDir("f308c-");
+    write(root, "src/hello.js", `// ${CANARIES.file}\nconst token = "${GH}";\nconsole.log("hello");\n`);
+    const fakeLlm = await startFakeLlm(behavior);
+    const cp = new ReferenceCp({ capabilities: cpPolicyCapability ? ["policy.check"] : [] });
+    const pidFile = path.join(root, ".agent2-runner.pid");   // never the real ~/.deepdebug
+    const logs = [];
+    const errors = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m), error: (m) => errors.push(m) };
+    const bridgePort = await freePort();
+    const bridgeBase = `http://127.0.0.1:${bridgePort}`;
+    const apiToken = crypto.randomBytes(32).toString("base64url");
+    const callbackToken = crypto.randomBytes(32).toString("base64url");
+    // spawn mode: the runner starts the fake agent2 as a PROCESS (fake-agent2-cli.js); `env` is the (fake) environment of the Local Agent, so it carries PATH/HOME and some secrets that must NOT reach the child
+    const apiPort = spawn ? await freePort() : 0;
+    const fake = spawn ? { port: apiPort, jobs: new Map(), requests: [], approvals: new Map(), async close() {} } : await startFakeAgent2({ token: apiToken, tenantId: TENANT, scenario, llmBase: () => `${bridgeBase}/v1`, callbackUrl: () => bridgeBase, callbackToken: () => callbackToken, workspaceUrl: () => bridgeBase, workspaceToken: () => callbackToken, supportList, frameApprovalId });
+    const spawnEnv = spawn ? { PATH: process.env.PATH, HOME: process.env.HOME, LOCAL_AGENT_AGENT2_CMD: JSON.stringify(spawn.cmd || [process.execPath, CLI, `--scenario=${scenario}`, ...(spawn.args || [])]), LOCAL_AGENT_AGENT2_PORT: String(apiPort),
+        LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "5000", ...(spawn.env || {}) } : {};
+    const fullEnv = spawn ? { ...BASE_ENV, LOCAL_AGENT_AGENT2_PIDFILE: pidFile, ...spawnEnv, ...env } : noRunnerEnv ? { ...BASE_ENV, ...env } : { ...BASE_ENV, LOCAL_AGENT_AGENT2_PIDFILE: pidFile, LOCAL_AGENT_AGENT2_URL: fake.baseUrl, LOCAL_AGENT_AGENT2_TOKEN: apiToken, LOCAL_AGENT_AGENT2_BRIDGE_PORT: String(bridgePort), LOCAL_AGENT_AGENT2_CALLBACK_TOKEN: callbackToken, ...env };
+    const wsManager = { list: () => [{ id: "ws-1", root, tenantId: TENANT }] };
+    const results = [];
+    const signing = signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }, "enforce");
+    const link = await buildV2Link({ tenantId: TENANT, agentId: AGENT, signing, wsManager, getWorkspaceRoot: () => root, log, env: fullEnv, llmFetch: fakeLlm.fetchImpl, onJobResult: (r) => results.push(r) });
+    const transport = { send: (t) => cp.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, transport)), () => {});
+    // the CP's answer to a policy.check (contract 2.2): `policy(checkFrame, cp)` returns the policy.decision payload, or null/undefined = no answer (the LA must fail closed)
+    const checks = [];
+    cp.onReceived = (m) => {
+        if (m.type !== "policy.check") return;
+        checks.push(m);
+        if (!policy) return;
+        const p = policy(m, cp);
+        if (p) cp.sendData("policy.decision", p, { requestId: m.requestId, workspaceId: m.workspaceId });
+    };
+    link.session.attach(transport);
+    await waitFor(() => link.session.state === "ready");
+    const key = mkKey("A2");
+    if (setKey && link.llm) { cp.sendData("config.update", { llmKey: keySet(key) }); await waitFor(() => cp.acksFromLa.length >= 1); }
+    const refOf = (rel) => link.content?.mintRef({ workspaceId: "ws-1", kind: "file", rel })?.id ?? "A".repeat(43);
+    const ack0 = () => cp.acksFromLa.length;
+    const r = {
+        cp, link, fake, fakeLlm, root, key, checks, pidFile, logs, errors, results, refOf, bridgePort, bridgeBase, apiToken, callbackToken, env: fullEnv, signing,
+        assign(over = {}, workspaceId = "ws-1") {
+            const p = { jobId: uuid(), kind: "fix", repoRef: { provider: "github", org: "acme", repo: "app", branch: "main" }, policy: { operationMode: "assist", automationLevel: 2, ceiling: "assist" },
+                budget: { tokens: 50_000, seconds: 60 }, llm: { alias: "vh-claude-sonnet", keyRef: sha(key) }, incidentRef: { id: "inc-42" },
+                inputs: [{ inline: `${CANARIES.request} please fix the login bug`, transient: true }, { ref: refOf("src/hello.js") }], ...(assignOver || {}), ...over };
+            const n = ack0();
+            cp.sendData("job.assign", p, { workspaceId });
+            return { p, acked: () => waitFor(() => cp.acksFromLa.length > n).then(() => cp.acksFromLa[n]) };
+        },
+        cancel(jobId) { const n = ack0(); cp.sendData("job.cancel", { jobId, reason: "user" }); return waitFor(() => cp.acksFromLa.length > n).then(() => cp.acksFromLa[n]); },
+        frames: (jobId, type) => cp.received.filter((f) => (!type || f.type === type) && (f.payload.jobId === jobId || (type === "audit.event"))),
+        done: (jobId, ms = 8000) => waitFor(() => r.frames(jobId, "job.result").length === 1 && r.frames(jobId, "job.event").some((e) => ["succeeded", "failed", "cancelled"].includes(e.payload.state)), ms),
+        approvalDecision(payload) { const n = ack0(); cp.sendData("approval.decision", payload, { workspaceId: "ws-1" }); return waitFor(() => cp.acksFromLa.length > n).then(() => cp.acksFromLa[n]); },
+        mint: (o) => mintApprovalToken({ privateKey: cp.privateKey, keyId: cp.keyId, ...o }),
+        everything: () => JSON.stringify([cp.received, logs, errors, link.jobs?.audit.tail(1000), link.llm?.client?.audit.tail(1000), link.llm?.audit.tail(1000), link.llm?.client?.stats, link.jobs?.stats,
+            link.agent2?.audit.tail(1000), link.agent2?.stats, link.agent2?.bridge.stats, link.agent2?.approvals.stats, link.agent2?.supervisor.stats]),
+        async stop() { link.close(); await fake.close(); await fakeLlm.close(); fs.rmSync(root, { recursive: true, force: true }); },
+    };
+    return r;
+}