@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/org/push.test.mjs

@@ -1,792 +0,0 @@
-/**
- * push.test.mjs — the agent's PUSH channel onto the org event ledger.
- *
- * Drives connectOrgPush over an injected org client + injected fetch + injected
- * timers + a tmp agentRoot, asserting the things that actually matter:
- *   - the LADDER falls stream → longpoll → cadence and probes back up;
- *   - an hq without the endpoint (404) demotes INSTANTLY, without retries;
- *   - resume after a disconnect loses nothing and re-delivers nothing (the
- *     cursor is persisted, sent back, and enforced as an exclusive watermark);
- *   - reconnect backs off with jitter, bounded, never hammering a down server;
- *   - a malformed frame is skipped fail-open and the connection survives it;
- *   - a burst is coalesced into one wake, with a trailing wake for the tail;
- *   - nothing here ever throws past the boundary.
- * No network, no real time.
- *
- * Run: node --test lib/org/push.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  connectOrgPush,
-  decodeFrameLine,
-  readCursor,
-  writeCursor,
-  PUSH_RUNG,
-  CURSOR_RELATIVE,
-  STATUS_RELATIVE,
-  _internals,
-} from "./push.mjs";
-
-const BASE = "https://org.cohortapp.com";
-
-function tmpRepo() {
-  const root = mkdtempSync(join(tmpdir(), "org-push-"));
-  mkdirSync(join(root, "config"), { recursive: true });
-  return root;
-}
-
-function cfgEnabled() {
-  return { org: { cohort: { enabled: true, base: BASE, token: "tok" } } };
-}
-function cfgDisabled() {
-  return { org: { cohort: { enabled: false, base: BASE, token: "tok" } } };
-}
-
-/**
- * A fake org client: only what push.mjs uses.
- *
- * `call` is the LONG-POLL seam. `agent.wait` is a POST METHOD on hq's
- * dispatcher, not a GET read — it is absent from `reads.ts#HANDLED_READS`, so
- * the GET this suite used to assert would have 404'd against every hq that has
- * ever existed. The ok-frame shape below (`{ok:true, result:{cursor, items}}`)
- * is hq `methods/agent/wait.ts`'s documented return contract.
- */
-function fakeClient(opts = {}) {
-  const c = {
-    isEnabled: (cfg) => !!(cfg && cfg.org && cfg.org.cohort && cfg.org.cohort.enabled),
-    configFromAgent: () => ({ base: BASE, token: "tok", orgId: "acme", enabled: true }),
-    readCalls: [],
-    callCalls: [],
-    _reads: opts.reads ? opts.reads.slice() : [],
-    _calls: opts.calls ? opts.calls.slice() : [],
-    read(path, o) {
-      c.readCalls.push({ path, o });
-      const next = c._reads.length ? c._reads.shift() : { ok: true, payload: { events: [] }, status: 200 };
-      return Promise.resolve(typeof next === "function" ? next(path, o) : next);
-    },
-    call(method, params, o) {
-      c.callCalls.push({ method, params, o });
-      const next = c._calls.length ? c._calls.shift() : { ok: true, status: 200, result: { items: [], cursor: null, timedOut: true } };
-      return Promise.resolve(typeof next === "function" ? next(method, params, o) : next);
-    },
-  };
-  return c;
-}
-
-/** Build an NDJSON/SSE stream response from a list of raw wire lines. */
-function streamResponse(lines, { status = 200, chunkAll = false } = {}) {
-  return {
-    status,
-    body: (async function* () {
-      if (chunkAll) { yield `${lines.join("\n")}\n`; return; }
-      for (const l of lines) yield `${l}\n`;
-    })(),
-  };
-}
-
-/** A fetch that serves a queue of responses (or throws when told to). */
-function fakeFetch(queue) {
-  const calls = [];
-  const f = async (url, init) => {
-    calls.push({ url: String(url), init });
-    const next = queue.length ? queue.shift() : streamResponse([]);
-    if (next instanceof Error) throw next;
-    return typeof next === "function" ? next(String(url), init) : next;
-  };
-  f.calls = calls;
-  return f;
-}
-
-/**
- * Wake handlers are invoked off a microtask (dispatch must never block on a
- * handler), so a test that counts wakes has to let the microtask queue drain.
- */
-const flush = () => new Promise((r) => setImmediate(r));
-
-/** Timers that never fire on their own — the test drives every step by hand. */
-function inertTimers() {
-  const scheduled = [];
-  return {
-    setTimeout: (fn, ms) => { const h = { fn, ms, unref() {} }; scheduled.push(h); return h; },
-    clearTimeout: (h) => { const i = scheduled.indexOf(h); if (i >= 0) scheduled.splice(i, 1); },
-    scheduled,
-  };
-}
-
-/** Build a live-but-idle handle whose ladder we step manually. */
-async function mkHandle(root, extra = {}) {
-  const timers = inertTimers();
-  const client = extra.client || fakeClient();
-  const handle = await connectOrgPush({
-    agentRoot: root,
-    cfg: cfgEnabled(),
-    client,
-    setTimeout: timers.setTimeout,
-    clearTimeout: timers.clearTimeout,
-    now: extra.now,
-    ...extra,
-  });
-  return { handle, ctx: handle._ctx, client, timers };
-}
-
-const EV = (seq, family = "messaging", kind = "send") =>
-  JSON.stringify({ seq, family, kind, entityId: `m${seq}`, actor: "u1", at: "2026-08-11T00:00:00Z", payload: { recipientCount: 2 } });
-
-// ---------------------------------------------------------------------------
-// Gate + wiring basics
-// ---------------------------------------------------------------------------
-
-test("disabled org → inert handle, zero network, cadence rung", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([]);
-  const handle = await connectOrgPush({ agentRoot: root, cfg: cfgDisabled(), client: fakeClient(), fetchImpl });
-  assert.equal(handle.isEnabled, false);
-  assert.equal(handle.rung(), PUSH_RUNG.CADENCE);
-  assert.equal(fetchImpl.calls.length, 0, "a disabled org must never touch the wire");
-  assert.doesNotThrow(() => handle.stop(), "inert stop is safe");
-});
-
-test("COHORT_PUSH_DISABLED=1 is an operator kill switch back to pure cadence", async () => {
-  const root = tmpRepo();
-  process.env.COHORT_PUSH_DISABLED = "1";
-  try {
-    const handle = await connectOrgPush({ agentRoot: root, cfg: cfgEnabled(), client: fakeClient() });
-    assert.equal(handle.isEnabled, false);
-  } finally {
-    delete process.env.COHORT_PUSH_DISABLED;
-  }
-});
-
-test("boot does not run a step inline — the first step is scheduled", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([]);
-  const { handle, timers } = await mkHandle(root, { fetchImpl });
-  assert.equal(fetchImpl.calls.length, 0, "no request before the scheduled first step runs");
-  assert.equal(timers.scheduled.length, 1, "exactly one pump scheduled");
-  assert.equal(timers.scheduled[0].ms, 0);
-  handle.stop();
-});
-
-// ---------------------------------------------------------------------------
-// Rung 1 — the stream
-// ---------------------------------------------------------------------------
-
-test("stream rung: events wake the messaging target and advance the persisted cursor", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([streamResponse([":ok", EV(11), EV(12), EV(13)])]);
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl,
-    wakeCoalesceMs: 0, // every event fires its own wake, so we can count them
-    minHealthyMs: 0,   // and don't apply the short-stream backoff floor here
-    enqueueTick: (t) => woke.push(t),
-  });
-
-  const delay = await _internals.ladderStep(ctx);
-  await flush();
-
-  assert.equal(ctx.rung, PUSH_RUNG.STREAM, "a healthy stream stays on the preferred rung");
-  assert.equal(ctx.cursor, 13, "the watermark advanced to the last seq");
-  assert.equal(delay, 0, "a clean EOF reconnects immediately");
-  assert.equal(readCursor(root), 13, "the cursor is durable across a restart");
-  assert.equal(woke.length, 3);
-  assert.equal(woke[0].cadence, "messaging-inbound", "the wake nudges the EXISTING authoritative fetch");
-  assert.equal(woke[0].source, "org-push");
-  assert.equal(woke[0].priority, "high");
-  handle.stop();
-});
-
-test("stream rung: SSE framing, NDJSON framing and keepalives all parse", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([
-    streamResponse([
-      ": keepalive",
-      "event: message",
-      `data: ${EV(5)}`,
-      "",
-      EV(6), // bare NDJSON on the same connection
-      JSON.stringify({ type: "heartbeat" }),
-    ]),
-  ]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, enqueueTick: (t) => woke.push(t) });
-  await _internals.ladderStep(ctx);
-  await flush();
-  assert.equal(ctx.cursor, 6, "both framings delivered");
-  assert.equal(woke.length, 2);
-  handle.stop();
-});
-
-test("stream rung: a malformed frame is skipped fail-open and the stream keeps reading", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([
-    streamResponse([
-      EV(20),
-      "{not json at all",                                  // unparseable
-      JSON.stringify({ seq: "banana", family: "messaging" }), // non-numeric seq
-      JSON.stringify({ type: "event", nope: true }),          // claims event, isn't
-      "[1,2,3]",                                              // array, not a frame
-      EV(21),
-    ]),
-  ]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, minHealthyMs: 0, enqueueTick: (t) => woke.push(t) });
-
-  let delay;
-  await assert.doesNotReject(async () => { delay = await _internals.ladderStep(ctx); });
-  await flush();
-
-  assert.equal(ctx.cursor, 21, "the good frame AFTER the garbage was still delivered");
-  assert.equal(woke.length, 2, "exactly the two valid events woke anything");
-  assert.ok(ctx.stats.malformed >= 3, `malformed frames were counted, not thrown (${ctx.stats.malformed})`);
-  assert.equal(ctx.rung, PUSH_RUNG.STREAM, "garbage does not cost us the rung");
-  assert.equal(delay, 0, "and does not cost us the connection either — we reconnect at once");
-  handle.stop();
-});
-
-test("stream rung: a throwing wake handler never breaks the loop or the cursor", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([streamResponse([EV(30), EV(31)])]);
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl,
-    wakeCoalesceMs: 0,
-    wake: { "org-messaging": () => { throw new Error("boom"); } },
-  });
-  await assert.doesNotReject(async () => { await _internals.ladderStep(ctx); });
-  assert.equal(ctx.cursor, 31, "hints advance even when the wake fails — the cadence is the backstop");
-  handle.stop();
-});
-
-// ---------------------------------------------------------------------------
-// Resume — the whole point of keying off CohortEvent.seq
-// ---------------------------------------------------------------------------
-
-test("resume after a disconnect loses nothing and re-delivers nothing", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([
-    // Connection 1 dies after seq 7.
-    streamResponse([EV(5), EV(6), EV(7)]),
-    // Connection 2: hq replays 6 and 7 (overlap is by design), then 8, 9, 10.
-    streamResponse([EV(6), EV(7), EV(8), EV(9), EV(10)]),
-  ]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, enqueueTick: (t) => woke.push(t) });
-
-  await _internals.ladderStep(ctx);
-  await flush();
-  assert.equal(ctx.cursor, 7);
-  assert.equal(readCursor(root), 7, "the cursor is on disk before the reconnect");
-
-  await _internals.ladderStep(ctx);
-  await flush();
-
-  const url2 = fetchImpl.calls[1].url;
-  assert.match(url2, /cursor=7/, "the reconnect resumes FROM the persisted watermark");
-  assert.equal(ctx.cursor, 10, "nothing after the drop was lost");
-  const seqs = woke.map((w) => w.metadata.pushSeq);
-  assert.deepEqual(seqs, [5, 6, 7, 8, 9, 10], "the overlap was deduped: every seq woke exactly once");
-  assert.ok(ctx.stats.duplicate >= 2, "the replayed frames were counted as duplicates, not delivered twice");
-  handle.stop();
-});
-
-test("a fresh agent bootstraps at HEAD — it never asks for cursor=0", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([streamResponse([])]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl });
-  await _internals.ladderStep(ctx);
-  assert.equal(fetchImpl.calls[0].url.includes("cursor="), false,
-    "no cursor param on a first run — cursor=0 would replay the whole org ledger");
-  handle.stop();
-});
-
-test("a corrupt cursor file reads as absent (bootstrap at head), never throws", () => {
-  const root = tmpRepo();
-  mkdirSync(join(root, "state", "org"), { recursive: true });
-  writeFileSync(join(root, CURSOR_RELATIVE), "{{{ not json");
-  assert.equal(readCursor(root), null);
-  writeFileSync(join(root, CURSOR_RELATIVE), JSON.stringify({ cursor: 0 }));
-  assert.equal(readCursor(root), null, "0 is corrupt, not a cursor");
-  writeCursor(root, 42);
-  assert.equal(readCursor(root), 42);
-});
-
-// ---------------------------------------------------------------------------
-// The ladder
-// ---------------------------------------------------------------------------
-
-test("ladder: repeated stream failures demote to the long-poll, which then delivers", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([
-    new Error("ECONNRESET"),
-    new Error("ECONNRESET"),
-    new Error("ECONNRESET"),
-  ]);
-  const client = fakeClient({
-    calls: [{ ok: true, status: 200, result: { items: [JSON.parse(EV(100)), JSON.parse(EV(101))], cursor: 101, timedOut: false } }],
-  });
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl, client, wakeCoalesceMs: 0, enqueueTick: (t) => woke.push(t),
-    demoteAfter: 3, baseBackoffMs: 10, maxBackoffMs: 100,
-  });
-
-  const d1 = await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.STREAM, "one failure is not a demotion");
-  assert.ok(d1 > 0, "a failed attempt backs off before retrying");
-  await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.STREAM);
-  const d3 = await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.LONGPOLL, "3 consecutive failures demote one rung");
-  assert.equal(d3, 0, "a demotion retries on the new rung at once");
-
-  await _internals.ladderStep(ctx);
-  await flush();
-  assert.equal(client.callCalls.length, 1, "the long-poll lane took over");
-  assert.equal(client.readCalls.length, 0, "agent.wait is a POST method — the GET read lane has no handler for it and 404s");
-  assert.equal(client.callCalls[0].method, "agent.wait");
-  assert.equal(client.callCalls[0].params.timeoutMs, 25_000, "hq caps agent.wait at 25s (MAX_WAIT_MS); asking for 55s only makes our abort budget wrong");
-  assert.equal(ctx.cursor, 101);
-  assert.deepEqual(woke.map((w) => w.metadata.pushSeq), [100, 101]);
-  handle.stop();
-});
-
-test("ladder: repeated long-poll failures demote to CADENCE, which idles instead of hammering", async () => {
-  const root = tmpRepo();
-  const client = fakeClient({
-    calls: [
-      { ok: false, status: 500, error: { code: "INTERNAL" } },
-      { ok: false, status: 500, error: { code: "INTERNAL" } },
-      { ok: false, status: 0, error: { code: "INTERNAL" } },
-    ],
-  });
-  let clock = 1_000;
-  const { handle, ctx } = await mkHandle(root, {
-    client, now: () => clock, startRung: PUSH_RUNG.LONGPOLL,
-    demoteAfter: 3, baseBackoffMs: 10, maxBackoffMs: 50, promoteAfterMs: 60_000,
-  });
-
-  await _internals.ladderStep(ctx);
-  await _internals.ladderStep(ctx);
-  await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.CADENCE, "the floor of the ladder");
-
-  const before = client.callCalls.length;
-  const delay = await _internals.ladderStep(ctx);
-  assert.equal(client.callCalls.length, before, "the cadence rung issues NO requests — it is the 45s poll doing the work");
-  assert.ok(delay >= 1_000, "it sleeps out the dwell rather than spinning");
-
-  // The status file must say, out loud, which lane the agent is on.
-  const status = JSON.parse(readFileSync(join(root, STATUS_RELATIVE), "utf8"));
-  assert.equal(status.rung, PUSH_RUNG.CADENCE);
-  assert.equal(status.cadenceFallbackActive, true, "the safety net is never switched off");
-  handle.stop();
-});
-
-test("ladder: a lower rung is probed back up to the stream after the dwell period", async () => {
-  const root = tmpRepo();
-  let clock = 1_000;
-  const fetchImpl = fakeFetch([streamResponse([EV(70)])]);
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl, now: () => clock, startRung: PUSH_RUNG.CADENCE, promoteAfterMs: 60_000, wakeCoalesceMs: 0,
-    enqueueTick: () => {},
-  });
-  ctx.rungSinceMs = clock;
-
-  await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.CADENCE, "still inside the dwell window");
-
-  clock += 60_001;
-  await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.STREAM, "an hq deploy must not strand the agent on the slow lane forever");
-  assert.equal(ctx.cursor, 70, "and the probe immediately delivered");
-  handle.stop();
-});
-
-test("ladder: a 404 (hq has no such endpoint) demotes INSTANTLY, with no retries and no backoff", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([{ status: 404, body: null }]);
-  const client = fakeClient({ calls: [{ ok: false, status: 404, error: { code: "NOT_FOUND" } }] });
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, client, demoteAfter: 3 });
-
-  const d1 = await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.LONGPOLL, "one 404 is enough — retrying an absent endpoint is pointless");
-  assert.equal(d1, 0);
-  assert.equal(fetchImpl.calls.length, 1, "an SDK ahead of the server must not hammer it");
-
-  const d2 = await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.CADENCE, "no wait lane either → straight to the cadence backstop");
-  assert.equal(d2, 0);
-  handle.stop();
-});
-
-test("ladder: a 401 is reported as a credential problem, not a transport blip", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([{ status: 401, body: null }]);
-  const warnings = [];
-  const realWarn = console.warn;
-  console.warn = (...a) => warnings.push(a.join(" "));
-  try {
-    const { handle, ctx } = await mkHandle(root, { fetchImpl, baseBackoffMs: 5 });
-    await _internals.ladderStep(ctx);
-    handle.stop();
-  } finally {
-    console.warn = realWarn;
-  }
-  const warned = warnings.join("\n");
-  assert.match(warned, /http 401/);
-  assert.match(warned, /COHORT_API_KEY/, "an auth failure must name the likely cause");
-  assert.match(warned, /45s messaging-inbound cadence/, "and must say the agent is still covered");
-});
-
-test("a scheduled stream recycle is a success, not a failure (it must not demote us)", async () => {
-  const root = tmpRepo();
-  const ref = {};
-  let clock = 1_000;
-  // The 15-minute recycle aborts the read, which surfaces as a THROW out of the
-  // body iterator — exactly how a real failure surfaces. Classifying the two
-  // apart is the difference between "healthy long-lived channel" and "an agent
-  // that demotes itself to the slow lane every quarter of an hour".
-  const fetchImpl = fakeFetch([
-    () => ({
-      status: 200,
-      body: (async function* () {
-        yield `${EV(200)}\n`;
-        clock += 15 * 60_000;
-        ref.ctx.streamAbortReason = "max-hold";
-        throw new Error("The operation was aborted");
-      })(),
-    }),
-  ]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, now: () => clock, wakeCoalesceMs: 0, enqueueTick: () => {}, demoteAfter: 2 });
-  ref.ctx = ctx;
-
-  const delay = await _internals.ladderStep(ctx);
-  assert.equal(ctx.rung, PUSH_RUNG.STREAM, "a recycle keeps the preferred rung");
-  assert.equal(ctx.failures, 0, "and spends none of the failure budget");
-  assert.equal(ctx.cursor, 200, "everything read before the recycle still counted");
-  assert.equal(delay, 0, "reconnect immediately");
-  handle.stop();
-});
-
-// ---------------------------------------------------------------------------
-// Backoff
-// ---------------------------------------------------------------------------
-
-test("backoff: jittered, growing, bounded — and never zero against a down server", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([
-    new Error("down"), new Error("down"), new Error("down"), new Error("down"),
-    new Error("down"), new Error("down"), new Error("down"), new Error("down"),
-  ]);
-  // rng() = 1 picks the top of each decorrelated window → the growth is visible
-  // and deterministic; the module still uses Math.random in production.
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl, rng: () => 0.999999, demoteAfter: 99, baseBackoffMs: 100, maxBackoffMs: 1_000, backoffFactor: 3,
-  });
-
-  const delays = [];
-  for (let i = 0; i < 6; i += 1) delays.push(await _internals.ladderStep(ctx));
-
-  assert.ok(delays.every((d) => d >= 100), `never hammers: every delay >= base (${delays})`);
-  assert.ok(delays.every((d) => d <= 1_000), `bounded by max (${delays})`);
-  assert.ok(delays[1] > delays[0], `backs off progressively (${delays})`);
-  assert.equal(delays[delays.length - 1], 1_000, "and saturates at the ceiling rather than growing forever");
-
-  // Same failures, a different RNG → different delays. That is the anti-lockstep
-  // property: a fleet of agents must not all retry a struggling hq in unison.
-  const root2 = tmpRepo();
-  const f2 = fakeFetch([new Error("down"), new Error("down"), new Error("down")]);
-  const { handle: h2, ctx: c2 } = await mkHandle(root2, {
-    fetchImpl: f2, rng: () => 0.0, demoteAfter: 99, baseBackoffMs: 100, maxBackoffMs: 1_000, backoffFactor: 3,
-  });
-  const lowJitter = [];
-  for (let i = 0; i < 3; i += 1) lowJitter.push(await _internals.ladderStep(c2));
-  assert.notDeepEqual(lowJitter, delays.slice(0, 3), "jitter actually varies the schedule");
-
-  handle.stop();
-  h2.stop();
-});
-
-test("a stream that dies instantly is rate-limited by the base backoff (no hot spin)", async () => {
-  const root = tmpRepo();
-  let clock = 5_000;
-  // A 200 that closes at once: 'ok' (clean EOF) but suspiciously short-lived.
-  const fetchImpl = fakeFetch([streamResponse([])]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, now: () => clock, baseBackoffMs: 250, minHealthyMs: 2_000 });
-  const delay = await _internals.ladderStep(ctx);
-  assert.equal(delay, 250, "an instantly-closing stream must not become a reconnect storm");
-  handle.stop();
-});
-
-test("a long-poll that answers INSTANTLY with nothing is floored, not spun", async () => {
-  const root = tmpRepo();
-  // A half-implemented (or proxy-terminated) agent.wait that returns at once
-  // instead of holding would otherwise re-arm at wire speed against hq.
-  let clock = 7_000;
-  const client = fakeClient({ calls: [{ ok: true, status: 200, result: { items: [], cursor: null, timedOut: true } }] });
-  const { handle, ctx } = await mkHandle(root, {
-    client, now: () => clock, startRung: PUSH_RUNG.LONGPOLL, baseBackoffMs: 750, minHealthyMs: 2_000,
-  });
-  const delay = await _internals.ladderStep(ctx);
-  assert.equal(delay, 750, "an instant empty answer is rate-limited");
-  assert.equal(ctx.rung, PUSH_RUNG.LONGPOLL, "but it is a SUCCESS, not a failure — no demotion");
-  handle.stop();
-});
-
-// ---------------------------------------------------------------------------
-// Wake semantics
-// ---------------------------------------------------------------------------
-
-test("a burst is coalesced into one wake, with a trailing wake for the tail", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const timers = inertTimers();
-  let clock = 10_000;
-  const fetchImpl = fakeFetch([streamResponse([EV(1), EV(2), EV(3), EV(4)])]);
-  const handle = await connectOrgPush({
-    agentRoot: root, cfg: cfgEnabled(), client: fakeClient(), fetchImpl,
-    setTimeout: timers.setTimeout, clearTimeout: timers.clearTimeout, now: () => clock,
-    wakeCoalesceMs: 1_500, enqueueTick: (t) => woke.push(t),
-  });
-  const ctx = handle._ctx;
-
-  await _internals.ladderStep(ctx);
-  await flush(); // wake handlers resolve on a microtask
-
-  assert.equal(woke.length, 1, "40 messages in a channel are ONE thing to go look at");
-  assert.equal(woke[0].metadata.pushSeq, 1, "the leading edge fires instantly — that is the product promise");
-
-  // The trailing wake was scheduled for the end of the window; fire it.
-  const trailing = timers.scheduled.filter((t) => t.ms > 0 && t.ms <= 1_500);
-  assert.equal(trailing.length, 1, "exactly one trailing timer, not one per event");
-  clock += 1_500;
-  trailing[0].fn();
-  await flush();
-
-  assert.equal(woke.length, 2, "the tail of the burst is never stranded until the 45s cadence");
-  assert.equal(woke[1].metadata.pushSeq, 4, "the trailing wake carries the newest seq");
-  handle.stop();
-});
-
-test("relevance: unknown families are consumed (cursor advances) but wake nothing", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([
-    streamResponse([
-      JSON.stringify({ seq: 50, family: "cost", kind: "report" }),
-      JSON.stringify({ seq: 51, family: "policy", kind: "publish" }),
-      EV(52),
-    ]),
-  ]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, enqueueTick: (t) => woke.push(t) });
-  await _internals.ladderStep(ctx);
-  await flush();
-  assert.equal(ctx.cursor, 52, "irrelevant events are still consumed — otherwise they replay forever");
-  assert.equal(woke.length, 1);
-  assert.equal(woke[0].metadata.pushSeq, 52);
-  handle.stop();
-});
-
-test("relevance: our own action echoing back does not wake us; an unproven event still does", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([
-    streamResponse([
-      JSON.stringify({ seq: 60, family: "messaging", kind: "send", actor: "alex-ai" }),  // us
-      JSON.stringify({ seq: 61, family: "email", kind: "received", payload: { memberId: "someone-else" } }),
-      JSON.stringify({ seq: 62, family: "messaging", kind: "send", actor: "human-1" }),
-    ]),
-  ]);
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl, wakeCoalesceMs: 0, selfIds: ["alex-ai"], enqueueTick: (t) => woke.push(t),
-  });
-  await _internals.ladderStep(ctx);
-  await flush();
-  assert.deepEqual(woke.map((w) => w.metadata.pushSeq), [62],
-    "only the event we cannot rule out — the frame can never PROVE an event is ours");
-  handle.stop();
-});
-
-test("a target with no default fetcher degrades quietly to its own poll (no throw, no tick)", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const fetchImpl = fakeFetch([streamResponse([JSON.stringify({ seq: 80, family: "email", kind: "received" })])]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, enqueueTick: (t) => woke.push(t) });
-  await assert.doesNotReject(async () => { await _internals.ladderStep(ctx); });
-  await flush();
-  assert.equal(woke.length, 0, "no cadence exists for orgmail — its adapter's own 45s poll stays the fetcher");
-  assert.equal(ctx.cursor, 80);
-  handle.stop();
-});
-
-test("onEvent observer sees every accepted event and cannot break the channel", async () => {
-  const root = tmpRepo();
-  const seen = [];
-  const fetchImpl = fakeFetch([streamResponse([EV(90), EV(91)])]);
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl, wakeCoalesceMs: 0, enqueueTick: () => {},
-    onEvent: (e) => { seen.push(e.seq); throw new Error("observer boom"); },
-  });
-  await assert.doesNotReject(async () => { await _internals.ladderStep(ctx); });
-  assert.deepEqual(seen, [90, 91]);
-  assert.equal(ctx.cursor, 91);
-  handle.stop();
-});
-
-// ---------------------------------------------------------------------------
-// Lifecycle + parsing units
-// ---------------------------------------------------------------------------
-
-test("stop() aborts the in-flight stream, clears timers and is idempotent", async () => {
-  const root = tmpRepo();
-  const cleared = [];
-  let aborted = 0;
-  const handle = await connectOrgPush({
-    agentRoot: root, cfg: cfgEnabled(), client: fakeClient(),
-    setTimeout: (fn, ms) => ({ fn, ms, unref() {} }),
-    clearTimeout: (h) => cleared.push(h),
-  });
-  handle._ctx.abort = { abort: () => { aborted += 1; } };
-  handle.stop();
-  handle.stop();
-  assert.equal(aborted, 1, "the held connection is torn down exactly once");
-  assert.equal(cleared.length, 1, "the pump timer is cleared exactly once");
-  assert.equal(handle._ctx.stopped, true);
-});
-
-test("decodeFrameLine: the wire vocabulary", () => {
-  assert.equal(decodeFrameLine("").kind, "ignore");
-  assert.equal(decodeFrameLine(": ping").kind, "heartbeat");
-  assert.equal(decodeFrameLine("event: message").kind, "ignore");
-  assert.equal(decodeFrameLine("id: 7").kind, "ignore");
-  assert.equal(decodeFrameLine('{"type":"heartbeat"}').kind, "heartbeat");
-  assert.equal(decodeFrameLine('{"type":"ready","cursor":9}').cursor, 9);
-  assert.equal(decodeFrameLine("garbage").kind, "ignore");
-  assert.equal(decodeFrameLine("{oops").kind, "malformed");
-  assert.equal(decodeFrameLine('{"type":"event"}').kind, "malformed");
-  const ev = decodeFrameLine(`data: ${EV(3)}`);
-  assert.equal(ev.kind, "event");
-  assert.equal(ev.event.seq, 3);
-  // hq's own fan-out frame carries no `type` at all — it must still parse.
-  const bare = decodeFrameLine(JSON.stringify({ seq: 4, family: "artifact", kind: "created" }));
-  assert.equal(bare.kind, "event");
-});
-
-test("v1Url matches the client's binding rules (bare origin vs /v1-suffixed base)", () => {
-  assert.equal(_internals.v1Url("https://x.dev", "agent.stream"), "https://x.dev/api/v1/agent.stream");
-  assert.equal(_internals.v1Url("https://x.dev/api/v1", "agent.stream"), "https://x.dev/api/v1/agent.stream");
-  assert.equal(_internals.v1Url("https://x.dev/v1/", "agent.wait"), "https://x.dev/v1/agent.wait");
-});
-
-test("the stream carries Bearer auth + the protocol header + the org pin", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([streamResponse([])]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl });
-  await _internals.ladderStep(ctx);
-  const h = fetchImpl.calls[0].init.headers;
-  assert.equal(h.authorization, "Bearer tok");
-  assert.equal(h["x-org-id"], "acme");
-  assert.ok(String(h.accept).includes("text/event-stream"));
-  assert.ok(String(h.accept).includes("application/x-ndjson"), "both framings are acceptable to us");
-  handle.stop();
-});
-
-test("housekeeping: tmp roots are removable (no lingering handles)", () => {
-  const root = tmpRepo();
-  assert.ok(existsSync(root));
-  rmSync(root, { recursive: true, force: true });
-  assert.equal(existsSync(root), false);
-});
-
-// ---------------------------------------------------------------------------
-// JOINT 3 — the wire contract, corrected against the DEPLOYED hq
-// ---------------------------------------------------------------------------
-
-test("JOINT 3: the stream path is /api/v1/stream, not /api/v1/agent.stream", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([streamResponse([EV(5)])]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, minHealthyMs: 0, enqueueTick: () => {} });
-  await _internals.ladderStep(ctx);
-  // `agent.stream` resolves to hq's [...method] catch-all, which answers 404 for
-  // an unknown read — read by the ladder as "endpoint absent" and demoted
-  // instantly, forever. hq serves the stream as a STATIC route at /api/v1/stream.
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/stream(\?|$)/);
-  assert.ok(!/agent\.stream/.test(fetchImpl.calls[0].url), "agent.stream is a path that has never existed on hq");
-  handle.stop();
-});
-
-test("JOINT 3: hq's untyped `cursor` watermark frame advances the resume point", () => {
-  // These are hq's REAL frames (src/server/agent-stream/sse.ts): no `type`, no
-  // `seq`, no `family` — the old decoder returned "ignore" for all three, so a
-  // reconnect re-asked hq to rescan every event that was not this seat's.
-  assert.deepEqual(decodeFrameLine('data: {"cursor":12766}'), { kind: "cursor", cursor: 12766 });
-  assert.deepEqual(
-    decodeFrameLine('data: {"orgId":"o","memberId":"m","cursor":12600,"heartbeatMs":20000,"lifetimeMs":900000}'),
-    { kind: "cursor", cursor: 12600 },
-  );
-  assert.deepEqual(decodeFrameLine('data: {"reason":"lifetime","cursor":13000,"message":"reconnect"}'), { kind: "cursor", cursor: 13000 });
-  // An event frame is still an event frame — the watermark branch must not eat it.
-  assert.equal(decodeFrameLine(`data: ${EV(9)}`).kind, "event");
-});
-
-test("JOINT 3: a watermark frame moves the persisted cursor FORWARD ONLY", async () => {
-  const root = tmpRepo();
-  const fetchImpl = fakeFetch([
-    streamResponse([
-      'data: {"orgId":"o","memberId":"m","cursor":500}',
-      EV(501),
-      'data: {"cursor":900}',   // 399 events that were NOT ours
-      'data: {"cursor":400}',   // a stale/mis-ordered frame must not rewind us
-    ]),
-  ]);
-  const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, minHealthyMs: 0, enqueueTick: () => {} });
-  await _internals.ladderStep(ctx);
-  await flush();
-  assert.equal(ctx.cursor, 900, "the checkpoint past other members' business is honoured");
-  assert.equal(readCursor(root), 900, "and persisted, so a restart does not rescan it");
-  handle.stop();
-});
-
-test("JOINT 3: every inbound family wakes the authoritative pull — board included", async () => {
-  const root = tmpRepo();
-  const woke = [];
-  const families = ["messaging", "board", "calendar", "escalation", "approval", "decision", "files", "handoff", "calling"];
-  const lines = families.map((f, i) => EV(200 + i, f, "x"));
-  const fetchImpl = fakeFetch([streamResponse(lines)]);
-  const { handle, ctx } = await mkHandle(root, {
-    fetchImpl, wakeCoalesceMs: 0, minHealthyMs: 0, enqueueTick: (t) => woke.push(t),
-  });
-  await _internals.ladderStep(ctx);
-  await flush();
-  assert.equal(woke.length, families.length, `every inbound family must wake something; got ${woke.length}/${families.length}`);
-  assert.ok(woke.every((w) => w.cadence === "messaging-inbound"), "one nudge, one authoritative ACL'd pull, one cursor");
-  handle.stop();
-});
-
-test("JOINT 3: a family hq proved is ours but nothing consumes is dropped LOUDLY", async () => {
-  const root = tmpRepo();
-  const warns = [];
-  const realWarn = console.warn;
-  console.warn = (...a) => warns.push(a.join(" "));
-  try {
-    const fetchImpl = fakeFetch([streamResponse([EV(300, "artifact", "action")])]);
-    const { handle, ctx } = await mkHandle(root, { fetchImpl, wakeCoalesceMs: 0, minHealthyMs: 0, enqueueTick: () => {} });
-    await _internals.ladderStep(ctx);
-    await flush();
-    assert.equal(ctx.cursor, 300, "it is still consumed — not advancing would re-deliver it forever");
-    assert.ok(
-      warns.some((w) => /"artifact" frame it had already resolved as THIS SEAT'S/.test(w)),
-      `a dropped for-me frame must be visible; got ${JSON.stringify(warns)}`,
-    );
-    handle.stop();
-  } finally {
-    console.warn = realWarn;
-  }
-});