@chorus-aidlc/chorus 0.14.2 → 0.14.4

package/cli/codex-usage-map.mjs

@@ -0,0 +1,115 @@
+// Persist the last cumulative Codex token snapshot per Chorus anchor. Codex
+// `turn.completed.usage` is backed by ThreadTokenUsage.total, so resumed execs
+// must subtract this baseline before publishing per-turn usage.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const NOOP_LOGGER = { warn() {} };
+const FIELDS = [
+  "input_tokens",
+  "cached_input_tokens",
+  "cache_write_input_tokens",
+  "output_tokens",
+  "reasoning_output_tokens",
+];
+
+export function codexUsageMapPath() {
+  return join(homedir(), ".chorus", "codex-usage.json");
+}
+
+function tokenInt(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.trunc(value)
+    : null;
+}
+
+function sanitizeUsage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const usage = {};
+  let found = false;
+  for (const field of FIELDS) {
+    const parsed = tokenInt(value[field]);
+    if (parsed !== null) {
+      usage[field] = parsed;
+      found = true;
+    }
+  }
+  return found ? usage : null;
+}
+
+function readMap(path, read, logger) {
+  try {
+    const parsed = JSON.parse(read(path));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    if (!(err && err.code === "ENOENT")) {
+      logger.warn(`[Chorus] codex-usage-map: read failed (${err}) - treating as empty`);
+    }
+    return {};
+  }
+}
+
+export function getCodexUsageSnapshot(anchor, threadId, deps = {}) {
+  if (!anchor || !threadId) return null;
+  const path = deps.path ?? codexUsageMapPath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const logger = deps.logger ?? NOOP_LOGGER;
+  const entry = readMap(path, read, logger)[anchor];
+  if (!entry || entry.threadId !== threadId) return null;
+  return sanitizeUsage(entry.usage);
+}
+
+export function setCodexUsageSnapshot(anchor, threadId, usage, deps = {}) {
+  const clean = sanitizeUsage(usage);
+  if (!anchor || !threadId || !clean) return;
+  const path = deps.path ?? codexUsageMapPath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const write = deps.write ?? writeFileSync;
+  const mkdir = deps.mkdir ?? mkdirSync;
+  const rename = deps.rename ?? renameSync;
+  const logger = deps.logger ?? NOOP_LOGGER;
+  try {
+    const map = readMap(path, read, logger);
+    map[anchor] = { threadId, usage: clean };
+    mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    write(tmp, JSON.stringify(map, null, 2) + "\n", { mode: 0o600 });
+    rename(tmp, path);
+  } catch (err) {
+    logger.warn(`[Chorus] codex-usage-map: persist failed (${err}) - next turn may overcount`);
+  }
+}
+
+function delta(current, previous) {
+  const now = tokenInt(current);
+  if (now === null) return null;
+  const before = tokenInt(previous);
+  return before !== null && now >= before ? now - before : now;
+}
+
+export function normalizeCodexUsageEvent(event, previous) {
+  if (!event || event.type !== "turn.completed" || !event.usage) return event;
+  const raw = event.usage;
+  const input = delta(raw.input_tokens, previous?.input_tokens);
+  const cacheRead = delta(raw.cached_input_tokens, previous?.cached_input_tokens);
+  const cacheWrite = delta(raw.cache_write_input_tokens, previous?.cache_write_input_tokens);
+  const exclusiveInput =
+    input === null ? null : Math.max(0, input - (cacheRead ?? 0) - (cacheWrite ?? 0));
+
+  return {
+    ...event,
+    usage: {
+      ...raw,
+      input_tokens: exclusiveInput,
+      cached_input_tokens: cacheRead,
+      cache_write_input_tokens: cacheWrite,
+      output_tokens: delta(raw.output_tokens, previous?.output_tokens),
+      reasoning_output_tokens: delta(
+        raw.reasoning_output_tokens,
+        previous?.reasoning_output_tokens
+      ),
+    },
+  };
+}

package/cli/daemon-agent.mjs

@@ -3,7 +3,18 @@
 // `claude-code` (the default), `codex`, and `kiro` are all implemented backends
 // (add-daemon-codex-backend cashed in the reserved `codex` slot;
 // add-daemon-kiro-backend adds `kiro`). Resolving an unknown value is a hard
