@cohortapp/agent-sdk 2.18.5 → 2.18.7

package/lib/org/inbound/directedness.mjs

@@ -939,4 +939,94 @@ export default {
   matchesMyName,
   taskIdFromFileKey,
   surfaceDef,
+  isMissedHumanMessage,
+  missedHumanRecord,
 };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// A PERSON'S MESSAGE THAT THIS SEAT DROPPED
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Drop reasons that are NOT a person going unanswered, even when a human wrote
+ * the message. Each one says the room was never this seat's to read or the
+ * item was never a message at all, so counting it would bury the reasons that
+ * matter under noise every tick produces.
+ *
+ * `own_message` is here for the obvious reason; the membership/visibility ones
+ * because a room the seat cannot see is not a room it declined to answer in.
+ */
+const NOT_A_MISSED_PERSON = Object.freeze([
+  "own_message",
+  "channel_not_visible",
+  "not_a_member",
+  "membership_unknown",
+  "channel_kind_unknown",
+  "surface_disabled",
+]);
+
+/**
+ * PURE. Did this seat just drop a message a PERSON wrote in a room the seat
+ * belongs to?
+ *
+ * ── WHY THIS EXISTS ──────────────────────────────────────────────────────────
+ * `pullWideInbound` counts every drop into `stats.dropped[reason]` — a tally,
+ * by reason, with no identity and, unless something else happened that tick, no
+ * log line at all. That tally is why the 2026-09-21 #general roll-call took a
+ * reconstruction to explain: thirteen seats each incremented
+ * `dropped.no_mentions_not_threaded` by one and none of them said WHICH message
+ * or that a human had written it. A counter cannot be audited after the fact
+ * and cannot be correlated across seats.
+ *
+ * A person's message that this seat decided not to answer is a different class
+ * of event from ambient chatter it correctly ignored, and it is the only class
+ * anyone ever asks about afterwards. So it is named individually, once, at
+ * WARN — the same treatment `hydrate` already gives a body it could not read.
+ *
+ * Deliberately narrow, for the same reason the surface list is: this fires only
+ * for a MESSAGE-topic candidate, authored by a member the DIRECTORY says is
+ * HUMAN (never assumed from the absence of evidence), in a room whose
+ * membership this seat has PROVEN. Everything else is either not a person, not
+ * a room, or not knowable — and an over-broad warn line is a line operators
+ * learn to skip.
+ *
+ * @param {Candidate} cand
+ * @param {{directed:boolean, reason?:string}} verdict the resolved verdict
+ * @param {import("./facts.mjs").Facts} facts
+ * @param {string} me this seat's member id
+ * @returns {boolean}
+ */
+export function isMissedHumanMessage(cand, verdict, facts, me) {
+  if (!cand || !verdict || verdict.directed) return false;
+  if (cand.topic !== "message") return false;
+  const reason = String(verdict.reason || "");
+  if (NOT_A_MISSED_PERSON.includes(reason)) return false;
+  const channelId = cand.ids && cand.ids.channelId;
+  if (!channelId) return false;
+  // A room whose membership is PROVEN, not merely visible: a public channel the
+  // seat can read but has not joined does not address it.
+  const members = asSet(facts && facts.memberChannelIds);
+  if (!has(members, channelId)) return false;
+  const author = cand.actor;
+  if (!author || (me && String(author) === String(me))) return false;
+  // Proven human. `authorKindOf` returns "" when the directory read degraded,
+  // and an unknown author is NOT reported as a missed person — a degraded tick
+  // would otherwise warn about every message in every room.
+  return authorKindOf(facts, author) === "HUMAN";
+}
+
+/**
+ * PURE. The redaction-safe record of one missed person's message. No body, no
+ * prose: the ids an operator needs to go and look, plus the reason this seat
+ * gave. Mirrors the payload shape hq's `responder.silence` rows carry, so the
+ * two planes describe the same event in the same words.
+ */
+export function missedHumanRecord(cand, verdict) {
+  return {
+    seq: cand && cand.seq != null ? cand.seq : null,
+    messageId: (cand && cand.ids && cand.ids.messageId) || cand?.entityId || null,
+    channelId: (cand && cand.ids && cand.ids.channelId) || null,
+    author: (cand && cand.actor) || null,
+    reason: String((verdict && verdict.reason) || "unknown"),
+  };
+}

