deepdebug-local-agent 1.10.0 → 1.12.0

package/test/la-protocol-v2/agent2-approval-discovery.test.js

@@ -0,0 +1,114 @@
+// F3-08c: how an `approval.decision` finds the approval agent2 is waiting on. The id in the frame is the control plane's, `audit.event approval_requested` carries none, so this agent
+// asks agent2 for the pending approvals OF THE JOB (`GET /local/v1/approvals?jobId=`) and the vhapr1 token (bound to the sha256 of the request hash) picks the one. A FAKE agent2
+// that exposes that endpoint (helpers/fake-agent2.js); the real agent2 gets the endpoint in PR #308's follow-up (task A of the F3-08c closing).
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import { closeAllFakes } from "./helpers/fake-llm.js";
+import { agent2Rig, uuid, waitFor } from "./helpers/agent2-rig.js";
+
+after(closeAllFakes);
+
+const h = (s) => crypto.createHash("sha256").update(s).digest("hex");
+async function pending(r) {
+    const a = r.assign(); await a.acked();
+    await waitFor(() => [...r.fake.approvals.values()].some((x) => x.jobId === a.p.jobId));
+    return { a, ap: [...r.fake.approvals.values()].find((x) => x.jobId === a.p.jobId) };
+}
+const foreign = (r, jobId, requestHash) => { const approvalId = uuid(); r.fake.approvals.set(approvalId, { approvalId, jobId, actionType: "RUN_SHELL_FREEFORM", toolName: "run_command", requestHash, expiresAt: new Date(Date.now() + 600_000).toISOString(), resolve() {}, decided: false }); return approvalId; };
+
+test("the pending list is asked FOR THE JOB (?jobId=); an approval of another job with the very same request hash is never a candidate, never decided", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pending(r);
+    const other = foreign(r, uuid(), ap.requestHash);
+    const ack = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(ack.status, "accepted");
+    await r.done(a.p.jobId);
+    const lists = r.fake.requests.filter((q) => q.method === "LIST");
+    assert.ok(lists.length >= 1);
+    for (const q of lists) assert.equal(q.query, `?jobId=${a.p.jobId}`, "always scoped to the running job");
+    assert.deepEqual(r.fake.requests.filter((q) => q.method === "DECIDE").map((q) => q.path), [`/local/v1/approvals/${ap.approvalId}`], "only the job's own approval was decided");
+    assert.equal(r.fake.approvals.get(other).decided, false);
+    await r.stop();
+});
+
+test("approvals of other jobs exist next to the job's own: the decision touches only the job's", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pending(r);
+    const other = foreign(r, uuid(), h("another request"));
+    const list = await (await fetch(`${r.fake.baseUrl}/local/v1/approvals`, { headers: { authorization: `Bearer ${r.apiToken}` } })).json();
+    assert.equal(list.approvals.length, 2, "unfiltered, agent2 would list both");
+    const ack = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(ack.status, "accepted");
+    await r.done(a.p.jobId);
+    assert.equal(r.fake.approvals.get(other).decided, false);
+    await r.stop();
+});
+
+test("two approvals pending in the job: the token decides which one is answered (the other keeps waiting)", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pending(r);
+    const second = foreign(r, a.p.jobId, h("second request"));
+    const ack = await r.approvalDecision({ approvalId: uuid(), decision: "denied", token: r.mint({ subject: h("second request") }) });
+    assert.equal(ack.status, "accepted");
+    assert.deepEqual(r.fake.requests.filter((q) => q.method === "DECIDE").map((q) => [q.path, q.decision]), [[`/local/v1/approvals/${second}`, "denied"]]);
+    assert.equal(r.fake.approvals.get(ap.approvalId).decided, false, "the first is still waiting");
+    const ack2 = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(ack2.status, "accepted");
+    await r.done(a.p.jobId);
+    await r.stop();
+});
+
+test("a decision for an approval that is no longer pending (decided, expired) is acked and delivers nothing; the control plane's id is not trusted as agent2's", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pending(r);
+    assert.equal((await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) })).status, "accepted");
+    await r.done(a.p.jobId);
+    const decides = r.fake.requests.filter((q) => q.method === "DECIDE").length;
+    // a new, valid token for the same (now gone) request: nothing waits any more
+    const late = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(late.status, "accepted");
+    assert.equal(r.fake.requests.filter((q) => q.method === "DECIDE").length, decides);
+    await r.stop();
+});
+
+test("an agent2 without the list endpoint falls back to the control plane's id as agent2's own (detail route); an id it does not know cannot be delivered and says so", async () => {
+    const r = await agent2Rig({ scenario: "approval", supportList: false, frameApprovalId: false });
+    const { ap } = await pending(r);
+    const lost = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.deepEqual([lost.status, lost.errorCode], ["rejected", "internal"]);
+    const found = await r.approvalDecision({ approvalId: ap.approvalId, decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(found.status, "accepted");
+    assert.equal(r.fake.requests.filter((q) => q.method === "DECIDE").length, 1);
+    await r.stop();
+});
+
+test("the approval id agent2 puts in its own frames (PR #308) is learned by this agent only: it never reaches the control plane; without the list endpoint it finds the approval for a decision with the control plane's (unrelated) id", async () => {
+    const r = await agent2Rig({ scenario: "approval", supportList: false, frameApprovalId: true });
+    const { a, ap } = await pending(r);
+    const audit = r.cp.received.filter((f) => f.type === "audit.event" && f.payload.action === "approval_requested");
+    assert.equal(audit.length, 1);
+    assert.deepEqual(Object.keys(audit[0].payload).sort(), ["action", "actionType", "decision", "requestHash", "toolName"], "the contract's closed payload: no approvalId, no summary");
+    assert.ok(!JSON.stringify(r.cp.received).includes(ap.approvalId), "agent2's approval id is not on the wire to the control plane");
+    const ack = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(ack.status, "accepted", "found through the frame, not through a list agent2 does not have");
+    assert.deepEqual(r.fake.requests.filter((q) => q.method === "DECIDE").map((q) => q.path), [`/local/v1/approvals/${ap.approvalId}`]);
+    await r.done(a.p.jobId);
+    assert.ok(!r.everything().includes(ap.approvalId), "nor in a log, an audit or a stat of this agent");
+    await r.stop();
+});
+
+test("frame-learned approvals do not widen what a token can approve: a token for another request hash still decides nothing, and a replayed token after the job is over finds nothing", async () => {
+    const r = await agent2Rig({ scenario: "approval", supportList: false, frameApprovalId: true });
+    const { a, ap } = await pending(r);
+    const wrong = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: h("another request") }) });
+    assert.deepEqual([wrong.status, wrong.errorCode], ["rejected", "unauthorized"]);
+    assert.equal(r.fake.requests.filter((q) => q.method === "DECIDE").length, 0);
+    assert.equal((await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) })).status, "accepted");
+    await r.done(a.p.jobId);
+    await waitFor(() => r.link.agent2.active === null);
+    const late = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(late.status, "accepted", "nothing runs: acked without an oracle");
+    assert.equal(r.fake.requests.filter((q) => q.method === "DECIDE").length, 1, "and nothing was delivered");
+    await r.stop();
+});

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

