@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/telemetry/collect.mjs

@@ -84,7 +84,21 @@
  *       // Also on `machine` (open record), so hq's fleet view can show it next
  *       // to sdkVersion without a schema change. `ok` is the attempt's verdict:
  *       // true = healthy on `to`; false = install failed or rolled back to `from`.
- *       upgrade?: { at: ISO8601, from: string, to: string, ok: boolean },
+ *       upgrade?: { at: ISO8601, from: string, to: string, ok: boolean,
+ *                   reason?: string, healthy?: boolean },  // reason: WHY a failure failed
+ *       // THE BEATING DAEMON — which process is emitting this beat, what code
+ *       // it is actually running, and the last health-gate verdict on it.
+ *       // Also on `machine` (open record). `sdkVersion` ABOVE is what is
+ *       // INSTALLED on the seat; `daemon.sdkVersion` is what the running
+ *       // process booted on, and the two differ for exactly as long as an
+ *       // installed upgrade has not been restarted onto. `pid`+`bootAt` make a
+ *       // crash loop visible org-side (a pid that moves every beat), which is
+ *       // the failure that hid for six days behind an hourly "up to date".
+ *       // `dashboardAt` is the stamp of the file these came from, so a reader
+ *       // can age the claim; it is never a liveness signal on its own.
+ *       daemon?: { pid?: number, bootAt?: ISO8601, uptimeS?: number,
+ *                  sdkVersion?: string, dashboardAt?: ISO8601,
+ *                  healthy?: boolean, healthReason?: string },
  *     },
  *     claudeAuth: "ok"|"relogin_required"|"unknown",
  *     alerts: [{ id, severity, kind, detail }],
@@ -120,6 +134,7 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { writeJsonAtomic } from "../fs-atomic.mjs";
 import { probeClaude as defaultProbeClaude } from "../setup/claude-probe.mjs";
+import { readSeatEngine } from "../runtime/adapter.mjs";
 
 import { list as listPresence } from "../collective/presence.mjs";
 import { billableUsd } from "../cost/ledger-row.mjs";
@@ -433,18 +448,64 @@ export async function collectMachine(o = {}) {
     if (Number.isFinite(disk)) machine.diskUsedPct = pct(disk);
   }
 
+  // IDENTITY (§3.8) — hostname / tailnetIp / sdkVersion: where the seat is and
+  // what it runs. Collected FIRST and on its own terms, no longer as a rider on
+  // the inventory probe.
+  //
+  // WHY IT MOVED. It used to be read out of `collectInventory`'s return, inside
+  // `if (o.inventory !== false)` and with no try of its own. Three ways that
+  // lost the one field a fleet rollout is verified by, none of them about
+  // identity: a caller that turned inventory off lost it as a side effect; a
+  // `system_profiler` fork that threw took the whole `collectMachine` down with
+  // it (`collectStatus` then substitutes a bare `{loadavg, memUsedPct}` floor —
+  // the beat still goes, carrying neither the host stats nor the version); and
+  // a seat in that state stayed in it, beat after beat, with nothing on the box
+  // or in the org saying why. Identity is three cheap, independent reads and it
+  // is what an operator is looking for; it should not be able to fail because a
+  // hardware probe did. Each field is independently fail-open inside
+  // `collectIdentity`, and the try here is the outer guard for the probe seam.
+  //
+  // The results are handed on to `collectInventory` below so the tailnet probe
+  // forks once per beat, not twice.
+  let identity = {};
+  if (o.identity !== false) {
+    try { identity = await collectIdentity(o, osImpl); } catch { identity = {}; }
+    if (identity.hostname) machine.hostname = identity.hostname;
+    if (identity.tailnetIp) machine.tailnetIp = identity.tailnetIp;
+    if (identity.sdkVersion) machine.sdkVersion = identity.sdkVersion;
+  }
+
   // INVENTORY — device / ram / cores. Cached on disk (see collectInventory):
   // the chip and the installed RAM do not change between beats, so the
   // system_profiler fork happens once per machine, not every 30 seconds.
