@chorus-aidlc/chorus 0.17.0 → 0.17.2

package/cli/init/steps/credential-seed.mjs

@@ -53,6 +53,7 @@ import {
 import { resolveInstallCwds as defaultResolveInstallCwds } from "../../daemon-install-config.mjs";
 import { validateAndFetchIdentity } from "../../chorus-client.mjs";
 import { agentTypeForSelection, isWakeableAgentType } from "../agent-type-map.mjs";
+import { writePiMcpServer, resolvePiMcpConfigPath } from "../pi-mcp-config.mjs";
 
 const STEP_ID = "credential-seed";
 const { SEEDED, SKIPPED, FAILED } = OUTCOME_ACTIONS;
@@ -421,6 +422,23 @@ export function readCodexEnvProfile(envPath, deps = {}) {
   }
 }
 
+/**
+ * Whether an init selection id is Pi (`pi`). Pi's Chorus MCP access is via the ADAPTER
+ * path (`pi-mcp-adapter` reads an mcp.json — chorus.ts never registers tools itself), so
+ * — like Codex's `[mcp_servers.chorus]` — `chorus agents add` writes pi's global
+ * `~/.pi/agent/mcp.json` with an `mcpServers.chorus` entry whose Authorization references
+ * the API key by ENV VAR (`Bearer ${CHORUS_API_KEY}`), NO literal key on disk. Unlike dsh /
+ * Claude Code / Codex, pi has NO settings env-file to persist the key + profile into, so this
+ * write does NOT suppress the CHORUS_AGENT_PROFILE export hint: interactive pi still needs
+ * CHORUS_API_KEY (+ CHORUS_AGENT_PROFILE) exported in its shell. We gate on the selection id,
+ * NOT the mapped daemon agentType (`pi` → the shared "offline" type, so it can't single pi
+ * out). Mirrors {@link isDshSelection} / {@link isClaudeSelection} / {@link isCodexSelection}.
+ * @param {string} id
+ */
+function isPiSelection(id) {
+  return id === "pi";
+}
+
 /**
  * @param {import("../contracts.mjs").StepContext & {
  *   validateCredentials?: Function, appendAgent?: Function, writeLogin?: Function,
@@ -442,6 +460,7 @@ export async function seedCredentials(ctx) {
   const readSettingsProfile = ctx.readClaudeSettingsProfile ?? readClaudeSettingsProfile;
   const writeCodexEnv = ctx.writeCodexEnv ?? writeCodexEnvFile;
   const readCodexProfile = ctx.readCodexEnvProfile ?? readCodexEnvProfile;
+  const writePiMcp = ctx.writePiMcp ?? writePiMcpServer;
 
   const selection = Array.isArray(ctx.selection) ? ctx.selection.filter((id) => nonEmpty(id)) : [];
   if (selection.length === 0) {
@@ -708,13 +727,47 @@ export async function seedCredentials(ctx) {
       }
     }
 
-    // Combined side-file note + hint-suppression flags (dsh, claude, and codex are mutually
-    // exclusive selection ids, so at most one note/flag is set per iteration).
-    const sideNote = `${dshNote}${claudeNote}${codexNote}`;
+    // pi-only: ALSO write pi's global ~/.pi/agent/mcp.json so `pi-mcp-adapter` exposes the
+    // chorus_* tools to the pi agent (the ADAPTER path — chorus.ts never registers tools). The
+    // Authorization header references the key by env var (`Bearer ${CHORUS_API_KEY}`), so NO
+    // literal cho_ key is written — the pi analogue of Codex's keyless [mcp_servers.chorus]
+    // bearer_token_env_var and CC's plugin .mcp.json ${VAR} interpolation. The URL is not a
+    // secret, so it is a resolved literal. UNGATED by daemon.json dedup (an idempotent re-run
+    // still repairs a missing/stale mcp.json). Unlike dsh/claude/codex this write does NOT
+    // suppress the CHORUS_AGENT_PROFILE export hint: pi has NO settings env-file to persist the
+    // key + profile into, so interactive pi still needs CHORUS_API_KEY (+ CHORUS_AGENT_PROFILE)
+    // in its shell — the daemon spawner injects them for the wake path. `piMcpWritten` is
+    // reported for observability only; it is intentionally NOT in the hint-suppression set.
+    let piNote = "";
+    let piMcpWritten = false;
+    if (isPiSelection(id)) {
+      const configPath = resolvePiMcpConfigPath(env);
+      try {
+        const p = writePiMcp({ configPath, url });
+        piMcpWritten = true;
+        piNote =
+          `; wrote mcpServers.chorus (Authorization: Bearer \${CHORUS_API_KEY}) into ${p} (0600) — ` +
+          "pi-mcp-adapter exposes the chorus_* tools with the cho_ key env-sourced (no literal key on " +
+          "disk). Interactive pi still needs CHORUS_API_KEY (+ CHORUS_AGENT_PROFILE) exported in its " +
+          "shell; the daemon injects them for the wake path. Your cho_ key is not shown here.";
+      } catch (err) {
+        piNote =
+          `; WARNING: could not write ${configPath} (${err?.message ?? String(err)}). ` +
+          "pi will not reach Chorus MCP until an mcpServers.chorus entry with an env-referenced " +
+          `Authorization (Bearer \${CHORUS_API_KEY}) exists — add it to ${configPath}. ` +
+          "Your cho_ key is not shown here.";
+      }
+    }
+
+    // Combined side-file note + hint-suppression flags (dsh, claude, codex, and pi are mutually
+    // exclusive selection ids, so at most one note is set per iteration). piMcpWritten is carried
+    // for observability but is NOT a hint-suppression flag (see the pi branch above).
+    const sideNote = `${dshNote}${claudeNote}${codexNote}${piNote}`;
     const hintFlags = {
       ...(profileInEnv ? { profileInEnv: true } : {}),
       ...(settingsEnvWritten ? { settingsEnvWritten: true } : {}),
       ...(codexEnvWritten ? { codexEnvWritten: true } : {}),
+      ...(piMcpWritten ? { piMcpWritten: true } : {}),
     };
 
     if (!res.ok) {

package/cli/init-args.mjs

@@ -113,7 +113,8 @@ OPTIONS
                            auto-start is unsupported (e.g. Windows). In an
                            interactive TTY run the daemon-setup step prompts instead
                            (default: No).
-  -y, --yes                Skip confirmation prompts (implied when non-TTY).
+  -y, --yes                Accept confirmation prompts, including refreshing
+                           installed plugins to latest (implied when non-TTY).
   -h, --help               Show this help message.
 
 NON-INTERACTIVE
@@ -121,6 +122,8 @@ NON-INTERACTIVE
   will not guess which agents to configure and aborts otherwise. The daemon boot service is
   installed non-interactively ONLY when you pass --daemon-autostart; otherwise the
   daemon config is written and you start it yourself with 'chorus daemon'.
+  With an explicit selection, --yes and non-TTY runs refresh selected installed
+  plugins to their latest available versions without prompting.
 
 SCOPE
   This installs the plugin SURFACE, seeds credentials into the daemon config, and

package/cli/init.mjs

@@ -97,11 +97,26 @@ export async function runInit(argv = [], deps = {}) {
 
   io.log(`[chorus agents add] Configuring: ${selectedIds.join(", ")}`);
 
+  // Resolve adapters once: update-intent detection and per-agent steps must see
+  // the same adapter instances/state readers.
+  const adapters = new Map();
+  for (const agentId of selectedIds) {
+    adapters.set(agentId, await getAdapter(agentId));
+  }
+  const updateInstalled = await resolveUpdateInstalled({
+    selectedIds,
+    adapters,
+    flags,
+    env,
+    io,
+  });
+  const resolvedFlags = { ...flags, updateInstalled };
+
   const steps = await orderedSteps();
   // `ctxExtras` lets a caller/test inject step-context collaborators (e.g. a
   // fake credential validator or command runner) so an end-to-end run is
   // hermetic; production passes none and steps use their real defaults.
-  const baseCtx = { selection: selectedIds, flags, io, env, backup, ...(deps.ctxExtras ?? {}) };
+  const baseCtx = { selection: selectedIds, flags: resolvedFlags, io, env, backup, ...(deps.ctxExtras ?? {}) };
   /** @type {import("./init/contracts.mjs").StepOutcome[]} */
   const outcomes = [];
 
