@commonlyai/cli 0.1.209 → 0.1.211

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.209",
+  "version": "0.1.211",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -88,9 +88,11 @@ import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { hostSandboxRefusal, windowsSandboxMessage } from '../lib/sandbox/host-check.js';
 import { prepareMcpBeforeFirstPoll } from '../lib/mcp-first-run.js';
+import { installedCliVersion, startUpdateNotice } from '../lib/update-check.js';
 import { createSeatStop } from '../lib/seat-stop.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
 import { describeUpstreamRefusal } from '../lib/upstream-refusal.js';
+import { createTurnRunner, supervisedRunPolicy } from '../lib/supervised-turn.js';
 import {
   DEFAULT_HOOK_TIMEOUT_MS,
   clampHookTimeoutMs,
@@ -534,6 +536,29 @@ export const listLocalAgents = () => {
     .filter(Boolean);
 };
 
+/**
+ * The token files listLocalAgents drops: present, but not readable JSON.
+ * `commonly doctor` reports them, because a dropped file otherwise reads as
+ * "no agent here" and lets doctor pass on a seat that cannot start.
+ * Throws when the directory exists but cannot be read, for doctor to report.
+ */
+export const listUnreadableAgentTokens = () => {
+  let files;
+  try {
+    files = readdirSync(tokensDir());
+  } catch (error) {
+    // Only a missing directory means no agents. existsSync also answers false
+    // for EACCES on an ancestor, which is why this reads instead of checking.
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return [];
+    throw error;
+  }
+  return files
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.slice(0, -'.json'.length))
+    .filter((name) => !loadAgentToken(name))
+    .sort();
+};
+
 // Chat event types whose payload already contains the prompt the wrapper
 // should forward verbatim. Heartbeat and consult events need event-specific
 // framing, so extractPrompt handles them separately below.
@@ -1356,6 +1381,11 @@ const extractPrompt = (event) => {
   return null;
 };
 
