@commonlyai/cli 0.1.223 → 0.1.224

package/node_modules/@commonlyai/seats/src/process-group.js

@@ -82,7 +82,9 @@ export const leadsOwnGroup = (child) => !!child
 
 // ── The process table ──────────────────────────────────────────────────────
 
-const PS_ENV = { ...process.env, LC_ALL: 'C' };
+// lstart is printed in local time with no offset, which repeats an hour when
+// daylight saving ends. In UTC it never repeats; `startedMs` reads it as UTC.
+const PS_ENV = { ...process.env, LC_ALL: 'C', TZ: 'UTC' };
 
 const parseTable = (text) => {
   const rows = [];
@@ -100,6 +102,9 @@ const ps = (args) => {
   } catch { return null; }
 };
 
+/** A row's `started` as epoch ms. */
+export const startedMs = (started) => Date.parse(`${started} GMT`);
+
 /** Every process: { pid, ppid, started }. null when ps is unavailable. */
 export const readProcessTable = () => ps(['-A', '-o', 'pid=,ppid=,lstart=']);
 
@@ -107,6 +112,9 @@ export const readProcessTable = () => ps(['-A', '-o', 'pid=,ppid=,lstart=']);
 export const readProcess = (pid) => (ps(['-o', 'pid=,ppid=,lstart=', '-p', String(pid)]) || [])
   .find((row) => row.pid === pid) || null;
 
