@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/scripts/daemon/agent-daemon.mjs

@@ -18,6 +18,7 @@
 
 import { resolve, join } from "path";
 import { readdirSync, readFileSync, renameSync, mkdirSync, appendFileSync, writeFileSync, unlinkSync } from "fs";
+import { createRequire } from "module";
 
 // Load .env before anything else. dotenv is present on every agent machine but
 // is not a packaged dependency, so we import it dynamically + best-effort: this
@@ -57,7 +58,14 @@ import { makeInboxScanPoller } from "../poller/inbox-scan-poller.mjs";
 import { existsSync as _existsSync } from "fs";
 import { isPriorityItem } from "../poller/utils.mjs";
 import { classifyItem, isDirectedAtAgent } from "./classifier.mjs";
-import { dispatch, getStatus, availableSlots, canDispatchBacklog, resetActiveSessions, yieldBacklogForReactive } from "./dispatcher.mjs";
+// A human's roll-call to the whole room ("everyone, status?"). Every addressed
+// seat answers for itself — so it is EXEMPT from the single-winner election,
+// 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 { 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";
 import { markReactiveStart, markReactiveEnd } from "../../lib/reactive-gate.mjs";
 import { buildPrompt } from "./prompt-builder.mjs";
 import { sendQuickResponse, sendHoldingMessage, isQuickReply } from "./responder.mjs";
@@ -93,7 +101,7 @@ const RUNG_MECHANISM = Object.fromEntries(RUNGS.map((r) => [r.id, r.mechanism]))
 // work and land it in the org's shared, ACL'd store so the fleet's memory
 // compounds. Fail-open + best-effort — never blocks or throws into the hot path;
 // local SQLite/interaction logs remain the fail-open cache.
-import { isEnabled as orgEnabled, loadOrgConfig, configFromAgent, electResponder, fetchSelfProfile, listMineResult as orgListMineResult } from "../../lib/org/client.mjs";
+import { isEnabled as orgEnabled, loadOrgConfig, configFromAgent, electResponder, fetchSelfProfile, listMineResult as orgListMineResult, call as orgCall } from "../../lib/org/client.mjs";
 // board.mine cache (design §3.5, WP-M6): the daemon writes state/org/board-mine.json
 // every 5 min; the SessionStart primer, session_status and `maestro board mine`
 // read it. The when/what is pure (lib/org/board-mine-cache.mjs); the I/O is here.
@@ -109,6 +117,9 @@ import { recordWorkStep as orgRecordWorkStep, cohortChannelId, cohortMessageId }
 // it: a holding "let me look into it" must not go out when the reply itself can
 // never be generated (the storm's other half — a promise the seat cannot keep).
 import { resolveClaudeBin, isSafeExecutable } from "../../lib/claude-bin.mjs";
+// W4 integration (conformance row 1): an engine-cohort seat never spawns claude, so its
+// presence check is the engine entry point, not the claude binary.
+import { readSeatEngine as _seatEngineForAvailability, seatGenerationAvailable as _seatGenerationAvailable, ENGINE_CLI_PATH as _ENGINE_CLI_PATH } from "../../lib/runtime/adapter.mjs";
 import { boardPriority } from "./board-mirror.mjs";
 // Observability spine (WS — diagnostics). mintTraceId + withTrace give each
 // inbound item ONE trace_id that deep callees inherit via AsyncLocalStorage;
@@ -139,6 +150,7 @@ import { processOne } from "../../lib/execution/pipeline.mjs";
 // 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 { CADENCE_REGISTRY } from "./cadence-handlers.mjs";
 import { sweepSessionInboxForDaemon } from "../../lib/session/inbox-claims.mjs";
 import { defaultEffects, scheduleToQueue } from "../../lib/execution/effects.mjs";
 import { loadReactObligations } from "../../lib/execution/match.mjs";
