@ravefox/space 0.0.0-stage → 0.2.1

package/src/lib/enforcement.js

@@ -0,0 +1,946 @@
+/**
+ * Wrapper-side enforcement (ADR-018 D3, "our drivers" row).
+ *
+ * The 2026-08-11 pilot proved that advisory guidance loses to task gravity:
+ * the tone contract was in every seat's tool descriptions and the review
+ * median still came out at 3,614 characters, with zero claims taken and a
+ * mention cascade that needed a manual wrapper kill. This module is the
+ * deterministic half — the wrapper enforces what the contract can only ask:
+ *
+ *   - claim-before-act + stand-down (createClaimKeeper)
+ *   - per-seat cascade damping     (createCascadeGovernor, classifyTrigger)
+ *   - post-time length gate        (splitForChat, deliverChatReply)
+ *
+ * One rule overrides everything here: enforcement must never convert an
+ * infrastructure failure into agent silence (#887 class). Every network or
+ * server error fails OPEN — the turn proceeds unguarded and says so in the
+ * log. Only an explicit "someone else holds it" or "cascade cap reached"
+ * stands the agent down, and both are logged with the reason.
+ */
+
+import { isUnseenMessagesHold } from './pod-catch-up.js';
+
+// Event types whose payload.messageId identifies a claimable trigger message.
+// first_contact is deliberately absent: the welcome wake targets exactly one
+// agent, so there is nothing to contend for. Heartbeats have no message at
+// all, and agent.ask routes privately.
+export const CLAIMABLE_EVENT_TYPES = new Set([
+  'chat.mention',
+  'message.posted',
+  'dm.message',
+]);
+
+// A decision card is the durable path for a real human choice. This lives in
+// wrapper enforcement, rather than only in the MCP tool description, because
+// a task-shaped prompt can otherwise make an agent phrase the same fork as a
+// prose @ask. The rule is framing, not a classifier: the agent still judges
+// whether the work genuinely cannot continue without a human ruling.
+export const DECISION_FORK_FRAME = [
+  '[Decision forks]',
+  'If you are blocked on a genuine fork that needs a human choice, use your runtime\'s decision-card tool (MCP: commonly_request_decision); include that person\'s real @handle when a specific person should rule, and do not duplicate the card with a prose @ask.',
+  'Use it only when you cannot safely continue before a ruling. Give 2–4 concrete options and mark one recommendation.',
+  'Use ordinary pod messages for status, factual questions, and coordination that do not require a human choice.',
+].join('\n');
+
+export const frameDecisionForkRule = (prompt) => `${DECISION_FORK_FRAME}\n\n${prompt}`;
+
+// ── trigger classification ──────────────────────────────────────────────────
+
+/**
+ * Who authored the message that woke us — 'agent', 'human', or 'unknown'?
+ *
+ * Three signals, in order:
+ *   1. payload.dmKind — the kernel stamps DM wakes 'agent-agent'/'user-agent'.
+ *   2. The trigger message's isBot flag, looked up by payload.messageId in the
+ *      pre-spawn snapshot the run loop already fetches for echo suppression.
+ *   3. payload.senderIsHuman, for what no snapshot can name. A page holds more
+ *      wakes than the snapshot holds messages, so without this a full page of
+ *      agent wakes reads as all unknown and walks past the cascade cap. A post
+ *      comment isn't a pod message at all (F225).
+ *
+ * 'unknown' is the fail-open verdict: it neither counts toward the cascade
+ * cap nor resets it. It's what's left when the kernel couldn't say either: an
+ * older server, or a sender it couldn't read.
+ */
+export const classifyTrigger = (event, recentMessages) => {
+  const p = event?.payload || {};
+  // The third pricing branch (#1044, fable 55845). Kernel-found work is not
+  // agent churn and must not price as it: counted as 'agent' it eats cascade
+  // budget exactly when the board is busiest; counted as 'human' it CLEARS the
+  // brake on unrelated cascades. 'kernel' is neutral like 'unknown' — no
+  // count, no reset — but chosen on purpose rather than fallen into, and the
+  // refusal/boot logs can say so. Checked before dmKind: triggerAuthor is the
+  // honest field (#1018) and wins where both appear.
+  if (p.triggerAuthor === 'kernel') return 'kernel';
+  if (p.dmKind === 'agent-agent') return 'agent';
+  if (p.dmKind === 'user-agent') return 'human';
+  const trigger = p.messageId && Array.isArray(recentMessages)
+    ? recentMessages.find((m) => String(m._id || m.id) === String(p.messageId))
+    : undefined;
+  if (typeof trigger?.isBot === 'boolean') return trigger.isBot ? 'agent' : 'human';
+  if (typeof p.senderIsHuman === 'boolean') return p.senderIsHuman ? 'human' : 'agent';
+  return 'unknown';
+};
+
+// Direct-address event types: the seat was NAMED (explicit @, implicit human
+// reply, or DM routing). A lost claim on these does not silence the seat —
+// being chosen by a human outranks being beaten to a CAS. Broadcast wakes
+// (message.posted) are the opposite: nobody asked for THIS seat, so a lost
+// race is a free stand-down.
+export const ADDRESSED_EVENT_TYPES = new Set(['chat.mention', 'thread.mention', 'dm.message']);
+
+/**
+ * A person @-mentioned this seat in a pod (ADR-018 D9.2): the one wake that
+ * carries unread message bodies. `trigger` is classifyTrigger's verdict, so an
+ * agent's mention, a kernel wake and an author nobody can name are all
+ * out. A DM wake is not a mention, whichever type it rides, and neither is a
+ * broadcast. Nor are three `chat.mention` wakes where nobody typed the seat's
+ * name: a welcome, an adjacent reply and a reply to the seat's own message.
+ */
+export const isPersonMention = (event, trigger) => {
+  const payload = event?.payload || {};
+  return trigger === 'human' && event?.type === 'chat.mention' && !payload.dmKind
+    && !payload.welcomeWake && !payload.adjacentReply && !payload.implicitReply;
+};
+
+// These are the two event types the kernel's bot-to-bot mention dampener
+// bounds as one shared budget. Keep the wrapper out of that same loop's
+// admission path: named seats need to respond even when broadcasts have
+// exhausted their cascade budget. The backend cannot be a runtime import of
+// the published CLI, so cli/__tests__/mention-event-types.contract.test.mjs
+// imports both modules and pins the two lists together.
+//
+// Agent-DM wakes also arrive as chat.mention, but carry payload.dmKind. They
+// stay on this governor's bounded path: event type alone does not identify the
+// producer that owns the kernel mention budget. dm.message is legacy consumer
+// vocabulary and remains on that same ordinary addressed-grace path.
+export const MENTION_EVENT_TYPES = new Set(['chat.mention', 'thread.mention']);
+
+// ── cascade governor ────────────────────────────────────────────────────────
+
+export const CASCADE_DEFAULTS = Object.freeze({
+  cap: 3,
+  addressedGrace: 2,
+  resetMs: 10 * 60 * 1000,
+});
+
+// Env names, exported so the CLI help text and the tests quote the same
+// strings rather than two copies that can drift apart.
+export const CASCADE_ENV_VARS = Object.freeze({
+  cap: 'COMMONLY_CASCADE_CAP',
+  addressedGrace: 'COMMONLY_CASCADE_ADDRESSED_GRACE',
+  resetMs: 'COMMONLY_CASCADE_RESET_MS',
+});
+
+// Flag spelling per key, for warning messages. A derived string
+// (key.replace(...)) would silently produce a flag that does not exist the
+// first time a key is renamed; this fails at the same moment the flag does.
+const CASCADE_FLAGS = {
+  cap: '--cascade-cap',
+  addressedGrace: '--cascade-grace',
+  resetMs: '--cascade-reset',
+};
+
+const CASCADE_BOUNDS = {
+  // 0 is meaningful, not a mistake: it refuses every agent-triggered turn in
+  // the pod, which is the "this room is on fire, mute the cascades" setting.
+  cap: { min: 0, max: 1000, integer: true },
+  // 0 restores the pre-#973 behaviour exactly. That is the point of the knob —
+  // the grace can be taken back on one seat, in one restart, without a revert
+  // and without a source edit.
+  addressedGrace: { min: 0, max: 1000, integer: true },
+  resetMs: { min: 1000, max: 24 * 60 * 60 * 1000, integer: true },
+};
+
+/**
+ * Resolve the three governor constants from (in precedence order) an explicit
+ * override, an environment variable, then the shipped default.
+ *
+ * These were literals in `run()`'s signature, reachable only by editing source
+ * — on a fleet whose CLI is a symlink into a live worktree, so "retune the
+ * cap" meant an edit plus a restart of every seat, with nothing recording
+ * which value ran. The sibling dampener one service over
+ * (AGENT_ASK_RATE_LIMIT_PER_HOUR) has always been env-tunable; this is
+ * copying that, not inventing it.
+ *
+ * An unparseable or out-of-range value warns and falls back rather than
+ * throwing. A seat that crash-loops on a typo'd env var is a worse outcome
+ * than one running the default — but a silent fallback would hide the typo,
+ * so it is loud.
+ *
+ * Overrides are validated on the SAME path as env values, deliberately. An
+ * earlier draft trusted them and passed them straight through, which made
+ * `--cascade-cap abc` resolve to NaN — and `streak < NaN` is false for every
+ * streak, so a typo at the command line would have silently refused every
+ * agent-triggered turn the seat ever saw. The louder source is not the safer
+ * one; there is one validator because there is one way to be wrong.
+ */
+export const resolveCascadeSettings = ({
+  env = process.env,
+  overrides = {},
+  warn = (msg) => console.warn(msg),
+} = {}) => {
+  const resolved = {};
+  for (const key of Object.keys(CASCADE_DEFAULTS)) {
+    const bounds = CASCADE_BOUNDS[key];
+    const fallback = CASCADE_DEFAULTS[key];
+    const override = overrides[key];
+    const hasOverride = override !== undefined && override !== null;
+    const raw = hasOverride ? override : env?.[CASCADE_ENV_VARS[key]];
+    // Names the source in the warning, so "which one did I get wrong" is
+    // answered by the message rather than by bisecting the launch command.
+    const label = hasOverride ? CASCADE_FLAGS[key] : CASCADE_ENV_VARS[key];
+
+    if (raw === undefined || raw === null || String(raw).trim() === '') {
+      resolved[key] = fallback;
+      continue;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || (bounds.integer && !Number.isInteger(parsed))) {
+      warn(`${label}='${raw}' is not an integer — using ${fallback}`);
+      resolved[key] = fallback;
+      continue;
+    }
+    if (parsed < bounds.min || parsed > bounds.max) {
+      warn(`${label}=${parsed} is outside [${bounds.min}, ${bounds.max}] — using ${fallback}`);
+      resolved[key] = fallback;
+      continue;
+    }
+    resolved[key] = parsed;
+  }
+  return resolved;
+};
+
+/**
+ * Per-pod damping of agent→agent retrigger chains.
+ *
+ * The pilot's failure shape: an agent's own posts kept waking it (via another
+ * agent's replies) until the operator killed the wrapper at round 3. The
+ * governor counts CONSECUTIVE agent-triggered turns per pod; at `cap` it
+ * refuses further agent-triggered turns until a human-triggered turn resets
+ * the streak, or `resetMs` passes with no ADMITTED agent-triggered turn from
+ * this seat in this pod (so a damped seat recovers on its own — a legitimate
+ * a2a handoff an hour later must not inherit a stale cap).
+ *
+ * NOTE on `resetMs`: it is a silence window, but the silence is far narrower
+ * than "the pod is quiet", and it is measured on two axes people get wrong in
+ * opposite directions:
+ *
+ *   WHOSE turns  — `pods` is a Map in this closure, inside ONE wrapper
+ *                  process. It never observes another seat's turns at all.
+ *                  Three chatty peers cannot keep this streak alive.
+ *   WHICH turns  — only turns that reached `record()`. A refusal returns from
+ *                  agent.js before it (`:859` vs `:1087`), so a capped seat
+ *                  stops updating `lastAgentTurnAt` entirely and its clock
+ *                  runs free from the last turn it was ALLOWED.
+ *
+ * Net shape is a token bucket, not a static ceiling: a burst of `cap`, then
+ * `cap` admits per `resetMs`, per pod. Sustained agent traffic with zero human
+ * turns yields 6/9/12/15/18/18/18/18 admits per hour as arrivals go from one
+ * per 600s to one per second — inert when quiet, pinned at cap-per-window
+ * however hard the burst gets. Per POD: a seat in N pods holds N buckets, so
+ * its seat-level ceiling is N times that.
+ *
+ * An earlier version of this note said the window requires zero agent turns
+ * "in the pod", and concluded that in a busy room the only live release is a
+ * human turn. Both halves are wrong, and wrongly reassuring: a capped seat
+ * self-releases every window no matter how loud the room is.
+ *
+ * Split into admit/record so a spawn that fails (and will be redelivered)
+ * never double-counts: admit() only reads, record() runs after a turn
+ * actually completed. Human-triggered turns are always admitted.
+ */
+export const createCascadeGovernor = ({
+  cap = CASCADE_DEFAULTS.cap,
+  addressedGrace = CASCADE_DEFAULTS.addressedGrace,
+  resetMs = CASCADE_DEFAULTS.resetMs,
+  now = Date.now,
+} = {}) => {
+  const pods = new Map(); // podId -> { streak, lastAgentTurnAt }
+
+  const stateFor = (podId) => {
+    const s = pods.get(podId) || { streak: 0, lastAgentTurnAt: 0 };
+    if (s.streak > 0 && now() - s.lastAgentTurnAt > resetMs) {
+      return { streak: 0, lastAgentTurnAt: 0 };
+    }
+    return s;
+  };
+
+  return {
+    admit(podId, trigger, eventType, payload = {}) {
+      if (trigger !== 'agent') return { allowed: true, streak: 0, addressed: false };
+      const s = stateFor(podId);
+      const addressed = ADDRESSED_EVENT_TYPES.has(eventType);
+      if (MENTION_EVENT_TYPES.has(eventType) && !payload?.dmKind) {
+        // Named mentions are bounded upstream by the kernel's shared
+        // bot-to-bot mention dampener. A DM emits chat.mention too, but its
+        // dmKind identifies a different producer, so it remains locally
+        // bounded. Every admitted turn still reaches record() after it
+        // completes, consuming broadcast liveness rather than creating an
+        // unmetered second loop.
+        return {
+          allowed: true,
+          streak: s.streak,
+          addressed,
+          graceApplied: false,
+        };
+      }
+      // Being NAMED outranks a mechanical brake — the same judgement the claim
+      // path already makes forty lines down in agent.js. Without this, a peer
+      // can @mention a capped seat and get silence, with no signal to either
+      // side that anything was suppressed. Observed 2026-08-18: one seat took
+      // 51 wakes and 28 consecutive cap refusals, five of them chat.mention,
+      // and answered none of them.
+      //
+      // Legacy direct-address events retain a GRACE, not an exemption. They
+      // still count toward the streak, so they terminate at cap +
+      // addressedGrace instead of never.
+      const limit = addressed ? cap + addressedGrace : cap;
+      // `addressed` describes the EVENT; `graceApplied` describes what this
+      // governor actually did with it. They diverge whenever addressedGrace is
+      // 0 — the pre-#973 setting, and the first thing an operator dials back —
+      // where an addressed event is refused at the plain cap having been given
+      // nothing extra. Reporting only `addressed` made the refusal log claim a
+      // grace was "also spent" on a seat whose own boot line says grace=0.
+      return {
+        allowed: s.streak < limit,
+        streak: s.streak,
+        addressed,
+        graceApplied: addressed && addressedGrace > 0,
+      };
+    },
+    record(podId, trigger) {
+      if (trigger === 'human') {
+        pods.set(podId, { streak: 0, lastAgentTurnAt: 0 });
+      } else if (trigger === 'agent') {
+        const s = stateFor(podId);
+        pods.set(podId, { streak: s.streak + 1, lastAgentTurnAt: now() });
+      }
+      // 'unknown' is neutral by FALLBACK; 'kernel' is neutral by DESIGN —
+      // both take this path, but only one of them is an accident.
+    },
+  };
+};
+
+// ── claim fairness ──────────────────────────────────────────────────────────
+
+
+// Frame prepended when an ADDRESSED seat lost the claim race: it still gets
+// its turn, but knows a peer is (probably) already answering — the bar for
+// posting rises from "have something to say" to "have something DIFFERENT".
+export const peerHoldsFrame = (holder, messageId) => (
+  `[Claim notice: @${holder} holds message ${messageId} and is likely responding. `
+  + 'You were directly addressed, so you still get this turn — but add your view ONLY '
+  + 'if it is materially different from what they would cover; otherwise return NO_REPLY.]'
+);
+
+/**
+ * Win-weighted claim delay — the "cooldown" that keeps one fast seat from
+ * monopolising a pod's broadcast wakes without ever risking that NOBODY
+ * claims. A seat that won its previous broadcast race in a pod waits a small
+ * jittered delay before entering the next one; everyone still claims, recent
+ * winners just start from the back. A loss (or `windowMs` of quiet) clears
+ * the handicap — you are only the monopolist while you are actually winning.
+ *
+ * Deliberately NOT a hard cooldown: with all seats abstaining, a message
+ * goes unhandled — the #887 shape again, self-inflicted.
+ */
+export const createClaimHandicap = ({
+  delayMs = 3000,
+  jitterMs = 1000,
+  windowMs = 5 * 60 * 1000,
+  now = Date.now,
+  random = Math.random,
+} = {}) => {
+  const wins = new Map(); // podId -> lastBroadcastWinAt
+
+  return {
+    recordWin(podId) {
+      wins.set(podId, now());
+    },
+    recordLoss(podId) {
+      wins.delete(podId);
+    },
+    yieldDelayMs(podId) {
+      const at = wins.get(podId);
+      // Explicit undefined check: a win recorded at clock 0 is still a win
+      // (a falsy-timestamp `!at` here silently disabled the handicap for the
+      // first test clock tick — caught by the unit suite).
+      if (at === undefined || now() - at > windowMs) return 0;
+      return delayMs + Math.floor(random() * jitterMs);
+    },
+  };
+};
+
+// ── claim keeper ────────────────────────────────────────────────────────────
+
+/**
+ * One claim lifecycle for one event: acquire → renew while the CLI turn runs
+ * → release (or discover mid-turn loss and stand down at post time).
+ *
+ * Acquire outcomes:
+ *   { claimed: true }                  — we hold the lease; start renewal.
+ *   { claimed: false, holder }         — someone else holds it; STAND DOWN.
+ *   { claimed: false, failOpen: true } — claim route unavailable (older
+ *     server, network, 403 on a stale install); proceed UNGUARDED. The
+ *     alternative turns a kernel deploy gap into a silent agent.
+ *
+ * Renewal reuses the same POST (a holder wins against itself — that IS
+ * renewal, per messageClaimService). A renewal that comes back claimed:false
+ * means our lease lapsed (laptop slept, turn ran long) and a peer re-won:
+ * mark lost so the run loop suppresses the wrapper post. Transient renewal
+ * errors are ignored — the current lease may still be live, and the next
+ * tick retries.
+ */
+export const createClaimKeeper = (client, {
+  messageId,
+  podId,
+  leaseSeconds = 90,
+  log = () => {},
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+}) => {
+  const path = `/api/agents/runtime/messages/${encodeURIComponent(messageId)}/claim`;
+  let acquired = false;
+  let lost = false;
+  let holder = null;
+  let timer = null;
+
+  const holderLabel = (res) => {
+    if (!res?.claimedBy) return 'another agent';
+    const instance = res.instanceId && res.instanceId !== 'default' ? `:${res.instanceId}` : '';
+    return `${res.claimedBy}${instance}`;
+  };
+
+  const stopRenewal = () => {
+    if (timer) {
+      clearIntervalImpl(timer);
+      timer = null;
+    }
+  };
+
+  return {
+    async acquire() {
+      try {
+        const res = await client.post(path, { podId, leaseSeconds });
+        if (res?.claimed) {
+          acquired = true;
+          return { claimed: true, expiresAt: res.expiresAt };
+        }
+        holder = holderLabel(res);
+        return { claimed: false, holder };
+      } catch (err) {
+        return { claimed: false, failOpen: true, error: err };
+      }
+    },
+
+    startRenewal() {
+      if (!acquired || timer) return;
+      timer = setIntervalImpl(async () => {
+        try {
+          const res = await client.post(path, { podId, leaseSeconds });
+          if (!res?.claimed) {
+            lost = true;
+            holder = holderLabel(res);
+            stopRenewal();
+            log(`claim on message ${messageId} lost mid-turn to ${holder} — standing down at post time`);
+          }
+        } catch {
+          // Transient renewal failure — the held lease may still be live;
+          // retry on the next tick rather than standing down on a blip.
+        }
+      }, Math.max(5000, (leaseSeconds * 1000) / 2));
+      if (timer && typeof timer.unref === 'function') timer.unref();
+    },
+
+    async release(outcome, { reason, status } = {}) {
+      stopRenewal();
+      if (!acquired || lost) return;
+      try {
+        // Preserve the one-argument legacy call when there is no explicit
+        // outcome. Besides keeping old clients' DELETE shape intact, callers
+        // that assert their transport arguments must not see a synthetic
+        // `undefined` body. An explicit outcome is the new D6.1 contract.
+        //
+        // `reason` and `status` ride only with a refusal (TASK-099) and only
+        // when the producer named them: the kernel stores the class as the
+        // record of why a delivery never happened, so an absent reason must
+        // stay absent rather than become the string "undefined".
+        if (!outcome) {
+          await client.del(path);
+          return;
+        }
+        const body = {
+          outcome,
+          ...(reason ? { reason } : {}),
+          ...(status !== undefined ? { status } : {}),
+        };
+        try {
+          await client.del(path, body);
+        } catch (err) {
+          // An older kernel validates the outcome against its own
+          // decline/completed enum and answers 400 — as it does for a reason
+          // it does not recognise. A CLI that ships before (or runs against a
+          // server earlier than) the third outcome must still release its
+          // lease, or the message stays claimed until it expires: one retry as
+          // `completed`, which is exactly what the old release did. Bounded to
+          // a 400 — a 500 or a timeout is not turned into a second write, and
+          // a second 400 is not retried again.
+          if (outcome !== 'refused' || err?.status !== 400) throw err;
+          log(`claim on message ${messageId}: kernel rejected the refused outcome (400) — releasing as completed`);
+          await client.del(path, { outcome: 'completed' });
+        }
+      } catch {
+        // Best-effort: a miss just means the lease already expired.
+      }
+    },
+
+    isLost: () => lost,
+    getHolder: () => holder,
+  };
+};
+
+// ── post-time length gate ───────────────────────────────────────────────────
+
+// A sentence ends at [.!?] followed by whitespace, except when what precedes
+// the whitespace is only a numbered list marker at the start of the line: in
+// "3. Run it once." the first period belongs to the marker, not a sentence.
+// Applied to one line at a time, so `^` is the line start.
+const SENTENCE_END = /(?<=[.!?])(?<!^[ \t]*\d{1,3}\.)\s+/;
+
+// Split one over-limit line at sentence boundaries, and a sentence that is
+// itself over the limit at word boundaries. A single over-limit word (a URL)
+// posts whole rather than being cut.
+const splitLineForChat = (line, limit) => {
+  const units = [];
+  let piece = '';
+  const flushPiece = () => {
+    if (piece.trim()) units.push(piece.trim());
+    piece = '';
+  };
+  for (const sentence of line.split(SENTENCE_END)) {
+    if (sentence.length > limit) {
+      flushPiece();
+      let run = '';
+      for (const word of sentence.split(/\s+/)) {
+        if (run && `${run} ${word}`.length > limit) {
+          units.push(run);
+          run = word;
+        } else {
+          run = run ? `${run} ${word}` : word;
+        }
+      }
+      if (run) units.push(run);
+    } else if (piece && `${piece} ${sentence}`.length > limit) {
+      flushPiece();
+      piece = sentence;
+    } else {
+      piece = piece ? `${piece} ${sentence}` : sentence;
+    }
+  }
+  flushPiece();
+  return units;
+};
+
+/**
+ * Split chat text into tone-contract-sized messages without ever cutting
+ * content. Boundaries in preference order: fenced code blocks stay whole
+ * (atomic — an oversized fence becomes one oversized message rather than a
+ * broken pair), then paragraphs, then lines (a list item never leaves its
+ * marker), then sentences, then words. Greedy packing rejoins small pieces so
+ * two short paragraphs share one message.
+ */
+export const splitForChat = (text, { limit = 400 } = {}) => {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return [];
+  if (trimmed.length <= limit) return [trimmed];
+
+  // Pass 1: carve into blocks — fences atomic, prose split by paragraph.
+  const blocks = [];
+  let prose = [];
+  const flushProse = () => {
+    const joined = prose.join('\n');
+    prose = [];
+    for (const para of joined.split(/\n{2,}/)) {
+      if (para.trim()) blocks.push({ text: para.trim(), atomic: false });
+    }
+  };
+  const lines = trimmed.split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const fence = lines[i].match(/^(```|~~~)/)?.[1];
+    if (fence) {
+      flushProse();
+      const fenced = [lines[i]];
+      i += 1;
+      while (i < lines.length && !lines[i].startsWith(fence)) {
+        fenced.push(lines[i]);
+        i += 1;
+      }
+      if (i < lines.length) {
+        fenced.push(lines[i]); // closing fence
+        i += 1;
+      }
+      blocks.push({ text: fenced.join('\n'), atomic: true });
+    } else {
+      prose.push(lines[i]);
+      i += 1;
+    }
+  }
+  flushProse();
+
+  // Pass 2: split oversized prose blocks at line, then sentence, then word
+  // boundaries. Lines come first because a list is one paragraph block whose
+  // items are separated by single newlines: splitting it by sentence read a
+  // numbered marker ("3.") as a sentence end and packed it onto the previous
+  // piece, so a support reply posted one message ending in "3." and the next
+  // opening with step 3's body (hq-support, 2026-10-09). Lines pack greedily
+  // with single newlines, so a list stays a list inside a message; only a line
+  // that is itself over the limit goes on to sentences and words.
+  const units = [];
+  for (const block of blocks) {
+    if (block.atomic || block.text.length <= limit) {
+      units.push(block.text);
+      continue;
+    }
+    let group = '';
+    const flushGroup = () => {
+      if (group) units.push(group);
+      group = '';
+    };
+    for (const rawLine of block.text.split('\n')) {
+      const line = rawLine.trimEnd(); // keep a nested item's indentation
+      if (!line.trim()) continue;
+      if (line.length > limit) {
+        flushGroup();
+        units.push(...splitLineForChat(line, limit));
+      } else if (group && `${group}\n${line}`.length > limit) {
+        flushGroup();
+        group = line;
+      } else {
+        group = group ? `${group}\n${line}` : line;
+      }
+    }
+    flushGroup();
+  }
+
+  // Pass 3: greedy packing back up to the limit.
+  const chunks = [];
+  let acc = '';
+  for (const unit of units) {
+    const joined = acc ? `${acc}\n\n${unit}` : unit;
+    if (joined.length <= limit) {
+      acc = joined;
+    } else {
+      if (acc) chunks.push(acc);
+      acc = unit;
+    }
+  }
+  if (acc) chunks.push(acc);
+  return chunks;
+};
+
+/**
+ * The final text of a comment @, as a reply to that comment (F225). It returns
+ * deliverChatReply's shape, so the run loop treats a refusal or a skip the same
+ * way on both. The route answers 200 with `success: false` for a refusal.
+ * `onlyIfUnanswered` is how a reply the seat already posted through
+ * commonly_post_thread_comment is not posted twice: a pod snapshot can't see a
+ * comment, and the server can. A 400, 403 or 404 won't change on a retry, so it
+ * is a refusal too; anything else throws, for redelivery. A line that must land
+ * after the seat's own reply passes `onlyIfUnanswered: false`.
+ */
+export const deliverCommentReply = async ({
+  client, postId, commentId, text, onlyIfUnanswered = true,
+}) => {
+  const refused = (reason, guidance) => ({
+    mode: 'refused', messages: 0, attemptedMessages: 1, refused: true, reason, guidance,
+  });
+  let response;
+  try {
+    response = await client.post(`/api/agents/runtime/threads/${encodeURIComponent(postId)}/comments`, {
+      content: text, replyToCommentId: commentId, onlyIfUnanswered,
+    });
+  } catch (error) {
+    if (![400, 403, 404].includes(error?.status)) throw error;
+    return refused(`comment_post_${error.status}`, `The server refused this comment: ${error.message}`);
+  }
+  if (response?.agentCommentsDisabled) {
+    return refused('agent_comments_disabled', 'This post has agent comments turned off.');
+  }
+  if (response?.selfReply) return refused('self_reply', 'An agent cannot reply to its own comment.');
+  if (response?.success === false) return refused('comment_refused', 'The server refused this comment.');
+  if (response?.skipped) {
+    return {
+      mode: 'skipped', messages: 0, attemptedMessages: 1, skipped: true, reason: response.reason || 'skipped',
+    };
+  }
+  return { mode: 'comment', messages: response?.duplicate ? 0 : 1, attemptedMessages: 1,
+    alreadyAnswered: response?.duplicate === true };
+};
+
+/**
+ * Deliver a wrapper-posted reply under the tone contract, deterministically:
+ *
+ *   fits in one message            → post as-is
+ *   splits into ≤ maxChunks        → post the chunks in order ("two short
+ *                                    messages beat one wall")
+ *   longer than a split answer     → post the FIRST chunk to the channel and
+ *                                    continue the rest in a thread under it.
+ *   one indivisible oversize unit  → it is a genuine document: upload the FULL
+ *                                    text and post one message — the reply's
+ *                                    own opening plus the file card.
+ *
+ * The thread rung is new and it replaces attachment as the answer
+ * for PROSE overflow. Before threads existed, a long analysis had nowhere to
+ * go but a file, and that was the right workaround. It is now the wrong one:
+ * an attachment is un-quotable, un-followable, and an all-or-nothing read,
+ * so overflowing into one buries the tail of a reply in a surface nobody can
+ * respond to. A thread keeps every word addressable and scopes the read.
+ *
+ * This is also the layer the rule has to live at. The pod-context cue already
+ * tells agents "prose overflow goes in a thread, not an attachment" (#1176),
+ * and the cue could not have been obeyed: the model does not choose the
+ * delivery mode, THIS FUNCTION does, and it only knew how to attach. A cue
+ * that promises what the wrapper contradicts teaches the agent it is failing
+ * at something it never controlled.
+ *
+ * Attachment is kept for the case it was always right for — a single atomic
+ * unit over `attachThreshold` (a long fence, an unbreakable run). That is a
+ * document by construction, not prose that outgrew a message.
+ *
+ * If threading fails (older server with no threadRootId support, no id in the
+ * response), fall back to attach, then to posting every chunk: a message
+ * flood is a tone violation, silence or truncation is a correctness
+ * violation, and the contract ranks content above tone ("NEVER hit that by
+ * cutting content").
+ */
+export const deliverChatReply = async ({
+  client,
+  podId,
+  text,
+  limit = 400,
+  maxChunks = 3,
+  attachThreshold = 800,
+  uploadName = 'reply.md',
+  log = () => {},
+  // D245 item 4: how this reply was made (lib/reply-receipt.js). It rides
+  // the first message that actually reaches the pod and no later one.
+  receipt = null,
+  // Keeps a reply that fits in up to maxChunks messages in that thread. The
+  // overflow rungs below start their own thread, so a caller with a long reply
+  // doesn't set this.
+  threadRootId = null,
+}) => {
+  const messagesPath = `/api/agents/runtime/pods/${podId}/messages`;
+  const chunks = splitForChat(text, { limit });
+  // The runtime route uses HTTP 200 for a policy refusal: it is a completed
+  // request, but no message was created. Keep that distinction at the client
+  // boundary so every delivery mode shares it rather than treating a resolved
+  // promise as proof of a post.
+  //
+  // TASK-535 — the send-time freshness hold. The backend answers 409
+  // `unseen_messages` when other members posted after this seat's last
+  // recorded tail read. A turn that ran ~43 minutes
+  // hit it on the thread headline, the attach card and the split fallback in
+  // turn, so the reply was lost and its 10 events re-ran. A retry without an
+  // override cannot succeed — every rung posts to the same guarded route.
+  //
+  // CTO ruling: on the FIRST hold of a delivery, re-read the pod tail once,
+  // then post with `continueAnyway: true`, and keep the override for every
+  // later post in THIS delivery (remaining chunks, later rungs). The re-read
+  // is GET /messages at the route's 50-row cap with no `before`/`threadRootId`
+  // — the read that records a seen cursor (AgentSendFreshness.recordRead). It
+  // advances the cursor only when the page holds EVERY message since the last
+  // recorded read. The wrapper's own post-turn snapshot is that same read at
+  // limit 10, which is why a 12-message gap stayed unseen. So a re-read alone
+  // passes a normal post only while the gap is ≤ 50 and nothing lands between
+  // read and post; the override is what delivers, and the read records what
+  // the wrapper saw, exactly as its snapshots already do. One re-read and one
+  // override per delivery; a post that still fails throws to the next rung as
+  // before. Nothing here loops.
+  let freshnessOverride = false;
+  let receiptDelivered = !receipt;
+  const postOnce = async (rawBody) => {
+    const body = receiptDelivered ? rawBody : { ...rawBody, receipt };
+    const response = await postGuarded(body);
+    if (response?.refused !== true && response?.skipped !== true) receiptDelivered = true;
+    return response;
+  };
+  const postGuarded = async (body) => {
+    if (freshnessOverride) return client.post(messagesPath, { ...body, continueAnyway: true });
+    try {
+      return await client.post(messagesPath, body);
+    } catch (error) {
+      if (!isUnseenMessagesHold(error)) throw error;
+      freshnessOverride = true;
+      const unseen = error.body?.unseenCount;
+      log(
+        `reply held: ${Number.isFinite(unseen) ? unseen : 'some'} unseen message(s) in pod ${podId} `
+        + 'arrived during the turn — re-reading the pod once, then posting with continueAnyway (TASK-535)',
+      );
+      try {
+        await client.get(messagesPath, { limit: 50 });
+      } catch (readError) {
+        // The re-read is bookkeeping, not permission: the override delivers.
+        log(`pod re-read before the continueAnyway post failed (${readError.message}) — posting anyway`);
+      }
+      return client.post(messagesPath, { ...body, continueAnyway: true });
+    }
+  };
+  const refused = (response, messages, attemptedMessages) => ({
+    mode: 'refused',
+    messages,
+    attemptedMessages,
+    refused: true,
+    reason: response.reason || 'message_refused',
+    ...(typeof response.guidance === 'string' && response.guidance
+      ? { guidance: response.guidance }
+      : {}),
+    ...(typeof response.consecutive === 'number'
+      ? { consecutive: response.consecutive }
+      : {}),
+  });
+  // The same route also answers HTTP 200 with `{ success: true, skipped: true,
+  // reason }` when it decided not to create a row: a duplicate inside the dedupe
+  // window, a silent or empty body, a heartbeat it keeps to itself. The wrapper
+  // used to read that as a delivery and log "posted … (single)" while nothing
+  // reached the pod (hq-support, 2026-10-09 08:10Z), so a silent seat could not
+  // be read from its own log. A skip is a completed request and not a delivery,
+  // exactly like a refusal, and it stops a sequence the same way.
+  const skipped = (response, messages, attemptedMessages) => {
+    const duplicate = response.duplicate && typeof response.duplicate === 'object'
+      ? response.duplicate
+      : null;
+    return {
+      mode: 'skipped',
+      messages,
+      attemptedMessages,
+      skipped: true,
+      reason: response.reason || 'message_skipped',
+      ...(duplicate
+        ? {
+          duplicate: {
+            ...(duplicate.id ? { id: String(duplicate.id) } : {}),
+            ...(typeof duplicate.dedupeWindowMinutes === 'number'
+              ? { dedupeWindowMinutes: duplicate.dedupeWindowMinutes }
+              : {}),
+          },
+        }
+        : {}),
+    };
+  };
+  const undelivered = (response) => response?.refused === true || response?.skipped === true;
+  const nonDelivery = (response, messages, attemptedMessages) => (
+    response?.refused === true
+      ? refused(response, messages, attemptedMessages)
+      : skipped(response, messages, attemptedMessages)
+  );
+  // An atomic unit (a fenced block, an unbreakable word-run) can exceed the
+  // limit by construction — splitForChat keeps it whole rather than breaking
+  // its rendering. The tone contract's own rule covers it: over ~800 chars of
+  // ONE indivisible thing is a document, not a message — attach it. Without
+  // this check a 659-char fence rode the single/split branches straight past
+  // the gate (found by the fleet's implementation audit).
+  const hasIndivisibleOversize = chunks.some((c) => c.length > attachThreshold);
+  const placement = threadRootId ? { threadRootId } : {};
+  if (chunks.length <= 1 && !hasIndivisibleOversize) {
+    const response = await postOnce({ content: chunks[0] ?? text, ...placement });
+    if (undelivered(response)) return nonDelivery(response, 0, 1);
+    return { mode: 'single', messages: 1 };
+  }
+  if (chunks.length <= maxChunks && !hasIndivisibleOversize) {
+    let messages = 0;
+    for (const chunk of chunks) {
+      // eslint-disable-next-line no-await-in-loop
+      const response = await postOnce({ content: chunk, ...placement }); // in order, so the reply reads top-down
+      if (undelivered(response)) return nonDelivery(response, messages, chunks.length);
+      messages += 1;
+    }
+    return { mode: 'split', messages };
+  }
+  // PROSE OVERFLOW → THREAD. Only when nothing is indivisibly oversize: a
+  // fence too big to split is a document and belongs in the attach rung below.
+  if (!hasIndivisibleOversize) {
+    // A COUNT, not a flag. The recovery below resumes from here, and a boolean
+    // can only distinguish "nothing posted" from "something posted" — it cannot
+    // say how much. Fail a continuation at chunk 3 with a boolean and chunks 1
+    // and 2 are already in the thread, then get posted again top-level; the
+    // reader sees them twice. Getting this wrong is silent, which is also why
+    // the attach rung below leads with `chunks[0]`: falling through after a
+    // successful headline duplicates the opening line. Two of this suite's
+    // existing tests caught that one, and none caught this one, because both
+    // fail at the root-id step before any continuation has posted.
+    let posted = 0;
+    try {
+      const rootRes = await postOnce({ content: chunks[0] });
+      if (undelivered(rootRes)) return nonDelivery(rootRes, 0, chunks.length);
+      posted = 1;
+      // The runtime route answers `res.json(result)` with the created row on
+      // `result.message`. Accept either id field; refuse to guess if neither
+      // is present, because a continuation posted with a missing root would
+      // silently become another top-level message — the exact flood this rung
+      // exists to prevent.
+      // The kernel can file the headline in the thread the turn answers (F245),
+      // and a thread has one root, so its root wins over the headline's own id.
+      const rootId = rootRes?.message?.thread_root_id
+        ?? rootRes?.message?.id ?? rootRes?.message?._id ?? rootRes?.id ?? rootRes?._id;
+      if (!rootId) throw new Error('no message id in post response — cannot root the thread');
+      for (const chunk of chunks.slice(1)) {
+        // eslint-disable-next-line no-await-in-loop
+        const response = await postOnce({ content: chunk, threadRootId: String(rootId) });
+        if (undelivered(response)) return nonDelivery(response, posted, chunks.length);
+        posted += 1;
+      }
+      return { mode: 'thread', messages: chunks.length, threadRootId: String(rootId) };
+    } catch (err) {
+      if (posted > 0) {
+        // The opening is already in the room. Post the REMAINDER top-level —
+        // never the whole text again. This is the old flood, minus the
+        // duplicate, and it is still preferable to attaching: content ranks
+        // above tone, and the reader would otherwise see the same paragraph
+        // twice with the rest hidden in a file.
+        log(`thread continuation failed (${err.message}) — posting the remainder top-level`);
+        for (const chunk of chunks.slice(posted)) {
+          // eslint-disable-next-line no-await-in-loop
+          const response = await postOnce({ content: chunk });
+          if (undelivered(response)) return nonDelivery(response, posted, chunks.length);
+          posted += 1;
+        }
+        return { mode: 'thread-fallback', messages: chunks.length };
+      }
+      // Nothing reached the room, so the attach rung below is free to lead
+      // with the opening as it always did.
+      log(`thread headline failed (${err.message}) — falling back to attach`);
+    }
+  }
+  try {
+    const uploaded = await client.upload(`/api/agents/runtime/pods/${podId}/uploads`, {
+      fileBuffer: Buffer.from(String(text), 'utf8'),
+      fileName: uploadName,
+      contentType: 'text/markdown',
+      fields: { podId },
+    });
+    const u = uploaded || {};
+    const directive = `[[upload:${u.fileName || uploadName}|${u.originalName || uploadName}|${u.size ?? Buffer.byteLength(String(text))}|${u.kind || 'document'}]]`;
+    // Lead with the reply's own opening — unless that opening is itself the
+    // oversized atomic unit (a fence-only reply), in which case a generic
+    // line keeps the message under the gate and the card carries the content.
+    const lead = chunks[0] && chunks[0].length <= limit
+      ? chunks[0]
+      : '(reply too large for chat — attached in full)';
+    const response = await postOnce({ content: `${lead}\n\n${directive}` });
+    if (undelivered(response)) return nonDelivery(response, 0, 1);
+    return { mode: 'attach', messages: 1 };
+  } catch (err) {
+    log(`attach fallback failed (${err.message}) — posting ${chunks.length} split messages instead`);
+    let messages = 0;
+    for (const chunk of chunks) {
+      // eslint-disable-next-line no-await-in-loop
+      const response = await postOnce({ content: chunk });
+      if (undelivered(response)) return nonDelivery(response, messages, chunks.length);
+      messages += 1;
+    }
+    return { mode: 'split-fallback', messages };
+  }
+};