@@ -109,7 +124,7 @@ export async function runInit(argv = [], deps = {}) {
     try {
       if (step.scope === STEP_SCOPES.PER_AGENT) {
         for (const agentId of selectedIds) {
-          const adapter = await getAdapter(agentId);
+          const adapter = adapters.get(agentId);
           outcomes.push(await step.run({ ...baseCtx, agentId, adapter }));
         }
       } else {
@@ -129,6 +144,36 @@ export async function runInit(argv = [], deps = {}) {
   return outcomes.flat().some(isFailureOutcome) ? 1 : 0;
 }
 
+/**
+ * Resolve one installed-plugin update decision for the whole invocation.
+ * Unsupported/guided adapters and selected adapters without an installed
+ * Chorus payload do not trigger the question. `--yes` and non-TTY runs accept
+ * automatically; an interactive answer defaults to no.
+ */
+export async function resolveUpdateInstalled({ selectedIds, adapters, flags, env, io }) {
+  let anyInstalled = false;
+  for (const agentId of selectedIds) {
+    const adapter = adapters.get(agentId);
+    if (!adapter || typeof adapter.readInstallState !== "function") continue;
+    try {
+      const profile = flags.dshProfile ?? env.CHORUS_DSH_PROFILE;
+      const state = await adapter.readInstallState({ env, profile });
+      if (state?.supported === true && state?.pluginInstalled === true) {
+        anyInstalled = true;
+        break;
+      }
+    } catch {
+      // State probes are advisory and read-only. A broken probe must not block
+      // normal repair/install work; the installer will report its own outcome.
+    }
+  }
+  if (!anyInstalled) return false;
+  if (flags.yes || !io.isTTY) return true;
+  if (typeof io.ask !== "function") return false;
+  const answer = String(await io.ask("Update installed Chorus plugins to the latest available versions? [y/N] ")).trim();
+  return /^(?:y|yes)$/i.test(answer);
+}
+
 /** Print the per-outcome summary table. */
 export function summarize(outcomes, io, selectedIds = []) {
   io.log("");

package/cli/kiro-spawner.mjs

@@ -222,6 +222,7 @@ export function pickNewSessionId(before, after) {
 export class KiroSpawner {
   /** @param {KiroSpawnerOptions} [opts] */
   constructor(opts = {}) {
+    this.sessionDecision = { probeIsAuthoritative: false };
     this.kiroPath = opts.kiroPath ?? null;
     this.spawnImpl = opts.spawnImpl ?? spawn;
     this.logger = opts.logger ?? NOOP_LOGGER;

package/cli/pi-spawner.mjs

@@ -0,0 +1,286 @@
+// cli/pi-spawner.mjs
+// Cross-platform headless pi spawner — the `pi` counterpart to ClaudeSpawner /
+// CodexSpawner, satisfying the SAME backend-agnostic Spawner.wake(...) contract so
+// the daemon's wake pipeline (queue, waker, directed delivery, headless guard,
+// reporters) stays backend-neutral and drives whichever spawner is injected purely
+// through the shared wake(...) contract.
+//
+// Verified against the pi source (earendil-works/pi, packages/coding-agent) before
+// coding — NOT guessed:
+//   • `pi --mode json -p` runs headless and emits a JSONL event stream on stdout
+//     (one JSON object per line): the session header first, then AgentSessionEvents
+//     (`message_start` / `message_update` / `message_end` / `tool_execution_*` /
+//     `turn_end` / `agent_end`). Verified against src/modes/print-mode.ts +
+//     src/modes/json-event.ts + docs/json.md.
+//   • The prompt is read from PIPED STDIN (never argv): main.ts `readPipedStdin()`
+//     folds stdin into the initial message when stdin is not a TTY. We pipe the
+//     prompt and close stdin, exactly like the Claude/Codex spawners.
+//   • SESSION MODEL — client-owned id (like Claude, unlike Codex). pi accepts a
+//     caller-provided `--session-id <id>` which is IDEMPOTENT create-or-resume:
+//     main.ts createSessionManager() resumes the existing session when one with
+//     that exact id already exists in the cwd-scoped session dir, otherwise creates
+//     a fresh session WITH that id. (`--session <id>` is the resume-ONLY flag — it
+//     hard-errors when the session is absent — so it is the wrong choice for a wake
+//     that must create-if-missing.) So we pass `--session-id <anchor>` for BOTH the
+//     first wake and every resume; pi owns the new-vs-resume decision from its own
+//     on-disk state. No persisted anchor→id map is needed (that is only for Codex,
+//     which generates its own id). We NEVER pass `--no-session` (that flag is for
+//     ephemeral subagent children only).
+//   • pi has NO permission system (no sandbox / no tool-approval prompt in headless
+//     mode), so `permissionMode` is a NO-OP: we emit no sandbox / skip-permissions
+//     flag. `chorus` and `yolo` modes run identically.
+//   • pi has no native MCP: a woken pi reaches Chorus tools only via the chorus-pi
+//     extension / pi-mcp-adapter installed in the woken environment. This spawner
+//     does not inject MCP; it exports the daemon's creds into the child env, which
+//     the extension consumes (CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE).
+//
+// Reuses claude-spawner's platform-neutral NDJSON parser (parseNdjsonChunk) and the
+// PATH-walk / .cmd-shim shape of the other spawners' path resolution.
+
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { win32 as pathWin32, posix as pathPosix } from "node:path";
+import { parseNdjsonChunk } from "./claude-spawner.mjs";
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+/**
+ * Build the argv for a headless pi run. The prompt is NEVER here — it goes over
+ * stdin (`pi -p` folds piped stdin into the initial message).
+ *
+ * `--session-id <anchor>` is pi's idempotent create-or-resume flag (verified against
+ * pi main.ts createSessionManager): it resumes the session with that exact id if one
+ * exists in the cwd-scoped dir, else creates a new session with that id — so the SAME
+ * args serve both the first wake and every resume, and pi owns the decision. `-p` is
+ * placed LAST so pi's arg parser can never mistake a following token for a message
+ * positional (its `-p` handler slurps the next bare, non-flag arg as a message).
+ *
+ * @param {{ sessionId: string }} o
+ * @returns {string[]}
+ */
+export function buildPiArgs({ sessionId }) {
+  return ["--mode", "json", "--session-id", sessionId, "-p"];
+}
+
+/**
+ * Resolve the real `pi` executable WITHOUT a shell — same approach as
+ * resolveClaudePath / resolveCodexPath. On Windows the bin may be `pi.cmd` (npm
+ * shim), which `spawn` can't exec directly without shell:true; we walk PATH for the
+ * platform candidates. `CHORUS_PI_PATH` overrides.
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, isFile?: (p: string) => boolean }} [deps]
+ * @returns {string | null}
+ */
+export function resolvePiPath(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;
+      }
+    });
+
+  if (env.CHORUS_PI_PATH && isFile(env.CHORUS_PI_PATH)) {
+    return env.CHORUS_PI_PATH;
+  }
+
+  const isWin = platform === "win32";
+  const p = isWin ? pathWin32 : pathPosix;
+  const names = isWin ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
+  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. On Windows a `.cmd`/`.bat` shim is
+ * not a PE executable, so it must run via `cmd.exe /d /s /c <path> ...args`; we keep
+ * shell:false and pass argv as an array (no shell word-splitting/injection).
+ * @param {string} piPath @param {string[]} args
+ * @param {NodeJS.Platform} [platform] @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ command: string, argv: string[] }}
+ */
+export function resolveSpawnCommand(piPath, args, platform = process.platform, env = process.env) {
+  const isWin = platform === "win32";
+  const lower = piPath.toLowerCase();
+  if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
+    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    return { command: comspec, argv: ["/d", "/s", "/c", piPath, ...args] };
+  }
+  return { command: piPath, argv: args };
+}
+
+/**
+ * @typedef {Object} PiSpawnerOptions
+ * @property {string} [piPath]   Resolved pi path (resolved lazily if omitted).
+ * @property {(o: object) => any} [spawnImpl]   Injectable spawn (tests).
+ * @property {{info(m:string):void,warn(m:string):void,error(m:string):void}} [logger]
+ * @property {"chorus"|"yolo"} [permissionMode]  Accepted for a uniform selectSpawner
+ *   call, but a NO-OP: pi has no permission system, so no flag is emitted either way.
+ * @property {{ url: string, apiKey: string, agentUuid?: string, agentName?: string }} [creds]
+ *   Daemon creds exported into the child env for the chorus-pi extension's MCP-over-HTTP
+ *   tooling and SessionStart bookkeeping.
+ * @property {NodeJS.Platform} [platform]  Injectable for tests; gates POSIX `detached`.
+ * @property {(deps?: object) => (string|null)} [resolvePiPathFn]  Injectable resolver.
+ */
+
+export class PiSpawner {
+  /** @param {PiSpawnerOptions} [opts] */
+  constructor(opts = {}) {
+    // pi manages new-vs-resume internally from its own on-disk session state (the
+    // `--session-id` anchor is idempotent create-or-resume), so the daemon's shared
+    // Claude transcript probe is NOT authoritative for pi. Setting this false makes
+    // the waker skip the Claude-specific "take over with `claude --resume`" log line
+    // (mirrors CodexSpawner) — pi is not resumable via `claude --resume`.
+    this.sessionDecision = { probeIsAuthoritative: false };
+    this.piPath = opts.piPath ?? null;
+    this.spawnImpl = opts.spawnImpl ?? spawn;
+    this.logger = opts.logger ?? NOOP_LOGGER;
+    // Stored for a uniform construction shape, but never consulted when building
+    // args — pi has no permission surface, so no sandbox / skip-permissions flag.
+    this.permissionMode = opts.permissionMode ?? "chorus";
+    this.creds = opts.creds ?? null;
+    this.platform = opts.platform ?? process.platform;
+    this.resolvePiPathFn = opts.resolvePiPathFn ?? resolvePiPath;
+  }
+
+  /**
+   * Spawn a headless pi run. Resolves when the subprocess exits. The prompt is
+   * written to stdin (never argv). `sessionId` is the Chorus anchor (direct idea
+   * uuid, or the entity uuid for an ad-hoc session) and is passed straight through as
+   * pi's client-owned `--session-id`, which pi resolves as create-or-resume from its
+   * own on-disk session dir — so the passed `isNew` (derived by the waker's
+   * Claude-specific transcript probe, which never matches a pi session) does NOT
+   * drive the flag; it is only echoed back for the waker's log line.
+   *
+   * @param {{ prompt: string, sessionId: string|null, isNew?: boolean, cwd?: string,
+   *           onMessage?: (obj: any) => void,
+   *           onChild?: (child: import("node:child_process").ChildProcess) => void }} params
+   * @returns {Promise<{ sessionId: string, backendSessionId: string|null, exitCode: number|null, isNew: boolean }>}
+   *   `backendSessionId` is the resumable anchor (the input `sessionId`) after a spawn,
+   *   so the conversation UI can offer a resumable id — mirrors the other spawners.
+   *   `null` on the pre-spawn failure paths (no run started, nothing to resume).
+   */
+  async wake({ prompt, sessionId, isNew, cwd, onMessage, onChild }) {
+    const anchor = typeof sessionId === "string" ? sessionId : "";
+    const isNewFlag = Boolean(isNew);
+
+    const piPath = this.piPath ?? this.resolvePiPathFn();
+    if (!piPath) {
+      // No crash — surface visibly and resolve with a failure result (matches the
+      // other spawners' "skipping wake" convention: exitCode null, no throw).
+      this.logger.error("[Chorus] cannot locate the `pi` executable on PATH; skipping wake");
+      return { sessionId: anchor, backendSessionId: null, exitCode: null, isNew: isNewFlag };
+    }
+
+    const args = buildPiArgs({ sessionId: anchor });
+    const { command, argv } = resolveSpawnCommand(piPath, args, this.platform);
+
+    // POSIX: detached process group so the interrupt path can group-kill the tree
+    // (pi may fork child shells / subagents). Windows uses taskkill /T. stdio stays
+    // piped — prompt over stdin + NDJSON stdout parse are unaffected.
+    const detached = this.platform !== "win32";
+
+    // Export the daemon's resolved connection pair for the chorus-pi extension's
+    // Chorus tooling. Explicitly overwrite inherited values so the extension and the
+    // daemon cannot disagree about which Chorus instance this wake belongs to.
+    const childEnv = { ...process.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;
+      // Identity profile for the woken session — its extension/skills pass this to
+      // `chorus mcp --agent`, which resolves the key from ~/.chorus/daemon.json.
+      if (this.creds.agentUuid || this.creds.agentName)
+        childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
+    }
+
+    return new Promise((resolve) => {
+      let child;
+      try {
+        child = this.spawnImpl(command, argv, {
+          cwd: cwd ?? process.cwd(),
+          stdio: ["pipe", "pipe", "pipe"],
+          env: childEnv,
+          shell: false,
+          detached,
+          windowsHide: true,
+        });
+      } catch (err) {
+        this.logger.error(`[Chorus] failed to spawn pi: ${err}`);
+        resolve({ sessionId: anchor, backendSessionId: null, exitCode: null, isNew: isNewFlag });
+        return;
+      }
+
+      // Hand the live child to the caller (interrupt registry) before resolving.
+      // Never let a throwing callback escape into the spawn path.
+      if (onChild) {
+        try {
+          onChild(child);
+        } catch (err) {
+          this.logger.warn(`[Chorus] onChild handler threw: ${err}`);
+        }
+      }
+
+      let stdoutBuf = "";
+
+      child.stdout?.setEncoding?.("utf8");
+      child.stdout?.on("data", (chunk) => {
+        stdoutBuf = parseNdjsonChunk(
+          stdoutBuf,
+          String(chunk),
+          (obj) => {
+            if (onMessage) {
+              try {
+                onMessage(obj);
+              } catch (err) {
+                this.logger.warn(`[Chorus] onMessage handler threw: ${err}`);
+              }
+            }
+          },
+          (msg) => this.logger.warn(`[Chorus] ${msg}`)
+        );
+      });
+
+      child.stderr?.setEncoding?.("utf8");
+      child.stderr?.on("data", (chunk) => {
+        const text = String(chunk).trim();
+        if (text) this.logger.warn(`[Chorus] pi stderr: ${text}`);
+      });
+
+      child.on("error", (err) => {
+        this.logger.error(`[Chorus] pi process error: ${err}`);
+        resolve({ sessionId: anchor, backendSessionId: anchor || null, exitCode: null, isNew: isNewFlag });
+      });
+
+      child.on("close", (code) => {
+        if (code !== 0) {
+          this.logger.warn(`[Chorus] pi exited with code ${code}`);
+        }
+        resolve({ sessionId: anchor, backendSessionId: anchor || null, exitCode: code, isNew: isNewFlag });
+      });
+
+      // Guard against an ASYNC stdin error (EPIPE) so it never becomes an
+      // uncaughtException that kills the daemon.
+      child.stdin?.on?.("error", (err) => {
+        this.logger.warn(`[Chorus] pi stdin error (ignored): ${err}`);
+      });
+
+      // Feed the prompt over stdin, then close it so the model runs.
+      try {
+        child.stdin?.write(prompt);
+        child.stdin?.end();
+      } catch (err) {
+        this.logger.warn(`[Chorus] failed writing prompt to pi stdin: ${err}`);
+      }
+    });
+  }
+}

package/cli/spawner-select.mjs

@@ -20,6 +20,7 @@ import { ClaudeSpawner } from "./claude-spawner.mjs";
 import { CodexSpawner } from "./codex-spawner.mjs";
 import { DshSpawner } from "./dsh-spawner.mjs";
 import { KiroSpawner } from "./kiro-spawner.mjs";
+import { PiSpawner } from "./pi-spawner.mjs";
 
 /**
  * A fail-closed spawner for the `offline` agentType. It satisfies the shared
@@ -52,7 +53,7 @@ export class OfflineSpawner {
 
 /**
  * Construct the spawner backend for `agentType`.
- * @param {string} agentType  "claude-code" | "codex" | "kiro" | "dsh" | "offline"
+ * @param {string} agentType  "claude-code" | "codex" | "kiro" | "dsh" | "pi" | "offline"
  *   (already validated upstream). "offline" → OfflineSpawner (fail-closed no-op).
  * @param {{ logger?: any, permissionMode?: "chorus"|"yolo", creds?: { url: string, apiKey: string } }} [opts]
  * @returns {import("./codex-spawner.mjs").Spawner}
@@ -79,5 +80,10 @@ export function selectSpawner(agentType, opts = {}) {
       prepareManagedConfigFn: opts.prepareManagedConfigFn,
     });
   }
+  if (agentType === "pi") {
+    // pi is a first-class wakeable backend — an explicit branch so it NEVER falls
+    // through to the claude-code default below (nor is treated as offline).
+    return new PiSpawner({ logger, permissionMode, creds });
+  }
   return new ClaudeSpawner({ logger, permissionMode, creds });
 }

package/cli/upload-hooks.mjs

@@ -399,15 +399,26 @@ function stripSystemReminders(s) {
  * the caller can skip it). Never throws — a shape it doesn't recognize yields null
  * rather than an error (defensive against CLI drift).
  *
- * Two stream dialects are recognized (their top-level shapes are disjoint, so no
+ * Four stream dialects are recognized (their top-level shapes are disjoint, so no
  * backend flag is needed):
  *  - Claude Code stream-json: `{ type: "user"|"assistant", message: { content … } }`.
+ *  - DeepSeek Harness (dsh): `{ type: "user/message"|"assistant/message", data: { message } }`.
  *  - codex `codex exec --json`: conversation/tool output rides on `item.completed`
  *    events discriminated by `item.type`; assistant text is an `agent_message`
  *    item with a top-level `item.text` (verified against codex-cli 0.142.3). codex
  *    does NOT echo the user prompt (the chat UI renders that from the turn's
  *    promptText), and `reasoning` / `command_execution` / lifecycle envelopes are
  *    not conversation text — all dropped.
+ *  - pi (@earendil-works/pi-coding-agent) `pi --mode json`: AgentSessionEvents whose
+ *    authoritative final text is a `message_end` carrying a full AgentMessage
+ *    (`{ role, content }`). We keep ONLY the assistant message: pi UNCONDITIONALLY
+ *    re-emits the wake prompt as a `message_end` with role "user" (agent-loop.ts),
+ *    which the daemon already stores as the turn's promptText — so echoing it would
+ *    duplicate the prompt (same reason codex drops the user echo). `toolResult`
+ *    messages and `tool_execution_end` tool-output events are not conversation text.
+ *    pi's content-block shape is identical to Claude's (text blocks `{type:"text",text}`,
+ *    thinking `{type:"thinking"}`, tool calls `{type:"toolCall"}`), so we normalize the
+ *    assistant envelope to the Claude shape and reuse the same block extractor.
  *
  * @param {any} obj  One parsed stream NDJSON object.
  * @returns {{ role: "user"|"assistant", text: string } | null}
@@ -438,6 +449,19 @@ export function extractTranscriptText(obj) {
     return { role: "assistant", text: itemText };
   }
 
+  // ── pi `pi --mode json` dialect ──
+  // pi's authoritative final text of each step is a `message_end` carrying a full
+  // AgentMessage `{ role, content }`. Keep ONLY the assistant message: pi re-emits the
+  // wake prompt as a role:"user" message_end (already stored as the turn's promptText),
+  // and role:"toolResult" / `tool_execution_end` events are tool output, not text.
+  // pi's content-block shape matches Claude's, so we hand the message to the Claude-shape
+  // extractor below (which keeps only `{type:"text"}` blocks, strips reminders, drops empties).
+  if (obj.type === "message_end") {
+    const message = obj.message;
+    if (!message || typeof message !== "object" || message.role !== "assistant") return null;
+    return extractTranscriptText({ type: "assistant", message });
+  }
+
   // ── Claude Code stream-json dialect ──
   if (!CONVERSATION_TYPES.has(obj.type)) return null;