@ravefox/space 0.0.0-stage → 0.2.0

package/src/commands/daemon.js

@@ -0,0 +1,933 @@
+import { collectRuntimeInventory, createInventoryCache } from '../lib/runtime-inventory.js';
+/**
+ * commonly daemon <subcommand>
+ *
+ * Phase 2, slice 1: register one machine, persist its scoped daemon bearer,
+ * and report/send heartbeats. Adoption and supervision deliberately arrive in
+ * later slices; this command never reads an agent runtime credential.
+ */
+
+import { hostname, homedir } from 'os';
+import { spawn } from 'child_process';
+import {
+  chmodSync, closeSync, existsSync, mkdirSync, openSync, rmSync, watch,
+} from 'fs';
+import { createClient } from '../lib/api.js';
+import { getToken, resolveInstance, resolveInstanceUrl } from '../lib/config.js';
+import {
+  clearDaemonStop, loadDaemonRecord, loadDaemonStop, removeDaemonRecord,
+  saveDaemonRecord, saveDaemonStop,
+} from '../lib/daemon-store.js';
+import {
+  createDaemonSupervisor,
+  DEFAULT_HEARTBEAT_MS,
+  DEFAULT_POLL_MS,
+} from '../lib/daemon-supervisor.js';
+import { loadAgentToken, saveAgentToken } from './agent.js';
+import { getLastTurn } from '../lib/session-store.js';
+import { getAdapter, providerKeyEnvNames, seatProviderKeyEnv } from '../lib/adapters/index.js';
+import { loginState, runLoginStatus, signedOutAdapters, signedOutHint } from '../lib/adapter-login.js';
+
+import {
+  installDaemonService,
+  installSummary,
+  uninstallDaemonService,
+  startDaemonService,
+  stopDaemonService,
+  restartDaemonService,
+  daemonLogPath,
+  servicePaths,
+  serviceOwnerQuery,
+  loadedServiceFile,
+  foreignServiceRefusal,
+  decodeCmdOutput,
+} from '../lib/daemon-service.js';
+
+import { daemonLogsDir, daemonSeatLogPath, readLogTail } from '../lib/daemon-logs.js';
+import { watchWindowsLauncher } from '../lib/daemon-service-windows.js';
+import {
+  UNSANDBOXED_FLAG, clearUnsandboxedOptIn, hostSandboxReport, loadUnsandboxedOptIn, saveUnsandboxedOptIn, unsandboxedFlagRefusal,
+} from '../lib/sandbox/windows-unsandboxed.js';
+import { loadDaemonState, saveDaemonState } from '../lib/daemon-state.js';
+import {
+  CLEAR_SCREEN, renderDaemonWatch, shouldRedraw, WATCH_INTERVAL_MS,
+} from '../lib/daemon-watch.js';
+import {
+  createReachCache, loadPodReach, readSessionLastTurn,
+} from '../lib/daemon-agent-states.js';
+import { installedCliVersion, startUpdateNotice, UPDATE_CHECK_OPT_OUT_ENV } from '../lib/update-check.js';
+import { machineHostReport } from '../lib/machine-host.js';
+import { orchestrateDaemonSetup } from '../lib/stable-install.js';
+import { CLI } from '../lib/cli-hint.js';
+
+// Set on the steps `daemon setup` runs, so a step can leave a line to setup.
+const SETUP_CHILD_ENV = 'COMMONLY_DAEMON_SETUP_STEP';
+
+// F459: login and register take --instance, so the first-timer walk tried it
+// on run too and got "unknown option". Run serves the one registration this
+// computer has, so --instance only confirms it: the same instance runs, any
+// other (or an unknown saved key) is refused with the register line instead of
+// quietly serving the registered one.
+const instanceKey = (url) => String(url || '').replace(/\/+$/, '').toLowerCase();
+export const daemonRunInstanceRefusal = (record, instanceArg, resolve = resolveInstance) => {
+  if (!instanceArg) return null;
+  const wanted = resolve(instanceArg)?.url;
+  if (wanted && instanceKey(wanted) === instanceKey(record?.instanceUrl)) return null;
+  if (!wanted) {
+    return `This computer is registered with ${record?.instanceUrl}, and no saved instance is named ${instanceArg}. `
+      + `To use another instance, sign in to it first (${CLI} login --instance <url>), then ${CLI} daemon register --instance <url>`;
+  }
+  return `This computer is registered with ${record?.instanceUrl}, not ${instanceArg}. To run it for that instance instead: `
+    + `${CLI} daemon register --instance ${instanceArg}`;
+};
+
+// launchd, systemd and Task Scheduler hold one Commonly daemon per computer
+// account. Install refuses to stop another HOME's; this flag takes it over.
+const REPLACE_FLAG = '--replace';
+const REPLACE_HELP = 'Replace a Space daemon that another account (another HOME) runs on this computer account. Without it, install stops and names that daemon.';
+
+// 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
+// platform routes by, so a seat attached to the wrong instance is otherwise
+// invisible) and the supervisor's `restarts` flap counter — which is written,
+// persisted and served, and was shown by no surface at all, so a seat that had
+// been crash-looping looked exactly like a healthy one (TASK-072, 2026-09-19).
+//
+// `restarts` distinguishes 0 from absent on purpose: a state file written by an
+// older daemon has no such field, and printing 0 for it would claim a reading the
+// file does not carry.
+export const formatSeatLine = (seat = {}) => {
+  const model = seat.model || 'default model';
+  const effort = seat.effort ? `/${seat.effort}` : '';
+  const error = seat.lastError ? ` error=${seat.lastError}` : '';
+  const restarts = seat.restarts === undefined || seat.restarts === null ? '-' : seat.restarts;
+  return `  ${seat.agentName}: ${seat.state} instance=${seat.instanceId || '-'} adapter=${seat.adapter || 'unknown'} model=${model}${effort} pid=${seat.pid || '-'} restarts=${restarts} lastTurn=${seat.lastTurnAt || 'never'}${error}`;
+};
+
+// `daemon status --watch`: one frame, then a redraw every 2 s on a terminal. Off a
+// terminal, or with NO_COLOR set, it prints one frame and returns. A failed
+// fetch is shown in the frame, so the loop keeps running through a brief outage.
+const watchDaemonStatus = async () => {
+  const redraw = shouldRedraw({ isTTY: process.stdout.isTTY });
+  // Each agent's pod comes from its token record. The verdict for a pod is read
+  // through the operator's login and cached for 10 s, so the 2 s frame does not
+  // re-read it. A failed read is thrown, so the next frame retries.
+  const reachFor = createReachCache({
+    load: (podId) => loadPodReach({
+      client: createClient({ instance: requireDaemonRecord().instanceUrl }),
+      podId,
+    }),
+  });
+  const frame = async () => {
+    try {
+      const record = requireDaemonRecord();
+      // A failed machine read still shows the local seats and logs, with the
+      // machine marked unreachable, so the operator can see what is running here.
+      let machine;
+      let machineNote = '';
+      try {
+        machine = await getDaemonMachineStatus({
+          client: createClient({ instance: record.instanceUrl, token: record.daemonToken }),
+          record,
+        });
+      } catch (error) {
+        machine = { name: record.machineName, status: 'unreachable', lastSeenAt: null };
+        machineNote = `Machine status unavailable (${error.message}): showing local seats only.`;
+      }
+      const seats = (loadDaemonState()?.seats || []).map((seat) => ({
+        ...seat,
+        // The supervisor stamps spawn time; the session store holds real turns.
+        lastTurnAt: readSessionLastTurn(seat.recordKey || seat.agentName),
+      }));
+      // Keyed by the local record, so two instances of one agent never read
+      // each other's log, last turn or pod (F427).
+      const logTails = {};
+      for (const seat of seats) {
+        const key = seat.recordKey || seat.agentName;
+        const tail = readLogTail(daemonSeatLogPath(key), 3);
+        logTails[key] = tail ? tail.split('\n') : [];
+      }
+      let states = null;
+      let stateNote = '';
+      if (!getToken(record.instanceUrl)) {
+        stateNote = `Not logged in: showing local process state only. Run: ${CLI} login --instance ${record.instanceUrl}`;
+      } else {
+        const podIds = [...new Set(seats.map((seat) => loadAgentToken(seat.recordKey || seat.agentName)?.podId).filter(Boolean))];
+        try {
+          states = await reachFor(podIds);
+        } catch (error) {
+          stateNote = `Agent states unavailable (${error.message}): showing local process state only`;
+        }
+      }
+      return renderDaemonWatch({
+        machine, seats, logTails, states, stateNote: [machineNote, stateNote].filter(Boolean).join(' '), now: Date.now(), width: process.stdout.columns || 80, color: redraw,
+      });
+    } catch (error) {
+      return daemonStatusErrorMessage(error);
+    }
+  };
+  if (!redraw) {
+    console.log(await frame());
+    return;
+  }
+  let busy = false;
+  const tick = async () => {
+    if (busy) return;
+    busy = true;
+    try {
+      process.stdout.write(`${CLEAR_SCREEN}${await frame()}\n`);
+    } finally {
+      busy = false;
+    }
+  };
+  await tick();
+  const timer = setInterval(tick, WATCH_INTERVAL_MS);
+  const stop = () => {
+    clearInterval(timer);
+    process.stdout.write('\n');
+    process.exit(0);
+  };
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+};
+
+const requireDaemonRecord = () => {
+  const record = loadDaemonRecord();
+  if (!record) {
+    throw new Error(`No local daemon is registered. Run: ${CLI} daemon register`);
+  }
+  return record;
+};
+
+const requireUserToken = (instance) => {
+  const token = getToken(instance);
+  if (!token) throw new Error(`Not logged in to ${instance}. Run: ${CLI} login --instance ${instance}`);
+  return token;
+};
+
+const requireRegistrationResponse = (response) => {
+  const machine = response?.machine;
+  if (!machine?.id || !machine?.machineId || !machine?.name || !response?.daemonToken) {
+    throw new Error('Server returned an incomplete machine registration. No daemon credential was stored.');
+  }
+  return { machine, daemonToken: response.daemonToken };
+};
+
+// Exported for a service-level test: persistence failure must revoke the
+// freshly-created machine because the raw bearer is not recoverable later.
+export const registerDaemonMachine = async ({
+  client,
+  instanceUrl,
+  name,
+  persist = saveDaemonRecord,
+  host = machineHostReport(),
+}) => {
+  // TASK-784: the host report is metadata only (platform, OS release major,
+  // arch, CLI version). An older server ignores it.
+  const { machine, daemonToken } = requireRegistrationResponse(
+    await client.post('/api/machines', { name, host }),
+  );
+  const record = {
+    machineDbId: machine.id,
+    machineId: machine.machineId,
+    machineName: machine.name,
+    instanceUrl,
+    daemonToken,
+    registeredAt: new Date().toISOString(),
+  };
+
+  try {
+    persist(record);
+  } catch (error) {
+    // The token is a one-time response. If it cannot be secured locally, tear
+    // down the server row so it cannot remain a live, unrecoverable bearer.
+    try {
+      await client.del(`/api/machines/${machine.id}`);
+    } catch (revokeError) {
+      throw new Error(
+        `Could not store the daemon credential and could not revoke machine ${machine.name} (${machine.id}): ${revokeError.message}`,
+      );
+    }
+    throw new Error(`Could not store the daemon credential securely: ${error.message}. Machine registration was revoked.`);
+  }
+
+  return { machine, record };
+};
+
+// What each supervisor check-in tells the server about this computer.
+// Native Windows has no OS sandbox for any adapter, so it never reports
+// 'default': Codex there runs on its own profiles only, and a removed marker
+// must not read as "confined" while seats may still run. An older daemon sends
+// neither field, which leaves the server's record. TASK-784: the host report
+// rides along, so a machine an older CLI registered fills in on upgrade.
+export const daemonMachineReport = () => ({ sandbox: hostSandboxReport(), host: machineHostReport() });
+
+export const heartbeatDaemonMachine = async ({ client, record }) => (
+  client.post(`/api/machines/${record.machineDbId}/heartbeat`)
+);
+
+export const getDaemonMachineStatus = async ({ client, record }) => {
+  const response = await client.get('/api/machines/me');
+  const machine = response?.machine;
+  if (!machine || typeof machine !== 'object' || Array.isArray(machine)
+      || !machine.id || !machine.machineId
+      || (record && (machine.id !== record.machineDbId || machine.machineId !== record.machineId))) {
+    throw new Error('Unexpected daemon status response; local credential kept.');
+  }
+  return machine;
+};
+
+const isRevokedDaemonKey = (error) => error?.status === 401 && [
+  'Daemon token revoked or unknown',
+  'Machine access revoked',
+].includes(error?.body?.message);
+
+const isMissingDaemonMachine = (error) => error?.status === 404
+  && error?.body?.message === 'Machine not found';
+
+const storedDaemonState = async (client, record) => {
+  try {
+    await getDaemonMachineStatus({ client, record });
+    return 'active';
+  } catch (error) {
+    if (isRevokedDaemonKey(error)) return 'revoked';
+    if (isMissingDaemonMachine(error)) return 'missing';
+    throw error;
+  }
+};
+
+export const daemonStatusErrorMessage = (error) => (isRevokedDaemonKey(error)
+  ? `This computer's old key was revoked. Run: ${CLI} daemon register`
+  : isMissingDaemonMachine(error)
+    ? `This computer is no longer registered. Run: ${CLI} daemon register`
+  : `Daemon status failed: ${error.message}`);
+
+// `daemon setup` on a computer that is already registered for this instance
+// skips login and register (it would stop at "already registered"). Only a
+// stored key the server still accepts counts; a revoked or missing one goes
+// through register, which replaces it.
+export const setupFindsRegistration = async ({
+  instance, load = loadDaemonRecord, state = storedDaemonState, clientFor = createClient,
+}) => {
+  const record = load();
+  if (!record || !instance) return false;
+  if (String(record.instanceUrl || '').replace(/\/+$/, '') !== instance) return false;
+  const client = clientFor({ instance: record.instanceUrl, token: record.daemonToken });
+  return (await state(client, record)) === 'active';
+};
+
+// Keep the old record until a new registration is securely persisted. A
+// network failure or a still-live daemon key must never silently mint another.
+export const allowRevokedDaemonReplacement = async ({ existing, client }) => {
+  if (!existing) return null;
+  const state = await storedDaemonState(client, existing);
+  if (state === 'active') {
+    throw new Error(`A local daemon is already registered for ${existing.machineName}. Run: ${CLI} daemon status`);
+  }
+  return state;
+};
+
+// Revoke remotely before unlinking locally. An owner-session 401/403 is not
+// proof of revocation: check the stored daemon key before discarding it.
+export const unregisterDaemonMachine = async ({
+  client, daemonClient, record, remove = removeDaemonRecord,
+}) => {
+  let removedRemotely = true;
+  try {
+    await client.del(`/api/machines/${record.machineDbId}`);
+  } catch (error) {
+    if (isMissingDaemonMachine(error)) {
+      removedRemotely = false;
+    } else if ([401, 403].includes(error?.status) && daemonClient) {
+      if (await storedDaemonState(daemonClient, record) === 'active') throw error;
+      removedRemotely = false;
+    } else {
+      throw error;
+    }
+  }
+  remove();
+  return { removedRemotely };
+};
+
+// The adapter names a binary on THIS machine — the one fact the server cannot
+// know (same reasoning as `agent run`'s env bootstrap). A server-declared
+// preference is honored when that CLI is installed; otherwise probe only the
+// established fallbacks. OpenCode must be named explicitly in runtime.adapter.
+export const resolveAdapterForRuntime = async (runtime, registry = { getAdapter }) => {
+  const candidates = [runtime?.adapter, 'claude', 'codex'].filter(Boolean);
+  for (const name of candidates) {
+    const adapter = registry.getAdapter(name);
+    // eslint-disable-next-line no-await-in-loop
+    if (adapter && await adapter.detect()) return name;
+  }
+  return null;
+};
+
+/**
+ * The daemon's first poll and heartbeat, with the Windows launcher watch armed
+ * BEFORE them (D245). Arming first puts the EPIPE guard on stdout and stderr
+ * before any supervision log line, and a launcher that is already gone stops
+ * the daemon here instead of after a tick logged into a dead pipe. Returns
+ * false when the daemon should not go on to its timers.
+ */
+export const firstSupervisionPass = async ({
+  supervisor,
+  onLauncherGone,
+  isEnded = () => false,
+  armLauncherWatch = watchWindowsLauncher,
+}) => {
+  let launcherGone = false;
+  armLauncherWatch({
+    onGone: (pid) => {
+      launcherGone = true;
+      onLauncherGone(pid);
+    },
+  });
+  const stopped = () => launcherGone || isEnded();
+  if (stopped()) return false;
+  await supervisor.tick();
+  if (stopped()) return false;
+  await supervisor.heartbeat();
+  return !stopped();
+};
+
+export const registerDaemon = (program) => {
+  const daemon = program.command('daemon').description('Manage the local Space daemon');
+  const signedOutNotes = async () => (await signedOutAdapters({
+    detect: (name) => getAdapter(name)?.detect(),
+    runStatus: runLoginStatus,
+  })).map((name) => `Note: ${signedOutHint(name)}.`);
+
+  daemon.addHelpText('after', `
+The daemon token is scoped to this machine and stored in a 0600 file under
+~/.commonly/daemon/. It is never shown again after registration.
+
+Examples:
+  $ ${CLI} daemon setup                             # install, log in, register, and start — one step
+  $ ${CLI} daemon register --name "Sam's MacBook"
+  $ ${CLI} daemon heartbeat
+  $ ${CLI} daemon status --verbose
+  $ ${CLI} daemon logs --seat my-agent -f
+  $ ${CLI} daemon start|stop|restart
+  $ ${CLI} daemon unregister
+`);
+
+  daemon
+    .command('setup')
+    .description('From a fresh computer in one step: install the CLI under your home (no sudo, no global install), log in, register this computer, and start the daemon')
+    .option('--instance <url-or-key>', 'Target Space instance')
+    .option(UNSANDBOXED_FLAG, `Native Windows only: the agents this daemon runs have no sandbox (see \`${CLI} daemon install\`). Forwarded to the install step.`)
+    .option(REPLACE_FLAG, REPLACE_HELP)
+    .action(async (opts) => {
+      try {
+        const instanceUrl = resolveInstanceUrl(opts.instance);
+        await orchestrateDaemonSetup({
+          version: installedCliVersion(),
+          instanceUrl,
+          unsandboxed: Boolean(opts.unsandboxed),
+          alreadyRegistered: (instance) => setupFindsRegistration({ instance }),
+          replace: Boolean(opts.replace),
+          foreignDaemon: async () => {
+            const target = servicePaths(process.platform, homedir());
+            const answer = await readServiceCmd(serviceOwnerQuery(process.platform)).catch(() => '');
+            return foreignServiceRefusal({ target, loadedFile: loadedServiceFile(target.kind, answer) });
+          },
+          log: (line) => console.log(line),
+          // Run the stable CLI once with the user's terminal attached, so login
+          // device-auth and any prompts work; reject on a non-zero exit so a
+          // failed step stops the chain before the next one.
+          runCli: (entry, args) => new Promise((resolve, reject) => {
+            // SETUP_CHILD_ENV: register leaves the signed-out note to setup's last line.
+            const child = spawn(process.execPath, [entry, ...args], { stdio: 'inherit', env: { ...process.env, [SETUP_CHILD_ENV]: '1' } });
+            child.on('error', reject);
+            child.on('close', (code) => (code === 0
+              ? resolve()
+              : reject(new Error(`\`commonly ${args.join(' ')}\` exited with code ${code}`))));
+          }),
+        });
+        // Growth's F370 walk: setup said all was well, and the first @mention
+        // then failed with "claude exited 1: Not logged in".
+        for (const line of await signedOutNotes()) console.log(line);
+      } catch (error) {
+        console.error(`Daemon setup failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('register')
+    .description('Register this machine and securely store its daemon credential')
+    .option('--name <name>', 'Machine name (default: this computer\'s hostname)')
+    .option('--instance <url-or-key>', 'Target Space instance')
+    .action(async (opts) => {
+      try {
+        const existing = loadDaemonRecord();
+        if (existing) {
+          const state = await allowRevokedDaemonReplacement({
+            existing,
+            client: createClient({ instance: existing.instanceUrl, token: existing.daemonToken }),
+          });
+          console.log(state === 'revoked'
+            ? "This computer's old key was revoked; registering it again."
+            : 'This computer is no longer registered; registering it again.');
+        }
+        const instanceUrl = resolveInstanceUrl(opts.instance);
+        const client = createClient({ instance: instanceUrl, token: requireUserToken(opts.instance || instanceUrl) });
+        const { machine, record } = await registerDaemonMachine({
+          client,
+          instanceUrl,
+          name: String(opts.name || hostname()).trim(),
+        });
+        clearDaemonStop();
+        console.log(`Registered ${machine.name}. Daemon credential stored securely.`);
+
+        try {
+          await heartbeatDaemonMachine({
+            client: createClient({ instance: record.instanceUrl, token: record.daemonToken }),
+            record,
+          });
+          console.log('Initial heartbeat accepted.');
+        } catch (error) {
+          console.error(`Machine is registered, but its initial heartbeat failed: ${error.message}`);
+          console.error(`Retry with: ${CLI} daemon heartbeat`);
+          process.exitCode = 1;
+        }
+        if (existing && existsSync(servicePaths(process.platform, homedir()).file)) {
+          console.log(`Restart the installed daemon to use the new key: ${CLI} daemon restart`);
+        }
+        // F458: register run by hand (the F454 walk) said nothing, and the
+        // agent looked healthy until its first message failed. Setup prints
+        // this itself, after the install step, so its own register doesn't.
+        if (!process.env[SETUP_CHILD_ENV]) {
+          for (const line of await signedOutNotes()) console.log(line);
+        }
+      } catch (error) {
+        console.error(`Daemon registration failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('unregister')
+    .description('Revoke this machine on the server and remove its local daemon credential')
+    .action(async () => {
+      try {
+        const record = requireDaemonRecord();
+        const client = createClient({
+          instance: record.instanceUrl,
+          token: requireUserToken(record.instanceUrl),
+        });
+        const { removedRemotely } = await unregisterDaemonMachine({
+          client,
+          daemonClient: createClient({ instance: record.instanceUrl, token: record.daemonToken }),
+          record,
+        });
+        console.log(removedRemotely
+          ? `Unregistered ${record.machineName} and removed its local daemon credential.`
+          : `Removed ${record.machineName}'s local daemon credential. Server access was already revoked or the machine was removed.`);
+      } catch (error) {
+        console.error(`Daemon unregister failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('heartbeat')
+    .description('Send a machine liveness heartbeat using the stored daemon credential')
+    .action(async () => {
+      try {
+        const record = requireDaemonRecord();
+        const response = await heartbeatDaemonMachine({
+          client: createClient({ instance: record.instanceUrl, token: record.daemonToken }),
+          record,
+        });
+        console.log(`Heartbeat accepted for ${response?.machine?.name || record.machineName}.`);
+      } catch (error) {
+        console.error(`Daemon heartbeat failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  // ── install / uninstall (ADR-026 D1) ──────────────────────────────────────
+  // The service manager's answer about the live daemon; rejects when it has none.
+  const readServiceCmd = (argv) => new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(argv[0], argv.slice(1), { stdio: ['ignore', 'pipe', 'ignore'] });
+    const chunks = [];
+    child.stdout.on('data', (chunk) => { chunks.push(chunk); });
+    child.on('error', rejectPromise);
+    child.on('close', (code) => (code === 0
+      ? resolvePromise(decodeCmdOutput(Buffer.concat(chunks)))
+      : rejectPromise(new Error(`${argv.join(' ')} exited ${code}`))));
+  });
+
+  const serviceDeps = () => ({
+    // writeFile is deliberately NOT injected here: daemon-service.js's default
+    // writer sets the 0600 mode at CREATION, and a bare `writeFileSync(file,
+    // content, 'utf8')` dropped that — leaving the service file, which can hold
+    // a provider key, readable at umask until the chmod a moment later.
+    mkdirp: (dir) => { if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); },
+    chmod: (path, mode) => chmodSync(path, mode),
+    ensureFile: (path) => { const fd = openSync(path, 'a', 0o600); closeSync(fd); },
+    existsFile: (file) => existsSync(file),
+    removeFile: (file) => rmSync(file),
+    readCmd: readServiceCmd,
+    execCmd: (argv) => new Promise((resolvePromise, rejectPromise) => {
+      const child = spawn(argv[0], argv.slice(1), { stdio: 'ignore' });
+      child.on('error', rejectPromise);
+      child.on('exit', (code) => (code === 0
+        ? resolvePromise()
+        : rejectPromise(new Error(`${argv.join(' ')} exited ${code}`))));
+    }),
+    log: (line) => console.log(line),
+  });
+
+  const runServiceAction = async (action, actionFn) => {
+    const deps = serviceDeps();
+    const target = servicePaths(process.platform, homedir());
+    if (!deps.existsFile(target.file)) {
+      throw new Error(`No installed daemon service found. Run: ${CLI} daemon install`);
+    }
+    await actionFn({ platform: process.platform, home: homedir(), execCmd: deps.execCmd });
+    console.log(`Daemon ${action} requested (${target.kind}).`);
+  };
+
+  daemon
+    .command('install')
+    .description('Register the daemon as a login service (launchd, systemd, or a Windows scheduled task); on Linux, also turn on lingering so it starts at boot')
+    .option(UNSANDBOXED_FLAG, 'Native Windows only: the agents this daemon runs have no sandbox, and run with your own access to files and commands. They get no connector grants. Codex can run commands in invite-only pods, where anyone in the pod, including people invited later, can direct it. Install again without it to turn it off.')
+    .option(REPLACE_FLAG, REPLACE_HELP)
+    .action(async (opts) => {
+      try {
+        if (opts.unsandboxed) {
+          const flagRefusal = unsandboxedFlagRefusal();
+          if (flagRefusal) throw new Error(flagRefusal);
+        }
+        // A service without a credential just crash-loops at boot.
+        requireDaemonRecord();
+        // D245: this command is the only writer of the opt-in, and installing
+        // without the flag is how it is turned off. Written before the task
+        // starts, so the first seats it spawns already read the answer.
+        // N3: the marker's state before this install, so a failed install can
+        // put it back rather than leave an opt-in with no daemon behind it.
+        const optedInBefore = loadUnsandboxedOptIn();
+        if (opts.unsandboxed) {
+          saveUnsandboxedOptIn();
+          console.log(`Agents this daemon runs will have no sandbox: they act with your own access to files and commands, and get no connector grants. Codex can run commands in invite-only pods, where anyone in the pod, people you invite later included, can direct it. To turn this off, run: ${CLI} daemon install`);
+        } else if (clearUnsandboxedOptIn()) {
+          console.log('Turned off running without a sandbox: on Windows, agents this daemon runs are refused again until you choose otherwise.');
+        }
+        // Same class one layer over (TASK-049): a service without the SEATS'
+        // provider key comes up clean, and every pi seat then dies inside its
+        // 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.
+        let installed;
+        try {
+          installed = await installDaemonService({
+            ...serviceDeps(),
+            replace: Boolean(opts.replace),
+            providerKeyEnvNames: providerKeyEnvNames(),
+            optionalEnvNames: [UPDATE_CHECK_OPT_OUT_ENV],
+          });
+        } catch (error) {
+          if (optedInBefore) saveUnsandboxedOptIn(); else clearUnsandboxedOptIn();
+          throw error;
+        }
+        console.log(installSummary(installed));
+      } catch (error) {
+        console.error(`Daemon install failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('uninstall')
+    .description('Remove the daemon login service (agents stop being supervised on this machine)')
+    .action(async () => {
+      try {
+        await uninstallDaemonService(serviceDeps());
+      } catch (error) {
+        console.error(`Daemon uninstall failed: ${error.message}`);
+        process.exitCode = 1;
+      } finally {
+        // N4: an uninstall that half-failed still turns the opt-in off; a
+        // later install has to ask for it again.
+        clearUnsandboxedOptIn();
+      }
+    });
+
+  daemon
+    .command('start')
+    .description('Start the installed daemon service and return to the terminal')
+    .action(async () => {
+      try {
+        await runServiceAction('start', startDaemonService);
+      } catch (error) {
+        console.error(`Daemon start failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('stop')
+    .description('Stop the installed daemon service')
+    .action(async () => {
+      try {
+        await runServiceAction('stop', stopDaemonService);
+      } catch (error) {
+        console.error(`Daemon stop failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('restart')
+    .description('Restart the installed daemon service and return to the terminal')
+    .action(async () => {
+      try {
+        await runServiceAction('restart', restartDaemonService);
+      } catch (error) {
+        console.error(`Daemon restart failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  // ── run (ADR-026 Phase 2, slice 2) ────────────────────────────────────────
+  daemon
+    .command('run')
+    .description('Run the resident supervisor: adopt requested agents, keep bound agents running, report per-agent state')
+    .option('--poll <ms>', 'Work-list poll interval in ms', String(DEFAULT_POLL_MS))
+    .option('--heartbeat <ms>', 'Heartbeat interval in ms', String(DEFAULT_HEARTBEAT_MS))
+    .option('--foreground', 'Keep the supervisor attached to this terminal (default for direct invocation)')
+    .option('--instance <url-or-key>', 'Confirm the instance this computer is registered with')
+    .action(async (opts) => {
+      let record;
+      try {
+        const terminal = loadDaemonStop();
+        if (terminal) {
+          console.error(`Daemon stopped: no valid local registration. Run: ${CLI} daemon register`);
+          process.exitCode = process.platform === 'darwin' ? 0 : terminal.exitCode;
+          return;
+        }
+        record = requireDaemonRecord();
+        const instanceRefusal = daemonRunInstanceRefusal(record, opts.instance);
+        if (instanceRefusal) {
+          console.error(instanceRefusal);
+          process.exitCode = 1;
+          return;
+        }
+        const stopped = loadDaemonStop(record);
+        if (stopped) {
+          console.error(`Daemon stopped: this computer's key was revoked. Run: ${CLI} daemon register`);
+          // launchd restarts the first nonzero terminal exit once; a saved
+          // verdict makes that second invocation successful and ends the loop.
+          process.exitCode = process.platform === 'darwin' ? 0 : stopped.exitCode;
+          return;
+        }
+        const client = createClient({ instance: record.instanceUrl, token: record.daemonToken });
+        const logsDir = daemonLogsDir();
+        if (!existsSync(logsDir)) mkdirSync(logsDir, { recursive: true });
+        chmodSync(logsDir, 0o700);
+        const stampLog = (line) => console.log(`${new Date().toISOString()} ${line}`);
+
+        // TASK-049: fail loudly, once, naming the variable.
+        //
+        // A service-started daemon inherits a clean environment, so a provider
+        // key that lives only in the operator's shell is absent here; a pi seat
+        // then dies at adapter start with `COMMONLY_LITELLM_KEY is not set` and
+        // the operator sees crash loops with no cause at daemon level. The
+        // warning names the seat that needs the key, when that seat starts:
+        // at daemon start it went to every BYO user, who needs none of them
+        // (Growth's F370 walk). Not fatal: the daemon's other seats are
+        // unaffected.
+        const warnedKeys = new Set();
+        const warnMissingSeatKey = (agentName) => {
+          let saved = null;
+          try { saved = loadAgentToken(agentName); } catch { return; }
+          const name = seatProviderKeyEnv({ adapter: saved?.adapter, environment: saved?.environment });
+          if (!name || process.env[name] || warnedKeys.has(`${agentName}:${name}`)) return;
+          warnedKeys.add(`${agentName}:${name}`);
+          stampLog(`WARNING: [${agentName}] needs ${name}, which is not set in this environment, so it will fail to start (a provider.keyFile avoids this); export it and re-run: ${CLI} 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;
+        let supervisor;
+        let terminalEnded = false;
+        const terminalAuth = (error) => isRevokedDaemonKey(error)
+          || isMissingDaemonMachine(error);
+        const onTerminalAuthError = () => {
+          terminalEnded = true;
+          let saved = false;
+          try {
+            saveDaemonStop(record, 77);
+            saved = true;
+          } catch (error) {
+            stampLog(`could not save revoked-machine stop marker: ${error.message}`);
+          }
+          stampLog(`machine key revoked; stopping supervised agents. Run: ${CLI} daemon register`);
+          clearInterval(pollTimer);
+          clearInterval(heartbeatTimer);
+          supervisor.stop();
+          // Without the marker launchd would restart forever. A successful
+          // exit parks it on macOS; systemd honors 77 directly.
+          process.exitCode = saved || process.platform !== 'darwin' ? 77 : 0;
+        };
+        const runtimeInventory = createInventoryCache((harnesses) => collectRuntimeInventory(getAdapter, undefined, harnesses, { loginState }));
+        supervisor = createDaemonSupervisor({
+          record,
+          client,
+          isTerminalAuthError: terminalAuth,
+          onTerminalAuthError,
+          // One child per agent, logging to its own file. The child is the
+          // ordinary `commonly agent run <name>` — the daemon is its
+          // supervisor, never its replacement (D6).
+          // `recordKey` is the local record: `<name>`, or `<name>@<id>` for
+          // another instance, which `agent run` resolves the same way (F427).
+          spawnChild: (recordKey) => {
+            warnMissingSeatKey(recordKey);
+            const seatLog = daemonSeatLogPath(recordKey);
+            const out = openSync(seatLog, 'a', 0o600);
+            chmodSync(seatLog, 0o600);
+            return spawn(process.execPath, [process.argv[1], 'agent', 'run', recordKey], {
+              stdio: ['ignore', out, out],
+              // Windows: never flash a console window per seat (no-op elsewhere).
+              windowsHide: true,
+              env: { ...process.env, COMMONLY_MANAGED_RUNNER: '1' },
+            });
+          },
+          loadToken: loadAgentToken,
+          saveToken: saveAgentToken,
+          machineReport: daemonMachineReport,
+          runtimeInventory,
+          resolveAdapter: (runtime) => resolveAdapterForRuntime(runtime),
+          log: stampLog,
+          persistState: (seats) => saveDaemonState({
+            machineName: record.machineName,
+            machineDbId: record.machineDbId,
+            updatedAt: new Date().toISOString(),
+            seats: seats.map((seat) => ({
+              ...seat,
+              lastTurnAt: getLastTurn(seat.recordKey || seat.agentName) || seat.lastTurnAt,
+            })),
+          }),
+        });
+
+        stampLog(`daemon supervising for ${record.machineName} — poll ${opts.poll}ms, heartbeat ${opts.heartbeat}ms (ctrl+c to stop)`);
+        const shutdown = () => {
+          stampLog('daemon stopping — terminating supervised agents');
+          clearInterval(pollTimer);
+          clearInterval(heartbeatTimer);
+          supervisor.stop();
+          process.exit(0);
+        };
+        // D245: under the Windows launcher, the launcher's exit is the stop
+        // signal. Armed before the first tick, so the EPIPE guard covers its
+        // log lines and a launcher already gone stops the daemon at once.
+        const started = await firstSupervisionPass({
+          supervisor,
+          onLauncherGone: (pid) => {
+            // stdout and stderr already swallow EPIPE (armed with the watch).
+            try { stampLog(`launcher ${pid} has exited`); } catch { /* stdout is gone */ }
+            shutdown();
+          },
+          isEnded: () => terminalEnded,
+        });
+        if (!started) return;
+        const runtimeFailure = (error) => {
+          if (terminalEnded) return;
+          terminalEnded = true;
+          stampLog(`daemon runtime failed: ${error.message}`);
+          clearInterval(pollTimer);
+          clearInterval(heartbeatTimer);
+          supervisor.stop();
+          process.exitCode = 75;
+        };
+        pollTimer = setInterval(() => { void supervisor.tick().catch(runtimeFailure); }, Number(opts.poll) || DEFAULT_POLL_MS);
+        heartbeatTimer = setInterval(() => { void supervisor.heartbeat().catch(runtimeFailure); }, Number(opts.heartbeat) || DEFAULT_HEARTBEAT_MS);
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+      } catch (error) {
+        console.error(`Daemon run failed: ${error.message}`);
+        const badConfig = !record || error.message.startsWith('Daemon credential file');
+        if (badConfig) {
+          try {
+            saveDaemonStop(record || { machineDbId: 'unregistered' }, 78);
+          } catch (markerError) {
+            console.error(`Could not save daemon stop marker: ${markerError.message}`);
+            if (process.platform === 'darwin') {
+              process.exitCode = 0;
+              return;
+            }
+          }
+        }
+        process.exitCode = badConfig ? 78 : 75;
+      }
+    });
+
+  daemon
+    .command('status')
+    .description('Show the server-derived liveness of this machine')
+    .option('--verbose', 'Include locally supervised seat state and process details')
+    .option('--watch', 'Redraw the machine and agent view every 2 s until Ctrl-C')
+    .action(async (opts) => {
+      if (opts.watch) {
+        await watchDaemonStatus();
+        return;
+      }
+      try {
+        const record = requireDaemonRecord();
+        const machine = await getDaemonMachineStatus({
+          client: createClient({ instance: record.instanceUrl, token: record.daemonToken }),
+          record,
+        });
+        const lastSeen = machine.lastSeenAt ? new Date(machine.lastSeenAt).toLocaleString() : 'never';
+        console.log(`${machine.name}: ${machine.status} (last heartbeat: ${lastSeen})`);
+        if (loadUnsandboxedOptIn()) console.log(`Sandbox: unsandboxed (opted in). Agents run with your own access and get no connector grants, and anyone in an invite-only pod can direct a Codex agent there. Turn off: ${CLI} daemon install`);
+        if (opts.verbose) {
+          const local = loadDaemonState();
+          if (!local) {
+            console.log('Local supervisor state: unavailable (daemon has not written state yet).');
+          } else if (!local.seats.length) {
+            console.log('Local supervisor state: no supervised seats.');
+          } else {
+            console.log('Local supervised seats:');
+            for (const seat of local.seats) console.log(formatSeatLine(seat));
+          }
+        }
+      } catch (error) {
+        console.error(daemonStatusErrorMessage(error));
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('logs')
+    .description('Show daemon or per-seat logs')
+    .option('--seat <name>', 'Show one supervised seat log instead of the daemon log')
+    .option('-f, --follow', 'Continue printing appended log output')
+    .option('--lines <n>', 'Number of trailing lines to show', '50')
+    .action(async (opts) => {
+      const path = opts.seat ? daemonSeatLogPath(opts.seat) : daemonLogPath();
+      const printTail = () => {
+        const output = readLogTail(path, opts.lines);
+        if (output === null) {
+          console.error(`No log found at ${path}`);
+          return false;
+        }
+        if (output) console.log(output);
+        return true;
+      };
+      if (!printTail() || !opts.follow) return;
+      const watcher = watch(path, () => printTail());
+      const close = () => {
+        watcher.close();
+        process.exit(0);
+      };
+      process.once('SIGINT', close);
+      process.once('SIGTERM', close);
+    });
+};