@cohortapp/agent-sdk 2.18.8 → 2.18.10

package/docs/runbooks/fleet-rollout.md

@@ -123,6 +123,36 @@ Until it does, the run says so in words on every all-unverifiable finish — tha
 exit 3 does **not** mean a seat is behind — rather than leaving the reader to
 infer it from a count.
 
+## What a rollout cannot do: a seat whose front door is blocked
+
+Publishing is not deploying, and a green stage 3 is not a seat that answers.
+Between "the registry has it" and "this fix is running on that machine" there
+are three steps, and only the first two happen by themselves:
+
+1. **the install** — the seat's hourly `autoupdate.sh` runs
+   `npm install @cohortapp/agent-sdk@latest` and lays the framework down;
+2. **the restart** — the daemon is kickstarted and the front door relaunched.
+   Since 2.18.8 the upgrade restarts a front door that is loaded but not
+   beating, so this no longer needs a person in the ordinary case;
+3. **a front door that can actually start.** This one has no automatic path.
+
+Step 3 is the gap to state out loud whenever a change ships that only runs on a
+restarted daemon. A front-door session sitting on a **first-run, permission or
+subscription modal** is alive to launchd, alive to `ps`, and answering nobody;
+the supervisor (2.18.6+) clears the modals it can name and restarts the session
+when it cannot, but a dialog that needs a human decision — trust this folder,
+grant this access, choose how to spend money — is not one of those, and waiting
+longer never clears it. Somebody has to be **at that keyboard**: attach to the
+session (`tmux attach -t maestro-<name>`, or `screen -r maestro-<name>`), read
+what is on the screen, and answer it. `plugins/maestro-skills/skills/seat-upgrade.md`
+is the procedure, including which options are never yours to press.
+
+So the honest form of "this fix is rolled out" is per seat, not per publish:
+the version moved, the beat is fresh, `maestro session status` is not
+`NOT LIVE`, and the inbox is being answered. A seat stuck at step 3 will show a
+fresh beat from a restarted DAEMON and still answer nothing — which is why the
+beat alone is never the proof.
+
 ## One wrinkle: the gates dirty the tree
 
 `npm test` appends to a tracked runtime ledger (`.claude-flow/policy/state.json`),

package/lib/comms/send-gate.mjs

