@chorus-aidlc/chorus 0.16.3 → 0.17.0

package/cli/credentials.mjs

@@ -159,13 +159,26 @@ export function resolveCredentials(flags = {}, deps = {}) {
     if (url && apiKey) return { url, apiKey, source: "env" };
   }
 
-  // 3. Login file (~/.chorus/daemon.json)
+  // 3. Login file (~/.chorus/daemon.json): the flat top-level url/apiKey, else the
+  //    first agents[] entry. The flat top-level agent config is DEPRECATED — `chorus
+  //    init` now writes credentials only into agents[] — so fall back to agents[0]
+  //    so this single-credential resolver (install/daemon-setup gate, legacy flat
+  //    daemon) still resolves from an agents[]-only daemon.json.
   tried.push(`login file (${loginPath}, run \`chorus login\`)`);
   {
     const file = readJson(loginPath);
     if (file) {
-      const url = nonEmpty(file.url);
-      const apiKey = nonEmpty(file.apiKey);
+      let url = nonEmpty(file.url);
+      let apiKey = nonEmpty(file.apiKey);
+      if (!(url && apiKey) && Array.isArray(file.agents)) {
+        const a0 = file.agents.find(
+          (a) => a && typeof a === "object" && nonEmpty(a.url) && nonEmpty(a.apiKey),
+        );
+        if (a0) {
+          url = nonEmpty(a0.url);
+          apiKey = nonEmpty(a0.apiKey);
+        }
+      }
       if (url && apiKey) return { url, apiKey, source: "login-file" };
     }
   }
@@ -194,3 +207,172 @@ export function resolveCredentials(flags = {}, deps = {}) {
       "  • login:   chorus login   (persists to ~/.chorus/daemon.json)\n"
   );
 }