+/** Several processes as they are now, in one ps call; a gone pid has no row. null when ps is unavailable. */
+export const readProcesses = (pids) => (pids.length ? ps(['-o', 'pid=,ppid=,lstart=', '-p', pids.join(',')]) : []);
+
 /** The descendants of `root` in `table`, deepest first. The root is not included. */
 export const descendantsOf = (table, root) => {
   const byParent = new Map();

package/node_modules/@commonlyai/seats/src/turn-processes.js

@@ -0,0 +1,199 @@
+/**
+ * Processes a turn leaves running.
+ *
+ * A turn can start work that outlives it. A dev server backgrounded from a
+ * shell tool (`npm exec vite &`) is orphaned the moment that shell exits and
+ * is reparented to launchd, where no group kill or descendant walk from the
+ * turn's child can reach it. Six such trees, one to four days old, took the
+ * fleet host's swap to 12 GB (SRE, 2026-11-01).
+ *
+ * So a turn's child is started with a fresh marker in its environment, which
+ * every process it starts inherits however it detaches. When the child has
+ * closed, the processes still carrying the marker are stopped: SIGTERM, then
+ * SIGKILL after a grace for any still alive. That includes a lasting server
+ * the turn started on first use, such as tmux, and a seat it restarted. A
+ * process started with COMMONLY_KEEP_PROCESS=1 is left running, and so is
+ * anything it starts, even one that clears the setting; the turn's child itself
+ * never inherits it. COMMONLY_TURN_REAP=0 turns the whole check off.
+ *
+ * Only processes started since the turn began are read, and each one's
+ * environment is only compared against the marker and the keep setting. Each
+ * pid is re-read just before it is signalled, and is signalled only while its
+ * start time is still the one recorded, so a reused pid is left alone.
+ *
+ * What it does not catch: on macOS `ps -E` cannot read the environment of an
+ * Apple platform binary (sh, bash, sleep), so one of those is stopped only as
+ * a descendant of a marked process. A process that clears its environment
+ * loses the marker. Both are left running. The same unreadable environment
+ * hides a keep setting: a kept Apple binary is not seen as kept, so a process
+ * it starts is kept only if that process keeps the setting itself.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import {
+  PROCESS_GROUPS_SUPPORTED, readProcesses, readProcessTable, startedMs,
+} from './process-group.js';
+
+export const TURN_MARK_ENV = 'COMMONLY_TURN_ID';
+export const KEEP_PROCESS_ENV = 'COMMONLY_KEEP_PROCESS';
+export const TURN_REAP_ENV = 'COMMONLY_TURN_REAP';
+export const TURN_REAP_GRACE_MS = 5_000;
+// How far before the turn a process's recorded start may read and still be
+// looked at. lstart has one-second resolution, and on Linux ps derives it from
+// the boot time, which drifts from the wall clock by a second or more. The
+// window only bounds what is read; the marker decides.
+export const TURN_START_SLACK_MS = 60_000;
+
+export const turnReapEnabled = (env = process.env) => PROCESS_GROUPS_SUPPORTED && env?.[TURN_REAP_ENV] !== '0';
+
+const PS_ENV = { ...process.env, LC_ALL: 'C' };
+
+// pid -> the set of tokens its environment reads as. A pid whose environment
+// could not be read has no entry, or a set without NAME=value pairs.
+const readEnvironmentsDarwin = (pids) => {
+  const out = new Map();
+  const res = spawnSync('ps', ['-E', '-ww', '-o', 'pid=,command=', '-p', pids.join(',')], {
+    encoding: 'utf8', env: PS_ENV, timeout: 5000, maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.error) return out;
+  for (const line of String(res.stdout || '').split('\n')) {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (match) out.set(Number(match[1]), new Set(match[2].split(/\s+/)));
+  }
+  return out;
+};
+
+const readEnvironmentsLinux = (pids) => {
+  const out = new Map();
+  for (const pid of pids) {
+    try {
+      out.set(pid, new Set(readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0')));
+    } catch { /* gone, or not readable */ }
+  }
+  return out;
+};
+
+export const readEnvironments = (pids) => {
+  if (!pids.length || !PROCESS_GROUPS_SUPPORTED) return new Map();
+  return process.platform === 'linux' ? readEnvironmentsLinux(pids) : readEnvironmentsDarwin(pids);
+};
+
+const selfAndAncestors = (table, pid) => {
+  const byPid = new Map(table.map((row) => [row.pid, row]));
+  const out = new Set([pid]);
+  for (let row = byPid.get(pid); row && row.ppid > 0 && !out.has(row.ppid); row = byPid.get(row.ppid)) {
+    out.add(row.ppid);
+  }
+  return out;
+};
+
+/**
+ * The processes still carrying `mark`, as { pid, ppid, started }: started at
+ * or after `since` (ms), neither this process nor an ancestor of it, and
+ * neither kept nor under a kept one. Each one brings its descendants, except a
+ * kept one and everything
+ * under it, whose environments may be unreadable. The start-time window only
+ * limits what is read; the marker is what decides. `io` is a test seam
+ * ({ table, envs, self }).
+ */
+export const findTurnProcesses = (mark, since, io = {}) => {
+  const { table = readProcessTable, envs = readEnvironments, self = process.pid } = io;
+  if (!mark) return [];
+  const rows = table();
+  if (!rows) return [];
+  const skip = selfAndAncestors(rows, self);
+  const floor = Number(since) - TURN_START_SLACK_MS;
+  const recent = rows.filter((row) => !skip.has(row.pid) && startedMs(row.started) >= floor);
+  const environments = envs(recent.map((row) => row.pid));
+  const marked = `${TURN_MARK_ENV}=${mark}`;
+  const keep = `${KEEP_PROCESS_ENV}=1`;
+  const kept = (pid) => environments.get(pid)?.has(keep) === true;
+  const byPid = new Map(rows.map((row) => [row.pid, row]));
+  // A kept process keeps what it starts even when that drops the setting.
+  const underKept = (row) => {
+    for (let up = byPid.get(row.ppid), seen = new Set(); up && !seen.has(up.pid); up = byPid.get(up.ppid)) {
+      if (kept(up.pid)) return true;
+      seen.add(up.pid);
+    }
+    return false;
+  };
+  const found = new Map();
+  for (const row of recent) {
+    if (environments.get(row.pid)?.has(marked) && !kept(row.pid) && !underKept(row)) found.set(row.pid, row);
+  }
+  const byParent = new Map();
+  for (const row of rows) {
+    if (row.pid === row.ppid) continue;
+    if (!byParent.has(row.ppid)) byParent.set(row.ppid, []);
+    byParent.get(row.ppid).push(row);
+  }
+  for (const stack = [...found.keys()]; stack.length;) {
+    for (const child of byParent.get(stack.pop()) || []) {
+      if (found.has(child.pid) || skip.has(child.pid) || kept(child.pid)) continue;
+      found.set(child.pid, child);
+      stack.push(child.pid);
+    }
+  }
+  return [...found.values()];
+};
+
+/**
+ * Stop what `findTurnProcesses` returns. SIGTERM is sent before this returns;
+ * `done` settles after `graceMs`, once anything still alive has had SIGKILL.
+ * A pid is signalled only while its start time is the one recorded, read for
+ * all of them in one ps call per signal. The grace timer holds the process
+ * open until SIGKILL has gone out, so a seat stopped mid-turn still escalates.
+ * `io` adds `read` (pids -> rows) to the find seam.
+ */
+export const reapTurnProcesses = (mark, since, { graceMs = TURN_REAP_GRACE_MS, io = {} } = {}) => {
+  const read = io.read || readProcesses;
+  const signal = (rows, name) => {
+    const now = new Map((read(rows.map((row) => row.pid)) || []).map((row) => [row.pid, row]));
+    return rows.filter((row) => {
+      if (now.get(row.pid)?.started !== row.started) return false;
+      try { process.kill(row.pid, name); return true; } catch { return false; }
+    });
+  };
+  const termed = signal(findTurnProcesses(mark, since, io), 'SIGTERM');
+  const done = termed.length === 0
+    ? Promise.resolve({ killed: [] })
+    : new Promise((resolve) => {
+      setTimeout(() => resolve({ killed: signal(termed, 'SIGKILL').map((row) => row.pid) }), graceMs);
+    });
+  return { termed: termed.map((row) => row.pid), done };
+};
+
+/**
+ * One turn's marker. `env` is the child's environment with the marker added;
+ * `reap(child)` runs once the child has closed, and returns what
+ * `reapTurnProcesses` does, or null when the check is off, the child never had
+ * a pid, or the turn was already reaped.
+ */
+export const markTurn = (env, { enabled = turnReapEnabled(), now = Date.now, graceMs } = {}) => {
+  if (!enabled) return { env, mark: null, reap: () => null };
+  const mark = randomUUID();
+  const since = now();
+  // A keep setting the seat itself was started with would keep every turn.
+  const childEnv = { ...env, [TURN_MARK_ENV]: mark };
+  delete childEnv[KEEP_PROCESS_ENV];
+  let reaped = false;
+  return {
+    env: childEnv,
+    mark,
+    reap: (child, { io } = {}) => {
+      if (reaped || !Number.isInteger(child?.pid) || child.pid <= 0) return null;
+      reaped = true;
+      try { return reapTurnProcesses(mark, since, { graceMs, io }); } catch { return null; }
+    },
+  };
+};
+
+/** The log line for a reap that stopped something, or null. */
+export const describeTurnReap = (result) => {
+  if (!result?.termed?.length) return null;
+  const n = result.termed.length;
+  return `stopped ${n} process${n === 1 ? '' : 'es'} this turn left running (pid ${result.termed.join(', ')}); `
+    + `start one with ${KEEP_PROCESS_ENV}=1 to keep it across turns`;
+};

