deepdebug-local-agent 1.3.0 → 1.5.0

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

@@ -0,0 +1,141 @@
+// F3-05b: the glue between the v1 tunnel and the v2 session, on real sockets: negotiation, fallback to v1 on the
+// same connection, v1 commands on a v2 connection, and what is (not) routed to the v2 pipeline.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ReferenceCpServer, uuid, waitFor } from "./helpers/reference-cp.js";
+import { startRig } from "./helpers/la-rig.js";
+import { isV2Frame } from "../../src/la-protocol-v2/link.js";
+
+async function withRig(srvOpts, rigOpts, body) {
+    const srv = await new ReferenceCpServer(srvOpts).start();
+    const rig = startRig(srv, rigOpts);
+    try { await body(srv, rig); } finally { await rig.stop(); await srv.stop(); }
+}
+
+test("negotiation: v2 register+hello first; the legacy register is NOT sent when the gateway speaks v2", async () => {
+    await withRig({ requireEnforce: true }, {}, async (srv, rig) => {
+        await rig.connect();
+        await waitFor(() => rig.link.mode === "v2");
+        assert.equal(rig.legacyRegisters, 0);
+        assert.equal(srv.legacy.length, 0, "no v1 frame was sent");
+        assert.deepEqual(srv.cp.registers.map((r) => r.protocol), [2]);
+    });
+});
+
+test("fallback: a gateway that ignores v2 gets the v1 register on the SAME connection after the handshake timeout", async () => {
+    await withRig({ v2Disabled: true }, { fallbackMs: 60_000 }, async (srv, rig) => {
+        await rig.connect();
+        assert.equal(rig.legacyRegisters, 0, "not yet: v2 owns the registration while it negotiates");
+        await waitFor(() => rig.legacyRegisters === 1, 2000);
+        assert.equal(rig.link.mode, "v1");
+        assert.equal(srv.connections, 1, "same connection");
+        await waitFor(() => srv.legacy.some((f) => f.type === "register" && "workspacePath" in f));
+        // v1 keeps working: a command reaches the v1 handler
+        srv.ws.send(JSON.stringify({ requestId: "r1", command: "health", params: {} }));
+        await waitFor(() => rig.v1Messages.length === 1);
+    });
+});
+
+test("fallback is remembered: the next connection goes straight to v1 (no 10 s wait per reconnect), until fallbackMs passes", async () => {
+    await withRig({ v2Disabled: true }, { fallbackMs: 150 }, async (srv, rig) => {
+        await rig.connect();
+        await waitFor(() => rig.legacyRegisters === 1, 2000);
+        rig.drop();
+        await waitFor(() => srv.closes.length === 1);
+        await rig.connect();
+        assert.equal(rig.legacyRegisters, 2, "legacy register immediately on the second connection");
+        rig.drop();
+        await waitFor(() => srv.closes.length === 2);
+        await new Promise((r) => setTimeout(r, 200)); // fallbackMs elapsed
+        await rig.connect();
+        assert.equal(rig.legacyRegisters, 2, "v2 is offered again");
+        await waitFor(() => rig.legacyRegisters === 3, 2000); // ... and falls back again after the timeout
+    });
+});
+
+test("fallback: error protocol_unsupported falls back at once, without waiting for the timeout", async () => {
+    await withRig({ refuseV2: true }, { options: { handshakeTimeoutMs: 5000 } }, async (srv, rig) => {
+        const t0 = Date.now();
+        await rig.connect();
+        await waitFor(() => rig.legacyRegisters === 1, 1500);
+        assert.ok(Date.now() - t0 < 1200, `fell back after ${Date.now() - t0} ms`);
+        assert.equal(rig.link.mode, "v1");
+        assert.equal(srv.connections, 1);
+    });
+});
+
+test("no fallback when the gateway refuses the handshake for a reason that v1 would not fix (signature_mode_insufficient)", async () => {
+    await withRig({ requireEnforce: true }, { mode: "warn", options: { handshakeTimeoutMs: 300 } }, async (srv, rig) => {
+        await rig.connect();
+        await waitFor(() => srv.cp.errorsSent.includes("signature_mode_insufficient"));
+        await new Promise((r) => setTimeout(r, 450));
+        assert.equal(rig.legacyRegisters, 0);
+    });
+});
+
+test("v1 commands keep working on a v2 connection: they reach the existing handler, not the v2 pipeline", async () => {
+    await withRig({ requireEnforce: true }, {}, async (srv, rig) => {
+        await rig.connect();
+        await waitFor(() => rig.link.mode === "v2");
+        const cmd = srv.cp.v1Command("health", {});
+        srv.ws.send(cmd);
+        await waitFor(() => rig.v1Messages.length === 1);
+        assert.equal(rig.v1Messages[0], cmd);
+        assert.deepEqual(srv.cp.peerErrors, []);
+        assert.equal(rig.session.stats.framesIn, 1, "only the ready went through the v2 pipeline");
+        // and v2 is unaffected
+        await rig.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" });
+    });
+});
+
+test("routing: anything that claims schemaVersion goes to the v2 pipeline (and is refused if wrong); everything else is v1's business", async () => {
+    await withRig({ requireEnforce: true }, {}, async (srv, rig) => {
+        await rig.connect();
+        await waitFor(() => rig.link.mode === "v2");
+        srv.ws.send("not json at all");
+        srv.ws.send(JSON.stringify({ type: "something-v1-only" }));
+        await waitFor(() => rig.v1Messages.length === 2);
+        assert.deepEqual(srv.cp.peerErrors, []);
+        srv.ws.send(JSON.stringify({ schemaVersion: 2, type: "shell.exec" }));
+        await waitFor(() => srv.cp.peerErrors.length === 1);
+        assert.deepEqual(srv.cp.peerErrors, ["unknown_type"]);
+        await waitFor(() => srv.closes.includes(4401));
+    });
+});
+
+test("routing: a binary frame is dropped by the v2 pipeline, never handed to the v1 handler", async () => {
+    await withRig({ requireEnforce: true }, {}, async (srv, rig) => {
+        await rig.connect();
+        await waitFor(() => rig.link.mode === "v2");
+        srv.ws.send(Buffer.from([0, 1, 2]), { binary: true });
+        await waitFor(() => rig.session.stats.nonText === 1);
+        assert.equal(rig.v1Messages.length, 0);
+    });
+});
+
+test("isV2Frame: schemaVersion present = v2; a v1 command, text and arrays are not; an oversized frame is judged by its head", () => {
+    assert.equal(isV2Frame('{"schemaVersion":2,"type":"x"}', 49152), true);
+    assert.equal(isV2Frame('{"schemaVersion":1}', 49152), true, "a wrong version is still a v2 attempt (and gets refused)");
+    assert.equal(isV2Frame('{"requestId":"r","command":"health","params":{}}', 49152), false);
+    assert.equal(isV2Frame('["schemaVersion"]', 49152), false);
+    assert.equal(isV2Frame("pong", 49152), false);
+    assert.equal(isV2Frame(`{"schemaVersion":2,"pad":"${"x".repeat(60_000)}"}`, 49152), true);
+    assert.equal(isV2Frame(`{"requestId":"r","command":"workspace.safe-patch","params":{"diff":"${"x".repeat(60_000)}"}}`, 49152), false);
+});
+
+test("the link survives a reconnect with the session intact (resume offered on the new socket)", async () => {
+    await withRig({ requireEnforce: true }, {}, async (srv, rig) => {
+        await rig.connect();
+        await waitFor(() => rig.link.mode === "v2");
+        await rig.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" });
+        const sid = rig.session.sessionId;
+        rig.drop();
+        await waitFor(() => rig.session.state === "detached");
+        await rig.connect();
+        await waitFor(() => rig.link.mode === "v2" && rig.session.state === "ready");
+        assert.equal(rig.session.sessionId, sid);
+        assert.equal(srv.cp.registers.at(-1).resume.sessionId, sid);
+        assert.equal(rig.legacyRegisters, 0);
+        assert.ok(uuid());
+    });
+});