+
+/**
+ * @typedef {Object} McpCredentials
+ * @property {string} url
+ * @property {string} apiKey
+ * @property {string} label  Diagnostic label for the acting identity ("flag" /
+ *   "env" / a `~/.chorus/daemon.json` agent name/label / the flat-resolution source).
+ */
+
+/**
+ * Resolve the url + `cho_` API key AND the acting agent identity for the
+ * `chorus mcp` command group. Unlike `resolveCredentials`, this understands the
+ * multi-agent `agents[]` model and refuses to guess which agent to act as.
+ *
+ * PROFILE identity (AWS-CLI style): a caller can name WHICH agent to act as by
+ * `--agent <name|uuid>` (explicit flag) or the `CHORUS_AGENT_PROFILE` env var,
+ * and this resolves that agent's key from `~/.chorus/daemon.json` — the secret
+ * never has to be threaded through the caller's environment. A profile matches
+ * an `agents[]` entry by its `agentUuid`, `agentName`, or the back-compat
+ * `label`/`name` aliases (exact). Ambiguous (matches >1 entry) → hard error.
+ *
+ * Precedence (owner decision: PREFER profile, fall back to url+key mode when no
+ * profile resolves — the key stays written in daemon.json, url+key is the
+ * fallback so the CLI-absent curl path still works):
+ *   1. Explicit `--agent <name|uuid>` flag → deliberate profile selection from
+ *      `agents[]`, PREFERRED over an explicit url+key pair (no match → hard error
+ *      listing agents). With NO `agents[]` it rides along an explicit `--url/--api-key`
+ *      pair (else the env pair) as the label, else it is a usage error.
+ *   2. Explicit `--url` + `--api-key` flags (no `--agent`) → used directly
+ *      (identity is explicit); a `CHORUS_AGENT_PROFILE` name rides along as the label.
+ *   3. `CHORUS_AGENT_PROFILE` env → ambient profile selection from `agents[]`.
+ *      A match wins over the url+key env pair; NO match falls through (the
+ *      profile "doesn't exist" → url-mode fallback), an ambiguous match throws.
+ *   4. `CHORUS_URL` + `CHORUS_API_KEY` env pair → used directly (url-mode
+ *      fallback / legacy plugin-hook path); a profile name rides as the label.
+ *   5. Exactly one agent in `agents[]` + nothing specified → that agent.
+ *   6. More than one agent + nothing specified → hard error (never pick
+ *      silently), listing the available agents.
+ *   7. No `agents[]` → flat resolution via `resolveCredentials`.
+ *
+ * Each selected agent's `url`/`apiKey` merges over the top-level per-field
+ * defaults (`resolveCredentialDefaults`), so an agent that omits a field
+ * inherits it.
+ *
+ * This never imports `cli/daemon-config.mjs` (which imports THIS module) — it
+ * reads `agents[]` directly to stay cycle-free; only url/apiKey/label matter for
+ * MCP, so per-agent agentType/permissionMode validation is intentionally skipped.
+ *
+ * @param {{ url?: string, apiKey?: string, agent?: string }} flags
+ * @param {ResolveDeps} [deps]
+ * @returns {McpCredentials}
+ * @throws {Error} on ambiguity, a missing `--agent` label, or nothing resolvable.
+ */
+export function resolveMcpCredentials(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const flagAgent = nonEmpty(flags.agent);
+  const envProfile = nonEmpty(env.CHORUS_AGENT_PROFILE);
+  // The profile name a caller asked for, whatever its source — used as the
+  // diagnostic label when creds ultimately come from explicit flags / the env pair.
+  const wanted = flagAgent ?? envProfile;
+
+  const envPair = () => {
+    const url = nonEmpty(env.CHORUS_URL);
+    const apiKey = nonEmpty(env.CHORUS_API_KEY);
+    return url && apiKey ? { url, apiKey } : null;
+  };
+  const flagPair = () => {
+    const url = nonEmpty(flags.url);
+    const apiKey = nonEmpty(flags.apiKey);
+    return url && apiKey ? { url, apiKey } : null;
+  };
+
+  // Read agents[] once and pre-resolve every entry (label, its match keys, and
+  // its effective url/apiKey merged over the top-level per-field defaults).
+  const file = readJson(loginPath);
+  const agentEntries =
+    file && Array.isArray(file.agents)
+      ? file.agents.filter((a) => a && typeof a === "object")
+      : [];
+  const hasAgents = agentEntries.length > 0;
+  const defaults = hasAgents ? resolveCredentialDefaults(flags, deps) : { url: undefined, apiKey: undefined };
+  const labelOf = (entry, i) =>
+    nonEmpty(entry.agentName) ?? nonEmpty(entry.label) ?? nonEmpty(entry.name) ?? `agents[${i}]`;
+  const resolved = agentEntries.map((entry, i) => ({
+    label: labelOf(entry, i),
+    // A profile may name an entry by its uuid, its display name, or the
+    // back-compat label/name aliases.
+    keys: [entry.agentUuid, entry.agentName, entry.label, entry.name]
+      .map((k) => nonEmpty(k))
+      .filter((k) => k !== undefined),
+    url: nonEmpty(entry.url) ?? defaults.url,
+    apiKey: nonEmpty(entry.apiKey) ?? defaults.apiKey,
+  }));
+  const labels = resolved.map((a) => a.label).join(", ");
+  const pick = (a) => {
+    if (!a.url || !a.apiKey) {
+      throw new Error(
+        `Agent "${a.label}" in ${loginPath} is missing a url or apiKey (and no top-level default supplies it).`,
+      );
+    }
+    return { url: a.url, apiKey: a.apiKey, label: a.label };
+  };
+  const matchesFor = (name) => resolved.filter((a) => a.keys.includes(name));
+  const selectOrThrow = (name, source) => {
+    const matches = matchesFor(name);
+    if (matches.length === 1) return pick(matches[0]);
+    if (matches.length > 1) {
+      throw new Error(
+        `${source} "${name}" is ambiguous in ${loginPath} — it matches ${matches.length} agents ` +
+          `(${matches.map((m) => m.label).join(", ")}). Use the agent UUID to disambiguate.`,
+      );
+    }
+    return null; // no match
+  };
+
+  // 1. Explicit --agent flag: a deliberate profile selection — PREFERRED over an
+  //    explicit url+key flag pair (owner: "prefer profile"). With NO agents[] to
+  //    match, it rides an explicit flag pair (else the env pair), using the name
+  //    as the diagnostic label; with neither it is a usage error.
+  if (flagAgent) {
+    if (hasAgents) {
+      const hit = selectOrThrow(flagAgent, "--agent");
+      if (hit) return hit;
+      throw new Error(`--agent "${flagAgent}" not found in ${loginPath} agents[]. Available: ${labels}.`);
+    }
+    const pair = flagPair() ?? envPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: flagAgent };
+    throw new Error(
+      `--agent "${flagAgent}" was given but ${loginPath} declares no agents[]. ` +
+        `Remove --agent, or configure an agents[] list.`,
+    );
+  }
+
+  // 2. Explicit url+key flag pair (no --agent) — identity is explicit.
+  {
+    const pair = flagPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: wanted ?? "flag" };
+  }
+
+  // 3. CHORUS_AGENT_PROFILE env: ambient profile selection. A match wins over the
+  //    url+key env pair; a no-match falls through to url-mode (profile "doesn't
+  //    exist"); an ambiguous match throws.
+  if (envProfile && hasAgents) {
+    const hit = selectOrThrow(envProfile, "CHORUS_AGENT_PROFILE");
+    if (hit) return hit;
+    // no match → fall through to the url-mode fallback below
+  }
+
+  // 4. Env pair (url-mode fallback). Carry the profile name as the label if set.
+  {
+    const pair = envPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: wanted ?? "env" };
+  }
+
+  // 5/6. agents[] with nothing specified: auto-single, else hard error.
+  if (hasAgents) {
+    if (resolved.length === 1) return pick(resolved[0]);
+    throw new Error(
+      `Multiple agents are configured in ${loginPath} (${labels}). ` +
+        `Specify which one to act as with --agent <name|uuid> or CHORUS_AGENT_PROFILE.`,
+    );
+  }
+
+  // 7. No agents[] → flat resolution (throws the detailed "could not resolve" error).
+  const flat = resolveCredentials(flags, deps);
+  return { url: flat.url, apiKey: flat.apiKey, label: flat.source };
+}

