@cohortapp/agent-sdk 2.18.6 → 2.18.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.18.6",
+  "version": "2.18.8",
   "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/local-triggers/autoupdate.sh

@@ -417,6 +417,46 @@ restart_daemon(){
   if [ -z "$DAEMON_LABEL" ]; then log "no -daemon plist under ~/Library/LaunchAgents — nothing to kickstart (maestro upgrade installs it; doctor will say)"; return 0; fi
   launchctl kickstart -k "gui/$UID_/$DAEMON_LABEL" >> "$LOG" 2>&1 || log "WARN: kickstart $DAEMON_LABEL nonzero"
 }
+session_beating(){ # is the front door actually ANSWERING, not merely loaded?
+  # `session_reconciled` asks whether the job is loaded and a supervisor process
+  # is alive. Both were true on the seats that went silent: on 2026-09-24 three
+  # front doors had been wedged on an unanswered modal for days with their
+  # supervisors up and their jobs loaded. A process that exists is not a
+  # colleague who answers — the same substitution this gate's daemon half was
+  # rewritten to stop making.
+  local hb="$AGENT_DIR/state/session/heartbeat.json" age
+  [ -f "$hb" ] || return 1
+  age="$(node -e '
+    try {
+      const j = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+      const t = Date.parse(j && j.ts);
+      process.stdout.write(Number.isFinite(t) ? String(Math.round((Date.now() - t) / 1000)) : "");
+    } catch {}
+  ' "$hb" 2>/dev/null)"
+  [ -n "$age" ] || return 1
+  [ "$age" -le "$SESSION_STALE_S" ]
+}
+
+revive_session(){ # a wedged front door cannot restart itself; restart it FOR it
+  # The upgrade notice asks the session to restart "at an idle moment". A
+  # session sitting on a modal never reaches an idle moment, so the polite ask
+  # is exactly the wrong instrument for the one case that needs it. A hard
+  # kickstart drops a wedged session and the new supervisor launches a fresh
+  # one — which clears the modal by construction and, from this release,
+  # watches the pane so it does not happen again.
+  [ -n "$SESSION_LABEL" ] || return 0
+  # An UNLOADED job is a different fault with a different remedy (`maestro
+  # session start`), and kickstarting a label launchd does not know just fails.
+  # Leave that one to session_reconciled, which already names it.
+  label_loaded "$SESSION_LABEL" || return 0
+  session_beating && return 0
+  log "front door $SESSION_LABEL is loaded but not beating (> ${SESSION_STALE_S}s) — kickstarting it rather than waiting for a session that cannot answer"
+  launchctl kickstart -k "gui/$(id -u)/$SESSION_LABEL" >> "$LOG" 2>&1 \
+    && { log "front door $SESSION_LABEL restarted"; return 0; }
+  log "WARN: could not kickstart $SESSION_LABEL (maestro session restart --force)"
+  return 1
+}
+
 session_reconciled(){ # only asked when a -session plist was generated; never a rollback reason
   label_loaded "$SESSION_LABEL" || { log "reconcile-failed: session job $SESSION_LABEL is not loaded (maestro session start)"; return 1; }
   pgrep -f "$AGENT_DIR/scripts/session/supervisor" >/dev/null 2>&1 || { log "reconcile-failed: $SESSION_LABEL is loaded but no supervisor process is alive for $AGENT_DIR (maestro session status)"; return 1; }
@@ -544,6 +584,12 @@ if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V |
   if is_healthy; then
     log "healthy on $CUR"
     sibling_job_audit
+    # The up-to-date path is NOT exempt from the front door, for the same
+    # reason it stopped being exempt from the daemon: the seats that went
+    # silent for days were all "up to date". A daemon that beats while the
+    # front door is wedged is a seat that looks perfect from here and answers
+    # nobody.
+    revive_session || true
     if [ -n "$STALE_HOP" ]; then
       # A real version hop: complete it the way an automatic one completes —
       # the notice tells the session to restart itself onto the new code.
@@ -597,6 +643,11 @@ fi
 # installed version, never a LATEST). Fail-open: an unreadable last.json holds
 # nothing.
 FAILED_HOLD_S="${MAESTRO_AUTOUPDATE_FAILED_HOLD_S:-86400}"
+# How long a front door may go without beating before this run restarts it FOR
+# it. Ten minutes: long enough that a busy session is never interrupted (the
+# heartbeat rides every tool use), short enough that a wedged one is measured in
+# minutes rather than the days it took to notice the last three.
+SESSION_STALE_S="${MAESTRO_SESSION_STALE_S:-600}"
 failed_hold_reason(){ # prints "<reason> at <at>" when LATEST failed health within FAILED_HOLD_S
   node -e '
     const [file, latest, holdS] = process.argv.slice(1);
@@ -668,7 +719,11 @@ restart_daemon
 
 if is_healthy; then
   REASON=""
-  if [ -n "$SESSION_LABEL" ] && ! session_reconciled; then REASON="session-reconcile-failed"; fi
+  # Revive BEFORE reconciling: the new code is installed, and a front door that
+  # is not beating must be restarted onto it rather than left holding an inbox
+  # it cannot answer.
+  revive_session || REASON="session-revive-failed"
+  if [ -n "$SESSION_LABEL" ] && ! session_reconciled; then REASON="${REASON:-session-reconcile-failed}"; fi
   log "OK: healthy on $LATEST${REASON:+ ($REASON)}"
   sibling_job_audit
   write_upgrade_notice "$CUR" "$LATEST"

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