@chorus-aidlc/chorus 0.17.2 → 0.18.0

package/cli/dsh-managed-config.mjs

@@ -1,4 +1,27 @@
+// Managed dsh profile composition for the daemon's `dsh --profile sdk` backend.
+//
+// dsh 0.1.2-rc.1 replaced the standalone `dsh-jsonrpc-agent` bin + hand-authored
+// `cordis.yml` (DSH_CORDIS_CONFIG) model with a profile launcher: `dsh --profile
+// sdk` boots the `sdk` profile under `$DSH_HOME/profiles/sdk` — an ordered stack
+// of plugin-bundle patch layers (dsh-base + dsh-sdk-app, the latter mounting the
+// `@deepseek-ai/dsh-sdk-jsonrpc-server` runtime that owns stdout). Chorus is a
+// native dsh bundle: `dsh plugin --profile sdk add @chorus-aidlc/chorus-dsh -w`
+// appends it to the profile's `dsh.profile.bundles` list, so its own
+// `cordis.patch.yml` (the chorus-dsh-lifecycle, chorus-mcp, chorus-skill-filesystem
+// and chorus-persona rows) auto-applies as a bundle layer — no `--patch` needed for
+// the Chorus rows, and pnpm auto-installs chorus-dsh's peers (mcp-client, persona,
+// skill-filesystem, tool-skill).
+//
+// The owner chose external_runtime: the `dsh` CLI itself comes from PATH /
+// CHORUS_DSH_PATH and is NEVER installed into the managed home. We only COMPOSE a
+// managed profile home under ~/.chorus/dsh/releases/<fingerprint>-<uuid>/ and hand
+// its path back as the child's DSH_HOME. Credentials reach the chorus-mcp row via
+// the CHORUS_URL / CHORUS_API_KEY the spawner injects into the child env (the
+// 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,
@@ -9,172 +32,24 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { createRequire } from "node:module";
-import { pathToFileURL } from "node:url";
+import { join } from "node:path";
 
 export const DSH_BUNDLE = "@chorus-aidlc/chorus-dsh";
