@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/lib/org/push.mjs

@@ -64,23 +64,35 @@
  * THE WIRE CONTRACT (what this expects of hq)
  * ============================================================================
  *
- * Rung 1 — GET `{base}/api/v1/agent.stream?cursor=<seq>`
- *   Accept: `text/event-stream, application/x-ndjson`. Held open; each frame is
- *   one line. BOTH framings are accepted by the parser below:
- *     - SSE:    `data: {...}\n\n`, with `:` comment lines as keepalives
- *     - NDJSON: `{...}\n`  (hq's house streaming format — see its AI gateway,
- *               which returns `application/x-ndjson`; there is no SSE precedent
- *               in that repo, so committing to only one framing would be a bet)
- *   Frame bodies:
- *     `{seq, family, kind, entityId, actor, at, payload}`  — a committed event
- *     `{type:"heartbeat"}`                                  — liveness only
- *     `{type:"ready", cursor}`                              — optional preamble
+ * VERIFIED AGAINST THE DEPLOYED APP (os.cohortapp.com), not inferred.
+ *
+ * Rung 1 — GET `{base}/api/v1/stream?cursor=<seq>`
+ *   `stream`, not `agent.stream`: it is a static Next route
+ *   (`hq src/app/api/v1/stream/route.ts`) that wins over the `[...method]`
+ *   catch-all. Accept: `text/event-stream`. Held open (15-min lifetime cap),
+ *   ~2KB comment preamble, 20s heartbeat comments, `X-Accel-Buffering: no`.
+ *   Both framings are accepted by the parser below (SSE `data:` lines and bare
+ *   NDJSON), because a future hq lane may use either.
+ *   Frame bodies, all UNTYPED (no `type` field) — recognised structurally:
+ *     `{seq, topic, reason, family, kind, entityId, actor, at, ids}` — an item
+ *        ALREADY FILTERED TO THIS SEAT by hq (relevance.ts#selectForMember)
+ *     `{orgId, memberId, cursor, heartbeatMs, lifetimeMs}`  — `event: ready`
+ *     `{cursor}`                                            — `event: cursor`,
+ *        the watermark past events that were NOT this seat's
+ *     `{reason, cursor, message}`                           — `event: bye`
+ *     `: …` comment lines                                    — heartbeats
  *   Anything unrecognised is ignored (forward-compatible).
  *
- * Rung 2 — GET `{base}/api/v1/agent.wait?cursor=<seq>&timeoutMs=55000`
- *   Returns the BARE payload (hq's GET lane never wraps reads in an ok-frame):
- *     `{ events: [ {seq, family, kind, ...}, ... ], cursor: <newHead> }`
- *   Empty `events` after the timeout is a normal, successful response.
+ * Rung 2 — POST `{base}/api/v1/agent.wait`  `{since?, timeoutMs, limit?}`
+ *   A METHOD on the dispatcher, NOT a GET read (the read lane's HANDLED_READS
+ *   list does not contain it — see waitOnce for the full autopsy). Returns the
+ *   standard ok-frame wrapping:
+ *     `{ cursor, items: [{seq, family, kind, entityId, actor, at, reason, ref}],
+ *        timedOut, bootstrap, memberId, waitedMs }`
+ *   `reason` is hq's RELATIONAL verdict (mention/channel/assignee/reviewer/
+ *   call_participant/mailbox_owner/mailbox_member), resolved server-side against
+ *   the projection tables — the chain payload is redacted and cannot name a
+ *   recipient. Empty `items` after the timeout is a normal, successful response.
  *
  * Both lanes key off `CohortEvent.seq` — the per-org monotonic, DB-unique,
  * gap-free ledger cursor hq's own poll route uses. Not the 30s ephemeral ring,
@@ -117,17 +129,32 @@ export const PUSH_RUNG = Object.freeze({
   CADENCE: "cadence",
 });
 
-/** Read path for the held stream (rung 1). */
-export const DEFAULT_STREAM_PATH = "agent.stream";
-/** Read path for the bounded long-poll (rung 2). */
+/**
+ * Path for the held stream (rung 1).
+ *
+ * `stream`, NOT `agent.stream`. hq serves this as an ORDINARY Next route at
+ * `src/app/api/v1/stream/route.ts` — a static segment that wins over the
+ * `[...method]` catch-all. `agent.stream` was a guess made before the server
+ * existed, and it resolved to the catch-all, which answered `NOT_FOUND` for an
+ * unknown read: the ladder read that as "this hq has no stream endpoint",
+ * demoted instantly and never probed rung 1 again. Verified against the
+ * deployed app: `GET /api/v1/stream` → 200 `text/event-stream`.
+ */
+export const DEFAULT_STREAM_PATH = "stream";
+/** Method name for the bounded long-poll (rung 2). A POST RPC — see waitOnce. */
 export const DEFAULT_WAIT_PATH = "agent.wait";
 
 /**
- * Long-poll hold, ms. 55s is not arbitrary: it is the bound hq's `approval.wait`
- * clamps to and the only hold length PROVEN to survive Railway's proxy in front
- * of `next start`. Do not raise it without measuring against the deployed app.
+ * Long-poll hold, ms.
+ *
+ * 25s, not 55s. `approval.wait` holds 55s and proves Railway tolerates it, but
+ * `agent.wait` deliberately caps itself at 25s (hq `methods/agent/wait.ts`
+ * MAX_WAIT_MS) because 30s is the tightest idle-read timeout in the common proxy
+ * layer between a daemon and the app. Asking for 55s does not get 55s — hq
+ * clamps it — it only makes OUR abort budget wrong, so we would tear down a
+ * healthy hold that was about to answer. Ask for what the server actually gives.
  */
-export const DEFAULT_WAIT_MS = 55_000;
+export const DEFAULT_WAIT_MS = 25_000;
 
 /**
  * Recycle a held stream after this long even when it looks healthy (ms). A
@@ -175,11 +202,47 @@ export const STATUS_RELATIVE = "state/org/push-status.json";
  * replace, or disable any of them without touching this module.
  */
 export const FAMILY_WAKE_TARGET = Object.freeze({
+  // ── The INBOUND families. Every one of these can carry something addressed to
+  //    this seat, and every one is resolved authoritatively by the wide inbound
+  //    reader behind the `messaging-inbound` cadence
+  //    (lib/org/inbound.pullWideInbound). They therefore all wake the SAME
+  //    target, which is the whole point: one nudge, one authoritative pull, one
+  //    cursor, one dedup-guarded write.
+  //
+  //    This map used to send `board`/`work` to a "board" target whose handler
+  //    escalates (spawns a session), and to name no target at all for files,
+  //    decision, escalation, approval, handoff or calendar — so a task assigned
+  //    to this agent produced NO wake, and the only thing that would ever find
+  //    it was a cadence tick against a reader that filtered the family out. That
+  //    is the shape of "board, task, calendar, escalation, approval and mandate
+  //    events never reach a daemon at all".
   messaging: "org-messaging",
   calling: "org-messaging",
+  board: "org-messaging",
+  work: "org-messaging",
+  file: "org-messaging",
+  files: "org-messaging",
+  decision: "org-messaging",
+  escalation: "org-messaging",
+  approval: "org-messaging",
+  handoff: "org-messaging",
+  calendar: "org-messaging",
+  meetings: "org-messaging",
+  // `mandate.*` is a governance lane: adopting/retiring a mandate changes what
+  // this seat is FOR. It gets its OWN target rather than being folded into
+  // `org-messaging`, because the wide inbound reader has no `mandate` branch —
+  // waking it would spend a pull that structurally cannot see the event. With no
+  // default handler this target logs once and degrades to the plan refresh's own
+  // cadence, which is honest; an agent repo that wants instant mandate reload
+  // passes `wake: { mandate: () => … }`.
+  mandate: "mandate",
+
+  // ── Lanes with their OWN fetcher. Email is polled by the orgmail channel
+  //    adapter (which writes its own inbox items) — waking the wide reader too
+  //    would double-deliver every mail into a thread-lease race, which is
+  //    exactly why the `email` inbound surface defaults OFF. Branding has its
+  //    own steward cadence.
   email: "orgmail",
-  board: "board",
-  work: "board",
   branding: "brand",
 });
 
@@ -335,13 +398,32 @@ export function decodeFrameLine(line) {
   if (type === "error") return { kind: "malformed" }; // a server-side error frame ends the read
 
   // An event either says so, or is recognised structurally: hq's own fan-out
-  // frame is {family, kind, entityId, actor, at, seq, payload} with NO `type`.
+  // frame is {seq, topic, reason, family, kind, entityId, actor, at, ids} with
+  // NO `type` (src/server/agent-stream/relevance.ts#selectForMember).
   const seq = Number(obj.seq);
   const hasShape = Number.isFinite(seq) && typeof obj.family === "string" && obj.family !== "";
   if (type === "event" || hasShape) {
     if (!hasShape) return { kind: "malformed" }; // claimed to be an event, isn't one
     return { kind: "event", event: obj };
   }
+
+  // ── WATERMARK FRAMES. hq emits three untyped frames that carry only a cursor:
+  //      event: ready   {orgId, memberId, cursor, heartbeatMs, lifetimeMs}
+  //      event: cursor  {cursor}
+  //      event: bye     {reason, cursor, message}
+  //    The `cursor` one is NOT optional bookkeeping — it is how the server moves
+  //    our resume watermark past events that were NOT for this seat. Verified on
+  //    the deployed app: a 20s idle hold emitted `data: {"cursor":12766}` after a
+  //    `ready` at 12600, i.e. 166 events of other members' business. Treating it
+  //    as `ignore` (which this parser did) means every reconnect re-asks hq to
+  //    re-scan that whole span, and it grows without bound in a busy org.
+  //
+  //    We key off the SHAPE — a numeric `cursor` and nothing event-like — rather
+  //    than the SSE `event:` field, because the field arrives on a different line
+  //    and this decoder is deliberately line-at-a-time and stateless.
+  const c = Number(obj.cursor);
+  if (Number.isFinite(c) && c >= 0) return { kind: "cursor", cursor: c };
+
   return { kind: "ignore" }; // forward-compatible: unknown frame types are fine
 }
 
@@ -366,7 +448,23 @@ export function decodeFrameLine(line) {
 function wakeTargetFor(ctx, ev) {
   const family = typeof ev.family === "string" ? ev.family : "";
   const target = FAMILY_WAKE_TARGET[family];
-  if (!target) return null;
+  if (!target) {
+    // NEVER SILENT. hq's SSE lane classifies eleven families
+    // (`agent-stream/relevance.ts`) and every frame it sends has ALREADY been
+    // proven to concern this seat. A family with no entry here is therefore a
+    // frame hq went to the trouble of addressing to us, that we consume and
+    // throw away. That is a delivery gap, not a filter — say so, once per
+    // family, so it shows up as a line rather than as an agent that "seems
+    // slow on artifacts".
+    if (family && !ctx.warnedTargets.has(`family:${family}`)) {
+      ctx.warnedTargets.add(`family:${family}`);
+      logWarn(
+        `hq pushed a "${family}" frame it had already resolved as THIS SEAT'S, and nothing here consumes that family — ` +
+        `it is being dropped. Add it to FAMILY_WAKE_TARGET (and give the wide inbound reader a branch) to close the gap.`,
+      );
+    }
+    return null;
+  }
 
   // Our own committed action echoing back is not news. Only applies when the
   // caller told us which ids are "us" — otherwise we cannot know, so we wake.
@@ -507,6 +605,31 @@ function dispatchEvent(ctx, ev) {
   return outcome;
 }
 
+/**
+ * Move the persisted watermark to a server-reported head. FORWARD ONLY.
+ *
+ * Both lanes report a head that can be AHEAD of the last frame they sent us:
+ * the SSE `cursor` checkpoint and `agent.wait`'s `cursor` both mean "I have
+ * EVALUATED up to here and nothing else in that span was yours." Honouring it is
+ * what stops every reconnect re-scanning other members' business; refusing to
+ * rewind is what stops a stale or mis-ordered frame replaying work.
+ *
+ * @param {object} ctx
+ * @param {number|undefined} head
+ * @param {string} why  frame kind, for the log
+ * @returns {boolean} whether the cursor moved
+ */
+function advanceCursor(ctx, head, why) {
+  const n = Number(head);
+  if (!Number.isFinite(n) || n < 0) return false;
+  if (ctx.cursor != null && n <= ctx.cursor) return false;
+  ctx.cursor = n;
+  writeCursor(ctx.agentRoot, n, ctx.now);
+  ctx.stats.checkpoints = (ctx.stats.checkpoints || 0) + 1;
+  if (why === "ready") logInfo(`resumed at ledger cursor ${n}`);
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // URLs + headers
 // ---------------------------------------------------------------------------
@@ -648,6 +771,11 @@ async function consumeStream(ctx) {
         const frame = decodeFrameLine(line);
         if (frame.kind === "event") {
           if (dispatchEvent(ctx, frame.event) === "delivered") delivered += 1;
+        } else if (frame.kind === "cursor" || frame.kind === "ready") {
+          // A server watermark. Forward-only, always — a rewind would replay
+          // events we have already woken on, and the cursor is the ONE piece of
+          // durable state this module owns.
+          advanceCursor(ctx, frame.cursor, frame.kind);
         } else if (frame.kind === "malformed") {
           // ONE bad frame must not cost the connection: count it, keep reading.
           ctx.stats.malformed += 1;
@@ -683,20 +811,49 @@ async function consumeStream(ctx) {
 // ---------------------------------------------------------------------------
 
 /**
- * One `agent.wait` round-trip. Follows the `approval.wait` precedent exactly:
- * a GET on the read lane returning the BARE payload, with the client abort
- * budgeted to outlast the server's own bound so the server gets to answer rather
+ * One `agent.wait` round-trip.
+ *
+ * ── IT IS A POST RPC, NOT A GET READ ──
+ * This used to call `client.read("agent.wait?cursor=…&timeoutMs=…")`, i.e. a GET
+ * on the `/v1` read lane. That lane dispatches from a CLOSED list
+ * (`hq src/server/rpc/reads.ts#HANDLED_READS`: snapshot, directory, events,
+ * board.ready, hierarchy, board.context, ops, approval.wait, cost.rollup,
+ * decision.list, policy, contacts.list, meetings.list, subagent.roster) —
+ * `agent.wait` is not on it and never was. Every rung-2 attempt therefore came
+ * back `NOT_FOUND` with HTTP 404, which `isUnsupportedStatus` reads as "this hq
+ * doesn't have the endpoint": instant demotion to CADENCE, no retry, no probe.
+ * The long-poll rung could not have worked on any hq, ever.
+ *
+ * `agent.wait` is a `sideEffecting:false` METHOD — `POST /api/v1/agent.wait`
+ * through the dispatcher (`hq src/server/methods/agent/wait.ts`). Its params are
+ * `{since, timeoutMs, limit}` under a `.strict()` zod schema, so `cursor` would
+ * have been rejected as an unknown key even on the right verb.
+ *
+ * ── THE RETURN CONTRACT IS `items`, NOT `events` ──
+ * `{cursor, items, timedOut, bootstrap, memberId, waitedMs}`. Each item is
+ * `{seq, family, kind, entityId, actor, at, reason, ref}` — ledger coordinates
+ * plus a RELATIONAL `reason` ("mention" | "channel" | "assignee" | "reviewer" |
+ * "call_participant" | "mailbox_owner" | "mailbox_member") that hq derived by
+ * joining the projection tables that name a seat. No body, no subject, no
+ * payload. That is the ACL-safe way to learn "this one is for me": the server
+ * resolved it against Mention / ChannelMember / Task / CallParticipant / Mailbox
+ * under `ctx.scopeWhere`, and we never widened a chain payload to carry it.
+ *
+ * The abort budget outlasts the server's own bound so hq gets to answer rather
  * than us aborting first. Never throws.
  *
  * @returns {Promise<{ok:boolean, unsupported?:boolean, reason:string, delivered:number}>}
  */
 async function waitOnce(ctx) {
   const startedAt = ctx.now();
-  const q = ctx.cursor != null ? `?cursor=${encodeURIComponent(ctx.cursor)}&` : "?";
-  const path = `${ctx.waitPath}${q}timeoutMs=${encodeURIComponent(ctx.waitMs)}`;
+  const params = { timeoutMs: ctx.waitMs };
+  // `since` ABSENT means "bootstrap at head, replay nothing" — the same
+  // distinction readCursor preserves. Sending 0 would replay the org's history.
+  if (ctx.cursor != null) params.since = ctx.cursor;
+
   let r;
   try {
-    r = await ctx.client.read(path, {
+    r = await ctx.client.call(ctx.waitPath, params, {
       base: ctx.base,
       token: ctx.token,
       orgId: ctx.orgId,
@@ -704,36 +861,42 @@ async function waitOnce(ctx) {
       timeoutMs: ctx.waitMs + 5_000,
     });
   } catch (err) {
-    // client.read is documented fail-open, but a caller must never assume.
+    // client.call is documented fail-open, but a caller must never assume.
     return { ok: false, reason: `wait threw: ${err && err.message}`, delivered: 0, lived: ctx.now() - startedAt };
   }
-  if (!r || !r.ok) {
+  if (!r || r.ok !== true) {
     const status = Number(r && r.status) || 0;
-    if (isUnsupportedStatus(status)) return { ok: false, unsupported: true, reason: `http ${status} (endpoint absent)`, delivered: 0, lived: ctx.now() - startedAt };
     const code = (r && r.error && r.error.code) || "UNKNOWN";
+    // A method this hq does not carry answers NOT_FOUND (the dispatcher's own
+    // frame) or 404/405/501 at the transport. Both mean "stop asking".
+    if (isUnsupportedStatus(status) || code === "NOT_FOUND") {
+      return { ok: false, unsupported: true, reason: `${code}${status ? ` (http ${status})` : ""} — endpoint absent`, delivered: 0, lived: ctx.now() - startedAt };
+    }
     return { ok: false, reason: `${code}${status ? ` (http ${status})` : ""}`, delivered: 0, lived: ctx.now() - startedAt };
   }
 
-  const payload = r.payload || {};
-  const events = Array.isArray(payload.events) ? payload.events : Array.isArray(payload) ? payload : [];
+  const result = (r.result && typeof r.result === "object" ? r.result : null) || {};
+  // `items` is the contract. `events` is tolerated so an older/newer hq, or the
+  // reference server, does not silently deliver nothing.
+  const items = Array.isArray(result.items)
+    ? result.items
+    : Array.isArray(result.events)
+      ? result.events
+      : [];
   let delivered = 0;
-  for (const ev of events) {
+  for (const it of items) {
     if (ctx.stopped) break;
-    const outcome = dispatchEvent(ctx, ev);
-    if (outcome === "delivered") delivered += 1;
-  }
-  // hq may report a head beyond the last event it sent (e.g. everything in the
-  // slice was filtered server-side). Trust it forward-only — never rewind.
-  const head = Number(payload.cursor);
-  if (Number.isFinite(head) && head > 0 && (ctx.cursor == null || head > ctx.cursor)) {
-    ctx.cursor = head;
-    writeCursor(ctx.agentRoot, head, ctx.now);
+    if (dispatchEvent(ctx, it) === "delivered") delivered += 1;
   }
+  // hq reports a head beyond the last item it sent whenever the span it
+  // evaluated held other members' business. Forward-only — never rewind.
+  advanceCursor(ctx, result.cursor, "wait");
+
   return {
     ok: true,
-    reason: events.length ? `${events.length} event(s)` : "timeout (no events)",
+    reason: items.length ? `${items.length} item(s) for this seat` : "timeout (nothing for this seat)",
     delivered,
-    events: events.length,
+    events: items.length,
     lived: ctx.now() - startedAt,
   };
 }
@@ -1013,6 +1176,7 @@ export const _internals = {
   consumeStream,
   waitOnce,
   dispatchEvent,
+  advanceCursor,
   scheduleWake,
   wakeTargetFor,
   setRung,

package/lib/org/push.test.mjs

@@ -49,18 +49,33 @@ function cfgDisabled() {
   return { org: { cohort: { enabled: false, base: BASE, token: "tok" } } };
 }
 
-/** A fake org client: only what push.mjs uses (isEnabled/configFromAgent/read). */
+/**
+ * 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;
 }
@@ -315,7 +330,7 @@ test("ladder: repeated stream failures demote to the long-poll, which then deliv
     new Error("ECONNRESET"),
   ]);
   const client = fakeClient({
-    reads: [{ ok: true, status: 200, payload: { events: [JSON.parse(EV(100)), JSON.parse(EV(101))], cursor: 101 } }],
+    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),
@@ -333,9 +348,10 @@ test("ladder: repeated stream failures demote to the long-poll, which then deliv
 
   await _internals.ladderStep(ctx);
   await flush();
-  assert.equal(client.readCalls.length, 1, "the long-poll lane took over");
-  assert.match(client.readCalls[0].path, /^agent\.wait\?/);
-  assert.match(client.readCalls[0].path, /timeoutMs=55000/, "the 55s bound approval.wait proved");
+  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();
@@ -344,7 +360,7 @@ test("ladder: repeated stream failures demote to the long-poll, which then deliv
 test("ladder: repeated long-poll failures demote to CADENCE, which idles instead of hammering", async () => {
   const root = tmpRepo();
   const client = fakeClient({
-    reads: [
+    calls: [
       { ok: false, status: 500, error: { code: "INTERNAL" } },
       { ok: false, status: 500, error: { code: "INTERNAL" } },
       { ok: false, status: 0, error: { code: "INTERNAL" } },
@@ -361,9 +377,9 @@ test("ladder: repeated long-poll failures demote to CADENCE, which idles instead
   await _internals.ladderStep(ctx);
   assert.equal(ctx.rung, PUSH_RUNG.CADENCE, "the floor of the ladder");
 
-  const before = client.readCalls.length;
+  const before = client.callCalls.length;
   const delay = await _internals.ladderStep(ctx);
-  assert.equal(client.readCalls.length, before, "the cadence rung issues NO requests — it is the 45s poll doing the work");
+  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.
@@ -396,7 +412,7 @@ test("ladder: a lower rung is probed back up to the stream after the dwell perio
 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({ reads: [{ ok: false, status: 404, error: { code: "NOT_FOUND" } }] });
+  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);
@@ -514,7 +530,7 @@ test("a long-poll that answers INSTANTLY with nothing is floored, not spun", asy
   // 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({ reads: [{ ok: true, status: 200, payload: { events: [] } }] });
+  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,
   });
@@ -688,3 +704,89 @@ test("housekeeping: tmp roots are removable (no lingering handles)", () => {
   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;
+  }
+});