package/test/la-protocol-v2/session-inbound.test.js

@@ -0,0 +1,279 @@
+// F3-05b: what the Local Agent does with a frame from the control plane. No sockets: the session is wired to a
+// ReferenceCp in memory, so the order of events is deterministic. Every refusal must carry only the wire code.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import { ReferenceCp, TENANT, AGENT, uuid, waitFor, newKeyPair } from "./helpers/reference-cp.js";
+import { inMemory, signingFor } from "./helpers/la-rig.js";
+import { closeCodeOf } from "../../src/la-protocol-v2/errors.js";
+
+const SECRET = "CLIENT_SECRET_MARKER_5521";
+const JOB = "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f";
+
+async function ready(opts = {}) {
+    const cp = new ReferenceCp(opts.cp);
+    const env = inMemory(cp, opts.la).start();
+    await waitFor(() => env.session.state === "ready");
+    return { cp, ...env };
+}
+const errorsFromLa = (env) => env.wire.toCp.map((t) => JSON.parse(t)).filter((f) => f.type === "error").map((f) => f.payload);
+const sentText = (env) => env.wire.toCp.join("\n");
+const close = (env) => env.session.close();
+
+test("handshake: register then hello, a signed ready is verified (enforce) and the session is ready", async () => {
+    const env = await ready({ cp: { requireEnforce: true } });
+    assert.equal(env.session.state, "ready");
+    assert.equal(env.cp.registers[0].signatureMode, "enforce");
+    assert.equal(env.cp.hellos[0].signatureMode, "enforce");
+    assert.equal(env.session.sessionId, env.cp.sessionId);
+    close(env);
+});
+
+const BAD_FRAMES = [
+    // [name, build(cp) -> text, expected code]
+    ["a type outside the allowlist", (cp) => JSON.stringify({ ...cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }), type: "shell.exec" }), "unknown_type"],
+    ["a v1 command name used as a type", (cp) => JSON.stringify({ ...cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }), type: "mcp.execute-command" }), "unknown_type"],
+    ["a la->cp type sent by the CP", (cp) => JSON.stringify({ schemaVersion: 2, type: "job.event", msgId: uuid(), seq: 1, tenantId: TENANT, agentId: AGENT, workspaceId: "", ts: new Date().toISOString(), payload: { jobId: JOB, state: "running" } }), "wrong_direction"],
+    ["JSON that does not parse", () => "{not json " + SECRET, "bad_frame"],
+    ["a duplicate key", () => `{"schemaVersion":2,"schemaVersion":2,"note":"${SECRET}"}`, "bad_frame"],
+    ["a JSON array", () => `["${SECRET}"]`, "bad_frame"],
+    ["a frame above 48 KiB", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); return JSON.stringify(f) + " ".repeat(50_000); }, "frame_too_large"],
+    ["an extra top-level field", (cp) => JSON.stringify({ ...cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }), extra: SECRET }), "schema_violation"],
+    ["an extra payload field", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); f.payload.note = SECRET; return JSON.stringify(f); }, "schema_violation"],
+    ["schemaVersion 1", (cp) => JSON.stringify({ ...cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }), schemaVersion: 1 }), "schema_violation"],
+    ["another tenant", (cp) => JSON.stringify({ ...cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }), tenantId: "99999999-5a4d-4e7b-9c21-0a1b2c3d4e5f" }), "tenant_mismatch"],
+    ["another agent", (cp) => JSON.stringify({ ...cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }), agentId: "99999999-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }), "agent_mismatch"],
+    ["paramsRaw different from payload", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); f.paramsRaw = JSON.stringify({ jobId: JOB, reason: "ops" }); return JSON.stringify(f); }, "params_mismatch"],
+    ["paramsRaw with a duplicate key", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); f.paramsRaw = `{"jobId":"${JOB}","reason":"user","reason":"user"}`; return JSON.stringify(f); }, "params_mismatch"],
+    ["sig bound to another tenant", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); f.sig.tenantId = "99999999-5a4d-4e7b-9c21-0a1b2c3d4e5f"; return JSON.stringify(f); }, "tenant_mismatch"],
+    ["sig bound to another workspace", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); f.sig.workspaceId = "other-ws"; return JSON.stringify(f); }, "tenant_mismatch"],
+    ["a bad signature (enforce)", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); f.sig.signature = Buffer.alloc(64, 7).toString("base64"); return JSON.stringify(f); }, "unauthorized"],
+    ["a signature of another key id", (cp) => { const f = cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }); f.sig.keyId = "unknown-key"; return JSON.stringify(f); }, "unauthorized"],
+    ["a seq gap", (cp) => { cp.cpSeq += 4; return JSON.stringify(cp.frameWith("job.cancel", { jobId: JOB, reason: "user" })); }, "seq_gap"],
+    ["a second ready", (cp) => { const f = cp.frameWith("config.update", { retentionDays: 7 }); f.type = "ready"; f.seq = 0; f.payload = { protocol: 2, sessionId: uuid(), resumed: false, peerLastSeq: 0, limits: { maxFrameBytes: 49152, chunkRawBytes: 32768, maxChunks: 64, ackTimeoutMs: 5000, maxRetries: 3, heartbeatSeconds: 30 } }; f.paramsRaw = JSON.stringify(f.payload); return JSON.stringify(f); }, "handshake_violation"],
+];
+
+for (const [name, build, code] of BAD_FRAMES) {
+    test(`inbound: ${name} -> error ${code}, close ${closeCodeOf(code)}, nothing of the content comes back`, async () => {
+        const env = await ready();
+        env.cp.sendRaw(build(env.cp));
+        await waitFor(() => errorsFromLa(env).length > 0);
+        const err = errorsFromLa(env)[0];
+        assert.equal(err.code, code);
+        assert.equal(err.closeCode, closeCodeOf(code));
+        assert.deepEqual(Object.keys(err).filter((k) => !["code", "retryable", "closeCode", "refSeq", "refMsgId"].includes(k)), []);
+        assert.equal(sentText(env).includes(SECRET), false, "the error frame echoed content");
+        assert.equal(env.logs.join("\n").includes(SECRET), false, "the log carries content");
+        await waitFor(() => env.wire.closed.length > 0);
+        assert.equal(env.wire.closed[0][0], closeCodeOf(code));
+        close(env);
+    });
+}
+
+test("inbound: a replayed nonce is refused (unauthorized): the same signed bytes cannot be sent twice", async () => {
+    const env = await ready();
+    const f = env.cp.frameWith("job.cancel", { jobId: JOB, reason: "user" });
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    env.cp.sendRaw(JSON.stringify(f));
+    await waitFor(() => env.cp.acksFromLa.length >= 1);
+    // same signature/nonce on a NEW seq: the nonce was already consumed
+    const g = { ...f, seq: f.seq + 1, msgId: uuid() };
+    env.cp.sendRaw(JSON.stringify(g));
+    await waitFor(() => errorsFromLa(env).length > 0);
+    assert.equal(errorsFromLa(env)[0].code, "unauthorized");
+    close(env);
+});
+
+test("inbound: seq_replayed (same seq, another msgId) carries refSeq and refMsgId", async () => {
+    const env = await ready();
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    const f = env.cp.frameWith("job.cancel", { jobId: JOB, reason: "user" });
+    env.cp.sendRaw(JSON.stringify(f));
+    await waitFor(() => env.cp.acksFromLa.length >= 1);
+    const other = env.cp.frameWith("job.cancel", { jobId: JOB, reason: "user" });
+    other.seq = f.seq; // same seq, another msgId
+    env.cp.sendRaw(JSON.stringify(other));
+    await waitFor(() => errorsFromLa(env).length > 0);
+    const e = errorsFromLa(env)[0];
+    assert.equal(e.code, "seq_replayed");
+    assert.equal(e.refSeq, f.seq);
+    assert.equal(e.refMsgId, other.msgId);
+    close(env);
+});
+
+test("inbound: before ready only ready/error/ack are accepted (not_ready)", async () => {
+    const cp = new ReferenceCp();
+    const env = inMemory(cp);
+    // attach without letting the CP answer: use a transport that swallows the register/hello
+    const swallow = { send() {}, close() {}, bufferedAmount: () => 0 };
+    env.session.attach(swallow);
+    env.session.handleText(JSON.stringify(cp.frameWith("job.cancel", { jobId: JOB, reason: "user" })), swallow);
+    await waitFor(() => env.session.stats.rejectedIn.not_ready === 1);
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ signature modes
+
+test("signature modes: warn and off accept a bad signature, enforce refuses it; hello reports the mode", async () => {
+    for (const [mode, accepted] of [["warn", true], ["off", true], ["enforce", false]]) {
+        const env = await ready({ la: { mode } });
+        assert.equal(env.cp.hellos[0].signatureMode, mode);
+        let ran = 0;
+        env.session.setHandler("job.cancel", () => { ran++; return { accept: true }; });
+        const f = env.cp.frameWith("job.cancel", { jobId: JOB, reason: "user" });
+        f.sig.signature = Buffer.alloc(64, 9).toString("base64");
+        env.cp.sendRaw(JSON.stringify(f));
+        if (accepted) {
+            await waitFor(() => ran === 1);
+            assert.equal(errorsFromLa(env).length, 0, mode);
+        } else {
+            await waitFor(() => errorsFromLa(env).length === 1);
+            assert.equal(ran, 0);
+        }
+        close(env);
+    }
+});
+
+test("signature: the signed text is what runs (handler gets the parsed paramsRaw)", async () => {
+    const env = await ready();
+    let got;
+    env.session.setHandler("job.cancel", (ctx) => { got = ctx; return { accept: true }; });
+    env.cp.sendRaw(JSON.stringify(env.cp.frameWith("job.cancel", { jobId: JOB, reason: "user" }, { requestId: uuid() })));
+    await waitFor(() => got);
+    assert.deepEqual(got.params, { jobId: JOB, reason: "user" });
+    assert.equal(got.type, "job.cancel");
+    assert.equal(got.seq, 1);
+    assert.throws(() => { got.type = "x"; }, TypeError, "the context handed to a handler is frozen");
+    close(env);
+});
+
+test("signature: a key the LA does not trust (rotation) is refused in the ready itself", async () => {
+    const cp = new ReferenceCp();
+    const other = newKeyPair();
+    const env = inMemory(cp, { signing: signingFor({ keyId: cp.keyId, publicKeyRaw: other.publicKeyRaw }, "enforce") }).start();
+    await waitFor(() => cp.peerErrors.length > 0);
+    assert.deepEqual(cp.peerErrors, ["unauthorized"]);
+    assert.notEqual(env.session.state, "ready");
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ acks and handlers
+
+test("ack: no handler -> rejected protocol_unsupported; the seq is still consumed", async () => {
+    const env = await ready();
+    env.cp.sendData("job.assign", { jobId: JOB, kind: "fix", repoRef: { provider: "github", org: "acme", repo: "billing", branch: "main" },
+        policy: { operationMode: "assist", automationLevel: 2, ceiling: "autonomous" }, budget: { tokens: 1000, seconds: 60 }, llm: { alias: "vh-coder", keyRef: "key-la-1" } });
+    env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => env.cp.acksFromLa.length >= 2);
+    assert.deepEqual(env.cp.acksFromLa.map((a) => [a.ackSeq, a.status, a.errorCode]), [[1, "rejected", "protocol_unsupported"], [2, "rejected", "protocol_unsupported"]]);
+    assert.equal(env.session.lastRecvSeq, 2);
+    assert.equal(env.cp.unacked.size, 0, "a rejected ack settles the frame at the CP");
+    close(env);
+});
+
+test("ack: a handler decides accepted / rejected / throws / is slow; every verdict is one ack", async () => {
+    const env = await ready({ la: { options: { handlerAckMs: 80 } } });
+    const verdicts = [{ accept: true }, { reject: "rate_limited" }, "throw", "slow"];
+    let i = 0;
+    env.session.setHandler("job.cancel", () => {
+        const v = verdicts[i++];
+        if (v === "throw") throw new Error("boom " + SECRET);
+        if (v === "slow") return new Promise((r) => setTimeout(() => r({ reject: "internal" }), 400));
+        return v;
+    });
+    for (let n = 0; n < 4; n++) env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => env.cp.acksFromLa.length >= 4);
+    assert.deepEqual(env.cp.acksFromLa.map((a) => [a.ackSeq, a.status, a.errorCode]),
+        [[1, "accepted", undefined], [2, "rejected", "rate_limited"], [3, "rejected", "internal"], [4, "accepted", undefined]]);
+    assert.equal(sentText(env).includes(SECRET), false);
+    close(env);
+});
+
+test("dedupe: a retransmission (same seq and msgId, fresh signature) is re-acked as duplicate and NEVER runs twice", async () => {
+    const env = await ready();
+    let ran = 0;
+    env.session.setHandler("job.cancel", () => { ran++; return { accept: true }; });
+    const seq = env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => env.cp.acksFromLa.length >= 1);
+    // the CP never saw the ack: it sends the frame again (what its retransmission timer does, re-signed)
+    const u = [...env.wire.toLa].map((t) => JSON.parse(t)).find((f) => f.type === "job.cancel");
+    env.cp.cpSeq = seq; // keep numbering; re-render the same seq/msgId with a fresh nonce
+    const again = env.cp.frameWith("job.cancel", { jobId: JOB, reason: "user" });
+    again.seq = u.seq; again.msgId = u.msgId;
+    env.cp.sendRaw(JSON.stringify(again));
+    await waitFor(() => env.cp.acksFromLa.length >= 2);
+    assert.equal(ran, 1);
+    assert.deepEqual(env.cp.acksFromLa.map((a) => a.status), ["accepted", "duplicate"]);
+    assert.equal(env.session.stats.duplicatesIn, 1);
+    assert.equal(errorsFromLa(env).length, 0);
+    close(env);
+});
+
+test("dedupe: the last 512 seq->msgId pairs are kept (the 513th old one is a replay)", async () => {
+    const env = await ready();
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    for (let n = 0; n < 520; n++) env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => env.session.lastRecvSeq === 520, 8000);
+    assert.equal(env.session.recvRing.size, 512);
+    close(env);
+});
+
+test("a piggy-backed ack field on a CP frame settles our frames", async () => {
+    const env = await ready();
+    env.cp.silent = true; // the CP does not send ack frames
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    const h = await env.session.enqueue("job.event", { jobId: JOB, state: "running" });
+    assert.equal(env.session.unacked.size, 1);
+    env.cp.laSeq = 1; // CP has the frame
+    env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" }); // carries ack:1
+    await h.acked;
+    assert.equal(env.session.unacked.size, 0);
+    close(env);
+});
+
+test("a rejected ack from the CP fails that frame with the code and releases the others", async () => {
+    const env = await ready();
+    env.cp.silent = true;
+    const a = await env.session.enqueue("job.event", { jobId: JOB, state: "running" });
+    const b = await env.session.enqueue("job.event", { jobId: JOB, state: "running" });
+    const c = await env.session.enqueue("job.event", { jobId: JOB, state: "succeeded" });
+    const f = env.cp.frameWith("ack", { ackSeq: 2, status: "rejected", errorCode: "rate_limited" });
+    f.type = "ack"; f.seq = 0; delete f.paramsRaw; delete f.sig; f.workspaceId = "";
+    env.cp.sendRaw(JSON.stringify(f));
+    await a.acked;
+    await assert.rejects(b.acked, (e) => e.code === "rate_limited");
+    assert.equal(env.session.unacked.has(3), true);
+    void c;
+    close(env);
+});
+
+test("an ack for a frame we never sent is ignored", async () => {
+    const env = await ready();
+    const f = { schemaVersion: 2, type: "ack", msgId: uuid(), seq: 0, tenantId: TENANT, agentId: AGENT, workspaceId: "", ts: new Date().toISOString(), payload: { ackSeq: 99, status: "accepted" } };
+    env.cp.sendRaw(JSON.stringify(f));
+    await new Promise((r) => setTimeout(r, 30));
+    assert.equal(errorsFromLa(env).length, 0);
+    assert.equal(env.session.state, "ready");
+    close(env);
+});
+
+test("inbound queue is bounded (maxInboundQueue): the overflow is answered rate_limited, the session survives", async () => {
+    const env = await ready({ la: { options: { maxInboundQueue: 2 } } });
+    env.session.setHandler("job.cancel", () => new Promise((r) => setTimeout(() => r({ accept: true }), 50)));
+    for (let n = 0; n < 6; n++) env.cp.sendRaw(JSON.stringify(env.cp.frameWith("job.cancel", { jobId: JOB, reason: "user" })));
+    await waitFor(() => errorsFromLa(env).some((e) => e.code === "rate_limited"));
+    assert.equal(env.wire.closed.length, 0, "rate_limited is not fatal");
+    close(env);
+});
+
+test("binary frames from the CP are dropped and counted, never parsed", async () => {
+    const env = await ready();
+    env.session.handleText("\u0000\u0001", env.transport, true);
+    assert.equal(env.session.stats.nonText, 1);
+    assert.equal(errorsFromLa(env).length, 0);
+    close(env);
+});
+
+test("sanity: the helper crypto is real (an Ed25519 signature over the v1 canonical string)", () => {
+    assert.equal(crypto.getHashes().includes("sha256"), true);
+});