@cohortapp/agent-sdk 2.18.8 → 2.18.11

package/lib/telemetry/collect.mjs

@@ -140,6 +140,8 @@ import { list as listPresence } from "../collective/presence.mjs";
 import { billableUsd } from "../cost/ledger-row.mjs";
 import { liveClaudeStats } from "../resource-governor.mjs";
 import { agentFirstName } from "../session/identity.mjs";
+import { snapshot as countersSnapshot } from "../diagnostics/counters.mjs";
+import { replyDebtFromCounters } from "../daemon/reply-debt.mjs";
 
 /** Default temperature probe ceiling — used only as a guard in alerts; here we just report. */
 const VALID_STATES = new Set(["active", "idle", "busy", "error", "offline"]);
@@ -1226,6 +1228,7 @@ function instantMs(v) {
 const ATTENTION_WHY = {
   "no-heartbeat": "up, never beaten",
   "stale-heartbeat": "no beat since this launch",
+  "beat-stopped": "beat, then stopped",
 };
 
 /**
@@ -1938,6 +1941,24 @@ export async function collectStatus(o = {}) {
     if (up) machine.upgrade = up;
   } catch { /* no upgrade field */ }
 
+  // 4c-ii. REPLIES THIS SEAT OWED AND DID NOT SEND — `machine.replyDebt`,
+  // absent on a seat that owes nothing today. Three measured paths end the
+  // reply path in nothing (a session-id collision, a scope the seat does not
+  // hold, a CLI stdout that will not parse as the envelope), and all three left
+  // their only trace in a log file and a JSON on this disk. A silence nobody
+  // off the box can count is indistinguishable from a quiet day, which is how
+  // a seat can stop answering people for three days without anything saying so.
+  //
+  // It rides `machine` for the same reason `frontDoor` does: hq's presence.beat
+  // validator keeps `session` strict and `machine` open, so a new seat-level
+  // fact lands without a lock-step hq deploy. Fail-open like every probe here —
+  // an unreadable counters stream drops the field, never the beat.
+  try {
+    const totals = opt.counterTotals !== undefined ? opt.counterTotals : countersSnapshot({ agentRoot: opt.agentRoot });
+    const debt = replyDebtFromCounters(totals || {}, { date: new Date(nowMs).toISOString().slice(0, 10) });
+    if (debt) machine.replyDebt = debt;
+  } catch { /* no replyDebt field */ }
+
   // 4d. WHO is beating — `machine.daemon` {pid, bootAt, uptimeS, sdkVersion,
   // dashboardAt, healthy?, healthReason?}. This is what makes fleet version
   // drift a QUERY instead of an ssh tour: `machine.sdkVersion` is what is