package/cli/daemon-agent.mjs

@@ -1,6 +1,6 @@
 // cli/daemon-agent.mjs
 // Pure resolution + validation of the daemon's `--agent <type>` selection.
-// `claude-code` (the default), `codex`, and `kiro` are all implemented backends
+// `claude-code` (the default), `codex`, `kiro`, and `dsh` are recognized 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).
@@ -16,10 +16,19 @@
 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
- * spawner-select.mjs). */
-export const KNOWN_AGENTS = ["claude-code", "codex", "kiro"];
+/** The agent backends the daemon recognizes. Existing spawners cover claude-code,
+ * codex, and kiro; dsh registration is the base contract for its bridge.
+ *
+ * `offline` is a NON-wakeable classification, not a real backend: an agent whose
+ * key is parked in daemon.json purely so `chorus mcp` can proxy through it, while
+ * the daemon builds NO spawner and dispatches NO wake for it. It is accepted here
+ * (and by-name in agent-backend-prompt via this list) so an agents[] entry may set
+ * `agentType: "offline"` and pass resolveAgentConfigs' KNOWN_AGENTS validation. The
+ * fail-closed no-wake handling lives in spawner-select.mjs (selectSpawner returns
+ * an OfflineSpawner that refuses to spawn) — an offline value MUST NOT fall through
+ * to the claude-code default and wake it. `chorus agents add` maps every non-wakeable
+ * selected agent (opencode/openclaw/pi/dsh) to this classification. */
+export const KNOWN_AGENTS = ["claude-code", "codex", "kiro", "dsh", "offline"];
 
 /** The default agent backend when neither --agent nor CHORUS_AGENT is set. */
 export const DEFAULT_AGENT = "claude-code";
@@ -35,6 +44,12 @@ export const DEFAULT_AGENT = "claude-code";
 export function backendCli(agentType) {
   if (agentType === "codex") return { name: "codex", envVar: "CHORUS_CODEX_PATH" };
   if (agentType === "kiro") return { name: "kiro-cli", envVar: "CHORUS_KIRO_PATH" };
+  if (agentType === "dsh") return { name: "dsh-jsonrpc-agent", envVar: "CHORUS_DSH_PATH" };
+  // `offline` has no CLI to resolve — it is never woken (see backendClientType).
+  // The daemon does not probe a binary for it; this explicit descriptor keeps the
+  // return sensible if some banner path ever reads it (CHORUS_AGENT selects the
+  // backend), instead of mislabeling it as `claude`.
+  if (agentType === "offline") return { name: "offline", envVar: "CHORUS_AGENT" };
   return { name: "claude", envVar: "CHORUS_CLAUDE_PATH" };
 }
 