-// error (no silent fallback). Zero dependencies.
+// error (no silent fallback).
+//
+// Resolution is layered like resolveSigintTimeoutMs / resolveDaemonCwds in
+// daemon-config.mjs — first defined source wins:
+//   --agent flag > CHORUS_AGENT env > ~/.chorus/daemon.json `agent` > claude-code.
+// The config-file layer lets an operator persist a default backend (e.g.
+// `"agent": "codex"`) once instead of re-passing --agent / re-exporting the env
+// on every start. IO (file read) is injectable so this stays unit-testable
+// without real disk.
+
+import { readFileSync } from "node:fs";
+import { loginFilePath } from "./credentials.mjs";
 
 /** The agent backends the daemon recognizes. All are implemented (claude-code
  * via ClaudeSpawner, codex via CodexSpawner, kiro via KiroSpawner — see
@@ -42,19 +53,58 @@ export function backendClientType(agentType) {
 }
 
 /**
- * Resolve the agent type from flag → env → default, and validate it.
- * Precedence: explicit `--agent` flag > CHORUS_AGENT env > DEFAULT_AGENT.
+ * Read a JSON file, returning `null` on any error (missing / unreadable /
+ * malformed). Never throws — mirrors daemon-config.mjs readJsonSafe.
+ * @param {string} path
+ * @returns {Record<string, unknown> | null}
+ */
+function readJsonSafe(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Resolve the agent type from flag → env → config file → default, and validate it.
+ * Precedence (first defined source wins, mirroring resolveSigintTimeoutMs /
+ * resolveDaemonCwds): explicit `--agent` flag > CHORUS_AGENT env >
+ * ~/.chorus/daemon.json `agent` > DEFAULT_AGENT.
+ *
+ * An unknown value from ANY source (flag, env, or file) is a hard error — no
+ * silent fallback. The config file lets an operator persist a default backend
+ * without re-passing --agent on every start.
  *
  * @param {{ agent?: string }} flags
  * @param {Record<string, string|undefined>} env
+ * @param {{
+ *   readJson?: (path: string) => (Record<string, unknown>|null),
+ *   loginPath?: string,
+ * }} [deps]
  * @returns {{ ok: true, agent: string } | { ok: false, value: string, error: string }}
  *   `ok:false` carries the offending value and a human-actionable error naming
  *   the accepted types — the caller exits non-zero and prints `error`.
  */
-export function resolveAgentType(flags, env) {
+export function resolveAgentType(flags, env, deps = {}) {
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+
+  const fromFile = () => {
+    const file = readJson(loginPath);
+    return file ? nonEmpty(file.agent) : undefined;
+  };
+
   const raw =
-    (typeof flags.agent === "string" && flags.agent.trim()) ||
-    (typeof env.CHORUS_AGENT === "string" && env.CHORUS_AGENT.trim()) ||
+    nonEmpty(flags.agent) ||
+    nonEmpty(env.CHORUS_AGENT) ||
+    fromFile() ||
     DEFAULT_AGENT;
   if (!KNOWN_AGENTS.includes(raw)) {
     return {

package/cli/daemon-install-config.mjs

@@ -26,6 +26,11 @@ import { resolveCredentials, loginFilePath } from "./credentials.mjs";
 import { updateDaemonConfig, prompt as defaultPrompt } from "./login.mjs";
 import { validateAndFetchIdentity } from "./chorus-client.mjs";
 import { normalizeCwd, cleanCwdList } from "./daemon-config.mjs";
+import { KNOWN_AGENTS, DEFAULT_AGENT } from "./daemon-agent.mjs";
+import { agentNotFoundWarningLine } from "./daemon-banner.mjs";
+import { resolveClaudePath } from "./claude-spawner.mjs";
+import { resolveCodexPath } from "./codex-spawner.mjs";
+import { resolveKiroPath } from "./kiro-spawner.mjs";
 import { readFileSync } from "node:fs";
 
 /** A non-empty trimmed string, or undefined. */
@@ -211,3 +216,127 @@ export async function resolveInstallCwds(flags = {}, opts = {}) {
   if (finalCwds.length > 0) writeConfig({ cwds: finalCwds });
   return { cwds: finalCwds };
 }
+
+/**
+ * The interactive agent-backend menu. Order mirrors KNOWN_AGENTS with claude-code
+ * first (it is the default). Kept beside the resolver so the numbered prompt and
+ * the accepted values never drift.
+ */
+const AGENT_MENU = [
+  { value: "claude-code", label: "Claude Code (default)" },
+  { value: "codex", label: "Codex CLI" },
+  { value: "kiro", label: "Kiro CLI" },
+];
+
+/** Probe the selected backend's CLI on PATH. Returns the resolved path or null.
+ * Injectable per backend so the check is testable without a real PATH. */
+function probeAgentCli(agent, probes = {}) {
+  const findClaude = probes.resolveClaudePath ?? resolveClaudePath;
+  const findCodex = probes.resolveCodexPath ?? resolveCodexPath;
+  const findKiro = probes.resolveKiroPath ?? resolveKiroPath;
+  if (agent === "codex") return findCodex();
+  if (agent === "kiro") return findKiro();
+  return findClaude();
+}
+
+/**
+ * Determine which local agent backend the installed daemon wakes and persist it
+ * to ~/.chorus/daemon.json `agent` (the single source of truth — the unit carries
+ * no --agent, exactly like `cwds`). AFTER resolving, probe the selected backend's
+ * CLI on PATH and warn (non-fatal) when it is missing, so the operator learns at
+ * install time rather than when the first wake fails.
+ *
+ * Resolution (first defined source wins):
+ *   1. --agent flag        — the operator's explicit choice.
+ *   2. CHORUS_AGENT env     — matches the daemon's own resolution precedence.
+ *   3. existing daemon.json `agent` — a prior valid choice is kept (re-install is
+ *      idempotent and does not re-prompt); an invalid stored value is ignored.
+ *   4. TTY + !skip         — interactive numbered menu (Enter = claude-code default).
+ *   5. non-TTY / skip      — DEFAULT_AGENT (claude-code), persisted so the config
+ *      is explicit about the backend the boot service runs.
+ *
+ * Never fails: --agent / CHORUS_AGENT are already validated upstream by
+ * resolveAgentType (runDaemon rejects an unknown value before dispatch), the menu
+ * is constrained to KNOWN_AGENTS, and default/stored-invalid fall back to
+ * claude-code. Returns the resolved `{ agent, cliPath, cliFound }`. Never throws.
+ *
+ * @param {{ agent?: string }} flags
+ * @param {Record<string, string|undefined>} [env]
+ * @param {{
+ *   isTTY?: boolean, skip?: boolean,
+ *   readJson?: (path: string) => (Record<string, unknown>|null),
+ *   loginPath?: string,
+ *   writeConfig?: (partial: Record<string, unknown>) => string,
+ *   prompt?: typeof defaultPrompt,
+ *   probes?: { resolveClaudePath?: Function, resolveCodexPath?: Function, resolveKiroPath?: Function },
+ *   log?: (m: string) => void,
+ *   errLog?: (m: string) => void,
+ * }} [opts]
+ * @returns {Promise<{ agent: string, cliPath: string|null, cliFound: boolean }>}
+ */
+export async function resolveInstallAgent(flags = {}, env = {}, opts = {}) {
+  const isTTY = opts.isTTY ?? false;
+  const skip = opts.skip ?? false;
+  const readJson = opts.readJson ?? readJsonSafe;
+  const loginPath = opts.loginPath ?? loginFilePath();
+  const writeConfig = opts.writeConfig ?? updateDaemonConfig;
+  const ask = opts.prompt ?? defaultPrompt;
+  const log = opts.log ?? (() => {});
+  const errLog = opts.errLog ?? (() => {});
+
+  // Only a KNOWN backend is ever accepted; anything else is treated as absent.
+  const known = (v) => (v && KNOWN_AGENTS.includes(v) ? v : undefined);
+
+  let agent;
+  let persist = true; // write unless we reuse an already-stored value (no-op)
+
+  // 1/2. Explicit --agent flag or CHORUS_AGENT env (both pre-validated upstream).
+  agent = known(nonEmpty(flags.agent)) ?? known(nonEmpty(env.CHORUS_AGENT));
+
+  // 3. Existing daemon.json `agent` — a prior valid choice is authoritative; keep
+  //    it and do not re-prompt (re-install stays idempotent). Skip the re-write.
+  if (!agent) {
+    const file = readJson(loginPath);
+    const stored = known(file ? nonEmpty(file.agent) : undefined);
+    if (stored) {
+      agent = stored;
+      persist = false; // already on disk — no-op write avoided
+    }
+  }
+
+  // 4. Interactive numbered menu on a TTY (Enter accepts the claude-code default).
+  if (!agent && isTTY && !skip) {
+    log("[Chorus] Which local agent backend should this daemon wake?");
+    for (let i = 0; i < AGENT_MENU.length; i += 1) {
+      log(`[Chorus]   ${i + 1}) ${AGENT_MENU[i].label}`);
+    }
+    const answer = nonEmpty(await ask(`Select [1-${AGENT_MENU.length}] (Enter for 1): `));
+    if (!answer) {
+      agent = DEFAULT_AGENT;
+    } else {
+      const n = Number(answer);
+      const byNumber = Number.isInteger(n) && n >= 1 && n <= AGENT_MENU.length ? AGENT_MENU[n - 1].value : undefined;
+      // Also accept the value typed by name (e.g. "codex") for muscle memory.
+      agent = byNumber ?? known(answer) ?? DEFAULT_AGENT;
+    }
+  }
+
+  // 5. Non-TTY / skip with nothing configured → the default, persisted so the boot
+  //    service config is explicit about the backend it runs.
+  if (!agent) agent = DEFAULT_AGENT;
+
+  if (persist) writeConfig({ agent });
+
+  // Probe the selected backend's CLI (non-fatal). A missing binary warns loudly so
+  // the operator fixes PATH before the first wake, but never blocks the install.
+  const cliPath = probeAgentCli(agent, opts.probes);
+  const cliFound = cliPath !== null;
+  if (cliFound) {
+    log(`[Chorus] agent backend: ${agent} (found CLI at ${cliPath}).`);
+  } else {
+    log(`[Chorus] agent backend: ${agent}.`);
+    errLog(`[Chorus] ${agentNotFoundWarningLine(agent)}`);
+  }
+
+  return { agent, cliPath, cliFound };
+}

package/cli/daemon-rest-client.mjs

@@ -16,6 +16,8 @@
 //                                                       startedAt|null }] }
 //   reportInterrupt  → POST /api/daemon/report-interrupt
 //                      { connectionUuid, entityType, entityUuid, reason }
+//   heartbeat        → POST /api/daemon/connection-heartbeat
+//                      { connectionUuid, connectedAt }
 //   readPendingTurns → GET  /api/daemon/pending-turns?connectionUuid=…
 //                      → { turns: [{ turnUuid, sessionId, directIdeaUuid, trigger,
 //                                    promptText }] }
@@ -72,6 +74,7 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *   transcript: (p: { sessionId: string, messages: Array<{ role: string, text: string }> }) => Promise<DaemonRestResult>,
  *   executionState: (p: { executions: Array<Record<string, unknown>> }) => Promise<DaemonRestResult>,
  *   reportInterrupt: (p: { entityType: string, entityUuid: string, reason: string }) => Promise<DaemonRestResult>,
+ *   heartbeat: (p: { connectionUuid: string, connectedAt: string }) => Promise<DaemonRestResult>,
  *   readPendingTurns: () => Promise<DaemonRestResult>,
  * }}
  */
@@ -136,16 +139,25 @@ export function createDaemonRestClient(opts) {
      * server resolves the turn by the session BUSINESS KEY (`sessionId`); the optional
      * `entityType`/`entityUuid` stamp the weak executionUuid link. An `interrupted`
      * status may carry `interruptedReason` (`user`/`crash`/`shutdown` — the server
-     * rejects `offline`, which is its own reconcile verdict). Requires the
-     * connectionUuid (the server addresses the turn against a connection the agent owns).
+     * rejects `offline`, which is its own reconcile verdict). A terminal edge may also
+     * carry `transcriptRelayError` — the daemon-known reason its transcript upload
+     * finally failed (fix #444 follow-up), persisted as a turn annotation — and `usage`,
+     * the whole normalized per-turn TokenUsage object (daemon-token-usage), persisted as
+     * the turn's usage. Both ride the terminal edge only. Requires the connectionUuid (the
+     * server addresses the turn against a connection the agent owns).
      */
-    async turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason }) {
+    async turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason, transcriptRelayError, usage }) {
       const connectionUuid = getConnectionUuid();
       if (!connectionUuid) {
         const error = `cannot advance turn for session ${sessionId} → ${status} — no connection uuid yet`;
         logger.warn(`[Chorus] ${error}`);
         return { ok: false, status: null, error, skipped: true };
       }
+      // Per-turn token usage (daemon-token-usage) is meaningful only on a TERMINAL edge —
+      // the daemon knows it at subprocess exit, exactly like transcriptRelayError. Guard on
+      // the terminal status here so a stray usage on → running is never sent (the server
+      // ignores it there anyway; this keeps the wire honest).
+      const isTerminal = status === "ended" || status === "interrupted";
       const body = {
         connectionUuid,
         sessionId,
@@ -154,6 +166,11 @@ export function createDaemonRestClient(opts) {
         ...(entityType && entityUuid ? { entityType, entityUuid } : {}),
         // Only meaningful alongside status=interrupted; never sent otherwise.
         ...(status === "interrupted" && interruptedReason ? { interruptedReason } : {}),
+        // Transcript-relay failure annotation (fix #444 follow-up): only sent when the
+        // daemon actually knows the upload failed (a truthy reason on a terminal edge).
+        ...(transcriptRelayError ? { transcriptRelayError } : {}),
+        // The whole normalized TokenUsage object, nested under `usage`, only on a terminal edge.
+        ...(usage && isTerminal ? { usage } : {}),
       };
       return post(
         "turn-advance",
@@ -223,6 +240,20 @@ export function createDaemonRestClient(opts) {
       );
     },
 
+    /**
+     * POST /api/daemon/connection-heartbeat — acknowledge receipt of one SSE heartbeat.
+     * The values come directly from the active stream's registration handshake; unlike
+     * other connection-scoped operations this must not resolve the uuid lazily, because
+     * a delayed acknowledgment must retain its original generation fence.
+     */
+    async heartbeat({ connectionUuid, connectedAt }) {
+      return post(
+        "connection-heartbeat",
+        "/api/daemon/connection-heartbeat",
+        { connectionUuid, connectedAt },
+      );
+    },
+
     /**
      * GET /api/daemon/pending-turns?connectionUuid=… — read this connection's unstarted
      * (pending) turns from the turn table (the reconnect-backfill / deliver_turn source).

package/cli/daemon.mjs

@@ -17,6 +17,7 @@ import { prompt, writeLoginFile, updateDaemonConfig } from "./login.mjs";
 import {
   resolveInstallCredentials,
   resolveInstallCwds,
+  resolveInstallAgent,
 } from "./daemon-install-config.mjs";
 import {
   resolvePermissionMode,
@@ -43,6 +44,7 @@ import {
 import { WAKE_ACTIONS } from "./prompts.mjs";
 import { createInterruptReporter } from "./interrupt-reporter.mjs";
 import { createTurnReporter } from "./turn-reporter.mjs";
+import { createDaemonRestClient } from "./daemon-rest-client.mjs";
 import { createControlHandler } from "./control-handler.mjs";
 import { resolveSigintTimeoutMs, resolveDaemonCwds } from "./daemon-config.mjs";
 import {
@@ -205,6 +207,13 @@ export function buildDaemon(creds, deps = {}) {
     // doesn't matter. Per-connection so each path's wakes report against the right row.
     /** @type {{ connectionUuid: string|null }} */
     const connectionState = { connectionUuid: null };
+    const daemonRestClient = createDaemonRestClient({
+      url: creds.url,
+      apiKey: creds.apiKey,
+      getConnectionUuid: () => connectionState.connectionUuid,
+      logger,
+      fetchImpl: deps.fetchImpl,
+    });
 
     // Per-connection terminal-outcome bookkeeping (add-daemon-connection-conflict-skip).
     // `resolved` guards recordConnectionOutcome against double-counting a reconnect's
@@ -389,6 +398,7 @@ export function buildDaemon(creds, deps = {}) {
           recordConnectionOutcome(outcome, false);
         },
         onControl,
+        acknowledgeHeartbeat: (registration) => daemonRestClient.heartbeat(registration),
         onReconnect: backfill,
         logger,
       });
