@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/session/current-work.mjs

@@ -0,0 +1,676 @@
+/**
+ * lib/session/current-work.mjs — "what am I doing right now, across the
+ * sessions on this machine", as a fact the agent can answer from.
+ *
+ * THE QUESTION THIS ANSWERS. A human asks, in a channel or a DM, "what are you
+ * doing right now?". Before this module the reply had nothing to read: the
+ * compiled context carried `state/sessions/active.json` (the daemon's own
+ * `--print` children, summary + model + sender) and nothing else — not the
+ * front-door session, not its peers, not the board items already in progress,
+ * and not the fact that a person has an interactive session open on the box.
+ * The quick-reply path carried none of it. So the honest answer was
+ * unavailable and the model either confabulated or hedged.
+ *
+ * ONE derivation, four readers. `summarizeCurrentWork` is PURE over injected
+ * snapshots of the five state files the writers already keep:
+ *
+ *   state/session/heartbeat.json      the front door's beat (feed.mjs, 15 s)
+ *   state/session/main-session.json   {sessionId, createdAt}
+ *   state/session/peers.json          {peers:[{name, purpose, startedAt}]}
+ *   state/sessions/active.json        the dispatcher's live children (this
+ *                                     module also defines that entry's shape —
+ *                                     {@link activeEntryFor} — so the writer
+ *                                     and the reader cannot drift)
+ *   state/collective/presence/*.json  every Claude Code session on the machine
+ *                                     (lib/collective/presence.mjs)
+ *   state/org/board-mine.json         the daemon's 5-minute `board.mine` cache
+ *   state/session/handoffs/*.json     cadence ticks handed to the front door
+ *                                     (counted, never read)
+ *
+ * `renderCurrentWork` turns the summary into a BOUNDED block (≤ 8 lines by
+ * default) for a prompt: the spawn path's compiled context and the quick-reply
+ * path's user content both inject it, so a "what are you doing" question is
+ * answered from fact on either path.
+ *
+ * THE SINGLE SOURCE. This is the ONLY renderer of "what am I doing". The
+ * 2.18.0 roll-call work briefly had a second one (`renderSelfActivity` in
+ * lib/org/inbound/broadcast.mjs, fed by the daemon's own file reads) and the
+ * quick reply injected both — two overlapping accounts of the same state,
+ * one of which quoted session names. Everything that renderer carried and
+ * this one lacked — the front door being absent, the board rows that are
+ * queued or blocked (not only in progress), the open handoffs — lives here
+ * now, behind the same audience and barrier predicate as the rest, and a
+ * roll-call reply calls this once (`explicitEmpty`, below, is the roll-call's
+ * "nothing is running" line). responder-single-source.test.mjs pins that no
+ * second renderer is imported by the responder again.
+ *
+ * The block is SHARED by readers the responder is not — `maestro session
+ * status`, the `session_status` tool, the spawned session's compiled context
+ * — so it states only what is true from every seat. The one line whose
+ * explanation depends on who is asking (an absent front door: "…and so this
+ * reply comes from the background responder" is true of the responder and
+ * false of a peer or a person at the CLI) takes that explanation from the
+ * caller (`mainAbsentNote`) and otherwise says only that the front door is
+ * not running. Likewise `explicitEmpty`: today only the quick-reply path
+ * asks for it, because agent-daemon routes every roll-call to that path and
+ * a live front door always renders a block; a spawned child or a
+ * tool-answering session composing a roll-call from nothing would get "" and
+ * no "do not invent" line — a known edge, not a reachable one today.
+ *
+ * THE PRIVACY FLOOR. A human's interactive Claude Code session on an agent box
+ * is reported as EXISTING — "an interactive session is open since T" — and
+ * nothing else: not its cwd, not its repo, not its intent, never its prompt.
+ * The 2.11.10 reaper fix made those sessions invisible to reap/count; this
+ * keeps them invisible to reporting beyond existence. The agent's OWN sessions
+ * (the front door, its peers, the daemon's children) are the ones described.
+ *
+ * THE AUDIENCE RULE ({@link scopeCurrentWorkFor}). A dispatched session's
+ * summary is the classifier's paraphrase of SOMEONE'S message — "draft the
+ * termination letter for X for Dana" is Dana's DM, restated. Design §5.5:
+ * per-person facts may inform a reply but are never quoted into a room they
+ * did not come from. So the block is rendered FOR an audience, and a
+ * dispatched session is described to that audience only when it came from
+ * the same conversation (the same channel id, or — in a private conversation
+ * — the same person); every other session is reported as EXISTING ("a request
+ * from another conversation"), with no summary, no sender, no channel and no
+ * board id. A session that is nobody's message — a backlog row with no sender
+ * and no ask — is the agent's own work and is described, barrier permitting. The information-barrier keyword filter the context compiler
+ * applies to history (`forbidsText`) is applied to whatever survives: a
+ * disclosable summary, a board title, a peer's purpose. An audience of `{}` —
+ * no identity — sees nothing cross-conversation; `null` is the operator's own
+ * view (`maestro session status --all`) and scopes nothing.
+ *
+ * Everything is fail-open: a missing or corrupt snapshot reads as absent.
+ * `now` is a parameter wherever it changes the answer. Node builtins only.
+ *
+ * @module lib/session/current-work
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { summarizeSessionStatus, listOpenHandoffs } from "./status-summary.mjs";
+import { TERMINAL_STATUS } from "../org/protocol.mjs";
+
+/** Lines the rendered block may not exceed (one of them is the header). */
+export const CURRENT_WORK_MAX_LINES = 8;
+
+/** Board columns that mean "in progress" across the column vocabularies hq has used. */
+const IN_PROGRESS_COLS = Object.freeze(["running", "doing", "in_progress", "in-progress"]);
+/** Board columns that mean "stuck": reported as blocked, which a roll-call asks about by name. */
+const BLOCKED_COLS = Object.freeze(["blocked"]);
+/**
+ * Board columns that mean "done on my side, waiting on a reviewer": not in
+ * progress, not queued (the work is finished), not terminal (it can come
+ * back). protocol's A2A map puts `review` with `blocked` (`input-required`),
+ * which is the honest reading for a roll-call: it is waiting on someone.
+ */
+const REVIEW_COLS = Object.freeze(["review", "in_review", "in-review"]);
+/**
+ * Board columns with no further work — never "queued". The protocol's own
+ * TERMINAL_STATUS is the base so the two cannot drift; the extra spellings
+ * are the ones other boards hq has fed `board.mine` from have used.
+ */
+const TERMINAL_COLS = Object.freeze([...TERMINAL_STATUS, "closed", "cancelled", "canceled", "complete", "completed"]);
+
+/** A `--name <first>-main` front door, or a `--name <first>-<slug>` peer. */
+const MAIN_NAME_RE = /-main$/;
+
+function toMs(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string") {
+    const n = Date.parse(v);
+    if (Number.isFinite(n)) return n;
+    const asNum = Number(v);
+    if (Number.isFinite(asNum) && v.trim() !== "") return asNum;
+  }
+  return null;
+}
+
+function iso(ms) {
+  return ms === null ? null : new Date(ms).toISOString();
+}
+
+function clip(s, n) {
+  const t = String(s == null ? "" : s).replace(/\s+/g, " ").trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+}
+
+// ---------------------------------------------------------------------------
+// The active.json entry (written by the dispatcher, read here)
+// ---------------------------------------------------------------------------
+
+/**
+ * The board item a queue row is FOR, when it is for one.
+ *
+ * The execution ladder queues a `task_assigned` / `task_comment` event as a
+ * backlog row carrying `source_ref: cohort:<surface>:<entityId>:<seq>` and
+ * `entity_id: <taskId>` (lib/execution/effects.scheduleToQueue). That row is
+ * the daemon's only handle on "a board item was assigned to me" — so it is the
+ * one place the item id can be read back from, and the reason a dispatched
+ * backlog session can name the board item it is working.
+ *
+ * Also honours a live inbox item of the same surfaces (`kind` +
+ * `channel_id`/`entity_id`), so both dispatch paths agree.
+ *
+ * PURE. Returns null when the row is not about a board item.
+ *
+ * @param {object} item a queue row (lib/backlog.parseQueueItems) or inbox item
+ * @returns {{itemId:string, surface:string}|null}
+ */
+export function boardItemRefFor(item) {
+  if (!item || typeof item !== "object") return null;
+  const ref = String(item.source_ref || item.raw_ref || "").trim();
+  if (ref.startsWith("cohort:")) {
+    const parts = ref.split(":");
+    const surface = parts[1] || "";
+    if (surface === "task_assigned" || surface === "task_comment") {
+      const id = String(item.entity_id || parts[2] || "").trim();
+      return id ? { itemId: id, surface } : null;
+    }
+  }
+  const kind = String(item.kind || "").trim();
+  if (kind === "task_assigned" || kind === "task_comment") {
+    const id = String(item.entity_id || item.channel_id || item.channel || "").trim();
+    return id ? { itemId: id, surface: kind } : null;
+  }
+  return null;
+}
+
+/**
+ * The record the dispatcher writes for one live child under
+ * `state/sessions/active.json[sessionId]`.
+ *
+ * Carries the ASK IDENTITY (`ask.channelId` + `ask.messageId`, the pair hq's
+ * `board.track` dedupes on) so the board row the daemon opens for an inbox
+ * ask can be linked back to the session ({@link linkBoardTask}); carries the
+ * board item id when the session is a backlog row for one; and carries the
+ * queue row id and title so a backlog session can be named. PURE.
+ *
+ * @param {object} o
+ * @param {object} [o.item]
+ * @param {object} [o.classResult]
+ * @param {string} [o.source] "inbox" | "backlog"
+ * @param {number} [o.now]
+ */
+export function activeEntryFor(o = {}) {
+  const item = o.item && typeof o.item === "object" ? o.item : {};
+  const cr = o.classResult && typeof o.classResult === "object" ? o.classResult : {};
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  const service = String(item.service || "").trim().toLowerCase();
+  const channelId = String(item.cohort_channel_id || item.channel_id || "").trim();
+  let messageId = null;
+  const raw = String(item.raw_ref || "").trim();
+  if (raw.startsWith("cohort:")) {
+    const parts = raw.split(":");
+    if (parts.length >= 3 && parts[2]) messageId = parts[2];
+  }
+  if (!messageId) {
+    const id = String(item.id || "").trim();
+    if (id.startsWith("cohort-")) messageId = id.slice("cohort-".length) || null;
+  }
+  const ask = service === "cohort" && channelId && messageId ? { channelId, messageId } : null;
+  const board = boardItemRefFor(item);
+  return {
+    sender: item.sender || null,
+    channel: item.channel || item.channel_id || null,
+    summary: cr.summary || item.title || "unknown",
+    model: cr.model || "sonnet",
+    startTime: now,
+    source: o.source || "inbox",
+    itemId: item.id ? String(item.id) : null,
+    title: item.title ? clip(item.title, 160) : null,
+    ask,
+    boardItemId: board ? board.itemId : null,
+    // Filled by linkBoardTask once the daemon's `working` board.track resolves.
+    boardTaskId: null,
+    boardCol: null,
+  };
+}
+
+/**
+ * Attach the board row hq opened for an ask to the live session that is
+ * working it. PURE over the active map: returns a NEW map, and the id of the
+ * entry it changed (or null when no live entry carries that ask).
+ *
+ * The daemon's `accepted`→`working` board.track is fire-and-forget and
+ * resolves AFTER the dispatch (agent-daemon.mjs), so the link is a second
+ * write, matched on the ask identity the entry already carries.
+ *
+ * @param {object} active the parsed active.json
+ * @param {{channelId:string, messageId:string}} ask
+ * @param {{taskId:string, col?:string|null}} row
+ * @returns {{active:object, sessionId:string|null}}
+ */
+export function linkBoardTask(active, ask, row) {
+  const cur = active && typeof active === "object" && !Array.isArray(active) ? active : {};
+  const out = { ...cur };
+  if (!ask || !ask.channelId || !ask.messageId || !row || !row.taskId) return { active: out, sessionId: null };
+  let hit = null;
+  for (const [id, e] of Object.entries(cur)) {
+    const a = e && e.ask;
+    if (a && a.channelId === ask.channelId && a.messageId === ask.messageId) {
+      out[id] = { ...e, boardTaskId: String(row.taskId), boardCol: row.col ? String(row.col) : e.boardCol || null };
+      hit = id;
+      break;
+    }
+  }
+  return { active: out, sessionId: hit };
+}
+
+// ---------------------------------------------------------------------------
+// The summary (pure)
+// ---------------------------------------------------------------------------
+
+function peersOf(peers) {
+  if (Array.isArray(peers)) return peers.filter((p) => p && typeof p === "object");
+  if (peers && typeof peers === "object" && Array.isArray(peers.peers)) return peers.peers.filter((p) => p && typeof p === "object");
+  return [];
+}
+
+function activeOf(active) {
+  if (Array.isArray(active)) return active.filter((e) => e && typeof e === "object").map((e, i) => [e.sessionId || e.id || `s${i}`, e]);
+  if (active && typeof active === "object") return Object.entries(active).filter(([, e]) => e && typeof e === "object");
+  return [];
+}
+
+function itemsOf(boardMine) {
+  if (Array.isArray(boardMine)) return boardMine;
+  if (boardMine && typeof boardMine === "object" && Array.isArray(boardMine.items)) return boardMine.items;
+  return [];
+}
+
+/**
+ * Derive the current-work summary from snapshots. PURE.
+ *
+ * @param {object} o
+ * @param {object|null} [o.heartbeat]    state/session/heartbeat.json
+ * @param {object|null} [o.mainSession]  state/session/main-session.json
+ * @param {object|object[]|null} [o.peers] state/session/peers.json
+ * @param {object|null} [o.active]       state/sessions/active.json
+ * @param {object[]|null} [o.presence]   lib/collective/presence.list() records
+ * @param {object|object[]|null} [o.boardMine] state/org/board-mine.json
+ * @param {string[]|null} [o.handoffs]  names of open handoff files (state/session/handoffs)
+ * @param {number} [o.now]
+ * @param {number} [o.staleMs]
+ * @param {string} [o.excludeSessionId]  the session composing the reply (never lists itself as "another")
+ */
+export function summarizeCurrentWork(o = {}) {
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  const status = summarizeSessionStatus({ heartbeat: o.heartbeat, peers: o.peers, handoffs: o.handoffs, now, staleMs: o.staleMs });
+  const main = o.mainSession && typeof o.mainSession === "object" ? o.mainSession : null;
+  const mainSessionId = (main && typeof main.sessionId === "string" && main.sessionId) || status.sessionId || null;
+  const mainSince = main ? toMs(main.createdAt) : null;
+
+  const peers = peersOf(o.peers).map((p) => ({
+    name: typeof p.name === "string" ? p.name : null,
+    purpose: typeof p.purpose === "string" ? clip(p.purpose, 140) : null,
+    startedAt: toMs(p.startedAt) !== null ? iso(toMs(p.startedAt)) : null,
+  }));
+  const peerNames = new Set(peers.map((p) => p.name).filter(Boolean));
+
+  const dispatched = activeOf(o.active).map(([id, e]) => {
+    const started = toMs(e.startTime || e.started_at || e.startedAt);
+    return {
+      sessionId: String(id),
+      source: e.source || "inbox",
+      summary: clip(e.summary || e.title || "unknown", 140),
+      sender: e.sender || null,
+      channel: e.channel || null,
+      startedAt: iso(started),
+      ageMs: started === null ? null : Math.max(0, now - started),
+      itemId: e.itemId || null,
+      boardItemId: e.boardItemId || null,
+      boardTaskId: e.boardTaskId || null,
+      ask: e.ask && typeof e.ask === "object" ? { channelId: e.ask.channelId || null, messageId: e.ask.messageId || null } : null,
+    };
+  });
+
+  // Interactive sessions that are NOT the agent's own: existence only.
+  const presence = Array.isArray(o.presence) ? o.presence.filter((r) => r && typeof r === "object") : [];
+  let interactiveOpen = 0;
+  let interactiveSince = null;
+  for (const r of presence) {
+    if (r.kind === "daemon") continue;
+    if (o.excludeSessionId && r.sessionId === o.excludeSessionId) continue;
+    if (mainSessionId && r.sessionId === mainSessionId) continue;
+    const name = typeof r.agentName === "string" ? r.agentName : "";
+    if (name && (MAIN_NAME_RE.test(name) || peerNames.has(name))) continue;
+    interactiveOpen += 1;
+    const s = toMs(r.startedAt);
+    if (s !== null && (interactiveSince === null || s < interactiveSince)) interactiveSince = s;
+  }
+
+  // Board rows, split the way a roll-call asks about them: in progress,
+  // blocked, queued. A terminal row (done/archived) is history, not work.
+  const boardRows = itemsOf(o.boardMine)
+    .filter((i) => i && typeof i === "object")
+    .map((i) => ({
+      itemId: i.itemId ? String(i.itemId) : null,
+      title: clip(i.title || "", 120),
+      boardName: i.boardName || null,
+      col: String(i.col || i.stage || i.status || "").toLowerCase() || null,
+      updatedAt: toMs(i.updatedAt) !== null ? iso(toMs(i.updatedAt)) : null,
+    }))
+    .filter((i) => i.itemId);
+  const boardInProgress = boardRows.filter((i) => IN_PROGRESS_COLS.includes(i.col)).map(({ col, ...rest }) => rest);
+  const boardBlocked = boardRows.filter((i) => BLOCKED_COLS.includes(i.col));
+  const boardInReview = boardRows.filter((i) => REVIEW_COLS.includes(i.col)).map(({ col, ...rest }) => rest);
+  const boardQueued = boardRows.filter((i) =>
+    i.col && !IN_PROGRESS_COLS.includes(i.col) && !BLOCKED_COLS.includes(i.col) && !REVIEW_COLS.includes(i.col) && !TERMINAL_COLS.includes(i.col));
+
+  return {
+    now: iso(now),
+    main: {
+      live: status.live,
+      state: status.state,
+      sessionId: mainSessionId,
+      since: iso(mainSince),
+      beatAgeMs: status.ageMs,
+    },
+    dispatched,
+    peers,
+    interactiveOpen,
+    interactiveSince: iso(interactiveSince),
+    boardInProgress,
+    boardBlocked,
+    boardInReview,
+    boardQueued,
+    handoffsOpen: Number.isFinite(status.handoffsOpen) ? status.handoffsOpen : 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The audience (pure)
+// ---------------------------------------------------------------------------
+
+/** What a redacted dispatched entry says instead of its summary. */
+export const REDACTED_WORK = "a request from another conversation";
+/** What a redacted peer purpose says. */
+export const REDACTED_PURPOSE = "(purpose not shareable here)";
+
+function sameConversation(d, audience) {
+  // Work that is nobody's message — a backlog row with no sender and no ask
+  // (the agent's own queue, or a board item assigned to it) — is the agent's
+  // own to describe, subject only to the barrier. The rule below is about
+  // summaries that restate a PERSON's message.
+  if (!d.sender && !d.ask) return true;
+  const chanId = String(audience.channelId || "").trim();
+  const chan = String(audience.channel || "").trim();
+  const askChan = d.ask && d.ask.channelId ? String(d.ask.channelId) : "";
+  const dChan = d.channel ? String(d.channel) : "";
+  if (chanId && askChan && chanId === askChan) return true;
+  if (chanId && dChan && chanId === dChan) return true;
+  if (chan && dChan && chan === dChan) return true;
+  // The same PERSON, in a PRIVATE conversation with them: their own asks may
+  // be described back to them. In a room, only the room's own asks — a
+  // person's DM ask is not quoted into a channel even for that person (§5.5).
+  const sender = String(audience.sender || "").trim().toLowerCase();
+  if (audience.isPrivate === true && sender && d.sender && String(d.sender).trim().toLowerCase() === sender) return true;
+  return false;
+}
+
+/**
+ * Scope a summary to an audience. PURE; returns a NEW summary.
+ *
+ * @param {object} summary from {@link summarizeCurrentWork}
+ * @param {{sender?:string, channelId?:string, channel?:string, isPrivate?:boolean, forbidsText?:(text:string)=>boolean}|null} audience
+ *   `null` → the operator's own view: nothing is scoped. `{}` → an audience
+ *   with no identity: every dispatched session is reported as existing only.
+ * @returns {object}
+ */
+export function scopeCurrentWorkFor(summary, audience) {
+  const s = summary && typeof summary === "object" ? summary : summarizeCurrentWork({});
+  if (audience === null) return s;
+  const a = audience && typeof audience === "object" ? audience : {};
+  const forbids = typeof a.forbidsText === "function"
+    ? (t) => { try { return Boolean(a.forbidsText(String(t || ""))); } catch { return true; } }
+    : () => false;
+
+  const dispatched = (s.dispatched || []).map((d) => {
+    const visible = sameConversation(d, a) && !forbids(d.summary);
+    if (visible) return { ...d, redacted: false };
+    return {
+      sessionId: d.sessionId, source: d.source, startedAt: d.startedAt, ageMs: d.ageMs,
+      summary: null, sender: null, channel: null, itemId: null, boardItemId: null, boardTaskId: null, ask: null,
+      redacted: true,
+    };
+  });
+  const boardInProgress = (s.boardInProgress || []).filter((b) => !forbids(b.title));
+  const boardBlocked = (s.boardBlocked || []).filter((b) => !forbids(b.title));
+  const boardInReview = (s.boardInReview || []).filter((b) => !forbids(b.title));
+  const boardQueued = (s.boardQueued || []).filter((b) => !forbids(b.title));
+  const peers = (s.peers || []).map((p) => (p.purpose && forbids(p.purpose) ? { ...p, purpose: null, redacted: true } : { ...p, redacted: false }));
+  return { ...s, dispatched, boardInProgress, boardBlocked, boardInReview, boardQueued, peers, scoped: true };
+}
+
+// ---------------------------------------------------------------------------
+// The block (pure)
+// ---------------------------------------------------------------------------
+
+function ageLabel(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "just now";
+  const m = Math.round(ms / 60_000);
+  if (m < 1) return "just now";
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+function sinceLabel(isoTs, now) {
+  const t = toMs(isoTs);
+  if (t === null) return "";
+  return ` (since ${isoTs.slice(0, 16).replace("T", " ")}Z, ${ageLabel(now - t)})`;
+}
+
+/** The block's header. Exported so a test can count it in a prompt. */
+export const CURRENT_WORK_HEADER = "## Current Work (your own sessions on this machine, right now)";
+
+/**
+ * The one line a roll-call gets when nothing at all is known. A roll-call
+ * answer composed from NO block would be composed from nothing — and the
+ * model fills nothing with invention. So the roll-call asks for this line
+ * instead of "", and the instruction to say so travels with it.
+ */
+export const CURRENT_WORK_EMPTY_LINE =
+  "- Nothing is recorded as running, queued or blocked on this machine right now — say so plainly; do not invent activity.";
+
+/**
+ * Render the summary as a bounded prompt block. PURE.
+ *
+ * Priority when the cap bites: dispatched sessions (the live work), then
+ * board items in progress, then blocked, then awaiting review, then peers,
+ * then the front door, then queued board items, then open handoffs, then the
+ * interactive-session line. The cap counts the header. Returns "" when there
+ * is genuinely nothing to say AND no front door — the caller then omits the
+ * section; a live-but-idle front door still renders, because "nothing else
+ * is running" is itself the honest answer. `explicitEmpty` (the roll-call)
+ * renders {@link CURRENT_WORK_EMPTY_LINE} under the header instead of "".
+ *
+ * `mainAbsentNote` is the caller's explanation of an absent front door,
+ * rendered in parentheses after "Main session: not running" — the daemon's
+ * quick reply says "this reply comes from the background responder"; every
+ * other reader (`maestro session status`, `session_status`, the compiled
+ * context of a spawned session) passes nothing, because from those seats
+ * that sentence would be false.
+ *
+ * @param {object} summary from {@link summarizeCurrentWork}
+ * @param {{max?:number, now?:number, explicitEmpty?:boolean, mainAbsentNote?:string}} [o]
+ * @returns {string}
+ */
+export function renderCurrentWork(summary, o = {}) {
+  const s = summary && typeof summary === "object" ? summary : summarizeCurrentWork({});
+  const max = Number.isFinite(o.max) && o.max > 1 ? o.max : CURRENT_WORK_MAX_LINES;
+  const now = Number.isFinite(o.now) ? o.now : toMs(s.now) ?? Date.now();
+  const blocked = Array.isArray(s.boardBlocked) ? s.boardBlocked : [];
+  const inReview = Array.isArray(s.boardInReview) ? s.boardInReview : [];
+  const queued = Array.isArray(s.boardQueued) ? s.boardQueued : [];
+  const handoffs = Number.isFinite(s.handoffsOpen) ? s.handoffsOpen : 0;
+  const mainAbsentNote = typeof o.mainAbsentNote === "string" ? clip(o.mainAbsentNote, 120) : "";
+  const nothing =
+    !s.main.live && s.main.state !== "stale" &&
+    s.dispatched.length === 0 && s.peers.length === 0 && s.boardInProgress.length === 0 &&
+    blocked.length === 0 && inReview.length === 0 && queued.length === 0 && handoffs === 0 && s.interactiveOpen === 0;
+  if (nothing) return o.explicitEmpty === true ? [CURRENT_WORK_HEADER, CURRENT_WORK_EMPTY_LINE].join("\n") : "";
+
+  const lines = [];
+  for (const d of s.dispatched) {
+    if (d.redacted) {
+      lines.push(`- Working now${sinceLabel(d.startedAt, now)}: ${REDACTED_WORK} — you can say you are busy with it; you cannot say what it is or who it is for`);
+      continue;
+    }
+    const who = d.sender ? ` for ${d.sender}` : "";
+    const where = d.channel ? ` in ${d.channel}` : "";
+    const board = d.boardTaskId ? ` — board item ${d.boardTaskId}` : d.boardItemId ? ` — board item ${d.boardItemId}` : "";
+    lines.push(`- Working now${sinceLabel(d.startedAt, now)}: ${d.summary}${who}${where}${board}`);
+  }
+  for (const b of s.boardInProgress) {
+    lines.push(`- In progress on the board: ${b.title} — board item ${b.itemId}${b.boardName ? ` (${b.boardName})` : ""}`);
+  }
+  for (const b of blocked) {
+    lines.push(`- Blocked on the board: ${b.title} — board item ${b.itemId}${b.boardName ? ` (${b.boardName})` : ""}`);
+  }
+  for (const b of inReview) {
+    lines.push(`- Awaiting review on the board: ${b.title} — board item ${b.itemId}${b.boardName ? ` (${b.boardName})` : ""}`);
+  }
+  for (const p of s.peers) {
+    lines.push(`- Parallel work${sinceLabel(p.startedAt, now)}: ${p.redacted ? REDACTED_PURPOSE : p.purpose || "(no stated purpose)"}`);
+  }
+  if (s.main.live) {
+    const busy = s.dispatched.length > 0 || s.peers.length > 0;
+    lines.push(`- Main session: live${sinceLabel(s.main.since, now)}${busy ? "" : " — idle apart from this reply"}`);
+  } else if (s.main.state === "stale") {
+    lines.push("- Main session: stale (stopped beating)");
+  } else {
+    lines.push(`- Main session: not running${mainAbsentNote ? ` (${mainAbsentNote})` : ""}`);
+  }
+  for (const b of queued) {
+    lines.push(`- Queued on the board: ${b.title} — board item ${b.itemId}${b.col ? ` [${b.col}]` : ""}${b.boardName ? ` (${b.boardName})` : ""}`);
+  }
+  if (handoffs > 0) {
+    lines.push(`- ${handoffs} open handoff${handoffs === 1 ? "" : "s"} waiting on the main session`);
+  }
+  if (s.interactiveOpen > 0) {
+    const n = s.interactiveOpen;
+    lines.push(
+      `- ${n} interactive session${n === 1 ? "" : "s"} open on this machine${sinceLabel(s.interactiveSince, now)} — you can say it is open; you cannot see what is in it.`,
+    );
+  }
+
+  const header = CURRENT_WORK_HEADER;
+  const budget = max - 1;
+  const body = lines.length > budget ? [...lines.slice(0, budget - 1), `- …and ${lines.length - (budget - 1)} more`] : lines;
+  return [header, ...body].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// The reader (I/O; thin)
+// ---------------------------------------------------------------------------
+
+function readJson(p) {
+  try {
+    if (!existsSync(p)) return null;
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read every snapshot under an agent root and summarise. Fail-open; READ-ONLY
+ * (presence is listed with `reap:false` so a reader never deletes a record;
+ * handoff files are counted, never opened).
+ *
+ * @param {string} agentRoot
+ * @param {{now?:number, staleMs?:number, excludeSessionId?:string, presenceList?:Function, activePath?:string, audience?:object|null}} [o]
+ *   `activePath` overrides where active.json is read from (the context
+ *   compiler's test seam points its session dir elsewhere). `audience` is
+ *   applied through {@link scopeCurrentWorkFor}; ABSENT is `{}` (an audience
+ *   with no identity, which sees nothing cross-conversation) — the operator's
+ *   unscoped view must be asked for with an explicit `null`.
+ */
+export async function readCurrentWork(agentRoot, o = {}) {
+  const root = String(agentRoot || "");
+  const sess = join(root, "state", "session");
+  let presence = [];
+  try {
+    const list = o.presenceList || (await import("../collective/presence.mjs")).list;
+    presence = list(root, { nowMs: o.now, reap: false }) || [];
+  } catch {
+    presence = [];
+  }
+  const summary = summarizeCurrentWork({
+    heartbeat: readJson(join(sess, "heartbeat.json")),
+    mainSession: readJson(join(sess, "main-session.json")),
+    peers: readJson(join(sess, "peers.json")),
+    active: readJson(o.activePath || join(root, "state", "sessions", "active.json")),
+    presence,
+    boardMine: readJson(join(root, "state", "org", "board-mine.json")),
+    handoffs: listOpenHandoffs(root),
+    now: o.now,
+    staleMs: o.staleMs,
+    excludeSessionId: o.excludeSessionId,
+  });
+  return scopeCurrentWorkFor(summary, o.audience === undefined ? {} : o.audience);
+}
+
+/**
+ * The audience an inbound item's reply is for. PURE. `isPrivate` is decided
+ * by lib/context/history-scope's rule (unknown is a room), passed in by the
+ * caller so this module stays free of that import's defaults.
+ *
+ * @param {object} item an inbox item
+ * @param {{isPrivate?:boolean, forbidsText?:Function}} [o]
+ */
+export function audienceForItem(item, o = {}) {
+  const it = item && typeof item === "object" ? item : {};
+  return {
+    sender: it.sender ? String(it.sender) : "",
+    channelId: String(it.cohort_channel_id || it.channel_id || it.channelId || "").trim(),
+    channel: it.channel ? String(it.channel) : "",
+    isPrivate: o.isPrivate === true,
+    ...(typeof o.forbidsText === "function" ? { forbidsText: o.forbidsText } : {}),
+  };
+}
+
+/**
+ * The block for a prompt, straight from disk, scoped to `o.audience` (see
+ * {@link readCurrentWork} — absent means "no identity", which discloses no
+ * cross-conversation work). "" when there is nothing to say, unless
+ * `explicitEmpty` (a roll-call) asks for the header + the "nothing" line.
+ * `mainAbsentNote` is passed through to {@link renderCurrentWork}.
+ * @param {string} agentRoot
+ * @param {{now?:number, max?:number, excludeSessionId?:string, activePath?:string, audience?:object|null, explicitEmpty?:boolean, mainAbsentNote?:string}} [o]
+ */
+export async function currentWorkBlock(agentRoot, o = {}) {
+  try {
+    const s = await readCurrentWork(agentRoot, o);
+    return renderCurrentWork(s, { max: o.max, now: o.now, explicitEmpty: o.explicitEmpty, mainAbsentNote: o.mainAbsentNote });
+  } catch {
+    // A roll-call still gets its "nothing" line: the instruction not to invent
+    // must reach the composer even when the read itself failed. (readCurrentWork
+    // absorbs a throwing presence lister and unreadable files; what reaches
+    // here is a defect further in — a poisoned record, say — and the answer
+    // to a roll-call is still "say nothing is known", not silence.)
+    return o.explicitEmpty === true ? [CURRENT_WORK_HEADER, CURRENT_WORK_EMPTY_LINE].join("\n") : "";
+  }
+}
+
+export default {
+  CURRENT_WORK_MAX_LINES,
+  CURRENT_WORK_HEADER,
+  CURRENT_WORK_EMPTY_LINE,
+  REDACTED_WORK,
+  REDACTED_PURPOSE,
+  boardItemRefFor,
+  activeEntryFor,
+  linkBoardTask,
+  summarizeCurrentWork,
+  scopeCurrentWorkFor,
+  audienceForItem,
+  renderCurrentWork,
+  readCurrentWork,
+  currentWorkBlock,
+};