@chorus-aidlc/chorus 0.17.2 → 0.18.0

package/cli/dsh-spawner.mjs

@@ -2,6 +2,8 @@
 // session are created per wake; no dsh session state is persisted by Chorus.
 
 import { spawn } from "node:child_process";
+import { safeSpawnError, redactedSetupError } from "./launch-diagnostics.mjs";
+import { validateAgentCliConfig, overlayAgentEnv, getAgentEnv, assertConfiguredShimArgs } from "./agent-cli-config.mjs";
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { win32 as pathWin32, posix as pathPosix } from "node:path";
@@ -28,20 +30,21 @@ function isFile(path) {
   }
 }
 
-/** Resolve the external SDK runtime. CHORUS_DSH_PATH overrides PATH. */
+/**
+ * Resolve the external `dsh` CLI (the profile launcher — dsh 0.1.2-rc.1 removed
+ * the standalone `dsh-jsonrpc-agent` bin). CHORUS_DSH_PATH overrides PATH.
+ */
 export function resolveDshPath(deps = {}) {
   const env = deps.env ?? process.env;
   const platform = deps.platform ?? process.platform;
   const fileProbe = deps.isFile ?? isFile;
-  const override = nonEmpty(env.CHORUS_DSH_PATH);
+  const override = nonEmpty(getAgentEnv(env, "CHORUS_DSH_PATH", platform));
   if (override && fileProbe(override)) return override;
 
   const windows = platform === "win32";
   const path = windows ? pathWin32 : pathPosix;
-  const names = windows
-    ? ["dsh-jsonrpc-agent.cmd", "dsh-jsonrpc-agent.exe", "dsh-jsonrpc-agent"]
-    : ["dsh-jsonrpc-agent"];
-  const dirs = (env.PATH || env.Path || "").split(path.delimiter).filter(Boolean);
+  const names = windows ? ["dsh.cmd", "dsh.exe", "dsh"] : ["dsh"];
+  const dirs = (getAgentEnv(env, "PATH", platform) || env.Path || "").split(path.delimiter).filter(Boolean);
   for (const dir of dirs) {
     for (const name of names) {
       const candidate = path.join(dir, name);
@@ -51,9 +54,14 @@ export function resolveDshPath(deps = {}) {
   return null;
 }
 
-/** Resolve the required Cordis composition without placing it in argv. */
-export function resolveDshConfig(env = process.env) {
-  return nonEmpty(env.CHORUS_DSH_CONFIG) ?? nonEmpty(env.DSH_CORDIS_CONFIG);
+/**
+ * An operator-supplied managed home override. When set, the daemon boots
+ * `dsh --profile sdk` against this pre-composed DSH_HOME and skips managed
+ * profile preparation entirely (the escape hatch replacing the old
+ * DSH_CORDIS_CONFIG override — which is gone with the removed cordis.yml model).
+ */
+export function resolveDshHome(env = process.env, platform = process.platform) {
+  return nonEmpty(getAgentEnv(env, "CHORUS_DSH_HOME", platform)) ?? nonEmpty(getAgentEnv(env, "DSH_HOME", platform));
 }
 
 /** Windows npm command shims need cmd.exe while retaining argv isolation. */
@@ -61,7 +69,7 @@ export function resolveDshSpawnCommand(dshPath, platform = process.platform, env
   const lower = dshPath.toLowerCase();
   if (platform === "win32" && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
     return {
-      command: env.ComSpec || env.COMSPEC || "cmd.exe",
+      command: getAgentEnv(env, "COMSPEC", platform) || "cmd.exe",
       argv: ["/d", "/s", "/c", dshPath],
     };
   }
@@ -133,7 +141,8 @@ export class DshSpawner {
     this.logger = opts.logger ?? NOOP_LOGGER;
     this.creds = opts.creds ?? null;
     this.platform = opts.platform ?? process.platform;
-    this.env = opts.env ?? process.env;
+    this.cliConfig = validateAgentCliConfig(opts.cliConfig, "dsh", opts.label);
+    this.env = overlayAgentEnv(opts.env ?? process.env, this.cliConfig.env, this.platform);
     this.bundleVersion = opts.bundleVersion ?? null;
     this.prepareManagedConfigFn = opts.prepareManagedConfigFn ?? prepareManagedDshConfig;
     this.timeoutMs = opts.timeoutMs ?? positiveInt(this.env.CHORUS_DSH_TIMEOUT_MS, DEFAULT_DSH_TIMEOUT_MS);
@@ -143,8 +152,9 @@ export class DshSpawner {
   }
 
   async wake({ prompt, sessionId: anchor, cwd, onMessage, onChild }) {
-    let dshPath = this.dshPath ?? this.resolveDshPathFn({ env: this.env, platform: this.platform });
-    let config = resolveDshConfig(this.env);
+    const dshPath = this.dshPath ?? this.resolveDshPathFn({ env: this.env, platform: this.platform });
+    let dshHome = resolveDshHome(this.env, this.platform);
+    let patchPath = null;
     const result = (backendSessionId, exitCode) => ({
       sessionId: backendSessionId || anchor || "",
       backendSessionId: backendSessionId || null,
@@ -154,37 +164,41 @@ export class DshSpawner {
 
     if (!dshPath) {
       this.logger.error(
-        "[Chorus] cannot locate `dsh-jsonrpc-agent`; install it or set CHORUS_DSH_PATH",
+        "[Chorus] cannot locate the `dsh` CLI; install DeepSeek Harness (dsh) or set CHORUS_DSH_PATH",
       );
       return result(null, null);
     }
-    if (!config) {
+    assertConfiguredShimArgs(dshPath, this.cliConfig.args, this.platform);
+    if (!dshHome) {
       try {
         const managed = await this.prepareManagedConfigFn({
           env: this.env,
+          platform: this.platform,
           bundleVersion: this.bundleVersion,
           dshPath,
           creds: this.creds,
         });
-        config = managed.configPath;
-        dshPath = managed.runtimePath ?? dshPath;
+        dshHome = managed.home;
+        patchPath = managed.patchPath ?? null;
       } catch (error) {
-        this.logger.error(`[Chorus] cannot prepare managed dsh config: ${errorText(error)}`);
+        const detail = redactedSetupError(error);
+        this.logger.error(`[Chorus] cannot prepare managed dsh profile: ${detail}`);
         return result(null, null);
       }
+    } else {
+      this.logger.info("[Chorus] using existing DSH_HOME profile, skipping managed preparation");
     }
 
     const dshSessionId = `chorus-${this.uuidFn().replaceAll("-", "")}`;
     const provider =
-      nonEmpty(this.env.CHORUS_DSH_PROVIDER) ?? nonEmpty(this.env.DSH_PROVIDER) ?? "deepseek-official";
+      nonEmpty(getAgentEnv(this.env, "CHORUS_DSH_PROVIDER", this.platform)) ?? nonEmpty(getAgentEnv(this.env, "DSH_PROVIDER", this.platform)) ?? "deepseek-official";
     const model =
-      nonEmpty(this.env.CHORUS_DSH_MODEL) ?? nonEmpty(this.env.DSH_MODEL) ?? "deepseek-v4-flash";
-    const childEnv = {
-      ...this.env,
+      nonEmpty(getAgentEnv(this.env, "CHORUS_DSH_MODEL", this.platform)) ?? nonEmpty(getAgentEnv(this.env, "DSH_MODEL", this.platform)) ?? "deepseek-v4-flash";
+    const childEnv = overlayAgentEnv(this.env, {
       CHORUS_DAEMON_HEADLESS: "1",
-      DSH_CORDIS_CONFIG: config,
+      DSH_HOME: dshHome,
       DSH_CWD: cwd || process.cwd(),
-    };
+    }, this.platform);
     if (this.creds?.url) childEnv.CHORUS_URL = this.creds.url;
     if (this.creds?.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
     // Identity profile — the dsh doc-mirror wrapper passes this to `chorus mcp
@@ -195,7 +209,19 @@ export class DshSpawner {
     if (this.creds?.agentUuid || this.creds?.agentName)
       childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
 
-    const { command, argv } = resolveDshSpawnCommand(dshPath, this.platform, childEnv);
+    // `dsh --profile sdk` boots the managed profile from DSH_HOME. The Chorus
+    // rows auto-apply as a bundle layer, so `--patch` is added only for a
+    // non-default provider overlay. resolveDshSpawnCommand keeps the win32 .cmd
+    // wrapper prefix; the launcher argv follows it.
+    const launch = resolveDshSpawnCommand(dshPath, this.platform, childEnv);
+    const command = launch.command;
+    const argv = [
+      ...launch.argv,
+      "--profile",
+      "sdk",
+      ...(patchPath ? ["--patch", patchPath] : []),
+      ...this.cliConfig.args,
+    ];
     let child;
     try {
       child = this.spawnImpl(command, argv, {
@@ -207,7 +233,7 @@ export class DshSpawner {
         windowsHide: true,
       });
     } catch (error) {
-      this.logger.error(`[Chorus] failed to start dsh runtime: ${errorText(error)}`);
+      this.logger.error(`[Chorus] failed to start dsh runtime: ${safeSpawnError(error)}`);
       return result(dshSessionId, null);
     }
 
@@ -349,7 +375,7 @@ export class DshSpawner {
         if (line) this.logger.warn(`[dsh] ${line}`);
       }
     });
-    child.on?.("error", (error) => fail(`dsh runtime process error: ${errorText(error)}`));
+    child.on?.("error", (error) => fail(`dsh runtime process error: ${safeSpawnError(error)}`));
     child.on?.("close", (code) => {
       closeSeen = true;
       exitCode = code;

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

@@ -68,7 +68,7 @@ function nonEmpty(value) {
  * Whether an init selection id is the DeepSeek Harness (dsh). dsh needs a SECOND
  * credential sink beyond ~/.chorus/daemon.json — see {@link writeDshCredentialsEnv}.
  * We gate on the selection id, NOT the daemon agentType: dsh maps to the shared
- * "offline" agentType (agent-type-map.mjs) alongside opencode/openclaw/pi, so the
+ * "offline" agentType (agent-type-map.mjs) alongside opencode/openclaw, so the
  * agentType cannot single dsh out. The id can.
  * @param {string} id
  */

package/cli/kiro-spawner.mjs

@@ -28,6 +28,8 @@
 // no-op here (this task owns spawn/resume/trust/interrupt + sessionId capture).
 
 import { spawn } from "node:child_process";
+import { safeSpawnError } from "./launch-diagnostics.mjs";
+import { validateAgentCliConfig, overlayAgentEnv, getAgentEnv, assertConfiguredShimArgs } from "./agent-cli-config.mjs";
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { win32 as pathWin32, posix as pathPosix, join } from "node:path";
@@ -37,8 +39,8 @@ import { reconstructTranscript as defaultReconstructTranscript } from "./kiro-tr
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
 /** Directory Kiro persists its CLI session store under (per-cwd conversations). */
-export function kiroSessionsDir() {
-  return join(homedir(), ".kiro", "sessions", "cli");
+export function kiroSessionsDir(env = process.env, platform = process.platform) {
+  return join(getAgentEnv(env, "HOME", platform) || getAgentEnv(env, "USERPROFILE", platform) || homedir(), ".kiro", "sessions", "cli");
 }
 
 /**
@@ -96,14 +98,15 @@ export function resolveKiroPath(deps = {}) {
       }
     });
 
-  if (env.CHORUS_KIRO_PATH && isFile(env.CHORUS_KIRO_PATH)) {
-    return env.CHORUS_KIRO_PATH;
+  const override = getAgentEnv(env, "CHORUS_KIRO_PATH", platform);
+  if (override && isFile(override)) {
+    return override;
   }
 
   const isWin = platform === "win32";
   const p = isWin ? pathWin32 : pathPosix;
   const names = isWin ? ["kiro-cli.cmd", "kiro-cli.exe", "kiro-cli"] : ["kiro-cli"];
-  const pathVar = env.PATH || env.Path || "";
+  const pathVar = getAgentEnv(env, "PATH", platform) || env.Path || "";
   const dirs = pathVar.split(p.delimiter).filter(Boolean);
   for (const dir of dirs) {
     for (const name of names) {
@@ -126,7 +129,7 @@ export function resolveSpawnCommand(kiroPath, args, platform = process.platform,
   const isWin = platform === "win32";
   const lower = kiroPath.toLowerCase();
   if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
-    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    const comspec = getAgentEnv(env, "COMSPEC", platform) || "cmd.exe";
     return { command: comspec, argv: ["/d", "/s", "/c", kiroPath, ...args] };
   }
   return { command: kiroPath, argv: args };
@@ -229,6 +232,8 @@ export class KiroSpawner {
     this.permissionMode = opts.permissionMode ?? "chorus";
     this.creds = opts.creds ?? null;
     this.platform = opts.platform ?? process.platform;
+    this.cliConfig = validateAgentCliConfig(opts.cliConfig, "kiro", opts.label);
+    this.env = overlayAgentEnv(opts.env ?? process.env, this.cliConfig.env, this.platform);
     this.getSessionIdFn = opts.getSessionIdFn ?? defaultGetSessionId;
     this.setSessionIdFn = opts.setSessionIdFn ?? defaultSetSessionId;
     this.resolveKiroPathFn = opts.resolveKiroPathFn ?? resolveKiroPath;
@@ -260,15 +265,16 @@ export class KiroSpawner {
     const knownSessionId = anchor ? this.getSessionIdFn(anchor) : null;
     const isNew = !knownSessionId;
 
-    const kiroPath = this.kiroPath ?? this.resolveKiroPathFn();
+    const kiroPath = this.kiroPath ?? this.resolveKiroPathFn({ env: this.env, platform: this.platform });
     if (!kiroPath) {
       // No crash — surface visibly and resolve with a failure result.
       this.logger.error("[Chorus] cannot locate the `kiro-cli` executable on PATH; skipping wake");
       return { sessionId: anchor, exitCode: null, isNew };
     }
 
-    const args = buildKiroArgs({ isNew, sessionId: knownSessionId, permissionMode: this.permissionMode });
-    const { command, argv } = resolveSpawnCommand(kiroPath, args, this.platform);
+    assertConfiguredShimArgs(kiroPath, this.cliConfig.args, this.platform);
+    const args = [...buildKiroArgs({ isNew, sessionId: knownSessionId, permissionMode: this.permissionMode }), ...this.cliConfig.args];
+    const { command, argv } = resolveSpawnCommand(kiroPath, args, this.platform, this.env);
 
     // POSIX: detached process group so the interrupt path can group-kill the tree
     // (kiro-cli forks child shells for tools). Windows uses taskkill /T. stdio
@@ -277,7 +283,7 @@ export class KiroSpawner {
 
     // Export the daemon's authoritative connection pair. CHORUS_API_KEY is also
     // referenced by the plugin's MCP config; neither value is placed in argv.
-    const childEnv = { ...process.env, CHORUS_DAEMON_HEADLESS: "1" };
+    const childEnv = { ...this.env, CHORUS_DAEMON_HEADLESS: "1" };
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
@@ -303,8 +309,8 @@ export class KiroSpawner {
           detached,
           windowsHide: true,
         });
-      } catch (err) {
-        this.logger.error(`[Chorus] failed to spawn kiro-cli: ${err}`);
+      } catch (error) {
+        this.logger.error(`[Chorus] failed to spawn kiro-cli: ${safeSpawnError(error)}`);
         resolve({ sessionId: anchor, exitCode: null, isNew });
         return;
       }
@@ -332,8 +338,8 @@ export class KiroSpawner {
         if (text) this.logger.warn(`[Chorus] kiro-cli stderr: ${text}`);
       });
 
-      child.on("error", (err) => {
-        this.logger.error(`[Chorus] kiro-cli process error: ${err}`);
+      child.on("error", (error) => {
+        this.logger.error(`[Chorus] kiro-cli process error: ${safeSpawnError(error)}`);
         resolve({ sessionId: knownSessionId || anchor, exitCode: null, isNew });
       });
 
@@ -376,6 +382,7 @@ export class KiroSpawner {
             this.reconstructTranscript({
               sessionId: observedSessionId ?? "",
               cwd: runCwd,
+              dir: kiroSessionsDir(this.env, this.platform),
               onMessage,
               stdout: stdoutBuf,
               logger: this.logger,
@@ -407,7 +414,7 @@ export class KiroSpawner {
   /** Snapshot the store, swallowing any failure (best-effort id capture). */
   #safeSnapshot(cwd) {
     try {
-      return this.snapshotSessionsFn(cwd, { logger: this.logger });
+      return this.snapshotSessionsFn(cwd, { logger: this.logger, dir: kiroSessionsDir(this.env, this.platform) });
     } catch (err) {
       this.logger.warn(`[Chorus] kiro session snapshot failed (${err}) — id capture degraded`);
       return new Map();

package/cli/launch-diagnostics.mjs

@@ -0,0 +1,67 @@
+// Child-process error messages, paths, argv, code and syscall are untrusted.
+// Only emit known classifications for spawn failures; never echo raw fields.
+const SPAWN_CODES = new Map([
+  ["ENOENT", "executable or working directory not found; check PATH and cwd"],
+  ["EACCES", "permission denied; check executable and directory permissions"],
+  ["EPERM", "operation not permitted; check process permissions"],
+  ["ENOEXEC", "invalid executable format; check the installed binary"],
+  ["ENOTDIR", "path component is not a directory; check executable path and cwd"],
+  ["EINVAL", "invalid process options; check executable and launch configuration"],
+  ["E2BIG", "argument/environment size limit exceeded; reduce configuration size"],
+  ["ENOMEM", "insufficient memory to start process"],
+  ["EAGAIN", "process resource limit reached; retry or check system limits"],
+  ["EMFILE", "process file descriptor limit reached"],
+  ["ENFILE", "system file descriptor limit reached"],
+  ["ETIMEDOUT", "process startup timed out"],
+]);
+
+export function safeSpawnError(error) {
+  const code = error?.code;
+  return typeof code === "string" && SPAWN_CODES.has(code)
+    ? `${code}: ${SPAWN_CODES.get(code)}`
+    : "unclassified startup failure; check executable installation, PATH, cwd and permissions";
+}
+
+// Setup stderr can embed arbitrary argv/env in JSON, escaped nested errors,
+// URLs, or encodings we cannot enumerate. Substring replacement is NOT a safe
+// output boundary. Classify known problems, but render only these fixed strings
+// (never captures, original text, paths, codes, or even a "redacted" remainder).
+// Keep the patterns recognizable in our own output: setup and spawner both call
+// this helper, and the second boundary must retain the first one's useful hints.
+const SETUP_HINTS = [
+  [/version mismatch/i, "version mismatch; check dsh runtime and Chorus bundle compatibility"],
+  [/no adapter registered/i, "no adapter registered; check that the selected provider adapter is installed"],
+  [/invalid plugin graph/i, "invalid plugin graph; rebuild the sdk profile and check plugin compatibility"],
+  [/bad key|unauthorized|authentication failed/i, "authentication failed; check provider and Chorus credentials"],
+  [/ERR_PNPM.*offline|package registry unavailable/i, "package registry unavailable; check network access and pnpm registry configuration"],
+  [/bundle version/i, "bundle version required; check the installed Chorus version"],
+  [/requires the dsh CLI|dsh CLI was not found|dsh CLI required/i, "dsh CLI required; install dsh or set CHORUS_DSH_PATH"],
+  [/missing.*bundle layer/i, "missing Chorus bundle layer; rebuild the managed sdk profile"],
+  [/did not install|Chorus bundle not installed/i, "Chorus bundle not installed; check package installation and rebuild the managed sdk profile"],
+  [/did not complete JSON-RPC initialization/i, "did not complete JSON-RPC initialization; check the dsh sdk profile and runtime compatibility"],
+  [/unexpected server identity/i, "unexpected server identity; check that the sdk profile loads the expected dsh runtime"],
+];
+const SETUP_CODES = new Map([
+  ...SPAWN_CODES,
+  ["ENOSPC", "disk full; free space for the managed profile"],
+  ["EROFS", "read-only filesystem; use a writable managed profile home"],
+]);
+const SETUP_FALLBACK = "unclassified setup failure; check dsh installation, sdk profile, provider adapter, package registry and filesystem permissions (raw details withheld)";
+
+export function redactedSetupError(error) {
+  const text = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  const stages = [];
+  if (/profile installation failed/i.test(text)) stages.push("dsh managed profile installation failed");
+  if (/composition validation failed/i.test(text)) stages.push("dsh managed composition validation failed");
+  if (/non-default provider/i.test(text)) {
+    stages.push("a non-default provider is configured; the managed sdk profile mounts only the deepseek-official adapter; pre-compose its adapter and point CHORUS_DSH_HOME at your own sdk profile");
+  }
+  const hints = [];
+  for (const [code, hint] of SETUP_CODES) {
+    if (error?.code === code || new RegExp(`\\b${code}\\b`).test(text)) hints.push(`${code}: ${hint}`);
+  }
+  for (const [pattern, hint] of SETUP_HINTS) {
+    if (pattern.test(text)) hints.push(hint);
+  }
+  return [...stages, hints.length ? hints.join("; ") : SETUP_FALLBACK].join(": ");
+}

package/cli/login.mjs

@@ -10,6 +10,7 @@ import { createInterface } from "node:readline";
 import { loginFilePath } from "./credentials.mjs";
 import { validateAndFetchIdentity } from "./chorus-client.mjs";
 import { promptAgentBackend } from "./agent-backend-prompt.mjs";
+import { rejectSharedCliConfig } from "./agent-cli-config.mjs";
 
 /**
  * Prompt for a line of input. When `mask` is true, typed characters are not
@@ -177,9 +178,12 @@ export function appendAgentConfig(agentObj, deps = {}) {
     // treat as empty
   }
 
+  // Refuse already-misplaced customization before any write (even duplicates).
+  rejectSharedCliConfig(current);
   const existingAgents =
     Array.isArray(current.agents) ? current.agents.filter((a) => a && typeof a === "object") : [];
 
+  let migratedFlat = false;
   /** @type {object[]} */
   let agents;
   if (existingAgents.length > 0) {
@@ -192,6 +196,12 @@ export function appendAgentConfig(agentObj, deps = {}) {
     if (Array.isArray(current.cwds)) flat.cwds = current.cwds;
     if (nonEmpty(current.agentName)) flat.agentName = current.agentName;
     if (nonEmpty(current.agentUuid)) flat.agentUuid = current.agentUuid;
+    // Move by presence, not validity: later validation must attribute malformed
+    // values to the original agent rather than lose them or leave shared keys.
+    for (const field of ["args", "env"]) {
+      if (Object.hasOwn(current, field)) flat[field] = current[field];
+    }
+    migratedFlat = true;
     agents = [flat];
   } else {
     agents = [];
@@ -206,7 +216,13 @@ export function appendAgentConfig(agentObj, deps = {}) {
   }
 
   agents.push(agentObj);
-  const writtenPath = updateDaemonConfig({ agents }, deps);
+  // JSON serialization omits undefined keys; the existing temp-file rename
+  // commits the fold and top-level removal together in one atomic write.
+  const update = { agents, ...(migratedFlat ? { args: undefined, env: undefined } : {}) };
+  // A flat file without a key cannot be folded into an original agent. Do not
+  // turn that partial config into an invalid shared file by adding an agent.
+  if (!migratedFlat) rejectSharedCliConfig({ ...current, agents });
+  const writtenPath = updateDaemonConfig(update, deps);
   return { ok: true, path: writtenPath, agents, index: agents.length - 1 };
 }
 

package/cli/pi-spawner.mjs

@@ -38,6 +38,8 @@
 // PATH-walk / .cmd-shim shape of the other spawners' path resolution.
 
 import { spawn } from "node:child_process";
+import { safeSpawnError } from "./launch-diagnostics.mjs";
+import { validateAgentCliConfig, overlayAgentEnv, getAgentEnv, assertConfiguredShimArgs } from "./agent-cli-config.mjs";
 import { statSync } from "node:fs";
 import { win32 as pathWin32, posix as pathPosix } from "node:path";
 import { parseNdjsonChunk } from "./claude-spawner.mjs";
@@ -83,14 +85,15 @@ export function resolvePiPath(deps = {}) {
       }
     });
 
-  if (env.CHORUS_PI_PATH && isFile(env.CHORUS_PI_PATH)) {
-    return env.CHORUS_PI_PATH;
+  const override = getAgentEnv(env, "CHORUS_PI_PATH", platform);
+  if (override && isFile(override)) {
+    return override;
   }
 
   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 pathVar = getAgentEnv(env, "PATH", platform) || env.Path || "";
   const dirs = pathVar.split(p.delimiter).filter(Boolean);
   for (const dir of dirs) {
     for (const name of names) {
@@ -113,7 +116,7 @@ export function resolveSpawnCommand(piPath, args, platform = process.platform, e
   const isWin = platform === "win32";
   const lower = piPath.toLowerCase();
   if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
-    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    const comspec = getAgentEnv(env, "COMSPEC", platform) || "cmd.exe";
     return { command: comspec, argv: ["/d", "/s", "/c", piPath, ...args] };
   }
   return { command: piPath, argv: args };
@@ -150,6 +153,8 @@ export class PiSpawner {
     this.permissionMode = opts.permissionMode ?? "chorus";
     this.creds = opts.creds ?? null;
     this.platform = opts.platform ?? process.platform;
+    this.cliConfig = validateAgentCliConfig(opts.cliConfig, "pi", opts.label);
+    this.env = overlayAgentEnv(opts.env ?? process.env, this.cliConfig.env, this.platform);
     this.resolvePiPathFn = opts.resolvePiPathFn ?? resolvePiPath;
   }
 
@@ -174,7 +179,7 @@ export class PiSpawner {
     const anchor = typeof sessionId === "string" ? sessionId : "";
     const isNewFlag = Boolean(isNew);
 
-    const piPath = this.piPath ?? this.resolvePiPathFn();
+    const piPath = this.piPath ?? this.resolvePiPathFn({ env: this.env, platform: this.platform });
     if (!piPath) {
       // No crash — surface visibly and resolve with a failure result (matches the
       // other spawners' "skipping wake" convention: exitCode null, no throw).
@@ -182,8 +187,10 @@ export class PiSpawner {
       return { sessionId: anchor, backendSessionId: null, exitCode: null, isNew: isNewFlag };
     }
 
-    const args = buildPiArgs({ sessionId: anchor });
-    const { command, argv } = resolveSpawnCommand(piPath, args, this.platform);
+    assertConfiguredShimArgs(piPath, this.cliConfig.args, this.platform);
+    const fixed = buildPiArgs({ sessionId: anchor });
+    const args = [...fixed.slice(0, -1), ...this.cliConfig.args, fixed.at(-1)];
+    const { command, argv } = resolveSpawnCommand(piPath, args, this.platform, this.env);
 
     // 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
@@ -193,7 +200,7 @@ export class PiSpawner {
     // 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" };
+    const childEnv = { ...this.env, CHORUS_DAEMON_HEADLESS: "1" };
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
@@ -214,8 +221,8 @@ export class PiSpawner {
           detached,
           windowsHide: true,
         });
-      } catch (err) {
-        this.logger.error(`[Chorus] failed to spawn pi: ${err}`);
+      } catch (error) {
+        this.logger.error(`[Chorus] failed to spawn pi: ${safeSpawnError(error)}`);
         resolve({ sessionId: anchor, backendSessionId: null, exitCode: null, isNew: isNewFlag });
         return;
       }
@@ -256,8 +263,8 @@ export class PiSpawner {
         if (text) this.logger.warn(`[Chorus] pi stderr: ${text}`);
       });
 
-      child.on("error", (err) => {
-        this.logger.error(`[Chorus] pi process error: ${err}`);
+      child.on("error", (error) => {
+        this.logger.error(`[Chorus] pi process error: ${safeSpawnError(error)}`);
         resolve({ sessionId: anchor, backendSessionId: anchor || null, exitCode: null, isNew: isNewFlag });
       });
 

package/cli/prompts.mjs

@@ -26,6 +26,13 @@
  * @property {string} actorUuid
  * @property {string} actorName
  * @property {{type: string, uuid: string, name: string} | null} [orchestrator]
+ * @property {{agentUuid: string, agentName: string, ideaUuid: string} | null} [wakerSession]
+ *   Derived, NON-persisted waker-session anchor (wake-carry-waker-session-anchor, T1). Present
+ *   only for an agent-caused wake on an idea/task-anchored resource whose waking agent has a
+ *   live, ONLINE-origin session for that idea — it tells the woken peer that replying on this
+ *   resource reaches the waker's existing live session. A SIBLING of `orchestrator`
+ *   (actor-scoped vs assignment-scoped): either, both, or neither may be present. The server
+ *   supplies it on the `chorus_get_notifications` projection; the router threads it here.
  * @property {string} [instructionText]  Free-text body of a `human_instruction` wake
  *   (子1 — daemon-session-conversation). The server denormalizes the canonical turn
  *   promptText onto the wake notification so the daemon reads it in the
@@ -64,6 +71,37 @@ function orchestratorGuidance(n) {
   );
 }
 
+/**
+ * Waker-session advisory, appended to a wake body whenever the notification carries a
+ * `wakerSession` anchor (wake-carry-waker-session-anchor, T2). It tells the woken peer WHERE
+ * the waking agent's live conversation is: replying by commenting on THIS resource lands the
+ * reply back in that agent's existing idea-anchored session, keeping the exchange on one
+ * thread instead of scattering into a fresh one.
+ *
+ * It is deliberately ADVISORY, not routing — the server surfaces the anchor only when it
+ * resolved a live, ONLINE-origin waker session (an offline/missing waker degrades to
+ * notify-only and the field is null); there is no automatic subscription and nothing is
+ * force-delivered. The wording must NOT promise a guaranteed channel.
+ *
+ * A SIBLING of `orchestratorGuidance`: independent, appended alongside it in buildPrompt, so
+ * either/both/neither may render on one wake and they may name different agents. Its OpenClaw
+ * twin is `buildWakerSessionGuidance` in packages/openclaw-plugin/src/event-router.ts —
+ * KEEP THE TWO WORDINGS IN SYNC.
+ * @param {NotificationDetail} n
+ */
+function wakerSessionGuidance(n) {
+  if (!n.wakerSession) return null;
+  const { agentName, agentUuid } = n.wakerSession;
+  return (
+    `@[${agentName}](agent:${agentUuid}) woke you and has a live session open on this ` +
+    `resource. If you reply by commenting on this same resource, your reply reaches that ` +
+    `agent's live session, keeping the exchange on one thread. This is advisory, not an ` +
+    `enforced server route — there is no automatic subscription and nothing is force-delivered; ` +
+    `replying here is simply where a reply lands via the normal return path. Prefer replying ` +
+    `on this resource over opening a new session.`
+  );
+}
+
 /**
  * Shared headless preamble prepended to EVERY wake prompt (add-daemon-headless-
  * interaction-guard). A daemon-woken session is a headless `claude -p` run with no
@@ -121,7 +159,12 @@ export function buildPrompt(n) {
   const body = buildPromptBody(n);
   if (body == null) return null;
   const handoff = orchestratorGuidance(n);
-  return `${HEADLESS_PREAMBLE}\n\n${body}${handoff ? `\n\n${handoff}` : ""}`;
+  const anchor = wakerSessionGuidance(n);
+  return (
+    `${HEADLESS_PREAMBLE}\n\n${body}` +
+    (handoff ? `\n\n${handoff}` : "") +
+    (anchor ? `\n\n${anchor}` : "")
+  );
 }
 
 /**
@@ -208,7 +251,14 @@ export function buildBatchPrompt(notifications) {
         ? `\n(${g.count} ${n.action} events on this ${entityType} arrived — showing the newest ` +
           `below; earlier ones are re-derivable via the entity's own chorus_get_* tools.)`
         : "";
-    return `${header}${collapseNote}\n\n${g.body}`;
+    // Per-wake waker-session advisory (wake-carry-waker-session-anchor, T2). The anchor is
+    // ACTOR-scoped, so it belongs to each event individually — different queued wakes may
+    // carry different (or no) waker sessions. Appending it only in buildPrompt would silently
+    // drop it in this coalesced busy-worker batch, the feature's core scenario; so surface it
+    // per block here too, keyed off the collapsed group's newest notification.
+    const anchor = wakerSessionGuidance(n);
+    const anchorBlock = anchor ? `\n\n${anchor}` : "";
+    return `${header}${collapseNote}\n\n${g.body}${anchorBlock}`;
   });
 
   return [HEADLESS_PREAMBLE, backlogPreamble, ...rendered].join("\n\n");

package/cli/spawner-select.mjs

@@ -59,7 +59,7 @@ export class OfflineSpawner {
  * @returns {import("./codex-spawner.mjs").Spawner}
  */
 export function selectSpawner(agentType, opts = {}) {
-  const { logger, permissionMode, creds } = opts;
+  const { logger } = opts;
   if (agentType === "offline") {
     // Fail-closed: an offline agent has no local backend. Return the no-op spawner
     // explicitly so we NEVER fall through to the claude-code default below and wake
@@ -67,23 +67,18 @@ export function selectSpawner(agentType, opts = {}) {
     return new OfflineSpawner({ logger });
   }
   if (agentType === "codex") {
-    return new CodexSpawner({ logger, permissionMode, creds });
+    return new CodexSpawner(opts);
   }
   if (agentType === "kiro") {
-    return new KiroSpawner({ logger, permissionMode, creds });
+    return new KiroSpawner(opts);
   }
   if (agentType === "dsh") {
-    return new DshSpawner({
-      logger,
-      creds,
-      bundleVersion: opts.bundleVersion,
-      prepareManagedConfigFn: opts.prepareManagedConfigFn,
-    });
+    return new DshSpawner(opts);
   }
   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 PiSpawner(opts);
   }
-  return new ClaudeSpawner({ logger, permissionMode, creds });
+  return new ClaudeSpawner(opts);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "The Agent Harness for AI-Human Collaboration — session lifecycle, task state, sub-agent orchestration, observability, and failure recovery",
   "homepage": "https://github.com/Chorus-AIDLC/Chorus",
   "repository": {