@commonlyai/cli 0.1.210 → 0.1.212

package/package.json

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

package/src/commands/agent.js

@@ -88,6 +88,7 @@ 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';
@@ -535,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.
@@ -1362,6 +1386,15 @@ const extractPrompt = (event) => {
 // cancel grace, and the wall-clock backstop past the adapter's own timeout.
 export { supervisedRunPolicy };
 
+// Codex turns are supervised by default (D211): a turn that stops making
+// progress is named and killed instead of holding the seat. COMMONLY_SUPERVISE_RUNS=0
+// opts out. Every other adapter stays off unless COMMONLY_SUPERVISE_RUNS=1.
+export const superviseRunsByDefault = (adapterName, env = process.env) => {
+  if (env.COMMONLY_SUPERVISE_RUNS === '0') return false;
+  if (adapterName === 'codex') return true;
+  return env.COMMONLY_SUPERVISE_RUNS === '1';
+};
+
 /**
  * Start the run loop. Polls /events, spawns the adapter per event, posts the
  * result into the pod, acks.
@@ -1437,14 +1470,15 @@ 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',
+  // Each spawn runs under the seats supervisor (stall window, wall-clock
+  // backstop, a named failure on every settle) when superviseRuns is true.
+  // Unset, the default comes from superviseRunsByDefault. 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,
 }) => {
+  const supervising = superviseRuns ?? superviseRunsByDefault(adapter?.name);
   reportRuntime = reportRuntime && WALKED_HARNESSES.includes(adapter?.name);
   if (environment?.provider !== undefined && !adapter?.supportsProvider) {
     throw new Error('environment.provider requires a provider-capable adapter');
@@ -1456,9 +1490,9 @@ export const performRun = ({
   // 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,
+    seat: agentName, turnTimeoutMs: effectiveTurnTimeoutMs, supervise: supervising, log,
   });
-  if (superviseRuns) log(turnRunner.describe(adapter?.name));
+  if (supervising) log(turnRunner.describe(adapter?.name));
   const runtimeReporter = createRuntimeReporter({
     client: runtimeReportClient || { post: async () => {} },
     harness: adapter.name, detect: () => adapter.detect(),
@@ -1871,7 +1905,7 @@ 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.
-  // With superviseRuns, the turn's log line is written once delivery has
+  // With supervising, 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) => {
@@ -4100,6 +4134,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/adapters/codex.js

@@ -897,6 +897,13 @@ export default {
         await writePublicCodexInstructions(childEnv.CODEX_HOME, ctx);
       }
 
+      // The awaits above can outlast a supervisor stall window. Once it has
+      // aborted, the attempt has already settled and a retry may be running,
+      // so no process is created for this one. Checked synchronously before
+      // runCodex, so the spawn itself cannot race the abort.
+      if (ctx.signal?.aborted) {
+        throw ctx.signal.reason || new Error('codex spawn cancelled before the process started');
+      }
       const { threadId } = await runCodex({
         args,
         cwd: ctx.cwd,

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

@@ -3,7 +3,8 @@
  * 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`)
+ *   codex by default, or COMMONLY_SUPERVISE_RUNS=1 (superviseRunsByDefault in
+ *     commands/agent.js; COMMONLY_SUPERVISE_RUNS=0 opts codex out)
  *     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,

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;
+};