@@ -49,6 +64,16 @@ export function backendCli(agentType) {
 export function backendClientType(agentType) {
   if (agentType === "codex") return "codex";
   if (agentType === "kiro") return "kiro";
+  if (agentType === "dsh") return "dsh";
+  // `offline` is a non-wakeable classification — the daemon SHALL NOT register it
+  // as a wakeable connection (daemon-multi-agent spec). It must therefore NOT
+  // fall through to the `claude_code` default (which would make an offline agent
+  // present as a wakeable claude_code connection). Return the distinct `offline`
+  // string: the runtime fan-out skips registering it at all, and this value is
+  // intentionally OUTSIDE the server's DAEMON_CLIENT_TYPES allowlist, so any
+  // future path that DID try to register it fails closed (server rejects) rather
+  // than silently registering it as claude_code.
+  if (agentType === "offline") return "offline";
   return "claude_code";
 }
 

package/cli/daemon-banner.mjs

@@ -19,7 +19,7 @@ import { backendCli } from "./daemon-agent.mjs";
  * @property {string} agentUuid        authenticated agent uuid.
  * @property {"yolo"|"chorus"} permissionMode
  * @property {string} credentialSource resolved credential source (flag/env/login-file/…).
- * @property {string} agentType        local agent backend (claude-code | codex) — drives the CLI row label.
+ * @property {string} agentType        local agent backend (claude-code | codex | kiro | dsh) — drives the CLI row label.
  * @property {string|null} cliPath     resolved path of the SELECTED backend's CLI, or null when not found.
  * @property {string} [connection]     connection state line (default "connecting…").
  * @property {string} [configPath]     absolute path to the daemon.json the CLI reads.
@@ -42,8 +42,8 @@ export function bannerRows(info) {
     info.permissionMode === "yolo"
       ? "YOLO ⚠  (full autonomy — Bash/write/any command)"
       : "chorus-only (Chorus MCP tools only)";
-  // The CLI row names the SELECTED backend (claude-code → "claude", codex →
-  // "codex") so a `--agent codex` run never mislabels itself as claude.
+  // The CLI row names the selected backend so non-Claude runs are never
+  // mislabeled and their own executable override is actionable.
   const cli = backendCli(info.agentType);
   const cliValue = info.cliPath
     ? `found: ${info.cliPath}`

package/cli/daemon-config.mjs

@@ -306,13 +306,19 @@ function positiveInt(value) {
  * @typedef {Object} AgentConfig  One fully-resolved agent runtime config.
  * @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.
+ * @property {string} agentType                 Backend: claude-code | codex | kiro | dsh | offline.
+ * @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).
  * @property {"yolo"|"chorus"} permissionMode   Woken-agent permission posture.
  * @property {number} maxConcurrency            This agent's wake-queue cap.
  * @property {number} sigintTimeoutMs           Interrupt escalation window (ms).
  * @property {string[]} browseRoots             Directory-discovery allowlist.
  * @property {string} label                     Diagnostic label ("agent" or "agents[i]").
+ * @property {string} [agentUuid]               This agent's Chorus UUID — exported to a
+ *                                              woken session as CHORUS_AGENT_PROFILE so its
+ *                                              hooks/skills resolve the key from daemon.json.
+ * @property {string} [agentName]               This agent's Chorus display name (profile alias).
  */
 
 /**
@@ -365,6 +371,8 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
         sigintTimeoutMs: resolveSigintTimeoutMs(flags, deps),
         browseRoots: resolveBrowseRoots(flags, deps),
         label: "agent",
+        agentUuid: nonEmptyStr(file?.agentUuid),
+        agentName: nonEmptyStr(file?.agentName),
       },
     ];
   }
@@ -433,6 +441,23 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
     const browseRoots =
       entry.browseRoots !== undefined ? cleanCwdList(entry.browseRoots, home) : defaultBrowseRoots;
 
-    return { url, apiKey, agentType, cwds, permissionMode, maxConcurrency, sigintTimeoutMs, browseRoots, label };
+    // daemonWake: per-agent opt-in for daemon waking (pass-through boolean). Only
+    // `=== false` disables waking; absent (undefined) or true ⇒ woken, so agent
+    // entries written before this field existed keep being woken. Orthogonal to
+    // agentType (offline is never woken regardless).
+    return {
+      url,
+      apiKey,
+      agentType,
+      cwds,
+      permissionMode,
+      maxConcurrency,
+      sigintTimeoutMs,
+      browseRoots,
+      daemonWake: entry.daemonWake,
+      label,
+      agentUuid: nonEmptyStr(entry.agentUuid),
+      agentName: nonEmptyStr(entry.agentName),
+    };
   });
 }

package/cli/daemon-install-config.mjs

@@ -27,9 +27,11 @@ import { updateDaemonConfig, appendAgentConfig, prompt as defaultPrompt } from "
 import { validateAndFetchIdentity } from "./chorus-client.mjs";
 import { normalizeCwd, cleanCwdList } from "./daemon-config.mjs";
 import { KNOWN_AGENTS, DEFAULT_AGENT } from "./daemon-agent.mjs";
+import { AGENT_MENU, promptAgentBackend } from "./agent-backend-prompt.mjs";
 import { agentNotFoundWarningLine } from "./daemon-banner.mjs";
 import { resolveClaudePath } from "./claude-spawner.mjs";
 import { resolveCodexPath } from "./codex-spawner.mjs";
+import { resolveDshPath } from "./dsh-spawner.mjs";
 import { resolveKiroPath } from "./kiro-spawner.mjs";
 import { readFileSync } from "node:fs";
 
@@ -160,12 +162,20 @@ export async function resolveInstallCredentials(flags = {}, env = {}, opts = {})
         );
         continue;
       }
-      const res = appendAgent({ url: u, apiKey: k, agentUuid: id.uuid, agentName: id.name });
+      // Which backend for this agent? Explicit --agent wins; otherwise the menu
+      // (we're already on a TTY here). undefined → omit agentType so the entry
+      // inherits the daemon default at resolve time (never a literal claude-code).
+      let at = nonEmpty(flags.agent);
+      if (!at) at = await promptAgentBackend({ ask, log, isTTY });
+      const agentObj = { url: u, apiKey: k, agentUuid: id.uuid, agentName: id.name };
+      if (at) agentObj.agentType = at;
+      const res = appendAgent(agentObj);
       if (!res.ok) {
         errLog(`[Chorus] agent ${id.name} (${id.uuid}) is already configured — skipping.`);
         continue;
       }
-      log(`[Chorus] added agent ${id.name} (${id.uuid}) — this daemon now serves ${res.agents.length} agents.`);
+      const backendNote = at ? ` (backend: ${at})` : "";
+      log(`[Chorus] added agent ${id.name} (${id.uuid})${backendNote} — this daemon now serves ${res.agents.length} agents.`);
     }
   }
 
@@ -242,7 +252,6 @@ export async function resolveInstallCwds(flags = {}, opts = {}) {
   const first = nonEmpty(await ask(`Working directory [${defaultCwd}] (Enter to accept the default): `));
   collected.push(first ?? defaultCwd);
   // subsequent adds
-  // eslint-disable-next-line no-constant-condition
   while (true) {
     const next = nonEmpty(await ask("Add another working directory (blank to finish): "));
     if (!next) break;
@@ -280,25 +289,23 @@ export async function resolveInstallBrowseRoots(flags = {}, opts = {}) {
   return { browseRoots };
 }
 
-/**
- * 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" },
-];
+// The interactive agent-backend menu (`AGENT_MENU`) now lives in
+// ./agent-backend-prompt.mjs as the single source of truth shared with the
+// add/login flows (imported above), so every backend prompt advertises the same
+// list and never drifts. resolveInstallAgent keeps its own inline menu render
+// below (its empty→DEFAULT_AGENT semantics differ from promptAgentBackend's
+// empty→undefined) but reads the same AGENT_MENU rows.
 
 /** 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 findDsh = probes.resolveDshPath ?? resolveDshPath;
   const findKiro = probes.resolveKiroPath ?? resolveKiroPath;
   if (agent === "codex") return findCodex();
   if (agent === "kiro") return findKiro();
+  if (agent === "dsh") return findDsh();
   return findClaude();
 }
 
@@ -331,7 +338,7 @@ function probeAgentCli(agent, probes = {}) {
  *   loginPath?: string,
  *   writeConfig?: (partial: Record<string, unknown>) => string,
  *   prompt?: typeof defaultPrompt,
- *   probes?: { resolveClaudePath?: Function, resolveCodexPath?: Function, resolveKiroPath?: Function },
+ *   probes?: { resolveClaudePath?: Function, resolveCodexPath?: Function, resolveKiroPath?: Function, resolveDshPath?: Function },
  *   log?: (m: string) => void,
  *   errLog?: (m: string) => void,
  * }} [opts]

package/cli/daemon-rest-client.mjs

@@ -4,10 +4,12 @@
 // the existing server endpoints accept, so the two daemon hosts — the chorus CLI daemon
 // (`cli/daemon.mjs`) and the OpenClaw plugin — cannot drift in the wire contract.
 //
-// The five operations and their EXACT server payload shapes (verified against
-// src/app/api/daemon/*/route.ts — the server is NOT changed by this work):
+// The operations and payload fields this client supports (verified against
+// src/app/api/daemon/*/route.ts):
 //   turnAdvance      → POST /api/daemon/turn-advance
-//                      { connectionUuid, sessionId, status, entityType?, entityUuid?,
+//                      { connectionUuid, sessionId, status, turnUuid?,
+//                        backendSessionId?, entityType?, entityUuid?,
+//                        interruptedReason?, transcriptRelayError?, usage?,
 //                        coalescedCount? }
 //   transcript       → POST /api/daemon/transcript
 //                      { sessionId, messages: [{ role, text }] }
@@ -71,7 +73,7 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
  * }} opts
  * @returns {{
- *   turnAdvance: (p: { sessionId: string, backendSessionId?: string|null, status: string, entityType?: string|null, entityUuid?: string|null, coalescedCount?: number }) => Promise<DaemonRestResult>,
+ *   turnAdvance: (p: { sessionId: string, turnUuid?: string|null, backendSessionId?: string|null, status: string, entityType?: string|null, entityUuid?: string|null, coalescedCount?: number }) => Promise<DaemonRestResult>,
  *   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>,
@@ -111,7 +113,7 @@ export function createDaemonRestClient(opts) {
    *                         established op-prefixed message.
    * @returns {Promise<DaemonRestResult>}
    */
-  async function post(op, path, body, successLog, context = "") {
+  async function post(op, path, body, successLog, context = "", readData = false) {
     let response;
     try {
       response = await fetchImpl(`${url}${path}`, {
@@ -131,8 +133,19 @@ export function createDaemonRestClient(opts) {
       logger.warn(`[Chorus] ${error}`);
       return { ok: false, status: response.status, error };
     }
+    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 };
+    return { ok: true, status: response.status, ...(data !== undefined ? { data } : {}) };
   }
 
   return {
@@ -148,7 +161,7 @@ export function createDaemonRestClient(opts) {
      * 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, transcriptRelayError, usage, backendSessionId, coalescedCount }) {
+    async turnAdvance({ sessionId, turnUuid, status, entityType, entityUuid, interruptedReason, transcriptRelayError, usage, backendSessionId, coalescedCount }) {
       const connectionUuid = getConnectionUuid();
       if (!connectionUuid) {
         const error = `cannot advance turn for session ${sessionId} → ${status} — no connection uuid yet`;
@@ -164,6 +177,7 @@ export function createDaemonRestClient(opts) {
         connectionUuid,
         sessionId,
         status,
+        ...(turnUuid ? { turnUuid } : {}),
         // Only sent when BOTH are present, so the server never gets a partial linkage.
         ...(entityType && entityUuid ? { entityType, entityUuid } : {}),
         // Only meaningful alongside status=interrupted; never sent otherwise.
@@ -182,12 +196,21 @@ export function createDaemonRestClient(opts) {
           ? { coalescedCount }
           : {}),
       };
-      return post(
+      const result = await post(
         "turn-advance",
         "/api/daemon/turn-advance",
         body,
         `advanced turn for session ${sessionId} → ${status}`,
+        "",
+        status === "running",
       );
+      const resolvedTurnUuid =
+        typeof result.data?.turn?.uuid === "string" ? result.data.turn.uuid : null;
+      if (status !== "running") return result;
+      const { data: _rawData, ...baseResult } = result;
+      return resolvedTurnUuid
+        ? { ...baseResult, data: { turnUuid: resolvedTurnUuid } }
+        : baseResult;
     },
 
     /**