@chorus-aidlc/chorus 0.17.3 → 0.18.1

package/cli/daemon.mjs

@@ -40,12 +40,13 @@ import { EventRouter } from "./event-router.mjs";
 import { WakeQueue } from "./wake-queue.mjs";
 import { Waker } from "./waker.mjs";
 import { LineageResolver } from "./lineage.mjs";
-import { resolveClaudePath } from "./claude-spawner.mjs";
+import { resolveClaudePath, isNewSession } from "./claude-spawner.mjs";
 import { resolveCodexPath } from "./codex-spawner.mjs";
 import { resolveDshPath } from "./dsh-spawner.mjs";
 import { prepareManagedDshConfig } from "./dsh-managed-config.mjs";
 import { resolveKiroPath } from "./kiro-spawner.mjs";
 import { selectSpawner } from "./spawner-select.mjs";
+import { overlayAgentEnv } from "./agent-cli-config.mjs";
 import {
   createExecutionUploadHooks,
   createTranscriptUploadHooks,
@@ -61,6 +62,7 @@ import {
   resolveDaemonCwds,
   resolveBrowseRoots,
   resolveAgentConfigs,
+  resolveFlatAgentCliConfig,
   hasConfiguredAgents,
 } from "./daemon-config.mjs";
 import { discoverDirectories, validateDirectory } from "./directory-discovery.mjs";
@@ -124,7 +126,7 @@ function defaultLogger() {
  *   maxConcurrency?: number,
  *   permissionMode?: "chorus"|"yolo",
  *   reportInterrupt?: (entityType: string, entityUuid: string, reason: "user"|"crash") => Promise<void>,
- *   advanceTurn?: (params: { sessionId: string, status: "running"|"ended", entityType?: string|null, entityUuid?: string|null }) => Promise<void>,
+ *   advanceTurn?: (params: { sessionId: string, status: "running"|"ended"|"interrupted", interruptedReason?: "user"|"crash"|"shutdown"|"invalid_path"|null, entityType?: string|null, entityUuid?: string|null }) => Promise<void>,
  *   sigintTimeoutMs?: number,
  * }} [deps]
  */
