deepdebug-local-agent 1.2.0 → 1.4.0

package/test/la-protocol-v2/helpers/reference-cp.js

@@ -0,0 +1,349 @@
+// Reference control plane for the tests of protocol v2 (F3-05b). NOT product code and NOT the gateway: a
+// small Node model of the CP side that applies the rules of the contract README in the same order as the
+// gateway's LaV2Session (size, parse, allowlist, schema, tenant, agent, direction, state, seq, chunks),
+// signs its frames like AgentRequestSigner (VH-AGENT-SIG-V1, method WS, path = type) and keeps a session
+// across connections so resume can be exercised. What it proves is limited by that: see the note
+// "Fase 3 F3-05b" (interoperability with the real LaV2Session is a separate test, test/interop).
+import crypto from "node:crypto";
+import { WebSocketServer } from "ws";
+import { loadContract } from "../../../src/la-protocol-v2/contract.js";
+import { canonicalString, sha256Hex } from "../../../src/utils/request-signing.js";
+import { parseStrict } from "../../../src/la-protocol-v2/strict-json.js";
+import { closeCodeOf, isFatal, isRetryable } from "../../../src/la-protocol-v2/errors.js";
+
+export const TENANT = "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f";
+export const AGENT = "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d";
+export const uuid = () => crypto.randomUUID();
+
+export function newKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+    const raw = publicKey.export({ format: "der", type: "spki" }).subarray(-32).toString("base64");
+    return { privateKey, publicKeyRaw: raw };
+}
+
+const DEFAULT_LIMITS = { maxFrameBytes: 49152, chunkRawBytes: 32768, maxChunks: 64, ackTimeoutMs: 5000, maxRetries: 3,
+    heartbeatSeconds: 30, contentFirstByteMs: 10000, contentTotalMs: 30000 };
+
+export class ReferenceCp {
+    constructor({ tenantId = TENANT, agentId = AGENT, privateKey, publicKeyRaw, keyId = "vh-cp-test", requireEnforce = false,
+        now = Date.now, limits = {}, workspaceId = "", skewSeconds = 60 } = {}) {
+        this.publicKeyRaw = publicKeyRaw;
+        this.contract = loadContract();
+        if (!privateKey) ({ privateKey, publicKeyRaw: this.publicKeyRaw } = newKeyPair());
+        Object.assign(this, { tenantId, agentId, privateKey, keyId, requireEnforce, now, skewSeconds, workspaceId });
+        this.limits = { ...DEFAULT_LIMITS, ...limits };
+        this.sessionId = uuid();
+        this.laSeq = 0; this.cpSeq = 0;
+        this.ring = new Map();
+        this.unacked = new Map();
+        this.chunkStates = new Map();
+        this.state = "await_register";
+        this.reattached = false;
+        this.resume = null;
+        this.sendFn = () => {}; this.closeFn = () => {};
+        // observations
+        this.received = [];       // LA data frames accepted, in order
+        this.duplicates = [];     // seq of duplicate frames re-acked
+        this.errorsSent = [];     // codes sent to the LA
+        this.peerErrors = [];     // error frames the LA sent us
+        this.acksFromLa = [];
+        this.registers = [];
+        this.hellos = [];
+        this.rawIn = [];
+        this.dropAcks = 0;        // do not ack the next n accepted LA data frames (simulates lost acks)
+        this.silent = false;      // do not ack anything
+        this.ackDelayMs = 0;      // answer acks late (slow consumer)
+        this.onReceived = () => {};
+        this.contentRequests = new Map(); // requestId -> {chunks:[], done}
+    }
+
+    /** A new connection of the same agent (resume candidate). */
+    attach(send, close) {
+        this.sendFn = send; this.closeFn = close;
+        for (const u of this.unacked.values()) clearTimeout(u.timer);
+        this.state = "await_register";
+        this.reattached = this.sessionStarted === true;
+        this.resume = null;
+    }
+
+    detach() {
+        for (const u of this.unacked.values()) { clearTimeout(u.timer); u.timer = null; }
+        this.sendFn = () => {};
+    }
+
+    // ------------------------------------------------------------------ inbound (LA -> CP)
+
+    /** @returns {null | {code:string}} the refusal (error frame already sent, close done when fatal) */
+    feed(text) {
+        this.rawIn.push(text);
+        const r = this.#process(text);
+        if (r) {
+            this.errorsSent.push(r.code);
+            this.#sendError(r.code, r.refSeq, r.refMsgId);
+            if (isFatal(r.code)) { this.closeFn(closeCodeOf(r.code), r.code); this.detach(); }
+        }
+        return r;
+    }
+
+    #process(text) {
+        const L = this.limits;
+        if (Buffer.byteLength(text, "utf8") > L.maxFrameBytes) return { code: "frame_too_large" };
+        let m;
+        try { m = parseStrict(text); } catch { return { code: "bad_frame" }; }
+        if (m === null || typeof m !== "object" || Array.isArray(m)) return { code: "bad_frame" };
+        const info = this.contract.typeInfo(m.type);
+        if (!info) return { code: "unknown_type" };
+        const v = this.contract.validateFrame(m);
+        if (!v.ok) return { code: v.code };
+        if (m.tenantId !== this.tenantId) return { code: "tenant_mismatch" };
+        if (m.agentId !== this.agentId) return { code: "agent_mismatch" };
+        if (info.direction === "cp->la") return { code: "wrong_direction" };
+        if (this.state === "await_register") return m.type === "register" ? this.#onRegister(m) : { code: "handshake_violation" };
+        if (this.state === "await_hello") return m.type === "hello" ? this.#onHello(m) : { code: "not_ready" };
+        if (m.type === "register" || m.type === "hello") return { code: "handshake_violation" };
+        if (info.control) {
+            if (m.type === "ack") this.#onAck(m);
+            else if (m.type === "error") this.peerErrors.push(m.payload.code);
+            return null;
+        }
+        return this.#onData(m);
+    }
+
+    #onRegister(m) {
+        const skew = Math.abs(Date.parse(m.ts) - this.now()) / 1000;
+        if (skew > this.skewSeconds) return { code: "clock_skew" };
+        this.registers.push(m.payload);
+        this.resume = m.payload.resume || null;
+        this.state = "await_hello";
+        return null;
+    }
+
+    #onHello(m) {
+        if (this.requireEnforce && m.payload.signatureMode !== "enforce") return { code: "signature_mode_insufficient" };
+        this.hellos.push(m.payload);
+        const resumed = !!(this.reattached && this.resume && this.resume.sessionId === this.sessionId && this.resume.lastRecvSeq <= this.cpSeq);
+        if (this.reattached && !resumed) this.#reset();
+        this.reattached = false;
+        this.sessionStarted = true;
+        if (resumed) this.#ackUpTo(this.resume.lastRecvSeq);
+        this.#sendReady(resumed);
+        this.state = "ready";
+        if (resumed) for (const u of this.unacked.values()) { u.retries = 0; this.#transmit(u); }
+        return null;
+    }
+
+    #reset() {
+        for (const u of this.unacked.values()) clearTimeout(u.timer);
+        this.unacked.clear(); this.ring.clear(); this.chunkStates.clear();
+        this.laSeq = 0; this.cpSeq = 0; this.sessionId = uuid();
+    }
+
+    #onAck(m) {
+        this.acksFromLa.push({ ackSeq: m.payload.ackSeq, status: m.payload.status, errorCode: m.payload.errorCode });
+        if (m.payload.ackSeq > this.cpSeq) return;
+        if (m.payload.status === "rejected") {
+            this.#ackUpTo(m.payload.ackSeq - 1);
+            const u = this.unacked.get(m.payload.ackSeq);
+            if (u) { clearTimeout(u.timer); this.unacked.delete(m.payload.ackSeq); }
+        } else this.#ackUpTo(m.payload.ackSeq);
+    }
+
+    #ackUpTo(n) {
+        for (const [seq, u] of this.unacked) { if (seq > n) break; clearTimeout(u.timer); this.unacked.delete(seq); }
+    }
+
+    #onData(m) {
+        const { seq, msgId } = m;
+        if (seq <= this.laSeq) {
+            if (this.ring.get(seq) === msgId) { this.duplicates.push(seq); if (!this.silent) this.#sendAck(seq, "duplicate"); return null; }
+            return { code: "seq_replayed", refSeq: seq, refMsgId: msgId };
+        }
+        if (seq !== this.laSeq + 1) return { code: "seq_gap", refSeq: seq, refMsgId: msgId };
+        if (m.type === "content.response") {
+            const bad = this.#chunkRule(m);
+            if (bad) return { code: bad, refSeq: seq, refMsgId: msgId };
+        }
+        this.laSeq = seq;
+        this.ring.set(seq, msgId);
+        while (this.ring.size > 512) this.ring.delete(this.ring.keys().next().value);
+        if (m.ack !== undefined) this.#ackUpTo(m.ack);
+        this.received.push(m);
+        if (m.type === "content.response") {
+            const c = this.contentRequests.get(m.requestId) || { chunks: [], done: false };
+            c.chunks.push(Buffer.from(m.payload.data, "base64"));
+            if (m.chunk.last) c.done = true;
+            this.contentRequests.set(m.requestId, c);
+        }
+        if (this.dropAcks > 0) this.dropAcks--;
+        else if (!this.silent) {
+            if (this.ackDelayMs > 0) setTimeout(() => this.#sendAck(seq, "accepted"), this.ackDelayMs);
+            else this.#sendAck(seq, "accepted");
+        }
+        this.onReceived(m);
+        return null;
+    }
+
+    #chunkRule(m) {
+        const { index, total, last } = m.chunk;
+        const st = this.chunkStates.get(m.requestId);
+        if (st && st.done) return "chunk_out_of_order";
+        if (st && st.total !== total) return "chunk_inconsistent";
+        if (index !== (st ? st.next : 0)) return "chunk_out_of_order";
+        if (last !== (index === total - 1)) return "chunk_inconsistent";
+        this.chunkStates.set(m.requestId, { total, next: index + 1, done: last });
+        return null;
+    }
+
+    // ------------------------------------------------------------------ outbound (CP -> LA)
+
+    #envelope(type, seq, requestId, workspaceId) {
+        return { schemaVersion: 2, type, msgId: uuid(), seq, tenantId: this.tenantId, agentId: this.agentId, workspaceId,
+            ts: new Date(this.now()).toISOString(), ...(requestId ? { requestId } : {}) };
+    }
+
+    #sign(frame, type, payload, workspaceId) {
+        const raw = JSON.stringify(payload);
+        const timestamp = String(Math.floor(this.now() / 1000));
+        const nonce = crypto.randomBytes(18).toString("base64url");
+        const canonical = canonicalString({ method: "WS", pathAndQuery: type, bodySha256: sha256Hex(Buffer.from(raw, "utf8")),
+            tenantId: this.tenantId, workspaceId, timestamp, nonce });
+        const signature = crypto.sign(null, Buffer.from(canonical, "utf8"), this.privateKey).toString("base64");
+        frame.paramsRaw = raw;
+        frame.sig = { keyId: this.keyId, timestamp, nonce, tenantId: this.tenantId, workspaceId, signature };
+        frame.payload = payload;
+    }
+
+    #sendReady(resumed) {
+        const f = this.#envelope("ready", 0, null, this.workspaceId);
+        this.#sign(f, "ready", { protocol: 2, sessionId: this.sessionId, resumed, peerLastSeq: this.laSeq, limits: { ...this.limits } }, this.workspaceId);
+        this.sendFn(JSON.stringify(f));
+    }
+
+    #sendAck(ackSeq, status, errorCode) {
+        const f = this.#envelope("ack", 0, null, "");
+        f.payload = { ackSeq, status, ...(errorCode ? { errorCode } : {}) };
+        this.sendFn(JSON.stringify(f));
+    }
+
+    #sendError(code, refSeq, refMsgId) {
+        const f = this.#envelope("error", 0, null, "");
+        f.payload = { code, retryable: isRetryable(code), ...(refSeq ? { refSeq } : {}), ...(refMsgId ? { refMsgId } : {}), ...(isFatal(code) ? { closeCode: closeCodeOf(code) } : {}) };
+        this.sendFn(JSON.stringify(f));
+    }
+
+    /** Sends a CP->LA data frame (job.assign, content.request, ...). Retransmitted (re-signed) until acked. */
+    sendData(type, payload, { workspaceId = this.workspaceId, requestId } = {}) {
+        const seq = ++this.cpSeq;
+        const u = { seq, type, payload, workspaceId, requestId, msgId: uuid(), retries: 0, timer: null };
+        this.unacked.set(seq, u);
+        this.#transmit(u);
+        return seq;
+    }
+
+    #transmit(u) {
+        const f = this.#envelope(u.type, u.seq, u.requestId, u.workspaceId);
+        f.msgId = u.msgId;
+        if (this.laSeq > 0) f.ack = this.laSeq;
+        this.#sign(f, u.type, u.payload, u.workspaceId);
+        this.sendFn(JSON.stringify(f));
+        clearTimeout(u.timer);
+        u.timer = setTimeout(() => {
+            if (!this.unacked.has(u.seq)) return;
+            if (u.retries >= this.limits.maxRetries) { this.timedOut = true; this.closeFn(closeCodeOf("timeout"), "ack_timeout"); this.detach(); return; }
+            u.retries++; this.retransmits = (this.retransmits || 0) + 1;
+            this.#transmit(u);
+        }, this.limits.ackTimeoutMs);
+        u.timer.unref?.();
+    }
+
+    /** A signed v1 command envelope ({requestId, command, params, paramsRaw, sig}) as the v1 gateway sends it. */
+    v1Command(command, params = {}) {
+        const f = { requestId: uuid(), command, params };
+        const raw = JSON.stringify(params);
+        const timestamp = String(Math.floor(this.now() / 1000));
+        const nonce = crypto.randomBytes(18).toString("base64url");
+        const canonical = canonicalString({ method: "WS", pathAndQuery: command, bodySha256: sha256Hex(Buffer.from(raw, "utf8")),
+            tenantId: this.tenantId, workspaceId: this.workspaceId, timestamp, nonce });
+        f.paramsRaw = raw;
+        f.sig = { keyId: this.keyId, timestamp, nonce, tenantId: this.tenantId, workspaceId: this.workspaceId,
+            signature: crypto.sign(null, Buffer.from(canonical, "utf8"), this.privateKey).toString("base64") };
+        return JSON.stringify(f);
+    }
+
+    /** Sends exactly this frame (for the tests that need an invalid CP frame). */
+    sendRaw(text) { this.sendFn(text); }
+    frameWith(type, payload, over = {}) {
+        const seq = ++this.cpSeq;
+        const f = this.#envelope(type, seq, over.requestId, this.workspaceId);
+        this.#sign(f, type, payload, this.workspaceId);
+        return Object.assign(f, over.frame || {});
+    }
+}
+
+/** A WebSocket server in front of one ReferenceCp (one agent). Authorization: Bearer <token>. */
+export class ReferenceCpServer {
+    constructor(opts = {}) {
+        this.cp = new ReferenceCp(opts);
+        this.privateKey = this.cp.privateKey;
+        this.publicKeyRaw = this.cp.publicKeyRaw;
+        this.keyId = this.cp.keyId;
+        this.token = opts.token || "tok";
+        this.connections = 0;
+        this.textsFromLa = [];   // everything the LA sent that was not a v2 frame (pings, legacy register, v1 answers)
+        this.legacy = [];        // parsed JSON frames of v1 shape
+        this.v2Disabled = !!opts.v2Disabled;      // behave like a gateway without v2: ignore v2 frames
+        this.refuseV2 = !!opts.refuseV2;          // answer the v2 register with error protocol_unsupported
+        this.closes = [];
+    }
+
+    async start() {
+        this.wss = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+        await new Promise((r) => this.wss.on("listening", r));
+        this.port = this.wss.address().port;
+        this.wss.on("connection", (ws, req) => {
+            if (req.headers.authorization !== `Bearer ${this.token}`) { ws.close(1008, "unauthorized"); return; }
+            this.connections++;
+            this.ws = ws;
+            if (!this.v2Disabled) this.cp.attach((t) => { if (ws.readyState === 1) ws.send(t); }, (code, reason) => ws.close(code, reason));
+            ws.on("message", (d, isBinary) => {
+                const text = d.toString();
+                if (text === "ping") { ws.send("pong"); return; }
+                let o = null;
+                try { o = JSON.parse(text); } catch { /* not json */ }
+                if (o && o.schemaVersion !== undefined) {
+                    if (this.v2Disabled) return;
+                    if (this.refuseV2) { // like the gateway: the connection is v1 from now on; the v2 frames after the register are ignored
+                        if (o.type === "register") ws.send(JSON.stringify({ schemaVersion: 2, type: "error", msgId: uuid(), seq: 0, tenantId: this.cp.tenantId, agentId: this.cp.agentId,
+                            workspaceId: "", ts: new Date().toISOString(), payload: { code: "protocol_unsupported", retryable: false } }));
+                        return;
+                    }
+                    this.cp.feed(text);
+                } else {
+                    this.textsFromLa.push(text);
+                    if (o) this.legacy.push(o);
+                }
+                void isBinary;
+            });
+            ws.on("close", (code) => { this.closes.push(code); this.cp.detach(); });
+        });
+        return this;
+    }
+
+    get url() { return `http://127.0.0.1:${this.port}`; }
+    kill() { this.ws && this.ws.terminate(); }
+    async stop() {
+        for (const c of this.wss.clients) c.terminate();
+        this.cp.detach();
+        await new Promise((r) => this.wss.close(r));
+    }
+}
+
+export async function waitFor(cond, ms = 4000, step = 10) {
+    const t0 = Date.now();
+    while (Date.now() - t0 < ms) {
+        const v = await cond();
+        if (v) return v;
+        await new Promise((r) => setTimeout(r, step));
+    }
+    throw new Error(`waitFor timed out after ${ms} ms: ${cond.toString().slice(0, 120)}`);
+}

