@chorus-aidlc/chorus 0.17.3 → 0.18.1

package/cli/codex-spawner.mjs

@@ -27,10 +27,13 @@
 // stream parse) and the PATH-walk shape of resolveClaudePath.
 
 import { spawn } from "node:child_process";
+import { safeSpawnError } from "./launch-diagnostics.mjs";
+import { validateAgentCliConfig, overlayAgentEnv, getAgentEnv, assertConfiguredShimArgs } from "./agent-cli-config.mjs";
 import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, win32 as pathWin32, posix as pathPosix } from "node:path";
 import { parseNdjsonChunk } from "./claude-spawner.mjs";
+import { awaitChildSettled } from "./child-exit.mjs";
 import { getThreadId as defaultGetThreadId, setThreadId as defaultSetThreadId } from "./codex-session-map.mjs";
 import {
   getCodexUsageSnapshot as defaultGetUsageSnapshot,
@@ -49,8 +52,9 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 export function hasChorusMcpServer(deps = {}) {
   const env = deps.env ?? process.env;
   const readFile = deps.readFile ?? readFileSync;
-  const home = deps.home ?? homedir();
-  const configPath = join(env.CODEX_HOME || join(home, ".codex"), "config.toml");
+  const platform = deps.platform ?? process.platform;
+  const home = deps.home ?? getAgentEnv(env, "HOME", platform) ?? getAgentEnv(env, "USERPROFILE", platform) ?? homedir();
+  const configPath = join(getAgentEnv(env, "CODEX_HOME", platform) || join(home, ".codex"), "config.toml");
   try {
     const config = readFile(configPath, "utf8");
     return /^\s*\[mcp_servers\.chorus\]\s*(?:#.*)?$/m.test(config);
@@ -148,14 +152,15 @@ export function resolveCodexPath(deps = {}) {
       }
     });
 
-  if (env.CHORUS_CODEX_PATH && isFile(env.CHORUS_CODEX_PATH)) {
-    return env.CHORUS_CODEX_PATH;
+  const override = getAgentEnv(env, "CHORUS_CODEX_PATH", platform);
+  if (override && isFile(override)) {
+    return override;
   }
 
   const isWin = platform === "win32";
   const p = isWin ? pathWin32 : pathPosix;
   const names = isWin ? ["codex.cmd", "codex.exe", "codex"] : ["codex"];
-  const pathVar = env.PATH || env.Path || "";
+  const pathVar = getAgentEnv(env, "PATH", platform) || env.Path || "";
   const dirs = pathVar.split(p.delimiter).filter(Boolean);
   for (const dir of dirs) {
     for (const name of names) {
@@ -178,7 +183,7 @@ export function resolveSpawnCommand(codexPath, args, platform = process.platform
   const isWin = platform === "win32";
   const lower = codexPath.toLowerCase();
   if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
-    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    const comspec = getAgentEnv(env, "COMSPEC", platform) || "cmd.exe";
     return { command: comspec, argv: ["/d", "/s", "/c", codexPath, ...args] };
   }
   return { command: codexPath, argv: args };
@@ -210,6 +215,8 @@ export class CodexSpawner {
     this.permissionMode = opts.permissionMode ?? "chorus";
     this.creds = opts.creds ?? null;
     this.platform = opts.platform ?? process.platform;
+    this.cliConfig = validateAgentCliConfig(opts.cliConfig, "codex", opts.label);
+    this.env = overlayAgentEnv(opts.env ?? process.env, this.cliConfig.env, this.platform);
     this.getThreadIdFn = opts.getThreadIdFn ?? defaultGetThreadId;
     this.setThreadIdFn = opts.setThreadIdFn ?? defaultSetThreadId;
     this.getUsageSnapshotFn = opts.getUsageSnapshotFn ?? defaultGetUsageSnapshot;
@@ -246,7 +253,7 @@ export class CodexSpawner {
     // instead of publishing the entire historical cumulative total.
     let needsUsageSeed = Boolean(knownThreadId && !previousUsage);
 
-    const codexPath = this.codexPath ?? this.resolveCodexPathFn();
+    const codexPath = this.codexPath ?? this.resolveCodexPathFn({ env: this.env, platform: this.platform });
     if (!codexPath) {
       // No crash — surface visibly and resolve with a failure result.
       this.logger.error("[Chorus] cannot locate the `codex` executable on PATH; skipping wake");
@@ -255,15 +262,17 @@ export class CodexSpawner {
 
     if (!this.mcpConfigChecked) {
       this.mcpConfigChecked = true;
-      if (!this.hasChorusMcpServerFn()) {
+      if (!this.hasChorusMcpServerFn({ env: this.env, platform: this.platform })) {
         this.logger.warn(
           "[Chorus] Codex config has no [mcp_servers.chorus] entry; wake will continue without Chorus MCP tools",
         );
       }
     }
 
-    const args = buildCodexArgs({ isNew, threadId: knownThreadId, permissionMode: this.permissionMode });
-    const { command, argv } = resolveSpawnCommand(codexPath, args, this.platform);
+    assertConfiguredShimArgs(codexPath, this.cliConfig.args, this.platform);
+    const args = [...buildCodexArgs({ isNew, threadId: knownThreadId, permissionMode: this.permissionMode }), ...this.cliConfig.args,
+      ...(this.cliConfig.args.length ? ["-"] : [])];
+    const { command, argv } = resolveSpawnCommand(codexPath, args, this.platform, this.env);
 
     // POSIX: detached process group so the interrupt path can group-kill the tree
     // (codex exec forks child shells for tools). Windows uses taskkill /T. stdio
@@ -273,7 +282,7 @@ export class CodexSpawner {
     // Export the daemon's resolved connection pair for both Codex MCP auth and
     // SessionStart hooks. Explicitly overwrite inherited values so the hook and
     // daemon cannot disagree about which Chorus instance this wake belongs to.
-    const childEnv = { ...process.env, CHORUS_DAEMON_HEADLESS: "1" };
+    const childEnv = { ...this.env, CHORUS_DAEMON_HEADLESS: "1" };
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
@@ -294,8 +303,8 @@ export class CodexSpawner {
           detached,
           windowsHide: true,
         });
-      } catch (err) {
-        this.logger.error(`[Chorus] failed to spawn codex: ${err}`);
+      } catch (error) {
+        this.logger.error(`[Chorus] failed to spawn codex: ${safeSpawnError(error)}`);
         resolve({ sessionId: anchor, backendSessionId: knownThreadId, exitCode: null, isNew });
         return;
       }
@@ -357,12 +366,14 @@ export class CodexSpawner {
         if (text) this.logger.warn(`[Chorus] codex stderr: ${text}`);
       });
 
-      child.on("error", (err) => {
-        this.logger.error(`[Chorus] codex process error: ${err}`);
+      child.on("error", (error) => {
+        this.logger.error(`[Chorus] codex process error: ${safeSpawnError(error)}`);
         resolve({ sessionId: anchor, backendSessionId: observedThreadId, exitCode: null, isNew });
       });
 
-      child.on("close", (code) => {
+      // Settle on process exit, not only on stdio close: a detached descendant can
+      // inherit the pipes and keep `close` from ever firing (see cli/child-exit.mjs).
+      awaitChildSettled(child, { logger: this.logger, label: "codex" }).then((code) => {
         if (code !== 0) {
           this.logger.warn(`[Chorus] codex exited with code ${code}`);
         }

package/cli/control-handler.mjs

@@ -12,6 +12,17 @@
 // so a stale / recycled connection uuid can never make the daemon kill the wrong
 // subprocess (Tech Design "Risks": mis-kill after a reconnect).
 //
+// When Check-2 fails for an `interrupt` (no live child here) the command is NOT
+// silently dropped (fix-phantom-running-turn, Tech Design "D — a no-child interrupt
+// reports the truth"): the handler logs the miss AND fire-and-forgets one
+// `advanceTurn({ status: "interrupted", interruptedReason: "user" })` so a server-side
+// `running` turn with no daemon child behind it converges instead of hanging forever.
+// The session business key is derived without any lookup, and therefore only for the
+// two control entity types where the derivation is an identity (`idea`,
+// `daemon_session` → sessionId === entityUuid). `task` / `proposal` / `document` keep
+// the pure-log behaviour: their session is anchored on the resource's DIRECT idea,
+// which the daemon cannot resolve locally, and guessing would converge the wrong turn.
+//
 // On a verified match it (a) sets a per-entity "interrupting" flag on the waker so
 // the waker reports the resulting exit as interrupted(reason="user") rather than a
 // crash, then (b) invokes the injected killer (process-killer.killProcessTree) on
@@ -25,6 +36,16 @@ import { killProcessTree } from "./process-killer.mjs";
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
+/**
+ * Control entity types whose session business key is the entityUuid itself, so a
+ * no-child interrupt can report the turn terminal WITHOUT any REST lookup:
+ *   • `idea`           — the session anchor IS the direct idea uuid.
+ *   • `daemon_session` — the ad-hoc session's own business id.
+ * Every other member of CONTROL_ENTITY_TYPES (`task`, `proposal`, `document`) is
+ * anchored on that resource's DIRECT idea, which is not derivable locally.
+ */
+const SELF_ANCHORED_ENTITY_TYPES = new Set(["idea", "daemon_session"]);
+
 /**
  * Build the `onControl(event)` callback the SseListener invokes for a
  * `type:"control"` event.
@@ -56,6 +77,15 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *                                            other still-pending turn along. Injected by the
  *                                            daemon (`backfill.pendingTurnsOnly`); the
  *                                            arg-less form (reconnect) still sweeps all.
+ *   advanceTurn?: (params: { sessionId: string, status: string, interruptedReason?: string,
+ *                            entityType?: string|null, entityUuid?: string|null }) => any,
+ *                                            The SAME `createTurnReporter(...)` instance the
+ *                                            waker uses (injected by `cli/daemon.mjs`; no
+ *                                            second transport, no new endpoint). Invoked
+ *                                            fire-and-forget ONLY when an `interrupt` finds no
+ *                                            live child for a self-anchored entity type, to
+ *                                            close a server-side `running` turn that nothing
+ *                                            else would ever close.
  *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
  * }} deps
  * @returns {(event: any) => void}  The onControl callback (synchronous, non-throwing).
@@ -67,6 +97,7 @@ export function createControlHandler(deps) {
   const sigintTimeoutMs = deps.sigintTimeoutMs;
   const redispatchResume = deps.redispatchResume;
   const deliverTurn = deps.deliverTurn;
+  const advanceTurn = deps.advanceTurn;
   const handleDirectoryRequest = deps.handleDirectoryRequest;
   const reportDirectoryRequest = deps.reportDirectoryRequest;
   const logger = deps.logger ?? NOOP_LOGGER;
@@ -202,11 +233,76 @@ export function createControlHandler(deps) {
       }
 
       // --- interrupt path: Check 2 — in-memory entity ownership (running child) ---
+      //
+      // The registry is keyed by the WAKE's own resource (`task:T`), while a
+      // conversation's control key is its session anchor (`idea:A`). A wake on a CHILD
+      // resource of idea A runs on session A (waker: `sessionId = directIdeaUuid`), so an
+      // `idea:A` interrupt must also find a running `task:T` / `proposal:P` / `document:D`
+      // entry whose `directIdeaUuid` is A — the same rule the UI's `executionMatchesSession`
+      // applies. Without this the exact-key lookup misses, we report a turn miss, the
+      // server's FIFO resolution grabs the SIBLING wake's `running` turn, and NOTHING is
+      // killed: the UI would say interrupted while the agent keeps working.
       const key = execKey(entityType, entityUuid);
-      const entry = waker?.executions?.get(key);
+      let entry = waker?.executions?.get(key);
+      // The entity the kill actually targets — normally the command's own, but a sibling
+      // wake when the match below re-points it.
+      let killEntityType = entityType;
+      let killEntityUuid = entityUuid;
+      let killKey = key;
+      if ((!entry || entry.status !== "running" || !entry.child) && entityType === "idea") {
+        for (const candidate of waker?.executions?.values() ?? []) {
+          if (
+            candidate.status === "running" &&
+            candidate.child &&
+            candidate.directIdeaUuid === entityUuid
+          ) {
+            killEntityType = candidate.entityType;
+            killEntityUuid = candidate.entityUuid;
+            killKey = execKey(killEntityType, killEntityUuid);
+            logger.info(
+              `[Chorus] control: no direct child for ${key}, but sibling wake ${killKey} ` +
+                `runs on this session; interrupting that instead`
+            );
+            entry = candidate;
+            break;
+          }
+        }
+      }
       if (!entry || entry.status !== "running" || !entry.child) {
         // Either we never ran this entity, it's only queued (no child yet), or the
-        // wake already finished (race: interrupt arrived after exit). Safe no-op.
+        // wake already finished (race: interrupt arrived after exit). There is nothing
+        // to kill — but the SERVER may still hold a `running` turn for this session
+        // that nothing else will ever close (the phantom-running-turn bug). Report it
+        // terminal so the UI converges. Only for the self-anchored entity types; for
+        // the rest we cannot know the session locally, so keep the old pure log.
+        if (SELF_ANCHORED_ENTITY_TYPES.has(entityType)) {
+          logger.info(
+            `[Chorus] control: no running subprocess for ${key} on this daemon; ` +
+              `reporting the turn as interrupted(user)`
+          );
+          // Fire-and-forget: createTurnReporter never throws and logs its own
+          // failures, but guard both the synchronous throw and the rejection so
+          // nothing escapes into the SSE loop. A server with no `running` turn
+          // answers not_found — a harmless no-op (losing race).
+          try {
+            Promise.resolve(
+              advanceTurn?.({
+                sessionId: entityUuid,
+                status: "interrupted",
+                interruptedReason: "user",
+                entityType,
+                entityUuid,
+              })
+            ).catch((err) => {
+              logger.warn(
+                `[Chorus] control: interrupted-turn report rejected for ${key}: ${err}`
+              );
+            });
+          } catch (err) {
+            logger.warn(`[Chorus] control: interrupted-turn report failed for ${key}: ${err}`);
+          }
+          return;
+        }
         logger.info(
           `[Chorus] control: no running subprocess for ${key} on this daemon; ignoring interrupt`
         );
@@ -215,18 +311,20 @@ export function createControlHandler(deps) {
 
       // --- Both checks passed: mark interrupting (so the waker reports reason=user),
       //     then kill the tree. ---
-      logger.info(`[Chorus] control: interrupting running subprocess for ${key} (pid=${entry.child.pid})`);
+      logger.info(`[Chorus] control: interrupting running subprocess for ${killKey} (pid=${entry.child.pid})`);
       try {
-        waker.markInterrupting?.(entityType, entityUuid);
+        // Flag the entity whose wake we are actually killing — a sibling re-point must
+        // mark THAT wake interrupting, or its exit would be reported as a crash.
+        waker.markInterrupting?.(killEntityType, killEntityUuid);
       } catch (err) {
-        logger.warn(`[Chorus] control: markInterrupting failed for ${key}: ${err}`);
+        logger.warn(`[Chorus] control: markInterrupting failed for ${killKey}: ${err}`);
       }
 
       // Fire-and-forget the kill: the waker observes the child's exit and reports
       // the interrupted state. The killer never throws, but guard the promise
       // anyway so a rejection can't surface as an unhandled rejection.
       Promise.resolve(killer(entry.child, { sigintTimeoutMs, logger })).catch((err) => {
-        logger.warn(`[Chorus] control: killProcessTree rejected for ${key}: ${err}`);
+        logger.warn(`[Chorus] control: killProcessTree rejected for ${killKey}: ${err}`);
       });
     } catch (err) {
       // Absolute backstop — a control event must never crash the SSE loop.

package/cli/credentials.mjs

@@ -19,6 +19,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { rejectSharedCliConfig } from "./agent-cli-config.mjs";
 
 /** Absolute path to the login file written by `chorus login`. */
 export function loginFilePath() {
@@ -425,6 +426,7 @@ export function resolveLaunchAgent(flags = {}, deps = {}) {
   const wanted = nonEmpty(flags.name) ?? nonEmpty(flags.agent) ?? nonEmpty(env.CHORUS_AGENT_PROFILE);
 
   const file = readJson(loginPath);
+  rejectSharedCliConfig(file);
   const agentEntries =
     file && Array.isArray(file.agents)
       ? file.agents.filter((a) => a && typeof a === "object")
@@ -448,6 +450,8 @@ export function resolveLaunchAgent(flags = {}, deps = {}) {
     agentUuid: nonEmpty(entry.agentUuid),
     agentName: nonEmpty(entry.agentName) ?? nonEmpty(entry.name),
     agentType: nonEmpty(entry.agentType),
+    args: entry.args,
+    env: entry.env,
   }));
   const labels = resolved.map((a) => a.label).join(", ");
 
@@ -479,6 +483,9 @@ export function resolveLaunchAgent(flags = {}, deps = {}) {
     agentUuid: selected.agentUuid,
     agentName: selected.agentName,
     agentType: selected.agentType,
+    // Validation uses the launcher's effective --type, not the stored classification.
+    args: selected.args,
+    env: selected.env,
     label: selected.label,
   };
 }

package/cli/daemon-config.mjs

@@ -18,6 +18,14 @@ import { isAbsolute, resolve as resolvePath } from "node:path";
 import { loginFilePath, resolveCredentials, resolveCredentialDefaults } from "./credentials.mjs";
 import { resolveAgentType, KNOWN_AGENTS } from "./daemon-agent.mjs";
 import { resolvePermissionMode } from "./daemon-permission-mode.mjs";
+import { rejectSharedCliConfig, validateAgentCliConfig } from "./agent-cli-config.mjs";
+
+/** Read only the flat profile customization; also used by the legacy startup path. */
+export function resolveFlatAgentCliConfig(type, deps = {}) {
+  const file = (deps.readJson ?? readJsonSafe)(deps.loginPath ?? loginFilePath());
+  rejectSharedCliConfig(file);
+  return validateAgentCliConfig(file ?? {}, type, "agent");
+}
 
 /** Built-in default escalation window (ms) — matches the spec's 10 seconds. */
 export const DEFAULT_SIGINT_TIMEOUT_MS = 10_000;
@@ -307,6 +315,8 @@ function positiveInt(value) {
  * @property {string} url                       Chorus server URL for this agent.
  * @property {string} apiKey                    This agent's `cho_` API key.
  * @property {string} agentType                 Backend: claude-code | codex | kiro | dsh | offline.
+ * @property {string[]} args                   Literal extra backend arguments (per-agent only).
+ * @property {Record<string,string>} env       Literal child environment overrides (per-agent only).
  * @property {boolean} [daemonWake]             Wake opt-in for a wakeable backend; only
  *                                              `false` disables (absent/true ⇒ woken).
  * @property {Array<string|undefined>} cwds     Served paths (`undefined` ⇒ process cwd).
@@ -344,6 +354,8 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
   const home = deps.home ?? homedir();
   const file = readJson(loginPath);
 
+  rejectSharedCliConfig(file);
+
   // Global default permission posture; a per-agent `permissionMode` overrides it.
   // needConfirm/hasAck is vestigial, so isTTY/hasAck do not affect the resolved mode.
   const defaultPermissionMode =
@@ -365,6 +377,7 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
         url: creds.url,
         apiKey: creds.apiKey,
         agentType: at.agent,
+        ...validateAgentCliConfig(file ?? {}, at.agent, "agent"),
         cwds: resolveDaemonCwds(flags, deps),
         permissionMode: defaultPermissionMode,
         maxConcurrency: positiveInt(file?.maxConcurrency) ?? DEFAULT_MAX_CONCURRENCY,
@@ -449,6 +462,7 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
       url,
       apiKey,
       agentType,
+      ...validateAgentCliConfig(entry, agentType, label),
       cwds,
       permissionMode,
       maxConcurrency,

package/cli/daemon-rest-client.mjs

@@ -40,6 +40,26 @@
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
+// Bounded retry policy for the TERMINAL turn-advance edge only (fix-phantom-running-turn).
+// A lost terminal report is the one failure that leaves a permanently phantom `running`
+// turn, so it — and only it — is worth retrying. Fixed constants on purpose: one more
+// configuration knob buys nothing here.
+const TERMINAL_TURN_ADVANCE_ATTEMPTS = 3;
+const TERMINAL_TURN_ADVANCE_DELAYS_MS = [500, 2000];
+
+/** Real-time delay; tests inject their own so they never sleep for real. */
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * A failure is retryable when repeating it can plausibly succeed: a network-level failure
+ * (no HTTP response at all), a `429`, or any `5xx`. Every `4xx` is a server VERDICT
+ * (invalid_transition, not_found, auth) — repeating it cannot make it true.
+ * @param {number|null} status
+ */
+function isRetryableFailure(status) {
+  return status === null || status === 429 || status >= 500;
+}
+
 /**
  * @typedef {Object} DaemonRestResult
  * @property {boolean} ok           True only on a 2xx response (and, for reads, a
@@ -70,6 +90,8 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *                                         executionState, reportInterrupt, readPendingTurns)
  *                                         require it; a null value skips the call (logged).
  *   fetchImpl?: typeof fetch,             Injectable for tests (defaults to global fetch).
+ *   sleep?: (ms: number) => Promise<void>, Injectable retry delay (defaults to setTimeout).
+ *                                         Only the terminal turn-advance edge retries.
  *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
  * }} opts
  * @returns {{
@@ -88,6 +110,8 @@ export function createDaemonRestClient(opts) {
   const getConnectionUuid = opts.getConnectionUuid ?? (() => null);
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   const logger = opts.logger ?? NOOP_LOGGER;
+  // Injectable retry delay so tests assert the schedule without spending real seconds.
+  const sleepImpl = opts.sleep ?? realSleep;
 
   const jsonHeaders = {
     Authorization: `Bearer ${apiKey}`,
@@ -111,41 +135,71 @@ export function createDaemonRestClient(opts) {
    *                         `<op> request failed` / `<op> returned <status>` core, so the
    *                         failing entity stays visible in the log without disturbing the
    *                         established op-prefixed message.
+   * @param {boolean} [readData]   Parse the response envelope's `data` on success.
+   * @param {{ attempts: number, delaysMs: number[], sleep?: (ms: number) => Promise<void> }|null} [retry]
+   *                         Optional bounded retry policy. Absent/null = today's exact
+   *                         single-shot behaviour (used by every op but the terminal
+   *                         turn-advance edge).
    * @returns {Promise<DaemonRestResult>}
    */
-  async function post(op, path, body, successLog, context = "", readData = false) {
-    let response;
-    try {
-      response = await fetchImpl(`${url}${path}`, {
-        method: "POST",
-        headers: jsonHeaders,
-        body: JSON.stringify(body),
-      });
-    } catch (err) {
-      // Network-level failure (DNS, connection refused, abort, …). Surface WITH cause.
-      const error = `${op} request failed${context}: ${err}`;
-      logger.warn(`[Chorus] ${error}`);
-      return { ok: false, status: null, error };
-    }
-    if (!response.ok) {
-      // Non-2xx. Surface WITH the status so a 4xx/5xx is debuggable.
-      const error = `${op} returned ${response.status}${context}`;
-      logger.warn(`[Chorus] ${error}`);
-      return { ok: false, status: response.status, error };
-    }
-    let data;
-    if (readData) {
+  async function post(op, path, body, successLog, context = "", readData = false, retry = null) {
+    const attempts = retry ? retry.attempts : 1;
+    const delaysMs = retry?.delaysMs ?? [];
+    // Named distinctly from the module-closure `sleepImpl` so this local never reads as a
+    // shadow: callers with a retry policy pass their own sleep explicitly.
+    const retrySleep = retry?.sleep ?? realSleep;
+
+    let failure;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      failure = undefined;
+      let response;
       try {
-        const parsed = await response.json();
-        data = parsed && typeof parsed === "object" ? parsed.data : undefined;
+        response = await fetchImpl(`${url}${path}`, {
+          method: "POST",
+          headers: jsonHeaders,
+          body: JSON.stringify(body),
+        });
       } catch (err) {
-        // Mixed-version fallback: older servers may return an empty successful body.
-        // Keep the lifecycle report successful, but make the missing correlation visible.
-        logger.warn(`[Chorus] ${op} response correlation unavailable: ${err}`);
+        // Network-level failure (DNS, connection refused, abort, …). Surface WITH cause.
+        // `head`/`tail` are split so the attempt ordinal can be injected before the cause.
+        failure = { status: null, head: `${op} request failed${context}`, tail: `: ${err}` };
+      }
+      if (!failure && !response.ok) {
+        // Non-2xx. Surface WITH the status so a 4xx/5xx is debuggable.
+        failure = { status: response.status, head: `${op} returned ${response.status}${context}`, tail: "" };
       }
+      if (!failure) {
+        let data;
+        if (readData) {
+          try {
+            const parsed = await response.json();
+            data = parsed && typeof parsed === "object" ? parsed.data : undefined;
+          } catch (err) {
+            // Mixed-version fallback: older servers may return an empty successful body.
+            // Keep the lifecycle report successful, but make the missing correlation visible.
+            logger.warn(`[Chorus] ${op} response correlation unavailable: ${err}`);
+          }
+        }
+        if (successLog) logger.info(`[Chorus] ${successLog}`);
+        return { ok: true, status: response.status, ...(data !== undefined ? { data } : {}) };
+      }
+
+      const canRetry = attempt < attempts && isRetryableFailure(failure.status);
+      // Per-attempt visibility, but ONLY when another attempt actually follows: the ordinal
+      // exists to explain a retry. A single-shot op, or a terminal failure that will be
+      // re-logged verbatim two lines below, must not emit a redundant ordinal line.
+      if (canRetry) {
+        logger.warn(`[Chorus] ${failure.head} (attempt ${attempt}/${attempts})${failure.tail}`);
+      }
+      if (!canRetry) break;
+      await retrySleep(delaysMs[attempt - 1] ?? delaysMs[delaysMs.length - 1] ?? 0);
     }
-    if (successLog) logger.info(`[Chorus] ${successLog}`);
-    return { ok: true, status: response.status, ...(data !== undefined ? { data } : {}) };
+
+    // Final failure: the message and the structured result are EXACTLY what they were
+    // before retries existed, so existing log-grep expectations still match.
+    const error = `${failure.head}${failure.tail}`;
+    logger.warn(`[Chorus] ${error}`);
+    return { ok: false, status: failure.status, error };
   }
 
   return {
@@ -203,6 +257,21 @@ export function createDaemonRestClient(opts) {
         `advanced turn for session ${sessionId} → ${status}`,
         "",
         status === "running",
+        // Bounded retry on the TERMINAL edge only. A lost `→ ended`/`→ interrupted` report
+        // is what strands a turn as phantom `running` forever; the `→ running` edge is not
+        // retried because the wake is about to run anyway and a stale retry could race the
+        // terminal edge. The repeat is safe: the daemon sends the `turnUuid` it learned
+        // from its own → running report, and advanceTurnForWake returns the existing
+        // projection for a same-turn same-terminal-status replay (no second usage rollup,
+        // timestamp write or SSE publish). Without a turnUuid, the FIFO lookup finds no
+        // `running` turn and answers not_found, changing nothing.
+        isTerminal
+          ? {
+              attempts: TERMINAL_TURN_ADVANCE_ATTEMPTS,
+              delaysMs: TERMINAL_TURN_ADVANCE_DELAYS_MS,
+              sleep: sleepImpl,
+            }
+          : null,
       );
       const resolvedTurnUuid =
         typeof result.data?.turn?.uuid === "string" ? result.data.turn.uuid : null;