@chorus-aidlc/chorus 0.17.0 → 0.17.2

package/cli/agent-launcher.mjs

@@ -0,0 +1,341 @@
+// cli/agent-launcher.mjs
+// `chorus agents run` — launch a configured coding-agent binary in the FOREGROUND
+// with the selected Chorus agent's connection + identity injected into the child
+// environment only. This is the interactive counterpart to the daemon's headless
+// spawners (claude-spawner / codex-spawner / …): it reuses the SAME env-injection
+// contract (CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE) and the SAME
+// shell-free PATH resolution, but differs deliberately —
+//   • stdio is INHERITED (the agent gets the real TTY; Ctrl-C reaches it directly),
+//   • CHORUS_DAEMON_HEADLESS is NOT set (and is cleared if it leaked in),
+//   • every token after `--` is passed to the agent VERBATIM, with no validation,
+//   • the child's exit (code or signal) is forwarded as this command's exit code.
+//
+// SECRET RULE: the `cho_` API key is injected into the child env only. It is NEVER
+// written to stdout, stderr, or any log — diagnostics name the agent by
+// name/UUID and the resolved binary, nothing else.
+
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { win32 as pathWin32, posix as pathPosix } from "node:path";
+import { resolveLaunchAgent } from "./credentials.mjs";
+
+/**
+ * Launch agent-type → executable base name. Launch is a SUPERSET of daemon wake:
+ * it can start ANY known agent, including the ones the daemon classifies
+ * "offline" (opencode / openclaw / dsh) and therefore never auto-wakes. The
+ * "offline" value itself is intentionally ABSENT: it is a wake classification,
+ * not a concrete backend, so it cannot name a binary — a user who added such an
+ * agent must pass an explicit `--type` (see resolveBinaryName).
+ * @type {Readonly<Record<string,string>>}
+ */
+export const TYPE_TO_BINARY = Object.freeze({
+  "claude-code": "claude",
+  claude: "claude",
+  codex: "codex",
+  kiro: "kiro-cli",
+  pi: "pi",
+  opencode: "opencode",
+  openclaw: "openclaw",
+  dsh: "dsh-jsonrpc-agent",
+});
+
+/** Human list of accepted --type values, for help + error text. */
+export const SUPPORTED_TYPES = "claude-code, codex, kiro, pi, opencode, openclaw, dsh";
+
+/**
+ * POSIX signal name → number, for the shell `128 + signum` exit convention when
+ * the launched agent is terminated by a signal (e.g. Ctrl-C = SIGINT → 130).
+ * Node's `close` event yields a signal NAME (or null); a naive `exit(code)` with
+ * code=null would collapse a signal death to exit 0 and hide it.
+ */
+const SIGNUM = Object.freeze({
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGILL: 4,
+  SIGABRT: 6,
+  SIGFPE: 8,
+  SIGKILL: 9,
+  SIGSEGV: 11,
+  SIGPIPE: 13,
+  SIGALRM: 14,
+  SIGTERM: 15,
+});
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Split raw `chorus agents run` argv into chorus-owned flags and verbatim
+ * passthrough. The FIRST bare `--` terminates chorus-flag parsing; everything
+ * after it is passthrough, untouched. Chorus flags (before `--`): `--name <v>` /
+ * `--name=<v>`, its `--agent` alias, `--type <v>` / `--type=<v>`, and `--help`/`-h`.
+ * The first token that is NOT a recognized chorus flag also starts the
+ * passthrough (lenient) — so `chorus agents run --name x foo --bar` treats
+ * `foo --bar` as passthrough even without an explicit `--`.
+ *
+ * @param {string[]} argv  argv AFTER the `run` sub-verb.
+ * @returns {{ name?: string, type?: string, help: boolean, passthrough: string[], error?: string }}
+ */
+export function parseRunArgs(argv = []) {
+  const out = { help: false, passthrough: [] };
+  let i = 0;
+  for (; i < argv.length; i += 1) {
+    const tok = argv[i];
+    if (tok === "--") {
+      i += 1; // consume the separator; the rest is passthrough
+      break;
+    }
+    if (tok === "--help" || tok === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (tok === "--name" || tok === "--agent") {
+      const v = argv[i + 1];
+      if (v === undefined) return { ...out, error: `flag ${tok} needs a value` };
+      out.name = v;
+      i += 1;
+      continue;
+    }
+    if (tok.startsWith("--name=")) {
+      out.name = tok.slice("--name=".length);
+      continue;
+    }
+    if (tok.startsWith("--agent=")) {
+      out.name = tok.slice("--agent=".length);
+      continue;
+    }
+    if (tok === "--type") {
+      const v = argv[i + 1];
+      if (v === undefined) return { ...out, error: `flag --type needs a value` };
+      out.type = v;
+      i += 1;
+      continue;
+    }
+    if (tok.startsWith("--type=")) {
+      out.type = tok.slice("--type=".length);
+      continue;
+    }
+    // Unrecognized token → start of verbatim passthrough.
+    break;
+  }
+  out.passthrough = argv.slice(i);
+  return out;
+}
+
+/**
+ * Resolve the agent type (explicit `--type` wins over the stored `agentType`)
+ * and map it to a binary base name. An `offline` classification or any unknown
+ * type has no launchable binary → returns an `error` string instructing the user
+ * to pass an explicit `--type`.
+ * @param {string|undefined} explicitType  the `--type` flag value
+ * @param {string|undefined} configType    the agent's stored agentType
+ * @returns {{ type: string, binary: string } | { error: string }}
+ */
+export function resolveBinaryName(explicitType, configType) {
+  const type = nonEmpty(explicitType) ?? nonEmpty(configType);
+  if (!type) {
+    return { error: `no agent type given and none is configured — pass --type <${SUPPORTED_TYPES}>` };
+  }
+  const binary = TYPE_TO_BINARY[type];
+  if (!binary) {
+    const reason =
+      type === "offline"
+        ? `agent is configured as "offline" (the daemon does not auto-wake it, so its concrete backend is not stored)`
+        : `unknown agent type "${type}"`;
+    return { error: `${reason} — pass an explicit --type <${SUPPORTED_TYPES}>` };
+  }
+  return { type, binary };
+}
+
+/**
+ * Resolve an executable base name to a full path WITHOUT a shell, walking PATH.
+ * On Windows, tries `.cmd` / `.exe` / bare (npm shims are `.cmd`); on POSIX just
+ * the bare name. Mirrors resolveClaudePath's shape. Returns null when not found.
+ * @param {string} binName
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, isFile?: (p: string) => boolean }} [deps]
+ * @returns {string | null}
+ */
+export function resolveBinaryPath(binName, deps = {}) {
+  const env = deps.env ?? process.env;
+  const platform = deps.platform ?? process.platform;
+  const isFile =
+    deps.isFile ??
+    ((p) => {
+      try {
+        return statSync(p).isFile();
+      } catch {
+        return false;
+      }
+    });
+  const isWin = platform === "win32";
+  const p = isWin ? pathWin32 : pathPosix;
+  const names = isWin ? [`${binName}.cmd`, `${binName}.exe`, binName] : [binName];
+  const pathVar = env.PATH || env.Path || "";
+  const dirs = pathVar.split(p.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = p.join(dir, name);
+      if (isFile(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the actual command + argv to spawn. A Windows `.cmd`/`.bat` shim is not
+ * a PE executable, so it must run via `cmd.exe /d /s /c <path> …args`; keep
+ * shell:false and pass argv as an array (no shell word-splitting/injection). On
+ * POSIX (and a real `.exe`) spawn the path directly.
+ * @param {string} binPath @param {string[]} args
+ * @param {NodeJS.Platform} [platform] @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ command: string, argv: string[] }}
+ */
+export function resolveSpawnCommand(binPath, args, platform = process.platform, env = process.env) {
+  const isWin = platform === "win32";
+  const lower = binPath.toLowerCase();
+  if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
+    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    return { command: comspec, argv: ["/d", "/s", "/c", binPath, ...args] };
+  }
+  return { command: binPath, argv: args };
+}
+
+/**
+ * Build the child environment: the inherited env plus the selected agent's Chorus
+ * connection + identity. NO CHORUS_DAEMON_HEADLESS — this is an interactive run;
+ * a leaked value from a daemon-run parent is cleared so the agent does not adopt
+ * headless behavior. Only non-empty fields are set.
+ * @param {import("./credentials.mjs").LaunchAgent} agent
+ * @param {NodeJS.ProcessEnv} [baseEnv]
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function buildChildEnv(agent, baseEnv = process.env) {
+  const childEnv = { ...baseEnv };
+  if (agent.url) childEnv.CHORUS_URL = agent.url;
+  if (agent.apiKey) childEnv.CHORUS_API_KEY = agent.apiKey;
+  const profile = agent.agentUuid || agent.agentName;
+  if (profile) childEnv.CHORUS_AGENT_PROFILE = profile;
+  delete childEnv.CHORUS_DAEMON_HEADLESS;
+  return childEnv;
+}
+
+/** Usage text for `chorus agents run`. */
+export function runHelpText(version = "") {
+  const v = version ? ` v${version}` : "";
+  return `\
+Chorus${v} — launch a configured agent
+
+USAGE
+  chorus agents run --name <name|uuid> [--type <type>] [--] [agent args…]
+
+Launches the agent's binary in the FOREGROUND with this agent's Chorus connection
+injected into the child (CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE).
+Everything after \`--\` is passed to the agent verbatim — the agent's full flag
+surface is available and is never inspected by chorus.
+
+FLAGS
+  --name <name|uuid>   Which configured agent to launch (default: the only one).
+  --type <type>        Override the agent's backend: ${SUPPORTED_TYPES}.
+  -h, --help           Show this help.
+
+Notes
+  • Agents added as opencode / openclaw / dsh are stored as "offline"; pass
+    --type explicitly to launch them.
+  • The API key is injected into the launched process only — never printed.
+`;
+}
+
+/**
+ * Run `chorus agents run …`. Selects the agent, resolves its binary, injects the
+ * Chorus env, and spawns it in the foreground. Resolves with an exit code (never
+ * calls process.exit): the launched agent's code, `128 + signum` on signal death,
+ * `1` on any launch failure, `2` on a usage error, `0` on --help.
+ *
+ * @param {string[]} argv  argv AFTER the `run` sub-verb.
+ * @param {{ stdout?: {write:(s:string)=>void}, stderr?: {write:(s:string)=>void},
+ *   env?: NodeJS.ProcessEnv, readJson?: (p:string)=>any, loginPath?: string,
+ *   platform?: NodeJS.Platform, cwd?: string, version?: string,
+ *   spawnImpl?: Function, isFile?: (p:string)=>boolean }} [opts]
+ * @returns {Promise<number>}
+ */
+export async function runAgentLaunch(argv = [], opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const env = opts.env ?? process.env;
+  const platform = opts.platform ?? process.platform;
+  const spawnImpl = opts.spawnImpl ?? spawn;
+  const version = opts.version ?? "";
+
+  const parsed = parseRunArgs(argv);
+  if (parsed.help) {
+    out.write(runHelpText(version));
+    return 0;
+  }
+  if (parsed.error) {
+    err.write(`error: ${parsed.error}\n\n${runHelpText(version)}`);
+    return 2;
+  }
+
+  // 1. Select which configured agent to launch.
+  let agent;
+  try {
+    agent = resolveLaunchAgent({ name: parsed.name }, opts);
+  } catch (e) {
+    err.write(`error: ${e.message}\n`);
+    return 1;
+  }
+
+  // 2. Resolve the type → binary (explicit --type wins over stored agentType).
+  const typeRes = resolveBinaryName(parsed.type, agent.agentType);
+  if (typeRes.error) {
+    err.write(`error: ${agent.label}: ${typeRes.error}\n`);
+    return 1;
+  }
+
+  // 3. Locate the binary on PATH.
+  const binPath = resolveBinaryPath(typeRes.binary, { env, platform, isFile: opts.isFile });
+  if (!binPath) {
+    err.write(
+      `error: could not find the \`${typeRes.binary}\` executable on PATH ` +
+        `(agent "${agent.label}", type "${typeRes.type}"). Is it installed?\n`,
+    );
+    return 1;
+  }
+
+  // 4. Build the child env and the spawn command.
+  const childEnv = buildChildEnv(agent, env);
+  const { command, argv: spawnArgv } = resolveSpawnCommand(binPath, parsed.passthrough, platform, env);
+
+  // Diagnostic — agent name/uuid + binary ONLY. Never the key or url userinfo.
+  out.write(`Launching ${agent.label} (${agent.agentUuid ?? "no uuid"}) → ${typeRes.binary}\n`);
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(command, spawnArgv, {
+        cwd: opts.cwd ?? process.cwd(),
+        stdio: "inherit",
+        env: childEnv,
+        shell: false,
+      });
+    } catch (e) {
+      err.write(`error: failed to launch ${typeRes.binary}: ${e.message}\n`);
+      resolve(1);
+      return;
+    }
+    child.on("error", (e) => {
+      err.write(`error: ${typeRes.binary} failed to start: ${e.message}\n`);
+      resolve(1);
+    });
+    child.on("close", (code, signal) => {
+      if (signal) {
+        resolve(128 + (SIGNUM[signal] ?? 0));
+        return;
+      }
+      resolve(typeof code === "number" ? code : 0);
+    });
+  });
+}