+// The supervisor's policy for a run-loop spawn: lib/supervised-turn.js has the
+// stall windows per adapter (codex 15 min, claude off) and their evidence, the
+// cancel grace, and the wall-clock backstop past the adapter's own timeout.
+export { supervisedRunPolicy };
+
 /**
  * Start the run loop. Polls /events, spawns the adapter per event, posts the
  * result into the pod, acks.
@@ -1431,6 +1461,13 @@ export const performRun = ({
   resolveOwnProviderKey = null,
   runtimeReportClient = null,
   refusalHandoff = null,
+  // Off unless COMMONLY_SUPERVISE_RUNS=1: each spawn runs under the seats
+  // supervisor (stall window, wall-clock backstop, a named failure on every
+  // settle). The CLI still talks to its provider directly, and one metadata
+  // line per turn goes to ~/.commonly/state/turns/<agent>.jsonl once
+  // delivery settles. Off, the spawn path is the plain adapter call it has
+  // always been, and nothing is written.
+  superviseRuns = process.env.COMMONLY_SUPERVISE_RUNS === '1',
 }) => {
   reportRuntime = reportRuntime && WALKED_HARNESSES.includes(adapter?.name);
   if (environment?.provider !== undefined && !adapter?.supportsProvider) {
@@ -1440,6 +1477,12 @@ export const performRun = ({
   const effectiveTurnTimeoutMs = Number.isFinite(requestedTurnTimeout) && requestedTurnTimeout > 0
     ? Math.min(requestedTurnTimeout, 2_147_483_647) : 15 * 60 * 1000;
   const client = createClient({ instance: instanceUrl, token });
+  // The supervised run keeps its trace in memory, metadata only; no record of
+  // a run is written to disk (lib/supervised-turn.js).
+  const turnRunner = createTurnRunner({
+    seat: agentName, turnTimeoutMs: effectiveTurnTimeoutMs, supervise: superviseRuns, log,
+  });
+  if (superviseRuns) log(turnRunner.describe(adapter?.name));
   const runtimeReporter = createRuntimeReporter({
     client: runtimeReportClient || { post: async () => {} },
     harness: adapter.name, detect: () => adapter.detect(),
@@ -1852,8 +1895,21 @@ export const performRun = ({
 
   // The spawn → post-decision half of a turn, split out so the claim release
   // above is a plain finally instead of threading through every return path.
-  const runTurn = async ({
-    event, eventPodId, prompt, preSpawnIds, snapshotMessages, claimKeeper, trigger,
+  // With superviseRuns, the turn's log line is written once delivery has
+  // settled; anything thrown after a spawn that resolved means the reply never
+  // reached the pod. Off, `turn` writes nothing.
+  const runTurn = async (args) => {
+    const turn = turnRunner.begin({ eventType: args.event.type });
+    try {
+      return await runTurnBody({ ...args, turn });
+    } catch (error) {
+      turn.finish('reply_lost');
+      throw error;
+    }
+  };
+
+  const runTurnBody = async ({
+    event, eventPodId, prompt, preSpawnIds, snapshotMessages, claimKeeper, trigger, turn,
   }) => {
     const placement = await placeTurn();
     // A workspace turn placed public (its pod turned public, or its pods could
@@ -2076,7 +2132,8 @@ export const performRun = ({
             reason: 'own-key-requires-scoped-spawn' };
         }
       }
-      result = await adapter.spawn(frameDecisionForkRule(promptForSpawn), {
+      const spawnPrompt = frameDecisionForkRule(promptForSpawn);
+      const spawnCtx = {
         onSpawn: reportRuntime ? (controls) => {
           observedSpawn = true;
           return runtimeReporter.spawn(controls);
@@ -2108,7 +2165,10 @@ export const performRun = ({
         instanceUrl,
         agentName,
         metadata: { event },
-      });
+      };
+      // Supervised or plain, a failure is thrown exactly as the adapter's own
+      // would be, so the run loop's classification and retry apply unchanged.
+      result = await turn.run(adapter, spawnPrompt, spawnCtx);
       spawnCompleted = true;
     } finally {
       try {
@@ -2191,6 +2251,9 @@ export const performRun = ({
     const upstream = result.upstream || null;
     let delivered = agentPostedItself;
     let deliveryRefusal = null;
+    // What became of the reply, for the turn line (lib/supervised-turn.js
+    // TURN_OUTCOMES). A throw below is reply_lost, finished by runTurn.
+    let turnOutcome;
 
     if (event.type === 'agent.ask') {
       if (silentReply) {
@@ -2200,6 +2263,7 @@ export const performRun = ({
         // having nothing to say.
         if (upstream) log(`[${event.type}] ${describeUpstreamRefusal(upstream)} — no private response`);
         else log(`[${event.type}] no private response (${reason})`);
+        turnOutcome = upstream ? 'upstream_refused' : 'silent';
       } else {
         try {
           await client.post(
@@ -2207,6 +2271,7 @@ export const performRun = ({
             { content: replyText },
           );
           delivered = true;
+          turnOutcome = 'delivered';
           log(`[${event.type}] routed private response (${Buffer.byteLength(replyText)} bytes)`);
         } catch (err) {
           // A tool-capable agent may have called commonly_respond_to_ask
@@ -2215,6 +2280,7 @@ export const performRun = ({
           // the model forever.
           if (err?.status === 409 && err?.body?.code === 'already_responded') {
             delivered = true;
+            turnOutcome = 'delivered';
             log(`[${event.type}] response already routed by agent tool`);
           } else {
             throw err;
@@ -2242,6 +2308,7 @@ export const performRun = ({
       // Report the two cases distinctly. `posted` is the load-bearing word: a
       // reader scanning for whether a seat is contributing must not have to
       // infer it from the absence of a different line.
+      turnOutcome = agentPostedItself ? 'delivered' : upstream ? 'upstream_refused' : 'silent';
       if (agentPostedItself) {
         log(
           `[${event.type}] posted via tool, then ${reason} — no echo needed `
@@ -2260,6 +2327,7 @@ export const performRun = ({
       // Name the message that caused the suppression. A silently dropped reply
       // is invisible to everyone; #757 went unnoticed precisely because this
       // line said only "posted via tool" with no way to tell whose post it saw.
+      turnOutcome = 'delivered';
       log(
         `[${event.type}] agent posted via tool this turn — not echoing CLI output `
         + `(avoids double-post; matched message ${suppressedBy.id} by ${suppressedBy.author} `
@@ -2269,6 +2337,7 @@ export const performRun = ({
       // ADR-018 D3: the lease lapsed mid-turn and a peer re-won the message —
       // that peer owns the conversation now, so posting would recreate the
       // two-agents-one-message crossing the claim exists to prevent.
+      turnOutcome = 'claim_lost';
       log(
         `[${event.type}] stood down — claim lost mid-turn to ${claimKeeper.getHolder()}; `
         + `reply suppressed (${Buffer.byteLength(replyText)} bytes not posted)`,
@@ -2311,6 +2380,7 @@ export const performRun = ({
         // it like a refusal: re-posting the same text inside the window would
         // only be skipped again.
         deliveryRefusal = delivery;
+        turnOutcome = 'server_skipped';
         const windowMinutes = delivery.duplicate?.dedupeWindowMinutes;
         const detail = [
           windowMinutes ? `${windowMinutes} min window` : null,
@@ -2336,6 +2406,7 @@ export const performRun = ({
         // guidance expressly says not to retry unchanged), while preserving
         // the refusal and its partial-post count for the seat and event ledger.
         deliveryRefusal = delivery;
+        turnOutcome = 'server_refused';
         const guidance = delivery.guidance || 'The server refused this message; do not retry it unchanged.';
         const detail = `after ${delivery.messages}/${delivery.attemptedMessages} message${delivery.attemptedMessages === 1 ? '' : 's'}`;
         log(`[${event.type}] wrapper delivery refused ${detail} (${delivery.reason}): ${guidance}`);
@@ -2351,12 +2422,14 @@ export const performRun = ({
         ));
       } else {
         delivered = true;
+        turnOutcome = 'delivered';
         log(
           `[${event.type}] posted ${Buffer.byteLength(replyText)} bytes as `
           + `${delivery.messages} message${delivery.messages === 1 ? '' : 's'} (${delivery.mode})`,
         );
       }
     }
+    turn.finish(turnOutcome);
     if (result.memorySummary && !memoryWithheld) {
       try {
         await syncBack(client, { summary: result.memorySummary });
@@ -4051,6 +4124,12 @@ Docs:
 
       console.log(`${stamp()} [${name}] polling ${record.instanceUrl} for events (ctrl+c to stop)`);
       console.log(`${stamp()} [${name}] ${foregroundDaemonHint({ daemonRegistered: hasDaemonRecord() })}`);
+      // TASK-660: one line when this CLI is stale. Fired, not awaited, so a
+      // slow registry never delays the first poll.
+      startUpdateNotice({
+        installedVersion: installedCliVersion(),
+        log: (line) => console.log(`${stamp()} [${name}] ${line}`),
+      });
 
       const { stop } = performRun({
         instanceUrl: record.instanceUrl,

package/src/commands/daemon.js

@@ -38,6 +38,7 @@ import {
 } from '../lib/daemon-service.js';
 import { daemonLogsDir, daemonSeatLogPath, readLogTail } from '../lib/daemon-logs.js';
 import { loadDaemonState, saveDaemonState } from '../lib/daemon-state.js';
+import { installedCliVersion, startUpdateNotice, UPDATE_CHECK_OPT_OUT_ENV } from '../lib/update-check.js';
 
 // One supervised seat, as `commonly daemon status --verbose` names it. Two of these
 // fields are worth reading closely: the seat's `instanceId` (the identity the
@@ -351,7 +352,11 @@ Examples:
         // adapter. The keys are captured here because this is the only moment
         // the operator's shell is in reach; the ones that are missing are named
         // by installDaemonService rather than left to be discovered per seat.
-        await installDaemonService({ ...serviceDeps(), providerKeyEnvNames: providerKeyEnvNames() });
+        await installDaemonService({
+          ...serviceDeps(),
+          providerKeyEnvNames: providerKeyEnvNames(),
+          optionalEnvNames: [UPDATE_CHECK_OPT_OUT_ENV],
+        });
         console.log('The daemon now starts at login and is kept alive. Uninstall with: commonly daemon uninstall');
       } catch (error) {
         console.error(`Daemon install failed: ${error.message}`);
@@ -451,6 +456,9 @@ Examples:
         for (const name of missingProviderKeys({ names: providerKeyEnvNames() })) {
           stampLog(`WARNING: ${name} is not set in this environment — a seat whose adapter needs it will fail to start. Export it and re-run: commonly daemon install (docs/agents/daemon-service-environment.md)`);
         }
+        // TASK-660: the daemon outlives many publishes, so say once at start-up
+        // when it is stale. Not awaited: supervision never waits on the registry.
+        startUpdateNotice({ installedVersion: installedCliVersion(), log: stampLog });
 
         let pollTimer;
         let heartbeatTimer;

package/src/commands/doctor.js

@@ -0,0 +1,135 @@
+/**
+ * commonly doctor — one line per check, exit 1 when any fails (TASK-660).
+ * The checks live in ../lib/doctor.js; this file supplies the real host.
+ */
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { homedir } from 'os';
+import { join } from 'path';
+import { createClient } from '../lib/api.js';
+import { getToken, resolveInstance, resolveInstanceUrl } from '../lib/config.js';
+import { loadDaemonRecord } from '../lib/daemon-store.js';
+import { servicePaths } from '../lib/daemon-service.js';
+import { getAdapter } from '../lib/adapters/index.js';
+import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
+import { daemonStatusErrorMessage, getDaemonMachineStatus } from './daemon.js';
+import { listLocalAgents, listUnreadableAgentTokens } from './agent.js';
+import { doctorExitCode, formatDoctorLine, runDoctor } from '../lib/doctor.js';
+
+const REQUEST_TIMEOUT_MS = 5000;
+
+// Every server read doctor makes is bounded, so a hung instance is a fail line, not a hang.
+export const timedClient = (client) => ({
+  ...client,
+  get: (path, params = {}, options = {}) => client.get(path, params, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...options }),
+});
+
+const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+
+const isExecutable = (path) => {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const isFile = (path) => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+
+// Node refuses to spawn a .cmd without a shell (CVE-2024-27980), and npm's
+// Windows shim is a .cmd, so that one case goes through cmd.exe, quoted.
+export const versionCommand = (binary, platform = process.platform) => (
+  platform === 'win32' && /\.(cmd|bat)$/i.test(binary)
+    ? { command: `"${binary}" --version`, args: [], shell: true }
+    : { command: binary, args: ['--version'], shell: false }
+);
+
+const runVersion = (binary) => {
+  const { command, args, shell } = versionCommand(binary);
+  const res = spawnSync(command, args, { encoding: 'utf8', timeout: REQUEST_TIMEOUT_MS, shell });
+  if (res.error || res.status !== 0) return null;
+  return (res.stdout || '').trim().split(/\s+/)[0] || null;
+};
+
+/**
+ * The instance and token every other command would use for `instanceArg`:
+ * createClient's own resolution (api.js), so doctor cannot pass a login that
+ * `agent attach` then fails, or fail one that works. COMMONLY_TOKEN wins over
+ * the saved token there, so it wins here, and the line says which one it sent.
+ */
+export const loginTarget = ({
+  instanceArg = null,
+  env = process.env,
+  resolve = resolveInstance,
+  resolveUrl = resolveInstanceUrl,
+  tokenFor = getToken,
+} = {}) => {
+  const saved = resolve(instanceArg);
+  const token = tokenFor(instanceArg);
+  return {
+    key: saved?.key || null,
+    url: resolveUrl(instanceArg),
+    tokenSource: !token ? null : (env.COMMONLY_TOKEN ? 'env' : 'saved'),
+    loginHint: instanceArg ? `commonly login --instance ${instanceArg}` : 'commonly login',
+  };
+};
+
+export const hostDoctorDeps = ({ instance: instanceArg = null } = {}) => ({
+  listAgents: () => listLocalAgents(),
+  listUnreadable: () => listUnreadableAgentTokens(),
+  getAdapter,
+  node: { nodeVersion: process.versions.node, enginesRange: pkg.engines?.node },
+  install: {
+    pathValue: process.env.PATH,
+    platform: process.platform,
+    isExecutable,
+    runVersion,
+    runningVersion: pkg.version,
+  },
+  login: {
+    target: loginTarget({ instanceArg }),
+    fetchUser: () => timedClient(createClient({ instance: instanceArg })).get('/api/auth/user'),
+  },
+  daemon: {
+    loadRecord: loadDaemonRecord,
+    serviceFile: servicePaths().file,
+    fileExists: existsSync,
+    fetchMachine: (record) => getDaemonMachineStatus({
+      client: timedClient(createClient({ instance: record.instanceUrl, token: record.daemonToken })),
+      record,
+    }),
+    describeError: daemonStatusErrorMessage,
+    now: Date.now(),
+  },
+  macos: {
+    platform: process.platform,
+    detectSeatbelt,
+    isFile,
+    loginKeychainPath: join(homedir(), 'Library', 'Keychains', 'login.keychain-db'),
+  },
+});
+
+export const registerDoctor = (program) => {
+  program
+    .command('doctor')
+    .description('Check this computer: Node, the install, login, the daemon, adapter CLIs, macOS prerequisites')
+    .option('--instance <keyOrUrl>', 'Saved instance to check the login of (default: the active one)')
+    .action(async (opts) => {
+      try {
+        const results = await runDoctor(hostDoctorDeps({ instance: opts.instance || null }));
+        for (const line of results.map(formatDoctorLine)) console.log(line);
+        process.exitCode = doctorExitCode(results);
+      } catch (error) {
+        console.error(`commonly doctor could not finish: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+};

package/src/index.js

@@ -21,6 +21,7 @@ import { registerDaemon } from './commands/daemon.js';
 import { registerPod } from './commands/pod.js';
 import { registerDev } from './commands/dev.js';
 import { registerVerify } from './commands/verify.js';
+import { registerDoctor } from './commands/doctor.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
@@ -54,6 +55,9 @@ registerPod(program);
 registerDev(program);
 registerVerify(program);
 
+// Install health: one line per check (TASK-660)
+registerDoctor(program);
+
 // Each subcommand owns its own `--instance <url>` flag; a program-level
 // duplicate shadowed the subcommand value on commander v12, causing
 // `commonly login --instance …` to silently fall back to the default URL.
@@ -66,6 +70,7 @@ Quick start:
   $ commonly agent detach my-claude                    # clean uninstall
   $ commonly daemon register --name "My MacBook"
   $ commonly daemon status
+  $ commonly doctor                                   # check Node, install, login, daemon, adapters
   $ commonly inbox list --token-file ~/.commonly/bin/ops-token   # an operator's own queue
 
 Custom Python agent:

package/src/lib/daemon-service.js

@@ -203,6 +203,10 @@ export const installDaemonService = async ({
   cliPath = resolve(process.argv[1]),
   // The provider keys the seats' adapters declare (adapters/index.js).
   providerKeyEnvNames = [],
+  // Settings carried only when set, never warned about when absent: the
+  // operator's opt-outs (COMMONLY_NO_UPDATE_CHECK), which reach the seats the
+  // daemon spawns only through this file.
+  optionalEnvNames = [],
   env = process.env,
   writeFile = writeServiceFile,
   mkdirp,
@@ -221,7 +225,7 @@ export const installDaemonService = async ({
     chmod(daemonLogPath(home), 0o600);
   }
 
-  const providerEnv = providerEnvPairs({ names: providerKeyEnvNames, env });
+  const providerEnv = providerEnvPairs({ names: [...new Set([...providerKeyEnvNames, ...optionalEnvNames])], env });
   const missing = missingProviderKeys({ names: providerKeyEnvNames, env });
 
   if (target.kind === 'launchd') {
@@ -237,7 +241,10 @@ export const installDaemonService = async ({
   } else {
     writeFile(target.file, systemdUnit({ nodePath, cliPath, providerEnv }));
     await execCmd(['systemctl', '--user', 'daemon-reload']);
-    await execCmd(['systemctl', '--user', 'enable', '--now', SYSTEMD_UNIT]);
+    // restart, not `enable --now`: a unit that is already running must pick up
+    // the environment just written, the way launchd's unload/load does.
+    await execCmd(['systemctl', '--user', 'enable', SYSTEMD_UNIT]);
+    await execCmd(['systemctl', '--user', 'restart', SYSTEMD_UNIT]);
   }
   for (const name of missing) {
     warn(`${name} is not set in this shell, so it is NOT in the service file. A seat whose adapter needs it will fail to start; export it and re-run: commonly daemon install (docs/agents/daemon-service-environment.md)`);

package/src/lib/doctor.js

@@ -0,0 +1,272 @@
+/**
+ * `commonly doctor` — the checks (TASK-660, D213).
+ *
+ * D213 keeps the Node daemon and hardens install by making breakage visible.
+ * Each check here answers one question a broken seat used to leave to a log
+ * autopsy, prints one line (pass, fail or skip) and, when it fails, the command
+ * that fixes it. Every outside fact (PATH, the saved login, the server, the
+ * daemon record, the adapters, the macOS files) comes in through `deps`, so the
+ * tests fake the environment and never touch this host.
+ *
+ * What a check must never do: print a token, or touch the keychain. The macOS
+ * check only stats the login keychain file and `/usr/bin/security`; it never
+ * runs `security`, so it cannot prompt, unlock or read a secret.
+ */
+import { delimiter, join } from 'node:path';
+import { parseVersion, versionOlderThan } from './mcp-server-version.js';
+
+export const PASS = 'pass';
+export const FAIL = 'fail';
+export const SKIP = 'skip';
+
+const result = (id, status, detail, fix = null) => ({ id, status, detail, ...(fix ? { fix } : {}) });
+
+/** `>=20`, `>=20.1` or `>=20.1.2` as a triple; null for any other range shape. */
+export const enginesFloor = (range) => {
+  const match = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?\s*$/.exec(String(range || ''));
+  return match ? [Number(match[1]), Number(match[2] || 0), Number(match[3] || 0)] : null;
+};
+
+// (a) Node against the package's engines floor.
+export const checkNode = ({ nodeVersion, enginesRange }) => {
+  const floor = enginesFloor(enginesRange);
+  if (!floor) return result('node', SKIP, `Node ${nodeVersion}; engines range '${enginesRange || 'none'}' is not a >= floor`);
+  const version = parseVersion(nodeVersion);
+  if (!version) return result('node', FAIL, `could not read the Node version '${nodeVersion}'`, `install Node ${enginesRange}`);
+  if (versionOlderThan(version, floor)) {
+    return result('node', FAIL, `Node ${nodeVersion} is older than the CLI needs (${enginesRange})`, `install Node ${floor[0]} or newer`);
+  }
+  return result('node', PASS, `Node ${nodeVersion} (needs ${enginesRange})`);
+};
+
+/** Every `commonly` on PATH, first one first (the one a shell runs). */
+export const findOnPath = ({ command, pathValue, platform, isExecutable }) => {
+  // npm also drops a bare sh shim beside the .cmd on Windows; cmd.exe cannot run
+  // it, so counting it would report a second install that is not one.
+  const names = platform === 'win32' ? [`${command}.cmd`, `${command}.exe`] : [command];
+  const found = [];
+  for (const dir of String(pathValue || '').split(platform === 'win32' ? ';' : delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (isExecutable(candidate) && !found.includes(candidate)) found.push(candidate);
+    }
+  }
+  return found;
+};
+
+// (b) Which `commonly` a shell runs, and its version.
+export const checkInstall = ({
+  pathValue, platform, isExecutable, runVersion, runningVersion,
+}) => {
+  const fix = 'npm install -g @commonlyai/cli';
+  const found = findOnPath({ command: 'commonly', pathValue, platform, isExecutable });
+  if (!found.length) return result('install', FAIL, 'no `commonly` on PATH', fix);
+  const [binary] = found;
+  const version = runVersion(binary);
+  if (!parseVersion(version)) return result('install', FAIL, `${binary} did not answer --version`, `reinstall: ${fix}`);
+  const notes = [];
+  if (runningVersion && parseVersion(runningVersion) && version !== runningVersion) {
+    notes.push(`this doctor is ${runningVersion}`);
+  }
+  if (found.length > 1) notes.push(`${found.length - 1} more on PATH`);
+  return result('install', PASS, `commonly ${version} at ${binary}${notes.length ? ` (${notes.join('; ')})` : ''}`);
+};
+
+// (c) The instance every other command would use, and whose token it sends.
+// The token is sent, never shown. `target` comes from loginTarget (commands/
+// doctor.js), which resolves it the way createClient does, COMMONLY_TOKEN first.
+export const checkLogin = async ({ target, fetchUser }) => {
+  const where = target.key ? `${target.key} (${target.url})` : target.url;
+  if (!target.tokenSource) {
+    return result('login', FAIL, target.key ? `${where} has no saved token` : 'not logged in', target.loginHint);
+  }
+  const fromEnv = target.tokenSource === 'env';
+  const tokenName = fromEnv ? 'the token in COMMONLY_TOKEN' : 'the saved token';
+  const refix = fromEnv ? 'replace or unset COMMONLY_TOKEN' : target.loginHint;
+  let user;
+  try {
+    user = await fetchUser();
+  } catch (error) {
+    if ([401, 403].includes(error?.status)) {
+      return result('login', FAIL, `${where} rejected ${tokenName}`, refix);
+    }
+    return result('login', FAIL, `could not reach ${target.url}: ${error?.message || error}`, 'check the network, then re-run commonly doctor');
+  }
+  const who = user?.username || user?.email || user?._id;
+  if (!who) return result('login', FAIL, `${where} answered without a user`, refix);
+  return result('login', PASS, `@${who} on ${where}${fromEnv ? ' (token from COMMONLY_TOKEN)' : ''}`);
+};
+
+const ago = (iso, now) => {
+  const at = Date.parse(iso);
+  if (!Number.isFinite(at)) return 'never';
+  const seconds = Math.max(0, Math.round((now - at) / 1000));
+  if (seconds < 120) return `${seconds}s ago`;
+  if (seconds < 7200) return `${Math.round(seconds / 60)}m ago`;
+  return `${Math.round(seconds / 3600)}h ago`;
+};
+
+// (d) The daemon: registered, service installed, heard from lately.
+export const checkDaemon = async ({
+  loadRecord, serviceFile, fileExists, fetchMachine, describeError, now,
+}) => {
+  let record;
+  try {
+    record = loadRecord();
+  } catch (error) {
+    return result('daemon', FAIL, error?.message || String(error), 'fix the file permissions named above, then re-run');
+  }
+  if (!record) {
+    return result('daemon', SKIP, 'no daemon registered on this computer (optional; agents then run in the foreground)');
+  }
+  const name = record.machineName || 'this computer';
+  if (!fileExists(serviceFile)) {
+    return result('daemon', FAIL, `${name} is registered but its login service is not installed (${serviceFile})`, 'commonly daemon install');
+  }
+  let machine;
+  try {
+    machine = await fetchMachine(record);
+  } catch (error) {
+    return result('daemon', FAIL, describeError(error), 'commonly daemon status');
+  }
+  const heard = `last heartbeat ${ago(machine?.lastSeenAt, now)}`;
+  if (machine?.status !== 'online') {
+    return result('daemon', FAIL, `${machine?.name || name} is ${machine?.status || 'unknown'}, ${heard}`, 'commonly daemon restart, then commonly daemon logs');
+  }
+  return result('daemon', PASS, `${machine.name || name} online, service installed, ${heard}`);
+};
+
+const MAX_NAMED_AGENTS = 5;
+
+const nameList = (names) => {
+  const sorted = [...names].sort();
+  const shown = sorted.slice(0, MAX_NAMED_AGENTS).join(', ');
+  return `${shown}${sorted.length > MAX_NAMED_AGENTS ? ` and ${sorted.length - MAX_NAMED_AGENTS} more` : ''}`;
+};
+
+// (e) Every adapter CLI a configured agent uses, found and answering --version.
+// `unreadable` names token files that exist but are not readable JSON: the
+// agent listing drops them, so without this line they would read as no agent.
+export const checkAdapters = async ({ agents, getAdapter, unreadable = [] }) => {
+  const byAdapter = new Map();
+  for (const agent of agents) {
+    const adapter = agent?.adapter || '?';
+    if (!byAdapter.has(adapter)) byAdapter.set(adapter, []);
+    byAdapter.get(adapter).push(agent.name);
+  }
+  const unreadableLine = unreadable.length
+    ? [result('adapters', FAIL, `the token file of ${nameList(unreadable)} is not readable JSON (~/.commonly/tokens)`, 'commonly agent detach <name> --force, then attach it again')]
+    : [];
+  if (!byAdapter.size) {
+    return unreadableLine.length ? unreadableLine : [result('adapters', SKIP, 'no agents are attached on this computer')];
+  }
+  const results = [];
+  for (const [name, agentNames] of [...byAdapter.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const id = `adapter:${name}`;
+    const used = `used by ${nameList(agentNames)}`;
+    if (name === '?') {
+      results.push(result(id, FAIL, `no adapter recorded in the token file, ${used}`, 'commonly agent detach <name> --force, then attach it again'));
+      continue;
+    }
+    const adapter = getAdapter(name);
+    if (!adapter) {
+      results.push(result(id, FAIL, `unknown adapter '${name}', ${used}`, `commonly agent detach <name> --force, then attach it again`));
+      continue;
+    }
+    if (typeof adapter.detect !== 'function') {
+      results.push(result(id, SKIP, `${name} runs no local CLI, ${used}`));
+      continue;
+    }
+    let found = null;
+    let detectError = null;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      found = await adapter.detect();
+    } catch (error) {
+      detectError = error?.message || String(error);
+    }
+    if (detectError) {
+      results.push(result(id, FAIL, `${name} could not be checked (${detectError}), ${used}`, `run the ${name} CLI with --version by hand`));
+      continue;
+    }
+    if (!found) {
+      results.push(result(id, FAIL, `${name} is not on PATH or its --version failed, ${used}`, `install the ${name} CLI, or put it on PATH`));
+      continue;
+    }
+    const at = found.path ? ` at ${found.path}` : '';
+    results.push(result(id, PASS, `${name} ${found.version || 'unknown version'}${at}, ${used}`));
+  }
+  return [...results, ...unreadableLine];
+};
+
+// (f) macOS: what the claude adapter's confined spawn needs, by file stat only.
+export const checkMacClaude = ({
+  platform, agents, detectSeatbelt, isFile, loginKeychainPath, securityPath = '/usr/bin/security',
+}) => {
+  if (platform !== 'darwin') return result('macos-claude', SKIP, 'not macOS');
+  if (!agents.some((agent) => agent?.adapter === 'claude')) {
+    return result('macos-claude', SKIP, 'no agent here uses the claude adapter');
+  }
+  const missing = [];
+  let seatbelt;
+  try {
+    seatbelt = detectSeatbelt();
+  } catch (error) {
+    seatbelt = { available: false, error: error?.message || String(error) };
+  }
+  if (!seatbelt?.available) missing.push(`Seatbelt (${seatbelt?.error || 'sandbox-exec unavailable'})`);
+  if (!isFile(loginKeychainPath)) missing.push(`login keychain (${loginKeychainPath})`);
+  if (!isFile(securityPath)) missing.push(`${securityPath}`);
+  if (missing.length) {
+    // A failed preflight most often means doctor itself is inside a sandbox
+    // (an agent's turn), where a nested sandbox-exec is refused.
+    const fixes = [];
+    if (!seatbelt?.available) fixes.push('run commonly doctor from a normal Terminal, not from inside an agent\'s sandbox');
+    if (missing.length > (seatbelt?.available ? 0 : 1)) {
+      fixes.push('sign in to this Mac as the user the agent runs as, and run claude once to log in');
+    }
+    const fix = fixes.join('; ');
+    return result('macos-claude', FAIL, `missing: ${missing.join('; ')}`, fix);
+  }
+  return result('macos-claude', PASS, 'Seatbelt runs, the login keychain and /usr/bin/security are present');
+};
+
+/** Every check, in the order the lines print. */
+export const runDoctor = async (deps) => {
+  // An unreadable tokens dir is one fail line, not a doctor that prints nothing.
+  let agents = null;
+  let unreadable = [];
+  let listError = null;
+  try {
+    agents = deps.listAgents();
+    unreadable = deps.listUnreadable ? deps.listUnreadable() : [];
+  } catch (error) {
+    listError = error?.message || String(error);
+  }
+  return [
+    checkNode(deps.node),
+    checkInstall(deps.install),
+    await checkLogin(deps.login),
+    await checkDaemon(deps.daemon),
+    ...(listError
+      ? [
+        result('adapters', FAIL, `could not list the attached agents (${listError})`, 'check that ~/.commonly/tokens is a directory you can read'),
+        result('macos-claude', SKIP, 'the attached agents could not be listed'),
+      ]
+      : [
+        ...(await checkAdapters({ agents, getAdapter: deps.getAdapter, unreadable })),
+        checkMacClaude({ ...deps.macos, agents }),
+      ]),
+  ];
+};
+
+// One line each, whatever a server or a CLI put in its error text.
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const oneLine = (text) => String(text ?? '').replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ').trim();
+
+export const formatDoctorLine = ({ id, status, detail, fix }) => (
+  `${status.padEnd(4)}  ${id.padEnd(16)} ${oneLine(detail)}${status === FAIL && fix ? ` — fix: ${oneLine(fix)}` : ''}`
+);
+
+export const doctorExitCode = (results) => (results.some((r) => r.status === FAIL) ? 1 : 0);

package/src/lib/supervised-turn.js

@@ -0,0 +1,351 @@
+/**
+ * One model turn of `commonly agent run`, on one of two paths. The supervised
+ * path also writes one metadata line per turn (the turn log), once the
+ * turn's outcome has reached the pod or failed to.
+ *
+ *   COMMONLY_SUPERVISE_RUNS=1  (read by performRun as `superviseRuns`)
+ *     the turn runs under `superviseRun` from @commonlyai/seats: a stall
+ *     window, a wall-clock backstop, and a guarantee the turn settles with a
+ *     named failure. No provider relay: the CLI talks to its provider directly,
+ *     exactly as on the plain path.
+ *   anything else
+ *     the plain path: `adapter.spawn(prompt, ctx)` with the caller's ctx object
+ *     untouched, and nothing written: the flag-off run loop is main's.
+ *
+ * A turn is ok only when its outcome reached the pod: the reply was delivered
+ * or the agent chose silence. The run loop names the outcome after delivery
+ * settles (turn.finish); a spawn that threw is `failed` at once.
+ *
+ * NO RECORD WRITER. The supervisor needs a trace store. The one here
+ * (createMetadataStore) is in memory, lives for one turn, and keeps event type
+ * names, times and the recovery action word. It drops every event's data, so
+ * no agent text, prompt, reply, failure detail or credential is kept, and
+ * nothing is written to disk (a redaction review on #2701).
+ *
+ * Metrics: ~/.commonly/state/turns/<seat>.jsonl (COMMONLY_TURN_LOG_DIR
+ * overrides the directory). Whitelisted fields only; see metricLine.
+ */
+import { appendFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { superviseRun as defaultSuperviseRun } from '@commonlyai/seats/supervisor';
+import { isEventType } from '@commonlyai/seats/trace/events';
+import { failureKindOf } from '@commonlyai/seats/failures';
+import { classifySpawnFailure } from './spawn-retry.js';
+
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * Stall windows per adapter, in ms; 0 is off. Unlisted adapters: off.
+ *
+ * codex: `codex exec --json` writes a JSONL event per item, so its stdout is a
+ *   real progress signal, and the quiet stretch is the longest single item (a
+ *   reasoning step or one shell command). Measured 2026-10-25 from per-turn
+ *   timestamp gaps in October codex rollouts on one host (~/.codex/sessions):
+ *   9,703 turns, max quiet gap 162 s, p99 53 s; 9 turns would have tripped the
+ *   package default of 120 s. 15 min is 5.5x the worst gap seen and still
+ *   30 min inside the seats' 45 min turn budget.
+ * claude: the adapter runs `claude -p --output-format text`, which writes
+ *   nothing to stdout until the reply is done. A healthy 14-minute claude turn
+ *   is 14 minutes of silence to the supervisor, so any window
+ *   under the turn budget would be a turn-length cap, not a liveness check.
+ *   Off; claude is guarded by the wall-clock backstop and the cancel ladder.
+ */
+export const STALL_DEFAULTS_MS = Object.freeze({ codex: 15 * 60 * 1000, claude: 0 });
+// How long after the supervisor's abort before it SIGKILLs the child's tree
+// (process-group.js). The claude and codex adapters do not act on the abort,
+// so on a stall the child is alive at the kill and its whole tree goes with it:
+// a SIGTERM to the CLI alone would let it exit first and orphan the MCP
+// servers it started in groups of their own, which the tree kill then skips.
+// An adapter that honours ctx.signal gets this long to settle.
+export const CANCEL_GRACE_MS = 15_000;
+// The wall clock sits past the adapter's own timeout, so the adapter's timeout
+// (the same SIGTERM and error as on the plain path) fires first; the
+// supervisor's only settles a child that outlived it.
+export const WALL_BACKSTOP_MS = 60_000;
+// After a failed turn, how long to wait for the child's exit status before
+// writing the metric line anyway (the kill lands just before settle).
+const EXIT_WAIT_MS = 3_000;
+
+const envName = (prefix, adapterName) => `${prefix}_${String(adapterName || '').toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+
+const envMs = (env, name, warnings) => {
+  const raw = env?.[name];
+  if (raw === undefined || raw === '') return undefined;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    warnings.push(`${name} ignored (want a non-negative integer of ms)`);
+    return undefined;
+  }
+  return Math.min(value, MAX_TIMER_MS);
+};
+
+/**
+ * The supervisor policy for one adapter's turn. Env overrides, most specific
+ * first: COMMONLY_SUPERVISE_STALL_MS_<ADAPTER>, COMMONLY_SUPERVISE_STALL_MS,
+ * COMMONLY_SUPERVISE_CANCEL_GRACE_MS, COMMONLY_SUPERVISE_WALL_BACKSTOP_MS.
+ * 0 turns a window off. No retries: the run loop keeps those.
+ */
+export const supervisedRunPolicy = (turnTimeoutMs, { adapterName = null, env = process.env, warnings = [] } = {}) => {
+  const stallMs = envMs(env, envName('COMMONLY_SUPERVISE_STALL_MS', adapterName), warnings)
+    ?? envMs(env, 'COMMONLY_SUPERVISE_STALL_MS', warnings)
+    ?? STALL_DEFAULTS_MS[adapterName] ?? 0;
+  const cancelGraceMs = envMs(env, 'COMMONLY_SUPERVISE_CANCEL_GRACE_MS', warnings) ?? CANCEL_GRACE_MS;
+  const backstopMs = envMs(env, 'COMMONLY_SUPERVISE_WALL_BACKSTOP_MS', warnings) ?? WALL_BACKSTOP_MS;
+  return {
+    stallMs,
+    cancelGraceMs,
+    timeoutMs: Math.min(Number(turnTimeoutMs) + backstopMs, MAX_TIMER_MS),
+  };
+};
+
+/**
+ * A trace store that keeps no agent text and writes nothing. superviseRun
+ * calls startRun once per turn; each event keeps { type, at, action? }.
+ */
+export const createMetadataStore = ({ now = Date.now } = {}) => {
+  let current = null;
+  let seq = 0;
+  return {
+    startRun({ runId } = {}) {
+      seq += 1;
+      const events = [];
+      let settled = false;
+      current = {
+        runId: runId || `turn-${now().toString(36)}-${seq}`,
+        emit(type, data) {
+          if (!isEventType(type)) throw new Error(`unknown trace event type: ${type}`);
+          if (settled) return null;
+          const entry = { type, at: now() };
+          if (type === 'liveness.recovery' && typeof data?.action === 'string') entry.action = data.action;
+          events.push(entry);
+          if (type === 'run.settled') settled = true;
+          return entry;
+        },
+        get settled() { return settled; },
+        events: () => events.map((entry) => ({ ...entry })),
+      };
+      return current;
+    },
+    lastRun: () => current,
+  };
+};
+
+export const metricsPathFor = (seat, env = process.env) => {
+  const dir = env?.COMMONLY_TURN_LOG_DIR || join(homedir(), '.commonly', 'state', 'turns');
+  const safe = String(seat || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64) || 'unknown';
+  return join(dir, `${safe}.jsonl`);
+};
+
+/** A failure's name, never its text. RunFailure kinds are the supervisor's words. */
+export const failureNameOf = (error) => {
+  const kind = failureKindOf(error) || (typeof error?.kind === 'string' && /^[a-z_]{1,40}$/.test(error.kind) ? error.kind : null);
+  if (kind) return { name: kind, source: 'supervisor' };
+  const message = String(error?.message ?? error ?? '');
+  if (/\btimed out after \d+ms\b/.test(message)) return { name: 'adapter_timeout', source: 'adapter' };
+  if (/\bexited with code\b/.test(message)) return { name: 'adapter_exit', source: 'adapter' };
+  return { name: 'adapter_error', source: 'adapter' };
+};
+
+const failureClassOf = (error) => {
+  try { return classifySpawnFailure(error); } catch { return null; }
+};
+
+// What happened to a turn, named by the run loop once delivery settles.
+export const TURN_OUTCOMES = Object.freeze([
+  'delivered', // the reply reached the pod (wrapper post, the agent's own post, or an ask response)
+  'silent', // NO_REPLY, a heartbeat control word, or empty output: nothing to post
+  'reply_lost', // the model answered and every delivery rung threw
+  'claim_lost', // the lease lapsed mid-turn and a peer owns the message; reply suppressed
+  'server_skipped', // the server answered and created nothing (a duplicate, a kept heartbeat)
+  'server_refused', // the server refused the post (a run cap)
+  'upstream_refused', // the model route refused; the CLI exited with nothing to say
+]);
+export const OK_OUTCOMES = Object.freeze(['delivered', 'silent']);
+
+const EVENT_TYPE_RE = /^[A-Za-z0-9._-]{1,40}$/;
+const iso = (ms) => new Date(ms).toISOString();
+const int = (value) => (Number.isInteger(value) ? value : null);
+
+/**
+ * The metric line. Every field is listed here, each a number, boolean, null or
+ * a short fixed word; nothing from the prompt, the reply, a failure's detail or
+ * the environment can reach it.
+ */
+export const metricLine = (f) => {
+  const failed = f.outcome === 'failed';
+  const outcome = failed || TURN_OUTCOMES.includes(f.outcome) ? f.outcome : 'unknown';
+  return {
+    v: 1,
+    ts: iso(f.settledMs ?? f.endMs),
+    seat: String(f.seat || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64),
+    adapter: String(f.adapter || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 32),
+    path: f.path === 'supervised' ? 'supervised' : 'legacy',
+    eventType: EVENT_TYPE_RE.test(String(f.eventType || '')) ? f.eventType : null,
+    turnStart: iso(f.startMs),
+    turnEnd: iso(f.endMs),
+    durationMs: Math.max(0, f.endMs - f.startMs),
+    outcome,
+    ok: OK_OUTCOMES.includes(outcome),
+    failure: failed ? (f.failureName || 'adapter_error') : null,
+    failureSource: failed ? (f.failureSource || null) : null,
+    failureClass: failed && typeof f.failureClass === 'string' ? f.failureClass : null,
+    stalled: !!f.stalled,
+    cancelled: !!f.cancelled,
+    killed: !!f.killed,
+    exitCode: int(f.exitCode),
+    signal: typeof f.signal === 'string' && /^SIG[A-Z0-9]+$/.test(f.signal) ? f.signal : null,
+    exitObserved: !!f.exitObserved,
+    childLeftRunning: typeof f.childLeftRunning === 'boolean' ? f.childLeftRunning : null,
+    attempts: int(f.attempts),
+    stallMs: int(f.policy?.stallMs),
+    cancelGraceMs: int(f.policy?.cancelGraceMs),
+    timeoutMs: int(f.policy?.timeoutMs),
+  };
+};
+
+const isChild = (value) => !!value && typeof value.once === 'function' && typeof value.kill === 'function';
+const isAlive = (child) => !!child && child.exitCode === null && child.signalCode === null;
+
+const waitForExit = (child, ms) => new Promise((resolve) => {
+  if (!isAlive(child)) { resolve(); return; }
+  const timer = setTimeout(resolve, ms);
+  timer.unref?.();
+  child.once('exit', () => { clearTimeout(timer); resolve(); });
+});
+
+/**
+ * @param {object} args
+ * @param {string} args.seat            agent name; names the metrics file
+ * @param {number} args.turnTimeoutMs   the run loop's effective turn budget
+ * @param {boolean} args.supervise      performRun's superviseRuns
+ * @param {(line: string) => void} [args.log]
+ * @param {object} [args.env]
+ * @param {Function} [args.superviseRun]  injectable for tests
+ */
+export const createTurnRunner = ({
+  seat,
+  turnTimeoutMs,
+  supervise = false,
+  log = () => {},
+  env = process.env,
+  now = Date.now,
+  superviseRun = defaultSuperviseRun,
+} = {}) => {
+  const metricsPath = metricsPathFor(seat, env);
+  let metricsWarned = false;
+
+  const record = (fields) => {
+    try {
+      mkdirSync(dirname(metricsPath), { recursive: true, mode: 0o700 });
+      appendFileSync(metricsPath, `${JSON.stringify(metricLine({ seat, ...fields }))}\n`, { mode: 0o600 });
+    } catch (error) {
+      // Metrics never fail a turn. Said once per process, not per turn.
+      if (!metricsWarned) {
+        metricsWarned = true;
+        log(`turn metrics not written (${error?.code || 'error'}); turns are unaffected`);
+      }
+    }
+  };
+
+  /** The boot line for the supervised path; the plain path logs nothing new. */
+  const describe = (adapterName) => {
+    const warnings = [];
+    const policy = supervisedRunPolicy(turnTimeoutMs, { adapterName, env, warnings });
+    return `supervised runs ON for ${adapterName}: stall=${policy.stallMs ? `${policy.stallMs}ms` : 'off'}, `
+      + `cancel grace=${policy.cancelGraceMs}ms, wall=${policy.timeoutMs}ms, `
+      + 'trace=memory (no record written); '
+      + `metrics → ${metricsPath}${warnings.length ? `; ${warnings.join('; ')}` : ''}`;
+  };
+
+  const runSupervised = async (adapter, prompt, ctx, eventType, hold) => {
+    const startMs = now();
+    const policy = supervisedRunPolicy(turnTimeoutMs, { adapterName: adapter?.name, env });
+    const store = createMetadataStore({ now });
+    let child = null;
+    let exit = null;
+    const callerOnSpawn = ctx?.onSpawn;
+    const onSpawn = (...args) => {
+      const proc = args.find(isChild);
+      if (proc) {
+        child = proc;
+        exit = null;
+        proc.once('exit', (code, signal) => { if (child === proc) exit = { code, signal }; });
+      }
+      return typeof callerOnSpawn === 'function' ? callerOnSpawn(...args) : undefined;
+    };
+
+    const supervised = await superviseRun({
+      adapter,
+      prompt,
+      ctx: { ...ctx, onSpawn },
+      store,
+      policy,
+      label: EVENT_TYPE_RE.test(String(eventType || '')) ? eventType : undefined,
+    });
+
+    const ok = !supervised.failure;
+    if (!ok) await waitForExit(child, EXIT_WAIT_MS);
+    const events = store.lastRun()?.events() || [];
+    const recovered = (action) => events.some((e) => e.type === 'liveness.recovery' && e.action === action);
+    const killed = recovered('kill');
+    const named = ok ? null : failureNameOf(supervised.failure);
+    const fields = {
+      adapter: adapter?.name,
+      path: 'supervised',
+      eventType,
+      startMs,
+      endMs: now(),
+      outcome: ok ? undefined : 'failed',
+      failureName: named?.name,
+      failureSource: named?.source,
+      failureClass: ok ? null : failureClassOf(supervised.failure),
+      stalled: events.some((e) => e.type === 'liveness.stalled'),
+      cancelled: recovered('cancel'),
+      killed,
+      exitCode: exit ? exit.code : null,
+      signal: exit ? exit.signal : null,
+      exitObserved: !!exit,
+      childLeftRunning: child ? isAlive(child) : null,
+      attempts: supervised.attempts,
+      policy,
+    };
+    // A spawn that resolved is not yet an ok turn: the line waits for the run
+    // loop to say what became of the reply.
+    if (ok) { hold(fields); return supervised.result; }
+    record(fields);
+    if (named.source === 'supervisor') {
+      // The name goes in the seat log. The throw takes the road a plain-path
+      // failure takes: unacked, the run loop's retry policy, onError.
+      log(`[${eventType}] supervised turn failed: ${named.name}${killed ? ' (child killed)' : ''}`
+        + `${isAlive(child) ? ' (child still running)' : ''}`);
+    }
+    throw supervised.failure;
+  };
+
+  return {
+    supervise,
+    metricsPath,
+    describe,
+    /**
+     * One model turn. `run` has adapter.spawn's contract; `finish(outcome)`
+     * writes the line once delivery has settled. Only the first finish counts,
+     * and a finish with no spawned turn behind it writes nothing.
+     */
+    begin({ eventType } = {}) {
+      let held = null;
+      let done = false;
+      return {
+        run(adapter, prompt, ctx) {
+          if (!supervise) return adapter.spawn(prompt, ctx);
+          return runSupervised(adapter, prompt, ctx, eventType, (fields) => { held = fields; });
+        },
+        finish(outcome) {
+          if (done || !held) return;
+          done = true;
+          record({ ...held, outcome, settledMs: now() });
+        },
+      };
+    },
+  };
+};

package/src/lib/update-check.js

@@ -0,0 +1,185 @@
+/**
+ * "Your CLI is N versions behind" — one line at `agent run` and `daemon run`
+ * start-up (TASK-660, D213).
+ *
+ * A seat pinned to an old CLI fails in ways that look like platform bugs, and
+ * nothing on the seat said it was old. This prints one line when the installed
+ * CLI trails npm latest by UPDATE_NOTICE_MIN_BEHIND or more, and is otherwise
+ * silent: offline, a slow registry, a malformed answer and
+ * COMMONLY_NO_UPDATE_CHECK=1 all print nothing.
+ *
+ * It must never slow start-up. `startUpdateNotice` returns at once; the lookup
+ * runs beside the poll loop, is capped at UPDATE_TIMEOUT_MS by its own timer
+ * (a fetch that ignores its abort signal still cannot hold it), and is cached
+ * for UPDATE_CACHE_TTL_MS so a restarting seat asks the registry once a day.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { exactVersion, parseVersion } from './mcp-server-version.js';
+
+export const CLI_PACKAGE = '@commonlyai/cli';
+export const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@commonlyai%2fcli/latest';
+export const UPDATE_CHECK_OPT_OUT_ENV = 'COMMONLY_NO_UPDATE_CHECK';
+export const UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+export const UPDATE_TIMEOUT_MS = 2000;
+// The CLI publishes often, so one or two releases behind is the normal gap
+// between a publish and a seat's next restart. Three is where it is stale.
+export const UPDATE_NOTICE_MIN_BEHIND = 3;
+
+export const updateCachePath = (home = homedir()) => join(home, '.commonly', 'update-check.json');
+
+/**
+ * How far `installed` trails `latest`: 0 when equal or ahead, the patch gap
+ * within one major.minor, and Infinity when latest is a newer minor or major
+ * (the patch numbers of two release lines say nothing about the distance).
+ * null when either side is not a version.
+ */
+export const versionsBehind = (installed, latest) => {
+  const a = parseVersion(installed);
+  const b = parseVersion(latest);
+  if (!a || !b) return null;
+  if (a[0] !== b[0] || a[1] !== b[1]) {
+    return (b[0] > a[0] || (b[0] === a[0] && b[1] > a[1])) ? Infinity : 0;
+  }
+  return Math.max(0, b[2] - a[2]);
+};
+
+/** The one line to print, or null when there is nothing worth saying. */
+export const updateNoticeLine = ({ installed, latest, minBehind = UPDATE_NOTICE_MIN_BEHIND }) => {
+  const behind = versionsBehind(installed, latest);
+  if (behind === null || behind < minBehind) return null;
+  // Only the parsed triple is printed: the registry's string never reaches the log.
+  const from = exactVersion(installed);
+  const to = exactVersion(latest);
+  const gap = Number.isFinite(behind) ? `${behind} versions behind` : 'behind a newer release line';
+  return `your CLI is ${gap} (installed ${from}, latest ${to}). Update: npm install -g ${CLI_PACKAGE}@latest`
+    + ` (silence with ${UPDATE_CHECK_OPT_OUT_ENV}=1)`;
+};
+
+const defaultReadText = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null);
+const defaultWriteText = (path, text) => {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text, { encoding: 'utf8', mode: 0o600 });
+};
+
+/** The cached latest version when the cache is younger than the TTL, else null. */
+export const readCachedLatest = ({ cachePath, now, readText = defaultReadText, ttlMs = UPDATE_CACHE_TTL_MS }) => {
+  let raw;
+  try {
+    raw = readText(cachePath);
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  try {
+    const cache = JSON.parse(raw);
+    const checkedAt = Date.parse(cache?.checkedAt);
+    const latest = exactVersion(cache?.latest);
+    if (!Number.isFinite(checkedAt) || !latest) return null;
+    if (now - checkedAt < 0 || now - checkedAt >= ttlMs) return null;
+    return latest;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * npm latest, or null on any failure. The timer is the cap, not the signal:
+ * the signal asks fetch to stop, the race guarantees the answer is on time.
+ */
+export const fetchLatestVersion = async ({
+  fetchImpl = globalThis.fetch,
+  timeoutMs = UPDATE_TIMEOUT_MS,
+  url = REGISTRY_LATEST_URL,
+} = {}) => {
+  if (typeof fetchImpl !== 'function') return null;
+  const controller = new AbortController();
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve(null);
+    }, timeoutMs);
+    timer.unref?.();
+  });
+  const lookup = (async () => {
+    const res = await fetchImpl(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+    if (!res?.ok) return null;
+    const body = await res.json();
+    return exactVersion(body?.version);
+  })().catch(() => null);
+  try {
+    return await Promise.race([lookup, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** The notice line for this start-up, or null. Never throws. */
+export const checkForCliUpdate = async ({
+  installedVersion,
+  env = process.env,
+  now = Date.now(),
+  cachePath = updateCachePath(),
+  fetchImpl = globalThis.fetch,
+  timeoutMs = UPDATE_TIMEOUT_MS,
+  readText = defaultReadText,
+  writeText = defaultWriteText,
+  minBehind = UPDATE_NOTICE_MIN_BEHIND,
+} = {}) => {
+  try {
+    if (env?.[UPDATE_CHECK_OPT_OUT_ENV] === '1') return null;
+    if (!parseVersion(installedVersion)) return null;
+    let latest = readCachedLatest({ cachePath, now, readText });
+    if (!latest) {
+      latest = await fetchLatestVersion({ fetchImpl, timeoutMs });
+      if (!latest) return null;
+      try {
+        writeText(cachePath, `${JSON.stringify({ checkedAt: new Date(now).toISOString(), latest })}\n`);
+      } catch {
+        // An unwritable cache costs one lookup per start, nothing more.
+      }
+    }
+    return updateNoticeLine({ installed: installedVersion, latest, minBehind });
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Fire the check and return at once. The returned promise (for tests) settles
+ * to the line that was logged, or null.
+ */
+export const startUpdateNotice = (params = {}) => Promise.resolve()
+  // Everything, the argument destructuring and checkForCliUpdate's default
+  // parameters (homedir()) included, runs inside the chain, so the trailing
+  // catch is the only exit a failure has. Start-up never sees a throw or an
+  // unhandled rejection from here.
+  .then(async () => {
+    const { log, ...options } = params;
+    const line = await checkForCliUpdate(options);
+    if (line) {
+      try {
+        log(line);
+      } catch {
+        // A closed log sink is not start-up's problem.
+      }
+    }
+    return line;
+  })
+  .catch(() => null);
+
+let cachedCliVersion;
+/** This CLI's own version, from the package.json it shipped with. */
+export const installedCliVersion = () => {
+  if (cachedCliVersion === undefined) {
+    try {
+      const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+      cachedCliVersion = typeof pkg?.version === 'string' ? pkg.version : null;
+    } catch {
+      cachedCliVersion = null;
+    }
+  }
+  return cachedCliVersion;
+};