-export const DSH_PEERS = Object.freeze([
-  "@deepseek-ai/dsh-mcp-client",
-  "@deepseek-ai/dsh-skill-filesystem",
-  "@deepseek-ai/dsh-tool-skill",
-  "@deepseek-ai/dsh-persona",
-]);
-export const DSH_RC_VERSION = "0.1.0-rc.7";
-export const MANAGED_CONFIG_FILE = "cordis.yml";
-
-// dsh-base supplies the core plugins used by the external JSON-RPC composition.
-// Hoisted linking makes those transitive plugins visible from the config anchor.
-const RUNTIME_PACKAGES = Object.freeze({
-  "@deepseek-ai/dsh-base": DSH_RC_VERSION,
-  "@deepseek-ai/dsh-agent-spine-demo": DSH_RC_VERSION,
-  "@deepseek-ai/dsh-sdk-jsonrpc-server": DSH_RC_VERSION,
-  "@deepseek-ai/dsh-sdk-jsonrpc-demo": DSH_RC_VERSION,
-  "@deepseek-ai/dsh-invariants": DSH_RC_VERSION,
-  "@deepseek-ai/cordis": "4.0.1",
-});
-const REQUIRED_IMPORTS = Object.freeze([DSH_BUNDLE, ...DSH_PEERS]);
-const STATE_VERSION = 1;
-
-const CONFIG_HEAD = `# Generated by Chorus. Secrets are read from the child environment.
-# This file is managed; use CHORUS_DSH_CONFIG or DSH_CORDIS_CONFIG to override it.
-
-- id: sdk-jsonrpc-server
-  name: '@deepseek-ai/dsh-sdk-jsonrpc-server'
-  config:
-    maxTokensAsSuccess: true
-
-- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    thinking: enabled
-    reasoningEffort: max
-
-- id: subprocess
-  name: '@deepseek-ai/dsh-subprocess-local'
-
-- id: bash
-  name: '@deepseek-ai/dsh-bash-local'
-  config:
-    cwd: !!js process.env.DSH_CWD ?? process.cwd()
-    timeoutMs: 60000
-
-- id: agent-spine
-  name: '@deepseek-ai/dsh-agent-spine-demo'
-  config:
-    persona: !!js process.env.DSH_SYSTEM_PROMPT ?? 'You are a coding agent.'
-    workspaceContext: false
-    skills:
-      enabled: false
-    toolBash:
-      enableRunInBackground: false
-    toolJobs: false
-
-- id: sessions
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
-  config:
-    root: !!js process.env.DSH_SESSION_ROOT ?? './.sessions'
-    compression: zstd
-
-- id: session-checkpoints
-  name: '@deepseek-ai/dsh-session-checkpoint-policy'
-
-- id: subagent
-  name: '@deepseek-ai/dsh-subagent'
-
-- id: subagent-spawn-in-process
-  name: '@deepseek-ai/dsh-subagent-spawn-in-process'
-  config:
-    providerName: spawn
-
-- id: tool-subagent
-  name: '@deepseek-ai/dsh-tool-subagent'
-  config:
-    provider: spawn
-    toolName: subagent
-    enableRunInBackground: false
-
-- id: tool-todo
-  name: '@deepseek-ai/dsh-tool-todo'
-  config:
-    allowParallelInProgress: true
-
-- id: fs-local
-  name: '@deepseek-ai/dsh-fs-local'
-  config:
-    cwd: !!js process.env.DSH_CWD ?? process.cwd()
-
-- id: fs-observation-policy
-  name: '@deepseek-ai/dsh-fs-observation-policy'
-
-- id: tool-fs
-  name: '@deepseek-ai/dsh-tool-fs'
-
-- id: token-meter
-  name: '@deepseek-ai/dsh-token-meter'
-
-- id: compaction-basic
-  name: '@deepseek-ai/dsh-compaction-basic'
-  config:
-    thresholdRatio: 0.8
-    retainRatio: 0.16
-    maxTokens: 8192
-    compactionRetries: 1
-
-- id: chorus-dsh-lifecycle
-  name: __CHORUS_BUNDLE__
-
-- id: chorus-mcp
-  name: '@deepseek-ai/dsh-mcp-client'
-  inject: [chorusDshConfig]
-  config:
-    serverName: chorus
-    transport: streamable-http
-    url: !!js '\`\${chorusDshConfig.url}/api/mcp\`'
-    headers:
-      Authorization: !!js '\`Bearer \${chorusDshConfig.apiKey}\`'
-    failOnStartupError: false
-    reconnect:
-      enabled: true
-
-- id: skill
-  name: '@deepseek-ai/dsh-skill'
-
-- id: chorus-skill-filesystem
-  name: '@deepseek-ai/dsh-skill-filesystem'
-  config:
-    providerName: chorus
-    includeDefaultRoots: false
-    customSkillDirs:
-      - !!js "process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('@chorus-aidlc/chorus-dsh/package.json')), 'skills')"
-
-- id: chorus-persona
-  name: __CHORUS_PERSONA__
-  config:
-    plugin: '@deepseek-ai/dsh-persona'
-    text: |-
-      You are a Chorus PM and developer agent powered by {{model}}. Work from {{cwd}}.
-      Use the Chorus AI-DLC lifecycle and load the relevant Chorus skill before operating
-      a Chorus resource. Keep decisions, progress, acceptance evidence, and review verdicts
-      on the assigned resource. In a headless daemon turn, never wait for terminal input:
-      persist human decisions through Chorus, mention the requester, and end the turn.
-      Do not push, merge, publish, approve, verify, or cross a human-owned gate unless the
-      wake explicitly grants that authority.
-
-- id: tool-skill
-  name: '@deepseek-ai/dsh-tool-skill'
-`;
-
-function errorText(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
-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;
+/** The shipped profile template the daemon boots: dsh-base + dsh-sdk-app. */
+export const DSH_PROFILE = "sdk";
+export const DSH_RC_VERSION = "0.1.2-rc.1";
+/** The JSON-RPC runtime identity the SDK profile reports on `initialize`. */
+export const RUNTIME_IDENTITY = "deepseek-harness-sdk-runtime";
+/** The provider served out-of-the-box by the base profile (no overlay needed). */
+export const DEFAULT_DSH_PROVIDER = "deepseek-official";
+
+// Bumped from 1: active.json now records a managed DSH_HOME (+ optional --patch
+// path) instead of a configPath/runtimePath pair. An old marker fails the shape
+// check in activeState() and is transparently re-prepared.
+const STATE_VERSION = 2;
+
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
 function readJson(path) {
@@ -185,86 +60,40 @@ function readJson(path) {
   }
 }
 
-function packageSpecs({ bundleVersion, bundleSpec }) {
-  return {
-    [DSH_BUNDLE]: bundleSpec ?? bundleVersion,
-    ...Object.fromEntries(DSH_PEERS.map((name) => [name, DSH_RC_VERSION])),
-    ...RUNTIME_PACKAGES,
-  };
-}
-
-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");
 }
 
