@cohortapp/agent-sdk 2.18.15 → 2.18.16

package/lib/org/inbound/hydrate.mjs

@@ -432,7 +432,29 @@ function hydrateMessage(c, facts) {
   const page = facts.channelPages instanceof Map ? facts.channelPages.get(s(c.ids.channelId)) : null;
   const msg = page && page.byId ? page.byId.get(s(c.ids.messageId)) : null;
   if (!msg) return { ok: false, reason: "message_not_in_page", text: "" };
-  const body = s(msg.body ?? msg.text).trim();
+  let body = s(msg.body ?? msg.text).trim();
+
+  // VOICE_NOTE_OVERLAY (2026-09-26; pb-2026-09-26-inbound-voice-notes-reach-agents-as-fileid-only).
+  // A voice note / attachment-only message arrives with an EMPTY body + attachments[]. Treating that
+  // as empty_body dropped the whole event. Server carries no transcript + no byte route, so the honest
+  // text is what the attachment IS and that it couldn't be heard; metadata rides on the event.
+  const atts = Array.isArray(msg.attachments) ? msg.attachments.filter((a) => a && typeof a === "object") : [];
+  if (!body && atts.length) {
+    body = atts
+      .map((a) => {
+        const name = s(a.name || a.filename || a.fileId || "attachment");
+        const mime = s(a.contentType || a.mime || a.mimetype || "");
+        const bytes = Number(a.sizeBytes ?? a.size_bytes ?? a.size ?? 0);
+        const secs = Number(a.durationSec ?? a.duration_sec ?? a.duration ?? 0);
+        const isAudio = /^audio\//.test(mime) || secs > 0;
+        const tx = s(a.transcript);
+        return tx
+          ? `[${isAudio ? "voice note" : "attachment"} ${name}] ${tx}`
+          : `[${isAudio ? "voice note" : "attachment"}: ${name}${mime ? ", " + mime : ""}${bytes ? ", " + bytes + " bytes" : ""}${secs ? ", " + secs + " s" : ""}; no transcript available on this seat]`;
+      })
+      .join("\n");
+  }
+
   if (!body) return { ok: false, reason: "empty_body", text: "" };
 
   const chan = facts.channels instanceof Map ? facts.channels.get(s(c.ids.channelId)) : null;
@@ -465,6 +487,18 @@ function hydrateMessage(c, facts) {
     from: { id: s(msg.authorId || c.actor), name: s(msg.authorName || msg.authorId || c.actor) },
     channelId: s(c.ids.channelId),
     channelLabel: s((chan && (chan.name || chan.slug)) || c.ids.channelId),
+    // VOICE_NOTE_OVERLAY: attachment metadata rides on the event so
+    // lib/channels/inbox-item.mjs writes attachments[] (and transcript when present).
+    attachments: atts.length
+      ? atts.map((a) => ({
+          id: s(a.fileId || a.id),
+          name: s(a.name || a.filename || "attachment"),
+          mimetype: s(a.contentType || a.mime || a.mimetype || "application/octet-stream"),
+          size: Number(a.sizeBytes ?? a.size_bytes ?? a.size ?? 0),
+          duration_sec: Number(a.durationSec ?? a.duration_sec ?? 0) || undefined,
+          ...(s(a.transcript) ? { transcript: s(a.transcript) } : {}),
+        }))
+      : undefined,
   };
 }
 

package/lib/org/inbound/project.mjs