package/cli/agents.mjs

@@ -67,6 +67,10 @@ USAGE
   chorus agents add [flags]         Configure agent(s): detect, install plugin, seed
                                     credentials (formerly \`chorus init\`; same flags —
                                     see \`chorus agents add --help\`)
+  chorus agents run --name <n> [--type <t>] -- [args…]
+                                    Launch an agent's binary in the foreground with its
+                                    Chorus connection injected; args after \`--\` pass
+                                    through verbatim (see \`chorus agents run --help\`)
   chorus agents remove <name|uuid>  Remove a configured agent from ~/.chorus/daemon.json
 
 Each listed UUID or name is a valid value for \`chorus mcp --agent <name|uuid>\` or the
@@ -316,6 +320,14 @@ export function runAgents(argv = [], opts = {}) {
     const runInit = opts.runInit ?? (async (a, o) => (await import("./init.mjs")).runInit(a, o));
     return runInit(argv.slice(1), { version });
   }
+  if (first === "run") {
+    // Foreground agent launch. Dynamic import keeps the list/remove paths from
+    // loading the launcher (and its child_process import). Forward the full opts
+    // (env/readJson/loginPath/spawnImpl/stdio) so tests can inject them.
+    const runAgentLaunch =
+      opts.runAgentLaunch ?? (async (a, o) => (await import("./agent-launcher.mjs")).runAgentLaunch(a, o));
+    return runAgentLaunch(argv.slice(1), { ...opts, version });
+  }
   if (first === "remove") {
     return removeAgent(argv.slice(1), opts);
   }

package/cli/claude-spawner.mjs

@@ -3,7 +3,7 @@
 // engineering point of the daemon: parsing stream-json is plain JS and
 // platform-neutral; the real work is spawning, and it is all Windows.
 //
-// Verified against Claude Code CLI 2.1.177:
+// Verified against Claude Code CLI 2.1.251:
 //   • `-p/--print` + `--output-format stream-json` emits NDJSON (one JSON object
 //     per line); every line carries `session_id`.
 //   • `--session-id <uuid>` sets the session id for a fresh run, and
@@ -32,6 +32,28 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 /** Matches a canonical lowercase UUID (any version). Chorus idea uuids are v4. */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
+/** Backend-neutral failure classification consumed by the wake orchestrator. */
+export const SESSION_CONFLICT_FAILURE = "session_conflict";
+
+const STDERR_BUFFER_LIMIT = 64 * 1024;
+const SESSION_CONFLICT_RE = /\bsession id\b[^\r\n]{0,200}\bis already in use\b/i;
+const CLAUDE_PROJECT_KEY_CAP = 200;
+
+/**
+ * Claude Code 2.1.251's Java-style signed 32-bit string hash, rendered as the
+ * absolute value in base36. Iterating by index intentionally hashes UTF-16 code
+ * units (including each surrogate in an astral character) rather than code points.
+ * @param {string} value
+ * @returns {string}
+ */
+function projectKeyHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash + value.charCodeAt(index)) | 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
 /**
  * True iff `id` is a well-formed, lowercase UUID. The daemon anchors the Claude
  * session id on a Chorus idea uuid (already lowercase v4); we validate before
@@ -45,22 +67,27 @@ export function isValidSessionId(id) {
 }
 
 /**
- * Claude Code's transcript directory for a working directory. Verified against the
- * live install: claude escapes the ABSOLUTE cwd by replacing both `/` and `.` with
- * `-` (e.g. `/home/u/dev/ai-pm` → `-home-u-dev-ai-pm`,
- * `/home/u/.cfg/x` → `-home-u--cfg-x`). On Windows the separators/drive differ, so
- * we escape backslashes and colons too; the rule there is best-effort and must be
- * re-verified against a Windows claude before claiming Windows resume support.
+ * Claude Code's transcript directory for a working directory. Verified against
+ * Claude Code 2.1.251's live Linux install and on-disk transcripts: every
+ * non-ASCII-alphanumeric UTF-16 code unit becomes `-`. That includes separators,
+ * dots, spaces, underscores, and non-ASCII characters; existing hyphens remain
+ * byte-identical because replacing `-` with `-` is a no-op. Escaped keys longer
+ * than 200 characters use the first 200 characters plus `-` and the base36
+ * Java-style signed 32-bit hash of the original cwd. The same expression produces
+ * the established Windows fixture, though the Windows on-disk layout remains
+ * best-effort until verified on a Windows Claude installation.
  * @param {string} cwd  Absolute working directory.
  * @param {NodeJS.Platform} [platform]
  * @returns {string}
  */
 export function escapeCwd(cwd, platform = process.platform) {
-  // Replace path separators and dots with `-`. On POSIX that's `/` and `.`; on
-  // Windows also `\` and the drive-colon. Collapsing both `/` and `.` is what
-  // produces the verified double-dash on a leading-dot segment.
-  const re = platform === "win32" ? /[\\/.:]/g : /[/.]/g;
-  return cwd.replace(re, "-");
+  // `platform` remains in the signature for fixture/API compatibility. Claude's
+  // observed sanitizer is platform-independent; platform path syntax supplies
+  // the differing separator/drive characters that this expression normalizes.
+  void platform;
+  const escaped = cwd.replace(/[^a-zA-Z0-9]/g, "-");
+  if (escaped.length <= CLAUDE_PROJECT_KEY_CAP) return escaped;
+  return `${escaped.slice(0, CLAUDE_PROJECT_KEY_CAP)}-${projectKeyHash(cwd)}`;
 }
 
 /**
@@ -284,7 +311,8 @@ export class ClaudeSpawner {
    *   so the waker can store the handle in its execution registry for the interrupt
    *   path BEFORE this promise resolves. It is invoked once, synchronously, only on a
    *   successful spawn; a spawn failure never calls it.
-   * @returns {Promise<{ sessionId: string, backendSessionId: string|null, exitCode: number|null, isNew: boolean }>}
+   * @returns {Promise<{ sessionId: string, backendSessionId: string|null, exitCode: number|null, isNew: boolean,
+   *                     failureClassification?: "session_conflict" }>}
    *   `backendSessionId` is the Claude `--resume` anchor (the input `sessionId`) on a
    *   terminal resolution after a spawn, so the conversation UI can offer a resumable
    *   id — mirrors codex-spawner's shape. `null` on the pre-spawn failure paths (no
@@ -369,6 +397,8 @@ export class ClaudeSpawner {
       }
 
       let stdoutBuf = "";
+      let stderrBuf = "";
+      let sessionConflictSeen = false;
       let observedSessionId = id;
 
       child.stdout?.setEncoding?.("utf8");
@@ -392,7 +422,10 @@ export class ClaudeSpawner {
 
       child.stderr?.setEncoding?.("utf8");
       child.stderr?.on("data", (chunk) => {
-        const text = String(chunk).trim();
+        const rawText = String(chunk);
+        stderrBuf = (stderrBuf + rawText).slice(-STDERR_BUFFER_LIMIT);
+        if (SESSION_CONFLICT_RE.test(stderrBuf)) sessionConflictSeen = true;
+        const text = rawText.trim();
         if (text) this.logger.warn(`[Chorus] claude stderr: ${text}`);
       });
 
@@ -411,7 +444,11 @@ export class ClaudeSpawner {
         }
         // backendSessionId is the `--resume` anchor (`id`), NOT observedSessionId (see
         // the process-error handler above for why the anchor is the resumable value).
-        resolve({ sessionId: observedSessionId, backendSessionId: id, exitCode: code, isNew });
+        const result = { sessionId: observedSessionId, backendSessionId: id, exitCode: code, isNew };
+        if (code !== null && code !== 0 && sessionConflictSeen) {
+          result.failureClassification = SESSION_CONFLICT_FAILURE;
+        }
+        resolve(result);
       });
 
       // Guard against an ASYNC stdin error (EPIPE): if claude exits/closes

package/cli/credentials.mjs

@@ -18,15 +18,19 @@
 
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 /** Absolute path to the login file written by `chorus login`. */
 export function loginFilePath() {
+  const override = process.env.CHORUS_DAEMON_CONFIG_PATH?.trim();
+  if (override) return resolve(override);
   return join(homedir(), ".chorus", "daemon.json");
 }
 
 /** Absolute path to the Claude Code user settings file (plugin fallback source). */
 export function claudeSettingsPath() {
+  const override = process.env.CHORUS_CLAUDE_SETTINGS_PATH?.trim();
+  if (override) return resolve(override);
   return join(homedir(), ".claude", "settings.json");
 }
 
@@ -376,3 +380,105 @@ export function resolveMcpCredentials(flags = {}, deps = {}) {
   const flat = resolveCredentials(flags, deps);
   return { url: flat.url, apiKey: flat.apiKey, label: flat.source };
 }
+
+/**
+ * @typedef {Object} LaunchAgent
+ * @property {string|undefined} url
+ * @property {string|undefined} apiKey
+ * @property {string|undefined} agentUuid
+ * @property {string|undefined} agentName
+ * @property {string|undefined} agentType   The daemon agentType stored in daemon.json
+ *   ("claude-code" | "codex" | "kiro" | "pi" | "offline" | …). The launcher maps this
+ *   (or an explicit --type) to a binary.
+ * @property {string} label                 Diagnostic display label (name/uuid), never the key.
+ */
+
+/**
+ * Resolve WHICH configured agent to launch (`chorus agents run`), returning the
+ * selected `agents[]` entry INCLUDING its `agentType` — the field the launcher
+ * needs to pick a binary and which `resolveMcpCredentials` deliberately drops.
+ *
+ * Selection precedence (mirrors `resolveMcpCredentials`, minus the url+key env/flag
+ * fallbacks — a launch always acts as a configured agent):
+ *   1. explicit selector: `flags.name` (the `--name` flag) or `flags.agent`
+ *      (`--agent` alias), matched against each entry's agentUuid / agentName /
+ *      label / name (exact). No match → error; >1 match → ambiguity error.
+ *   2. `CHORUS_AGENT_PROFILE` env, same matching.
+ *   3. exactly one configured agent → that agent.
+ *   4. more than one and nothing specified → error (never pick silently).
+ * No `agents[]` at all → error telling the user to configure one.
+ *
+ * Each entry's url/apiKey merges over the top-level per-field defaults
+ * (`resolveCredentialDefaults`), same as `resolveMcpCredentials`. This never
+ * imports daemon-config.mjs (which imports this module) — it reads `agents[]`
+ * directly to stay cycle-free.
+ *
+ * @param {{ name?: string, agent?: string, url?: string, apiKey?: string }} flags
+ * @param {ResolveDeps} [deps]
+ * @returns {LaunchAgent}
+ * @throws {Error} on ambiguity, no match, or no configured agents.
+ */
+export function resolveLaunchAgent(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const wanted = nonEmpty(flags.name) ?? nonEmpty(flags.agent) ?? nonEmpty(env.CHORUS_AGENT_PROFILE);
+
+  const file = readJson(loginPath);
+  const agentEntries =
+    file && Array.isArray(file.agents)
+      ? file.agents.filter((a) => a && typeof a === "object")
+      : [];
+  if (agentEntries.length === 0) {
+    throw new Error(
+      `No agents are configured in ${loginPath}. Run \`chorus agents add\` to configure one.`,
+    );
+  }
+
+  const defaults = resolveCredentialDefaults(flags, deps);
+  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),
+    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,
+    agentUuid: nonEmpty(entry.agentUuid),
+    agentName: nonEmpty(entry.agentName) ?? nonEmpty(entry.name),
+    agentType: nonEmpty(entry.agentType),
+  }));
+  const labels = resolved.map((a) => a.label).join(", ");
+
+  let selected;
+  if (wanted) {
+    const matches = resolved.filter((a) => a.keys.includes(wanted));
+    if (matches.length === 0) {
+      throw new Error(`No configured agent matches "${wanted}" in ${loginPath}. Available: ${labels}.`);
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `"${wanted}" is ambiguous in ${loginPath} — it matches ${matches.length} agents ` +
+          `(${matches.map((m) => m.label).join(", ")}). Use the agent UUID to disambiguate.`,
+      );
+    }
+    selected = matches[0];
+  } else if (resolved.length === 1) {
+    selected = resolved[0];
+  } else {
+    throw new Error(
+      `Multiple agents are configured in ${loginPath} (${labels}). ` +
+        `Specify which one to launch with --name <name|uuid> or CHORUS_AGENT_PROFILE.`,
+    );
+  }
+
+  return {
+    url: selected.url,
+    apiKey: selected.apiKey,
+    agentUuid: selected.agentUuid,
+    agentName: selected.agentName,
+    agentType: selected.agentType,
+    label: selected.label,
+  };
+}