@@ -1968,7 +1989,12 @@ export async function collectStatus(o = {}) {
   if (opt.withAlerts !== false) {
     try {
       const mod = await import("./alerts.mjs");
-      status.alerts = mod.deriveAlerts(status, opt.thresholds) || [];
+      // `nowMs` is handed over, not left to the default: one rule (the front
+      // door) is a DURATION measured against `machine.sessionNote.since`, and
+      // it must be measured against the same instant the rest of this snapshot
+      // was, or a slow collection could date the silence differently from the
+      // note that describes it.
+      status.alerts = mod.deriveAlerts(status, opt.thresholds, nowMs) || [];
     } catch { status.alerts = []; }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.18.8",
+  "version": "2.18.11",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/policies/ai-disclosure.yaml

@@ -74,6 +74,27 @@ posture:
       deployment's own policy requires unprompted disclosure.
     proactive_disclosure: true
     machine_readable_marking: true
+    # WHO THE PROACTIVE DUTY IS OWED TO. Art. 50(1) addresses informing a
+    # person that they are interacting with an AI system. A colleague inside
+    # the deploying organisation — who provisioned the agent, sees an AI badge
+    # beside its name in every surface, and is three hundred messages into a
+    # working thread with it — is not that person.
+    #
+    # Unscoped, this duty made every agent open every post with "Quick note
+    # before we get into it: I'm <name>, an AI assistant working with
+    # <principal>", including mid-thread corrections to their own numbers. That
+    # is not a transparency control; it reads as the agent disclaiming its own
+    # work, and it tells people something they already know in a way that makes
+    # them feel worse about the colleague they are talking to.
+    #
+    # The email footer learned this and was scoped (channels.email.footer_scope,
+    # first_contact_only + external_recipients_only); the identity line never
+    # was. It is the same duty and it takes the same scope.
+    #
+    # The truthfulness invariant is NOT scoped by this and never will be: a
+    # sincere question about the agent's nature is answered plainly on any
+    # message, internal or external, first or thousandth.
+    internal_recipients_exempt: true
 
   # Do not volunteer, but never conceal and always answer truthfully (invariant).
   disclose-on-ask:
@@ -133,10 +154,36 @@ governance:
 # own voice (policies/communication-style.md governs tone — prose, no filler).
 # ───────────────────────────────────────────────────────────────────────────
 channels:
+  # The organisation's own workspace: channels, DMs, threads, boards. Every
+  # member here provisioned these agents or works beside them daily, and the
+  # product marks them structurally — an AI badge on the member row, the
+  # directory, the mailbox list and the composer. That marking is always on and
+  # needs no sentence from the agent.
+  cohort:
+    identity_line: >
+      {agent_name} here — I'm an AI assistant working with {principal_name}.
+    marking:
+      kind: product_badge
+      detail: >
+        Cohort labels every AI member in the UI (member rows, directory,
+        mailbox list, message headers). The marking is structural and
+        unconditional; the identity line is not.
+    identity_scope:
+      first_contact_only: true
+      external_recipients_only: true
+    notes: >
+      In practice this means the line is effectively never used inside the
+      workspace, which is correct: it is for someone meeting the agent for the
+      first time from outside, and Cohort has no such surface today. If one is
+      added, the line is here and already scoped.
+
   slack:
     identity_line: >
       Quick note before we get into it — I'm {agent_name}, an AI assistant
       working with {principal_name}.
+    identity_scope:
+      first_contact_only: true
+      external_recipients_only: true
     marking:
       kind: profile_metadata        # bot/app badge + display-name suffix
       detail: "Display name carries an AI marker; profile states the principal."

package/scripts/daemon/agent-daemon.mjs

@@ -17,6 +17,10 @@
 // =============================================================================
 
 import { resolve, join } from "path";
+import { homedir } from "os";
+import { execFile as _execFileCb } from "child_process";
+import { promisify } from "util";
+const execFileAsync = promisify(_execFileCb);
 import { readdirSync, readFileSync, renameSync, mkdirSync, appendFileSync, writeFileSync, unlinkSync } from "fs";
 import { createRequire } from "module";
 
@@ -63,6 +67,9 @@ import { classifyItem, isDirectedAtAgent } from "./classifier.mjs";
 // gets a deterministic classification (no LLM triage), no holding ack, and a
 // per-seat jitter so thirteen answers do not land in the same second.
 import { isRollCallItem, rollCallJitterMs } from "../../lib/org/inbound/broadcast.mjs";
+import { isRoomSurface } from "../../lib/org/inbound/surfaces.mjs";
+import { isMembershipReason } from "../../lib/org/inbound/directedness.mjs";
+import { cohortSurfaceOf, cohortSurfaceLabel, cohortSurfaceIsDeclared } from "./deliver.mjs";
 import { itemCollectiveIntent } from "../../lib/org/inbound/collective.mjs";
 import { dispatch, getStatus, availableSlots, canDispatchBacklog, resetActiveSessions, yieldBacklogForReactive, linkActiveSessionBoard } from "./dispatcher.mjs";
 import { boardItemRefFor } from "../../lib/session/current-work.mjs";
@@ -132,6 +139,9 @@ import { boardPriority } from "./board-mirror.mjs";
 import { mintTraceId, withTrace } from "../../lib/diagnostics/trace.mjs";
 import { emitEvent, EVENT_TYPES } from "../../lib/diagnostics/events.mjs";
 import * as counters from "../../lib/diagnostics/counters.mjs";
+// Replies this seat owed and did not send, counted where a human can see them
+// (the presence beat) rather than only in a file on this disk.
+import { REPLY_DEBT_COUNTERS, isScopeFault } from "../../lib/daemon/reply-debt.mjs";
 import { getHookBus } from "../../lib/hooks/bus.mjs";
 // EXECUTION LADDER (lib/execution/**). The reactive front of the chain:
 // intake (what surface is this, and is it mine) → match (which compiled
@@ -149,7 +159,8 @@ import { processOne } from "../../lib/execution/pipeline.mjs";
 // of spawning `claude --print`; not live → today's dispatch, unchanged. The
 // gate is pure (lib/session/frontdoor.mjs); the assurance sweep reopens a
 // session claim that was neither replied nor done within 20 min.
-import { makeFrontDoorGate } from "../../lib/session/frontdoor.mjs";
+import { shouldReviveFrontDoor, reviveCommand, sessionJobLabelOnDisk } from "../../lib/session/revive.mjs";
+import { makeFrontDoorGate, sessionLiveFromHeartbeat } from "../../lib/session/frontdoor.mjs";
 import { CADENCE_REGISTRY } from "./cadence-handlers.mjs";
 import { sweepSessionInboxForDaemon } from "../../lib/session/inbox-claims.mjs";
 import { defaultEffects, scheduleToQueue } from "../../lib/execution/effects.mjs";
@@ -263,11 +274,60 @@ async function poll() {
  * on the 60s full poll. Returns the count of new items processed. Never throws.
  */
 const _frontDoorGate = makeFrontDoorGate({ agentRoot: AGENT_REPO_DIR });
+
+// ── REVIVING A SHUT FRONT DOOR ───────────────────────────────────────────────
+//
+// The daemon already reads the front-door state every poll to decide who owns
+// the inbox. It is therefore the one process that watches a session it does not
+// live inside — and that is exactly what a wedged front door needs.
+//
+// The supervisor's own watchdog (2.18.7) cannot help when the supervisor is
+// itself parked in its launch probe waiting on a session that will never report
+// ready: James Kirkland sat that way for 3.5 days and Isla Roselli for 15,
+// through several SDK upgrades, because installing new code does not restart a
+// stuck process. The hourly autoupdate job restarts it (2.18.8) but only once
+// an hour and only on the runs that reach that far. This closes it to a minute.
+//
+// State is per-process and deliberately not persisted: a daemon restart is
+// itself a change of circumstances, and a fresh budget after one is the answer
+// we want rather than a stale count carried across it.
+const _revive = { attempts: 0, lastAt: null };
+async function reviveFrontDoorIfShut(state, deps = {}) {
+  const now = deps.now ? deps.now() : Date.now();
+  const live = sessionLiveFromHeartbeat(state && state.heartbeat, { now });
+  const verdict = shouldReviveFrontDoor({
+    frontDoor: state && state.frontDoor,
+    sessionLive: state && state.sessionLive,
+    silentMs: live.ageMs,
+    attempts: _revive.attempts,
+    lastAttemptAt: _revive.lastAt,
+    now,
+    reviveAfterMs: Number(process.env.MAESTRO_SESSION_STALE_S || 0) * 1000 || undefined,
+  });
+  if (!verdict.revive) return verdict;
+  const label = sessionJobLabelOnDisk(readdirSync, homedir());
+  if (!label) return { revive: false, reason: "no-session-job" };
+  _revive.attempts += 1;
+  _revive.lastAt = now;
+  const cmd = reviveCommand(label, typeof process.getuid === "function" ? process.getuid() : 0);
+  console.error(`[daemon] front door shut — ${verdict.reason}; restarting ${label}`);
+  try {
+    await (deps.execFile || execFileAsync)(cmd.file, cmd.args);
+    console.error(`[daemon] ${label} restarted; a fresh session clears whatever the old one was sitting on`);
+  } catch (err) {
+    console.error(`[daemon] could not restart ${label}: ${err && err.message ? err.message : err} — this seat needs a person`);
+  }
+  return verdict;
+}
+
 async function pollService(svc) {
   try {
     // Front door: a live main session owns this service's inbox — leave it.
     const fd = _frontDoorGate.check(svc.name);
     if (fd.changed) console.log(`[daemon] front door for ${svc.name}: ${fd.dispatch ? "daemon dispatches" : "main session owns intake"} (${fd.reason})`);
+    // A door that is shut is not a door that owns anything. Ask on every poll,
+    // cheap and bounded: the common answer is "answering" off a fresh beat.
+    if (svc.name === "cohort") await reviveFrontDoorIfShut(fd.state).catch(() => {});
     if (!fd.dispatch) return 0;
     const result = await svc.fn();
     // Dedup by raw_ref first: the same Slack message arrives via multiple paths
@@ -499,18 +559,41 @@ function claudeAvailable() {
  * `electedMe:false`. A degraded election must never fall back to respond-to-all —
  * that is the storm this whole change exists to end.
  *
+ * ── WHAT A REASON MEANS, AND WHY `decided` IS ON THE VERDICT ────────────────
+ * Every path below that is not an election result ends in silence too, because
+ * the fail-safe is inverted — but silence-because-hq-picked-someone-else and
+ * silence-because-the-election-could-not-run are different events, and for
+ * months the caller printed both as "not elected to respond". An operator
+ * reading that log saw a decision where there had been an outage, or a missing
+ * id, or an item that was never a message. So the verdict now carries `decided`:
+ * TRUE only when hq actually ran the election and named responders. The caller
+ * logs the two cases in different words.
+ *
  * @param {object} item the (cohort) inbox item
  * @param {object} [deps] { electResponder, orgCfg } injectable seams for tests
- * @returns {Promise<{electedMe:boolean, reason:string, election?:string, mode?:string}>}
+ * @returns {Promise<{electedMe:boolean, decided:boolean, reason:string, election?:string, mode?:string}>}
  */
 async function electResponderVerdict(item, deps = {}) {
   const impl = deps.electResponder || electResponder;
   try {
     const cfg = deps.orgCfg !== undefined ? deps.orgCfg : daemonOrgCfg();
-    if (!orgEnabled(cfg)) return { electedMe: false, reason: "org-disabled" };
+    if (!orgEnabled(cfg)) {
+      return { electedMe: false, decided: false, reason: "org integration disabled — no roster to elect against" };
+    }
     const channelId = cohortChannelId(item);
     const messageId = cohortMessageId(item);
-    if (!channelId || !messageId) return { electedMe: false, reason: "no-message-id" };
+    // A ROOM ITEM MISSING ITS IDS IS A DEFECT, AND THE LOG MUST SAY SO. These
+    // two used to share the single reason "no-message-id", which was wrong on
+    // both counts: it named the message when the CHANNEL was the missing half,
+    // and it was the reason 23 doc comments printed in a day — items that have
+    // no channel id because they are not room traffic and never should have
+    // reached this call at all. That class is now excluded by the caller's
+    // surface gate, so anything landing here genuinely is a room item whose
+    // projection lost an id.
+    if (!channelId || !messageId) {
+      const missing = !channelId && !messageId ? "channel id and message id" : (!channelId ? "channel id" : "message id");
+      return { electedMe: false, decided: false, reason: `room item carries no ${missing} — the election cannot be asked` };
+    }
     const conn = configFromAgent(cfg);
     const res = await impl(
       { messageId, channelId },
@@ -518,9 +601,9 @@ async function electResponderVerdict(item, deps = {}) {
     );
     if (!res || res.error) {
       const reason = res && res.error
-        ? `${res.error.code || "error"}: ${res.error.message || ""}`
-        : "no-response";
-      return { electedMe: false, reason: reason.slice(0, 200) };
+        ? `hq refused the election (${res.error.code || "error"}: ${res.error.message || ""})`
+        : "hq returned no election frame";
+      return { electedMe: false, decided: false, reason: reason.slice(0, 200) };
     }
     const out = res.result !== undefined ? res.result : res;
     const responders = Array.isArray(out && out.responders) ? out.responders : [];
@@ -535,14 +618,40 @@ async function electResponderVerdict(item, deps = {}) {
     const electedMe =
       !!mySlug &&
       responders.some((r) => String((r && r.slug) || "").trim().toLowerCase() === mySlug);
+    // NO SLUG ON RECORD is not an election result: hq may well have elected
+    // somebody, this seat simply cannot tell whether it was itself. Reporting it
+    // as "hq elected another seat" would be an assertion nothing checked.
+    if (!mySlug) {
+      return {
+        electedMe: false,
+        decided: false,
+        reason: "this seat has no org member slug on record — cannot tell whether it was elected",
+        election: out && out.election,
+        mode: out && out.mode,
+      };
+    }
+    const others = responders
+      .map((r) => String((r && r.slug) || "").trim())
+      .filter(Boolean)
+      .slice(0, 5)
+      .join(", ");
     return {
       electedMe,
-      reason: electedMe ? "elected" : "not-elected",
+      decided: true,
+      reason: electedMe
+        ? "hq elected this seat"
+        : others
+          ? `hq elected ${others}`
+          : "hq elected nobody",
       election: out && out.election,
       mode: out && out.mode,
     };
   } catch (err) {
-    return { electedMe: false, reason: `error: ${err && err.message ? err.message : String(err)}`.slice(0, 200) };
+    return {
+      electedMe: false,
+      decided: false,
+      reason: `the election call threw (${err && err.message ? err.message : String(err)})`.slice(0, 200),
+    };
   }
 }
 
@@ -802,25 +911,136 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // twelve seats silent on a message that named all thirteen. The inbound
     // join proved the address (human author, my room, collective marker), so
     // this is not ambient traffic and there is nothing to hold an election over.
+    //
+    // AND IT NEEDS A ROOM. `messaging.electResponder` takes
+    // `{messageId, channelId}`, loads that Message row and that channel's AI
+    // roster, and picks one of the seats IN THE ROOM. A document comment, a
+    // board comment, an approval or a decision names no channel and has no room
+    // roster — there is nobody to elect between. Asking the messaging election
+    // about one produced `no-message-id`, and because this gate's failure mode
+    // is inverted to fail-SILENT, "this is not a message" came out as "stay
+    // quiet": 23 doc comments dropped on this seat in a single day, each one
+    // logged as a decision not to answer a message.
+    //
+    // TWO SEPARATE QUESTIONS, AND THEY MUST NOT BE COLLAPSED INTO ONE. "Is this
+    // surface room traffic?" decides whether an election is the RIGHT mechanism;
+    // "was the address ambient?" decides whether one is NEEDED; "does the item
+    // name a channel?" decides whether one can be ASKED. A personal address on a
+    // non-room surface (I own the doc, I am the assignee, the approval is on my
+    // desk) skips the election because there is nothing to arbitrate. An AMBIENT
+    // address on a non-room surface still wants one — and gets one whenever the
+    // item names a room. `isRoomSurface` answers TRUE for an unknown name, so a
+    // new ambient channel surface keeps the storm gate by default.
     const rollCall = isRollCallItem(item);
-    if (service === "cohort" && !isDm && !rollCall && !isDirectedAtAgent(item)) {
+    const surface = service === "cohort" ? cohortSurfaceOf(item) : "";
+    // The name a PERSON reads. `cohortSurfaceOf` answers for ROUTING, and its
+    // fallback for a legacy `cohort:<channelId>:<messageId>` raw_ref (or a bare
+    // `kind:"message"`, which is what `lib/org/messaging.mjs` stamps) is "dm" —
+    // correct as a route, a lie as a label, and it printed
+    // `Election on dm in channel/roadmap` for an ambient PUBLIC-channel message
+    // in this very lane's test output. `cohortSurfaceLabel` never guesses.
+    const surfaceLabel = service === "cohort" ? cohortSurfaceLabel(item) : "";
+    const surfaceDeclared = service === "cohort" ? cohortSurfaceIsDeclared(item) : false;
+    // THE ADDRESS THE SERVER PROVED OUTRANKS THE LOCAL PROSE HEURISTIC. The
+    // comment above says an @mention or a named address "skips the election
+    // entirely (`isDirectedAtAgent` already decided)" — but `isDirectedAtAgent`
+    // is a SLACK-shaped rule: it matches the seat's configured first name and
+    // Slack member id against the message prose, and knows nothing about a
+    // Cohort mention row. A Cohort @mention whose prose spells the seat
+    // differently (a display name, a surname, a slug) therefore read as
+    // UNDIRECTED and went to an election — one surface's gate judging another
+    // surface's item, which is the same shape as the doc-comment bug above.
+    // `priority_signals.mentions_agent` is the ingest layer's real verdict,
+    // stamped by `lib/org/inbound/project.mjs` only for a genuine dm / mention /
+    // named / direct address, so it is the one to trust here.
+    const provenAddress = service === "cohort" && item.priority_signals && item.priority_signals.mentions_agent === true;
+    const undirectedCohort =
+      service === "cohort" && !isDm && !rollCall && !provenAddress && !isDirectedAtAgent(item);
+    // AMBIENT vs PERSONAL, and whether an election can be ASKED at all. Three
+    // facts, kept separate because they answer different questions:
+    //
+    //   `nonRoom`  — the surface's reply is not a message posted into a room.
+    //   `ambient`  — the address was proved by MEMBERSHIP or VISIBILITY
+    //                (`channel`, `participant`, `shared`), so every seat that
+    //                shares the room or the share holds an equal claim. That is
+    //                what an election is for.
+    //   `roomToArbitrate` — the item names a real Cohort channel, so
+    //                `messaging.electResponder` has a roster to elect from.
+    //
+    // ONLY THE COMBINATION `nonRoom && ambient && !roomToArbitrate` IS A DEAD
+    // END. An ambient non-room item that DOES name a room still goes to the
+    // election, exactly as it did before this change — a comment on a
+    // chat-attached file (`resolveChatFile` → `yes("file_comment","channel")`)
+    // carries its channel id, so hq can arbitrate the room's roster and one
+    // seat can answer. Excluding it unconditionally would have made that class
+    // permanently unanswerable by anybody, which is a behaviour change this
+    // lane never claimed and does not want: if hq cannot resolve the comment id
+    // as a Message the election errors, the inverted fail-safe fires, and the
+    // silence is the same one — so asking costs nothing and can only turn a
+    // never into an answer.
+    const nonRoom = undirectedCohort && !isRoomSurface(surface);
+    const ambient = undirectedCohort && isMembershipReason(item.direct_reason);
+    const roomToArbitrate = Boolean(cohortChannelId(item));
+    if (nonRoom && ambient && !roomToArbitrate) {
+      // AMBIENT, AND NO MECHANISM CAN REACH IT. A doc comment is addressed to
+      // this seat only because the file is SHARED with it — a visibility fact a
+      // whole channel can hold at once — but the reply is an RPC against a file
+      // id, there is no Message row and no channel id, and
+      // `messaging.electResponder` has nothing to be asked about. So the seat
+      // stays silent, and the log says THAT: a missing mechanism, not a
+      // decision. Arbitration for ambient non-room surfaces is a real gap; it
+      // needs a server-side election keyed on the entity, not a local guess.
+      console.log(`[daemon] No arbitration exists for an ambient ${surfaceLabel} item (addressed by ${item.direct_reason || "membership"}, it names no room, and the responder election is messaging-only) — staying silent (gap, not a decision; from ${item.sender})`);
+      logEvent("classifications", {
+        item_id: itemId,
+        sender: item.sender,
+        service,
+        surface,
+        surface_declared: surfaceDeclared,
+        skipped: true,
+        reason: `no_arbitration_for_ambient_surface: ${surface}`,
+        direct_reason: item.direct_reason || null,
+        summary: classResult.summary,
+      });
+      markProcessed(item, service);
+      return { ok: true, path: "filtered", reason: "no_arbitration_for_ambient_surface" };
+    } else if (nonRoom && !ambient) {
+      console.log(`[daemon] No election on a ${surfaceLabel} item — it is not room traffic and the inbound join already proved it is addressed here (${item.direct_reason || "addressed"}); handling it on its own surface (from ${item.sender})`);
+    } else if (undirectedCohort) {
       const verdict = await _electResponderVerdict(item);
       if (!verdict.electedMe) {
-        console.log(`[daemon] Election: not elected to respond (${verdict.reason}) — staying silent for ${item.sender} in ${item.channel}`);
+        // TWO DIFFERENT EVENTS, TWO DIFFERENT SENTENCES. `decided` is true only
+        // when hq ran the election and named responders; everything else is the
+        // fail-safe firing on an outage or a malformed item, and calling that a
+        // decision is how an outage reads as normal operation in the log.
+        console.log(
+          verdict.decided
+            ? `[daemon] Election on ${surfaceLabel} in ${item.channel}: ${verdict.reason} — this seat stays silent (from ${item.sender})`
+            : `[daemon] Election on ${surfaceLabel} in ${item.channel} could not be decided: ${verdict.reason} — staying silent (fail-safe, not a decision; from ${item.sender})`,
+        );
         logEvent("classifications", {
           item_id: itemId,
           sender: item.sender,
           service,
+          surface,
+          surface_declared: surfaceDeclared,
           skipped: true,
-          reason: `not_elected: ${verdict.reason}`,
+          reason: verdict.decided
+            ? `election_elected_another: ${verdict.reason}`
+            : `election_undecided: ${verdict.reason}`,
+          election_decided: verdict.decided === true,
           election: verdict.election || null,
           mode: verdict.mode || null,
           summary: classResult.summary,
         });
         markProcessed(item, service);
-        return { ok: true, path: "filtered", reason: "not_elected" };
+        return {
+          ok: true,
+          path: "filtered",
+          reason: verdict.decided ? "election_elected_another" : "election_undecided",
+        };
       }
-      console.log(`[daemon] Election: elected to respond (${verdict.election || "elected"}, mode=${verdict.mode || "?"}) for ${item.sender} in ${item.channel}`);
+      console.log(`[daemon] Election on ${surfaceLabel} in ${item.channel}: ${verdict.reason} (${verdict.election || "elected"}, mode=${verdict.mode || "?"}) — answering ${item.sender}`);
     }
 
     // DIRECTED-MESSAGE GATE: In channels and group chats, only respond to
@@ -1046,6 +1266,32 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
       // the forbidden one); the escalation is the trace that a human must act.
       if (result.permanent) {
         const cause = result.code || result.error || "permanent send failure";
+        // A SCOPE REFUSAL IS A CONFIGURATION FAULT AND SOMEBODY ELSE'S TO FIX.
+        // Everything below this line is correct and stays — the ask is not
+        // lost, the obligation is durable, an operator can sweep
+        // state/obligations/needs-attention. But all of it is on THIS DISK. The
+        // measured case (2026-09-22, doc comment on a file this seat may not
+        // comment on) produced three log lines and one JSON file, and nothing
+        // off the box ever said the seat was missing a scope. A person would
+        // have to already suspect this seat to go and look, which is the same
+        // silence in a nicer folder.
+        //
+        // So a scope fault is also COUNTED, and the count rides the presence
+        // beat (lib/telemetry/collect → machine.replyDebt → the
+        // `seat_missing_scope` alert). Counting rather than sending: the only
+        // channel we had was the forbidden one, and the seat cannot know which
+        // other room would reach the right human. What it CAN do is stop being
+        // the only thing that knows.
+        //
+        // Falling through to a session is still refused, for the reason below:
+        // a denied session runs autonomously and improvises unrelated work into
+        // a channel this seat was just told it may not write to.
+        if (isScopeFault(result.code)) {
+          counters.bump(REPLY_DEBT_COUNTERS.scopeRefused, {
+            service, sender: item.sender || "unknown",
+            channel: item.channel_id || item.channel || "none",
+          });
+        }
         console.error(`[daemon] Quick reply PERMANENTLY failed for ${item.sender} (${cause}) — NOT spawning a session; opening obligation + escalating`);
         let obligationKey = itemId;
         try {
@@ -1061,6 +1307,7 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
             channel: item.channel_id || item.channel || null,
             summary: classResult && classResult.summary, openedAt: Date.now(),
             attempts: 1, sessionId: null, traceId: trace_id, lastError: cause,
+            configFault: isScopeFault(result.code) ? "missing-scope" : null,
             item: { content: item.content } },
           { failure: { label: cause }, told: false },
         );

package/scripts/daemon/assurance.mjs

@@ -1556,6 +1556,11 @@ export function escalate(rec, o = {}) {
       failedAt: new Date(Number.isFinite(o.now) ? o.now : Date.now()).toISOString(),
       cause: o.failure ? o.failure.label : (rec.lastError || "unknown"),
       requesterWasTold: !!o.told,
+      // WHO has to act. A transport failure is this seat's own problem and the
+      // sweep retries it; a scope fault is a configuration the seat cannot
+      // grant itself, so the row says so in a word an operator can grep rather
+      // than leaving them to infer it from `cause`.
+      configFault: rec.configFault || null,
       attempts: rec.attempts || 0,
       sessionId: rec.sessionId || null,
       traceId: rec.traceId || null,

package/scripts/daemon/deliver.mjs

@@ -34,7 +34,7 @@ import { recordOutbound } from "../../lib/comms/receipts.mjs";
 // Pure data (a frozen table, no imports of its own) — the surface vocabulary the
 // inbound projection stamps into `raw_ref`. Imported rather than re-listed so a
 // new surface cannot be added upstream without this file's switch noticing.
-import { SURFACE_NAMES } from "../../lib/org/inbound/surfaces.mjs";
+import { ROOM_SURFACES, SURFACE_NAMES } from "../../lib/org/inbound/surfaces.mjs";
 
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 
@@ -117,11 +117,17 @@ export function resolveSlackChannel(item) {
  * correct case for it.
  */
 
-/** Surfaces that genuinely live in a Cohort room — these reply with a message. */
-// `broadcast` is a room message like a mention: the roll-call answer posts
-// into the space it was asked in. Without this entry the reply has no
-// transport, `canDeliverTo` says no, and the surface is dark at the last step.
-const CHANNEL_SURFACES = Object.freeze(["dm", "mention", "broadcast", "thread_reply", "call"]);
+/**
+ * Surfaces that genuinely live in a Cohort room — these reply with a message.
+ *
+ * DERIVED, not re-typed. This was a hand-kept copy of five names, and a
+ * hand-kept copy is a list that can be forgotten: `broadcast` had to be added
+ * here by hand when the roll-call surface landed, and until it was, the reply
+ * had no transport, `canDeliverTo` said no, and the surface was dark at the last
+ * step. `surfaces.mjs` now carries `room` as a per-surface fact and this reads
+ * it, so a new room surface is routable the moment it is declared.
+ */
+const CHANNEL_SURFACES = ROOM_SURFACES;
 
 /**
  * Error frame codes a retry cannot change.
@@ -174,17 +180,77 @@ function entityFromRawRef(item) {
  */
 export function cohortSurfaceOf(item) {
   if (!item) return "";
-  // Guarded against the LEGACY raw_ref shape, which is `cohort:<channelId>:
-  // <messageId>` — still on disk today. An all-lowercase channel id would
-  // otherwise parse as a surface name and route a working DM to nowhere.
-  const m = /^cohort:([a-z_]+):/.exec(str(item.raw_ref));
-  if (m && SURFACE_NAMES.includes(m[1])) return m[1];
+  const declared = declaredSurface(item);
+  if (declared) return declared;
   const kind = str(item.kind);
   if (kind === "file_comment") return str(item.channel_id) ? "file_comment" : "doc_comment";
   if (!kind || kind === "message") return "dm";
   return kind;
 }
 
+/**
+ * The surface name `project.mjs` DECLARED in `raw_ref`, or "" when it declared
+ * none.
+ *
+ * Guarded against the LEGACY raw_ref shape, which is `cohort:<channelId>:
+ * <messageId>` — still on disk today, and still what `lib/org/messaging.mjs`
+ * stamps. An all-lowercase channel id would otherwise parse as a surface name
+ * and route a working DM to nowhere.
+ */
+function declaredSurface(item) {
+  const m = /^cohort:([a-z_]+):/.exec(str(item && item.raw_ref));
+  return m && SURFACE_NAMES.includes(m[1]) ? m[1] : "";
+}
+
+/**
+ * Did `raw_ref` actually DECLARE this item's surface, or was it inferred?
+ *
+ * Worth recording next to a logged surface: an inferred one is a guess made
+ * from `kind` / `channel_kind`, and an operator reading the row later should be
+ * able to tell the two apart without re-deriving it.
+ *
+ * @param {object} item
+ * @returns {boolean}
+ */
+export function cohortSurfaceIsDeclared(item) {
+  return declaredSurface(item) !== "";
+}
+
+/**
+ * How to NAME this item's surface in a line a person reads.
+ *
+ * ── WHY THIS IS NOT `cohortSurfaceOf` ──
+ * Because that function's job is ROUTING, and for routing its fallbacks are
+ * right: an item with the legacy `cohort:<channelId>:<messageId>` raw_ref, or
+ * bare `kind:"message"`, replies with a message posted into `channel_id`, which
+ * is precisely what the `dm` branch does. But "dm" is then a ROUTE, not a
+ * claim about where the message was written — and a log line that prints it
+ * tells an operator "dm" about a message in a PUBLIC channel. The lane that
+ * added these lines to make the log truthful hit exactly that in its own test
+ * output: `Election on dm in channel/roadmap`.
+ *
+ * So the label is derived separately and never guesses: a declared surface is
+ * used verbatim; otherwise `channel_kind` (which hq stamps on the narrow reader)
+ * names the room; otherwise the item's own `is_dm`; otherwise it says plainly
+ * that the surface was never declared, rather than inventing one.
+ *
+ * @param {object} item
+ * @returns {string}
+ */
+export function cohortSurfaceLabel(item) {
+  if (!item) return "unknown surface";
+  const declared = declaredSurface(item);
+  if (declared) return declared;
+  const kind = str(item.kind);
+  if (kind === "file_comment") return str(item.channel_id) ? "file_comment" : "doc_comment";
+  if (kind && kind !== "message") return kind;
+  const channelKind = str(item.channel_kind).toUpperCase();
+  if (channelKind === "DM") return "dm";
+  if (channelKind) return `${channelKind.toLowerCase()} channel message`;
+  if (item.is_dm === true) return "dm";
+  return "message (surface not declared in raw_ref)";
+}
+
 /**
  * Where a reply to this Cohort item goes — a pure function of the item, so it
  * can be asked BEFORE anything is promised (see `canDeliverTo`).
@@ -766,5 +832,7 @@ export default {
   canDeliverTo,
   cohortReplyRoute,
   cohortSurfaceOf,
+  cohortSurfaceLabel,
+  cohortSurfaceIsDeclared,
   DELIVERABLE_SERVICES,
 };