deepdebug-local-agent 1.2.0 → 1.4.0

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);
+});

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

@@ -0,0 +1,382 @@
+// F3-05b: what the Local Agent sends, and what it does about acks, loss, backpressure and resume.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import { ReferenceCp, ReferenceCpServer, TENANT, AGENT, uuid, waitFor } from "./helpers/reference-cp.js";
+import { inMemory, startRig } from "./helpers/la-rig.js";
+import { sendContent, sendContentFailure } from "../../src/la-protocol-v2/content.js";
+import { loadContract } from "../../src/la-protocol-v2/contract.js";
+
+const JOB = "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f";
+const REQ = "d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f80";
+const ev = (state = "running", extra = {}) => ({ jobId: JOB, state, ...extra });
+const contract = loadContract();
+
+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 };
+}
+
+// ------------------------------------------------------------------------------------------ envelope and numbering
+
+test("outbound: every frame is closed, schema-valid, carries the configured tenant/agent and consecutive seq", async () => {
+    const env = await ready();
+    for (let i = 0; i < 5; i++) await env.session.send("job.event", ev("running", { iteration: i }));
+    await env.session.send("alert", { code: "disk_low", severity: "warn" }).catch(() => {});
+    const frames = env.wire.toCp.map((t) => JSON.parse(t));
+    for (const f of frames) {
+        assert.deepEqual(contract.validateFrame(f), { ok: true }, f.type);
+        assert.equal(f.tenantId, TENANT);
+        assert.equal(f.agentId, AGENT);
+        assert.equal(f.schemaVersion, 2);
+        assert.match(f.msgId, /^[0-9a-f-]{36}$/);
+        assert.equal("sig" in f || "paramsRaw" in f, false, "LA frames are never signed");
+    }
+    assert.deepEqual(frames.filter((f) => f.type === "register" || f.type === "hello").map((f) => f.seq), [0, 0]);
+    assert.deepEqual(env.cp.received.filter((f) => f.type === "job.event").map((f) => f.seq), [1, 2, 3, 4, 5]);
+    assert.equal(new Set(env.cp.received.map((f) => f.msgId)).size, env.cp.received.length, "msgId is unique per frame");
+    env.session.close();
+});
+
+test("outbound: our frames piggyback ack = highest contiguous CP seq received", async () => {
+    const env = await ready();
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => env.session.lastRecvSeq === 2);
+    await env.session.send("job.event", ev());
+    assert.equal(env.cp.received.at(-1).ack, 2);
+    env.session.close();
+});
+
+test("outbound: heartbeat frames go out on their own, with mode/clock/disk/queue (no paths, no content)", async () => {
+    const env = await ready({ la: { options: { heartbeatMs: 40 } } });
+    await waitFor(() => env.cp.received.filter((f) => f.type === "heartbeat").length >= 2);
+    const hb = env.cp.received.find((f) => f.type === "heartbeat");
+    assert.deepEqual(Object.keys(hb.payload).sort(), ["clockEpochMs", "diskFreeBytes", "inflight", "queueDepth", "signatureMode"]);
+    assert.equal(hb.payload.diskFreeBytes, 1234);
+    assert.equal(hb.payload.signatureMode, "enforce");
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ refusals before a byte is written
+
+const REFUSED = [
+    ["a type outside the allowlist", "shell.exec", {}, "unknown_type"],
+    ["a v1 command name", "mcp.execute-command", {}, "unknown_type"],
+    ["a cp->la type", "job.assign", {}, "wrong_direction"],
+    ["a session type (register)", "register", {}, "wrong_direction"],
+    ["a field the schema does not know", "job.event", ev("running", { stack: "x" }), "schema_violation"],
+    ["a state outside the enum", "job.event", ev("exploded"), "schema_violation"],
+    ["a string above its maxLength", "job.result", { jobId: JOB, outcome: "pr_opened", prUrl: "https://example.com/" + "a".repeat(600) }, "payload_too_large"],
+];
+for (const [name, type, payload, code] of REFUSED) {
+    test(`outbound refusal: ${name} -> ${code}, nothing is written`, async () => {
+        const env = await ready();
+        const before = env.wire.toCp.length;
+        await assert.rejects(env.session.enqueue(type, payload), (e) => e.code === code);
+        assert.equal(env.wire.toCp.length, before);
+        assert.equal(env.session.sendSeq, 0, "a refused frame does not consume a seq");
+        env.session.close();
+    });
+}
+
+test("outbound refusal: before the first ready nothing can be sent (not_ready)", async () => {
+    const cp = new ReferenceCp();
+    const env = inMemory(cp);
+    await assert.rejects(env.session.enqueue("job.event", ev()), (e) => e.code === "not_ready");
+    env.session.close();
+});
+
+test("outbound refusal: the send queue is bounded (rate_limited)", async () => {
+    const env = await ready({ cp: { }, la: { options: { maxInFlight: 1, maxQueued: 3 } } });
+    env.cp.silent = true;
+    const ps = [];
+    for (let i = 0; i < 6; i++) ps.push(env.session.enqueue("job.event", ev()).then(() => "ok", (e) => e.code));
+    const res = await Promise.race([Promise.all(ps), new Promise((r) => setTimeout(() => r(null), 100))]);
+    assert.equal(res, null, "waiting frames keep waiting");
+    const refused = await Promise.all(ps.slice(-2));
+    assert.deepEqual(refused, ["rate_limited", "rate_limited"]);
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ acks, loss, backpressure
+
+test("backpressure: at most maxInFlight frames unacked, the rest wait; when acks resume everything arrives once and in order", async () => {
+    const env = await ready({ cp: { limits: { ackTimeoutMs: 150, maxRetries: 3 } }, la: { options: { maxInFlight: 3 } } });
+    env.cp.silent = true; // acks lost
+    const all = [];
+    for (let i = 0; i < 10; i++) all.push(env.session.send("job.event", ev("running", { iteration: i })));
+    await waitFor(() => env.cp.received.length === 3);
+    await new Promise((r) => setTimeout(r, 40));
+    assert.equal(env.cp.received.length, 3, "never more than maxInFlight on the wire");
+    assert.equal(env.session.snapshot.waiting, 7);
+    assert.equal(env.session.snapshot.unacked, 3);
+    env.cp.silent = false; // the retransmissions of 1..3 are now acked (as duplicates)
+    await Promise.all(all);
+    assert.deepEqual(env.cp.received.map((f) => f.payload.iteration), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    assert.deepEqual(env.cp.received.map((f) => f.seq), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+    assert.ok(env.session.stats.retransmits >= 1, "the lost acks forced a retransmission (cumulative acks settle the rest)");
+    env.session.close();
+});
+
+test("ack lost: the SAME bytes (same seq and msgId) are sent again, the CP sees a duplicate, the caller's ack resolves", async () => {
+    const env = await ready({ cp: { limits: { ackTimeoutMs: 100 } } });
+    env.cp.dropAcks = 1;
+    await env.session.send("job.event", ev());
+    const copies = env.wire.toCp.filter((t) => t.includes('"job.event"'));
+    assert.equal(copies.length, 2);
+    assert.equal(copies[0], copies[1], "a retransmission is byte-identical");
+    assert.deepEqual(env.cp.duplicates, [1]);
+    assert.equal(env.cp.received.length, 1);
+    assert.equal(env.session.stats.retransmits, 1);
+    env.session.close();
+});
+
+test("retries exhausted: the caller gets timeout, the connection is closed with 4420, the frame is kept for a resume", async () => {
+    const env = await ready({ cp: { limits: { ackTimeoutMs: 100, maxRetries: 2 } } });
+    env.cp.silent = true;
+    const h = await env.session.enqueue("job.event", ev());
+    await assert.rejects(h.acked, (e) => e.code === "timeout");
+    assert.deepEqual(env.wire.closed[0], [4420, "ack_timeout"]);
+    assert.equal(env.session.stats.retransmits, 2);
+    assert.equal(env.session.state, "detached");
+    assert.equal(env.session.unacked.size, 1, "kept for the resume");
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ content (chunking)
+
+const bytesOf = (n) => crypto.randomBytes(n);
+
+test("chunking: 100 KiB goes out as 4 ordered chunks, each <= 32 KiB raw, each frame <= 48 KiB, and the CP rebuilds it exactly", async () => {
+    const env = await ready();
+    const data = bytesOf(100 * 1024);
+    const r = await sendContent(env.session, { requestId: REQ, source: data, contentType: "application/octet-stream" });
+    assert.deepEqual(r, { chunks: 4, bytes: data.length });
+    const frames = env.cp.received.filter((f) => f.type === "content.response");
+    assert.deepEqual(frames.map((f) => f.chunk), [0, 1, 2, 3].map((index) => ({ index, total: 4, last: index === 3 })));
+    assert.deepEqual(frames.map((f) => f.payload.byteLength), [32768, 32768, 32768, 4096]);
+    assert.ok(env.cp.rawIn.every((t) => Buffer.byteLength(t) <= 49152));
+    assert.ok(Math.max(...env.cp.rawIn.map((t) => Buffer.byteLength(t))) > 43692, "a full chunk really is that big");
+    assert.equal(frames[0].requestId, REQ);
+    assert.ok(frames.every((f) => f.payload.totalBytes === data.length && f.payload.encoding === "base64"));
+    const c = env.cp.contentRequests.get(REQ);
+    assert.equal(c.done, true);
+    assert.ok(Buffer.concat(c.chunks).equals(data));
+    assert.deepEqual(env.cp.errorsSent, []);
+    env.session.close();
+});
+
+test("chunking: exactly 2 MiB = 64 chunks is accepted, 2 MiB + 1 is refused before a single chunk is sent", async () => {
+    const env = await ready();
+    const max = bytesOf(2 * 1024 * 1024);
+    const r = await sendContent(env.session, { requestId: REQ, source: max });
+    assert.equal(r.chunks, 64);
+    assert.ok(Buffer.concat(env.cp.contentRequests.get(REQ).chunks).equals(max));
+    const before = env.wire.toCp.length;
+    await assert.rejects(sendContent(env.session, { requestId: uuid(), source: bytesOf(2 * 1024 * 1024 + 1) }), (e) => e.code === "payload_too_large");
+    assert.equal(env.wire.toCp.length, before);
+    env.session.close();
+});
+
+test("chunking: empty content is one empty chunk; a failure answer is one empty chunk with the status", async () => {
+    const env = await ready();
+    await sendContent(env.session, { requestId: REQ, source: Buffer.alloc(0), contentType: "text/plain" });
+    const rid2 = uuid();
+    await sendContentFailure(env.session, { requestId: rid2, status: "not_found", errorCode: "internal" });
+    const [a, b] = env.cp.received;
+    assert.deepEqual(a.chunk, { index: 0, total: 1, last: true });
+    assert.equal(a.payload.data, "");
+    assert.equal(b.payload.status, "not_found");
+    assert.deepEqual(b.chunk, { index: 0, total: 1, last: true });
+    env.session.close();
+});
+
+test("chunking + backpressure: with a slow CP never more than maxInFlight chunks are unacked", async () => {
+    const env = await ready({ cp: { }, la: { options: { maxInFlight: 3 } } });
+    env.cp.ackDelayMs = 15;
+    let maxUnacked = 0;
+    env.cp.onReceived = () => { maxUnacked = Math.max(maxUnacked, env.session.unacked.size); };
+    const data = bytesOf(40 * 32768);
+    await sendContent(env.session, { requestId: REQ, source: data });
+    assert.ok(maxUnacked <= 3 && maxUnacked >= 2, `max unacked ${maxUnacked}`);
+    assert.ok(Buffer.concat(env.cp.contentRequests.get(REQ).chunks).equals(data));
+    assert.equal(env.session.stats.retransmits, 0);
+    env.session.close();
+});
+
+test("chunking is lazy: the next chunk is not read until a slot opens (bounded memory)", async () => {
+    const env = await ready({ la: { options: { maxInFlight: 2 } } });
+    env.cp.silent = true;
+    let reads = 0;
+    const source = { size: 10 * 32768, async read(offset, length) { reads++; return Buffer.alloc(length, 1); } };
+    const p = sendContent(env.session, { requestId: REQ, source });
+    p.catch(() => {});
+    await waitFor(() => env.cp.received.length === 2);
+    await new Promise((r) => setTimeout(r, 60));
+    assert.ok(reads <= 3, `read ${reads} chunks while only 2 can be in flight`);
+    env.session.close();
+    await assert.rejects(p);
+});
+
+test("chunking: cancelling (AbortSignal) stops reading and drops the chunks still waiting", async () => {
+    const env = await ready({ la: { options: { maxInFlight: 2 } } });
+    env.cp.ackDelayMs = 30;
+    const ac = new AbortController();
+    let reads = 0;
+    const source = { size: 20 * 32768, async read(o, l) { reads++; if (reads === 4) ac.abort(); return Buffer.alloc(l, 2); } };
+    await assert.rejects(sendContent(env.session, { requestId: REQ, source, signal: ac.signal }), (e) => e.code === "agent_offline");
+    assert.ok(reads <= 5);
+    assert.equal(env.session.snapshot.waiting, 0);
+    env.session.close();
+});
+
+// the chunk rules of the contract applied to what we send (the invalid-chunk-* traces, from the sender's side)
+const CHUNK = (data = Buffer.alloc(26, 1)) => ({ status: "ok", contentType: "text/plain", encoding: "base64", data: data.toString("base64"), byteLength: data.length });
+const BAD_CHUNKS = [
+    ["out of order (0 then 2)", [[0, 3, false], [2, 3, true]], "chunk_out_of_order"],
+    ["after last", [[0, 1, true], [1, 2, true]], "chunk_out_of_order"],
+    ["total changes mid-stream", [[0, 3, false], [1, 4, false]], "chunk_inconsistent"],
+    ["last on the wrong index", [[0, 3, false], [1, 3, true]], "chunk_inconsistent"],
+    ["last missing on the last index", [[0, 1, false]], "chunk_inconsistent"],
+    ["a stream that does not start at 0", [[1, 3, false]], "chunk_out_of_order"],
+];
+for (const [name, steps, code] of BAD_CHUNKS) {
+    test(`chunk rules on send: ${name} -> ${code}`, async () => {
+        const env = await ready();
+        let got = null;
+        for (const [index, total, last] of steps) {
+            try { await env.session.send("content.response", CHUNK(), { requestId: uuid() === "" ? "" : REQ, chunk: { index, total, last } }); }
+            catch (e) { got = e.code; break; }
+        }
+        assert.equal(got, code);
+        env.session.close();
+    });
+}
+
+test("chunk rules on send: byteLength must equal the decoded size; data above 32 KiB raw is refused", async () => {
+    const env = await ready();
+    const p = CHUNK();
+    p.byteLength = 27;
+    await assert.rejects(env.session.send("content.response", p, { requestId: REQ, chunk: { index: 0, total: 1, last: true } }), (e) => e.code === "chunk_inconsistent");
+    const big = bytesOf(32769);
+    await assert.rejects(env.session.send("content.response", { ...CHUNK(big) }, { requestId: uuid(), chunk: { index: 0, total: 1, last: true } }),
+        (e) => ["payload_too_large", "schema_violation", "chunk_inconsistent"].includes(e.code));
+    assert.equal(env.cp.received.length, 0);
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ resume (real sockets)
+
+// every ws test runs inside withRig: sockets and servers are closed even when an assertion throws
+async function withRig(opts, body) {
+    const srv = await new ReferenceCpServer({ requireEnforce: true, ...(opts.cp || {}) }).start();
+    const rig = startRig(srv, opts.rig);
+    try {
+        await rig.connect();
+        await waitFor(() => rig.session.state === "ready");
+        await body({ srv, rig });
+    } finally {
+        await rig.stop();
+        await srv.stop();
+    }
+}
+
+test("resume: after a dropped socket the LA offers {sessionId,lastRecvSeq}, continues numbering, and the CP gets one copy of everything", async () => {
+    await withRig({}, async ({ srv, rig }) => {
+    rig.session.setHandler("job.cancel", () => ({ accept: true }));
+    await rig.session.send("job.event", ev("running", { iteration: 1 }));
+    await rig.session.send("job.event", ev("running", { iteration: 2 }));
+    srv.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => rig.session.lastRecvSeq === 1);
+    const sid = rig.session.sessionId;
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    const queued = rig.session.send("job.event", ev("running", { iteration: 3 })); // queued while detached
+    await rig.connect();
+    await queued;
+    const reg = srv.cp.registers.at(-1);
+    assert.deepEqual(reg.resume, { sessionId: sid, lastRecvSeq: 1 });
+    assert.equal(rig.session.sessionId, sid);
+    assert.deepEqual(srv.cp.received.filter((f) => f.type === "job.event").map((f) => [f.seq, f.payload.iteration]), [[1, 1], [2, 2], [3, 3]]);
+    assert.equal(srv.cp.hellos.length, 2);
+});});
+
+test("resume: frames the CP never saw are sent again (same seq and msgId) and are acked after the reconnect", async () => {
+    await withRig({ cp: { limits: { ackTimeoutMs: 5000 } } }, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const h = await rig.session.enqueue("job.event", ev("running", { iteration: 1 }));
+    await waitFor(() => srv.cp.received.length === 1);
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    srv.cp.silent = false;
+    await rig.connect();
+    await h.acked; // ready{peerLastSeq:1} settles it
+    assert.equal(srv.cp.received.length, 1, "no second copy");
+    assert.equal(rig.session.unacked.size, 0);
+});});
+
+test("resume: a frame lost with the socket is delivered after the reconnect (retransmitted once, not twice)", async () => {
+    await withRig({}, async ({ srv, rig }) => {
+    // write the frame, then lose the connection before the CP reads it
+    srv.ws.pause?.();
+    rig.ws.terminate();
+    await waitFor(() => rig.session.state === "detached");
+    const p = rig.session.send("job.event", ev("running", { iteration: 9 }));
+    await rig.connect();
+    await p;
+    assert.deepEqual(srv.cp.received.map((f) => f.payload.iteration), [9]);
+});});
+
+test("resumed:false (the CP lost the session): numbering restarts at 1 and frames that were in flight fail with agent_offline", async () => {
+    await withRig({}, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const a = await rig.session.enqueue("job.event", ev("running", { iteration: 1 }));
+    const b = await rig.session.enqueue("job.event", ev("running", { iteration: 2 }));
+    await waitFor(() => srv.cp.received.length === 2);
+    const old = rig.session.sessionId;
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    srv.cp.sessionId = uuid(); // the CP has no memory of this session
+    srv.cp.silent = false;
+    await rig.connect();
+    await assert.rejects(a.acked, (e) => e.code === "agent_offline");
+    await assert.rejects(b.acked, (e) => e.code === "agent_offline");
+    assert.notEqual(rig.session.sessionId, old);
+    await rig.session.send("job.event", ev("running", { iteration: 3 }));
+    assert.equal(srv.cp.received.at(-1).seq, 1, "both sides restart at 1");
+});});
+
+test("resume window: after resumeWindowMs a dropped session is forgotten (no resume offered, in-flight fail)", async () => {
+    await withRig({ rig: { options: { resumeWindowMs: 80 } } }, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const h = await rig.session.enqueue("job.event", ev());
+    await waitFor(() => srv.cp.received.length === 1);
+    rig.drop();
+    await waitFor(() => rig.session.state === "idle");
+    await assert.rejects(h.acked, (e) => e.code === "agent_offline");
+    srv.cp.silent = false;
+    await rig.connect();
+    await waitFor(() => rig.session.state === "ready");
+    assert.equal(srv.cp.registers.at(-1).resume, undefined);
+});});
+
+test("resume: a content stream does not survive a reset (its chunks would reach a CP that never saw chunk 0)", async () => {
+    await withRig({ rig: { options: { maxInFlight: 1 } } }, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const p = sendContent(rig.session, { requestId: REQ, source: bytesOf(5 * 32768) });
+    p.catch(() => {});
+    await waitFor(() => srv.cp.received.length === 1);
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    srv.cp.sessionId = uuid();
+    srv.cp.silent = false;
+    await rig.connect();
+    await assert.rejects(p, (e) => e.code === "agent_offline");
+    await new Promise((r) => setTimeout(r, 50));
+    assert.equal(srv.cp.received.filter((f) => f.type === "content.response").length, 1);
+    assert.deepEqual(srv.cp.errorsSent, []);
+});});