@@ -157,6 +159,10 @@ export function buildDaemon(creds, deps = {}) {
   // passed through so the Codex backend can export the daemon key into the woken
   // process env (the Claude backend ignores creds — it gets its key via --mcp-config).
   const spawner = deps.spawner ?? selectSpawner(agentType, {
+    ...deps.spawnerOptions,
+    cliConfig: deps.cliConfig,
+    env: deps.env,
+    label: deps.label,
     logger,
     permissionMode,
     creds,
@@ -306,6 +312,7 @@ export function buildDaemon(creds, deps = {}) {
         creds,
         lineage,
         spawner,
+        isNewSessionFn: (sessionId, runCwd) => isNewSession(sessionId, runCwd, { env: spawner.env, platform: spawner.platform }),
         cwd: boundCwd,
         hooks,
         logger,
@@ -423,6 +430,10 @@ export function buildDaemon(creds, deps = {}) {
       sigintTimeoutMs,
       redispatchResume,
       deliverTurn,
+      // The SAME turn reporter the wakers use (declared above and passed into
+      // makeWaker) — one transport, so a no-child interrupt can close the
+      // server-side `running` turn (fix-phantom-running-turn, Tech Design D).
+      advanceTurn,
       handleDirectoryRequest: async (event) => {
         if (event.operation === "roots") {
           return { roots: [...browseRoots] };
@@ -664,6 +675,8 @@ export function buildMultiAgentDaemon(agentConfigs, deps = {}) {
         logger,
         permissionMode: cfg.permissionMode,
         agentType: cfg.agentType,
+        cliConfig: { args: cfg.args, env: cfg.env },
+        label: cfg.label,
         cwds: cfg.cwds,
         cwd: undefined,
         maxConcurrency: cfg.maxConcurrency,
@@ -862,6 +875,19 @@ export async function runDaemon(flags = {}, deps = {}) {
     return handleLifecycleAction(action, { log, errLog, lifecycle, service, pfDeps });
   }
 
+  // Validate flat customization before credential/network preflight, including
+  // the detach path. Lifecycle-only actions above do not launch an agent.
+  const multiAgent = hasConfiguredAgents({ readJson: deps.readJson, loginPath: deps.loginPath });
+  let cliConfig;
+  if (!multiAgent) {
+    try {
+      cliConfig = resolveFlatAgentCliConfig(agentType, { readJson: deps.readJson, loginPath: deps.loginPath });
+    } catch (error) {
+      errLog(`[Chorus] ${error.message}`);
+      return 1;
+    }
+  }
+
   // `-d` / --detach: complete any interactive preflight in THIS foreground process
   // (which holds the TTY), then spawn the daemon detached and return. The detached
   // child re-enters runDaemon with the DETACHED_ENV marker set, so it skips the
@@ -889,7 +915,7 @@ export async function runDaemon(flags = {}, deps = {}) {
   // credential preflight (interactive credential completion is a single-agent
   // affordance). Each agent authenticates on its own key; a failure is isolated
   // (logged + that agent skipped) so the rest still serve.
-  if (hasConfiguredAgents({ readJson: deps.readJson, loginPath: deps.loginPath })) {
+  if (multiAgent) {
     const buildMulti = deps.buildMulti ?? buildMultiAgentDaemon;
     let agentConfigs;
     try {
@@ -950,6 +976,7 @@ export async function runDaemon(flags = {}, deps = {}) {
     const multiDaemon = buildMulti(okConfigs, {
       logger: { info: log, warn: errLog, error: errLog },
       verbose,
+      env,
       fetchImpl: deps.fetchImpl,
       killer: deps.killer,
       sseListener: deps.sseListener,
@@ -1002,14 +1029,15 @@ export async function runDaemon(flags = {}, deps = {}) {
   // arrives. The resolved path (or absence) is shown in the banner below. Each
   // backend probes its own binary, including the `dsh` CLI for dsh, so the
   // startup banner and warning report the selected runtime rather than Claude.
+  const discoveryEnv = overlayAgentEnv(env, cliConfig.env);
   const cliPath =
     agentType === "codex"
-      ? findCodex()
+      ? findCodex({ env: discoveryEnv })
       : agentType === "kiro"
-        ? findKiro()
+        ? findKiro({ env: discoveryEnv })
         : agentType === "dsh"
-          ? findDsh()
-          : findClaude();
+          ? findDsh({ env: discoveryEnv })
+          : findClaude({ env: discoveryEnv });
 
   // The daemon.json the layered config readers (credentials, sigint timeout, cwds)
   // consult. Surfacing its absolute path + presence in the banner makes it obvious
@@ -1068,6 +1096,8 @@ export async function runDaemon(flags = {}, deps = {}) {
     logger: { info: log, warn: errLog, error: errLog },
     permissionMode,
     agentType,
+    cliConfig,
+    env,
     verbose,
     sigintTimeoutMs,
     cwds,

package/cli/dsh-managed-config.mjs

@@ -20,6 +20,8 @@
 // chorus-dsh-lifecycle plugin's documented fallback also reads $DSH_HOME/.env).
 
 import { spawnSync } from "node:child_process";
+import { safeSpawnError, redactedSetupError } from "./launch-diagnostics.mjs";
+import { getAgentEnv, overlayAgentEnv } from "./agent-cli-config.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import {
   existsSync,
@@ -46,22 +48,10 @@ export const DEFAULT_DSH_PROVIDER = "deepseek-official";
 // check in activeState() and is transparently re-prepared.
 const STATE_VERSION = 2;
 
-function errorText(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function nonEmpty(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-function redactedErrorText(error, values = []) {
-  let text = errorText(error);
-  for (const value of values) {
-    if (typeof value === "string" && value) text = text.replaceAll(value, "[REDACTED]");
-  }
-  return text;
-}
-
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -70,8 +60,8 @@ function readJson(path) {
   }
 }
 
-export function managedDshRoot(env = process.env) {
-  const home = env.HOME || env.USERPROFILE || homedir();
+export function managedDshRoot(env = process.env, platform = process.platform) {
+  const home = getAgentEnv(env, "HOME", platform) || getAgentEnv(env, "USERPROFILE", platform) || homedir();
   return join(home, ".chorus", "dsh");
 }
 
@@ -103,7 +93,7 @@ export function buildProviderPatch(provider) {
 function runCommand(command, argv, opts) {
   const platform = opts.platform ?? process.platform;
   const isCmd = platform === "win32" && /\.(cmd|bat)$/i.test(command);
-  const executable = isCmd ? opts.env?.ComSpec || opts.env?.COMSPEC || "cmd.exe" : command;
+  const executable = isCmd ? getAgentEnv(opts.env ?? process.env, "COMSPEC", platform) || "cmd.exe" : command;
   const commandArgs = isCmd ? ["/d", "/s", "/c", command, ...argv] : argv;
   const result = spawnSync(executable, commandArgs, {
     cwd: opts.cwd,
@@ -115,7 +105,7 @@ function runCommand(command, argv, opts) {
     windowsHide: true,
   });
   if (result.error || result.status !== 0) {
-    const detail = result.error?.message || result.stderr?.trim() || `exit ${result.status}`;
+    const detail = result.error ? safeSpawnError(result.error) : result.stderr?.trim() || `exit ${result.status}`;
     throw new Error(detail);
   }
   return result;
@@ -179,14 +169,13 @@ export function validateManagedDshProfile(home, opts = {}) {
 export function validateManagedDshComposition(home, opts = {}) {
   const dshPath = opts.dshPath;
   if (!dshPath) throw new Error("cannot validate dsh composition: the dsh CLI was not found");
-  const env = {
-    ...(opts.env ?? process.env),
+  const env = overlayAgentEnv(opts.env ?? process.env, {
     CHORUS_DAEMON_HEADLESS: "1",
     CHORUS_URL: opts.creds?.url ?? "http://127.0.0.1",
     CHORUS_API_KEY: opts.creds?.apiKey ?? "cho_validation",
     DSH_HOME: home,
     DSH_CWD: home,
-  };
+  }, opts.platform);
   const argv = ["--profile", DSH_PROFILE, ...(opts.patchPath ? ["--patch", opts.patchPath] : [])];
   const request = `${JSON.stringify({
     jsonrpc: "2.0",
@@ -231,8 +220,19 @@ function activeState(root, pathExists = existsSync) {
  *   patchPath:(string|null), validatedAt:string, reused:boolean }>}
  */
 export async function prepareManagedDshConfig(opts = {}) {
+  try {
+    return await prepareManagedDshConfigInternal(opts);
+  } catch (error) {
+    // Cover every failure path, including reuse validation and filesystem errors.
+    // Only fixed classifications/hints cross this boundary, never raw stderr.
+    throw new Error(redactedSetupError(error));
+  }
+}
+
+async function prepareManagedDshConfigInternal(opts) {
   const env = opts.env ?? process.env;
-  const root = opts.root ?? managedDshRoot(env);
+  const platform = opts.platform ?? process.platform;
+  const root = opts.root ?? managedDshRoot(env, platform);
   const bundleVersion = opts.bundleVersion;
   if (!bundleVersion) throw new Error("dsh managed preparation requires a Chorus bundle version");
   const dshPath = opts.dshPath;
@@ -246,8 +246,8 @@ export async function prepareManagedDshConfig(opts = {}) {
   // and tested end-to-end against a real dsh runtime without publishing first.
   // Unset in production. `opts.bundleSpec` (tests) still wins over the env.
   const bundleSpec =
-    opts.bundleSpec ?? nonEmpty(env.CHORUS_DSH_BUNDLE_SPEC) ?? `${DSH_BUNDLE}@${bundleVersion}`;
-  const provider = nonEmpty(env.CHORUS_DSH_PROVIDER) ?? nonEmpty(env.DSH_PROVIDER) ?? DEFAULT_DSH_PROVIDER;
+    opts.bundleSpec ?? nonEmpty(getAgentEnv(env, "CHORUS_DSH_BUNDLE_SPEC", platform)) ?? `${DSH_BUNDLE}@${bundleVersion}`;
+  const provider = nonEmpty(getAgentEnv(env, "CHORUS_DSH_PROVIDER", platform)) ?? nonEmpty(getAgentEnv(env, "DSH_PROVIDER", platform)) ?? DEFAULT_DSH_PROVIDER;
   const providerPatch = buildProviderPatch(provider);
   // Bind the fingerprint to the ACTUAL external dsh runtime version: peers are a
   // lenient range now, so a managed profile composed against an older `dsh` must
@@ -278,14 +278,13 @@ export async function prepareManagedDshConfig(opts = {}) {
     const install = opts.install ?? ((home) => runner(
       dshPath,
       ["plugin", "--profile", DSH_PROFILE, "add", bundleSpec, "-w"],
-      { cwd: home, env: { ...env, DSH_HOME: home }, timeout: opts.installTimeoutMs ?? 300_000, platform: opts.platform },
+      { cwd: home, env: overlayAgentEnv(env, { DSH_HOME: home }, platform), timeout: opts.installTimeoutMs ?? 300_000, platform: opts.platform },
     ));
     try {
       install(releaseDir);
     } catch (error) {
       throw new Error(
-        `dsh managed profile installation failed: ` +
-          redactedErrorText(error, [env.CHORUS_API_KEY, opts.creds?.apiKey]),
+        `dsh managed profile installation failed: ` + redactedSetupError(error),
       );
     }
 
@@ -307,11 +306,10 @@ export async function prepareManagedDshConfig(opts = {}) {
     } catch (error) {
       const hint =
         provider !== DEFAULT_DSH_PROVIDER
-          ? ` (provider "${provider}" is non-default — the managed sdk profile mounts only the ${DEFAULT_DSH_PROVIDER} adapter; a custom provider needs its adapter pre-composed, e.g. point CHORUS_DSH_HOME at your own sdk profile)`
+          ? ` (a non-default provider is configured — the managed sdk profile mounts only the ${DEFAULT_DSH_PROVIDER} adapter; a custom provider needs its adapter pre-composed, e.g. point CHORUS_DSH_HOME at your own sdk profile)`
           : "";
       throw new Error(
-        `dsh managed composition validation failed${hint}: ` +
-          redactedErrorText(error, [env.CHORUS_API_KEY, opts.creds?.apiKey]),
+        `dsh managed composition validation failed${hint}: ` + redactedSetupError(error),
       );
     }
 

package/cli/dsh-spawner.mjs

@@ -2,10 +2,13 @@
 // 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";
 import { prepareManagedDshConfig } from "./dsh-managed-config.mjs";
+import { awaitChildSettled } from "./child-exit.mjs";
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 export const DEFAULT_DSH_TIMEOUT_MS = 30 * 60 * 1000;
@@ -36,13 +39,13 @@ 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.cmd", "dsh.exe", "dsh"] : ["dsh"];
-  const dirs = (env.PATH || env.Path || "").split(path.delimiter).filter(Boolean);
+  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);
@@ -58,8 +61,8 @@ export function resolveDshPath(deps = {}) {
  * 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) {
-  return nonEmpty(env.CHORUS_DSH_HOME);
+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. */
@@ -67,7 +70,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],
     };
   }
@@ -139,7 +142,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);
@@ -150,7 +154,7 @@ export class DshSpawner {
 
   async wake({ prompt, sessionId: anchor, cwd, onMessage, onChild }) {
     const dshPath = this.dshPath ?? this.resolveDshPathFn({ env: this.env, platform: this.platform });
-    let dshHome = resolveDshHome(this.env);
+    let dshHome = resolveDshHome(this.env, this.platform);
     let patchPath = null;
     const result = (backendSessionId, exitCode) => ({
       sessionId: backendSessionId || anchor || "",
@@ -165,10 +169,12 @@ export class DshSpawner {
       );
       return result(null, null);
     }
+    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,
@@ -176,22 +182,24 @@ export class DshSpawner {
         dshHome = managed.home;
         patchPath = managed.patchPath ?? null;
       } catch (error) {
-        this.logger.error(`[Chorus] cannot prepare managed dsh profile: ${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_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
@@ -213,6 +221,7 @@ export class DshSpawner {
       "--profile",
       "sdk",
       ...(patchPath ? ["--patch", patchPath] : []),
+      ...this.cliConfig.args,
     ];
     let child;
     try {
@@ -225,7 +234,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);
     }
 
@@ -367,8 +376,10 @@ export class DshSpawner {
         if (line) this.logger.warn(`[dsh] ${line}`);
       }
     });
-    child.on?.("error", (error) => fail(`dsh runtime process error: ${errorText(error)}`));
-    child.on?.("close", (code) => {
+    child.on?.("error", (error) => fail(`dsh runtime process error: ${safeSpawnError(error)}`));
+    // Settle on process exit, not only on stdio close: a detached descendant can
+    // inherit the pipes and keep `close` from ever firing (see cli/child-exit.mjs).
+    awaitChildSettled(child, { logger: this.logger, label: "dsh" }).then((code) => {
       closeSeen = true;
       exitCode = code;
       if (stderrBuffer.trim()) this.logger.warn(`[dsh] ${stderrBuffer.trim()}`);

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,17 +28,20 @@
 // 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";
 import { getSessionId as defaultGetSessionId, setSessionId as defaultSetSessionId } from "./kiro-session-map.mjs";
 import { reconstructTranscript as defaultReconstructTranscript } from "./kiro-transcript.mjs";
+import { awaitChildSettled } from "./child-exit.mjs";
 
 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 +99,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 +130,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 +233,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 +266,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 +284,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 +310,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,12 +339,14 @@ 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 });
       });
 
-      child.on("close", (code) => {
+      // Settle on process exit, not only on stdio close: a detached descendant can
+      // inherit the pipes and keep `close` from ever firing (see cli/child-exit.mjs).
+      awaitChildSettled(child, { logger: this.logger, label: "kiro-cli" }).then((code) => {
         if (code !== 0) {
           this.logger.warn(`[Chorus] kiro-cli exited with code ${code}`);
         }
@@ -376,6 +385,7 @@ export class KiroSpawner {
             this.reconstructTranscript({
               sessionId: observedSessionId ?? "",
               cwd: runCwd,
+              dir: kiroSessionsDir(this.env, this.platform),
               onMessage,
               stdout: stdoutBuf,
               logger: this.logger,
@@ -407,7 +417,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(": ");
+}