+  //
+  // WRAPPED, and the try is not decorative. `collectInventory` is not total:
+  // `execFileSafe` swallows a failing FORK, but the reads around it do not all
+  // have a try of their own (the platform read at the top of the probe block is
+  // the live example), so the function can and does throw. Before identity was
+  // hoisted above this, that throw propagated out of `collectMachine` and
+  // `collectStatus` substituted its bare `{loadavg, memUsedPct}` floor — the
+  // beat went out carrying neither host stats NOR the version, which is how two
+  // seats beat for days with no hostname and no sdkVersion. Now it costs its
+  // own three fields and nothing else.
   if (o.inventory !== false) {
-    const inv = await collectInventory(o);
-    if (inv.device) machine.device = inv.device;
-    if (inv.ram) machine.ram = inv.ram;
-    if (Number.isFinite(inv.cores)) machine.cores = inv.cores;
-    // IDENTITY (§3.8) — where the seat is and what it runs.
-    if (inv.hostname) machine.hostname = inv.hostname;
-    if (inv.tailnetIp) machine.tailnetIp = inv.tailnetIp;
-    if (inv.sdkVersion) machine.sdkVersion = inv.sdkVersion;
+    try {
+      const inv = await collectInventory({
+        ...o,
+        // Hand the identity answers on so the tailnet probe forks ONCE per
+        // beat, not twice. An empty string is an answer ("probed, none
+        // found") — and when `identity` is switched off entirely it is the
+        // right answer to hand on: a caller that asked for no identity should
+        // not pay for a tailnet fork inside the inventory probe either.
+        // `collectInventory` still returns those two fields; we ignore them —
+        // `machine.hostname/tailnetIp/sdkVersion` are set above or not at all.
+        tailnetIp: typeof o.tailnetIp === "string" ? o.tailnetIp : String(identity.tailnetIp || ""),
+        sdkVersion: typeof o.sdkVersion === "string" ? o.sdkVersion : String(identity.sdkVersion || ""),
+      });
+      if (inv.device) machine.device = inv.device;
+      if (inv.ram) machine.ram = inv.ram;
+      if (Number.isFinite(inv.cores)) machine.cores = inv.cores;
+    } catch { /* device/ram/cores drop; identity above already landed */ }
   }
 
   // spend24h — the agent's own rolling 24h LLM spend, off the cost ledger.
