@chorus-aidlc/chorus 0.17.3 → 0.18.0

package/cli/codex-spawner.mjs

@@ -27,6 +27,8 @@
 // stream parse) and the PATH-walk shape of resolveClaudePath.
 
 import { spawn } from "node:child_process";
+import { safeSpawnError } from "./launch-diagnostics.mjs";
+import { validateAgentCliConfig, overlayAgentEnv, getAgentEnv, assertConfiguredShimArgs } from "./agent-cli-config.mjs";
 import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, win32 as pathWin32, posix as pathPosix } from "node:path";
@@ -49,8 +51,9 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 export function hasChorusMcpServer(deps = {}) {
   const env = deps.env ?? process.env;
   const readFile = deps.readFile ?? readFileSync;
-  const home = deps.home ?? homedir();
-  const configPath = join(env.CODEX_HOME || join(home, ".codex"), "config.toml");
+  const platform = deps.platform ?? process.platform;
+  const home = deps.home ?? getAgentEnv(env, "HOME", platform) ?? getAgentEnv(env, "USERPROFILE", platform) ?? homedir();
+  const configPath = join(getAgentEnv(env, "CODEX_HOME", platform) || join(home, ".codex"), "config.toml");
   try {
     const config = readFile(configPath, "utf8");
     return /^\s*\[mcp_servers\.chorus\]\s*(?:#.*)?$/m.test(config);
@@ -148,14 +151,15 @@ export function resolveCodexPath(deps = {}) {
       }
     });
 
-  if (env.CHORUS_CODEX_PATH && isFile(env.CHORUS_CODEX_PATH)) {
-    return env.CHORUS_CODEX_PATH;
+  const override = getAgentEnv(env, "CHORUS_CODEX_PATH", platform);
+  if (override && isFile(override)) {
+    return override;
   }
 
   const isWin = platform === "win32";
   const p = isWin ? pathWin32 : pathPosix;
   const names = isWin ? ["codex.cmd", "codex.exe", "codex"] : ["codex"];
-  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) {
@@ -178,7 +182,7 @@ export function resolveSpawnCommand(codexPath, args, platform = process.platform
   const isWin = platform === "win32";
   const lower = codexPath.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", codexPath, ...args] };
   }
   return { command: codexPath, argv: args };
@@ -210,6 +214,8 @@ export class CodexSpawner {
     this.permissionMode = opts.permissionMode ?? "chorus";
     this.creds = opts.creds ?? null;
     this.platform = opts.platform ?? process.platform;
+    this.cliConfig = validateAgentCliConfig(opts.cliConfig, "codex", opts.label);
+    this.env = overlayAgentEnv(opts.env ?? process.env, this.cliConfig.env, this.platform);
     this.getThreadIdFn = opts.getThreadIdFn ?? defaultGetThreadId;
     this.setThreadIdFn = opts.setThreadIdFn ?? defaultSetThreadId;
     this.getUsageSnapshotFn = opts.getUsageSnapshotFn ?? defaultGetUsageSnapshot;
@@ -246,7 +252,7 @@ export class CodexSpawner {
     // instead of publishing the entire historical cumulative total.
     let needsUsageSeed = Boolean(knownThreadId && !previousUsage);
 
-    const codexPath = this.codexPath ?? this.resolveCodexPathFn();
+    const codexPath = this.codexPath ?? this.resolveCodexPathFn({ env: this.env, platform: this.platform });
     if (!codexPath) {
       // No crash — surface visibly and resolve with a failure result.
       this.logger.error("[Chorus] cannot locate the `codex` executable on PATH; skipping wake");
@@ -255,15 +261,17 @@ export class CodexSpawner {
 
     if (!this.mcpConfigChecked) {
       this.mcpConfigChecked = true;
-      if (!this.hasChorusMcpServerFn()) {
+      if (!this.hasChorusMcpServerFn({ env: this.env, platform: this.platform })) {
         this.logger.warn(
           "[Chorus] Codex config has no [mcp_servers.chorus] entry; wake will continue without Chorus MCP tools",
         );
       }
     }
 
-    const args = buildCodexArgs({ isNew, threadId: knownThreadId, permissionMode: this.permissionMode });
-    const { command, argv } = resolveSpawnCommand(codexPath, args, this.platform);
+    assertConfiguredShimArgs(codexPath, this.cliConfig.args, this.platform);
+    const args = [...buildCodexArgs({ isNew, threadId: knownThreadId, permissionMode: this.permissionMode }), ...this.cliConfig.args,
+      ...(this.cliConfig.args.length ? ["-"] : [])];
+    const { command, argv } = resolveSpawnCommand(codexPath, args, this.platform, this.env);
 
     // POSIX: detached process group so the interrupt path can group-kill the tree
     // (codex exec forks child shells for tools). Windows uses taskkill /T. stdio
@@ -273,7 +281,7 @@ export class CodexSpawner {
     // Export the daemon's resolved connection pair for both Codex MCP auth and
     // SessionStart hooks. Explicitly overwrite inherited values so the hook and
     // 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;
@@ -294,8 +302,8 @@ export class CodexSpawner {
           detached,
           windowsHide: true,
         });
-      } catch (err) {
-        this.logger.error(`[Chorus] failed to spawn codex: ${err}`);
+      } catch (error) {
+        this.logger.error(`[Chorus] failed to spawn codex: ${safeSpawnError(error)}`);
         resolve({ sessionId: anchor, backendSessionId: knownThreadId, exitCode: null, isNew });
         return;
       }
@@ -357,8 +365,8 @@ export class CodexSpawner {
         if (text) this.logger.warn(`[Chorus] codex stderr: ${text}`);
       });
 
-      child.on("error", (err) => {
-        this.logger.error(`[Chorus] codex process error: ${err}`);
+      child.on("error", (error) => {
+        this.logger.error(`[Chorus] codex process error: ${safeSpawnError(error)}`);
         resolve({ sessionId: anchor, backendSessionId: observedThreadId, exitCode: null, isNew });
       });
 

package/cli/credentials.mjs

@@ -19,6 +19,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { rejectSharedCliConfig } from "./agent-cli-config.mjs";
 
 /** Absolute path to the login file written by `chorus login`. */
 export function loginFilePath() {
@@ -425,6 +426,7 @@ export function resolveLaunchAgent(flags = {}, deps = {}) {
   const wanted = nonEmpty(flags.name) ?? nonEmpty(flags.agent) ?? nonEmpty(env.CHORUS_AGENT_PROFILE);
 
   const file = readJson(loginPath);
+  rejectSharedCliConfig(file);
   const agentEntries =
     file && Array.isArray(file.agents)
       ? file.agents.filter((a) => a && typeof a === "object")
@@ -448,6 +450,8 @@ export function resolveLaunchAgent(flags = {}, deps = {}) {
     agentUuid: nonEmpty(entry.agentUuid),
     agentName: nonEmpty(entry.agentName) ?? nonEmpty(entry.name),
     agentType: nonEmpty(entry.agentType),
+    args: entry.args,
+    env: entry.env,
   }));
   const labels = resolved.map((a) => a.label).join(", ");
 
@@ -479,6 +483,9 @@ export function resolveLaunchAgent(flags = {}, deps = {}) {
     agentUuid: selected.agentUuid,
     agentName: selected.agentName,
     agentType: selected.agentType,
+    // Validation uses the launcher's effective --type, not the stored classification.
+    args: selected.args,
+    env: selected.env,
     label: selected.label,
   };
 }

package/cli/daemon-config.mjs

@@ -18,6 +18,14 @@ import { isAbsolute, resolve as resolvePath } from "node:path";
 import { loginFilePath, resolveCredentials, resolveCredentialDefaults } from "./credentials.mjs";
 import { resolveAgentType, KNOWN_AGENTS } from "./daemon-agent.mjs";
 import { resolvePermissionMode } from "./daemon-permission-mode.mjs";
+import { rejectSharedCliConfig, validateAgentCliConfig } from "./agent-cli-config.mjs";
+
+/** Read only the flat profile customization; also used by the legacy startup path. */
+export function resolveFlatAgentCliConfig(type, deps = {}) {
+  const file = (deps.readJson ?? readJsonSafe)(deps.loginPath ?? loginFilePath());
+  rejectSharedCliConfig(file);
+  return validateAgentCliConfig(file ?? {}, type, "agent");
+}
 
 /** Built-in default escalation window (ms) — matches the spec's 10 seconds. */
 export const DEFAULT_SIGINT_TIMEOUT_MS = 10_000;
@@ -307,6 +315,8 @@ function positiveInt(value) {
  * @property {string} url                       Chorus server URL for this agent.
  * @property {string} apiKey                    This agent's `cho_` API key.
  * @property {string} agentType                 Backend: claude-code | codex | kiro | dsh | offline.
+ * @property {string[]} args                   Literal extra backend arguments (per-agent only).
+ * @property {Record<string,string>} env       Literal child environment overrides (per-agent only).
  * @property {boolean} [daemonWake]             Wake opt-in for a wakeable backend; only
  *                                              `false` disables (absent/true ⇒ woken).
  * @property {Array<string|undefined>} cwds     Served paths (`undefined` ⇒ process cwd).
@@ -344,6 +354,8 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
   const home = deps.home ?? homedir();
   const file = readJson(loginPath);
 
+  rejectSharedCliConfig(file);
+
   // Global default permission posture; a per-agent `permissionMode` overrides it.
   // needConfirm/hasAck is vestigial, so isTTY/hasAck do not affect the resolved mode.
   const defaultPermissionMode =
@@ -365,6 +377,7 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
         url: creds.url,
         apiKey: creds.apiKey,
         agentType: at.agent,
+        ...validateAgentCliConfig(file ?? {}, at.agent, "agent"),
         cwds: resolveDaemonCwds(flags, deps),
         permissionMode: defaultPermissionMode,
         maxConcurrency: positiveInt(file?.maxConcurrency) ?? DEFAULT_MAX_CONCURRENCY,
@@ -449,6 +462,7 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
       url,
       apiKey,
       agentType,
+      ...validateAgentCliConfig(entry, agentType, label),
       cwds,
       permissionMode,
       maxConcurrency,

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";
@@ -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,
@@ -664,6 +671,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 +871,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 +911,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 +972,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 +1025,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 +1092,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,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";
@@ -36,13 +38,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 +60,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 +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],
     };
   }
@@ -139,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);
@@ -150,7 +153,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 +168,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 +181,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 +220,7 @@ export class DshSpawner {
       "--profile",
       "sdk",
       ...(patchPath ? ["--patch", patchPath] : []),
+      ...this.cliConfig.args,
     ];
     let child;
     try {
@@ -225,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);
     }
 
@@ -367,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
  */