@@ -768,6 +778,7 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
     const installCfg = svc.installConfig ?? {
       resolveInstallCredentials,
       resolveInstallCwds,
+      resolveInstallAgent,
     };
 
     const credResult = await installCfg.resolveInstallCredentials(flags, env, {
@@ -801,10 +812,30 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
       log,
     });
 
+    // Configure + persist the agent backend to daemon.json `agent` (single source
+    // of truth; the unit carries no --agent, exactly like --cwd). Prompts an
+    // interactive menu on a TTY (Enter = claude-code); reuses a --agent flag /
+    // CHORUS_AGENT env / a prior stored choice; probes the selected CLI and warns
+    // (non-fatal) when it is missing. An unknown --agent was already rejected by
+    // resolveAgentType above, so this phase never fails.
+    await installCfg.resolveInstallAgent(flags, env, {
+      isTTY,
+      skip,
+      writeConfig: pfDeps?.writeConfig ?? updateDaemonConfig,
+      readJson: pfDeps?.readJson,
+      loginPath: pfDeps?.loginPath,
+      prompt: pfDeps?.askPrompt,
+      log,
+      errLog,
+    });
+
     const spec = {
       ...svc.resolveServicePaths(),
       cwds: flags.cwd ?? [],
-      agent: flags.agent,
+      // NOTE: agent is deliberately NOT passed into the unit. The selected backend
+      // is persisted to daemon.json `agent` (single source of truth) and read back
+      // by the daemon via resolveAgentType — mirroring how --cwd is handled. Baking
+      // --agent into ExecStart too would let the two sources drift.
       chorusOnly: flags.chorusOnly === true,
       workingDir: process.cwd(),
     };