@@ -0,0 +1,103 @@
+// F3-08c (Local Agent half): configuration, frame whitelist and the small pure helpers of the agent2 runner.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveAgent2RunnerConfig, parseCommand, loopbackBase, relayBase, agent2RunnerRequested } from "../../src/la-protocol-v2/jobs/agent2/config.js";
+import { normalizeFrame } from "../../src/la-protocol-v2/jobs/agent2/frames.js";
+import { workspaceUuid } from "../../src/la-protocol-v2/jobs/agent2/runner.js";
+import { approvalSubject } from "../../src/la-protocol-v2/jobs/agent2/approvals.js";
+
+const T = "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f";
+const J = "0b6f1c22-7a0e-4d8e-9a53-1b7a8c9d0e1f";
+const warns = () => { const w = []; return { w, warn: (m) => w.push(m) }; };
+const TOKEN = "k".repeat(40);
+
+test("flag: only LOCAL_AGENT_RUNNER=agent2 turns it on; anything else is off (an unknown value is said, `smoke` is the other runner's)", () => {
+    for (const v of [undefined, "", "false", "smoke", "AGENT3", "1"]) {
+        const { w, warn } = warns();
+        assert.deepEqual(resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: v, LOCAL_AGENT_AGENT2_CMD: "x" }, warn), { enabled: false }, String(v));
+        assert.equal(agent2RunnerRequested({ LOCAL_AGENT_RUNNER: v }), false);
+        assert.equal(w.length, v && !["false", "smoke"].includes(v) ? 1 : 0, String(v));
+    }
+    assert.equal(agent2RunnerRequested({ LOCAL_AGENT_RUNNER: " Agent2 " }), true);
+});
+
+test("spawn and attach need exactly one way to reach agent2; attach needs a loopback URL, a 32+ char token and a fixed bridge port", () => {
+    const base = { LOCAL_AGENT_RUNNER: "agent2" };
+    assert.match(resolveAgent2RunnerConfig(base).error, /needs LOCAL_AGENT_AGENT2_CMD or LOCAL_AGENT_AGENT2_URL/);
+    assert.match(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_CMD: "a", LOCAL_AGENT_AGENT2_URL: "http://127.0.0.1:1" }).error, /not both/);
+    assert.match(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_CMD: "[1,2]" }).error, /JSON array/);
+    const spawn = resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_CMD: '["java","-jar","/opt/agent2.jar"]' });
+    assert.deepEqual([spawn.enabled, spawn.mode, spawn.cmd, spawn.apiPort, spawn.bridgePort], [true, "spawn", ["java", "-jar", "/opt/agent2.jar"], 8765, 0]);
+    assert.deepEqual(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_CMD: "java -jar x.jar" }).cmd, ["java", "-jar", "x.jar"]);
+    for (const url of ["http://10.0.0.5:8765", "https://127.0.0.1:8765", "http://user:pw@127.0.0.1:8765", "http://127.0.0.1:8765/x", "http://example.com", "ftp://127.0.0.1"]) {
+        assert.match(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_URL: url, LOCAL_AGENT_AGENT2_TOKEN: TOKEN, LOCAL_AGENT_AGENT2_BRIDGE_PORT: "5058" }).error, /loopback/, url);
+    }
+    const u = "http://127.0.0.1:8765";
+    assert.match(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_URL: u }).error, /LOCAL_AGENT_AGENT2_TOKEN/);
+    assert.match(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_URL: u, LOCAL_AGENT_AGENT2_TOKEN: "short" }).error, /LOCAL_AGENT_AGENT2_TOKEN/);
+    assert.match(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_URL: u, LOCAL_AGENT_AGENT2_TOKEN: TOKEN }).error, /BRIDGE_PORT/);
+    const att = resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_URL: "http://localhost:8765/", LOCAL_AGENT_AGENT2_TOKEN: TOKEN, LOCAL_AGENT_AGENT2_BRIDGE_PORT: "5058", LOCAL_AGENT_AGENT2_CALLBACK_TOKEN: "c".repeat(32) });
+    assert.deepEqual([att.mode, att.url, att.bridgePort, att.callbackToken], ["attach", "http://localhost:8765", 5058, "c".repeat(32)]);
+    assert.equal(resolveAgent2RunnerConfig({ ...base, LOCAL_AGENT_AGENT2_URL: u, LOCAL_AGENT_AGENT2_TOKEN: TOKEN, LOCAL_AGENT_AGENT2_BRIDGE_PORT: "5058", LOCAL_AGENT_AGENT2_CALLBACK_TOKEN: "short" }).callbackToken, null);
+});
+
+test("numbers are clamped, never unlimited; the old HTTP PolicyGate pair is ignored (the gate is asked over the v2 channel)", () => {
+    const c = resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: "x", LOCAL_AGENT_AGENT2_MAX_RESTARTS: "9999", LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "-1", LOCAL_AGENT_AGENT2_MAX_BODY_BYTES: "abc", LOCAL_AGENT_AGENT2_CANCEL_WAIT_MS: "5" });
+    assert.deepEqual([c.maxRestarts, c.startTimeoutMs, c.maxBodyBytes, c.cancelWaitMs], [3, 90_000, 1024 * 1024, 8_000]);
+    assert.equal(c.policy, undefined, "no HTTP relay in the config any more");
+    assert.deepEqual([c.policyCheckTimeoutMs, c.maxWorkspaceBodyBytes, c.workspaceTimeoutMs], [10_000, 16 * 1024 * 1024, 900_000]);
+    const clamped = resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: "x", LOCAL_AGENT_AGENT2_POLICY_TIMEOUT_MS: "5", LOCAL_AGENT_AGENT2_WORKSPACE_MAX_BODY_BYTES: "0", LOCAL_AGENT_AGENT2_WORKSPACE_TIMEOUT_MS: "999999999" });
+    assert.deepEqual([clamped.policyCheckTimeoutMs, clamped.maxWorkspaceBodyBytes, clamped.workspaceTimeoutMs], [10_000, 16 * 1024 * 1024, 900_000]);
+    const { w, warn } = warns();
+    const old = resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: "x", LOCAL_AGENT_AGENT2_POLICY_URL: "https://gw.example.com/", LOCAL_AGENT_AGENT2_POLICY_TOKEN: "SECRET-BEARER-CANARY" }, warn);
+    assert.equal(old.enabled, true);
+    assert.equal(old.policy, undefined);
+    assert.equal(w.length, 1);
+    assert.match(w[0], /ignored/);
+    assert.ok(!w[0].includes("SECRET-BEARER-CANARY"), "the bearer is never echoed");
+    assert.equal(relayBase("https://u:p@gw.example.com"), null);
+    assert.equal(relayBase("http://127.0.0.1:9"), "http://127.0.0.1:9");
+    assert.equal(loopbackBase("http://[::1]:9"), "http://[::1]:9");
+    assert.equal(parseCommand("a\0b"), null);
+    assert.equal(parseCommand("[]"), null);
+});
+
+test("workspaceUuid: a UUID stays, a free-form id becomes a stable name-based UUID that depends on the tenant", () => {
+    assert.equal(workspaceUuid(T, J), J);
+    const a = workspaceUuid(T, "default");
+    assert.match(a, /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+    assert.equal(workspaceUuid(T, "default"), a);
+    assert.notEqual(workspaceUuid(T, "ws-1"), a);
+    assert.notEqual(workspaceUuid("9d1f6a2c-0000-4000-8000-000000000000", "default"), a);
+});
+
+const ctx = { tenantId: T, jobId: J };
+const frame = (type, payload, over = {}) => ({ seq: 1, type, tenantId: T, workspaceId: J, payload, ...over });
+
+test("frames: job.event / job.result / audit.event are reduced to the closed whitelist; unknown or out-of-range values are dropped, never repaired", () => {
+    const ev = normalizeFrame(frame("job.event", { jobId: J, state: "running", phase: "edit", iteration: 3, filesRead: 2, filesChanged: 1, tokensIn: 9, tokensOut: 9, costUsd: 5, model: "m", message: "x" }), ctx);
+    assert.deepEqual(ev.payload, { jobId: J, state: "running", phase: "edit", iteration: 3, filesRead: 2, filesChanged: 1 });
+    assert.deepEqual(normalizeFrame(frame("job.event", { jobId: J, state: "running", phase: "hack", iteration: -1, filesRead: 1.5, errorCode: "boom" }), ctx).payload, { jobId: J, state: "running" });
+    assert.equal(normalizeFrame(frame("job.event", { jobId: J, state: "exploded" }), ctx), null);
+    assert.equal(normalizeFrame(frame("job.event", { jobId: J, state: "failed", errorCode: "tests_failed" }), ctx).terminal, true);
+    const res = normalizeFrame(frame("job.result", { jobId: J, outcome: "pr_opened", prUrl: "https://x/y", filesChangedCount: 2, tests: { pass: 1, fail: 0, skip: 0 }, extra: "no" }), ctx);
+    assert.deepEqual(res.payload, { jobId: J, outcome: "pr_opened", prUrl: "https://x/y", filesChangedCount: 2, tests: { pass: 1, fail: 0, skip: 0 } });
+    assert.equal(normalizeFrame(frame("job.result", { jobId: J, outcome: "great" }), ctx), null);
+    const au = normalizeFrame(frame("audit.event", { action: "approval_requested", decision: "require_human", actionType: "RUN_SHELL_FREEFORM", toolName: "run_command", requestHash: "a".repeat(64), summary: "rm -rf" }), ctx);
+    assert.deepEqual(au.payload, { action: "approval_requested", decision: "require_human", actionType: "RUN_SHELL_FREEFORM", toolName: "run_command", requestHash: "a".repeat(64) });
+    assert.deepEqual(normalizeFrame(frame("audit.event", { action: "policy_decision", decision: "maybe", actionType: "has space", toolName: "../etc", requestHash: "XYZ" }), ctx).payload, { action: "policy_decision" });
+    for (const action of ["redaction", "content_served", "config_applied", "x"]) assert.equal(normalizeFrame(frame("audit.event", { action }), ctx), null, action);
+});
+
+test("frames: another tenant or another job is a violation (not data); bad shapes are ignored", () => {
+    assert.deepEqual(normalizeFrame(frame("job.event", { jobId: J, state: "failed" }, { tenantId: "9d1f6a2c-0000-4000-8000-000000000000" }), ctx), { violation: "tenant" });
+    assert.deepEqual(normalizeFrame(frame("job.event", { jobId: "6c9a1c22-7a0e-4d8e-9a53-1b7a8c9d0e1f", state: "failed" }), ctx), { violation: "job" });
+    assert.deepEqual(normalizeFrame(frame("job.result", { jobId: "6c9a1c22-7a0e-4d8e-9a53-1b7a8c9d0e1f", outcome: "failed" }), ctx), { violation: "job" });
+    for (const f of [null, [], "x", {}, { seq: 0, type: "job.event", payload: {} }, frame("job.event", null), frame("job.event", []), frame("nope", {}), { ...frame("job.event", { jobId: J, state: "running" }), seq: "1" }]) assert.equal(normalizeFrame(f, ctx), null);
+    assert.notEqual(normalizeFrame({ seq: 1, type: "job.event", payload: { jobId: J, state: "running" } }, ctx), null, "a frame without a tenant field is taken at the word of the authenticated loopback channel");
+});
+
+test("approvalSubject: the token is bound to the request hash string", () => {
+    assert.equal(approvalSubject("ab"), "ab");
+    assert.equal(approvalSubject(undefined), "");
+});

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

@@ -0,0 +1,118 @@
+// F3-08c: an agent2 left behind by a previous run of this agent (it was SIGKILLed, it crashed) keeps the API port and an old token; the next start must end it, and must never
+// touch anything else. The supervisor keeps a pidfile for that; an orderly exit of the agent takes the child with it. Real processes (the fake agent2 CLI), no mocks of the OS.
+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 { spawn, execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { closeAllFakes } from "./helpers/fake-llm.js";
+import { agent2Rig, TENANT, waitFor } from "./helpers/agent2-rig.js";
+
+after(closeAllFakes);
+
+const CLI = fileURLToPath(new URL("./helpers/fake-agent2-cli.js", import.meta.url));
+const EXIT_SCRIPT = fileURLToPath(new URL("./helpers/supervisor-exit-script.js", import.meta.url));
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+const toKill = new Set();
+after(() => { for (const p of toKill) { try { process.kill(p, "SIGKILL"); } catch { /* gone */ } } });
+const sha = (cmd) => crypto.createHash("sha256").update(JSON.stringify(cmd)).digest("hex");
+
+/** the process a crashed LA would have left: the same command, listening on the API port with an OLD token */
+async function orphanOf(r, { cmd = [process.execPath, CLI, "--scenario=ok_pr"] } = {}) {
+    const child = spawn(cmd[0], cmd.slice(1), { env: { PATH: process.env.PATH, AGENT2_LOCAL_API_TOKEN: "old-token-".padEnd(40, "o"), AGENT2_LOCAL_TENANT_ID: TENANT, AGENT2_LOCAL_PORT: r.env.LOCAL_AGENT_AGENT2_PORT,
+        AGENT2_LLM_BASE_URL: "http://127.0.0.1:1/v1", AGENT2_LA_CALLBACK_URL: "http://127.0.0.1:1", AGENT2_LA_CALLBACK_TOKEN: "c".repeat(40) }, stdio: "ignore", detached: true });
+    child.unref();
+    toKill.add(child.pid);
+    await waitFor(async () => { try { return (await fetch(`http://127.0.0.1:${r.env.LOCAL_AGENT_AGENT2_PORT}/local/v1/health`)).ok; } catch { return false; } }, 8000, 50);
+    return child;
+}
+const writePid = (r, pid, over = {}) => fs.writeFileSync(r.pidFile, JSON.stringify({ pid, cmdSha: sha(JSON.parse(r.env.LOCAL_AGENT_AGENT2_CMD)), startedAt: Date.now(), ...over }));
+const run = async (r) => { const a = r.assign(); await a.acked(); await r.done(a.p.jobId, 15_000); return a; };
+
+test("an orphan agent2 from a previous run (pidfile + same command, alive) is ended at the next start, and the job runs on a NEW process on the same port", async () => {
+    const r = await agent2Rig({ spawn: {}, scenario: "ok_pr", env: { LOCAL_AGENT_AGENT2_STOP_GRACE_MS: "2000" } });
+    const orphan = await orphanOf(r);
+    writePid(r, orphan.pid);
+    assert.ok(alive(orphan.pid));
+    const a = await run(r);
+    assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "pr_opened", "the job ran on the new process: the old token would have been refused");
+    await waitFor(() => !alive(orphan.pid), 4000);
+    assert.equal(r.link.agent2.supervisor.stats.orphansEnded, 1);
+    const fresh = JSON.parse(fs.readFileSync(r.pidFile, "utf8"));
+    assert.equal(fresh.pid, r.link.agent2.supervisor.pid);
+    assert.notEqual(fresh.pid, orphan.pid);
+    assert.ok(r.logs.some((l) => /previous run is still alive/.test(l)));
+    r.link.close();
+    await waitFor(() => !fs.existsSync(r.pidFile), 5000);
+    await r.stop();
+});
+
+test("a pid that is alive but is NOT our command (the pid was reused) is never touched; a dead pid and a command that changed are cleared; nothing blocks the start", async () => {
+    const r = await agent2Rig({ spawn: {}, scenario: "ok_pr" });
+    const stranger = spawn("sleep", ["60"], { stdio: "ignore", detached: true });
+    stranger.unref(); toKill.add(stranger.pid);
+    writePid(r, stranger.pid);
+    const a = await run(r);
+    assert.ok(alive(stranger.pid), "an unrelated process is left alone");
+    assert.equal(r.link.agent2.supervisor.stats.orphansEnded, 0);
+    assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "pr_opened");
+    r.link.close(); await waitFor(() => !fs.existsSync(r.pidFile), 5000); await r.stop();
+
+    // a dead pid
+    const r2 = await agent2Rig({ spawn: {}, scenario: "ok_pr" });
+    const gone = spawn(process.execPath, ["-e", "0"], { stdio: "ignore" });
+    await new Promise((x) => gone.on("exit", x));
+    writePid(r2, gone.pid);
+    await run(r2);
+    assert.equal(r2.link.agent2.supervisor.stats.orphansEnded, 0);
+    r2.link.close(); await r2.stop();
+
+    // the pidfile of ANOTHER command (the configuration changed): a look-alike is not ended
+    const r3 = await agent2Rig({ spawn: {}, scenario: "ok_pr" });
+    const lookalike = await orphanOf(r3);
+    writePid(r3, lookalike.pid, { cmdSha: sha(["something", "else"]) });
+    await new Promise((x) => setTimeout(x, 100));
+    assert.ok(alive(lookalike.pid));
+    r3.link.close(); await r3.stop();
+    process.kill(lookalike.pid, "SIGKILL");
+
+    // junk in the pidfile, and our own pid
+    const r4 = await agent2Rig({ spawn: {}, scenario: "ok_pr" });
+    fs.writeFileSync(r4.pidFile, "not json");
+    await run(r4);
+    fs.writeFileSync(r4.pidFile, JSON.stringify({ pid: process.pid, cmdSha: sha(JSON.parse(r4.env.LOCAL_AGENT_AGENT2_CMD)) }));
+    r4.link.close(); await r4.stop();
+    assert.ok(alive(process.pid));
+});
+
+test("where the command line of the pid cannot be read, nothing is killed (the start goes on, loudly)", async () => {
+    const { createAgent2Supervisor } = await import("../../src/la-protocol-v2/jobs/agent2/supervisor.js");
+    const { resolveAgent2RunnerConfig } = await import("../../src/la-protocol-v2/jobs/agent2/config.js");
+    const dir = fs.mkdtempSync(path.join(fs.realpathSync(process.env.TMPDIR || "/tmp"), "a2orph-"));
+    const pidFile = path.join(dir, "p.pid");
+    const cfg = resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: JSON.stringify([process.execPath, CLI, "--scenario=ok_pr"]), LOCAL_AGENT_AGENT2_PIDFILE: pidFile });
+    const victim = spawn("sleep", ["60"], { stdio: "ignore", detached: true });
+    victim.unref(); toKill.add(victim.pid);
+    fs.writeFileSync(pidFile, JSON.stringify({ pid: victim.pid, cmdSha: sha(cfg.cmd) }));
+    const warns = [];
+    const proc = Object.assign(new (await import("node:events")).EventEmitter(), { stdout: null, stderr: null, pid: 999999, kill: () => true });
+    const sup = createAgent2Supervisor({ config: cfg, tenantId: TENANT, bridge: { listen: async () => ({ baseUrl: "http://127.0.0.1:1" }), setCallbackToken() {} }, env: { HOME: dir }, log: { warn: (m) => warns.push(m), info() {} },
+        cmdlineOf: async () => null, spawnImpl: () => proc, fetchImpl: async () => new Response(JSON.stringify({ status: "up" }), { status: 200 }) });
+    await sup.ensureReady();
+    assert.ok(alive(victim.pid), "not verified, not killed");
+    assert.equal(sup.stats.orphanChecksSkipped, 1);
+    assert.ok(warns.some((w) => /cannot be read/.test(w)));
+    await sup.stop();
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test("an orderly exit of the agent (process.exit) takes the child with it", async () => {
+    const dir = fs.mkdtempSync(path.join(fs.realpathSync(process.env.TMPDIR || "/tmp"), "a2exit-"));
+    const out = execFileSync(process.execPath, [EXIT_SCRIPT, CLI, path.join(dir, "p.pid")], { encoding: "utf8", timeout: 30_000 });
+    const pid = Number(/CHILD_PID=(\d+)/.exec(out)[1]);
+    toKill.add(pid);
+    await waitFor(() => !alive(pid), 5000, 50);
+    fs.rmSync(dir, { recursive: true, force: true });
+});

