@commonlyai/cli 0.1.41 → 0.1.42

package/package.json

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

package/src/commands/agent.js

@@ -2474,6 +2474,7 @@ Docs:
       // back on 2026-08-18, and that only worked because the processes were
       // still alive — after the next restart that route is gone too.
       console.log(`${stamp()} [${name}] polling ${record.instanceUrl} for events (ctrl+c to stop)`);
+      console.log(`${stamp()} [${name}] foreground mode; to background and keep it across logins, run: commonly daemon install`);
 
       const { stop } = performRun({
         instanceUrl: record.instanceUrl,

package/src/commands/daemon.js

@@ -9,9 +9,8 @@
 import { hostname, homedir } from 'os';
 import { spawn } from 'child_process';
 import {
-  existsSync, mkdirSync, openSync, rmSync, writeFileSync,
+  chmodSync, closeSync, existsSync, mkdirSync, openSync, rmSync, watch, writeFileSync,
 } from 'fs';
-import { join } from 'path';
 import { createClient } from '../lib/api.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
 import { loadDaemonRecord, removeDaemonRecord, saveDaemonRecord } from '../lib/daemon-store.js';
@@ -21,11 +20,19 @@ import {
   DEFAULT_POLL_MS,
 } from '../lib/daemon-supervisor.js';
 import { loadAgentToken, saveAgentToken } from './agent.js';
+import { getLastTurn } from '../lib/session-store.js';
 import { getAdapter } from '../lib/adapters/index.js';
 import {
   installDaemonService,
   uninstallDaemonService,
+  startDaemonService,
+  stopDaemonService,
+  restartDaemonService,
+  daemonLogPath,
+  servicePaths,
 } from '../lib/daemon-service.js';
+import { daemonLogsDir, daemonSeatLogPath, readLogTail } from '../lib/daemon-logs.js';
+import { loadDaemonState, saveDaemonState } from '../lib/daemon-state.js';
 
 const requireDaemonRecord = () => {
   const record = loadDaemonRecord();
@@ -132,7 +139,9 @@ The daemon token is scoped to this machine and stored in a 0600 file under
 Examples:
   $ commonly daemon register --name "Sam's MacBook"
   $ commonly daemon heartbeat
-  $ commonly daemon status
+  $ commonly daemon status --verbose
+  $ commonly daemon logs --seat my-agent -f
+  $ commonly daemon start|stop|restart
   $ commonly daemon unregister
 `);
 
@@ -212,6 +221,8 @@ Examples:
   const serviceDeps = () => ({
     writeFile: (file, content) => writeFileSync(file, content, 'utf8'),
     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),
     execCmd: (argv) => new Promise((resolvePromise, rejectPromise) => {
@@ -224,6 +235,16 @@ Examples:
     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: commonly 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) so it survives reboots')
@@ -251,18 +272,56 @@ Examples:
       }
     });
 
+  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)')
     .action(async (opts) => {
       try {
         const record = requireDaemonRecord();
         const client = createClient({ instance: record.instanceUrl, token: record.daemonToken });
-        const logsDir = join(homedir(), '.commonly', 'logs', 'daemon');
+        const logsDir = daemonLogsDir();
         if (!existsSync(logsDir)) mkdirSync(logsDir, { recursive: true });
+        chmodSync(logsDir, 0o700);
         const stampLog = (line) => console.log(`${new Date().toISOString()} ${line}`);
 
         const supervisor = createDaemonSupervisor({
@@ -272,7 +331,9 @@ Examples:
           // ordinary `commonly agent run <name>` — the daemon is its
           // supervisor, never its replacement (D6).
           spawnChild: (agentName) => {
-            const out = openSync(join(logsDir, `${agentName}.log`), 'a');
+            const seatLog = daemonSeatLogPath(agentName);
+            const out = openSync(seatLog, 'a', 0o600);
+            chmodSync(seatLog, 0o600);
             return spawn(process.execPath, [process.argv[1], 'agent', 'run', agentName], {
               stdio: ['ignore', out, out],
             });
@@ -281,6 +342,15 @@ Examples:
           saveToken: saveAgentToken,
           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.agentName) || seat.lastTurnAt,
+            })),
+          }),
         });
 
         stampLog(`daemon supervising for ${record.machineName} — poll ${opts.poll}ms, heartbeat ${opts.heartbeat}ms (ctrl+c to stop)`);
@@ -306,7 +376,8 @@ Examples:
   daemon
     .command('status')
     .description('Show the server-derived liveness of this machine')
-    .action(async () => {
+    .option('--verbose', 'Include locally supervised seat state and process details')
+    .action(async (opts) => {
       try {
         const record = requireDaemonRecord();
         const machine = await getDaemonMachineStatus({
@@ -318,9 +389,52 @@ Examples:
         }
         const lastSeen = machine.lastSeenAt ? new Date(machine.lastSeenAt).toLocaleString() : 'never';
         console.log(`${machine.name}: ${machine.status} (last heartbeat: ${lastSeen})`);
+        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) {
+              const model = seat.model || 'default model';
+              const effort = seat.effort ? `/${seat.effort}` : '';
+              const error = seat.lastError ? ` error=${seat.lastError}` : '';
+              console.log(`  ${seat.agentName}: ${seat.state} adapter=${seat.adapter || 'unknown'} model=${model}${effort} pid=${seat.pid || '-'} lastTurn=${seat.lastTurnAt || 'never'}${error}`);
+            }
+          }
+        }
       } catch (error) {
         console.error(`Daemon status failed: ${error.message}`);
         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);
+    });
 };

package/src/lib/daemon-logs.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const daemonLogsDir = (home = homedir()) => join(home, '.commonly', 'logs', 'daemon');
+export const daemonSeatLogPath = (agentName, home = homedir()) => {
+  const safeName = String(agentName || 'unknown').replace(/[^A-Za-z0-9._-]/g, '_');
+  return join(daemonLogsDir(home), `${safeName}.log`);
+};
+
+export const tailLines = (text, count = 50) => {
+  const lines = String(text).split(/\r?\n/);
+  // A trailing newline is a separator, not an empty log line.
+  if (lines.at(-1) === '') lines.pop();
+  return lines.slice(-Math.max(0, Number(count) || 0)).join('\n');
+};
+
+export const readLogTail = (path, count = 50) => {
+  try {
+    return tailLines(readFileSync(path, 'utf8'), count);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+};

package/src/lib/daemon-service.js

@@ -55,6 +55,7 @@ export const launchdPlist = ({ nodePath, cliPath, home = homedir() }) => `<?xml
 \t\t<string>${xmlEscape(cliPath)}</string>
 \t\t<string>daemon</string>
 \t\t<string>run</string>
+\t\t<string>--foreground</string>
 \t</array>
 \t<key>RunAtLoad</key>
 \t<true/>
@@ -73,7 +74,7 @@ Description=Commonly local agent daemon (ADR-026)
 After=network-online.target
 
 [Service]
-ExecStart=${nodePath} ${cliPath} daemon run
+ExecStart=${nodePath} ${cliPath} daemon run --foreground
 Restart=always
 RestartSec=5
 Environment=PATH=${childPath(nodePath)}
@@ -90,11 +91,18 @@ export const installDaemonService = async ({
   writeFile,
   mkdirp,
   execCmd, // async (argv: string[]) => void — throws on failure
+  chmod = () => {},
+  ensureFile,
   log = () => {},
 }) => {
   const target = servicePaths(platform, home);
   mkdirp(dirname(target.file));
   mkdirp(dirname(daemonLogPath(home)));
+  chmod(dirname(daemonLogPath(home)), 0o700);
+  if (ensureFile) {
+    ensureFile(daemonLogPath(home));
+    chmod(daemonLogPath(home), 0o600);
+  }
 
   if (target.kind === 'launchd') {
     writeFile(target.file, launchdPlist({ nodePath, cliPath, home }));
@@ -133,3 +141,33 @@ export const uninstallDaemonService = async ({
   log(`Removed ${target.kind} service (${target.file}).`);
   return target;
 };
+
+const serviceAction = async ({
+  action,
+  platform = process.platform,
+  home = homedir(),
+  execCmd,
+}) => {
+  const target = servicePaths(platform, home);
+  if (target.kind === 'launchd') {
+    if (action === 'start') {
+      // `install` already loads the plist. A second `start` should be
+      // idempotent rather than failing with "already loaded".
+      await execCmd(['launchctl', 'load', '-w', target.file]).catch(async () => {
+        await execCmd(['launchctl', 'start', LAUNCHD_LABEL]);
+      });
+    }
+    else if (action === 'stop') await execCmd(['launchctl', 'unload', '-w', target.file]);
+    else {
+      await execCmd(['launchctl', 'unload', '-w', target.file]).catch(() => {});
+      await execCmd(['launchctl', 'load', '-w', target.file]);
+    }
+  } else {
+    await execCmd(['systemctl', '--user', action, SYSTEMD_UNIT]);
+  }
+  return target;
+};
+
+export const startDaemonService = (options) => serviceAction({ ...options, action: 'start' });
+export const stopDaemonService = (options) => serviceAction({ ...options, action: 'stop' });
+export const restartDaemonService = (options) => serviceAction({ ...options, action: 'restart' });

package/src/lib/daemon-state.js

@@ -0,0 +1,81 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// The state file is deliberately next to the daemon credential, but it never
+// contains one. Keeping both under the already-private daemon directory makes
+// it difficult for a future status field to accidentally become world-readable.
+export const daemonStateDir = (home = homedir()) => join(home, '.commonly', 'daemon');
+export const daemonStatePath = (home = homedir()) => join(daemonStateDir(home), 'state.json');
+
+const fixedLastError = (value) => {
+  if (!value) return null;
+  const match = typeof value === 'string'
+    ? value.match(/^child exited with code (-?\d+|null)$/)
+    : null;
+  return match ? `child exited with code ${match[1]}` : 'child process error';
+};
+
+const seatState = (seat = {}) => ({
+  agentName: seat.agentName,
+  instanceId: seat.instanceId,
+  state: seat.state,
+  restarts: seat.restarts,
+  adapter: seat.adapter || null,
+  model: seat.model || null,
+  effort: seat.effort || null,
+  pid: Number.isInteger(seat.pid) ? seat.pid : null,
+  lastTurnAt: seat.lastTurnAt || null,
+  lastError: fixedLastError(seat.lastError),
+});
+
+// Pick fields rather than serializing arbitrary supervisor objects. This is a
+// security boundary: no token, environment, or child-process metadata can be
+// persisted merely because a future caller adds it to a runtime row.
+export const publicDaemonState = (state = {}) => ({
+  machineName: state.machineName || null,
+  machineDbId: state.machineDbId || null,
+  updatedAt: state.updatedAt || new Date().toISOString(),
+  seats: Array.isArray(state.seats) ? state.seats.map(seatState) : [],
+});
+
+export const saveDaemonState = (state, { home = homedir() } = {}) => {
+  const dir = daemonStateDir(home);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const path = daemonStatePath(home);
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(publicDaemonState(state), null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
+  chmodSync(temp, 0o600);
+  renameSync(temp, path);
+  chmodSync(path, 0o600);
+  return path;
+};
+
+export const loadDaemonState = ({ home = homedir() } = {}) => {
+  try {
+    const parsed = JSON.parse(readFileSync(daemonStatePath(home), 'utf8'));
+    return publicDaemonState(parsed);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw new Error(`Could not read daemon state: ${error.message}`);
+  }
+};
+
+export const removeDaemonState = ({ home = homedir() } = {}) => {
+  try {
+    unlinkSync(daemonStatePath(home));
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+};

package/src/lib/daemon-supervisor.js

@@ -49,6 +49,7 @@ export const createDaemonSupervisor = ({
   loadToken, // (agentName) => token record | null
   saveToken, // (agentName, record) => void
   resolveAdapter, // async (runtime) => adapter name for THIS machine
+  persistState = () => {}, // (agentStates) => void; must not persist secrets
   log = () => {},
   setTimeoutFn = setTimeout,
   clearTimeoutFn = clearTimeout,
@@ -57,25 +58,48 @@ export const createDaemonSupervisor = ({
   const seats = new Map();
   let stopped = false;
 
+  const persist = () => {
+    try {
+      persistState(agentStates());
+    } catch (error) {
+      // A diagnostic state file must never take the daemon down. The log is
+      // still useful, and the next state transition retries the write.
+      log(`could not persist local daemon state: ${error.message}`);
+    }
+  };
+
   const agentStates = () => Array.from(seats.values()).map((s) => ({
     agentName: s.agentName,
     instanceId: s.instanceId,
     state: s.state,
     restarts: s.restarts,
+    adapter: s.adapter || null,
+    model: s.model || null,
+    effort: s.effort || null,
+    pid: Number.isInteger(s.pid) ? s.pid : null,
+    lastTurnAt: s.lastTurnAt || null,
+    lastError: s.lastError || null,
   }));
 
   const startChild = (seat) => {
     if (stopped || !seat.desired || seat.child) return;
     seat.child = spawnChild(seat.agentName);
     seat.state = 'running';
+    seat.pid = Number.isInteger(seat.child?.pid) ? seat.child.pid : null;
+    seat.lastTurnAt = new Date().toISOString();
+    seat.lastError = null;
+    persist();
     log(`[${seat.agentName}] supervising (restarts so far: ${seat.restarts})`);
     seat.child.on('exit', (code) => {
       seat.child = null;
+      seat.pid = null;
       if (stopped || !seat.desired) {
         seat.state = 'stopped';
+        persist();
         return;
       }
       seat.state = code === 0 ? 'stopped' : 'crashed';
+      seat.lastError = code === 0 ? null : `child exited with code ${code}`;
       seat.restarts += 1;
       const delay = backoffMs(seat.restarts - 1);
       log(`[${seat.agentName}] exited (code ${code}) — respawn in ${Math.round(delay / 1000)}s`);
@@ -83,6 +107,7 @@ export const createDaemonSupervisor = ({
         seat.backoffTimer = null;
         startChild(seat);
       }, delay);
+      persist();
     });
   };
 
@@ -97,6 +122,8 @@ export const createDaemonSupervisor = ({
       seat.child.kill('SIGTERM');
     } else {
       seat.state = 'stopped';
+      seat.pid = null;
+      persist();
     }
   };
 
@@ -280,10 +307,20 @@ export const createDaemonSupervisor = ({
           restarts: 0,
           backoffTimer: null,
           desired: true,
+          adapter: null,
+          model: null,
+          effort: null,
+          pid: null,
+          lastTurnAt: null,
+          lastError: null,
         };
         seats.set(key, seat);
       }
       seat.desired = true;
+      const localToken = loadToken(row.agentName);
+      seat.adapter = row.runtime?.adapter || localToken?.adapter || seat.adapter || null;
+      seat.model = row.runtime?.model || localToken?.environment?.model || seat.model || null;
+      seat.effort = row.runtime?.effort || localToken?.environment?.effort || seat.effort || null;
       // eslint-disable-next-line no-await-in-loop
       const ready = await ensureToken(row);
       if (ready === 'changed' && seat.child) {
@@ -293,11 +330,13 @@ export const createDaemonSupervisor = ({
       } else if (ready && !seat.child && !seat.backoffTimer) {
         startChild(seat);
       }
+      persist();
     }
 
     for (const [key, seat] of seats) {
       if (!desiredKeys.has(key) && seat.desired) stopSeat(seat);
     }
+    persist();
   };
 
   const heartbeat = async () => {
@@ -311,7 +350,12 @@ export const createDaemonSupervisor = ({
 
   const stop = () => {
     stopped = true;
-    for (const seat of seats.values()) stopSeat(seat);
+    for (const seat of seats.values()) {
+      stopSeat(seat);
+      seat.state = 'stopped';
+      seat.pid = null;
+    }
+    persist();
   };
 
   return {

package/src/lib/session-store.js

@@ -87,6 +87,18 @@ export const getSession = (agentName, podId) => {
   return readAgent(agentName)[podId]?.sessionId || null;
 };
 
+// Read-only diagnostic projection used by the daemon operator surface. A
+// wrapper may serve several pods, so return the newest completed turn.
+export const getLastTurn = (agentName) => {
+  if (!agentName) return null;
+  const state = readAgent(agentName);
+  return Object.values(state)
+    .map((entry) => entry?.lastTurn)
+    .filter((value) => typeof value === 'string')
+    .sort()
+    .at(-1) || null;
+};
+
 export const setSession = (agentName, podId, sessionId) => {
   if (!agentName || !podId) return;
   const state = readAgent(agentName);