@chorus-aidlc/chorus 0.17.1 → 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/credentials.mjs

@@ -380,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 = {}) =>

package/cli/init/agent-type-map.mjs

@@ -12,7 +12,7 @@
 //      "claude-code" EXPLICITLY here. No caller ever passes the raw init id
 //      through to daemon.json; every write goes through agentTypeForSelection.
 //   2. Any selection the daemon cannot wake as a first-class backend
-//      (opencode / openclaw / pi, and dsh while its harness is dormant/offline)
+//      (opencode / openclaw, and dsh while its harness is dormant/offline)
 //      maps to the non-wakeable "offline" classification. Its key is still parked
 //      in agents[] for the `chorus mcp` proxy, but the daemon builds no spawner
 //      and dispatches no wake (spawner-select.mjs fail-closes on "offline").
@@ -22,7 +22,7 @@
 // woken as claude-code.
 
 /**
- * Selection id → daemon agentType. Only claude/codex/kiro are wakeable backends;
+ * Selection id → daemon agentType. claude/codex/kiro/pi are wakeable backends;
  * everything else is classified offline. `dsh` maps to offline because the dsh
  * harness is de-advertised (offline) — re-map it here to bring it back online.
  * @type {Readonly<Record<string, string>>}
@@ -31,9 +31,9 @@ export const SELECTION_TO_AGENT_TYPE = Object.freeze({
   claude: "claude-code", // explicit rename — never pass the init id "claude" through verbatim
   codex: "codex",
   kiro: "kiro",
+  pi: "pi", // wakeable via PiSpawner (add-daemon-pi-backend)
   opencode: "offline",
   openclaw: "offline",
-  pi: "offline",
   dsh: "offline",
 });
 
@@ -42,7 +42,7 @@ export const SELECTION_TO_AGENT_TYPE = Object.freeze({
  * daemon.json `agents[]`. Unknown ids fail closed to "offline" (never a wakeable
  * default), so an agent is only ever woken when its backend is explicitly known.
  * @param {string} selectionId
- * @returns {string} a KNOWN_AGENTS agentType ("claude-code" | "codex" | "kiro" | "offline")
+ * @returns {string} a KNOWN_AGENTS agentType ("claude-code" | "codex" | "kiro" | "pi" | "offline")
  */
 export function agentTypeForSelection(selectionId) {
   return SELECTION_TO_AGENT_TYPE[selectionId] ?? "offline";
@@ -51,7 +51,7 @@ export function agentTypeForSelection(selectionId) {
 /**
  * Whether a daemon agentType is one the daemon can actually wake. "offline" is the
  * one non-wakeable classification; every other value the init mapping produces
- * (claude-code / codex / kiro) is wakeable.
+ * (claude-code / codex / kiro / pi) is wakeable.
  * @param {string} agentType
  * @returns {boolean}
  */