@commonlyai/cli 0.1.72 → 0.1.74

package/package.json

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

package/src/commands/agent.js

@@ -17,6 +17,13 @@ import { homedir, tmpdir } from 'os';
 import { fileURLToPath } from 'url';
 
 import { createClient } from '../lib/api.js';
+import {
+  buildSpawnId,
+  createSpawnCredentialLease,
+  readSpawnPolicy,
+  resolveSpawnTtlSeconds,
+  revokeOrphanedSpawnCredentials,
+} from '../lib/spawn-credential.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
 import { startPoller, terminalDeliveryAckError } from '../lib/poller.js';
 import { startWebhookServer, forwardToLocalWebhook } from '../lib/webhook-server.js';
@@ -925,10 +932,46 @@ export const performRun = ({
   // Kept injectable for small-page regression cases; the runtime ships with
   // the server's ordinary ten-event page.
   inboxBatchLimit = 10,
+  // TASK-102 part B. Undefined means "use the server's published default"; a
+  // number here is the operator's ask, and the policy read at boot is what
+  // makes a clamp visible instead of silent.
+  spawnCredentialTtlSeconds = null,
+  spawnCredentialLeaseFactory = createSpawnCredentialLease,
+  revokeOrphansImpl = revokeOrphanedSpawnCredentials,
   sleepImpl = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
 }) => {
   const client = createClient({ instance: instanceUrl, token });
 
+  // THE BOOT SWEEP IS THE SECOND NET, AND IT HAPPENS ONCE PER PROCESS. A seat
+  // that dies mid-turn (kill, crash, reboot) leaves its child credential live
+  // until its own TTL expires, because `close()` never ran; this is what collects
+  // those. Fire-and-forget by contract: `performRun` is synchronous for its
+  // callers, the sweep is best-effort, and a sweep that failed must not stop a
+  // seat from spawning — it logs and returns. Per process rather than per spawn
+  // because the orphans being collected belong to the PREVIOUS process.
+  //
+  // The promise wrapper is not ceremony: it makes a throwing OR rejecting
+  // implementation of the seam a log line instead of an unhandled rejection,
+  // which is the difference between a diagnostic and a crash in a seat that is
+  // otherwise fine.
+  void Promise.resolve()
+    .then(() => revokeOrphansImpl({ client, log }))
+    .catch((err) => log(`spawn credential boot sweep failed (${err?.message ?? err})`));
+
+  // The bounds the server will clamp to. READ ONLY IF THERE IS AN ASK TO CLAMP:
+  // with no `COMMONLY_SPAWN_TTL_SECONDS` the cli sends no `ttlSeconds` at all
+  // and the server's default is what it is, so a per-run read would be a request
+  // on every seat's boot in exchange for nothing. Read once and cached, because
+  // the bounds are constants for the life of a process. `readSpawnPolicy` never
+  // rejects (a failure resolves to null), so this cannot fail a spawn; it just
+  // sends the ask unclamped and lets the server decide.
+  let spawnPolicyPromise = null;
+  const spawnPolicyForAsk = () => {
+    if (spawnCredentialTtlSeconds === null || spawnCredentialTtlSeconds === undefined) return null;
+    if (spawnPolicyPromise === null) spawnPolicyPromise = readSpawnPolicy({ client, log });
+    return spawnPolicyPromise;
+  };
+
   // THE SEAT'S OWN RECORD IS THE ONLY DECLARATION THERE IS. The broker reaches a
   // seat as an injected MCP entry written by hand into its environment — no
   // server projection puts it there (`GRANT_BROKER_URL` is imported by one
@@ -1267,21 +1310,90 @@ export const performRun = ({
     const promptWithFocus = `${focusFrame}\n\n${prompt}`;
 
     log(`[${event.type}] spawning ${adapter.name}`);
-    const result = await adapter.spawn(frameDecisionForkRule(promptWithFocus), {
-      sessionId,
-      cwd: agentCwd,
-      env: process.env,
-      memoryLongTerm,
-      environment: seatEnvironment,
-      // Runtime context the Claude/Codex adapters expose only to their
-      // per-spawn MCP environment. Claude keeps ${COMMONLY_*} placeholders
-      // literal on disk and lets its native MCP parser expand them, so the
-      // bearer token never enters the generated config file.
-      runtimeToken: token,
-      instanceUrl,
-      agentName,
-      metadata: { event },
+    // TASK-102 part B. The CHILD gets a scoped credential; the wrapper keeps
+    // the seat token for its own polling, claiming and posting (`client` was
+    // built from `token` above and is not touched here). The lease renews while
+    // the child runs and revokes when it returns, so the window in which a
+    // leaked child credential is usable is one turn rather than a seat's life.
+    //
+    // A refusal throws: `openSpawnCredential` only falls back to the seat token
+    // for capacity, and a verdict (401/403/400/404/409) must fail the spawn
+    // rather than restore the authority the refusal was about. The catch below
+    // turns that throw into a NAMED refusal on the turn result, so the claim is
+    // released as `delivery-refused` instead of being re-delivered forever.
+    const spawnPolicyOrNull = spawnPolicyForAsk();
+    const lease = spawnCredentialLeaseFactory({
+      client,
+      seatToken: token,
+      spawnId: buildSpawnId({ agentName, eventId: event?._id || event?.payload?.batchEventIds || null }),
+      desiredTtlSeconds: spawnCredentialTtlSeconds,
+      policy: spawnPolicyOrNull === null ? null : await spawnPolicyOrNull,
+      log,
     });
+    let opened;
+    try {
+      opened = await lease.open();
+    } catch (err) {
+      // A VERDICT IS NOT A CRASH, AND IT IS NOT A NO-OP (wren 72153, vera
+      // 72157). Letting it escape as a bare throw left `turnResult` undefined,
+      // so `claimReleaseFor` returned the legacy holder-only DELETE — right for
+      // a transient failure, wrong for a refusal that recurs on every
+      // redelivery: the wake loops forever with one local log line as its only
+      // record. Naming it on the turn result is what lets the release carry the
+      // class, and on a human wake lets the kernel hand the message to a
+      // remaining listener instead of stranding it.
+      if (!err?.spawnCredentialRefused) {
+        // ONLY a verdict is named as a refusal. An unexpected failure inside
+        // the lease — a bug in our own code, not the server's answer — keeps
+        // the legacy release, because `delivery-refused` would hand a human's
+        // message away and close the row on the strength of our own defect.
+        // Redelivery is the right remedy for a crash.
+        log(`spawn credential lease failed (${err?.message ?? err}) — not spawning`);
+        throw err;
+      }
+      const status = Number.isInteger(err.status) ? err.status : null;
+      const code = typeof err.body?.code === 'string' ? err.body.code : null;
+      log(`spawn credential refused (HTTP ${status ?? 'no response'}) — not spawning`);
+      // `delivery-refused` claims the least of the three classes: the model
+      // never ran, and the refuser is our own mint rather than the model
+      // provider (that would be `upstream-refused`, and its status is the HTTP
+      // status of an upstream call — a meaning this refusal does not have, so
+      // the number travels in the ack instead of on the claim record).
+      return {
+        outcome: 'no_action',
+        refused: { reason: 'delivery-refused' },
+        reason: `spawn-credential-refused-${status ?? 'unknown'}`,
+        details: {
+          ...(status !== null ? { status } : {}),
+          ...(code !== null ? { code } : {}),
+        },
+      };
+    }
+    let result;
+    try {
+      result = await adapter.spawn(frameDecisionForkRule(promptWithFocus), {
+        sessionId,
+        cwd: agentCwd,
+        env: process.env,
+        memoryLongTerm,
+        environment: seatEnvironment,
+        // Runtime context the Claude/Codex adapters expose only to their
+        // per-spawn MCP environment. Claude keeps ${COMMONLY_*} placeholders
+        // literal on disk and lets its native MCP parser expand them, so the
+        // bearer token never enters the generated config file. Since TASK-102
+        // part B this is the per-spawn credential when one could be minted, and
+        // the seat token only when the server could not mint.
+        runtimeToken: opened.token,
+        instanceUrl,
+        agentName,
+        metadata: { event },
+      });
+    } finally {
+      // Best-effort by construction: `close` logs and returns on a failed
+      // revoke, so a turn that already produced an answer is not failed by
+      // cleanup. The boot sweep collects anything left behind.
+      await lease.close();
+    }
 
     if (result.newSessionId) {
       setSession(agentName, eventPodId, result.newSessionId);
@@ -2611,6 +2723,10 @@ Docs:
         workspacePath: record.workspacePath || null,
         intervalMs: parseInt(opts.interval, 10),
         ...cascadeOverridesFromOpts(opts),
+        // TASK-102 part B: the operator's TTL ask, if any. Unset means the
+        // server's published default, which is the only lifetime we can justify
+        // without an operator saying otherwise.
+        spawnCredentialTtlSeconds: resolveSpawnTtlSeconds(process.env),
         log: (line) => console.log(`${stamp()} [${name}] ${line}`),
         // Both sinks are stamped, and both must be — but not for the reason
         // this comment gave until now, which its own PR falsified.

package/src/commands/daemon.js

@@ -9,7 +9,7 @@
 import { hostname, homedir } from 'os';
 import { spawn } from 'child_process';
 import {
-  chmodSync, closeSync, existsSync, mkdirSync, openSync, rmSync, watch, writeFileSync,
+  chmodSync, closeSync, existsSync, mkdirSync, openSync, rmSync, watch,
 } from 'fs';
 import { createClient } from '../lib/api.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
@@ -21,7 +21,7 @@ import {
 } 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 { getAdapter, providerKeyEnvNames } from '../lib/adapters/index.js';
 import {
   installDaemonService,
   uninstallDaemonService,
@@ -29,6 +29,7 @@ import {
   stopDaemonService,
   restartDaemonService,
   daemonLogPath,
+  missingProviderKeys,
   servicePaths,
 } from '../lib/daemon-service.js';
 import { daemonLogsDir, daemonSeatLogPath, readLogTail } from '../lib/daemon-logs.js';
@@ -237,7 +238,10 @@ Examples:
 
   // ── install / uninstall (ADR-026 D1) ──────────────────────────────────────
   const serviceDeps = () => ({
-    writeFile: (file, content) => writeFileSync(file, content, 'utf8'),
+    // 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); },
@@ -270,7 +274,12 @@ Examples:
       try {
         // A service without a credential just crash-loops at boot.
         requireDaemonRecord();
-        await installDaemonService(serviceDeps());
+        // 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.
+        await installDaemonService({ ...serviceDeps(), providerKeyEnvNames: providerKeyEnvNames() });
         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}`);
@@ -342,6 +351,20 @@ Examples:
         chmodSync(logsDir, 0o700);
         const stampLog = (line) => console.log(`${new Date().toISOString()} ${line}`);
 
+        // TASK-049: fail loudly at BIND, 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; every 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. One
+        // line at startup answers the question the log would otherwise take a
+        // seat autopsy to answer. Not fatal: the daemon's other seats are
+        // unaffected, and refusing to start would turn one missing key into a
+        // whole-machine outage.
+        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)`);
+        }
+
         const supervisor = createDaemonSupervisor({
           record,
           client,

package/src/lib/adapters/index.js

@@ -22,3 +22,18 @@ const ADAPTERS = {
 export const listAdapterNames = () => Object.keys(ADAPTERS);
 
 export const getAdapter = (name) => ADAPTERS[name] || null;
+
+/**
+ * TASK-049: the environment a seat's ADAPTER needs from the operator's shell.
+ *
+ * The adapter owns the provider, so the adapter declares the variable (see
+ * `pi.js`); the daemon reads the list to carry those keys into its login
+ * service, because launchd and systemd start the daemon with a clean
+ * environment — a key that exists only in an interactive shell is absent at
+ * boot, and the seat then dies inside its own adapter. An adapter that
+ * authenticates through its own CLI (claude, codex) declares nothing here and
+ * contributes nothing.
+ */
+export const providerKeyEnvNames = (adapters = ADAPTERS) => [...new Set(
+  Object.values(adapters).map((adapter) => adapter.providerKeyEnv).filter(Boolean),
+)];

package/src/lib/adapters/pi.js

@@ -386,6 +386,14 @@ const runPi = ({ args, cwd, env, payload, timeoutMs, credentials = [], spawnImpl
 export default {
   name: 'pi',
 
+  // TASK-049: the variable this adapter needs from the environment of whatever
+  // process spawns it. Declared HERE because the adapter owns the provider; the
+  // registry collects it (adapters/index.js) so the daemon can carry the key
+  // into its login service and fail loudly at bind when it is absent, instead
+  // of the seat dying at line ~406 with nothing naming the missing variable at
+  // daemon level.
+  providerKeyEnv: DEFAULT_PROVIDER.apiKeyEnv,
+
   async detect() {
     const res = spawnSync('pi', ['--version'], { encoding: 'utf8' });
     if (res.error || res.status !== 0) return null;

package/src/lib/daemon-service.js

@@ -11,6 +11,8 @@
  * supervisor: the unit CONTENT is unit-testable without touching launchctl.
  */
 
+import { randomBytes } from 'crypto';
+import { renameSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname, resolve } from 'path';
 
@@ -28,6 +30,29 @@ export const servicePaths = (platform = process.platform, home = homedir()) => (
 const xmlEscape = (value) => String(value)
   .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 
+// The systemd sink is NOT the plist sink, so escaping one is not escaping both.
+// Inside `Environment="…"` a raw `"` closes the quote, and a raw newline ends
+// the assignment so the remainder of the key lands in the unit as a directive.
+// The adversary here is the operator's own environment, so severity is low —
+// but correctness does not need an adversary: a provider key containing a `"`
+// writes a unit that will not start, with nothing on screen to say why.
+// systemd quoted values carry C-style escapes (systemd.syntax(7)), so both
+// values are escaped and neither sink is trusted to be the harmless one. The
+// last replacement is the least obvious: `Environment=` does NOT expand `$VAR`
+// but DOES perform specifier expansion (systemd.exec(5), "Specifier expansion is
+// performed"), and `systemd.unit(5)` gives the escape — `%%` in place of `%`.
+// A key containing `%h` would otherwise be rewritten to the home directory: the
+// unit parses, the daemon starts, the seat gets a key nobody exported, and it
+// fails at the provider with nothing at daemon level naming the cause — the same
+// failure class this code exists to remove, arriving through the escaping.
+const systemdEscape = (value) => String(value)
+  .replace(/%/g, '%%')
+  .replace(/\\/g, '\\\\')
+  .replace(/"/g, '\\"')
+  .replace(/\n/g, '\\n')
+  .replace(/\r/g, '\\r')
+  .replace(/\t/g, '\\t');
+
 // PATH matters for the CHILDREN: the daemon spawns `commonly agent run`,
 // which spawns the user's claude/codex CLI by name. launchd's default PATH
 // has no /opt/homebrew/bin, so without this the daemon comes up and every
@@ -36,7 +61,87 @@ const childPath = (nodePath) => [
   dirname(nodePath), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin',
 ].filter((entry, index, all) => all.indexOf(entry) === index).join(':');
 
-export const launchdPlist = ({ nodePath, cliPath, home = homedir() }) => `<?xml version="1.0" encoding="UTF-8"?>
+// TASK-049: PATH is not the only thing the children need.
+//
+// launchd and systemd both start the daemon from a CLEAN environment, so a
+// seat's provider key that exists only in the operator's interactive shell is
+// absent at boot — and the seat then dies inside its own adapter (`pi.js`
+// throws `COMMONLY_LITELLM_KEY is not set`). That is the same defect the PATH
+// line above fixes, one layer over, and it is fixed the same way: carry what
+// the install could see. Installation is the ONLY moment the operator's shell is
+// in reach, so the keys are captured there, and the ones that were missing are
+// named at install time rather than discovered one crash-looping seat at a time.
+//
+// The values are secrets. The daemon's own credential is a 0600 file, so the
+// service file is written 0600 too instead of being left at the umask default a
+// PATH-only unit could safely keep.
+//
+// The mode is guaranteed BY CONSTRUCTION rather than by the order of two calls:
+// the content is written to a sibling temp file CREATED 0600 and then renamed
+// over the target. `writeFileSync`'s mode applies only at creation, so the
+// obvious alternatives each leave a path open — a write straight to the target
+// cannot narrow a file an EARLIER install left at 0644 (its mode survives the
+// write, and a pre-existing 0644 service file is what every upgrade meets),
+// and a chmod after the write closes the door the key already walked through.
+// The rename also removes a second hazard, narrower than it first looks: systemd
+// does NOT re-read a changed unit by itself — it reports the file as changed on
+// disk and keeps the loaded copy until a `systemctl --user daemon-reload`. What
+// is exposed is a reader CONCURRENT with the write, and that is not exotic here:
+// an install ends by running `daemon-reload`, every other install on the machine
+// can run one at the same moment, and `systemctl --user show` reads the file.
+// After a rename each of them sees the old file or the new one, never a
+// truncated unit.
+//
+// POSIX rename replaces the destination atomically, so this needs no
+// chmod-if-exists dance and no cleanup of the old file.
+//
+// The temp NAME and the temp WRITE are each half of the same defence, and
+// neither is sufficient on its own. A predictable name (`<file>.tmp-<pid>`) lets
+// a process running as this user — which is every seat this repo spawns —
+// pre-plant a symlink at that path and capture the key when the write follows
+// it; `O_EXCL` is what actually refuses that, because it fails on a symlink at
+// the final component instead of writing through it. The random suffix only
+// removes the easy target, and the cleanup only deletes a temp this call made.
+export const SERVICE_FILE_MODE = 0o600;
+
+// Exported so the O_EXCL refusal is witnessed against a real symlink at a known
+// path rather than assumed from the absence of a race.
+export const serviceTempPath = (file, suffix = randomBytes(6).toString('hex')) => `${file}.tmp-${suffix}`;
+
+export const writeServiceFile = (file, content, { suffix } = {}) => {
+  const tmp = serviceTempPath(file, suffix);
+  let created = false;
+  try {
+    // `wx` = O_CREAT|O_EXCL: the write either creates the temp itself or does not
+    // happen at all, so a planted path is refused rather than followed.
+    writeFileSync(tmp, content, { encoding: 'utf8', mode: SERVICE_FILE_MODE, flag: 'wx' });
+    created = true;
+    renameSync(tmp, file);
+  } catch (error) {
+    // Only the temp this call created is ours to remove. After a refused write
+    // the path belongs to whoever planted it.
+    if (created) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        // Nothing to clean up; the original error is the one that matters.
+      }
+    }
+    throw error;
+  }
+};
+export const providerEnvPairs = ({ names = [], env = process.env } = {}) => names
+  .filter((name) => env[name])
+  .map((name) => [name, String(env[name])]);
+
+export const missingProviderKeys = ({ names = [], env = process.env } = {}) => names
+  .filter((name) => !env[name]);
+
+const plistEnvPairs = (pairs) => pairs
+  .map(([name, value]) => `\t\t<key>${xmlEscape(name)}</key>\n\t\t<string>${xmlEscape(value)}</string>\n`)
+  .join('');
+
+export const launchdPlist = ({ nodePath, cliPath, home = homedir(), providerEnv = [] }) => `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
@@ -48,7 +153,7 @@ export const launchdPlist = ({ nodePath, cliPath, home = homedir() }) => `<?xml
 \t\t<string>${xmlEscape(childPath(nodePath))}</string>
 \t\t<key>HOME</key>
 \t\t<string>${xmlEscape(home)}</string>
-\t</dict>
+${plistEnvPairs(providerEnv)}\t</dict>
 \t<key>ProgramArguments</key>
 \t<array>
 \t\t<string>${xmlEscape(nodePath)}</string>
@@ -69,7 +174,11 @@ export const launchdPlist = ({ nodePath, cliPath, home = homedir() }) => `<?xml
 </plist>
 `;
 
-export const systemdUnit = ({ nodePath, cliPath }) => `[Unit]
+export const systemdUnit = ({ nodePath, cliPath, providerEnv = [] }) => {
+  const providerLines = providerEnv.length
+    ? `\n${providerEnv.map(([name, value]) => `Environment="${systemdEscape(`${name}=${value}`)}"`).join('\n')}`
+    : '';
+  return `[Unit]
 Description=Commonly local agent daemon (ADR-026)
 After=network-online.target
 
@@ -77,23 +186,28 @@ After=network-online.target
 ExecStart=${nodePath} ${cliPath} daemon run --foreground
 Restart=always
 RestartSec=5
-Environment=PATH=${childPath(nodePath)}
+Environment=PATH=${childPath(nodePath)}${providerLines}
 
 [Install]
 WantedBy=default.target
 `;
+};
 
 export const installDaemonService = async ({
   platform = process.platform,
   home = homedir(),
   nodePath = process.execPath,
   cliPath = resolve(process.argv[1]),
-  writeFile,
+  // The provider keys the seats' adapters declare (adapters/index.js).
+  providerKeyEnvNames = [],
+  env = process.env,
+  writeFile = writeServiceFile,
   mkdirp,
   execCmd, // async (argv: string[]) => void — throws on failure
   chmod = () => {},
   ensureFile,
   log = () => {},
+  warn = log,
 }) => {
   const target = servicePaths(platform, home);
   mkdirp(dirname(target.file));
@@ -104,17 +218,27 @@ export const installDaemonService = async ({
     chmod(daemonLogPath(home), 0o600);
   }
 
+  const providerEnv = providerEnvPairs({ names: providerKeyEnvNames, env });
+  const missing = missingProviderKeys({ names: providerKeyEnvNames, env });
+
   if (target.kind === 'launchd') {
-    writeFile(target.file, launchdPlist({ nodePath, cliPath, home }));
+    // The mode and the atomicity are the WRITER's, not an ordering rule here:
+    // `writeServiceFile` creates a 0600 sibling and renames it over the target,
+    // so no chmod is needed on this path and no half-written unit is ever
+    // visible to launchd (see the writer for why neither half could cover both).
+    writeFile(target.file, launchdPlist({ nodePath, cliPath, home, providerEnv }));
     // Reload cleanly if a previous version is loaded; the unload of an
     // unknown label fails by design and is ignored.
     await execCmd(['launchctl', 'unload', target.file]).catch(() => {});
     await execCmd(['launchctl', 'load', '-w', target.file]);
   } else {
-    writeFile(target.file, systemdUnit({ nodePath, cliPath }));
+    writeFile(target.file, systemdUnit({ nodePath, cliPath, providerEnv }));
     await execCmd(['systemctl', '--user', 'daemon-reload']);
     await execCmd(['systemctl', '--user', 'enable', '--now', 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)`);
+  }
   log(`Installed ${target.kind} service (${target.file}). Logs: ${daemonLogPath(home)}`);
   return target;
 };

package/src/lib/spawn-credential.js

@@ -0,0 +1,375 @@
+/**
+ * spawn-credential.js — TASK-102 part B (the cli half of TASK-094).
+ *
+ * WHAT THIS REPLACES. Every adapter used to hand the child the seat's own
+ * runtime token (`ctx.runtimeToken`, sourced from `COMMONLY_AGENT_TOKEN`): one
+ * long-lived credential, the full authority of the seat, inherited by every
+ * process the child spawns and written to a credential file that outlives the
+ * turn. The backend half (TASK-094 PR A, merged as `3e08c328`) can mint a
+ * per-spawn child instead — bounded lifetime, named in a ledger, revocable —
+ * and this module is the caller that makes that real rather than available.
+ *
+ * WHY A LEASE AND NOT A SINGLE MINT. The granted TTL is 900s by default
+ * (`SPAWN_TTL_MAX_SECONDS`), and a turn can outlive it: a long coding turn
+ * would start failing mid-flight with 401s the seat cannot explain, which is
+ * strictly worse than the seat token it replaced. So the lease renews at
+ * half-life while the child runs (the absolute lifetime is 24h, so renewal is
+ * the mechanism the backend already provides for exactly this) and revokes at
+ * the end of the turn, which is what bounds a leaked child credential to one
+ * turn instead of forever.
+ *
+ * THE FALLBACK PREDICATE IS ABOUT WHAT A FAILURE TELLS US (vera 71068/`#1823`
+ * thread). Four arms, each named here so a reader checking the predicate against
+ * this comment does not have to re-derive one:
+ *
+ *   capacity — 429, 5xx, or no HTTP response at all. The server could not mint
+ *     *right now*; that says nothing about whether this seat may mint, and the
+ *     seat token is an authority the seat already holds, so falling back grants
+ *     nothing new and keeps the seat working. `no status` belongs here because
+ *     the request never got a verdict at all: an availability fact, not an
+ *     authorization one.
+ *   route absent — a 404 whose body carries NO `code`. The mint's own refusals
+ *     always name themselves (`REFUSAL_STATUS` in
+ *     `backend/routes/spawnCredentials.ts` maps `not_found` → 404), so a bare
+ *     404 is Express's default page from a backend deployed before this route
+ *     existed. Failing THAT closed would stop every spawn on such a fleet and
+ *     re-deliver the event forever — strictly worse than the seat token every
+ *     seat was using before this module existed. `readSpawnPolicy` reads its own
+ *     404 the same way; one reading of "404" per file, not two.
+ *   verdict — every other 4xx (401 dead token, 403 not this seat's installation,
+ *     400 malformed spawn id, 409 not renewable, or a 404 that DOES carry a
+ *     code). A refusal is about the caller or the request, and falling back
+ *     there would silently restore the exact authority the refusal was about,
+ *     making the whole mechanism decorative.
+ *   malformed success — a 2xx carrying no usable token. Deliberately NOT filed
+ *     under capacity: the server answered, and the answer is a server bug
+ *     rather than anything about this caller. It falls back for the same reason
+ *     route-absent does — the seat's authority is what it already had, and
+ *     failing closed would take a fleet down over someone else's bug — but it is
+ *     its own arm so that the choice is visible as a choice.
+ *
+ * The caller's own identity is never used for its own HTTP call: the lease is
+ * minted with the SEAT token over the seat's client, and only the CHILD gets
+ * the scoped token. The wrapper keeps polling, claiming and posting with the
+ * seat token, which is why `performRun` passes `spawnToken.token` to the
+ * adapter and keeps `token` for its client.
+ *
+ * THE POLICY READ EXISTS SO THE CLAMP IS VISIBLE. `GET /policy` publishes the
+ * bounds `clampSpawnTtlSeconds` actually applies (`minTtlSeconds`,
+ * `maxTtlSeconds`, `absoluteLifetimeSeconds`). A caller that asks for 3600 used
+ * to receive a 900s credential with no way to find out; here the ask is
+ * compared against the published cap and the difference is logged once at
+ * open. The read is best-effort: a missing policy degrades to sending the ask
+ * and letting the server clamp, never to refusing to spawn.
+ */
+
+export const SPAWN_CREDENTIAL_BASE = '/api/agents/runtime/spawn-credentials';
+
+// Renew at half the granted lifetime: one renewal is missed and the credential
+// still has 450s of headroom at the default TTL, which covers a slow span
+// between the timer firing and the request landing.
+export const RENEW_AT_FRACTION = 0.5;
+
+// Never renew faster than this. A server that grants a TTL shorter than two
+// minutes would otherwise produce a renewal loop tight enough to be its own
+// traffic; the floor keeps the loop's cadence a function of our intent rather
+// than of an unexpectedly small grant.
+export const MIN_RENEW_INTERVAL_MS = 30 * 1000;
+
+/** Capacity (the server could not mint) vs verdict (the server refused). */
+export const isCapacityRefusal = (status) => (
+  status === undefined || status === null || status === 429 || status >= 500
+);
+
+/**
+ * A 404 with no `code` is the route missing, not this caller being refused.
+ *
+ * The mint's refusals are always typed (`not_found` → 404 via
+ * `REFUSAL_STATUS`), so an untyped 404 cannot have come from the route — it is
+ * Express's default page. Treated as its own arm rather than as a verdict
+ * because the two call for opposite handling: a verdict must fail the spawn
+ * closed, while a route that does not exist yet must not stop the fleet from
+ * spawning at all.
+ */
+export const isRouteAbsentRefusal = (status, body) => (
+  status === 404 && !body?.code
+);
+
+/**
+ * The ledger names the spawn, and the name has to be stable per spawn and
+ * unique across spawns: the event id is the only identifier the wrapper has
+ * that means "this turn" (a session id recurs across turns, an agent name
+ * recurs forever). Truncated to the route's `MAX_SPAWN_ID_LENGTH`, keeping the
+ * tail — the event id — because the prefix is the part a reader can infer.
+ */
+export const buildSpawnId = ({ agentName = 'agent', eventId = null, maxLength = 128 } = {}) => {
+  const suffix = eventId === null || eventId === undefined ? 'unknown' : String(eventId);
+  const tail = `:${suffix}`;
+  // The bound is on the WHOLE id. Bounding only the suffix (the first version)
+  // let a long enough agent name through the bound entirely: the backend
+  // refuses anything over MAX_SPAWN_ID_LENGTH with `invalid_spawn_id` → 400 →
+  // fail closed, so a name would have made its own seat unspawnable. The name is
+  // shortened first because it is the part a reader can infer from the pod; the
+  // event id is what makes the row unique across turns, so it is kept whole
+  // whenever it fits. Longest live `instanceId` is 25 chars (vera, 566 seats),
+  // so this guards a future name rather than a live path.
+  const nameBudget = Math.max(1, maxLength - tail.length);
+  const name = String(agentName).slice(0, nameBudget) || 'agent';
+  const id = `${name}${tail}`;
+  return id.length > maxLength ? id.slice(0, maxLength) : id;
+};
+
+/**
+ * The operator's ask, read from `COMMONLY_SPAWN_TTL_SECONDS`.
+ *
+ * Unset is the normal case and means "the server's published default" — the
+ * cli has no business inventing a lifetime for a credential it does not own.
+ * A malformed value degrades to unset rather than to a guess: this knob exists
+ * so an operator can discover the cap, and a typo must not become a different
+ * number that nobody chose.
+ */
+export const resolveSpawnTtlSeconds = (env = {}) => {
+  const raw = String(env.COMMONLY_SPAWN_TTL_SECONDS || '').trim();
+  if (!raw) return null;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return parsed;
+};
+
+/**
+ * Best-effort bounds read. Returns null when the route is absent (an older
+ * server) or unreachable — the caller then sends its ask unclamped and lets the
+ * server's own clamp decide, which is the pre-policy behaviour and never worse.
+ */
+export const readSpawnPolicy = async ({ client, log = () => {} }) => {
+  try {
+    const policy = await client.get(`${SPAWN_CREDENTIAL_BASE}/policy`);
+    return policy && typeof policy === 'object' ? policy : null;
+  } catch (err) {
+    log(`spawn credential policy unavailable (${err?.status ?? 'no response'}) — sending the TTL ask unclamped`);
+    return null;
+  }
+};
+
+/**
+ * The boot sweep: collect credentials orphaned by a process that died before it
+ * could revoke them (a killed seat, a crashed daemon, a machine that rebooted
+ * mid-turn). `POST /revoke-orphans` is the net behind `close()`.
+ *
+ * Called once per process from the run entry, and best-effort on purpose: it is
+ * the SECOND net, so a failure has to leave the seat starting normally. It also
+ * cannot be allowed to hold up the first turn, which is why the caller does not
+ * await it.
+ */
+export const revokeOrphanedSpawnCredentials = async ({ client, log = () => {} }) => {
+  try {
+    const result = await client.post(`${SPAWN_CREDENTIAL_BASE}/revoke-orphans`, {});
+    const revoked = typeof result?.revoked === 'number' ? result.revoked : null;
+    log(revoked
+      ? `spawn credential boot sweep revoked ${revoked} orphan(s)`
+      : 'spawn credential boot sweep found no orphans');
+    return { ok: true, revoked };
+  } catch (err) {
+    // Includes the route-absent case: a backend older than the mint has no
+    // sweep to run, and that must be a log line, never a failed boot.
+    log(`spawn credential boot sweep skipped (${err?.status ?? 'no response'})`);
+    return { ok: false, reason: 'sweep-failed' };
+  }
+};
+
+/**
+ * Open one lease. Returns `{ token, credentialId, source, expiresAt, grantedSeconds }`.
+ *
+ * `source` is `'spawn'` when the child got a scoped credential and
+ * `'seat-fallback'` when it got the seat token because the server could not
+ * mint. A refusal (a verdict — see the header) throws with
+ * `spawnCredentialRefused` set and the status attached, so the caller fails the
+ * spawn closed rather than falling back.
+ */
+export const openSpawnCredential = async ({
+  client,
+  seatToken,
+  spawnId,
+  desiredTtlSeconds = null,
+  policy = null,
+  log = () => {},
+}) => {
+  const cap = typeof policy?.maxTtlSeconds === 'number' ? policy.maxTtlSeconds : null;
+  let ask = desiredTtlSeconds;
+  if (typeof ask === 'number' && Number.isFinite(ask)) {
+    if (cap !== null && ask > cap) {
+      log(`spawn credential: asked for ${ask}s, the server's cap is ${cap}s — asking for ${cap}s instead`);
+      ask = cap;
+    }
+  } else {
+    ask = null;
+  }
+
+  let minted;
+  try {
+    minted = await client.post(
+      SPAWN_CREDENTIAL_BASE,
+      ask === null ? { spawnId } : { spawnId, ttlSeconds: ask },
+    );
+  } catch (err) {
+    const status = err?.status ?? null;
+    if (isCapacityRefusal(status === null ? undefined : status)) {
+      log(`spawn credential unavailable (${status === null ? 'no response' : `HTTP ${status}`}) — spawning with the seat token`);
+      return { token: seatToken, credentialId: null, source: 'seat-fallback', expiresAt: null, grantedSeconds: null };
+    }
+    if (isRouteAbsentRefusal(status, err?.body)) {
+      log('spawn credential route absent on this backend (HTTP 404 with no code) — spawning with the seat token');
+      return {
+        token: seatToken, credentialId: null, source: 'seat-fallback', expiresAt: null, grantedSeconds: null, reason: 'route-absent',
+      };
+    }
+    const code = err?.body?.code ? ` code=${err.body.code}` : '';
+    const refusal = new Error(`spawn credential refused: HTTP ${status}${code}`);
+    refusal.spawnCredentialRefused = true;
+    refusal.status = status;
+    refusal.body = err?.body ?? null;
+    throw refusal;
+  }
+
+  // A 201 with no usable token is not a credential. Treat it as un-mintable
+  // and fall back, rather than handing the child `undefined` — which would
+  // look like a scoped credential everywhere downstream while silently being
+  // no credential at all. (It is also the shape a stub client returns, so this
+  // guard is what keeps a test that does not care about minting on the seat
+  // token instead of on nothing.)
+  if (typeof minted?.token !== 'string' || !minted.token.trim()) {
+    log('spawn credential response carried no token — spawning with the seat token');
+    return {
+      token: seatToken, credentialId: null, source: 'seat-fallback', expiresAt: null, grantedSeconds: null, reason: 'no-token',
+    };
+  }
+
+  const grantedSeconds = minted?.expiresAt
+    ? Math.max(0, Math.round((new Date(minted.expiresAt).getTime() - Date.now()) / 1000))
+    : (typeof ask === 'number' ? ask : cap);
+  return {
+    token: minted.token,
+    credentialId: minted.credentialId || null,
+    source: 'spawn',
+    expiresAt: minted.expiresAt || null,
+    grantedSeconds,
+  };
+};
+
+/** Renewal cadence for a granted lifetime. */
+export const renewIntervalMs = (grantedSeconds) => {
+  const half = typeof grantedSeconds === 'number' && grantedSeconds > 0
+    ? (grantedSeconds * 1000) * RENEW_AT_FRACTION
+    : MIN_RENEW_INTERVAL_MS;
+  return Math.max(MIN_RENEW_INTERVAL_MS, Math.round(half));
+};
+
+/**
+ * A lease owns the credential's lifetime: open, renew while the child runs,
+ * revoke when it ends. `setIntervalImpl`/`clearIntervalImpl` are injected so a
+ * test can drive the cadence without waiting on wall-clock time.
+ */
+export const createSpawnCredentialLease = ({
+  client,
+  seatToken,
+  spawnId,
+  desiredTtlSeconds = null,
+  policy = null,
+  log = () => {},
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+}) => {
+  let credentialId = null;
+  let timer = null;
+  let grantedSeconds = null;
+
+  const stopRenewal = () => {
+    if (timer !== null) {
+      clearIntervalImpl(timer);
+      timer = null;
+    }
+  };
+
+  const renew = async () => {
+    if (!credentialId) return;
+    // A renewal extends the SAME credential, so the TTL to ask for is the one
+    // the server already granted rather than the caller's original desire: a
+    // caller that asked for 3600 and was capped at 900 must not turn every
+    // renewal into another request for 3600.
+    const ask = typeof grantedSeconds === 'number' && grantedSeconds > 0
+      ? Math.floor(grantedSeconds)
+      : undefined;
+    try {
+      await client.post(
+        `${SPAWN_CREDENTIAL_BASE}/${credentialId}/renew`,
+        ask === undefined ? {} : { ttlSeconds: ask },
+      );
+      log(`spawn credential renewed (${credentialId})`);
+    } catch (err) {
+      const status = err?.status ?? null;
+      if (isCapacityRefusal(status === null ? undefined : status)) {
+        // The credential is still live; we simply could not reach the server.
+        // Keep the timer: the next tick is a fresh attempt.
+        log(`spawn credential renewal deferred (${status === null ? 'no response' : `HTTP ${status}`})`);
+        return;
+      }
+      if (isRouteAbsentRefusal(status, err?.body)) {
+        // Same reading of 404 as `openSpawnCredential`: an untyped 404 is the
+        // route missing, so keep the timer and do not treat it as a verdict
+        // about this credential. The credential keeps its remaining lifetime
+        // either way, and a route that comes back is picked up next tick.
+        log('spawn credential renewal deferred (route absent, HTTP 404 with no code)');
+        return;
+      }
+      // A verdict — expired or revoked. The route's contract is explicit that
+      // this is the caller's signal to stop, not to retry harder: a late
+      // renewal must not resurrect a dead child.
+      stopRenewal();
+      log(`spawn credential renewal refused (HTTP ${status}) — the child keeps its remaining lifetime and is not extended`);
+    }
+  };
+
+  const startRenewal = () => {
+    const interval = renewIntervalMs(grantedSeconds);
+    timer = setIntervalImpl(() => { renew(); }, interval);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  };
+
+  return {
+    async open() {
+      const opened = await openSpawnCredential({ client, seatToken, spawnId, desiredTtlSeconds, policy, log });
+      credentialId = opened.credentialId;
+      grantedSeconds = opened.grantedSeconds;
+      if (opened.source === 'spawn' && credentialId) startRenewal();
+      log(opened.source === 'spawn'
+        ? `spawn credential minted (${credentialId}, granted ${opened.grantedSeconds}s)`
+        : 'spawning with the seat token (spawn credential unavailable)');
+      return opened;
+    },
+
+    /**
+     * End the spawn: stop extending it and revoke it. Revocation is
+     * best-effort on purpose — the boot sweep (`revokeOrphanedSpawnCredentials`,
+     * called once per process from the run entry) is the second net, and a
+     * failed revoke must never fail a turn that already produced an answer.
+     */
+    async close() {
+      stopRenewal();
+      if (!credentialId) return { revoked: false, reason: 'no-credential' };
+      const id = credentialId;
+      credentialId = null;
+      try {
+        await client.del(`${SPAWN_CREDENTIAL_BASE}/${id}`);
+        log(`spawn credential revoked (${id})`);
+        return { revoked: true };
+      } catch (err) {
+        log(`spawn credential revoke failed (${id}, ${err?.status ?? 'no response'}) — the boot sweep will collect it`);
+        return { revoked: false, reason: 'revoke-failed' };
+      }
+    },
+
+    // Exposed for tests and for a caller that wants the cadence it got.
+    get credentialId() { return credentialId; },
+    get grantedSeconds() { return grantedSeconds; },
+  };
+};