@@ -116,6 +116,9 @@ export function toMessageEvent(o = {}) {
     sender: s(from.name || from.id),
     is_reply: Boolean(hydrated.isReply),
     thread_context: hydrated.threadContext != null ? hydrated.threadContext : null,
+    // VOICE_NOTE_OVERLAY (2026-09-26): attachment metadata from the hydrator rides on the event so
+    // lib/channels/inbox-item.mjs writes attachments[] (and a transcript when one exists).
+    ...(Array.isArray(hydrated.attachments) && hydrated.attachments.length ? { attachments: hydrated.attachments } : {}),
     priority_signals: {
       from_ceo: false,
       tagged_urgent: URGENT.test(text) || c.kind === "board.blocked" || c.family === "escalation",

package/lib/session/frontdoor.mjs

@@ -3,14 +3,29 @@
  * or the daemon's legacy `claude --print` lane (design §3.1, §3.3, §3.4).
  *
  * THE ONE RULE. When the seat's main session is the configured front door AND
- * it is provably live (a fresh `state/session/heartbeat.json`), the daemon
- * stops spawning for the surfaces the session owns: Cohort inbox items are
- * left in place for the session to claim, and escalate/guarded cadence ticks
- * are written as handoffs for the session to ack. When the session is NOT
- * live — no heartbeat, a stale one, or the front door is `daemon` — the daemon
+ * it is provably live (a fresh `state/session/heartbeat.json`) AND it has
+ * actually CONSUMED inbound within the assurance window, the daemon stops
+ * spawning for the surfaces the session owns: Cohort inbox items are left in
+ * place for the session to claim, and escalate/guarded cadence ticks are
+ * written as handoffs for the session to ack. When the session is NOT live —
+ * no heartbeat, a stale one, or the front door is `daemon` — the daemon
  * dispatches exactly as it always has. Liveness is MEASURED, never assumed,
  * and the fallback is the legacy lane, so nothing is ever dropped.
  *
+ * A WRITTEN HEARTBEAT IS NOT A CONSUMED INBOX (DM-LATENCY). A session answers
+ * inbound only between its own tool calls; it can sit in a long catch-up turn,
+ * beating the whole time, without ever draining the inbox. "Live" and "not
+ * draining" are then both true and nobody answers a slow DM. So liveness alone
+ * no longer holds the item: the session must ALSO have proved a consume — an
+ * inbox claim/reply/done or a handoff ack, both of which stamp the ONE
+ * `state/session/last-consumed.json` file (see lib/session/handoffs.mjs). A
+ * fresh beat with a stale last-consume is a beating-but-wedged front door, and
+ * the daemon takes the item rather than let it go unanswered. The window is
+ * the 20-min assurance sweep interval, NOT the 90-s heartbeat: a session mid
+ * long turn is normal and must not lose the item on a heartbeat-length silence.
+ * The consume signal only ever *loses* the session the item — a missing or
+ * unreadable stamp fails open to the daemon taking it, never to dropping it.
+ *
  * PURE CORE. `sessionLiveFromHeartbeat`, `resolveFrontDoor`,
  * `frontDoorServices`, `shouldDaemonDispatch` and `shouldHandOffTick` take
  * every input as a parameter — the parsed heartbeat object, the clock, the
@@ -28,6 +43,7 @@
 import { join } from "node:path";
 import * as nodeFs from "node:fs";
 import { createRequire } from "node:module";
+import { readLastConsumed } from "./handoffs.mjs";
 
 // js-yaml is a declared dependency; loaded synchronously so the reader stays
 // sync. Fail-open: without it the flat line parser below still reads the
@@ -40,6 +56,16 @@ try {
 
 /** A heartbeat older than this is stale — the session is treated as not live. */
 export const DEFAULT_STALE_MS = 90_000;
+/**
+ * A last-consume older than this is stale — the session is beating but has not
+ * proved it drained inbound, so the daemon takes the item. This is the 20-min
+ * assurance-sweep interval, deliberately much longer than DEFAULT_STALE_MS: a
+ * session mid a long catch-up turn is normal and must not lose the item on a
+ * heartbeat-length silence.
+ */
+export const DEFAULT_CONSUMED_STALE_MS = 20 * 60 * 1000;
+/** Where the session runtime stamps its last inbound consume (relative to the agent root). */
+export const LAST_CONSUMED_RELATIVE = "state/session/last-consumed.json";
 /** Inbox services the session fronts by default. */
 export const DEFAULT_FRONT_DOOR_SERVICES = Object.freeze(["cohort"]);
 /** Cadence modes whose tick spawns a sub-session — the ones a live session takes over. */
@@ -75,6 +101,30 @@ export function sessionLiveFromHeartbeat(heartbeat, o = {}) {
   return { live: true, reason: "fresh", ageMs };
 }
 
+/**
+ * Has the front door CONSUMED inbound recently, given its last-consume epoch
+ * ms (from `state/session/last-consumed.json`, stamped by an inbox
+ * claim/reply/done or a handoff ack)? Pure. `null`/`undefined`/non-finite
+ * means "never proved a consume" — NOT "just now" — so it reads as not
+ * consumed and the daemon takes the item (fail-open in the safe direction:
+ * the item is answered, never dropped). A stamp a moment in the future is
+ * writer/reader clock skew, not a broken read, and counts as consumed.
+ *
+ * @param {number|null|undefined} lastConsumedAt epoch ms, or nullish = never
+ * @param {object} [o]
+ * @param {number} [o.now] epoch ms
+ * @param {number} [o.staleMs] window (default DEFAULT_CONSUMED_STALE_MS)
+ * @returns {{consumed:boolean, reason:string, ageMs:number|null}}
+ */
+export function sessionConsumedRecently(lastConsumedAt, o = {}) {
+  const now = typeof o.now === "number" ? o.now : Date.now();
+  const staleMs = Number.isFinite(o.staleMs) && o.staleMs > 0 ? o.staleMs : DEFAULT_CONSUMED_STALE_MS;
+  if (!Number.isFinite(lastConsumedAt)) return { consumed: false, reason: "never-consumed", ageMs: null };
+  const ageMs = now - lastConsumedAt;
+  if (ageMs > staleMs) return { consumed: false, reason: "consumed-stale", ageMs };
+  return { consumed: true, reason: "consumed", ageMs };
+}
+
 /**
  * Which process is the front door. `MAESTRO_FRONT_DOOR` in the env wins, then
  * `frontDoor` / `front_door` in config/session.yaml (a string, or an object
@@ -116,7 +166,15 @@ export function frontDoorServices(config) {
  * `dispatch:false` means "leave the item in place — the live session owns it".
  * Any malformed input resolves to dispatch (fail-open: never drop an item).
  *
- * @param {{frontDoor?:string, sessionLive?:boolean, service?:string, services?:string[]}} a
+ * The gate is two clauses now: the session must be the live front door for the
+ * service AND it must have consumed inbound within the window. A live session
+ * that has stopped draining the inbox (`sessionConsumed:false`) loses the item
+ * to the daemon — a beating heartbeat is not a consumed inbox (DM-LATENCY).
+ * The consumed clause is opt-in on an explicit `false`: an absent
+ * `sessionConsumed` (an older reader, a direct caller) never steals the item,
+ * so behaviour without the field is exactly the pre-DM-latency gate.
+ *
+ * @param {{frontDoor?:string, sessionLive?:boolean, sessionConsumed?:boolean, service?:string, services?:string[]}} a
  * @returns {{dispatch:boolean, reason:string}}
  */
 export function shouldDaemonDispatch(a) {
@@ -126,6 +184,10 @@ export function shouldDaemonDispatch(a) {
   const services = Array.isArray(x.services) && x.services.length ? x.services : DEFAULT_FRONT_DOOR_SERVICES;
   const svc = String(x.service || "").trim().toLowerCase();
   if (!svc || !services.includes(svc)) return { dispatch: true, reason: "service-not-front-door" };
+  // Live and owns the service, but has it actually drained inbound? A live
+  // front door that has not consumed within the window is wedged mid-turn —
+  // the daemon takes the item so a slow DM is not left unanswered.
+  if (x.sessionConsumed === false) return { dispatch: true, reason: "session-not-consuming" };
   return { dispatch: false, reason: "session-live" };
 }
 
@@ -187,9 +249,10 @@ function parseSessionYaml(text, yamlParse) {
  * @param {object} [deps.fs] `{existsSync, readFileSync}` (default node:fs)
  * @param {object} [deps.env] (default process.env)
  * @param {number} [deps.now] epoch ms
- * @param {number} [deps.staleMs]
+ * @param {number} [deps.staleMs] heartbeat freshness window
+ * @param {number} [deps.consumedStaleMs] last-consume freshness window (default DEFAULT_CONSUMED_STALE_MS)
  * @param {Function} [deps.yamlParse] optional YAML parser (js-yaml `load`)
- * @returns {{frontDoor:"session"|"daemon", sessionLive:boolean, services:string[], liveness:object, heartbeat:object|null}}
+ * @returns {{frontDoor:"session"|"daemon", sessionLive:boolean, sessionConsumed:boolean, lastConsumedAt:number|null, services:string[], liveness:object, consumed:object, heartbeat:object|null}}
  */
 export function readFrontDoorState(agentRoot, deps = {}) {
   const fs = deps.fs || nodeFs;
@@ -209,11 +272,24 @@ export function readFrontDoorState(agentRoot, deps = {}) {
     }
   } catch { heartbeat = null; /* corrupt heartbeat → not live → legacy lane (fail-open) */ }
   const liveness = sessionLiveFromHeartbeat(heartbeat, { now, staleMs: deps.staleMs });
+  // The other half of "provably answering": has the front door drained inbound
+  // within the window? `readLastConsumed` (lib/session/handoffs.mjs) reads the
+  // ONE last-consumed.json both consume paths stamp; a missing/unreadable
+  // stamp is `null` and reads as not-consumed (fail-open to the daemon taking
+  // the item). Kept SEPARATE from `sessionLive`: an alive-but-unconsumed
+  // session is still alive, so the revive path (which reads `sessionLive`)
+  // must not fire on it — only the dispatch gate reacts to `sessionConsumed`.
+  let lastConsumedAt = null;
+  try { lastConsumedAt = readLastConsumed(agentRoot, { fs }); } catch { lastConsumedAt = null; }
+  const consumed = sessionConsumedRecently(lastConsumedAt, { now, staleMs: deps.consumedStaleMs });
   return {
     frontDoor: resolveFrontDoor({ env, config }),
     sessionLive: liveness.live,
+    sessionConsumed: consumed.consumed,
+    lastConsumedAt,
     services: frontDoorServices(config),
     liveness,
+    consumed,
     heartbeat,
   };
 }
@@ -254,9 +330,12 @@ export function makeFrontDoorGate(o = {}) {
 
 export default {
   DEFAULT_STALE_MS,
+  DEFAULT_CONSUMED_STALE_MS,
+  LAST_CONSUMED_RELATIVE,
   DEFAULT_FRONT_DOOR_SERVICES,
   HANDOFF_MODES,
   sessionLiveFromHeartbeat,
+  sessionConsumedRecently,
   resolveFrontDoor,
   frontDoorServices,
   shouldDaemonDispatch,

package/lib/session/handoffs.mjs

@@ -28,6 +28,14 @@ export const DEFAULT_HANDOFF_DEADLINE_MS = 30 * 60_000;
 export const DEFAULT_HANDOFF_RETENTION_MS = 7 * 24 * 60 * 60_000;
 /** Handoff directory (relative to the agent root). */
 export const HANDOFFS_RELATIVE = "state/session/handoffs";
+/**
+ * WHEN the front door last consumed inbound (DARK-SEAT wedged-verdict).
+ * There are two consume paths — acking a handoff (this module, below) and an
+ * inbound claim/reply/done (session-runtime) — and both stamp this ONE file,
+ * so `collect.mjs#sessionWedge` has a single fact to read regardless of which
+ * path fired. Relative to the agent root, like every other state/ path here.
+ */
+export const LAST_CONSUMED_RELATIVE = "state/session/last-consumed.json";
 
 // A tick id is a bus event id (`evt-<iso>-<hex>`) or a test literal. It is a
 // path segment, so anything that could climb out of the directory is refused.
@@ -139,6 +147,47 @@ export function readHandoff(agentRoot, tickId, deps = {}) {
   return rec ? { ...rec, path } : null;
 }
 
+/**
+ * Stamp `LAST_CONSUMED_RELATIVE` with the current instant — the front door
+ * just consumed inbound. Best-effort by design: every caller of this (an ack,
+ * an inbound claim) has its own success/failure to report, and a stamp that
+ * cannot be written must never turn an otherwise-successful consume into a
+ * failure. Callers that need to know still get `{ok:false, error}` back; they
+ * are just not obliged to act on it.
+ *
+ * @param {string} agentRoot
+ * @param {{now?:number, fs?:object, writeJson?:Function}} [o]
+ * @returns {{ok:true, path:string}|{ok:false, error:string}}
+ */
+export function stampConsumed(agentRoot, o = {}) {
+  const fs = o.fs || nodeFs;
+  const writeJson = o.writeJson || writeJsonAtomicDefault;
+  const path = join(agentRoot, LAST_CONSUMED_RELATIVE);
+  try {
+    fs.mkdirSync(join(agentRoot, "state", "session"), { recursive: true });
+    writeJson(path, { ts: iso(nowOf(o)) });
+    return { ok: true, path };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Read `LAST_CONSUMED_RELATIVE` back as epoch ms, or `null` when absent or
+ * unreadable — fail-open, like every read in this ledger. `sessionWedge`
+ * treats `null` the same as "never consumed", not as "just now".
+ *
+ * @param {string} agentRoot
+ * @param {{fs?:object}} [deps]
+ * @returns {number|null}
+ */
+export function readLastConsumed(agentRoot, deps = {}) {
+  const fs = deps.fs || nodeFs;
+  const rec = readJson(fs, join(agentRoot, LAST_CONSUMED_RELATIVE));
+  const ms = rec ? Date.parse(rec.ts || "") : NaN;
+  return Number.isFinite(ms) ? ms : null;
+}
+
 /** Move an open handoff into done/ with a terminal status. */
 function retire(agentRoot, rec, patch, deps) {
   const fs = deps.fs || nodeFs;
@@ -181,6 +230,11 @@ export function ackHandoff(agentRoot, tickId, o = {}) {
       resultPath: o.resultPath || null,
       ...(o.note ? { note: String(o.note) } : {}),
     }, o);
+    // Consume path #1 (DARK-SEAT wedged-verdict): acking a handoff is proof
+    // the front door read and answered inbound. Best-effort — a stamp that
+    // fails to write must never turn a completed ack into a reported failure;
+    // the wedge verdict simply falls back to whatever it saw before.
+    try { stampConsumed(agentRoot, o); } catch { /* the ack already succeeded */ }
     return { ok: true, path };
   } catch (err) {
     return { ok: false, error: err && err.message ? err.message : String(err) };
@@ -285,6 +339,7 @@ export default {
   DEFAULT_HANDOFF_DEADLINE_MS,
   DEFAULT_HANDOFF_RETENTION_MS,
   HANDOFFS_RELATIVE,
+  LAST_CONSUMED_RELATIVE,
   handoffPaths,
   writeHandoff,
   listHandoffs,
@@ -292,4 +347,6 @@ export default {
   ackHandoff,
   expireHandoffs,
   pruneHandoffs,
+  stampConsumed,
+  readLastConsumed,
 };

package/lib/session/inbox-claims.mjs

@@ -43,6 +43,7 @@ import { join } from "node:path";
 import { readdirSync, readFileSync, existsSync, renameSync, statSync, openSync, ftruncateSync, writeSync, closeSync } from "node:fs";
 import { writeFileAtomic } from "../fs-atomic.mjs";
 import { readFrontDoorState } from "./frontdoor.mjs";
+import { stampConsumed } from "./handoffs.mjs";
 
 /** A session claim neither replied nor done within this window is reopened. */
 export const SESSION_CLAIM_STALE_MS = 20 * 60_000;
@@ -68,6 +69,21 @@ function iso(ms) { return new Date(ms).toISOString(); }
 function nowOf(o) { return typeof o.now === "number" ? o.now : Date.now(); }
 function q(v) { return `"${String(v).replace(/[\r\n]+/g, " ").replace(/"/g, "'")}"`; }
 
+/**
+ * Stamp the ONE `state/session/last-consumed.json` the front door reads to
+ * decide whether a live session is actually draining inbound (DM-LATENCY).
+ * This is the inbound consume path — a claim/reply/done — the mirror of the
+ * handoff-ack path in lib/session/handoffs.mjs; both stamp the same file, so
+ * `frontdoor.readFrontDoorState` has a single fact to read. Best-effort by
+ * design: a stamp that cannot be written must never turn an otherwise
+ * successful claim/reply/done into a failure. The injected `writeConsumed`
+ * seam (default `stampConsumed`) lets a test drive the failure path.
+ */
+function noteConsumed(agentRoot, o = {}) {
+  const stamp = typeof o.writeConsumed === "function" ? o.writeConsumed : stampConsumed;
+  try { stamp(agentRoot, { now: nowOf(o) }); } catch { /* the caller's own transition already succeeded */ }
+}
+
 /**
  * The marker lines to append below an item.
  * @param {{claimedBy?:string, claimedAt?:string, now?:number, deferredUntil?:number|string, deferredReason?:string, repliedAt?:number|string}} o
@@ -216,6 +232,7 @@ export function markSessionClaim(agentRoot, service, item, o = {}) {
     const body = stripSessionMarkers(readFileSync(dst, "utf-8"));
     const sep = body.endsWith("\n") || body === "" ? "" : "\n";
     writeFileAtomic(dst, body + sep + sessionMarkerLines({ claimedBy: o.by || "session", now: nowOf(o) }));
+    noteConsumed(agentRoot, o); // claiming an item is the front door draining inbound (DM-LATENCY)
     return { ok: true, path: dst };
   } catch (err) {
     return { ok: false, error: err && err.message ? err.message : String(err) };
@@ -248,6 +265,7 @@ export function markSessionReplied(agentRoot, service, item, o = {}) {
       repliedAt: nowOf(o),
     });
     writeInPlace(found.path, body + sep + markers);
+    noteConsumed(agentRoot, o); // replying is the front door draining inbound (DM-LATENCY)
     return { ok: true, path: found.path };
   } catch (err) {
     return { ok: false, error: err && err.message ? err.message : String(err) };
@@ -318,19 +336,46 @@ function retire(dir, file) {
 
 /**
  * Strip the session markers off a file in place (same inode). Exported for
- * the CLI's terminal transitions. Never throws; returns whether it wrote.
+ * the CLI's terminal transitions (`inbox done`). Never throws; returns whether
+ * it wrote.
+ *
+ * Finishing an item is also the front door draining inbound, so it advances
+ * the last-consumed stamp (DM-LATENCY) — the same consume signal a claim and a
+ * reply write. The item path is `<agentRoot>/state/inbox/<service>/<file>`, so
+ * the agent root is the path with those four segments removed; when it can be
+ * recovered, the consume is stamped best-effort. An explicit `o.agentRoot`
+ * wins, so a caller that already holds the root need not rely on the derivation.
+ *
  * @param {string} path
+ * @param {{now?:number, agentRoot?:string, writeConsumed?:Function}} [o]
  * @returns {boolean}
  */
-export function stripMarkersInPlace(path) {
+export function stripMarkersInPlace(path, o = {}) {
   try {
     const raw = readFileSync(path, "utf-8");
     const clean = stripSessionMarkers(raw);
     if (clean !== raw) writeInPlace(path, clean);
+    const agentRoot = o.agentRoot || agentRootFromInboxPath(path);
+    if (agentRoot) noteConsumed(agentRoot, o);
     return true;
   } catch { return false; }
 }
 
+/**
+ * Recover the agent root from an inbox item path
+ * (`<agentRoot>/state/inbox/<service>/<file>`) by dropping the last four
+ * segments — but only when the tail actually IS `state/inbox/<service>/<file>`,
+ * so a path of an unexpected shape yields null rather than a wrong root.
+ */
+function agentRootFromInboxPath(path) {
+  const parts = String(path || "").split(/[\\/]/);
+  if (parts.length < 5) return null;
+  const [file, service, inbox, state] = [parts[parts.length - 1], parts[parts.length - 2], parts[parts.length - 3], parts[parts.length - 4]];
+  void file; void service;
+  if (inbox !== "inbox" || state !== "state") return null;
+  return parts.slice(0, parts.length - 4).join("/") || "/";
+}
+
 /**
  * THE ASSURANCE SWEEP. Reopens (a) a session claim neither replied nor done
  * within `staleMs` (default 20 min), (b) a session deferral whose