package/package.json

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

package/src/lib/adapters/claude.js

@@ -6,6 +6,7 @@ import {
 import {
   descendantsOf, killProcessTree, readProcessTable, spawnInOwnGroup, wantsOwnProcessGroup,
 } from '@commonlyai/seats/process-group';
+import { describeTurnReap, markTurn, turnReapEnabled } from '@commonlyai/seats/turn-processes';
 /**
  * claude adapter — wraps the local `claude` CLI as a Commonly agent.
  *
@@ -92,7 +93,7 @@ import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credent
 import {
   prepareMcpSpawn, PUBLIC_MCP_UNAVAILABLE_CODE, publicMcpUnavailableError, selectedMcpVersionDir,
 } from '../mcp-home.js';
-import { buildMemoryPreamble, ROW_SLICING_CUE } from '../memory-bridge.js';
+import { BACKGROUND_PROCESS_CUE, buildMemoryPreamble, ROW_SLICING_CUE } from '../memory-bridge.js';
 import { claudeConfigDirFor, claudeContextTokens, claudeTranscriptPath } from '../session-recycle.js';
 import { skillsAsText } from '../skill-prompt.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
@@ -115,13 +116,14 @@ const buildPrompt = buildMemoryPreamble;
 
 // The working habits a private claude seat is taught on a fresh session
 // (TASK-545). Parallel reads live here because only this CLI has a subagent
-// tool; codex is passed row slicing alone. A public seat is passed neither: its
-// argv allows Read and the MCP under dontAsk, so it has no subagent to spawn,
-// and it answers strangers rather than working board rows.
+// tool; codex is passed row slicing and the background-process cue. A public
+// seat is passed none: its argv allows Read and the MCP under dontAsk, so it
+// has no subagent to spawn or shell to background from, and it answers
+// strangers rather than working board rows.
 const PARALLEL_READS_CUE = 'Parallel reads: when a row needs several files or sources read, '
   + 'use the Agent tool. Spawn read-only subagents in parallel, brief each one with the files '
   + 'to read and the question to answer, and keep only their conclusions.';
-const WORK_CUES = [PARALLEL_READS_CUE, ROW_SLICING_CUE];
+const WORK_CUES = [PARALLEL_READS_CUE, ROW_SLICING_CUE, BACKGROUND_PROCESS_CUE];
 const RUNTIME_CREDENTIAL_PLACEHOLDER = '${COMMONLY_AGENT_TOKEN}';
 
 const QUOTE_SHELL_ARGUMENT = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
@@ -635,11 +637,14 @@ export const claudeFailureTail = (stdout) => {
 const runClaude = ({
   cmd, args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {}, ownGroup = false,
   transcriptPath = null, firstOutputMs = firstOutputWindowMs(), lockProbe, stallKillGraceMs = STALL_KILL_GRACE_MS,
-  processTable = readProcessTable, survivorIo, modelStream = true,
+  processTable = readProcessTable, survivorIo, modelStream = true, turnReap = turnReapEnabled(),
 }) => new Promise((resolve, reject) => {
+  // Every process the turn starts inherits this marker however it detaches,
+  // so what it leaves running is stopped once the turn has closed.
+  const turn = markTurn(env ?? process.env, { enabled: turnReap });
   const proc = spawnInOwnGroup(spawnImpl, cmd, args, {
     cwd,
-    env,
+    env: turn.env,
     stdio: ['ignore', 'pipe', 'pipe'],
   }, { ownGroup });
   observeSpawn(proc, onSpawn, controls);
@@ -711,6 +716,9 @@ const runClaude = ({
     clearTimeout(timer);
     clearTimeout(stallKill);
     watchdog.stop();
+    const reaped = describeTurnReap(turn.reap(proc));
+    // eslint-disable-next-line no-console
+    if (reaped) console.warn(`[claude] ${reaped}`);
     if (stalled) {
       sweepStallSurvivors();
       return reject(stalled);
@@ -1418,6 +1426,7 @@ export default {
         stallKillGraceMs: ctx._stallKillGraceMs,
         processTable: ctx._processTable,
         survivorIo: ctx._survivorIo,
+        turnReap: ctx._turnReap,
       });
       // TASK-440: the context this turn left, read from the transcript the
       // child wrote under its own env (an isolated HOME for public seats).
@@ -1486,6 +1495,7 @@ export default {
           stallKillGraceMs: ctx._stallKillGraceMs,
           processTable: ctx._processTable,
           survivorIo: ctx._survivorIo,
+          turnReap: ctx._turnReap,
         });
         const contextTokens = claudeContextTokens({
           cwd: physicalPath(ctx.cwd), sessionId: freshId,

package/src/lib/adapters/codex.js

@@ -1,6 +1,7 @@
 import { codexRuntimeInventory } from '../native-runtime-inventory.js';
 import { observeSpawn, controlsFromArguments } from '../runtime-observation.js';
 import { spawnInOwnGroup, wantsOwnProcessGroup } from '@commonlyai/seats/process-group';
+import { describeTurnReap, markTurn, turnReapEnabled } from '@commonlyai/seats/turn-processes';
 /**
  * codex adapter — wraps the local `codex` CLI as a Commonly agent.
  *
@@ -73,7 +74,7 @@ import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { prepareMcpSpawn, publicMcpUnavailableError, selectedMcpVersionDir } from '../mcp-home.js';
-import { buildMemoryPreamble, ROW_SLICING_CUE } from '../memory-bridge.js';
+import { BACKGROUND_PROCESS_CUE, buildMemoryPreamble, ROW_SLICING_CUE } from '../memory-bridge.js';
 import { resolveSkillSource, skillsAsText } from '../skill-prompt.js';
 import { isLegacySandboxTrust, normalizeSandboxTrust, refuseWorkspaceTrust } from '../environment.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
@@ -731,14 +732,19 @@ const CODEX_PROVIDER_KEY_ENVS = [
 ];
 
 // `ownGroup`: see runClaude in claude.js.
-const runCodex = ({ args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {}, ownGroup = false }) => new Promise((resolve, reject) => {  // stdio: ['ignore', 'pipe', 'pipe'] — without this, child_process.spawn
+const runCodex = ({
+  args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {}, ownGroup = false,
+  turnReap = turnReapEnabled(),
+}) => new Promise((resolve, reject) => {  // stdio: ['ignore', 'pipe', 'pipe'] — without this, child_process.spawn
   // defaults stdin to a fresh pipe. Codex 0.125.0's `exec` then blocks on
   // `Reading additional input from stdin...` because it sees an open pipe
   // and waits for input that never arrives. Interactive runs are fine because
   // codex detects a TTY and uses the argv prompt directly. Setting stdin to
   // `'ignore'` gives codex /dev/null → immediate EOF → it falls back to the
   // argv prompt as intended. Surfaced live during ADR-005 Phase 2 smoke.
-  const proc = spawnInOwnGroup(spawnImpl, 'codex', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] }, { ownGroup });
+  // What the turn leaves running is stopped once it has closed (see claude.js).
+  const turn = markTurn(env ?? process.env, { enabled: turnReap });
+  const proc = spawnInOwnGroup(spawnImpl, 'codex', args, { cwd, env: turn.env, stdio: ['ignore', 'pipe', 'pipe'] }, { ownGroup });
   observeSpawn(proc, onSpawn, controls);
   let stderr = '';
   let timedOut = false;
@@ -757,6 +763,9 @@ const runCodex = ({ args, cwd, env, timeoutMs, credentials = [], spawnImpl = chi
   });
   proc.on('close', (code) => {
     clearTimeout(timer);
+    const reaped = describeTurnReap(turn.reap(proc));
+    // eslint-disable-next-line no-console
+    if (reaped) console.warn(`[codex] ${reaped}`);
     if (timedOut) return reject(new Error(`codex timed out after ${timeoutMs}ms`));
     if (events.turnFailedMessage) {
       // Surface the model-side failure message verbatim — the run loop posts
@@ -823,7 +832,7 @@ export default {
     // answers strangers rather than working board rows, so it is taught neither.
     const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm, {
       freshSession: !ctx.sessionId,
-      workCues: sandbox?.trust === 'public' ? [] : [ROW_SLICING_CUE],
+      workCues: sandbox?.trust === 'public' ? [] : [ROW_SLICING_CUE, BACKGROUND_PROCESS_CUE],
     });
 
     // Per-spawn temp dir for --output-last-message. Cleaned up in `finally`
@@ -917,6 +926,7 @@ export default {
         credentials: spawnCredentials(ctx, CODEX_PROVIDER_KEY_ENVS),
         spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, controls: controlsFromArguments(args.slice(args.indexOf('exec') + (args[args.indexOf('exec') + 1] === 'resume' ? 3 : 1), -1), { modelFlag: '--model', valueFlags: ['-c', '-o', '--permission-profile'], codex: true }), // test seam only — do not use in production
         ownGroup: wantsOwnProcessGroup(ctx),
+        turnReap: ctx._turnReap,
       });
 
       let text = '';

package/src/lib/memory-bridge.js

@@ -20,6 +20,8 @@
  * them from the client is wasted bytes and the kernel discards them.
  */
 
+import { KEEP_PROCESS_ENV } from '@commonlyai/seats/turn-processes';
+
 export const SOURCE_RUNTIME = 'local-cli';
 
 /**
@@ -34,6 +36,13 @@ export const ROW_SLICING_CUE = 'Slicing: when a row is too large for one turn, s
   + "to the row's taskId) with one assignee, a written file or area boundary, and its own "
   + 'acceptance line.';
 
+// The turn's leftovers are stopped when it ends (@commonlyai/seats/turn-processes),
+// so a seat that means to reuse a server has to say so when it starts it.
+export const BACKGROUND_PROCESS_CUE = 'Background processes: anything you start in the background is '
+  + 'stopped when this turn ends, including a server that starts on first use, such as tmux, and an agent you '
+  + 'restart with nohup. To keep one for a later turn, such as a dev server you will reuse, start it '
+  + `with ${KEEP_PROCESS_ENV}=1 set, and stop it yourself when you are done with it.`;
+
 /**
  * The turn preamble, shared by every adapter so the two cannot drift.
  *