package/test/la-protocol-v2/agent2-policy-check.test.js

@@ -0,0 +1,273 @@
+// F3-08c, contract 2.2: the PolicyGate of agent2 is asked over the v2 channel (`policy.check` LA -> CP, `policy.decision` CP -> LA), not with a platform bearer over HTTP.
+// In process: the REAL v2 session + buildV2Link (LOCAL_AGENT_RUNNER=agent2, attach mode) against the ReferenceCp (which validates every frame against the synced contract
+// and answers like the gateway: it lists `policy.check` in `ready` only for an LA that announced it), with a FAKE agent2 that asks through the bridge like the hosted
+// PolicyGateGuard does. What it proves: the frame is the closed one (no tenant, agent, origin, path, command, URL), the answer maps back to what agent2 reads, and every
+// failure (no capability, no answer, a refused frame, a wrong hash, a late answer) is a DENY. NOT proven: the real gateway handler (its own tests, PR #633).
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { closeAllFakes } from "./helpers/fake-llm.js";
+import { agent2Rig, TENANT, waitFor, uuid } from "./helpers/agent2-rig.js";
+import { createPolicyCheckRelay, normalizePolicyCheck, decisionBody } from "../../src/la-protocol-v2/jobs/agent2/policy-check.js";
+
+after(closeAllFakes);
+
+const HASH = "c".repeat(64);
+const decisionFor = (m, over = {}) => ({ decision: "ALLOW", reasonCode: "autonomous", shadow: false, approvalRequired: false, actionType: m.payload.actionType, requestHash: m.payload.requestHash, policySnapshot: { hash: "d".repeat(64) }, ...over });
+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) }; };
+
+// ------------------------------------------------------------------------------------------------------ the frame
+
+test("policy.check: the frame is closed and says nothing about WHO asks: no tenant/agent/origin claim, no path, no command, no URL; the answer is the decision payload agent2 (LocalPolicyCheck.verdict) requires", async () => {
+    const r = await agent2Rig({ scenario: "policy_check", policy: (m) => decisionFor(m, { effectiveMode: "assist" }) });
+    const { a, job } = await run(r);
+    assert.equal(r.checks.length, 1);
+    const m = r.checks[0];
+    assert.equal(m.type, "policy.check");
+    assert.match(m.requestId, /^[0-9a-f-]{36}$/);
+    assert.equal(m.tenantId, TENANT, "the envelope names the session's tenant, as every frame does; it is the CP that derives it, not this agent that asserts it");
+    assert.equal(m.workspaceId, "ws-1");
+    assert.equal(m.sig, undefined, "unsigned: the authenticated session is the identity");
+    assert.deepEqual(m.payload, {
+        actionType: "APPLY_PATCH", toolName: "apply_patch", requestHash: m.payload.requestHash,
+        repoRefs: [{ provider: "github", org: "acme", repo: "app" }],
+        incidentId: "inc-42", jobId: a.p.jobId, modelAlias: "vh-claude-sonnet",
+    });
+    assert.match(m.payload.requestHash, /^[0-9a-f]{64}$/);
+    for (const forbidden of ["tenantId", "agentId", "agent", "executionOrigin", "workspaceId", "diffFiles", "allowedFiles", "repoUrl", "repoUrls"]) assert.ok(!(forbidden in m.payload), forbidden);
+    assert.equal(r.link.agent2.policyCheck.stats.dropped, 8, "agent2's extra claims (tenant, workspace, agent, origin, files, URLs) were dropped and counted");
+    const wire = JSON.stringify(r.cp.rawIn);
+    for (const leak of ["SECRET-PATH-CANARY", "11111111-1111-4111-8111-111111111111", "hosted", "github.com", "gitlab.com", ".git"]) assert.ok(!wire.includes(leak), `on the wire: ${leak}`);
+    assert.deepEqual(r.cp.errorsSent, [], "the CP's contract validator accepted the frame");
+    // what agent2 (PolicyGateGuard) reads
+    assert.equal(job.record.policy.status, 200);
+    assert.deepEqual(job.record.policy.json, { decision: "ALLOW", reasonCode: "autonomous", shadow: false, approvalRequired: false, actionType: "APPLY_PATCH", requestHash: job.record.policy.requestHash, effectiveMode: "assist", policySnapshot: { hash: "d".repeat(64) } });
+    assert.equal(job.record.policy.requestHash, m.payload.requestHash, "the decision is bound to the hash agent2 sent (the one of its approval_requested)");
+    assert.equal(r.link.agent2.policyCheck.pending, 0);
+    await r.stop();
+});
+
+test("policy.check: this agent announces the capability only with the agent2 runner; the contract copy is 2.2", async () => {
+    const r = await agent2Rig({ scenario: "no_change" });
+    assert.ok(r.cp.registers[0].capabilities.includes("policy.check") && r.cp.registers[0].capabilities.includes("contract.v2.1"));
+    assert.ok(r.cp.hellos[0].capabilities.includes("policy.check"));
+    assert.ok(r.link.session.peerHas("policy.check"), "the CP listed it in ready");
+    await r.stop();
+    const off = await agent2Rig({ env: { LOCAL_AGENT_RUNNER: "", LOCAL_AGENT_JOBS: "false" }, noRunnerEnv: true, setKey: false });
+    assert.ok(!off.cp.registers[0].capabilities.includes("policy.check"), "no runner, no question to ask");
+    await off.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ the decisions
+
+test("decisions: REQUIRE_HUMAN (enforced) says approvalRequired; a shadow DENY says shadow; a DENY keeps its reason code; the CP's own codes pass through", async () => {
+    const cases = [
+        [{ decision: "REQUIRE_HUMAN", approvalRequired: true, reasonCode: "assist_mode" }, { decision: "REQUIRE_HUMAN", shadow: false, approvalRequired: true, reasonCode: "assist_mode" }],
+        [{ decision: "REQUIRE_HUMAN", shadow: true, reasonCode: "assist_mode" }, { decision: "REQUIRE_HUMAN", shadow: true, approvalRequired: false, reasonCode: "assist_mode" }],
+        [{ decision: "DENY", shadow: true, reasonCode: "assist_mode" }, { decision: "DENY", shadow: true, approvalRequired: false, reasonCode: "assist_mode" }],
+        [{ decision: "DENY", reasonCode: "rate_limited" }, { decision: "DENY", shadow: false, approvalRequired: false, reasonCode: "rate_limited" }],
+        [{ decision: "DENY", reasonCode: "not_client_mode" }, { decision: "DENY", shadow: false, approvalRequired: false, reasonCode: "not_client_mode" }],
+        [{ decision: "DENY", reasonCode: "workspace_unknown" }, { decision: "DENY", shadow: false, approvalRequired: false, reasonCode: "workspace_unknown" }],
+    ];
+    for (const [over, expected] of cases) {
+        const r = await agent2Rig({ scenario: "policy_check", policy: (m) => decisionFor(m, over) });
+        const { job } = await run(r);
+        assert.equal(job.record.policy.status, 200);
+        for (const [k, v] of Object.entries(expected)) assert.equal(job.record.policy.json[k], v, `${over.reasonCode} :: ${k}`);
+        await r.stop();
+    }
+});
+
+test("the decision agent2 gets is complete for LocalPolicyCheck.verdict (every field it requires) and carries nothing else", async () => {
+    const r = await agent2Rig({ scenario: "policy_check", policy: (m) => ({ ...decisionFor(m, { effectiveMode: "observe" }) }) });
+    const { job } = await run(r);
+    assert.deepEqual(Object.keys(job.record.policy.json).sort(), ["actionType", "approvalRequired", "decision", "effectiveMode", "policySnapshot", "reasonCode", "requestHash", "shadow"]);
+    await r.stop();
+});
+
+test("fail closed: a decision the contract would call inconsistent or incomplete is never read as an answer: 502 DENY (the session's schema check is not the only look)", async () => {
+    // the ReferenceCp does not validate what the CP sends (the LA session does), so a malformed-but-schema-valid decision cannot be built here: test the second look directly
+    const asked = { requestHash: HASH };
+    const ok = { decision: "REQUIRE_HUMAN", reasonCode: "assist_mode", shadow: false, approvalRequired: true, actionType: "APPLY_PATCH", requestHash: HASH, policySnapshot: { hash: "d".repeat(64) } };
+    assert.deepEqual(decisionBody(ok, asked), ok);
+    for (const bad of [{ approvalRequired: false }, { shadow: true }, { decision: "MAYBE" }, { reasonCode: "Bad Code" }, { requestHash: "e".repeat(64) }, { actionType: "has space" }, { policySnapshot: {} }, { policySnapshot: { hash: "z" } }, { shadow: "false" }]) {
+        assert.equal(decisionBody({ ...ok, ...bad }, asked), null, JSON.stringify(bad));
+    }
+    for (const drop of ["decision", "reasonCode", "shadow", "approvalRequired", "actionType", "requestHash", "policySnapshot"]) { const x = { ...ok }; delete x[drop]; assert.equal(decisionBody(x, asked), null, drop); }
+    assert.equal(decisionBody(null, asked), null);
+    assert.equal(decisionBody({ ...ok, junk: "x", effectiveMode: "weird" }, asked).junk, undefined);
+    assert.equal(decisionBody({ ...ok, effectiveMode: "weird" }, asked).effectiveMode, undefined);
+});
+
+// ------------------------------------------------------------------------------------------------------ fail closed
+
+test("fail closed: handleDecision with an inconsistent decision for a pending question (a session that let it through) answers 502 DENY decision_invalid, never the decision", async () => {
+    const job = { jobId: uuid(), workspaceId: "ws-1", alias: "vh-x", repoRef: { provider: "github", org: "acme", repo: "app" } };
+    let sent = null;
+    const session = { state: "ready", peerHas: () => true, enqueue: (type, payload, o) => { sent = { type, payload, o }; return Promise.resolve({ acked: new Promise(() => {}) }); } };
+    const rl = createPolicyCheckRelay({ getSession: () => session, timeoutMs: 30_000 });
+    const pending = rl.relay({ check: { actionType: "APPLY_PATCH", requestHash: HASH }, job });
+    await waitFor(() => sent !== null);
+    const inconsistent = { decision: "ALLOW", reasonCode: "autonomous", shadow: false, approvalRequired: true, actionType: "APPLY_PATCH", requestHash: HASH, policySnapshot: { hash: "d".repeat(64) } };
+    assert.deepEqual(rl.handleDecision({ requestId: sent.o.requestId, params: inconsistent }), { accept: true });
+    const out = await pending;
+    assert.deepEqual([out.status, out.json.decision, out.json.error], [502, "DENY", "decision_invalid"]);
+    assert.equal(rl.stats.invalid, 1);
+    assert.equal(rl.stats.allow, 0, "not counted as an ALLOW");
+    rl.close();
+});
+
+test("fail closed: the CP does not list policy.check -> nothing is sent and agent2 gets a 503 DENY", async () => {
+    const r = await agent2Rig({ scenario: "policy_check", cpPolicyCapability: false, policy: (m) => decisionFor(m) });
+    assert.ok(!r.link.session.peerHas("policy.check"));
+    const { job } = await run(r);
+    assert.equal(r.checks.length, 0, "no policy.check frame was sent to a CP that did not announce the capability");
+    assert.equal(job.record.policy.status, 503);
+    assert.deepEqual([job.record.policy.json.decision, job.record.policy.json.shadow, job.record.policy.json.error], ["DENY", false, "not_negotiated"]);
+    await r.stop();
+});
+
+test("fail closed: no decision in time -> 504 DENY; the late decision is dropped and counted; a decision nobody asked for is dropped too", async () => {
+    let held = null;
+    const r = await agent2Rig({ scenario: "policy_check", env: { LOCAL_AGENT_AGENT2_POLICY_TIMEOUT_MS: "1000" }, policy: (m) => { held = m; return null; } });
+    const t0 = Date.now();
+    const { job } = await run(r);
+    assert.equal(job.record.policy.status, 504);
+    assert.equal(job.record.policy.json.decision, "DENY");
+    assert.equal(job.record.policy.json.error, "timeout");
+    assert.ok(Date.now() - t0 >= 900, "it waited the configured time");
+    // the answer arrives late
+    r.cp.sendData("policy.decision", decisionFor(held), { requestId: held.requestId, workspaceId: held.workspaceId });
+    await waitFor(() => r.link.agent2.policyCheck.stats.late === 1);
+    r.cp.sendData("policy.decision", decisionFor(held), { requestId: uuid(), workspaceId: "ws-1" });
+    await waitFor(() => r.link.agent2.policyCheck.stats.late === 2);
+    assert.equal(r.link.agent2.policyCheck.pending, 0);
+    assert.deepEqual(r.cp.acksFromLa.filter((x) => x.status === "rejected"), [], "both were acked (no oracle), neither was used");
+    await r.stop();
+});
+
+test("fail closed: a decision for another request (wrong requestHash) is NOT the answer: 502 DENY at once, counted", async () => {
+    const r = await agent2Rig({ scenario: "policy_check", policy: (m) => decisionFor(m, { requestHash: HASH }) });
+    const { job } = await run(r);
+    assert.equal(job.record.policy.status, 502);
+    assert.deepEqual([job.record.policy.json.decision, job.record.policy.json.error], ["DENY", "decision_mismatch"]);
+    assert.equal(r.link.agent2.policyCheck.stats.mismatch, 1);
+    assert.ok(r.logs.some((l) => /did not match/.test(l)) && !r.logs.join("\n").includes(HASH));
+    await r.stop();
+});
+
+test("fail closed: the CP refuses the frame (ack rejected) -> a DENY at once, not after the timeout", async () => {
+    const r = await agent2Rig({ scenario: "policy_check", env: { LOCAL_AGENT_AGENT2_POLICY_TIMEOUT_MS: "20000" }, policy: null });
+    r.cp.rejectTypes["policy.check"] = "protocol_unsupported";   // like a gateway with the feature off: a stray policy.check is refused, no decision will come
+    const t0 = Date.now();
+    const { job } = await run(r);
+    assert.equal(job.record.policy.status, 503);
+    assert.match(job.record.policy.json.error, /^rejected/);
+    assert.ok(Date.now() - t0 < 5000);
+    await r.stop();
+});
+
+test("the relay in isolation: no session, not ready, not negotiated, a bad action type, too many in flight, the session closing -> DENY with a reason; never throws", async () => {
+    const job = { jobId: uuid(), workspaceId: "ws-1", alias: "vh-x", repoRef: { provider: "github", org: "acme", repo: "app", branch: "main" } };
+    const body = { actionType: "APPLY_PATCH", toolName: "apply_patch", requestHash: HASH };
+    assert.equal((await createPolicyCheckRelay({ getSession: () => null }).relay({ check: body, job })).json.error, "no_session");
+    assert.equal((await createPolicyCheckRelay({ getSession: () => ({ state: "detached", peerHas: () => true }) }).relay({ check: body, job })).json.error, "no_session");
+    assert.equal((await createPolicyCheckRelay({ getSession: () => ({ state: "ready", peerHas: () => false }) }).relay({ check: body, job })).json.error, "not_negotiated");
+    const never = { state: "ready", peerHas: () => true, enqueue: () => new Promise(() => {}) };
+    const rl = createPolicyCheckRelay({ getSession: () => never, timeoutMs: 30_000 });
+    assert.equal((await rl.relay({ check: { ...body, actionType: "has space" }, job })).status, 400);
+    assert.equal((await rl.relay({ check: null, job })).status, 400);
+    assert.equal((await rl.relay({ check: { actionType: "APPLY_PATCH" }, job })).status, 400, "no requestHash: nothing to bind a decision to");
+    const open = Array.from({ length: 16 }, () => rl.relay({ check: body, job }));
+    assert.equal(rl.pending, 16);
+    const extra = await rl.relay({ check: body, job });
+    assert.deepEqual([extra.status, extra.json.error], [429, "busy"]);
+    rl.close();
+    for (const o of await Promise.all(open)) assert.deepEqual([o.status, o.json.decision, o.json.error], [503, "DENY", "closed"]);
+    const boom = createPolicyCheckRelay({ getSession: () => ({ state: "ready", peerHas: () => true, enqueue: () => Promise.reject(Object.assign(new Error("x"), { code: "rate_limited" })) }) });
+    assert.equal((await boom.relay({ check: body, job })).json.error, "send_rate_limited");
+});
+
+// ------------------------------------------------------------------------------------------------------ the door (bridge)
+
+test("the door: only the callback token opens it; only the exact `{type:policy.check,payload}` of PR #308 is served (the hosted `{method,path,body}` shape is not); a tenant/origin/agent claim is dropped before the frame", async () => {
+    const r = await agent2Rig({ scenario: "policy", policy: (m) => decisionFor(m) });
+    const { job } = await run(r);
+    assert.equal(job.record.policy.status, 200, "the request of PR #308, as is, is answered (no 403 path_not_allowed)");
+    assert.equal(job.record.policyOtherShape.status, 403, "the hosted shape is refused");
+    assert.deepEqual(job.record.policyOtherShape.json.error.code, "path_not_allowed");
+    assert.equal(r.checks.length, 1, "only the real question reached the control plane");
+    await r.stop();
+    const seen = [];
+    const r2 = await agent2Rig({ scenario: "stuck", policy: (m) => { seen.push(m); return decisionFor(m); } });
+    const a = r2.assign(); await a.acked(); await waitFor(() => r2.fake.jobs.size === 1);
+    const h = r2.fake.jobs.get(a.p.jobId).h;
+    assert.equal((await h.policyCheck({ actionType: "X", tokenOverride: "z".repeat(43) })).status, 401);
+    assert.equal((await h.policyCheck({ actionType: "X", tokenOverride: r2.fake.jobs.get(a.p.jobId).llm.key })).status, 401, "the LLM token is not the door's");
+    const ok = await h.policyCheck({ actionType: "APPLY_PATCH", extra: { tenantId: "9d1f6a2c-0000-4000-8000-000000000000", executionOrigin: "hosted", agent: "x", workspaceId: "w" } });
+    assert.equal(ok.status, 200);
+    assert.equal(seen.length, 1);
+    assert.deepEqual(Object.keys(seen[0].payload).sort(), ["actionType", "incidentId", "jobId", "modelAlias", "repoRefs", "requestHash"]);
+    await r2.cancel(a.p.jobId);
+    await r2.stop();
+});
+
+test("the door: another job id, another repository, a malformed question, a wrong envelope -> refused with a code, NOTHING is sent to the control plane (agent2 cannot ask about what is not its job)", async () => {
+    const r = await agent2Rig({ scenario: "policy_hostile", policy: (m) => decisionFor(m) });
+    const { job } = await run(r);
+    const bad = job.record.bad;
+    const expected = { otherJob: 403, otherRepo: 403, twoRepos: 403, repoExtraKey: 400, noHash: 400, badHash: 400, badAction: 400, badTool: 400, payloadArray: 403, noPayload: 403, extraTop: 403, otherType: 403 };
+    for (const [k, status] of Object.entries(expected)) assert.equal(bad[k].status, status, k);
+    assert.equal(r.checks.length, 0, "no frame left this agent");
+    for (const k of ["otherJob", "otherRepo", "twoRepos"]) assert.equal(bad[k].json.decision, "DENY", k);
+    assert.equal(bad.otherJob.json.error, "job_mismatch");
+    assert.equal(bad.otherRepo.json.error, "repo_mismatch");
+    assert.deepEqual(r.cp.errorsSent, []);
+    await r.stop();
+});
+
+test("the question is pinned to the running job: a payload without jobId/repoRefs/modelAlias gets the job's; the job's repository is always the one asked about", async () => {
+    const r = await agent2Rig({ scenario: "stuck", policy: (m) => decisionFor(m) });
+    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.policyRaw({ type: "policy.check", payload: { actionType: "OPEN_PR", requestHash: HASH } });
+    assert.equal(res.status, 200);
+    assert.deepEqual(r.checks[0].payload, { actionType: "OPEN_PR", requestHash: HASH, repoRefs: [{ provider: "github", org: "acme", repo: "app" }], incidentId: "inc-42", jobId: a.p.jobId, modelAlias: "vh-claude-sonnet" });
+    await r.cancel(a.p.jobId);
+    await r.stop();
+});
+
+test("no running job (the job is over, its token revoked) -> 409 DENY; nothing is asked", async () => {
+    const r = await agent2Rig({ scenario: "no_change", policy: (m) => decisionFor(m) });
+    const a = r.assign(); await a.acked(); await r.done(a.p.jobId);
+    await waitFor(() => r.link.agent2.bridge.activeJobs === 0);
+    const res = await fetch(`${r.bridgeBase}/agent2/cp-request`, { method: "POST", headers: { authorization: `Bearer ${r.callbackToken}`, "content-type": "application/json" }, body: JSON.stringify({ type: "policy.check", payload: { actionType: "X", requestHash: HASH } }) });
+    assert.equal(res.status, 409);
+    assert.equal(r.checks.length, 0);
+    await r.stop();
+});
+
+test("normalizePolicyCheck: the closed payload, pinned to the job; the same job/hash binds the decision (agent2's own requestHash is used, none is invented)", () => {
+    const job = { jobId: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", workspaceId: "ws-1", alias: "vh-x", incidentId: "inc-1", repoRef: { provider: "github", org: "acme", repo: "app", branch: "main" } };
+    const ok = normalizePolicyCheck({ actionType: "RUN_SHELL_FREEFORM", toolName: "run_command", requestHash: HASH, modelAlias: "vh-OTHER", tenantId: "t", executionOrigin: "hosted" }, job);
+    assert.deepEqual(ok.payload, { actionType: "RUN_SHELL_FREEFORM", toolName: "run_command", requestHash: HASH, repoRefs: [{ provider: "github", org: "acme", repo: "app" }], incidentId: "inc-1", jobId: job.jobId, modelAlias: "vh-x" });
+    assert.equal(ok.dropped, 2);
+    assert.equal(normalizePolicyCheck({ actionType: "x y", requestHash: HASH }, job).error, "bad_action_type");
+    assert.equal(normalizePolicyCheck({ actionType: "X" }, job).error, "bad_request_hash");
+    assert.equal(normalizePolicyCheck({ actionType: "X", requestHash: "A".repeat(64) }, job).error, "bad_request_hash", "upper case is not a sha256 of the contract");
+    assert.equal(normalizePolicyCheck({ actionType: "X", requestHash: HASH, jobId: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5e" }, job).error, "job_mismatch");
+    assert.equal(normalizePolicyCheck({ actionType: "X", requestHash: HASH, repoRefs: [{ provider: "github", org: "acme", repo: "lib" }] }, job).error, "repo_mismatch");
+    assert.equal(normalizePolicyCheck({ actionType: "X", requestHash: HASH, repoRefs: [] }, job).error, "bad_repo_refs");
+    assert.equal(normalizePolicyCheck({ actionType: "X", requestHash: HASH, repoRefs: "github.com/acme/app" }, job).error, "bad_repo_refs");
+    assert.equal(normalizePolicyCheck({ actionType: "X", requestHash: HASH, repoRefs: [{ provider: "svn", org: "acme", repo: "app" }] }, job).error, "bad_repo_refs");
+    assert.equal(normalizePolicyCheck({ actionType: "X", requestHash: HASH, repoRefs: [{ provider: "github", org: "acme", repo: "app" }] }, { ...job, repoRef: undefined }).error, "repo_mismatch", "a repository on a job that has none is not asked about");
+    assert.deepEqual(normalizePolicyCheck({ actionType: "X", requestHash: HASH }, { ...job, repoRef: undefined, incidentId: undefined }).payload, { actionType: "X", requestHash: HASH, jobId: job.jobId, modelAlias: "vh-x" });
+    assert.equal(normalizePolicyCheck(null, job).error, "bad_request");
+});
+
+test("no secret, request text, path or token of the client reaches the wire, a log, an audit or a stat through the policy door", async () => {
+    const r = await agent2Rig({ scenario: "policy_check", policy: (m) => decisionFor(m) });
+    const { job } = await run(r);
+    const dump = r.everything();
+    for (const secret of [r.key, r.apiToken, r.callbackToken, job.llm.key, "SECRET-PATH-CANARY", "acme/app.git", r.root]) assert.ok(!dump.includes(secret), secret.slice(0, 16));
+    await r.stop();
+});