@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/org/push.mjs

@@ -0,0 +1,1025 @@
+/**
+ * lib/org/push.mjs — the agent's PUSH channel onto the org event ledger.
+ *
+ * THE GAP this closes: an agent currently learns about org activity on a POLL.
+ * The `messaging-inbound` cadence runs every 45s (lib/cadences.mjs:66) and the
+ * orgmail adapter polls every 45s (lib/channels/orgmail/adapter.mjs:61), so a
+ * human who @mentions an AI colleague in the Cohort app waits up to three
+ * quarters of a minute for the agent to even NOTICE. hq already knows the agent
+ * is alive — it suppresses its own in-process LLM responder for any member whose
+ * daemon beat within 100s (hq src/server/llm-responder/sdk-driven.ts) — so the
+ * hand-off is real: hq stays quiet, and the daemon owes the org a fast answer.
+ * This module is the delivery half of that hand-off.
+ *
+ * ============================================================================
+ * THE LADDER (this is the whole design; the rest is mechanics)
+ * ============================================================================
+ *
+ *   1. STREAM   — one held HTTP connection, server pushes frames as they commit.
+ *                 Preferred: zero idle requests, sub-second wake.
+ *   2. LONGPOLL — a bounded `agent.wait` request (the `approval.wait` precedent,
+ *                 hq src/server/rpc/reads.ts:532 — proven to survive a ~55s hold
+ *                 behind Railway's proxy). Used when the stream cannot be
+ *                 established or keeps dying.
+ *   3. CADENCE  — nothing. We stop talking and the EXISTING 45s cadences carry
+ *                 the agent, exactly as they do today.
+ *
+ * Rung 3 is not a failure mode we tolerate reluctantly — it is the safety net the
+ * whole design rests on. **The cadences are never disabled by this module.** They
+ * keep running underneath the push channel at all times, which is what makes
+ * every hard decision below cheap:
+ *
+ *   - a dropped frame is not lost work (the cadence re-discovers it ≤45s later),
+ *   - a duplicate frame is harmless (the cadence path is already dedup-guarded:
+ *     `pullInbound` has its own cursor and `writeInboxItem` refuses re-writes),
+ *   - and a push channel that dies entirely degrades the agent to TODAY'S
+ *     behaviour rather than making it deaf.
+ *
+ * That is the house rule from lib/org/mesh.mjs, applied to a live connection:
+ * fail-open, loudly, never take the daemon down.
+ *
+ * ============================================================================
+ * WHY THIS IS A *WAKE* CHANNEL, NOT A DELIVERY CHANNEL
+ * ============================================================================
+ *
+ * hq's event frames are REDACTED by design. `messaging.send` appends only
+ * `{actor, channelId, channelKind, recipientCount, mentionCount, ...}` — counts,
+ * never recipient ids (hq src/server/methods/messaging/send.ts:124-139); a call
+ * invite carries `inviteCount`, not invitees. **A frame is structurally incapable
+ * of telling us "this one is for you."** Answering that question means joining
+ * Mention / ChannelMember / Task.assigneeId / CallParticipant / Mailbox — i.e.
+ * exactly what `lib/org/messaging.pullInbound` and `email.inbox` already do,
+ * server-side, correctly, with their own cursors.
+ *
+ * So we do NOT try to re-derive recipient-ness on the client. A pushed frame is
+ * treated as a HINT: "something happened in family X at seq N — go look." The
+ * wake handler kicks the existing authoritative fetch (by default: enqueue a
+ * `messaging-inbound` tick onto the cadence bus, which the consumer drains within
+ * ~2s and which routes real directed items into the inbox pipeline). The push
+ * channel therefore changes ONE number — time-to-notice, 45s → ~1s — and changes
+ * nothing else about how work is fetched, deduped, or dispatched. Small blast
+ * radius, and the 45s path stays warm and exercised.
+ *
+ * ============================================================================
+ * 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
+ *   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.
+ *
+ * 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,
+ * not the 500-frame Redis tail: those lose data across a deploy, and a cursor
+ * that survives a restart is the entire point. A 404/405/501 on either path means
+ * "this hq doesn't have that endpoint yet" and demotes INSTANTLY without retries —
+ * an SDK that ships ahead of the server must not hammer it.
+ *
+ * ============================================================================
+ * Node builtins + existing maestro libs only. ESM. Every seam — clock, timers,
+ * fetch, RNG, the org client, the cadence enqueuer — is injectable, so the whole
+ * ladder is testable with no sockets and no real time.
+ *
+ * @module lib/org/push
+ */
+
+"use strict";
+
+import { join, resolve, dirname } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync } from "node:fs";
+
+import * as defaultClient from "./client.mjs";
+import { PROTOCOL_VERSION } from "./protocol.mjs";
+import { decorrelatedBackoff } from "../util/reconnect.mjs";
+
+// ---------------------------------------------------------------------------
+// Contract constants
+// ---------------------------------------------------------------------------
+
+/** The three rungs of the ladder. Frozen — this is a contract, not a hint. */
+export const PUSH_RUNG = Object.freeze({
+  STREAM: "stream",
+  LONGPOLL: "longpoll",
+  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). */
+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.
+ */
+export const DEFAULT_WAIT_MS = 55_000;
+
+/**
+ * Recycle a held stream after this long even when it looks healthy (ms). A
+ * half-open connection through a proxy is indistinguishable from an idle one
+ * until you try to write; periodically re-establishing turns "silently deaf
+ * forever" into "at most a 15-minute deafness, and we'd have noticed via the
+ * idle watchdog first anyway".
+ */
+export const DEFAULT_STREAM_MAX_MS = 15 * 60_000;
+
+/**
+ * Abort a stream that has produced NO bytes at all (not even a heartbeat) for
+ * this long (ms). hq is expected to heartbeat; absent bytes means the connection
+ * is dead or the proxy is buffering us into uselessness — either way, drop it and
+ * let the ladder decide.
+ */
+export const DEFAULT_IDLE_MS = 90_000;
+
+/** Consecutive failures on a rung before demoting to the next one down. */
+export const DEFAULT_DEMOTE_AFTER = 3;
+
+/**
+ * How long to sit on a lower rung before probing the one above (ms). Applies to
+ * both LONGPOLL→STREAM and CADENCE→STREAM: a transient hq deploy must not
+ * permanently strand the agent on the slow lane.
+ */
+export const DEFAULT_PROMOTE_AFTER_MS = 5 * 60_000;
+
+/**
+ * Wake debounce (ms). A 40-message burst in a busy channel is ONE thing to go
+ * look at, not 40. Leading-edge fire (first event wakes instantly — that is the
+ * product promise) + trailing-edge fire (anything that arrived during the window
+ * still gets a wake, so the tail of a burst is never stranded until the 45s
+ * cadence).
+ */
+export const DEFAULT_WAKE_COALESCE_MS = 1_500;
+
+/** Cursor + status files, relative to the agent root. */
+export const CURSOR_RELATIVE = "state/org/push-cursor.json";
+export const STATUS_RELATIVE = "state/org/push-status.json";
+
+/**
+ * family → wake target. The target NAMES a fetch path; it does not perform one.
+ * Handlers live in `wake` (see DEFAULT_WAKE_HANDLERS) so an agent repo can add,
+ * replace, or disable any of them without touching this module.
+ */
+export const FAMILY_WAKE_TARGET = Object.freeze({
+  messaging: "org-messaging",
+  calling: "org-messaging",
+  email: "orgmail",
+  board: "board",
+  work: "board",
+  branding: "brand",
+});
+
+/**
+ * Cadence a target's DEFAULT handler ticks. Only `org-messaging` is enabled by
+ * default, deliberately:
+ *
+ *   - `messaging-inbound` is GUARDED and routes inline — it pulls directed items
+ *     and writes inbox files. No LLM session is spawned by the tick itself, so a
+ *     chatty channel costs I/O, not money.
+ *   - `backlog-executor` / `brand-steward` ESCALATE (they spawn a session when
+ *     they find work). Waking those on every board or branding event would let a
+ *     third party drive this agent's spend. Opt in explicitly if you want it:
+ *       wake: { board: () => enqueueTick({ cadence: "backlog-executor", ... }) }
+ *   - `orgmail` has no cadence at all — its fetcher is the channel adapter's own
+ *     poll loop, which the daemon owns. The wiring can pass a handler that pokes
+ *     that adapter; absent one, email degrades to the adapter's 45s poll, which
+ *     is exactly today's behaviour.
+ */
+export const TARGET_CADENCE = Object.freeze({
+  "org-messaging": "messaging-inbound",
+});
+
+// ---------------------------------------------------------------------------
+// Logging — never throws, always loud enough to be found
+// ---------------------------------------------------------------------------
+
+function logInfo(msg) { try { console.log(`[org-push] ${msg}`); } catch { /* never throw from logging */ } }
+function logWarn(msg) { try { console.warn(`[org-push] ${msg}`); } catch { /* never throw from logging */ } }
+
+// ---------------------------------------------------------------------------
+// Cursor persistence — the one piece of durable state
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the persisted ledger cursor. Returns `null` when we have never run (or
+ * the file is unreadable/corrupt).
+ *
+ * `null` is MEANINGFULLY DIFFERENT FROM 0 and the distinction is load-bearing:
+ * hq treats an ABSENT cursor as "bootstrap at head, replay nothing", and treats
+ * `cursor=0` as "replay the entire org ledger from the beginning". A fresh agent
+ * that sent 0 would wake on every event in the workspace's history. So: no file →
+ * send no cursor at all. Anything older than boot is the cadences' problem, and
+ * they have their own cursors for it.
+ *
+ * @param {string} agentRoot
+ * @returns {number|null}
+ */
+export function readCursor(agentRoot) {
+  try {
+    const p = join(agentRoot, CURSOR_RELATIVE);
+    if (!existsSync(p)) return null;
+    const raw = JSON.parse(readFileSync(p, "utf8"));
+    const n = Number(raw && raw.cursor);
+    // A non-positive / non-finite cursor is corrupt, not "start from zero" —
+    // treat it as absent (bootstrap at head) rather than replaying all history.
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+  } catch {
+    return null; // fail-open: a corrupt cursor bootstraps at head
+  }
+}
+
+/**
+ * Persist the ledger cursor (tmp + rename, so a crash mid-write can never leave a
+ * truncated file that reads as "bootstrap"). Fail-open; never throws.
+ * @param {string} agentRoot
+ * @param {number} cursor
+ * @param {Function} [now]
+ */
+export function writeCursor(agentRoot, cursor, now = Date.now) {
+  const n = Number(cursor);
+  if (!Number.isFinite(n) || n <= 0) return;
+  try {
+    const p = join(agentRoot, CURSOR_RELATIVE);
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify({ cursor: Math.floor(n), updatedAt: new Date(now()).toISOString() }, null, 2)}\n`);
+    renameSync(tmp, p);
+  } catch { /* fail-open */ }
+}
+
+/**
+ * Publish the channel's current rung to disk so `doctor`/an operator can see
+ * WHICH lane an agent is on without reading logs. A push channel that quietly
+ * degraded to the 45s cadence and told nobody is the silent failure this whole
+ * codebase is allergic to. Fail-open.
+ */
+function writeStatus(ctx, extra = {}) {
+  try {
+    const p = join(ctx.agentRoot, STATUS_RELATIVE);
+    mkdirSync(dirname(p), { recursive: true });
+    const body = {
+      rung: ctx.rung,
+      since: new Date(ctx.rungSinceMs).toISOString(),
+      cursor: ctx.cursor,
+      reason: ctx.rungReason || null,
+      cadenceFallbackActive: true, // ALWAYS true — the cadences never stop.
+      updatedAt: new Date(ctx.now()).toISOString(),
+      ...extra,
+    };
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(body, null, 2)}\n`);
+    renameSync(tmp, p);
+  } catch { /* fail-open */ }
+}
+
+// ---------------------------------------------------------------------------
+// Frame decoding — tolerant on purpose
+// ---------------------------------------------------------------------------
+
+/**
+ * Decode one wire line into a typed outcome. Understands SSE framing and bare
+ * NDJSON, because hq's house streaming format is NDJSON while the requested rung
+ * is "SSE" — accepting both costs ~10 lines and removes a deployment coin-flip.
+ *
+ * Never throws. An unparseable or unrecognised line is `{kind:"malformed"}` /
+ * `{kind:"ignore"}`, and the caller keeps reading the stream: one bad byte must
+ * not cost us the connection, let alone the daemon.
+ *
+ * @param {string} line
+ * @returns {{kind:"event"|"heartbeat"|"ready"|"ignore"|"malformed", event?:object, cursor?:number}}
+ */
+export function decodeFrameLine(line) {
+  const s = typeof line === "string" ? line.trim() : "";
+  if (!s) return { kind: "ignore" };
+  // SSE comment — the canonical keepalive. Counts as liveness, carries nothing.
+  if (s.startsWith(":")) return { kind: "heartbeat" };
+
+  let json = s;
+  if (s.startsWith("data:")) {
+    json = s.slice(5).trim();
+    if (!json) return { kind: "ignore" };
+  } else if (/^(event|id|retry):/i.test(s)) {
+    // Other SSE field lines. We key off the ledger seq inside `data:`, never off
+    // SSE's own `id:`/`event:` fields, so these are pure noise to us.
+    return { kind: "ignore" };
+  } else if (!(s.startsWith("{") || s.startsWith("["))) {
+    // Not JSON and not an SSE field we know → ignore rather than cry malformed
+    // (proxies and frameworks inject blank/padding lines).
+    return { kind: "ignore" };
+  }
+
+  let obj;
+  try { obj = JSON.parse(json); } catch { return { kind: "malformed" }; }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return { kind: "malformed" };
+
+  const type = typeof obj.type === "string" ? obj.type : "";
+  if (type === "heartbeat" || type === "ping" || type === "keepalive") return { kind: "heartbeat" };
+  if (type === "ready" || type === "hello") {
+    const c = Number(obj.cursor);
+    return { kind: "ready", cursor: Number.isFinite(c) ? c : undefined };
+  }
+  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`.
+  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 };
+  }
+  return { kind: "ignore" }; // forward-compatible: unknown frame types are fine
+}
+
+// ---------------------------------------------------------------------------
+// Relevance — a coarse filter, never a verdict
+// ---------------------------------------------------------------------------
+
+/**
+ * Should this event wake anything, and which target? Returns null to skip.
+ *
+ * This is DELIBERATELY coarse. The frame cannot prove an event is ours (see the
+ * module header), so the only safe direction is to wake and let the authoritative
+ * fetch decide. The single exception hq gives us is `email.received`, whose
+ * payload really does name the owning seat (`memberId`) — and even there we only
+ * skip when the caller supplied ids to compare against AND the payload names a
+ * different one. When we cannot prove it isn't ours, we wake.
+ *
+ * @param {object} ctx
+ * @param {object} ev
+ * @returns {string|null} wake target name, or null
+ */
+function wakeTargetFor(ctx, ev) {
+  const family = typeof ev.family === "string" ? ev.family : "";
+  const target = FAMILY_WAKE_TARGET[family];
+  if (!target) 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.
+  if (ctx.selfIds.size > 0 && ev.actor && ctx.selfIds.has(String(ev.actor))) return null;
+
+  // The one payload that names a seat. Skip only on a POSITIVE mismatch.
+  const memberId = ev.payload && ev.payload.memberId;
+  if (ctx.selfIds.size > 0 && memberId && !ctx.selfIds.has(String(memberId))) return null;
+
+  return target;
+}
+
+// ---------------------------------------------------------------------------
+// Wake dispatch — leading + trailing debounce
+// ---------------------------------------------------------------------------
+
+/**
+ * Default handler for the `org-messaging` target: enqueue a high-priority
+ * `messaging-inbound` tick. The cadence consumer drains the bus every ~2s and
+ * `guardMessagingInbound` then does the real, authoritative pull from ITS own
+ * cursor — so this is a nudge onto an existing, already-correct path, not a
+ * second ingestion route.
+ */
+async function defaultCadenceWake(ctx, target, meta) {
+  const cadence = TARGET_CADENCE[target];
+  if (!cadence) {
+    // No default fetcher for this target (e.g. orgmail, whose fetcher is the
+    // channel adapter the daemon owns). Degrading to that adapter's own poll is
+    // correct — it is today's behaviour — but say so once, loudly enough to find.
+    if (!ctx.warnedTargets.has(target)) {
+      ctx.warnedTargets.add(target);
+      logInfo(`no wake handler for target "${target}" — that lane keeps its own poll cadence (no regression, just no speed-up)`);
+    }
+    return false;
+  }
+  const enqueue = ctx.enqueueTick || (await import("../cadence-bus.mjs")).enqueueTick;
+  enqueue({
+    cadence,
+    type: "cadence_tick",
+    source: "org-push",
+    priority: "high",
+    agentRoot: ctx.agentRoot,
+    metadata: { pushSeq: meta.seq, family: meta.family, kind: meta.kind, rung: ctx.rung },
+  });
+  return true;
+}
+
+/**
+ * Fire a wake for `target`, debounced. Leading edge fires immediately (the whole
+ * point is speed); anything arriving inside the window sets a trailing wake so
+ * the tail of a burst is never stranded waiting for the 45s cadence.
+ *
+ * Fully fail-open: a throwing handler is logged and swallowed. A wake that fails
+ * costs latency, never correctness — the cadence still runs.
+ */
+function scheduleWake(ctx, target, meta) {
+  const nowMs = ctx.now();
+  const state = ctx.wakeState.get(target) || { cooldownUntil: 0, trailing: null, timer: null };
+  ctx.wakeState.set(target, state);
+
+  const fire = (m) => {
+    state.cooldownUntil = ctx.now() + ctx.wakeCoalesceMs;
+    Promise.resolve()
+      .then(() => {
+        const handler = ctx.wake[target];
+        if (handler === null || handler === false) return false; // explicitly disabled
+        if (typeof handler === "function") return handler(m, ctx);
+        return defaultCadenceWake(ctx, target, m);
+      })
+      .catch((err) => logWarn(`wake handler "${target}" failed (${err && err.message}) — the ${ctx.cadenceNote} still covers this`));
+  };
+
+  if (nowMs >= state.cooldownUntil) { fire(meta); return; }
+
+  // Inside the debounce window → remember the newest event and make sure exactly
+  // one trailing wake is scheduled for when the window closes.
+  state.trailing = meta;
+  if (state.timer == null) {
+    const delay = Math.max(1, state.cooldownUntil - nowMs);
+    state.timer = ctx.setTimeoutFn(() => {
+      state.timer = null;
+      const m = state.trailing;
+      state.trailing = null;
+      if (m && !ctx.stopped) fire(m);
+    }, delay);
+    if (state.timer && typeof state.timer.unref === "function") { try { state.timer.unref(); } catch { /* */ } }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Event dispatch — the watermark
+// ---------------------------------------------------------------------------
+
+/**
+ * Consume one event frame: dedup against the watermark, wake the right target,
+ * then advance + persist the cursor.
+ *
+ * ORDERING (copied from hq's own connection-manager, which solved this): the
+ * watermark is exclusive-lower-bound, so a frame at or below the cursor is a
+ * duplicate and is dropped. Duplicates genuinely happen — a long-poll response
+ * and a re-established stream overlap by design, and overlapping is much safer
+ * than gapping.
+ *
+ * The cursor advances even for events we ignored (wrong family, someone else's
+ * mailbox): they ARE consumed, and not advancing would re-deliver them forever.
+ *
+ * The cursor also advances when the wake handler fails. That is a deliberate
+ * trade: this channel carries HINTS, and the authoritative fetch behind the 45s
+ * cadence will find the work regardless. Refusing to advance would rebuild the
+ * whole poison-message problem on a lane that has a backstop by construction.
+ *
+ * @returns {"delivered"|"skipped"|"duplicate"|"malformed"}
+ */
+function dispatchEvent(ctx, ev) {
+  const seq = Number(ev && ev.seq);
+  if (!Number.isFinite(seq) || seq <= 0) { ctx.stats.malformed += 1; return "malformed"; }
+  if (ctx.cursor != null && seq <= ctx.cursor) { ctx.stats.duplicate += 1; return "duplicate"; }
+
+  let outcome = "skipped";
+  try {
+    const target = wakeTargetFor(ctx, ev);
+    if (target) {
+      scheduleWake(ctx, target, { seq, family: ev.family, kind: ev.kind, entityId: ev.entityId, at: ev.at });
+      ctx.stats.woke += 1;
+      outcome = "delivered";
+    }
+    if (typeof ctx.onEvent === "function") {
+      // Observer seam — additive, never load-bearing, independently fail-open.
+      try { ctx.onEvent({ ...ev, seq, rung: ctx.rung }); } catch (err) { logWarn(`onEvent observer threw (${err && err.message})`); }
+    }
+  } catch (err) {
+    logWarn(`event dispatch failed at seq ${seq} (${err && err.message}) — advancing anyway; the ${ctx.cadenceNote} covers it`);
+  }
+
+  ctx.cursor = seq;
+  ctx.stats.lastSeqAt = ctx.now();
+  writeCursor(ctx.agentRoot, seq, ctx.now);
+  return outcome;
+}
+
+// ---------------------------------------------------------------------------
+// URLs + headers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `/v1` URL. Mirrors lib/org/client.mjs's private `v1Url` — that helper
+ * is module-private and client.mjs is owned elsewhere, so we re-derive the same
+ * two rules here rather than reach into it: an already-`/v1`-suffixed base is
+ * used verbatim, anything else gets `/api/v1/`.
+ */
+function v1Url(base, path) {
+  const b = String(base || "").replace(/\/+$/, "");
+  if (/\/(?:api\/)?v1$/.test(b)) return `${b}/${path}`;
+  return `${b}/api/v1/${path}`;
+}
+
+/** Auth headers for a GET on the /v1 binding. Same shape client.mjs sends. */
+function streamHeaders(ctx) {
+  const h = {
+    accept: "text/event-stream, application/x-ndjson;q=0.9, application/json;q=0.8",
+    "x-org-protocol": String(PROTOCOL_VERSION),
+    // Best-effort hint to proxies that buffer: we want bytes forwarded as they
+    // arrive. Harmless where unsupported.
+    "cache-control": "no-cache",
+  };
+  if (ctx.token) h.authorization = `Bearer ${ctx.token}`;
+  if (ctx.orgId) h["x-org-id"] = String(ctx.orgId);
+  return h;
+}
+
+/** `?cursor=` only when we HAVE one — see readCursor for why 0 is not a cursor. */
+function cursorQuery(ctx) {
+  return ctx.cursor != null ? `?cursor=${encodeURIComponent(ctx.cursor)}` : "";
+}
+
+// ---------------------------------------------------------------------------
+// Rung 1 — the held stream
+// ---------------------------------------------------------------------------
+
+/**
+ * Iterate a fetch response body as chunks, tolerating both shapes Node gives us:
+ * an async-iterable (undici's default) and a WHATWG reader. Tests inject plain
+ * async generators, which hit the first branch.
+ */
+async function* iterateBody(body) {
+  if (!body) return;
+  if (typeof body[Symbol.asyncIterator] === "function") {
+    for await (const chunk of body) yield chunk;
+    return;
+  }
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) return;
+        if (value) yield value;
+      }
+    } finally {
+      try { reader.releaseLock(); } catch { /* fail-open */ }
+    }
+  }
+}
+
+/** HTTP statuses that mean "this hq does not have this endpoint". */
+function isUnsupportedStatus(status) {
+  return status === 404 || status === 405 || status === 501;
+}
+
+/**
+ * Open the stream and consume it until it ends, errors, goes idle, or hits the
+ * max hold. Returns a typed outcome; NEVER throws.
+ *
+ * @returns {Promise<{ok:boolean, unsupported?:boolean, reason:string, delivered:number, lived:number}>}
+ */
+async function consumeStream(ctx) {
+  const startedAt = ctx.now();
+  const f = ctx.fetchImpl || globalThis.fetch;
+  if (typeof f !== "function") return { ok: false, unsupported: true, reason: "no fetch implementation", delivered: 0, lived: 0 };
+
+  const url = v1Url(ctx.base, `${ctx.streamPath}${cursorQuery(ctx)}`);
+  const ac = typeof AbortController === "function" ? new AbortController() : null;
+  ctx.abort = ac;
+
+  // Two watchdogs on one abort: idle (no bytes at all) and max-hold (recycle).
+  let idleTimer = null;
+  const armIdle = () => {
+    if (idleTimer != null) { try { ctx.clearTimeoutFn(idleTimer); } catch { /* */ } }
+    idleTimer = ctx.setTimeoutFn(() => {
+      ctx.streamAbortReason = "idle";
+      try { ac && ac.abort(); } catch { /* */ }
+    }, ctx.idleMs);
+    if (idleTimer && typeof idleTimer.unref === "function") { try { idleTimer.unref(); } catch { /* */ } }
+  };
+  const maxTimer = ctx.setTimeoutFn(() => {
+    ctx.streamAbortReason = "max-hold";
+    try { ac && ac.abort(); } catch { /* */ }
+  }, ctx.streamMaxMs);
+  if (maxTimer && typeof maxTimer.unref === "function") { try { maxTimer.unref(); } catch { /* */ } }
+  const disarm = () => {
+    if (idleTimer != null) { try { ctx.clearTimeoutFn(idleTimer); } catch { /* */ } idleTimer = null; }
+    try { ctx.clearTimeoutFn(maxTimer); } catch { /* */ }
+  };
+
+  ctx.streamAbortReason = null;
+  let delivered = 0;
+  try {
+    armIdle();
+    let res;
+    try {
+      res = await f(url, { method: "GET", headers: streamHeaders(ctx), signal: ac ? ac.signal : undefined });
+    } catch (err) {
+      return { ok: false, reason: `connect failed: ${err && err.message}`, delivered, lived: ctx.now() - startedAt };
+    }
+    const status = Number(res && res.status) || 0;
+    if (isUnsupportedStatus(status)) {
+      return { ok: false, unsupported: true, reason: `http ${status} (endpoint absent)`, delivered, lived: ctx.now() - startedAt };
+    }
+    if (status !== 200) {
+      // 401/403 is a credential problem, not a transport one — say so plainly;
+      // it is the exact failure that made mesh beats look healthy for hours.
+      const hint = status === 401 || status === 403 ? " — check COHORT_API_KEY is present and paired" : "";
+      return { ok: false, reason: `http ${status}${hint}`, delivered, lived: ctx.now() - startedAt };
+    }
+    if (!res.body) {
+      return { ok: false, unsupported: true, reason: "no response body (not a stream)", delivered, lived: ctx.now() - startedAt };
+    }
+
+    const decoder = new TextDecoder();
+    let buf = "";
+    for await (const chunk of iterateBody(res.body)) {
+      if (ctx.stopped) break;
+      armIdle(); // ANY byte, including a heartbeat comment, proves liveness
+      buf += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+      let nl;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        const frame = decodeFrameLine(line);
+        if (frame.kind === "event") {
+          if (dispatchEvent(ctx, frame.event) === "delivered") delivered += 1;
+        } else if (frame.kind === "malformed") {
+          // ONE bad frame must not cost the connection: count it, keep reading.
+          ctx.stats.malformed += 1;
+          if (ctx.stats.malformed <= 5) logWarn(`ignoring malformed stream frame (total ${ctx.stats.malformed})`);
+        }
+        // heartbeat / ready / ignore: liveness already recorded above.
+      }
+      if (buf.length > 1_000_000) buf = ""; // a frame this large is a bug, not a frame
+    }
+    const reason = ctx.streamAbortReason || (ctx.stopped ? "stopped" : "eof");
+    // An idle abort is a FAILED stream (the server went quiet on us); a clean EOF
+    // or a scheduled recycle is a healthy end — reconnect immediately.
+    const ok = reason !== "idle";
+    return { ok, reason, delivered, lived: ctx.now() - startedAt };
+  } catch (err) {
+    // An abort surfaces HERE, as a throw out of the body iterator — which means
+    // this catch has to tell a deliberate teardown apart from a real failure.
+    // A scheduled recycle (`max-hold`) and our own `stop()` are successes: the
+    // connection did its job and we ended it on purpose, so they must not spend
+    // the rung's failure budget and must not trigger a demotion. Only an idle
+    // timeout or a genuine transport error counts against us.
+    const reason = ctx.streamAbortReason || (ctx.stopped ? "stopped" : `read failed: ${err && err.message}`);
+    const ok = reason === "max-hold" || reason === "stopped";
+    return { ok, reason, delivered, lived: ctx.now() - startedAt };
+  } finally {
+    disarm();
+    ctx.abort = null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rung 2 — the bounded long-poll
+// ---------------------------------------------------------------------------
+
+/**
+ * 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
+ * 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)}`;
+  let r;
+  try {
+    r = await ctx.client.read(path, {
+      base: ctx.base,
+      token: ctx.token,
+      orgId: ctx.orgId,
+      fetchImpl: ctx.fetchImpl,
+      timeoutMs: ctx.waitMs + 5_000,
+    });
+  } catch (err) {
+    // client.read 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) {
+    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";
+    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 : [];
+  let delivered = 0;
+  for (const ev of events) {
+    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);
+  }
+  return {
+    ok: true,
+    reason: events.length ? `${events.length} event(s)` : "timeout (no events)",
+    delivered,
+    events: events.length,
+    lived: ctx.now() - startedAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The ladder
+// ---------------------------------------------------------------------------
+
+/**
+ * Move to a rung and say so. Every transition is logged AND written to
+ * state/org/push-status.json — the channel is never allowed to change lanes in
+ * silence.
+ */
+function setRung(ctx, rung, reason) {
+  if (ctx.rung === rung) return;
+  const from = ctx.rung;
+  ctx.rung = rung;
+  ctx.rungSinceMs = ctx.now();
+  ctx.rungReason = reason;
+  ctx.failures = 0;
+  ctx.backoffMs = 0;
+  const line = `ladder ${from} → ${rung} (${reason})`;
+  if (rung === PUSH_RUNG.CADENCE) {
+    logWarn(`${line} — push is OFF; the agent falls back to the ${ctx.cadenceNote}, i.e. today's behaviour. Will re-probe in ${Math.round(ctx.promoteAfterMs / 1000)}s.`);
+  } else if (rung === PUSH_RUNG.LONGPOLL) {
+    logWarn(`${line} — degraded but still push: bounded ${Math.round(ctx.waitMs / 1000)}s waits.`);
+  } else {
+    logInfo(line);
+  }
+  writeStatus(ctx);
+}
+
+/** Demote one rung. STREAM → LONGPOLL → CADENCE; CADENCE is the floor. */
+function demote(ctx, reason) {
+  if (ctx.rung === PUSH_RUNG.STREAM) return setRung(ctx, PUSH_RUNG.LONGPOLL, reason);
+  if (ctx.rung === PUSH_RUNG.LONGPOLL) return setRung(ctx, PUSH_RUNG.CADENCE, reason);
+  // Already on the floor: refresh the dwell clock so we don't probe in a tight
+  // loop against an hq that is plainly down.
+  ctx.rungSinceMs = ctx.now();
+  ctx.rungReason = reason;
+  writeStatus(ctx);
+}
+
+/**
+ * Run exactly ONE step of the ladder and return how long to wait before the next
+ * one. Exported through `_internals` so tests drive the state machine without
+ * real timers — the same discipline mesh.mjs uses with `beatOnce`.
+ *
+ * @returns {Promise<number>} delay in ms before the next step
+ */
+async function ladderStep(ctx) {
+  if (ctx.stopped) return 0;
+
+  // Promotion check first: any rung below STREAM is a temporary state, and a
+  // transient hq deploy must never strand an agent on the slow lane forever.
+  if (ctx.rung !== PUSH_RUNG.STREAM) {
+    const dwell = ctx.now() - ctx.rungSinceMs;
+    if (dwell >= ctx.promoteAfterMs) {
+      setRung(ctx, PUSH_RUNG.STREAM, "probing the preferred rung after a dwell period");
+    } else if (ctx.rung === PUSH_RUNG.CADENCE) {
+      // Nothing to do on the floor: the cadences are carrying the agent. Sleep
+      // out the remaining dwell rather than burning requests.
+      return Math.max(1_000, ctx.promoteAfterMs - dwell);
+    }
+  }
+
+  const rung = ctx.rung;
+  const res = rung === PUSH_RUNG.STREAM ? await consumeStream(ctx) : await waitOnce(ctx);
+  ctx.stats.attempts += 1;
+  if (ctx.stopped) return 0;
+
+  if (res.unsupported) {
+    // "This hq doesn't have that endpoint." Retrying is pointless and rude —
+    // demote immediately, no backoff spent, no failure budget consumed.
+    demote(ctx, `${rung} unsupported: ${res.reason}`);
+    return 0;
+  }
+
+  if (res.ok) {
+    ctx.failures = 0;
+    ctx.backoffMs = 0;
+    ctx.stats.ok += 1;
+    if (rung === PUSH_RUNG.STREAM) {
+      // A clean EOF/recycle is normal for a held stream: reconnect at once, with
+      // a small floor so a server that instantly closes cannot spin us hot.
+      const lived = Number(res.lived) || 0;
+      return lived < ctx.minHealthyMs ? ctx.baseBackoffMs : 0;
+    }
+    // Long-poll: immediately re-arm — the re-arm IS the mechanism. The one guard
+    // is against an `agent.wait` that answers instantly instead of holding (a
+    // half-implemented endpoint, or a proxy that terminates the hold): an empty
+    // answer that came back far faster than the hold we asked for would otherwise
+    // spin this loop at wire speed against hq. Floor it at the base backoff.
+    const livedWait = Number(res.lived) || 0;
+    if (!res.events && livedWait < ctx.minHealthyMs) return ctx.baseBackoffMs;
+    return 0;
+  }
+
+  ctx.failures += 1;
+  ctx.stats.failures += 1;
+  logWarn(`${rung} attempt failed (${res.reason}) [${ctx.failures}/${ctx.demoteAfter}] — the ${ctx.cadenceNote} is still covering this agent`);
+  if (ctx.failures >= ctx.demoteAfter) {
+    demote(ctx, `${ctx.demoteAfter} consecutive failures (last: ${res.reason})`);
+    return 0;
+  }
+  // Jittered decorrelated backoff — the same algorithm as lib/util/reconnect and
+  // lib/rate-guard, so the whole fleet backs off a struggling hq identically and
+  // never in lockstep.
+  ctx.backoffMs = decorrelatedBackoff(ctx.backoffMs, {
+    base: ctx.baseBackoffMs,
+    max: ctx.maxBackoffMs,
+    factor: ctx.backoffFactor,
+    rng: ctx.rng,
+  });
+  return ctx.backoffMs;
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Open the push channel. Returns a handle with `stop()`.
+ *
+ * A no-op (inert handle) when the org integration is disabled or the push channel
+ * is switched off, so the caller's shutdown path is always safe to call. NEVER
+ * throws: a push problem must not take the daemon down, and the 45s cadences keep
+ * running underneath regardless of what happens here.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot                the agent repo root
+ * @param {object} o.cfg                      org config (lib/org/client.loadOrgConfig)
+ * @param {object}   [o.client]               injected org client (defaults to lib/org/client)
+ * @param {Function} [o.fetchImpl]            injected fetch
+ * @param {Function} [o.now]                  injected clock () => ms
+ * @param {Function} [o.setTimeout]           injected timer
+ * @param {Function} [o.clearTimeout]         injected timer clearer
+ * @param {Function} [o.rng]                  injected uniform [0,1) for jitter
+ * @param {Function} [o.onEvent]              observer, called per accepted event
+ * @param {object}   [o.wake]                 target → handler (fn | null to disable)
+ * @param {Function} [o.enqueueTick]          injected cadence-bus enqueuer
+ * @param {string[]} [o.selfIds]              ids that mean "this seat" (actor/mailbox filter)
+ * @param {boolean}  [o.enabled]              force off (default: on when the org is enabled)
+ * @param {number}   [o.waitMs] [o.idleMs] [o.streamMaxMs] [o.demoteAfter]
+ * @param {number}   [o.promoteAfterMs] [o.wakeCoalesceMs]
+ * @param {number}   [o.baseBackoffMs] [o.maxBackoffMs] [o.backoffFactor]
+ * @param {string}   [o.startRung]            start on a specific rung (tests/ops)
+ * @returns {Promise<{stop:Function, isEnabled:boolean, rung:Function, _ctx?:object}>}
+ */
+export async function connectOrgPush(o = {}) {
+  const client = o.client || defaultClient;
+  const cfg = o.cfg || {};
+
+  // Same gate as the mesh: disabled org → inert handle, zero network.
+  let enabled = false;
+  try { enabled = !!client.isEnabled(cfg); } catch { enabled = false; }
+  // Explicit kill switch for operators who want the pure-cadence world back.
+  if (o.enabled === false || process.env.COHORT_PUSH_DISABLED === "1") enabled = false;
+  if (!enabled) {
+    return { stop() {}, isEnabled: false, rung: () => PUSH_RUNG.CADENCE };
+  }
+
+  const agentRoot = resolve(o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  let conn = {};
+  try { conn = client.configFromAgent(cfg) || {}; } catch { conn = {}; }
+
+  const num = (v, d) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : d);
+  // Some knobs are legitimately ZERO ("never coalesce", "trust any stream"), so
+  // they need a variant that treats 0 as a value rather than as "unset".
+  const num0 = (v, d) => (Number.isFinite(Number(v)) && Number(v) >= 0 ? Number(v) : d);
+
+  const ctx = {
+    agentRoot,
+    client,
+    fetchImpl: o.fetchImpl,
+    base: conn.base,
+    token: conn.token,
+    orgId: conn.orgId,
+
+    now: typeof o.now === "function" ? o.now : Date.now,
+    setTimeoutFn: typeof o.setTimeout === "function" ? o.setTimeout : setTimeout,
+    clearTimeoutFn: typeof o.clearTimeout === "function" ? o.clearTimeout : clearTimeout,
+    rng: typeof o.rng === "function" ? o.rng : undefined,
+
+    streamPath: o.streamPath || DEFAULT_STREAM_PATH,
+    waitPath: o.waitPath || DEFAULT_WAIT_PATH,
+    waitMs: Math.min(55_000, num(o.waitMs, DEFAULT_WAIT_MS)),
+    idleMs: num(o.idleMs, DEFAULT_IDLE_MS),
+    streamMaxMs: num(o.streamMaxMs, DEFAULT_STREAM_MAX_MS),
+    minHealthyMs: num0(o.minHealthyMs, 2_000),
+    demoteAfter: num(o.demoteAfter, DEFAULT_DEMOTE_AFTER),
+    promoteAfterMs: num(o.promoteAfterMs, DEFAULT_PROMOTE_AFTER_MS),
+    wakeCoalesceMs: num0(o.wakeCoalesceMs, DEFAULT_WAKE_COALESCE_MS),
+    baseBackoffMs: num(o.baseBackoffMs, 1_000),
+    maxBackoffMs: num(o.maxBackoffMs, 60_000),
+    backoffFactor: num(o.backoffFactor, 3),
+
+    onEvent: typeof o.onEvent === "function" ? o.onEvent : null,
+    wake: { ...(o.wake || {}) },
+    enqueueTick: typeof o.enqueueTick === "function" ? o.enqueueTick : null,
+    selfIds: new Set((Array.isArray(o.selfIds) ? o.selfIds : []).filter(Boolean).map(String)),
+
+    // The phrase we use everywhere we mention the backstop, so an operator reading
+    // logs always sees the same words for the same thing.
+    cadenceNote: "45s messaging-inbound cadence",
+
+    cursor: readCursor(agentRoot),
+    rung: PUSH_RUNG.STREAM,
+    rungSinceMs: 0,
+    rungReason: "boot",
+    failures: 0,
+    backoffMs: 0,
+    stopped: false,
+    timer: null,
+    abort: null,
+    streamAbortReason: null,
+    wakeState: new Map(),
+    warnedTargets: new Set(),
+    stats: { attempts: 0, ok: 0, failures: 0, malformed: 0, duplicate: 0, woke: 0, lastSeqAt: 0 },
+  };
+  ctx.rungSinceMs = ctx.now();
+  if (o.startRung && Object.values(PUSH_RUNG).includes(o.startRung)) ctx.rung = o.startRung;
+
+  const stop = function stop() {
+    if (ctx.stopped) return;
+    ctx.stopped = true;
+    if (ctx.timer != null) { try { ctx.clearTimeoutFn(ctx.timer); } catch { /* */ } ctx.timer = null; }
+    for (const state of ctx.wakeState.values()) {
+      if (state.timer != null) { try { ctx.clearTimeoutFn(state.timer); } catch { /* */ } state.timer = null; }
+    }
+    try { ctx.abort && ctx.abort.abort(); } catch { /* */ }
+    writeStatus(ctx, { stopped: true });
+  };
+  ctx.stop = stop;
+
+  // The run loop: one ladder step, then sleep for whatever the step asked for.
+  // Recursive scheduling (not setInterval) because each rung has its own natural
+  // rhythm and a step must never overlap itself.
+  const pump = async () => {
+    if (ctx.stopped) return;
+    let delay = ctx.baseBackoffMs;
+    try {
+      delay = await ladderStep(ctx);
+    } catch (err) {
+      // Belt and braces: ladderStep is already fail-open, but this loop is the
+      // last thing standing between a push bug and a dead daemon.
+      logWarn(`ladder step threw (${err && err.message}) — backing off; the ${ctx.cadenceNote} still covers this agent`);
+      delay = ctx.maxBackoffMs;
+    }
+    if (ctx.stopped) return;
+    ctx.timer = ctx.setTimeoutFn(() => { void pump(); }, Math.max(0, delay));
+    if (ctx.timer && typeof ctx.timer.unref === "function") { try { ctx.timer.unref(); } catch { /* */ } }
+  };
+
+  logInfo(
+    `push channel starting on rung "${ctx.rung}" (cursor ${ctx.cursor == null ? "head (bootstrap, no replay)" : ctx.cursor}) — ` +
+    `the ${ctx.cadenceNote} remains active as the safety net`,
+  );
+  writeStatus(ctx);
+  // The first step is SCHEDULED, never run inline: boot must not block on a
+  // round-trip, and it means an injected timer gives a test full control of the
+  // loop (the same discipline mesh.mjs uses for its beat interval).
+  ctx.timer = ctx.setTimeoutFn(() => { void pump(); }, 0);
+  if (ctx.timer && typeof ctx.timer.unref === "function") { try { ctx.timer.unref(); } catch { /* */ } }
+
+  return {
+    stop,
+    isEnabled: true,
+    rung: () => ctx.rung,
+    stats: () => ({ ...ctx.stats, rung: ctx.rung, cursor: ctx.cursor }),
+    _ctx: ctx,
+  };
+}
+
+export const _internals = {
+  ladderStep,
+  consumeStream,
+  waitOnce,
+  dispatchEvent,
+  scheduleWake,
+  wakeTargetFor,
+  setRung,
+  demote,
+  writeStatus,
+  v1Url,
+  iterateBody,
+};
+
+export default { connectOrgPush, PUSH_RUNG, readCursor, writeCursor, decodeFrameLine, _internals };