package/lib/org/inbound/index.mjs

@@ -55,7 +55,12 @@
 "use strict";
 
 import { read as clientRead } from "../client.mjs";
-import { classifyEvent, resolveDirected } from "./directedness.mjs";
+import {
+  classifyEvent,
+  resolveDirected,
+  isMissedHumanMessage,
+  missedHumanRecord,
+} from "./directedness.mjs";
 import { resolveFacts, DEFAULT_LIMITS } from "./facts.mjs";
 import { hydrate } from "./hydrate.mjs";
 import { toMessageEvent } from "./project.mjs";
@@ -106,6 +111,11 @@ export async function pullWideInbound(o = {}) {
     delivered: 0,
     bySurface: {},
     dropped: {},
+    // EVERY person's message this tick decided not to answer, named. See
+    // `directedness.mjs#isMissedHumanMessage`: `dropped` is a tally by reason
+    // and cannot say WHICH message or that a human wrote it, which is the only
+    // question anyone asks after a room goes quiet.
+    unanswered: [],
     degraded: [],
     calls: 0,
     reads: 0,
@@ -195,6 +205,18 @@ export async function pullWideInbound(o = {}) {
     const verdict = resolveDirected(cand, me, facts, { enabled, meAliases });
     if (!verdict.directed) {
       stats.dropped[verdict.reason] = (stats.dropped[verdict.reason] || 0) + 1;
+      // A PERSON's message this seat is dropping is not ambient chatter, and a
+      // counter is not a record of it. Name it — once, at WARN, with the ids —
+      // so "I posted and nobody replied" is answerable from this machine's own
+      // log instead of by reasoning backwards from thirteen tallies.
+      if (isMissedHumanMessage(cand, verdict, facts, me)) {
+        const rec = missedHumanRecord(cand, verdict);
+        stats.unanswered.push(rec);
+        log(
+          "warn",
+          `[inbound] NOT answering a person: message ${rec.messageId || cand.seq} in channel ${rec.channelId} from ${rec.author} — ${rec.reason}`
+        );
+      }
       continue;
     }
     directed.push({ cand, verdict });

package/lib/org/ui-parity.mjs

@@ -3317,7 +3317,19 @@ export function messagingSearch(params, o = {}) {
  * message ({ messageId }) or a channel over a window ({ channelId,
  * windowDays? }); one of the two is required. Each row carries the operator
  * reason (human_mentioned | addressed_to_human | nobody_elected |
- * no_responders) and its text. The agent-plane twin of the "Unanswered
+ * no_responders | handed_to_daemons) and its text; a `handed_to_daemons` row
+ * also carries `daemonDriven`, the seats hq stood down for — every eligible
+ * colleague in the room was answering from its OWN machine, so hq deliberately
+ * said nothing and a room that then heard nothing is a fault on the DAEMON
+ * plane, with the seat list already in hand.
+ *
+ * The same sentence is NOT repeated in `protocol.mjs`: that file is pinned by
+ * `protocol.checksum` to hq's vendored copy, so even a comment there is a
+ * cross-repo re-vendor (`scripts/sync-protocol.mjs`). The vocabulary's source
+ * of truth is hq `src/server/llm-responder/silence-verdict.ts`; this JSDoc is
+ * the agent-facing restatement of it.
+ *
+ * The agent-plane twin of the "Unanswered
  * messages" panel on /settings/ai — same reader, same decoder.
  * @param {object} params - { channelId?, messageId?, windowDays?, limit? }
  * @param {object} o - { base, token, fetchImpl? }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.18.5",
+  "version": "2.18.7",
   "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/plugins/maestro-skills/skills/seat-provision.md

@@ -0,0 +1,107 @@
+---
+name: seat-provision
+description: Bring a brand-new Mac mini or Mac Studio up as a working Cohort agent seat — SDK installed, profile pulled from Cohort, launchd jobs loaded, daemon beating, front door answering. Use when a new machine arrives, when a seat is being re-enrolled after a rebuild, or when someone asks how a colleague gets a machine.
+---
+
+# Bringing up a new seat
+
+A seat is one directory (`~/<firstname>`), three launchd jobs, and one org
+credential. It is finished when the machine **answers its humans**, not when
+the install completes.
+
+Run this on the machine itself, signed in as that seat's user. You cannot
+provision another agent's machine from yours.
+
+## Before you touch the machine
+
+Two things must exist first, and only a person with production access can make
+one of them:
+
+- **An org API key for this member.** Minted in hq by
+  `scripts/mint-avatar-agent-keys.ts --confirm` — one key per seat, never
+  shared, returned exactly once and unrecoverable afterwards. It is a
+  production database write and needs explicit authorisation.
+- **A Claude credential for the seat**, long-lived (`CLAUDE_CODE_OAUTH_TOKEN`)
+  rather than a keychain login that expires while nobody is watching.
+
+Never print either into a log, a commit, a message, or a terminal someone else
+can scroll back through.
+
+## Bring it up
+
+```bash
+cd ~
+npx -y @cohortapp/agent-sdk@latest create <firstname>
+cd ~/<firstname>
+npm install @cohortapp/agent-sdk@latest --save
+```
+
+Write `.env` (mode 600) with the seat's credential and
+`MAESTRO_PREFER_SUBSCRIPTION_AUTH=1`, then pull the profile from Cohort, which
+is the source of truth for who this colleague is:
+
+```bash
+COHORT_BASE=<org base url> \
+COHORT_API_KEY=<the minted key> \
+COHORT_ORG_ID=org_default_adaptic \
+COHORT_AGENT_ID=<slug> \
+node node_modules/@cohortapp/agent-sdk/bin/maestro.mjs setup --yes
+```
+
+**`COHORT_BASE` is silently required.** The profile pull fails open: leave it
+out and setup "succeeds" with an empty identity, no charter and no org config,
+and the seat then runs as nobody. Check `config/agent.json` and
+`config/org.yaml` are populated before going further — that check has caught
+this more than once.
+
+Then load the three jobs and start the lanes:
+
+```bash
+maestro upgrade --force-overwrite     # lays down plists, skills, scripts
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.maestro.<name>-daemon.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.maestro.<name>-autoupdate.plist
+maestro session start
+```
+
+## Prove it, before you call it done
+
+A new seat that looks installed and answers nobody is the normal failure mode.
+Five checks:
+
+1. **Identity is real.** `config/agent.json` has a name, a role and a charter —
+   not empty strings.
+2. **The org connection works.** The daemon log shows `org-mesh connected`, and
+   `state/org/last-beat.json` is fresh and `{"ok":true}`.
+3. **The seat is visible to the org.** It appears in the fleet view with its
+   hostname, version and a beat inside the last few minutes. If hq cannot see
+   it, nobody can route work to it.
+4. **The front door is live.** `maestro session status` — not `NOT LIVE`. A
+   first launch is where a modal is most likely to be waiting; read the pane
+   rather than assuming (see `seat-upgrade`).
+5. **A real message lands.** Ask a colleague to send one and watch it arrive in
+   `maestro inbox list` and get answered. Everything up to here proves the
+   plumbing; only this proves the seat.
+
+## Things that have actually gone wrong here
+
+- **A root-owned npm prefix** makes every global install fail. Give the seat
+  its own prefix (`npm config set prefix ~/.npm-global`) rather than using
+  `sudo`, which leaves files the seat cannot later update.
+- **Display names are not login names.** The person is "James Kirkland"; the
+  account is `James T Kirk`. Read the real login from the directory rather than
+  guessing from the display name.
+- **One live key per seat.** If a key was minted twice during a fumbled
+  enrolment, revoke the orphan — an unused credential is a liability, and two
+  live keys make it impossible to tell which machine is which.
+- **Confirm the autoupdater is armed** before you walk away. Without it the
+  seat never takes another release, and nothing will tell you: it simply stays
+  where it is while the fleet moves on.
+- **Shred the credential files** you staged during setup.
+
+## What to say afterwards
+
+The seat's name, its version, that it is beating, that the front door is live,
+and that a real message was answered. If any of the five checks did not pass,
+say which one and what is still needed — a half-provisioned seat that is
+reported as done is worse than one reported as blocked, because the work gets
+routed to it.

package/plugins/maestro-skills/skills/seat-upgrade.md

@@ -0,0 +1,108 @@
+---
+name: seat-upgrade
+description: Take this machine's @cohortapp/agent-sdk to a new version and prove the seat is still answering afterwards — the version, the daemon, the front door and the beat. Use when an upgrade notice arrives, when `maestro session status` says a restart is pending, when this seat is behind the fleet, or when someone asks you to update the SDK here.
+---
+
+# Upgrading this seat
+
+An upgrade is not `npm install`. It is: install, lay the framework files down,
+restart the two processes that were running the old code, and then **prove the
+seat still answers its humans**. The last step is the one that gets skipped,
+and skipping it is how a seat goes quiet for three days without anybody
+noticing.
+
+Everything here runs on **this** machine, as this seat's own user. You cannot
+reach another agent's machine and must not try.
+
+## What this seat runs, and which part an upgrade breaks
+
+Three long-lived things, and they fail independently:
+
+| | what it is | how it gets the new code |
+| --- | --- | --- |
+| **the daemon** | `ai.maestro.<name>-daemon`, polls Cohort, classifies, dispatches | must be kickstarted after the install |
+| **the front door** | `ai.maestro.<name>-session`, the long-lived Claude session that answers | must be restarted, and it is the one that hangs |
+| **the autoupdater** | hourly `ai.maestro.<name>-autoupdate` | runs the above by itself, hourly |
+
+If the hourly job already did this, you have nothing to do. Check before you
+act: `node scripts/fleet/rollout.mjs --verify-only --deadline 0` from the SDK
+repo if you have it, or simply read the installed version and compare it with
+the registry.
+
+## Do it
+
+```bash
+cd ~/<yourname>                       # your agent directory, not the SDK repo
+node -p "require('./node_modules/@cohortapp/agent-sdk/package.json').version"   # before
+npm view @cohortapp/agent-sdk version --prefer-online                          # target
+```
+
+`--prefer-online` matters: npm caches registry metadata and will happily serve
+you the previous version for many minutes after a publish. A version that looks
+unchanged is often a stale read, not a stalled release.
+
+```bash
+npm install @cohortapp/agent-sdk@<version> --save --no-audit --no-fund
+./node_modules/.bin/maestro upgrade --force-overwrite
+```
+
+`maestro upgrade` copies the framework (`lib/`, `scripts/`, skills, plists)
+into your agent directory. Files you own are protected by `.maestroignore`; it
+reports drift rather than clobbering them.
+
+Then restart both lanes, because **neither restarts itself**:
+
+```bash
+maestro session restart --force      # the front door: kill and relaunch
+launchctl kickstart -k gui/$(id -u)/ai.maestro.<name>-daemon
+```
+
+## Then prove it, which is the actual job
+
+An upgrade that installs and leaves the seat mute is a failed upgrade. Four
+checks, in this order, and none of them is "the process exists":
+
+1. **The version moved.** Re-read `node_modules/@cohortapp/agent-sdk/package.json`.
+2. **The daemon is beating.** `state/org/last-beat.json` should be fresh (under
+   five minutes) and `{"ok":true}`. A daemon can be alive and beating nothing.
+3. **The front door is live.** `maestro session status` must not say `NOT LIVE`.
+   A heartbeat older than a few minutes means it is wedged, not busy.
+4. **The seat answers.** Look at `maestro inbox list`: if items are arriving and
+   nothing is being answered, the seat is silent even though every process is
+   up.
+
+## When the front door will not come back
+
+This is the failure worth knowing by heart, because it has cost this
+organisation days of silence:
+
+**A blocked modal in the front-door session stops the seat answering
+anything.** The session process is alive, `ps` shows it, launchd is happy — and
+it is sitting on a dialog nobody pressed a key on. The one that did it was the
+subscription limit chooser (*"You've hit your weekly limit… 1. Stop and wait  2.
+Wait here, then continue automatically  3. Add funds  4. Upgrade your plan"*),
+which sat unanswered for 65 hours, including 41 hours **after** the limit had
+already reset.
+
+Since 2.18.6 the supervisor handles this itself: it captures the pane, names
+the modal, answers it when the answer is free and known by name, and restarts
+the session when it is not. If you are on an older build, or it has given up
+after its bounded retries, do it by hand:
+
+```bash
+maestro session status                                   # NOT LIVE? read on
+screen -S maestro-<name> -p 0 -X hardcopy /tmp/pane.txt  # or: tmux capture-pane -p -t =maestro-<name>
+cat /tmp/pane.txt                                        # WHAT IS ON THE SCREEN
+```
+
+Read it before you act. **Never answer a modal option that spends money** —
+"Add funds" and "Upgrade your plan" are not yours to press. If the safe option
+is on screen, send its key; otherwise `maestro session restart --force`, which
+always works and costs only the session's context.
+
+## What to say afterwards
+
+Report the version before and after, the beat age, whether the front door is
+live, and anything you had to clear by hand. If you cleared a modal, say which
+one — it is a fleet-wide signal, not a local curiosity, and it is how the next
+seat's failure gets recognised in seconds instead of days.

package/scripts/session/supervisor.mjs

@@ -53,6 +53,7 @@ import { resolveAgentRoot } from "../../lib/agent-root.mjs";
 import { writeJsonAtomic as fsWriteJsonAtomic, writeFileAtomic as fsWriteFileAtomic } from "../../lib/fs-atomic.mjs";
 import { parseHeartbeat } from "../../lib/session/liveness.mjs";
 import { ensureClaudeConfig, heartbeatSilence, attentionRecord, HEARTBEAT_GRACE_MS } from "../../lib/session/first-run.mjs";
+import { paneTail, classifyPane, watchdogAction, captureCommand, sendKeyCommand } from "../../lib/session/pane.mjs";
 import { acquireLock as singletonAcquireLock } from "../../lib/singleton.js";
 import { buildSpawn } from "../../lib/runtime/adapter.mjs";
 import { resolveSeatSpawn } from "../../lib/runtime/seat-engine.mjs";
@@ -332,15 +333,95 @@ export async function runSupervisor(deps = {}) {
   const startedAt = Number(d.now());
   let launchFailed = false;
   stopCmd = cmds.stop;
-  const cancelWatchdog = d.after(d.heartbeatGraceMs, () => {
+  // ── THE WATCHDOG ────────────────────────────────────────────────────────
+  //
+  // It used to fire ONCE: write attention.json, log "attach and answer it",
+  // and then leave the session wedged for the rest of its life. On 2026-09-24
+  // three seats had been silent for days behind that note — and the note was a
+  // guess ("probably a first-run dialog or a permission prompt") that was
+  // wrong. The real modal, captured off this seat's own pane, was the
+  // subscription-limit chooser, still unanswered 41 hours after the limit had
+  // reset. The fleet accepts no ssh, so the instruction it printed could not be
+  // carried out by anyone.
+  //
+  // So it now RECURS and ACTS: capture the pane, name what is on it, answer it
+  // if the answer is free and known by name, else restart the session. Bounded,
+  // because a supervisor that restarts every two minutes for three days is a
+  // worse failure than the one it replaces. Every pass records what it saw, so
+  // the note stops being a guess and becomes evidence.
+  let clears = 0;
+  let restarts = 0;
+  let watchdogStopped = false;
+  let cancelPass = () => {};
+  const paneFile = join(agentRoot, "state", "session", "pane-capture.txt");
+
+  const capturePane = async () => {
+    const cmd = captureCommand(mux, muxName, paneFile);
+    try {
+      const r = await d.execFile(cmd.file, cmd.args, { cwd: agentRoot, env: d.env });
+      if (cmd.via === "stdout") return String((r && r.stdout) || "");
+      try { return d.readFileSync(paneFile, "utf8"); } catch { return ""; }
+    } catch { return ""; }
+  };
+
+  const sendKeys = async (keys) => {
+    for (const k of keys) {
+      const cmd = sendKeyCommand(mux, muxName, k);
+      try { await d.execFile(cmd.file, cmd.args, { cwd: agentRoot, env: d.env }); } catch { return false; }
+      await d.sleep(250);
+    }
+    return true;
+  };
+
+  const watchdogPass = async () => {
+    if (watchdogStopped) return;
+    // Retire the timer that just fired before scheduling the next one, so the
+    // pass that ends the session cancels exactly one live timer and leaves
+    // nothing behind.
+    try { cancelPass(); } catch { /* already fired */ }
     let hb = null;
     try { hb = parseHeartbeat(d.readFileSync(paths.heartbeatFile, "utf8")); } catch { hb = null; }
     const silence = heartbeatSilence({ startedAt, heartbeat: hb, now: d.now(), graceMs: d.heartbeatGraceMs });
-    if (!silence.silent) return;
+    if (!silence.silent) { schedulePass(); return; }
+
+    const pane = paneTail(await capturePane());
+    const seen = classifyPane(pane);
+    const act = watchdogAction({ silent: true, kind: seen.kind, keys: seen.keys, clears, restarts });
+
     const rec = attentionRecord({ reason: silence.reason, mux, muxName, since: startedAt, runMs: silence.runMs });
-    try { d.writeJsonAtomic(paths.attentionFile, rec); } catch { /* the log line still says it */ }
-    d.log(`session ${muxName} has been up ${Math.round(silence.runMs / 1000)} s with no heartbeat — probably blocked on a first-run dialog or a permission prompt; attach with \`${rec.attach}\` and answer it`);
-  });
+    // The record now carries WHAT THE SCREEN SAYS and what was done about it.
+    // `hint` keeps the attach line for a human who is at the machine, but it is
+    // no longer the only remedy on offer.
+    const record = { ...rec, modal: seen.kind, modalWhy: seen.why, pane, action: act.act, actionReason: act.reason, clears, restarts };
+    try { d.writeJsonAtomic(paths.attentionFile, record); } catch { /* the log line still says it */ }
+    d.log(`session ${muxName} silent ${Math.round(silence.runMs / 1000)} s — screen shows: ${seen.kind} (${seen.why}); ${act.reason}`);
+
+    if (act.act === "clear") {
+      clears += 1;
+      d.log(`session ${muxName}: answering ${seen.kind} with ${JSON.stringify(seen.choice || seen.keys)}`);
+      await sendKeys(seen.keys);
+    } else if (act.act === "restart") {
+      restarts += 1;
+      d.log(`session ${muxName}: restarting (${restarts}) — the session is not answering and the screen cannot be cleared safely`);
+      try { await d.execFile(cmds.stop.file, cmds.stop.args, { cwd: agentRoot, env: d.env }); } catch { /* the relaunch loop handles a dead mux */ }
+      watchdogStopped = true; // the supervisor's own loop relaunches; do not fight it
+      return;
+    } else if (act.act === "give-up") {
+      // Stop thrashing, keep saying so. The beat carries `attention` and hq
+      // alerts on it; this is the state a person genuinely has to see.
+      d.log(`session ${muxName}: ${act.reason}`);
+      watchdogStopped = true;
+      return;
+    }
+    schedulePass();
+  };
+
+  const schedulePass = () => {
+    if (watchdogStopped) return;
+    cancelPass = d.after(d.heartbeatGraceMs, () => { watchdogPass().catch(() => {}); });
+  };
+  schedulePass();
+  const cancelWatchdog = () => { watchdogStopped = true; try { cancelPass(); } catch { /* already fired */ } };
   const dropEnvFile = () => { if (envFile) { try { d.unlinkSync(envFile); } catch { /* the session consumed it */ } } };
   try {
     // The engine's env (seat token, every Claude credential scrubbed) rides the