package/test/la-protocol-v2/helpers/spawn-agent.js

@@ -0,0 +1,35 @@
+// Boots the REAL agent (src/server.js of `root`) against a ReferenceCpServer and returns what it did.
+// Used by the flag-off characterization and by the end-to-end test of the v2 tunnel.
+import net from "node:net";
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+export const freePort = () => new Promise((res) => { const s = net.createServer().listen(0, "127.0.0.1", () => { const p = s.address().port; s.close(() => res(p)); }); });
+
+export async function runAgent({ srv, root = DEFAULT_ROOT, env = {}, cfg, until, ms = 20000 }) {
+    const ws = fs.mkdtempSync(path.join(os.tmpdir(), "v2e2e-ws-"));
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "v2e2e-home-"));
+    if (cfg) {
+        fs.mkdirSync(path.join(home, ".deepdebug"));
+        fs.writeFileSync(path.join(home, ".deepdebug", "config.json"), JSON.stringify(cfg));
+    }
+    const full = { ...process.env, PORT: String(await freePort()), GATEWAY_URL: srv.url, AUTH_TOKEN: srv.token, WORKSPACE_ROOT: ws, HOME: home, ...env };
+    delete full.LOCAL_AGENT_TOKEN;
+    for (const k of Object.keys(full)) if (full[k] === undefined) delete full[k];
+    const child = spawn(process.execPath, ["src/server.js"], { cwd: root, env: full, stdio: "ignore" });
+    try {
+        const deadline = Date.now() + ms;
+        while (Date.now() < deadline) {
+            if (until && (await until())) break;
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    } finally {
+        child.kill("SIGKILL");
+        fs.rmSync(ws, { recursive: true, force: true });
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}

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