@@ -487,7 +487,7 @@ export function screenScaffold(text) {
  *
  * @returns {string|null} block reason, or null if disclosure rules are satisfied
  */
-export function screenDisclosure(text, { policy, jurisdiction, firstContact }) {
+export function screenDisclosure(text, { policy, jurisdiction, firstContact, recipientClass, channel }) {
   const lc = String(text || "").toLowerCase();
 
   // 1. Truthfulness invariant — locked, applies under every posture. A message
@@ -537,9 +537,31 @@ export function screenDisclosure(text, { policy, jurisdiction, firstContact }) {
 
   const posture = postures[postureName] || {};
 
-  // Only first-contact messages carry the proactive-disclosure duty; a reply in
-  // an ongoing thread does not have to re-disclose every turn.
-  if (posture.proactive_disclosure && firstContact) {
+  // WHO THE DUTY IS OWED TO, and when.
+  //
+  // Two scopes, both read from the policy rather than assumed here:
+  //   - first contact only. A reply in an ongoing thread does not re-disclose
+  //     every turn.
+  //   - external recipients only, when the posture says
+  //     `internal_recipients_exempt`. A colleague inside the deploying
+  //     organisation, who sees an AI badge beside the agent's name on every
+  //     surface, is not the person Art. 50(1) is about.
+  //
+  // Unscoped on the second axis, this screen blocked every internal post that
+  // did not carry the identity line — which taught agents to open every
+  // message, including mid-thread corrections to their own numbers, with
+  // "Quick note before we get into it: I'm <name>, an AI assistant working
+  // with <principal>". The block was doing that, not the model: the only way
+  // past a gate that demands disclosure is to disclose.
+  //
+  // A channel may narrow it further via `channels.<channel>.identity_scope`,
+  // the same shape the email footer already carries.
+  const chScope = (policy.channels && policy.channels[channel] && policy.channels[channel].identity_scope) || {};
+  const internalExempt = chScope.external_recipients_only !== undefined
+    ? chScope.external_recipients_only === true
+    : posture.internal_recipients_exempt === true;
+  const dutyOwed = !(internalExempt && recipientClass === "internal");
+  if (posture.proactive_disclosure && firstContact && dutyOwed) {
     const discloses =
       /\bai\b/i.test(String(text || "")) ||
       lc.includes("automated") ||
@@ -738,6 +760,8 @@ export async function screenOutbound({
       policy: disclosurePolicy,
       jurisdiction,
       firstContact,
+      recipientClass,
+      channel,
     });
     if (disclosureReason) return blocked(disclosureReason);
 

package/lib/daemon/reply-debt.mjs

@@ -0,0 +1,105 @@
+/**
+ * lib/daemon/reply-debt.mjs — the seat's count of replies it OWED and did not send.
+ *
+ * Three measured failures on this machine ended the reply path in nothing:
+ *
+ *   1. `claude CLI exited 1: Error: Session ID <uuid> is already in use.` — the
+ *      session router's RESUME decision handed a used id to `--session-id`,
+ *      which is the flag for STARTING a session. Fixed at the source
+ *      (`sessionArgs` in lib/runtime/adapter.mjs) and retried once here.
+ *   2. `Quick reply PERMANENTLY failed for <name> (FORBIDDEN_SCOPE)` — the seat
+ *      is missing a scope. That is a CONFIGURATION fault: no retry, no session,
+ *      and no amount of waiting fixes it. Someone has to grant the scope.
+ *   3. A CLI stdout that does not parse as the JSON envelope. Failing closed is
+ *      right — the raw model turn must not reach the wire — but the outcome is
+ *      still silence.
+ *
+ * In all three the seat knows it withheld a reply and nobody downstream does.
+ * The obligation file and the needs-attention JSON are on the seat's own disk;
+ * an operator would have to already suspect this seat to go and look. So every
+ * withheld reply is counted through `lib/diagnostics/counters.mjs` (durable
+ * JSONL, per UTC day, survives a restart) under the names below, and
+ * {@link replyDebtFromCounters} folds today's totals into the one small object
+ * the status snapshot carries on every presence beat — which is what turns
+ * "this seat withheld N replies today" into a number somebody can see without
+ * an ssh.
+ *
+ * PURE. No clock, no disk, no env: the caller passes today's totals and the
+ * date. (`docs`/CLAUDE.md: decisions are pure functions; I/O at the edge.)
+ *
+ * @module lib/daemon/reply-debt
+ */
+
+"use strict";
+
+/**
+ * The counter names the reply path bumps. One table so the emitter
+ * (scripts/daemon/*) and the reader (lib/telemetry/collect) cannot drift —
+ * a typo on either side would silently zero the number a human reads.
+ */
+export const REPLY_DEBT_COUNTERS = Object.freeze({
+  /** A reply was withheld because the CLI's stdout did not parse as the envelope. */
+  unparseable: "reply.withheld_unparseable",
+  /** A reply was refused by a scope the seat does not hold (configuration fault). */
+  scopeRefused: "reply.scope_refused",
+  /** A spawn hit `Session ID … is already in use`. */
+  sessionCollision: "reply.session_collision",
+  /** …and the one retry with a fresh id recovered it. */
+  sessionCollisionRecovered: "reply.session_collision_recovered",
+});
+
+function count(totals, name) {
+  const n = Number(totals && totals[name]);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Fold today's counter totals into the seat-level reply-debt summary.
+ *
+ * Returns `null` when the seat owes nothing today — an all-zero object on every
+ * beat would be noise in the snapshot and would train a reader to ignore the
+ * field, which is the failure this exists to fix.
+ *
+ * `withheld` is the headline: replies a person was owed and did not get. A
+ * collision that the retry RECOVERED is not withheld (the person got the
+ * answer), so it is reported separately rather than summed in — overcounting
+ * would make the number untrustworthy in the direction that gets it ignored.
+ *
+ * @param {Record<string, number>} totals `counters.snapshot()` for today
+ * @param {{date?: string}} [o] UTC date stamp the totals are for (YYYY-MM-DD)
+ * @returns {{withheld:number, unparseable:number, scopeRefused:number,
+ *            sessionCollisions:number, recovered:number, date?:string}|null}
+ */
+export function replyDebtFromCounters(totals, o = {}) {
+  const unparseable = count(totals, REPLY_DEBT_COUNTERS.unparseable);
+  const scopeRefused = count(totals, REPLY_DEBT_COUNTERS.scopeRefused);
+  const sessionCollisions = count(totals, REPLY_DEBT_COUNTERS.sessionCollision);
+  const recovered = count(totals, REPLY_DEBT_COUNTERS.sessionCollisionRecovered);
+  // A collision that the retry did not recover cost a reply. Clamped at 0: the
+  // two counters are bumped by different code paths and a restart between them
+  // could in principle leave recovered > collisions for the day.
+  const lostToCollision = Math.max(0, sessionCollisions - recovered);
+  const withheld = unparseable + scopeRefused + lostToCollision;
+  if (withheld === 0 && sessionCollisions === 0) return null;
+  const out = { withheld, unparseable, scopeRefused, sessionCollisions, recovered };
+  if (typeof o.date === "string" && o.date) out.date = o.date;
+  return out;
+}
+
+/**
+ * Is this send failure a CONFIGURATION fault — a scope or permission the seat
+ * does not hold — rather than a transport problem?
+ *
+ * The distinction decides who is owed the trace. A transport failure is the
+ * seat's own problem and the assurance sweep retries it; a scope fault is
+ * somebody else's problem and retrying is dead time. `FORBIDDEN_SCOPE` is hq's
+ * code for a 403 (lib/org/client.mjs:230).
+ *
+ * @param {string|null|undefined} code
+ * @returns {boolean}
+ */
+export function isScopeFault(code) {
+  return String(code || "").toUpperCase() === "FORBIDDEN_SCOPE";
+}
+
+export default { REPLY_DEBT_COUNTERS, replyDebtFromCounters, isScopeFault };

package/lib/org/inbound/directedness.mjs

@@ -82,6 +82,66 @@ export const MEMBERSHIP_REQUIRED_KINDS = Object.freeze([
  * "@here", "roll call"); surface `broadcast`. See broadcast.mjs.
  */
 
+/**
+ * The reasons that are MEMBERSHIP or VISIBILITY, not identity: this seat was
+ * addressed because it can see the thing, not because anything named it.
+ *
+ * The distinction matters downstream: an ambient address is what a responder
+ * ELECTION exists to arbitrate (one seat answers for the room), while a personal
+ * address has nothing to arbitrate and is simply mine to answer. Get a reason on
+ * the wrong side of this line and every seat that shares the room answers the
+ * same comment.
+ *
+ * ── THE TEST A REASON HAS TO PASS TO STAY OUT OF THIS LIST ──
+ * Not "does it sound personal" — CAN TWO SEATS HOLD IT AT ONCE FOR THE SAME
+ * EVENT, on a fact that is about access rather than about them? Walked through
+ * the whole vocabulary, with the fact each one is read from:
+ *
+ *   IN (plural, access-shaped):
+ *   - `channel`      — `facts.memberChannelIds`. I am in the room.
+ *   - `participant`  — a call in a room I belong to; the room is the join.
+ *   - `shared`       — `facts.fileAcl`, and this one was the bug. `resolveDoc`
+ *     answers `shared` whenever the ACL entry says so, and `facts.mjs` builds
+ *     that entry as `Boolean(permission && permission !== "none")` — i.e. "I can
+ *     OPEN this file". That is a visibility fact of exactly the same class as
+ *     room membership: a doc shared to a 16-seat channel grants it to all
+ *     sixteen. Treating it as a personal address put sixteen replies on one
+ *     comment — the storm the election exists to prevent, relocated to a new
+ *     surface.
+ *
+ *   OUT (singular, identity-shaped), and why each is safe:
+ *   - `owner` / `calendar_owner` — one id compared to mine (`acl.ownerId`).
+ *   - `named` — my own name matched in the comment body.
+ *   - `assignee` / `reviewer` — `facts.taskRole`, built from the task's single
+ *     `assigneeId` / `reviewerId` columns. hq has no reviewer LIST; if it ever
+ *     grows one, `reviewer` moves into this list on the same argument as
+ *     `shared`.
+ *   - `approver` / `requester` / `waiting_on` / `direct` / `to` — a single id on
+ *     the row, compared to mine.
+ *   - `proposer` — `decision.proposedBy`, one id.
+ *   - `attendee` — my own attendee row on the event, from my ACL'd read.
+ *   - `commenter` — plural, but it is `decisionVoices.has(me)`: I SPOKE there.
+ *     That is the same shape as `thread` below — participation I performed, not
+ *     access I was granted — and it stays out for the same reason.
+ *
+ * `thread` is deliberately NOT here: a reply in a thread I have spoken in is a
+ * continuation of my own participation, and it is a room surface anyway, so it
+ * keeps the messaging election by the ordinary route.
+ *
+ * @type {readonly string[]}
+ */
+export const MEMBERSHIP_REASONS = Object.freeze(["channel", "participant", "shared"]);
+
+/**
+ * Was this item's address proved by membership rather than by naming this seat?
+ *
+ * @param {string} reason a {@link Reason}
+ * @returns {boolean}
+ */
+export function isMembershipReason(reason) {
+  return MEMBERSHIP_REASONS.includes(String(reason || ""));
+}
+
 /** Narrow an unknown payload to a readable record (never throws). */
 function obj(v) {
   return v && typeof v === "object" && !Array.isArray(v) ? v : {};

package/lib/org/inbound/facts.mjs

@@ -80,6 +80,7 @@ export const DEFAULT_LIMITS = Object.freeze({
  * @property {Set<string>|null} myEventIds        calendar events I own or attend (null == unreadable)
  * @property {Map<string,object>|null} myEvents   eventId → the calendar event DTO
  * @property {Map<string,string>|null} memberKinds member id AND slug → "HUMAN"|"AI_AGENT" (null == not read / unreadable)
+ * @property {Map<string,string>|null} memberNames member id AND slug → displayName (null == not read / unreadable)
  * @property {number|null} aiMemberCount          how many AI_AGENT members the org has (the roll-call respondent bound)
  * @property {string[]} degraded               names of facts that could not be read
  */
@@ -134,6 +135,7 @@ export async function resolveFacts(o = {}) {
     myEventIds: null,
     myEvents: null,
     memberKinds: null,
+    memberNames: null,
     aiMemberCount: null,
     degraded,
   };
@@ -353,8 +355,18 @@ export function wantsMemberKinds(candidates, facts, me) {
 /**
  * `member.list` → `facts.memberKinds` keyed by BOTH member id and slug (the
  * chain's `actor` is documented as "member slug or api-key id" while history's
- * `authorId` is the cuid; one map answers either) + `facts.aiMemberCount`.
- * Org-scoped, read-only, the same directory every seat may already list.
+ * `authorId` is the cuid; one map answers either) + `facts.memberNames`, keyed
+ * the same way, + `facts.aiMemberCount`. Org-scoped, read-only, the same
+ * directory every seat may already list.
+ *
+ * WHY THE NAMES, GIVEN THE KINDS WERE ENOUGH. Every hydrator falls back to
+ * `c.actor` when the surface's own payload carries no author NAME — and for a
+ * doc comment, a decision comment or an approval, the payload routinely carries
+ * only an id. That fallback put a raw member cuid into `from.name`, so the item
+ * arrived with `sender: "cmub6e9lb0ojn…"` and every log line, every prompt and
+ * every board row said it. The directory that answers "who is that id" was
+ * already being fetched here, once per pull, and its names were being thrown
+ * away. Keeping them costs no extra call.
  */
 async function resolveMemberKinds({ facts, io, log, degraded }) {
   const frame = await io.call("member.list", {});
@@ -364,13 +376,25 @@ async function resolveMemberKinds({ facts, io, log, degraded }) {
     return;
   }
   const kinds = new Map();
+  const names = new Map();
   let ai = 0;
   for (const m of arrayOf(resultOf(frame), "members")) {
     if (!m) continue;
-    const kind = String(m.kind || "").toUpperCase();
-    if (!kind) continue;
     const id = String(m.id || "");
     const slug = String(m.slug || "");
+    // The name is recorded even for a member whose `kind` is blank — an unknown
+    // kind is a reason not to prove anybody human, never a reason to forget who
+    // they are.
+    const name = String(m.displayName || "").trim();
+    if (name) {
+      if (id) names.set(id, name);
+      if (slug) {
+        names.set(slug, name);
+        names.set(slug.toLowerCase(), name);
+      }
+    }
+    const kind = String(m.kind || "").toUpperCase();
+    if (!kind) continue;
     if (id) kinds.set(id, kind);
     if (slug) {
       kinds.set(slug, kind);
@@ -379,6 +403,7 @@ async function resolveMemberKinds({ facts, io, log, degraded }) {
     if (kind === "AI_AGENT") ai += 1;
   }
   facts.memberKinds = kinds;
+  facts.memberNames = names;
   facts.aiMemberCount = ai;
 }
 

package/lib/org/inbound/project.mjs

@@ -87,7 +87,7 @@ export function toMessageEvent(o = {}) {
   const subjectDetail = s(hydrated.subjectDetail);
   const subject = subjectDetail ? `${def.subject}: ${subjectDetail}` : def.subject;
 
-  const from = hydrated.from || { id: s(c.actor), name: s(c.actor) };
+  const from = resolveFrom(hydrated, c, facts);
   const scope = scopeFor(verdict.surface, channelKind, def.scope);
 
   const ev = {
@@ -199,6 +199,43 @@ export function toMessageEvent(o = {}) {
   return ev;
 }
 
+/**
+ * Who sent this — with a NAME, not a database id.
+ *
+ * Every hydrator ends its `from` with the same fallback chain, and the last link
+ * is always `c.actor`, a member cuid. That is correct as a LAST resort and wrong
+ * as an answer: a surface whose payload carries only an author id (a doc
+ * comment, a decision comment, an approval) arrived with `name === id`, and the
+ * id is what then appeared in the daemon's log lines ("staying silent for
+ * cmub6e9lb0ojn…"), in the classifier prompt, and on any board row the turn
+ * opened. The org directory that answers "who is that id" is already in hand —
+ * `facts.memberNames`, built from the one `member.list` the facts pass makes per
+ * pull — so this consults it before settling for the id.
+ *
+ * FAIL-OPEN, like everything else in this file: an unreadable directory, an
+ * outsider, an api-key actor with no member row, all keep today's behaviour and
+ * carry the id. A name is an improvement on an id, never a precondition for
+ * delivering the item.
+ *
+ * @param {import("./hydrate.mjs").Hydrated} hydrated
+ * @param {import("./directedness.mjs").Candidate} c
+ * @param {import("./facts.mjs").Facts} facts
+ * @returns {{id:string,name:string}}
+ */
+export function resolveFrom(hydrated, c, facts) {
+  const raw = (hydrated && hydrated.from) || {};
+  const id = s(raw.id || (c && c.actor));
+  const given = s(raw.name).trim();
+  // A hydrator that could not find a name hands back the id itself. Treat that
+  // as "no name", not as a name that happens to look like a cuid.
+  if (given && given !== id) return { id, name: given };
+  const names = facts && facts.memberNames instanceof Map ? facts.memberNames : null;
+  const looked = names
+    ? s(names.get(id) || names.get(id.toLowerCase()) || "").trim()
+    : "";
+  return { id, name: looked || given || id };
+}
+
 /**
  * The per-surface `message_id`. For messaging this stays the hq message id so
  * the projection is byte-identical to today's DM path; for everything else the

package/lib/org/inbound/surfaces.mjs

@@ -16,6 +16,10 @@
  *               daemon classifier can route WITHOUT parsing prose,
  *   - `subject` the human-readable inbox subject prefix,
  *   - `scope`   the `source.userScope` the projection stamps,
+ *   - `room`    is this surface ROOM TRAFFIC — does it arrive on a Cohort
+ *               channel, carry a real `channel_id`, and is a reply to it a
+ *               message posted back into that room? See `ROOM_SURFACES` below
+ *               for why this is a structural fact and not a convenience.
  *   - `default` whether the surface is tailed unless the operator says otherwise.
  *
  * Adding a surface is a data edit here plus a `classifyEvent` branch in
@@ -45,6 +49,7 @@ export const SURFACES = Object.freeze({
     kind: "message",
     subject: "Cohort message",
     scope: "dm",
+    room: true,
     default: true,
   }),
   /** An @mention of me in a public/private space. THE headline gap. */
@@ -53,6 +58,7 @@ export const SURFACES = Object.freeze({
     kind: "mention",
     subject: "Cohort @mention",
     scope: "channel",
+    room: true,
     default: true,
   }),
   /**
@@ -67,6 +73,7 @@ export const SURFACES = Object.freeze({
     kind: "broadcast",
     subject: "Cohort roll-call",
     scope: "channel",
+    room: true,
     default: true,
   }),
   /** A reply in a thread I have spoken in / been named in. */
@@ -75,6 +82,7 @@ export const SURFACES = Object.freeze({
     kind: "thread_reply",
     subject: "Cohort thread reply",
     scope: "channel",
+    room: true,
     default: true,
   }),
   /** A call started/invited in one of my rooms. Byte-compatible with today. */
@@ -83,6 +91,7 @@ export const SURFACES = Object.freeze({
     kind: "call",
     subject: "Cohort call invite",
     scope: "channel",
+    room: true,
     default: true,
   }),
   /** A board item assigned to me (or claimed/completed on my behalf). */
@@ -91,6 +100,7 @@ export const SURFACES = Object.freeze({
     kind: "task_assigned",
     subject: "Cohort task assigned",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** A comment / block / move on a board item I own or review. */
@@ -99,6 +109,7 @@ export const SURFACES = Object.freeze({
     kind: "task_comment",
     subject: "Cohort task update",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** A comment on a chat-attached file in one of my rooms (family `file`). */
@@ -107,6 +118,7 @@ export const SURFACES = Object.freeze({
     kind: "file_comment",
     subject: "Cohort file comment",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** A comment / suggestion on a workspace doc I own or am shared on (family `files`). */
@@ -115,6 +127,7 @@ export const SURFACES = Object.freeze({
     kind: "file_comment",
     subject: "Cohort document comment",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** An approval on my desk, or the outcome of one I requested. */
@@ -123,6 +136,7 @@ export const SURFACES = Object.freeze({
     kind: "approval",
     subject: "Cohort approval",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** A decision I proposed / commented on / must sign. */
@@ -131,6 +145,7 @@ export const SURFACES = Object.freeze({
     kind: "decision",
     subject: "Cohort decision",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** An escalation raised on my task / in my room / waiting on me. */
@@ -139,6 +154,7 @@ export const SURFACES = Object.freeze({
     kind: "escalation",
     subject: "Cohort escalation",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /**
@@ -159,6 +175,7 @@ export const SURFACES = Object.freeze({
     kind: "calendar",
     subject: "Cohort calendar",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** A delegation offered to me, or one I offered being accepted/declined. */
@@ -167,6 +184,7 @@ export const SURFACES = Object.freeze({
     kind: "handoff",
     subject: "Cohort handoff",
     scope: "channel",
+    room: false,
     default: true,
   }),
   /** An inbound email routed to my mailbox. OFF by default — see note above. */
@@ -175,6 +193,7 @@ export const SURFACES = Object.freeze({
     kind: "email",
     subject: "Cohort email",
     scope: "dm",
+    room: false,
     default: false,
   }),
 });
@@ -182,6 +201,55 @@ export const SURFACES = Object.freeze({
 /** Every surface name, sorted for determinism. */
 export const SURFACE_NAMES = Object.freeze(Object.keys(SURFACES).sort());
 
+/**
+ * The surfaces that are ROOM TRAFFIC: the event arrived on a Cohort channel, the
+ * projection stamps a real `channel_id`, and a reply is a message posted back
+ * into that room.
+ *
+ * WHY THIS IS A STRUCTURAL FACT AND NOT A CONVENIENCE LIST. Two mechanisms are
+ * only defined for room traffic, and both used to be decided by a hand-kept list
+ * or by nothing at all:
+ *
+ *   1. REPLY ROUTING. `scripts/daemon/deliver.mjs` kept its own copy of these
+ *      five names (`CHANNEL_SURFACES`) and now derives them from here, so a new
+ *      surface cannot be routed by a list that was never told about it.
+ *   2. THE RESPONDER ELECTION. `messaging.electResponder` is a MESSAGING
+ *      mechanism: it takes `{messageId, channelId}`, loads that Message row and
+ *      that channel's AI roster, and elects one of the seats in the room. A
+ *      surface that is not room traffic has neither id, so the election cannot
+ *      run on it — and, because the election's failure mode is inverted to
+ *      fail-SILENT, running it anyway turns "this is not a message" into "stay
+ *      quiet". That is exactly how 23 document comments were dropped on this
+ *      seat in a day, each one logged as a decision not to answer a message.
+ *
+ * A non-room surface reaches this seat only because `directedness.mjs` PROVED
+ * the address (I own the doc, I am the assignee, the approval is on my desk).
+ * There is no roster to arbitrate and nothing to elect.
+ */
+export const ROOM_SURFACES = Object.freeze(
+  Object.entries(SURFACES)
+    .filter(([, def]) => def.room === true)
+    .map(([name]) => name)
+    .sort(),
+);
+
+/**
+ * Is this surface room traffic?
+ *
+ * UNKNOWN NAMES ANSWER `true`. The caller that asks is deciding whether to SKIP
+ * the responder election, and skipping it for an ambient channel message is the
+ * multi-seat storm this whole mechanism exists to prevent. So an unrecognised
+ * surface keeps the election — the conservative answer — and only the surfaces
+ * this table positively declares non-room are exempted.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isRoomSurface(name) {
+  const def = SURFACES[String(name || "")];
+  return def ? def.room === true : true;
+}
+
 /**
  * The MessageEvent `kind` values these surfaces introduce, beyond the five the
  * channel contract already ships. `lib/channels/contract.mjs` must list them in

package/lib/runtime/adapter.mjs

@@ -207,14 +207,46 @@ export function subscriptionAuth(env) {
  * capture the child's transcript (lib/collective/loop-guard.mjs) — without it,
  * every capture spawns a session whose end spawns another capture.
  */
+/**
+ * The session flag for a `--print` lane, and THE reason this is a function.
+ *
+ * `--session-id <uuid>` means "START a session under this id". The Claude CLI
+ * REFUSES it — `Error: Session ID <uuid> is already in use.`, exit 1, in 0.1s,
+ * before any model call — when a transcript for that id already exists. So the
+ * note these lanes used to carry ("pre-minting + reusing the same UUID across
+ * spawns IS the resume mechanism; never combine --resume with --session-id")
+ * was false, and it was false in the only direction that costs a reply: the
+ * session-router's RESUME decision handed a previously-used id straight back to
+ * `--session-id`, so EVERY resume exited 1 and the reply was dropped. Measured
+ * on this seat: four dropped quick replies 09-22..09-24, one per room per TTL
+ * cycle (the non-zero exit makes the next route EPHEMERAL_REPLACE, which is why
+ * it alternated rather than wedged — and why continuity had in fact never once
+ * worked).
+ *
+ * Continuing an existing transcript is `--resume <uuid>` (`claude --help`:
+ * "continues that session in the background under the same ID, or starts a copy
+ * and says so when the session is already running" — non-fatal either way).
+ * Starting a fresh one under a chosen id is `--session-id <uuid>`. The caller
+ * knows which it has; `resumeSession` is it saying so.
+ *
+ * @param {{sessionId?:string|null, resumeSession?:boolean}} i
+ * @returns {string[]}
+ */
+export function sessionArgs(i = {}) {
+  if (!i.sessionId) return [];
+  return i.resumeSession === true
+    ? ["--resume", String(i.sessionId)]
+    : ["--session-id", String(i.sessionId)];
+}
+
 const LANES = Object.freeze({
   dispatcher: {
     posture: "stock-oauth", stdin: false, retarget: true,
-    argv: (i, x) => ["--print", "--output-format", "json", ...x.settings, ...x.perm, ...x.mcp, ...x.knobs, "--session-id", i.sessionId, "--model", i.model, i.prompt],
+    argv: (i, x) => ["--print", "--output-format", "json", ...x.settings, ...x.perm, ...x.mcp, ...x.knobs, ...sessionArgs(i), "--model", i.model, i.prompt],
   },
   resume: {
     posture: "stock-oauth", stdin: false, retarget: true,
-    argv: (i, x) => ["--print", "--output-format", "json", ...x.settings, ...x.perm, ...x.mcp, ...x.knobs, "--session-id", i.sessionId, "--model", i.model, i.prompt],
+    argv: (i, x) => ["--print", "--output-format", "json", ...x.settings, ...x.perm, ...x.mcp, ...x.knobs, ...sessionArgs(i), "--model", i.model, i.prompt],
   },
   cadence: {
     posture: "cadence", stdin: false, retarget: true,
@@ -222,7 +254,7 @@ const LANES = Object.freeze({
   },
   responder: {
     posture: "stock-oauth", stdin: true, retarget: false,
-    argv: (i, x) => ["--print", ...x.perm, ...x.mcp, "--model", i.model, "--append-system-prompt", i.systemPrompt, "--output-format", "json", ...(i.sessionId ? ["--session-id", i.sessionId] : [])],
+    argv: (i, x) => ["--print", ...x.perm, ...x.mcp, "--model", i.model, "--append-system-prompt", i.systemPrompt, "--output-format", "json", ...sessionArgs(i)],
   },
   classifier: {
     posture: "stock-oauth", stdin: true, retarget: false,
@@ -361,7 +393,10 @@ function laneEnv(spec, i, deps) {
  * @param {string} [i.model]        the --model value
  * @param {string} [i.prompt]       the prompt; argv or stdin per lane
  * @param {string} [i.systemPrompt] --append-system-prompt (responder/classifier/ack/enrich)
- * @param {string} [i.sessionId]    --session-id (dispatcher/resume/responder/main-session)
+ * @param {string} [i.sessionId]    the session uuid (dispatcher/resume/responder/main-session)
+ * @param {boolean} [i.resumeSession] true → `--resume <id>` (continue an existing
+ *                                    transcript); false/absent → `--session-id <id>`
+ *                                    (start a new one under that id). See {@link sessionArgs}.
  * @param {null|"strict"|{source?:string, agentRoot?:string}} [i.mcp] MCP flags
  * @param {string[]} [i.permissions] resolved permission args (lib/session-permissions.mjs)
  * @param {object} [i.knobs]        {maxTurns, effort, agentsJson} router spawn knobs