-export function renderManagedDshConfig(bundleEntry = DSH_BUNDLE) {
-  const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
-  const personaEntry =
-    bundleEntry === DSH_BUNDLE ? `${DSH_BUNDLE}/persona` : join(dirname(bundleEntry), "persona.mjs");
-  const skillDir =
-    bundleEntry === DSH_BUNDLE
-      ? `"process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('@chorus-aidlc/chorus-dsh/package.json')), 'skills')"`
-      : quote(resolve(dirname(bundleEntry), "..", "skills"));
-  return CONFIG_HEAD
-    .replace("__CHORUS_BUNDLE__", quote(bundleEntry))
-    .replace("__CHORUS_PERSONA__", quote(personaEntry))
-    .replace(
-      `"process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('@chorus-aidlc/chorus-dsh/package.json')), 'skills')"`,
-      skillDir,
-    );
-}
-
-function resolveInstalledBundleEntry(projectDir) {
-  const pkgPath = join(projectDir, "node_modules", "@chorus-aidlc", "chorus-dsh", "package.json");
-  const pkg = readJson(pkgPath);
-  if (!pkg) return null;
-  const exported = pkg.exports?.["."]?.default ?? pkg.main;
-  return typeof exported === "string" ? resolve(dirname(pkgPath), exported) : null;
-}
-
-export async function validateManagedDshImports(projectDir, opts = {}) {
-  const requireFromConfig = createRequire(join(projectDir, MANAGED_CONFIG_FILE));
-  const resolveImport = opts.resolveImport ?? ((name) => requireFromConfig.resolve(name));
-  const importModule = opts.importModule ?? ((entry) => import(pathToFileURL(entry).href));
-  const resolved = {};
-  let usedBundleFallback = false;
-
-  for (const name of REQUIRED_IMPORTS) {
-    try {
-      resolved[name] = resolveImport(name);
-    } catch (error) {
-      if (name !== DSH_BUNDLE) {
-        throw new Error(`dsh managed import resolution failed for ${name}: ${errorText(error)}`);
-      }
-      const fallback =
-        opts.resolveBundleEntry?.(projectDir) ?? resolveInstalledBundleEntry(projectDir);
-      if (!fallback || !existsSync(fallback)) {
-        throw new Error(`dsh managed bundle resolution failed: ${errorText(error)}`);
-      }
-      resolved[name] = fallback;
-      usedBundleFallback = true;
-    }
-  }
-
-  for (const [name, entry] of Object.entries(resolved)) {
-    try {
-      await importModule(entry);
-    } catch (error) {
-      throw new Error(`dsh managed import load failed for ${name}: ${errorText(error)}`);
-    }
-  }
-  return {
-    resolved,
-    bundleEntry: resolved[DSH_BUNDLE],
-    usedBundleFallback,
-  };
+/**
+ * Build the optional `--patch` overlay for a non-default provider. The base
+ * profile serves `deepseek-official` unchanged, so that (and an empty value)
+ * yields `null` — no overlay, no `--patch`. For any other provider we emit a
+ * minimal overlay selecting it as the profile's default-model provider by
+ * targeting the base `agent-default-model` row (always present, so the tree
+ * still composes and the structural `initialize` probe still passes). Provider
+ * routing + credentials are exercised only on a live turn — a guarded extension
+ * point, not a verified path. Keep this small.
+ * @param {string} provider
+ * @returns {{ fileName: string, yaml: string } | null}
+ */
+export function buildProviderPatch(provider) {
+  const value = typeof provider === "string" ? provider.trim() : "";
+  if (!value || value === DEFAULT_DSH_PROVIDER) return null;
+  const yaml =
+    `# Chorus-generated provider overlay (CHORUS_DSH_PROVIDER=${value}).\n` +
+    `# Applied after the profile layer via \`dsh --profile ${DSH_PROFILE} --patch\`.\n` +
+    `- id: agent-default-model\n` +
+    `  config:\n` +
+    `    provider: ${JSON.stringify(value)}\n`;
+  return { fileName: "chorus-provider.patch.yml", yaml };
 }
 
+/** Windows npm/cmd shims need cmd.exe while retaining argv isolation. */
 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,
@@ -276,63 +105,163 @@ 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;
 }
 