@@ -1307,7 +1368,142 @@ export function upgradeSummary(last) {
   const at = typeof last.at === "string" ? last.at : "";
   const to = typeof last.to === "string" ? last.to : "";
   if (!at || !to) return null;
-  return { at, from: typeof last.from === "string" ? last.from : "", to, ok: last.ok === true };
+  // `reason` and `healthy` are the two fields autoupdate.sh has always written
+  // to state/autoupdate/last.json and this projection used to drop. Without
+  // them a failed attempt reaches the org as a bare `ok:false` — which is the
+  // state three seats were in on 2026-09-24: provably behind, provably having
+  // tried, and no way to learn WHY short of reading a file on a machine nobody
+  // could reach. "install-failed" and "unhealthy-rolled-back" are different
+  // problems with different fixes and they looked identical from here.
+  //
+  // Bounded on the way out: a reason is a short token plus at most a trimmed
+  // error line, and the beat is not a log shipper.
+  const reason = typeof last.reason === "string" ? last.reason.trim().slice(0, 300) : "";
+  return {
+    at,
+    from: typeof last.from === "string" ? last.from : "",
+    to,
+    ok: last.ok === true,
+    ...(reason ? { reason } : {}),
+    ...(typeof last.healthy === "boolean" ? { healthy: last.healthy } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Daemon — WHICH process is beating, what code it is running, and the gate's
+// last verdict on it (`machine.daemon`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Top-level scalars we lift out of state/dashboards/daemon-health.yaml. The file
+ * is written by scripts/daemon/health.mjs as flat `key: value` lines plus one
+ * indented `dispatcher:` JSON block, so a line regex over the UNINDENTED lines
+ * reads it exactly and cannot be confused by the nested block. We do NOT pull a
+ * YAML parser in for four scalars on a 30-second loop.
+ *
+ * Fail-open → null (no file, unreadable, or no recognisable line).
+ * @param {string} text
+ * @returns {{pid?:number, sdkVersion?:string, installedSdkVersion?:string,
+ *            versionsAgree?:boolean, versionDrift?:string, bootAt?:string,
+ *            updatedAt?:string, uptimeS?:number}|null}
+ */
+export function parseDaemonHealthYaml(text) {
+  if (typeof text !== "string" || text === "") return null;
+  const out = {};
+  for (const line of text.split("\n")) {
+    // Unindented `key: value` only — an indented line belongs to `dispatcher:`.
+    const m = /^([a-z_]+):[ \t]+(.+?)[ \t]*$/.exec(line);
+    if (!m) continue;
+    const [, k, v] = m;
+    if (k === "pid") { const n = Number(v); if (Number.isInteger(n) && n > 0) out.pid = n; }
+    else if (k === "sdk_version") { const s = v.trim(); if (s && s !== "undefined" && s !== "null") out.sdkVersion = s; }
+    // The three the resolver added so a version can be CHECKED and not merely
+    // read. `sdk_version_agrees` is a tri-state written as a word: "unknown"
+    // is not false and must never collapse to one.
+    else if (k === "sdk_version_installed") { const s = v.trim(); if (s && s !== "undefined" && s !== "null") out.installedSdkVersion = s; }
+    else if (k === "sdk_version_agrees") { const s = v.trim(); if (s === "true" || s === "false") out.versionsAgree = s === "true"; }
+    else if (k === "sdk_version_drift") { const s = v.trim(); if (s && s !== "undefined" && s !== "null") out.versionDrift = s; }
+    else if (k === "daemon_start") { const s = v.trim(); if (!Number.isNaN(Date.parse(s))) out.bootAt = new Date(Date.parse(s)).toISOString(); }
+    else if (k === "updated") { const s = v.trim(); if (!Number.isNaN(Date.parse(s))) out.updatedAt = new Date(Date.parse(s)).toISOString(); }
+    else if (k === "uptime_s") { const n = Number(v); if (Number.isFinite(n) && n >= 0) out.uptimeS = Math.floor(n); }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/** state/dashboards/daemon-health.yaml as text, or "" — fail-open. */
+function readDaemonHealthText(agentRoot) {
+  if (!agentRoot) return "";
+  try {
+    return readFileSync(join(resolve(agentRoot), "state", "dashboards", "daemon-health.yaml"), "utf8");
+  } catch { return ""; }
+}
+
+/**
+ * Pure: the beat's `machine.daemon` — WHO is beating and whether the last health
+ * gate believed it.
+ *
+ * WHY THIS FIELD EXISTS. `machine.sdkVersion` is the version INSTALLED on the
+ * seat. It is not the version RUNNING: autoupdate installs into node_modules
+ * while the old daemon process keeps executing the code it booted on, and a
+ * hand-run `maestro upgrade` never restarts the daemon at all. One seat logged
+ * "up to date" hourly for six days while its daemon crash-looped on the
+ * previous version ~25 s at a time; the org saw nothing, because nothing the
+ * beat carried could tell the two versions apart. `pid` + `bootAt` make the
+ * distinction visible org-side: a pid that changes every beat is a crash loop,
+ * and `sdkVersion` here differing from `machine.sdkVersion` is an installed-but-
+ * not-restarted seat. Neither needs an ssh tour to see any more.
+ *
+ * ADDITIVE AND SMALL — six scalars, every one optional. It rides `machine`,
+ * which hq validates as an OPEN record (`presence/beat.ts#statusSchema`), so it
+ * lands the moment the daemon emits it and renders when the reader learns it.
+ * It is NOT put on `session`, whose hq schema is `.strict()` and would refuse
+ * the whole beat.
+ *
+ * FRESHNESS. `pid`/`bootAt`/`sdkVersion` describe the process that wrote the
+ * dashboard, which a DEAD daemon leaves behind verbatim. `dashboardAt` is that
+ * file's own stamp, carried so a reader can age the claim rather than trust it;
+ * the ledger beat's server-stamped `at` remains the only liveness signal.
+ *
+ * @param {object|null} dash  parsed daemon-health.yaml scalars, or null
+ * @param {object|null} last  state/autoupdate/last.json, or null
+ * THE SEAT'S OWN VERDICT RIDES ALONG. `installedSdkVersion` + `versionsAgree`
+ * are what the daemon's resolver concluded on the box, where both files are
+ * readable; hq compares `machine.sdkVersion` against `machine.daemon.sdkVersion`
+ * and reaches the same conclusion from the outside. Carrying both is not
+ * redundancy — they are read at different instants from different files, and a
+ * reader that sees them disagree has learned something real. `versionsAgree` is
+ * carried ONLY as a real boolean: an inferred running version yields no verdict
+ * at all, and absence must never read as agreement.
+ *
+ * @returns {{pid?:number, bootAt?:string, uptimeS?:number, sdkVersion?:string,
+ *            installedSdkVersion?:string, versionsAgree?:boolean,
+ *            versionDrift?:string, dashboardAt?:string, healthy?:boolean,
+ *            healthReason?:string}|null}
+ */
+export function daemonSummary(dash, last) {
+  const out = {};
+  if (dash && typeof dash === "object") {
+    if (Number.isInteger(dash.pid) && dash.pid > 0) out.pid = dash.pid;
+    if (typeof dash.bootAt === "string" && dash.bootAt) out.bootAt = dash.bootAt;
+    if (Number.isFinite(dash.uptimeS) && dash.uptimeS >= 0) out.uptimeS = Math.floor(dash.uptimeS);
+    if (typeof dash.sdkVersion === "string" && dash.sdkVersion) out.sdkVersion = dash.sdkVersion;
+    if (typeof dash.installedSdkVersion === "string" && dash.installedSdkVersion) out.installedSdkVersion = dash.installedSdkVersion;
+    if (typeof dash.versionsAgree === "boolean") out.versionsAgree = dash.versionsAgree;
+    if (dash.versionsAgree === false && typeof dash.versionDrift === "string" && dash.versionDrift) out.versionDrift = dash.versionDrift.slice(0, 200);
+    if (typeof dash.updatedAt === "string" && dash.updatedAt) out.dashboardAt = dash.updatedAt;
+  }
+  // The health GATE's verdict, as autoupdate.sh last recorded it
+  // (`{from,to,at,ok,healthy,reason}`). `healthy` is the gate's answer about the
+  // DAEMON — pid stability, no fatal line since boot, a server-acknowledged
+  // beat — which is a different question from `upgrade.ok` (did the last install
+  // land). Only a real boolean is carried: a record written before the gate
+  // existed has no opinion, and absence must not read as "healthy".
+  if (last && typeof last === "object" && typeof last.healthy === "boolean") {
+    out.healthy = last.healthy;
+    const reason = typeof last.reason === "string" ? last.reason.trim() : "";
+    if (!last.healthy && reason) out.healthReason = reason.slice(0, 200);
+  }
+  return Object.keys(out).length > 0 ? out : null;
 }
 
 /** state/autoupdate/last.json, or null. */
@@ -1570,7 +1766,12 @@ function subscriptionModeFromEnv(agentRoot, env) {
 function probeAuthForBeat(o, nowMs) {
   if (o.probeClaude === false) return "unknown";
   const agentRoot = resolve(o.agentRoot);
-  if (!subscriptionModeFromEnv(agentRoot, o.env || process.env)) return "unknown";
+  // W4 integration (row 25): an engine-cohort seat's probe is the engine's `auth status` — a
+  // real call to the gateway that proves the seat credential — so it is asked whatever the
+  // seat's Claude env says. A claude seat still probes only on the subscription path.
+  let cohortSeat = false;
+  try { cohortSeat = (o.seatEngine || readSeatEngine)(agentRoot) === "cohort"; } catch { cohortSeat = false; /* unreadable config: the default engine */ }
+  if (!cohortSeat && !subscriptionModeFromEnv(agentRoot, o.env || process.env)) return "unknown";
   const injected = typeof o.probeClaude === "function";
   if (!injected) {
     const hit = _authProbeMemo.get(agentRoot);
@@ -1737,6 +1938,21 @@ export async function collectStatus(o = {}) {
     if (up) machine.upgrade = up;
   } catch { /* no upgrade field */ }
 
+  // 4d. WHO is beating — `machine.daemon` {pid, bootAt, uptimeS, sdkVersion,
+  // dashboardAt, healthy?, healthReason?}. This is what makes fleet version
+  // drift a QUERY instead of an ssh tour: `machine.sdkVersion` is what is
+  // INSTALLED, `machine.daemon.sdkVersion` is what is RUNNING, and a pid that
+  // moves every beat is a crash loop. Fail-open in the same way every other
+  // probe here is — a throw drops the field, never the beat.
+  try {
+    const dash = opt.daemonDashboard !== undefined
+      ? opt.daemonDashboard
+      : parseDaemonHealthYaml(readDaemonHealthText(opt.agentRoot));
+    const last = opt.autoupdateLast !== undefined ? opt.autoupdateLast : readAutoupdateLast(opt.agentRoot);
+    const d = daemonSummary(dash, last);
+    if (d) machine.daemon = d;
+  } catch { /* no daemon field */ }
+
   const status = {
     state,
     activity: act.activity || "idle",
@@ -1782,6 +1998,8 @@ export const _internals = {
   sessionJobInstalled,
   readSessionAttention,
   upgradeSummary,
+  parseDaemonHealthYaml,
+  daemonSummary,
   detectClaudeAuth,
   resetAuthProbeCache,
   scanForRelogin,

package/lib/upgrade/ignored-drift.mjs

@@ -0,0 +1,105 @@
+/**
+ * lib/upgrade/ignored-drift.mjs — what a `.maestroignore`-protected file is
+ * missing from upstream, said per file.
+ *
+ * `maestro upgrade` never touches a path `.maestroignore` names — that is the
+ * file's whole purpose. Until this module, the summary said only "14 ignored
+ * (.maestroignore protected)": a count, with no way to tell from the log
+ * whether a protected fork was one line behind upstream or a whole release
+ * behind. On one seat the protected daemon lacked 24 upstream references to a
+ * feature the release notes said had shipped, and nothing in any upgrade log
+ * said so. A protected file is a fork the operator owns, and an owner needs a
+ * per-file answer to "how far has upstream moved under this?".
+ *
+ * `classifyIgnored` is PURE over the two texts (either may be null for absent)
+ * and answers one of:
+ *
+ *   identical        — the protection is currently idle (safe to drop the entry)
+ *   local-only       — the seat has it, upstream ships nothing at that path
+ *   upstream-only    — upstream ships it, the seat has never taken it
+ *   drifts           — both exist and differ: `onlyHere` / `onlyUpstream` are
+ *                      the line counts each side has that the other does not
+ *
+ * The line counts are a MULTISET difference, not an edit script: cheap, stable
+ * across a whole tree, and honest about what they are — a size of drift, not a
+ * patch. A moved block counts as zero drift, which is the right answer for
+ * "is upstream's fix in here?" and the wrong one for "is this file identical?"
+ * (that is `identical`, decided by bytes first).
+ *
+ * @module lib/upgrade/ignored-drift
+ */
+
+"use strict";
+
+/** Where `maestro upgrade` writes the report, relative to the agent root. */
+export const IGNORED_DRIFT_REL = ".maestro/ignored-drift.json";
+
+/**
+ * Multiset line difference of two texts.
+ * @param {string} a
+ * @param {string} b
+ * @returns {{onlyA:number, onlyB:number}}
+ */
+export function lineDrift(a, b) {
+  const count = (text) => {
+    const m = new Map();
+    for (const line of String(text).split("\n")) m.set(line, (m.get(line) || 0) + 1);
+    return m;
+  };
+  const ma = count(a);
+  const mb = count(b);
+  let onlyA = 0;
+  let onlyB = 0;
+  for (const [line, n] of ma) onlyA += Math.max(0, n - (mb.get(line) || 0));
+  for (const [line, n] of mb) onlyB += Math.max(0, n - (ma.get(line) || 0));
+  return { onlyA, onlyB };
+}
+
+/**
+ * Classify one protected path.
+ * @param {string} path            repo-relative path (reported back verbatim)
+ * @param {string|null} localText  the seat's bytes, or null when absent
+ * @param {string|null} upstreamText the package's bytes, or null when absent
+ * @returns {{path:string, state:"identical"|"local-only"|"upstream-only"|"drifts", onlyHere?:number, onlyUpstream?:number}}
+ */
+export function classifyIgnored(path, localText, upstreamText) {
+  const hasLocal = typeof localText === "string";
+  const hasUpstream = typeof upstreamText === "string";
+  if (hasLocal && !hasUpstream) return { path, state: "local-only" };
+  if (!hasLocal && hasUpstream) return { path, state: "upstream-only" };
+  if (!hasLocal && !hasUpstream) return { path, state: "local-only" }; // named in .maestroignore, present nowhere — the entry is idle
+  if (localText === upstreamText) return { path, state: "identical" };
+  const d = lineDrift(localText, upstreamText);
+  return { path, state: "drifts", onlyHere: d.onlyA, onlyUpstream: d.onlyB };
+}
+
+/**
+ * Build the whole report.
+ * @param {Array<{path:string, local:string|null, upstream:string|null}>} entries
+ * @param {{sdkVersion?:string, at?:string}} [meta]
+ */
+export function buildIgnoredDriftReport(entries, meta = {}) {
+  const files = entries.map((e) => classifyIgnored(e.path, e.local, e.upstream));
+  const counts = { identical: 0, "local-only": 0, "upstream-only": 0, drifts: 0 };
+  for (const f of files) counts[f.state] += 1;
+  return {
+    sdkVersion: meta.sdkVersion || null,
+    at: meta.at || null,
+    counts,
+    files,
+  };
+}
+
+/**
+ * One log line per protected file, for the upgrade summary.
+ * @param {{path:string, state:string, onlyHere?:number, onlyUpstream?:number}} f
+ */
+export function formatIgnoredLine(f) {
+  switch (f.state) {
+    case "identical": return `    = ${f.path} (identical to upstream — the entry is idle)`;
+    case "local-only": return `    · ${f.path} (upstream ships nothing here)`;
+    case "upstream-only": return `    ! ${f.path} (upstream ships it; this seat has never taken it)`;
+    case "drifts": return `    ~ ${f.path} (drifts: ${f.onlyUpstream} upstream line${f.onlyUpstream === 1 ? "" : "s"} not here, ${f.onlyHere} local line${f.onlyHere === 1 ? "" : "s"} not upstream)`;
+    default: return `    ? ${f.path}`;
+  }
+}

package/lib/voice/post-call-brief.mjs

@@ -37,6 +37,8 @@ import { spawn } from "node:child_process";
 import { writeFileSync, readFileSync, mkdirSync, existsSync, appendFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { writeJsonAtomic } from "../fs-atomic.mjs";
+import { buildSpawn } from "../runtime/adapter.mjs";
+import { resolveSeatSpawn } from "../runtime/seat-engine.mjs";
 
 const BRIEF_PROMPT = `You are an executive operator processing the transcript of a voice call.
 Produce a structured post-call brief in JSON only — no preamble, no commentary.
@@ -166,25 +168,36 @@ export async function generateBrief(opts = {}) {
 // Claude --print runner (single-shot, JSON-only output)
 // ---------------------------------------------------------------------------
 
-function runClaudeBrief({ agentRoot, model, systemPrompt, input }) {
+/**
+ * The voice-brief spawn for this seat (conformance row 36). Binary + argv + env
+ * from the runtime adapter (lane "voice-brief"), with the seat's engine:
+ *   claude  --print --dangerously-skip-permissions --strict-mcp-config --model <m>
+ *           <prompt>, env {...env, AGENT_ROOT, AGENT_DIR}; the binary resolved
+ *           by claude-bin (a safe $CLAUDE_BIN, then the known install paths)
+ *           instead of a bare `claude`, which ENOENTs under launchd. The
+ *           buildSpawn input is exactly what it was before the seat was read.
+ *   cohort  `node lib/engine/cli.mjs run -p …` with the seat token and every
+ *           Anthropic/Claude credential scrubbed; no token → a refused spec
+ *           (the caller writes the fallback brief), never claude.
+ * @param {{agentRoot:string, model:string, prompt:string, env:object}} o
+ * @param {{resolveSeatSpawn?:Function, buildSpawn?:Function, adapterDeps?:object}} [deps]
+ */
+export async function briefSpawnSpec({ agentRoot, model, prompt, env }, deps = {}) {
+  const seat = await (deps.resolveSeatSpawn || resolveSeatSpawn)(agentRoot);
+  return (deps.buildSpawn || buildSpawn)({ lane: "voice-brief", model, prompt, mcp: "strict", agentRoot, env, ...seat.fields }, deps.adapterDeps);
+}
+
+async function runClaudeBrief({ agentRoot, model, systemPrompt, input }) {
+  const fullPrompt = `${systemPrompt}\n\n---\n${input}`;
+  const spec = await briefSpawnSpec({ agentRoot, model, prompt: fullPrompt, env: process.env });
   return new Promise((resolveP) => {
-    const claudeBin = process.env.CLAUDE_BIN || "claude";
-    const fullPrompt = `${systemPrompt}\n\n---\n${input}`;
-    const proc = spawn(claudeBin, [
-      "--print",
-      "--dangerously-skip-permissions",
-      "--strict-mcp-config",
-      "--model", model,
-      fullPrompt,
-    ], {
+    if (!spec.ok) {
+      resolveP(fallbackBrief(input, spec.error.message));
+      return;
+    }
+    const proc = spawn(spec.bin, spec.argv, {
       cwd: agentRoot,
-      env: {
-        ...process.env,
-        AGENT_ROOT: agentRoot,
-        AGENT_DIR: agentRoot,
-        // Voice briefs are routine summarization; let model router pick
-        // the cheap backend by signalling it as a "fast" tier task.
-      },
+      env: spec.env,
       stdio: ["ignore", "pipe", "pipe"],
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.17.0",
+  "version": "2.18.5",
   "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": {
@@ -114,18 +114,28 @@
     ".claude/settings.json",
     ".env.example",
     "README.md",
-    "framework-features.json"
+    "framework-features.json",
+    "!**/*.test.mjs",
+    "!**/*.test.js",
+    "!**/fixtures/**",
+    "!**/test-fixtures/**",
+    "!**/__fixtures__/**",
+    "!test/**",
+    "!scripts/eval/replay/examples/**"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
+    "fleet:rollout": "node scripts/fleet/rollout.mjs",
     "test": "node scripts/ci/run-tests.mjs",
     "test:coverage": "node scripts/ci/run-coverage.mjs",
-    "test:list": "node --test bin/maestro.test.mjs lib/action-executor.test.mjs lib/archetype.test.mjs lib/autonomy.test.mjs lib/backlog.test.mjs lib/budget-guard.test.mjs lib/cadence-bus-schedule.test.mjs lib/cadence-bus.test.mjs lib/cadences.test.mjs lib/capability.test.mjs lib/channels/base-adapter.test.mjs lib/channels/channels.test.mjs lib/channels/contract.test.mjs lib/channels/inbox-item.test.mjs lib/channels/pairing.test.mjs lib/channels/slack-adapter.test.mjs lib/channels/telegram-adapter.test.mjs lib/channels/whatsapp/baileys-typing.test.mjs lib/charter.test.mjs lib/claude-bin.test.mjs lib/collective/capture.test.mjs lib/collective/cards.test.mjs lib/collective/config.test.mjs lib/collective/global-config.test.mjs lib/collective/presence.test.mjs lib/collective/recall.test.mjs lib/comms.test.mjs lib/fs-atomic.test.mjs lib/fs-ownership.test.mjs lib/learning/config.test.mjs lib/learning/counters.test.mjs lib/learning/curator-consolidate.test.mjs lib/learning/curator.test.mjs lib/learning/reflect.test.mjs lib/learning/session-index.test.mjs lib/learning/skill-writer.test.mjs lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs lib/org/approvals.test.mjs lib/org/board.test.mjs lib/org/client.test.mjs lib/org/cost-sync.test.mjs lib/org/handoff.test.mjs lib/org/keys.test.mjs lib/org/knowledge.test.mjs lib/org/activity.test.mjs lib/org/leases.test.mjs lib/org/mesh.test.mjs lib/org/messaging.test.mjs lib/org/cohort-client.test.mjs lib/org/policy.test.mjs lib/org/registry.test.mjs lib/org/tool-surface.test.mjs lib/org/ui-parity.test.mjs lib/org/doctor.test.mjs lib/org/verify.test.mjs lib/mcp/server.test.mjs lib/channels/orgmail/adapter.test.mjs lib/rag/rag.test.mjs lib/rate-guard.test.mjs lib/render.test.mjs lib/resource-governor.test.mjs lib/security/coerce-args.test.mjs lib/security/dangerous-tools.test.mjs lib/security/external-content.test.mjs lib/security/redact.test.mjs lib/security/secret-equal.test.mjs lib/session-permissions.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/enroll-from-cohort.test.mjs lib/setup/integration.test.mjs lib/setup/io.test.mjs lib/setup/runner.test.mjs lib/setup/sections/identity.test.mjs lib/setup/sections/learning.test.mjs lib/setup/sections/messaging.test.mjs lib/setup/sections/org.test.mjs lib/setup/sections/orgmail.test.mjs lib/setup/sections/recovery.test.mjs lib/setup/sections/subagents.test.mjs lib/setup/sot.test.mjs lib/setup/state.test.mjs lib/singleton.test.mjs lib/subagents/schema.test.mjs lib/subagents/refs.test.mjs lib/subagents/manifest.test.mjs lib/subagents/lock.test.mjs lib/subagents/resolve.test.mjs lib/subagents/gap.test.mjs lib/subagents/client.test.mjs lib/subagents/cli.test.mjs lib/telemetry/alerts.test.mjs lib/telemetry/collect.test.mjs lib/tool-definitions.test.mjs lib/voice/session-rotation.test.mjs lib/voice/outbound.test.mjs lib/voice/stt.test.mjs lib/voice/voice.test.mjs scripts/cadence/enqueue-cadence-tick.test.mjs scripts/ci/check-durable-write-seam.test.mjs scripts/ci/check-no-build-artifacts.test.mjs scripts/ci/check-no-residual-identity.test.mjs scripts/ci/check.test.mjs scripts/collective/hook-runner.test.mjs scripts/cost/fleet-digest.test.mjs scripts/daemon/cadence-consumer-governance.test.mjs scripts/daemon/cadence-consumer.test.mjs scripts/daemon/cadence-handlers.test.mjs scripts/daemon/classify-kind.test.mjs scripts/daemon/dispatcher-cooldown.test.mjs scripts/daemon/dispatcher-governance.test.mjs scripts/daemon/inbox-deferral.test.mjs scripts/daemon/lib/session-router.test.mjs scripts/daemon/prompt-builder.test.mjs scripts/daemon/typing-registry.test.mjs scripts/hooks/pre-send-audit.test.mjs scripts/local-triggers/generate-plists.test.mjs scripts/poller/inbox-scan-poller.test.mjs scripts/poller/lib/cloud-relay-dedup.test.mjs scripts/poller/slack-socket-mode.test.mjs scripts/setup/gen-subagent-manifest.test.mjs scripts/setup/init-agent.test.mjs services/webhook-relay/server.test.mjs lib/cadence-bus-requeue.test.mjs lib/cli/inbox.test.mjs lib/cli/session-ack.test.mjs lib/org/mesh-directives.test.mjs lib/session/frontdoor.test.mjs lib/session/handoffs.test.mjs lib/session/inbox-claims.test.mjs scripts/daemon/agent-daemon-frontdoor.test.mjs scripts/daemon/cadence-consumer-frontdoor.test.mjs scripts/daemon/dispatcher-resume.test.mjs scripts/daemon/inbox-deferral-session.test.mjs scripts/watchdog/memory-watchdog.test.mjs lib/upgrade/launchd-reconcile.test.mjs lib/upgrade/global-refresh.test.mjs lib/upgrade/verify.test.mjs lib/upgrade/post-steps.test.mjs lib/org/board-mine-cache.test.mjs scripts/daemon/agent-daemon-board-mine.test.mjs scripts/local-triggers/autoupdate.test.mjs scripts/daemon/sdk-version.test.mjs",
+    "test:list": "node scripts/ci/run-tests.mjs --list",
     "test:setup": "node --test lib/setup/io.test.mjs lib/setup/state.test.mjs lib/setup/sot.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/runner.test.mjs lib/setup/integration.test.mjs lib/setup/sections/subagents.test.mjs",
     "check": "node scripts/ci/check.mjs",
+    "test:engine-conformance": "node test/engine-conformance/run.mjs",
+    "eval:replay": "node scripts/eval/replay/run.mjs",
     "conformance:org": "node scripts/ci/conformance-org-api.mjs",
     "conformance:org:write": "node scripts/ci/conformance-org-api.mjs --write",
     "test:router": "node --test lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs scripts/cost/fleet-digest.test.mjs",

package/plugins/maestro-skills/skills/board-work.md

@@ -54,6 +54,11 @@ accepted` (or `maestro board track <inbox-id> --stage accepted --title …
 the message and dedupes, so a re-delivered ask finds the same row. See
 `inbound-triage`.
 
+If you got the ask through the inbox, `maestro inbox claim <id>` has ALREADY
+filed it — and `--title` / `--why` are read only by the step that opens the
+row, so they belong on that claim (`maestro inbox claim <id> --title … --why
+…`). Sending them later, against a row that exists, is accepted and ignored.
+
 ## What not to do
 
 - Do not narrate every step on the board; the board is for the state a

package/plugins/maestro-skills/skills/inbound-triage.md

@@ -11,26 +11,39 @@ no: see "The one-interim rule" at the foot of this skill.
 
 ## The three outcomes
 
+> **The board row is automatic — you do not open it.** `maestro inbox claim`
+> opens the row and puts it in `running`, `reply` closes it with what you said,
+> `done` closes it if you never replied, and `defer` parks it in `blocked` with
+> your reason. The server's own gate decides whether an ask deserves a row at
+> all, from the text, so a claimed one-line question mints nothing. Use
+> `maestro board track` only to say something the four commands cannot: a
+> `--stage blocked` with `notify` when you need unblocking mid-work, or a
+> `--stage review` when a human should look before it goes out.
+
 1. **Reply now.** The ask is answerable in one message from what you already
    know or can look up in under a minute (a status, a fact, a yes/no, a link,
    a short opinion). `maestro inbox claim <id>` → `maestro inbox reply <id>
-   --text "…"` → `maestro inbox done <id>`. No board row: the ledger on the
-   server already records that you answered.
+   --text "…"` → `maestro inbox done <id>`. No board row: the server's gate
+   reads the text as answerable in the turn and mints nothing.
 
 2. **File it, work here.** The ask needs real work — reading, drafting,
    building, several steps — but you can finish it in this session inside an
    hour or two without blocking the front door. In ONE turn:
-   - `maestro inbox claim <id>`
-   - `maestro board track <id> --stage accepted --title "<what you took on>"
-     --why "<one line: why this is more than a reply>"`
+   - `maestro inbox claim <id>` — this opens the row and puts it in `running`.
+     If the row deserves a better name than the ask's own first sentence, say
+     so ON THE CLAIM: `maestro inbox claim <id> --title "<what you took on>"
+     --why "<one line: why this is more than a reply>"`. The claim is the only
+     moment either is read — the server writes the title and the reason when
+     the row OPENS and protects them afterwards, so a later `maestro board
+     track … --title/--why` on the same ask is accepted and changes nothing.
    - then run the work — a `Workflow` when it has distinct steps, plain tool
-     use when it does not. Track meaningful changes only: `--stage working`
-     when the substantive part starts, `--stage blocked` (say what you need,
-     `notify` who can unblock) when stuck, `--stage review` when a human should
-     look before it goes out.
-   - report back in the SAME channel/thread with `maestro inbox reply <id>`
-     (or `messaging_send` to the thread), then `maestro board track <id>
-     --stage done` and `maestro inbox done <id>`.
+     use when it does not. Track only what the four inbox commands cannot say:
+     `--stage blocked` (say what you need, `notify` who can unblock) when
+     stuck, `--stage review` when a human should look before it goes out.
+   - report back in the SAME channel/thread with `maestro inbox reply <id>`,
+     which closes the row and tags the channel, then `maestro inbox done <id>`.
+     If you reported with `messaging_send` instead, `maestro inbox done <id>`
+     is what closes the row.
 
 3. **File it, hand to a peer.** Same as 2, but the work is long (hours), heavy
    (a repo build, a large research pass), or would block you from answering the
@@ -39,13 +52,14 @@ no: see "The one-interim rule" at the foot of this skill.
    with a prompt that names the deliverable, the channel and thread to report
    to, the inbox id, and the instruction to `SendMessage` you a two-line
    status when done. You stay the one who talks to the human; the peer talks to
-   you. When it reports back, you send the result and close the row
-   (`--stage done`) and the item (`maestro inbox done <id>`).
+   you. When it reports back, you send the result and close the item
+   (`maestro inbox reply` then `maestro inbox done <id>`), which closes the row.
 
 ## How to pick
 
 - Would a competent colleague answer this from their chair in one message?
-  → reply now.
+  → reply now. A "what are you doing / working on right now?" is this kind:
+  answer it from `maestro session status` (`currentWork`), never from memory.
 - Does it produce an artefact (a doc, a deck, a number that needs checking, a
   change in a system)? → file it. The server derives the board from the
   message: a DM's ask lands on that conversation's board, a space's ask on the
@@ -56,6 +70,33 @@ no: see "The one-interim rule" at the foot of this skill.
   and say in-channel what you need and from whom. That is a message with
   content in it, so it is always worth sending; do not guess.
 
+## Addressed to the whole room (`collective` on the feed line)
+
+A message a human sent to everyone carries `collective` on its `inbound` line:
+`roll-call`, `work`, or `ambient`. It is empty for a DM, an @mention or a task.
+Nobody was named, so nobody is more responsible than you: **you answer for your
+own seat, and you never answer for anyone else's.**
+
+- `collective: roll-call` — "can everyone give me an update on what they're
+  doing right now?" → **outcome 1**. Answer from `maestro session status`
+  (`currentWork`) in at most five short lines: what you are on, what is queued,
+  what is blocked. No board row — reporting on yourself is not work. Do not
+  summarise, guess at or speak for any colleague; they answer for themselves.
+- `collective: work` — "everyone, please review the binder by Friday" → **outcome
+  2 or 3**, exactly as if it had been addressed to you alone. Claim it, `board
+  track --stage accepted`, do YOUR slice, and reply with what you will do and by
+  when. The board row is yours and covers your slice only; twelve other seats
+  are opening twelve other rows for the same message and that is correct.
+- `collective: ambient` — the room was addressed and nothing was asked of you
+  ("everyone should take a look sometime", "FYI the binder is up"). **Outcome 1
+  at most, and usually silence.** Do not mint work from it. A board that grows a
+  row per seat per aside is a board nobody opens by the end of the week.
+
+Why it is on the line at all: when your front door is live the daemon does not
+dispatch these items, so there is no other plane that will act on them. If the
+field is missing or empty on a message that plainly addressed the room, treat it
+as `ambient` and use your judgement — it is a hint, not an instruction.
+
 ## Special topics
 
 - **Calls** (`topic: call`): answer in the channel — join if you are free now,