@@ -459,13 +471,17 @@ export function enrichItem(item, service) {
  * @returns {boolean}
  */
 function claudeAvailable() {
-  try {
-    const bin = resolveClaudeBin();
-    if (!bin || bin === "claude") return false; // bare fallback = nothing found
-    return isSafeExecutable(bin);
-  } catch {
-    return false;
-  }
+  let engine = "claude";
+  try { engine = _seatEngineForAvailability(AGENT_REPO_DIR); } catch { engine = "claude"; /* unreadable config: the default engine */ }
+  return _seatGenerationAvailable({
+    engine,
+    claudeBinOk: () => {
+      const bin = resolveClaudeBin();
+      if (!bin || bin === "claude") return false; // bare fallback = nothing found
+      return isSafeExecutable(bin);
+    },
+    engineCliPresent: () => _existsSync(_ENGINE_CLI_PATH),
+  });
 }
 
 /**
@@ -553,15 +569,113 @@ const FASTPATH_WORK_RE = /\b(analy[sz]e|create|build|writ(e|ing)|draft|prepare|r
 // A DM that reads like a question / greeting / quick ask — safe to answer directly.
 const FASTPATH_ASK_RE = /(\?|^(what|how|when|where|who|why|which|is |are |was |were |do |did |does |can |could |would |will |have |has |should |hey|hi |hello|thanks|thank you|yo |quick (q|question)|you (there|around|up)))/i;
 
+/**
+ * Resolve the sender_privilege band handed to the classifier.
+ *
+ * A populated band from upstream wins. The inbox-item writer defaults a
+ * missing band to the string "unknown" (lib/channels/inbox-item.mjs), so
+ * "unknown" is treated as a miss, and only then does the CEO priority signal
+ * decide between "ceo" and "unknown".
+ *
+ * The previous inline form was
+ *   `item.sender_privilege || item.priority_signals?.from_ceo ? "ceo" : "unknown"`
+ * which parses as `(a || b) ? "ceo" : "unknown"`: every non-empty band —
+ * including the default "unknown" — resolved to "ceo", and the classifier
+ * escalated the item as if the CEO had sent it.
+ *
+ * @param {object} item
+ * @returns {string}
+ */
+export function resolveSenderPrivilege(item) {
+  const band = item?.sender_privilege;
+  if (band && band !== "unknown") return band;
+  return item?.priority_signals?.from_ceo ? "ceo" : "unknown";
+}
+
 /**
  * Decide whether a directed DM is a "plainly simple question" that can skip the
  * LLM classifier and be answered directly. Returns a default classResult (the
  * quick-reply shape) when it qualifies, else null (→ full classify path).
  * Deliberately CONSERVATIVE: 1:1 DM, short, question-shaped, no work-verbs.
- * `deps.fastPathClassify` can override (tests); `deps.disableFastPath` disables.
+ * `deps.fastPathClassify` can override (tests); `deps.disableFastPath` (or
+ * DAEMON_DISABLE_FASTPATH=1) disables the DM heuristic — NOT the roll-call
+ * branch, which is deterministic and is checked before the switch.
+ */
+/**
+ * The identity string that makes this seat's roll-call jitter DIFFERENT from
+ * every other seat's: the org member slug (COHORT_AGENT_ID / config
+ * org.cohort.agentId), falling back to the configured first name. Empty only
+ * on an unconfigured seat, where every seat would share a key — harmless
+ * (they still wait), just not spread.
  */
+function rollCallSeatKey(deps = {}) {
+  try {
+    const cfg = deps.orgCfg !== undefined ? deps.orgCfg : daemonOrgCfg();
+    return String(
+      process.env.COHORT_AGENT_ID ||
+        (cfg && cfg.org && cfg.org.cohort && cfg.org.cohort.agentId) ||
+        (loadAgent().firstName || ""),
+    ).trim().toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
 export function fastPathClassify(item, isDm, deps = {}) {
   if (deps && typeof deps.fastPathClassify === "function") return deps.fastPathClassify(item, isDm);
+  // A COLLECTIVE ADDRESS is classified deterministically. The inbound join
+  // already proved the four broadcast conditions (human author, my room, not
+  // threaded, collective address) before it stamped the kind, and the answer
+  // shape is fixed (≤ 5 lines, for myself). Sending it through the LLM
+  // classifier would only add ~5-8 s and a chance of "archive" — the exact
+  // silence this surface exists to end, and one that would now also swallow a
+  // work ask carrying a deadline. `answerable + respond` routes it to the
+  // in-process quick-reply responder, which is where the collective block is
+  // injected.
+  //
+  // This branch sits ABOVE the fast-path kill switches on purpose. The
+  // switches (`deps.disableFastPath`, DAEMON_DISABLE_FASTPATH=1) exist to
+  // force a plain DM through the full LLM classify path when the heuristic
+  // regexes below misjudge one; a roll-call is not a heuristic call — its
+  // conditions were proven upstream — so routing it to the classifier under
+  // the switch would re-open the "archive" hole the branch closes. Pinned by
+  // the "ROLL-CALL: survives the fast-path kill switch" test.
+  if (isRollCallItem(item)) {
+    // WHICH KIND of collective address this is (`lib/org/inbound/collective.mjs`,
+    // the twin of hq's `work/collective.ts`). It does NOT change the ROUTE —
+    // every one of the three still takes the quick path — it changes the
+    // prompt block and the summary line.
+    //
+    // ── WHY A WORK BROADCAST DOES NOT SPAWN THIRTEEN SESSIONS ─────────────
+    //
+    // "Everyone, please review the binder by Friday" is real work for thirteen
+    // seats, and the tempting move is to dispatch a session per seat. That is
+    // thirteen fifteen-to-forty-minute Claude runs fired by one sentence, on
+    // thirteen machines, inside one poll tick — the storm shape this daemon has
+    // been burned by before, bought for an ask with a Friday deadline.
+    //
+    // The proportionate answer is the one the org already has: the quick reply
+    // says what this seat will do and by when, and the SAME quick path's
+    // `trackWorkStep` opens the seat's OWN board row (hq's gate accepts it now
+    // that the audience travels as a fact — see lib/org/work-ledger.mjs). The
+    // row is then pulled through the ordinary board-work lane, which is rate-
+    // controlled, resumable, and visible. A broadcast makes work VISIBLE AND
+    // OWNED here; it does not make thirteen machines start at once.
+    const intent = itemCollectiveIntent(item, isRollCallItem) || "roll-call";
+    const label = intent === "work" ? "Everyone-work" : intent === "ambient" ? "Everyone" : "Roll-call";
+    return {
+      priority: "normal",
+      action: "respond",
+      model: "sonnet",
+      summary: `${label}: ${String(item.content || item.subject || "").slice(0, 80)}`,
+      category: "action_required",
+      directed_at_agent: true,
+      answerable: true,
+      fast_path: true,
+      roll_call: true,
+      collective_intent: intent,
+    };
+  }
   if (deps && deps.disableFastPath) return null;
   if (process.env.DAEMON_DISABLE_FASTPATH === "1") return null;
   if (!isDm) return null;                                   // 1:1 DMs only (never group/ambient)
@@ -627,12 +741,12 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     let classResult = fastPathClassify(item, isDm, deps);
     if (classResult) {
       recordClassification(true);
-      console.log(`[daemon] fast-path DM — skipped classify (${classResult.model}): ${classResult.summary}`);
+      console.log(`[daemon] fast-path ${classResult.roll_call ? "roll-call" : "DM"} — skipped classify (${classResult.model}): ${classResult.summary}`);
     } else {
       // Classify via Haiku CLI
       classResult = await _classify({
         sender: item.sender || "unknown",
-        sender_privilege: item.sender_privilege || item.priority_signals?.from_ceo ? "ceo" : "unknown",
+        sender_privilege: resolveSenderPrivilege(item),
         channel: item.channel || "unknown",
         service,
         content: item.content || item.subject || "",
@@ -681,7 +795,15 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // respond-to-all. The directed fast path is untouched, so an org outage can
     // never drop a genuinely-directed DM. Slack keeps its own local gate below,
     // where no org roster exists to elect against.
-    if (service === "cohort" && !isDm && !isDirectedAtAgent(item)) {
+    //
+    // A ROLL-CALL IS EXEMPT. The election elects ONE responder for an ambient
+    // message; a human's "everyone, status?" is the opposite — every addressed
+    // member owes its own line, and reducing it to a single winner would leave
+    // 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.
+    const rollCall = isRollCallItem(item);
+    if (service === "cohort" && !isDm && !rollCall && !isDirectedAtAgent(item)) {
       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}`);
@@ -834,6 +956,26 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // path does not have, so a quick reply would be a wrong answer delivered
     // fast. With no routing decision (an item the ladder could not place) this
     // is exactly today's behaviour.
+    // ROLL-CALL RATE SHAPING. Thirteen seats received the same event in the
+    // same poll tick; without this their answers land in the same second and
+    // the room reads as a machine chorus. Each seat waits a deterministic slice
+    // of a 0-20 s window keyed on (seat, channel, message) — the same seat
+    // re-answering after a crash waits the same amount, and no two seats share
+    // a key. Applied to BOTH reply paths (quick reply here, session below).
+    let rollCallDelayMs = 0;
+    if (rollCall) {
+      rollCallDelayMs = rollCallJitterMs({
+        seat: rollCallSeatKey(deps),
+        channelId: item.channel_id || item.channel || "",
+        messageId: cohortMessageId(item) || item.id || "",
+      });
+      const _sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+      if (rollCallDelayMs > 0) {
+        console.log(`[daemon] roll-call: waiting ${rollCallDelayMs}ms before answering in ${item.channel} (rate shaping)`);
+        await _sleep(rollCallDelayMs);
+      }
+    }
+
     if (_isQuickReply(classResult, routed)) {
       console.log(`[daemon] Quick reply path for ${item.sender} (${classResult.model})`);
       // Free the subscription NOW: evict any already-running backlog sessions
@@ -859,6 +1001,29 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
         // created and closed in the same instant claims the ask was delivered by
         // a message; leaving it open is the truthful reading, and the stable
         // askKey means whatever really finishes it closes THIS row.
+        //
+        // THIS IS ALSO THE COLLECTIVE PATH. A work-shaped broadcast is answered
+        // here and gets its row here — one per addressee, keyed on the calling
+        // seat server-side, tagged into the channel exactly once across all of
+        // them. A roll-call reaches the same call and is refused by name
+        // (`collective-roll-call`), which is the gate working, not a miss.
+        //
+        // ── AND IT IS ONLY ONE OF THE TWO PLANES. SAY SO. ─────────────────
+        //
+        // Everything in this function is downstream of `answerItem`, which is
+        // only ever reached through `pollService` — and `pollService` returns 0
+        // at its third line (`if (!fd.dispatch) return 0`) whenever
+        // `makeFrontDoorGate` says a live main session owns this service's
+        // inbox. That is the NORMAL state of a healthy seat, and it is the same
+        // fork the 13-day board blackout hid behind: a test that calls
+        // `answerItem` directly is green over a path production does not take.
+        //
+        // On a front-door seat the item never reaches here at all. It becomes
+        // an `inbound` feed line (lib/session/feed-core.mjs), which is why that
+        // line now carries `collective` — the session reads the same verdict
+        // this branch computed and opens its own row per `inbound-triage`
+        // §"Addressed to the whole room". Two planes, one classifier, and
+        // neither of them silently inert.
         void trackWorkStep({
           item,
           stage: "accepted",
@@ -1038,7 +1203,9 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // (the old board mirror) came to exist. Chained rather than fired in
     // parallel because `triage` is not terminal: an `accepted` that commits
     // AFTER a `working` drags the row back out of `running` for good.
-    void trackWorkStep({
+    const _trackWorkStep = deps.trackWorkStep || trackWorkStep;
+    const _linkSessionToBoardRow = deps.linkSessionToBoardRow || linkSessionToBoardRow;
+    void _trackWorkStep({
       item,
       stage: "accepted",
       deferred: true,
@@ -1046,13 +1213,23 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
       note: classResult && classResult.summary ? `Picked this up. ${classResult.summary}` : "Picked this up — starting work now.",
       source: { service, trace_id, classified: String(classResult && classResult.action) },
     }).then(() =>
-      trackWorkStep({
+      _trackWorkStep({
         item,
         stage: "working",
         deferred: true,
         source: { service, trace_id },
       }),
-    );
+    ).then((res) => {
+      // THE LINK BACK. hq's row id reaches the live session's active.json entry,
+      // so a "what are you doing right now?" reply can cite the board item a
+      // person could open — instead of a session that knows it is working and
+      // a board that knows what on, with nothing joining the two.
+      _linkSessionToBoardRow(item, res);
+    }).catch((err) => {
+      // The chain is fire-and-forget; a rejection here must be a log line, not
+      // an unhandled rejection that takes the daemon down.
+      console.warn(`[board] track chain failed: ${err && err.message}`);
+    });
 
     // Build prompt with holding message context and dispatch
     const prompt = await buildPrompt(item, classResult, {
@@ -1796,6 +1973,92 @@ export function _resetDaemonOrgCfgCache() {
   _cachedDaemonOrgCfg = undefined;
 }
 
+/**
+ * Startup guard: a cadence with a producer but no prompt file dead-letters on
+ * every tick, identically, forever. A cadence resolves to `mode: escalate` /
+ * `guarded` with a prompt path via config/.cadence-registry.json, or via the
+ * "conventional" schedules/triggers/<id>.md that cadence-consumer.mjs's
+ * getCadenceDef() falls back to for an unknown id; when that file is absent
+ * the tick can never be rendered, and the DLQ refills — 42 times on the seat
+ * this was written on (ib-2026-09-03-eight-cadences-fire-with-no-prompt-file).
+ * Ported from that seat's fork 2026-09-22.
+ *
+ * CADENCE_REGISTRY (the hardcoded, code-reviewed map in cadence-handlers.mjs)
+ * is deliberately EXCLUDED: getCadenceDef() checks it first and it wins, so an
+ * entry there with no `prompt` (skill-curator, nightly-backup — inline handlers
+ * or guards documented as "never escalates") is by design, not a defect.
+ * Checking config/cadences.yaml directly would false-positive on exactly these,
+ * since that compiled file still carries a `prompt:` for every id.
+ *
+ * Sources checked (both are inputs to what actually resolves at tick time):
+ *   - config/.cadence-registry.json — the compiled config-driven registry
+ *     getCadenceDef() reads once CADENCE_REGISTRY misses.
+ *   - config/plan.yaml — active SCHEDULE obligations feed resolveCadences()'s
+ *     obligations leg directly (lib/cadences.mjs), independent of the JSON
+ *     registry, which is how a cadence kept firing with no plist at all.
+ *
+ * Fail-open throughout: a read/parse failure logs a warning and is skipped,
+ * never blocks daemon startup. Logs once, at boot; returns the ids so a test
+ * (and doctor) can read the answer without the log.
+ * @param {{agentRoot?:string, registry?:object}} [deps] test seams
+ * @returns {string[]} cadence ids whose prompt file is missing
+ */
+export function assertCadencePromptsExist(deps = {}) {
+  const root = deps.agentRoot || AGENT_REPO_DIR;
+  const hardcoded = deps.registry || CADENCE_REGISTRY;
+  const candidates = new Map(); // id -> prompt path (repo-relative)
+
+  try {
+    const registryPath = join(root, "config", ".cadence-registry.json");
+    if (_existsSync(registryPath)) {
+      const registry = JSON.parse(readFileSync(registryPath, "utf-8")) || {};
+      for (const [id, entry] of Object.entries(registry)) {
+        if (hardcoded[id]) continue; // hardcoded handler wins — trust it
+        candidates.set(id, (entry && entry.prompt) || `schedules/triggers/${id}.md`);
+      }
+    }
+  } catch (err) {
+    console.warn(`[daemon] cadence prompt assertion: could not read .cadence-registry.json (${err && err.message ? err.message : err})`);
+  }
+
+  try {
+    const planPath = join(root, "config", "plan.yaml");
+    if (_existsSync(planPath)) {
+      const plan = yamlLoadSync(readFileSync(planPath, "utf-8"));
+      for (const ob of Array.isArray(plan && plan.obligations) ? plan.obligations : []) {
+        if (ob.kind !== "SCHEDULE" || !ob.cadence_id) continue;
+        if (ob.status && ob.status !== "active") continue;
+        if (hardcoded[ob.cadence_id]) continue; // hardcoded handler wins — trust it
+        candidates.set(ob.cadence_id, ob.prompt || `schedules/triggers/${ob.cadence_id}.md`);
+      }
+    }
+  } catch (err) {
+    console.warn(`[daemon] cadence prompt assertion: could not read plan.yaml (${err && err.message ? err.message : err})`);
+  }
+
+  const missing = [];
+  for (const [id, prompt] of candidates) {
+    if (!_existsSync(join(root, prompt))) missing.push(id);
+  }
+  if (missing.length > 0) {
+    console.warn(
+      `[daemon] ${missing.length} cadence(s) have a producer but no prompt file — every tick will dead-letter: ${missing.sort().join(", ")}`
+    );
+  }
+  return missing;
+}
+
+let _yamlLoadSyncCache = null;
+function yamlLoadSync(text) {
+  if (!_yamlLoadSyncCache) {
+    // require() rather than a dynamic import keeps this assertion synchronous
+    // so it can run inline at the top of main(), before the first poll —
+    // js-yaml ships a CJS build so this resolves cleanly.
+    _yamlLoadSyncCache = createRequire(import.meta.url)("js-yaml");
+  }
+  return _yamlLoadSyncCache.load(text);
+}
+
 /**
  * Refresh state/org/board-mine.json from hq `board.mine` when the cache is
  * 5 min old (or absent). Fail-open end to end: an un-enrolled seat writes
@@ -1987,6 +2250,87 @@ export async function trackWorkStep(a = {}) {
   }
 }
 
+/**
+ * Join hq's board row to the daemon session working the same ask (dispatcher
+ * `linkActiveSessionBoard`), so the current-work block names the item. Pure
+ * over its arguments except for the one active.json rewrite the dispatcher
+ * does; fail-open; `linkImpl` is the test seam.
+ *
+ * @param {object} item the inbox item the row was tracked for
+ * @param {object} res the `working` trackWorkStep result
+ * @param {{linkImpl?:Function}} [deps]
+ * @returns {{linked:boolean, sessionId:string|null, parked:boolean}|null} null when there was nothing to link
+ */
+export function linkSessionToBoardRow(item, res, deps = {}) {
+  try {
+    if (!res || !res.tracked || !res.taskId) return null;
+    const channelId = cohortChannelId(item);
+    const messageId = cohortMessageId(item);
+    if (!channelId || !messageId) return null;
+    const impl = deps.linkImpl || linkActiveSessionBoard;
+    const out = impl({ channelId, messageId }, { taskId: res.taskId, col: res.col || null });
+    if (out && (out.linked || out.parked)) {
+      console.log(`[board] task ${res.taskId} ${out.linked ? `linked to session ${out.sessionId}` : "parked until its session registers"}`);
+    }
+    return out || null;
+  } catch (err) {
+    console.warn(`[board] link to session failed: ${err && err.message}`);
+    return null;
+  }
+}
+
+/**
+ * WORK VISIBILITY for a BACKLOG session that is for a BOARD ITEM. An inbox ask
+ * gets accepted→working→done/failed through `trackWorkStep` (board.track,
+ * keyed on the message). A backlog row the execution ladder queued for a
+ * `task_assigned` / `task_comment` event is about an item that ALREADY EXISTS
+ * on a board and was assigned to this agent — `board.track` has no message to
+ * key on and `board.claim` refuses an item that is already assigned. What the
+ * item's thread CAN carry is a comment: one when the session starts on it,
+ * one when the session ends, each naming the session ref so the row and the
+ * session log join. `board.comment` dedupes nothing server-side, so the
+ * idempotency key is (item, stage, session).
+ *
+ * Fire-and-forget, fail-open, never silent — same contract as trackWorkStep.
+ *
+ * @param {object} a - { item (queue row), stage: "working"|"done"|"failed", sessionRef, note?, cfg?, callImpl? }
+ * @returns {Promise<{tracked:boolean, reason:string, itemId?:string|null}>}
+ */
+export async function trackBoardItemStep(a = {}) {
+  try {
+    const ref = boardItemRefFor(a.item);
+    if (!ref) return { tracked: false, reason: "not-a-board-item" };
+    const stage = String(a.stage || "").trim();
+    if (!["working", "done", "failed"].includes(stage)) return { tracked: false, reason: "bad-stage" };
+    const cfg = a.cfg !== undefined ? a.cfg : daemonOrgCfg();
+    if (!orgEnabled(cfg)) return { tracked: false, reason: "org-disabled" };
+    const conn = configFromAgent(cfg);
+    const sessionRef = String(a.sessionRef || "").trim() || "unknown";
+    const lead =
+      stage === "working" ? "Started on this." :
+      stage === "done" ? "Finished a working session on this." :
+      "A working session on this ended without completing; it is still owed.";
+    const body = `${lead}${a.note ? ` ${String(a.note).slice(0, 2000)}` : ""} (session ${sessionRef})`;
+    const impl = a.callImpl || orgCall;
+    const res = await impl("board.comment", { itemId: ref.itemId, body }, {
+      base: conn.base,
+      token: conn.token,
+      fetchImpl: a.fetchImpl,
+      idempotencyKey: `board.comment:${ref.itemId}:${stage}:${sessionRef}`,
+    });
+    if (!res || res.error) {
+      const reason = res && res.error ? `${res.error.code || "error"}: ${res.error.message || ""}` : "no-response";
+      console.log(`[board] item ${ref.itemId} ${stage} not tracked: ${reason.slice(0, 200)}`);
+      return { tracked: false, reason: reason.slice(0, 200), itemId: ref.itemId };
+    }
+    console.log(`[board] item ${ref.itemId} ${stage} — commented (session ${sessionRef})`);
+    return { tracked: true, reason: "ok", itemId: ref.itemId };
+  } catch (err) {
+    console.warn(`[board] item track failed (${a.stage}): ${err && err.message}`);
+    return { tracked: false, reason: "error" };
+  }
+}
+
 // A distillation longer than this is truncated before it lands in the store —
 // the shared memory holds a salient one-liner, never a transcript.
 const SESSION_DISTILL_MAX_CHARS = 400;
@@ -2224,9 +2568,34 @@ export function recoverInFlight() {
 // Backlog Sweep
 // ---------------------------------------------------------------------------
 
-async function sweepBacklog() {
-  const slots = availableSlots();
+/**
+ * Drain the backlog queues into sessions. `deps` are test seams only —
+ * `{dispatch, buildPrompt, trackBoardItemStep, availableSlots}` — so the
+ * board-item bookkeeping around a dispatch can be pinned without a child
+ * process or an hq.
+ */
+export async function sweepBacklog(deps = {}) {
+  const dispatchImpl = deps.dispatch || dispatch;
+  const buildPromptImpl = deps.buildPrompt || buildPrompt;
+  const trackBoardItem = deps.trackBoardItemStep || trackBoardItemStep;
+  const slots = (deps.availableSlots || availableSlots)();
   if (slots <= 0) return; // No capacity
+  // FRONT DOOR (design §3.1, ported from a seat fork 2026-09-22): while the
+  // main session is live it works the board itself (main-session skill, idle
+  // loop). A daemon backlog session on the same rows holds the seat's pen and
+  // voice beside it — four such sessions edited a pack and DM'd a dark seat on
+  // one seat on 9 Sep 2026 while the front door was open. pollService already
+  // steps back from the INBOX on this gate; the backlog sweep is the other
+  // lane that spawns in the seat's name, and it must step back on the same
+  // signal. Fail-open on a reader error (the gate's worst case is the old
+  // behaviour: the daemon sweeps). `deps.frontDoorGate` is the test seam.
+  {
+    const fd = (deps.frontDoorGate || _frontDoorGate).check("cohort");
+    if (!fd.dispatch) {
+      if (fd.changed) console.log(`[daemon] front door live (${fd.reason}) — backlog belongs to the main session; sweep skipped`);
+      return;
+    }
+  }
 
   try {
     const queueDir = join(AGENT_REPO_DIR, "state", "queues");
@@ -2352,7 +2721,7 @@ async function sweepBacklog() {
         );
       }
 
-      const prompt = await buildPrompt(null, classResult, {
+      const prompt = await buildPromptImpl(null, classResult, {
         type: "backlog",
         queueItem,
       });
@@ -2361,8 +2730,26 @@ async function sweepBacklog() {
       // they get the same outcome discipline. This onClose does NOT touch the
       // backlog finalize path (the session updates its own queue item) — it is
       // purely the outcome sweep, gated off by default.
-      dispatch(prompt, queueItem, classResult, "backlog", {
+      // "Started on this" is said when a child has STARTED — from the
+      // dispatcher's `onSpawn`, with the session id it minted — never at the
+      // call site: `dispatch()` returns silently on rate-limit, governor
+      // QUEUE/DEFER, the backlog cap and a denied claim, and a comment fired
+      // here would have told the board about a session that did not exist
+      // until some later sweep succeeded (if it did). Both comments carry the
+      // real session id, so a retried row that genuinely starts again says so.
+      let startRef = null;
+      dispatchImpl(prompt, queueItem, classResult, "backlog", {
+        onSpawn: ({ sessionId }) => {
+          startRef = String(sessionId || "");
+          void trackBoardItem({ item: queueItem, stage: "working", sessionRef: startRef, note: classResult.summary });
+        },
         onClose: ({ ok, sessionId, stdout }) => {
+          void trackBoardItem({
+            item: queueItem,
+            stage: ok ? "done" : "failed",
+            sessionRef: String(sessionId || startRef || "unknown"),
+            note: ok ? sessionCompletionNote(stdout) : null,
+          });
           if (!ok) return;
           Promise.resolve(sweepOutcomesForSession({ sessionId, stdout, item: queueItem, classResult }))
             .catch(() => { /* fail-open */ });
@@ -2432,6 +2819,7 @@ async function main() {
   // that doctor/operators read. subscribe + bump are both fail-open; an init
   // failure here can never stop the daemon coming up.
   registerHookSubscribers();
+  assertCadencePromptsExist();
 
   // Check for emergency stop
   try {