-export function validateManagedDshComposition(configPath, opts = {}) {
+/**
+ * Probe the external dsh runtime version (`dsh --version`) so the managed-profile
+ * fingerprint invalidates when the operator upgrades the dsh CLI — a stale profile
+ * composed against an older runtime must not be silently reused (reuse alone never
+ * re-runs compose). Fail-soft: an unreadable version yields "unknown" (stable per
+ * install) and never blocks preparation. Injectable via opts.runtimeVersion.
+ * @returns {string}
+ */
+function resolveRuntimeVersion(dshPath, opts = {}) {
+  if (typeof opts.runtimeVersion === "string") return opts.runtimeVersion;
+  try {
+    const runner = opts.runCommand ?? runCommand;
+    const r = runner(dshPath, ["--version"], {
+      env: opts.env ?? process.env,
+      timeout: opts.versionTimeoutMs ?? 10_000,
+      platform: opts.platform,
+    });
+    return String(r.stdout ?? "").trim() || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Cheap structural check that a prepared home actually carries the composed
+ * profile: its manifest lists the Chorus bundle and the package is installed.
+ * Runs on both a fresh prepare and every reuse (fast — no dsh spawn).
+ * @param {string} home managed DSH_HOME
+ */
+export function validateManagedDshProfile(home, opts = {}) {
+  const pathExists = opts.profileExists ?? existsSync;
+  const readManifest = opts.readJson ?? readJson;
+  const profileDir = join(home, "profiles", DSH_PROFILE);
+  const manifest = readManifest(join(profileDir, "package.json"));
+  const bundles = manifest?.dsh?.profile?.bundles;
+  if (!Array.isArray(bundles) || !bundles.includes(DSH_BUNDLE)) {
+    throw new Error(`dsh managed profile is missing the ${DSH_BUNDLE} bundle layer`);
+  }
+  const bundlePkg = join(profileDir, "node_modules", ...DSH_BUNDLE.split("/"), "package.json");
+  if (!pathExists(bundlePkg)) {
+    throw new Error(`dsh managed profile did not install ${DSH_BUNDLE}`);
+  }
+  return { profileDir, bundles };
+}
+
+/**
+ * Drive one JSON-RPC `initialize` over stdin against `dsh --profile sdk` (with
+ * any provider `--patch`) and assert the SDK runtime answers with the expected
+ * identity. `initialize` makes no LLM/network call, so this needs no real
+ * credentials or provider routing — it structurally confirms the composed tree
+ * loads and the JSON-RPC server owns stdout. Probes with the CONFIGURED provider
+ * (+ its `--patch`) so a non-default provider whose LLM adapter is not mounted
+ * fails HERE at prepare (fail-fast) instead of silently at the first real wake.
+ * @param {string} home managed DSH_HOME
+ */
+export function validateManagedDshComposition(home, opts = {}) {
   const dshPath = opts.dshPath;
-  if (!dshPath) throw new Error("cannot validate dsh composition: dsh-jsonrpc-agent was not found");
-  const env = {
-    ...(opts.env ?? process.env),
+  if (!dshPath) throw new Error("cannot validate dsh composition: the dsh CLI was not found");
+  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_CORDIS_CONFIG: configPath,
-    DSH_CWD: dirname(configPath),
-  };
-  const request =
-    `${JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { cwd: dirname(configPath), provider: "deepseek-official", model: "deepseek-v4-flash" } })}\n`;
+    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",
+    id: 1,
+    method: "initialize",
+    params: { cwd: home, provider: opts.provider ?? DEFAULT_DSH_PROVIDER, model: "deepseek-v4-flash" },
+  })}\n`;
   const runner = opts.runCommand ?? runCommand;
-  const result = runner(dshPath, [], {
-    cwd: dirname(configPath),
+  const result = runner(dshPath, argv, {
+    cwd: home,
     env,
     input: request,
-    timeout: opts.timeoutMs ?? 20_000,
+    timeout: opts.timeoutMs ?? 30_000,
     platform: opts.platform,
   });
-  if (!String(result.stdout ?? "").includes('"id":1')) {
+  const stdout = String(result.stdout ?? "");
+  if (!stdout.includes('"id":1')) {
     throw new Error("dsh composition validation did not complete JSON-RPC initialization");
   }
+  if (!stdout.includes(RUNTIME_IDENTITY)) {
+    throw new Error("dsh composition validation returned an unexpected server identity");
+  }
 }
 
 function activeState(root, pathExists = existsSync) {
   const state = readJson(join(root, "active.json"));
-  if (
-    !state ||
-    state.version !== STATE_VERSION ||
-    typeof state.configPath !== "string" ||
-    typeof state.runtimePath !== "string"
-  ) return null;
-  return pathExists(state.configPath) && pathExists(state.runtimePath) ? state : null;
+  if (!state || state.version !== STATE_VERSION || typeof state.home !== "string") return null;
+  if (!pathExists(state.home)) return null;
+  if (state.patchPath && !pathExists(state.patchPath)) return null;
+  return state;
 }
 
+/**
+ * Ensure a validated managed dsh profile home exists and return where it lives.
+ * Reuses the last-known-good release when the fingerprint (profile + Chorus
+ * bundle spec + dsh RC + external dsh runtime version + provider) is unchanged;
+ * otherwise composes a fresh
+ * release in an isolated dir, validates it, and atomically flips active.json.
+ * A failed fresh prepare rolls back and leaves the prior marker intact.
+ *
+ * @returns {Promise<{ version:number, fingerprint:string, home:string,
+ *   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 specs = packageSpecs({ bundleVersion, bundleSpec: opts.bundleSpec });
+  const dshPath = opts.dshPath;
+  if (!dshPath) {
+    throw new Error("dsh managed preparation requires the dsh CLI (install dsh or set CHORUS_DSH_PATH)");
+  }
+  // Bundle spec passed to `dsh plugin --profile sdk add`. Defaults to the
+  // published `@chorus-aidlc/chorus-dsh@<appVersion>`. `CHORUS_DSH_BUNDLE_SPEC`
+  // overrides it with any pnpm-installable spec — a local package dir, a packed
+  // tarball, or a pinned version — so a pre-publish local build can be composed
+  // 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(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
+  // be rebuilt when the operator upgrades the CLI — the reuse path never re-runs
+  // compose, so without this a runtime upgrade would silently reuse a stale tree.
+  const runtimeVersion = resolveRuntimeVersion(dshPath, opts);
   const fingerprint = createHash("sha256")
-    .update(JSON.stringify({ version: STATE_VERSION, specs }))
+    .update(JSON.stringify({ version: STATE_VERSION, profile: DSH_PROFILE, bundleSpec, dshRc: DSH_RC_VERSION, runtimeVersion, provider }))
     .digest("hex")
     .slice(0, 16);
   const current = activeState(root, opts.statePathExists ?? existsSync);
 
   if (current?.fingerprint === fingerprint) {
-    await (opts.validateImports ?? validateManagedDshImports)(dirname(current.configPath), opts);
+    await (opts.validateProfile ?? validateManagedDshProfile)(current.home, opts);
     return { ...current, reused: true };
   }
 
@@ -340,59 +269,56 @@ export async function prepareManagedDshConfig(opts = {}) {
   const markerTmp = join(root, `.active-${randomUUID()}.json`);
   mkdirSync(releaseDir, { recursive: true });
   try {
-    writeFileSync(
-      join(releaseDir, "package.json"),
-      `${JSON.stringify({ private: true, type: "module", dependencies: specs }, null, 2)}\n`,
-      { mode: 0o600 },
-    );
-    writeFileSync(join(releaseDir, ".npmrc"), "node-linker=hoisted\n", { mode: 0o600 });
-
-    const install = opts.install ?? ((cwd) => runCommand(
-      opts.packageManager ?? (opts.platform === "win32" ? "pnpm.cmd" : "pnpm"),
-      ["install", "--prod", "--ignore-scripts", "--frozen-lockfile=false"],
-      { cwd, env, timeout: opts.installTimeoutMs ?? 120_000, platform: opts.platform },
+    // Compose the managed profile with the EXTERNAL dsh CLI: `dsh plugin
+    // --profile sdk add <bundle> -w`. `-w` is required — the profile dir is a
+    // pnpm workspace root, so pnpm refuses a bare `add` (ERR_PNPM_ADDING_TO_ROOT).
+    // This initializes profiles/sdk (base + sdk-app), appends the Chorus bundle
+    // to its bundle list, and installs it plus its peers.
+    const runner = opts.runCommand ?? runCommand;
+    const install = opts.install ?? ((home) => runner(
+      dshPath,
+      ["plugin", "--profile", DSH_PROFILE, "add", bundleSpec, "-w"],
+      { 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 package installation failed: ` +
-          redactedErrorText(error, [env.CHORUS_API_KEY, opts.creds?.apiKey]),
+        `dsh managed profile installation failed: ` + redactedSetupError(error),
       );
     }
 
-    const importResult = await (opts.validateImports ?? validateManagedDshImports)(releaseDir, opts);
-    const bundleEntry = importResult.usedBundleFallback ? importResult.bundleEntry : DSH_BUNDLE;
-    const configPath = join(releaseDir, MANAGED_CONFIG_FILE);
-    const runtimePath = join(
-      releaseDir,
-      "node_modules",
-      ".bin",
-      opts.platform === "win32" ? "dsh-jsonrpc-agent.cmd" : "dsh-jsonrpc-agent",
-    );
-    if (!(opts.runtimeExists ?? existsSync)(runtimePath)) {
-      throw new Error(`dsh managed runtime was not installed at ${runtimePath}`);
+    await (opts.validateProfile ?? validateManagedDshProfile)(releaseDir, opts);
+
+    let patchPath = null;
+    if (providerPatch) {
+      patchPath = join(releaseDir, providerPatch.fileName);
+      writeFileSync(patchPath, providerPatch.yaml, { mode: 0o600 });
     }
-    writeFileSync(configPath, renderManagedDshConfig(bundleEntry), { mode: 0o600 });
 
     try {
-      (opts.validateComposition ?? validateManagedDshComposition)(configPath, {
+      (opts.validateComposition ?? validateManagedDshComposition)(releaseDir, {
         ...opts,
-        dshPath: runtimePath,
+        dshPath,
+        provider,
+        patchPath,
       });
     } catch (error) {
+      const hint =
+        provider !== DEFAULT_DSH_PROVIDER
+          ? ` (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: ` +
-          redactedErrorText(error, [env.CHORUS_API_KEY, opts.creds?.apiKey]),
+        `dsh managed composition validation failed${hint}: ` + redactedSetupError(error),
       );
     }
 
     const state = {
       version: STATE_VERSION,
       fingerprint,
-      configPath,
-      bundleEntry,
-      runtimePath,
+      home: releaseDir,
+      patchPath,
+      runtimeVersion,
       validatedAt: new Date().toISOString(),
     };
     mkdirSync(root, { recursive: true });