package/cli/daemon-agent.mjs

@@ -27,8 +27,8 @@ import { loginFilePath } from "./credentials.mjs";
  * 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"];
+ * selected agent (opencode/openclaw) to this classification. */
+export const KNOWN_AGENTS = ["claude-code", "codex", "kiro", "dsh", "pi", "offline"];
 
 /** The default agent backend when neither --agent nor CHORUS_AGENT is set. */
 export const DEFAULT_AGENT = "claude-code";
@@ -45,6 +45,7 @@ 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" };
+  if (agentType === "pi") return { name: "pi", envVar: "CHORUS_PI_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
@@ -65,6 +66,7 @@ export function backendClientType(agentType) {
   if (agentType === "codex") return "codex";
   if (agentType === "kiro") return "kiro";
   if (agentType === "dsh") return "dsh";
+  if (agentType === "pi") return "pi";
   // `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

package/cli/init/adapters.mjs

@@ -35,13 +35,13 @@ import {
   installDsh,
   installOpenclaw,
   installKiro,
+  installPi,
   readCodexInstallState,
   readOpencodeInstallState,
   readDshInstallState,
   readOpenclawInstallState,
   readKiroInstallState,
-  guided,
-  GUIDED_MESSAGES,
+  readPiInstallState,
 } from "./install-methods.mjs";
 
 // Re-export the shared marketplace identifiers from their canonical home so
@@ -95,7 +95,7 @@ export const AGENT_DESCRIPTORS = [
   { id: "kiro", displayName: "Kiro CLI", binaries: ["kiro"], configDirs: ["~/.kiro"], readState: readKiroInstallState, install: installKiro },
   { id: "opencode", displayName: "opencode", binaries: ["opencode"], configDirs: ["~/.config/opencode", "~/.opencode"], readState: readOpencodeInstallState, install: installOpencode },
   { id: "openclaw", displayName: "OpenClaw", binaries: ["openclaw"], configDirs: ["~/.openclaw", "~/.config/openclaw"], readState: readOpenclawInstallState, install: installOpenclaw },
-  { id: "pi", displayName: "Pi", binaries: ["pi"], configDirs: ["~/.pi", "~/.config/pi"], install: guided("pi", GUIDED_MESSAGES.pi) },
+  { id: "pi", displayName: "Pi", binaries: ["pi"], configDirs: ["~/.pi", "~/.config/pi"], readState: readPiInstallState, install: installPi },
   { id: "dsh", displayName: "DeepSeek Harness (dsh)", binaries: ["dsh"], configDirs: ["$DSH_HOME", "~/.dsh"], readState: readDshInstallState, install: installDsh },
 ];
 
@@ -117,8 +117,8 @@ export function buildAdapter(d) {
       // `guided()` fallback also returns a function (so `typeof d.install ===
       // "function"` alone would report every fallback agent as supported — the
       // pre-existing latent bug); guided installers are tagged `.guided === true`,
-      // so exclude them here. Real installers (claude/codex/opencode + dsh/openclaw/
-      // kiro) → true; guided (pi) → false.
+      // so exclude them here. Every current agent (claude/codex/opencode + dsh/
+      // openclaw/kiro/pi) has a real installer → true; a future guided fallback → false.
       return { supported: typeof d.install === "function" && d.install.guided !== true, ...base };
     },
     installPlugin: (ctx = {}) =>