@ran-sh/dsh-crew 1.5.1 → 1.6.1

package/src/install/install-legacy.mjs

@@ -1,739 +1,728 @@
-// One-click installers: register the Claude Code plugin persistently and
-// render Codex agent roles with real paths. Called from the CLI entry or the
-// DSH settings page. All edits are backed up and idempotent.
-
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, readdirSync, rmSync, statSync, lstatSync } from 'node:fs';
-import { createHash } from 'node:crypto';
-import { dirname, join, resolve, relative } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
-import { normalizeModelPriority } from '../model-routing.mjs';
-import { zcodeStatus } from './zcode.mjs';
-
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
-const MARKETPLACE_NAME = 'dsh-crew';
-const PLUGIN_KEY = `dsh-crew@${MARKETPLACE_NAME}`;
-const POLICY_START = '<!-- DSH CREW MANAGED POLICY:START -->';
-const POLICY_END = '<!-- DSH CREW MANAGED POLICY:END -->';
-
-/**
- * The directory Codex actually reads.
- *
- * Codex honours `CODEX_HOME` and falls back to `~/.codex`; writing only to the
- * latter silently does nothing for anyone who set it — the registration stays
- * frozen on whatever release was current when they set it, while every install
- * reports success because the file it wrote really did change. Resolve the same
- * way Codex does, and treat an empty or whitespace value as unset.
- */
-export function codexHomeDir(home = homedir(), env = process.env) {
-  const override = typeof env?.CODEX_HOME === 'string' ? env.CODEX_HOME.trim() : '';
-  return override ? resolve(override) : join(home, '.codex');
-}
-export const CODEX_LEGACY_POLICY_HASHES = Object.freeze([
-  '2d6f3839bb3df4bda90f481726281292b1a4b4585298b1cf9ec56215295b5c78',
-]);
-// dsh_worker_config is included so the session commands (/dsh-crew:config,
-// /dsh-config) and any orchestrator policy lookup run without an extra
-// authorization prompt.
-export const MCP_TOOLS = ['dsh_run_worker', 'dsh_spawn_worker', 'dsh_worker_status', 'dsh_worker_result', 'dsh_worker_cancel', 'dsh_worker_config'];
-
-function backup(file) {
-  if (existsSync(file)) {
-    const bak = `${file}.dsh-crew-backup-${Date.now()}`;
-    copyFileSync(file, bak);
-    return bak;
-  }
-  return null;
-}
-
-function readJson(file, fallback) {
-  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return fallback; }
-}
-
-function readText(file) {
-  try { return readFileSync(file, 'utf8'); } catch { return null; }
-}
-
-function normalizedPath(value) {
-  if (typeof value !== 'string' || !value.trim()) return null;
-  try {
-    const path = resolve(value);
-    return process.platform === 'win32' ? path.toLowerCase() : path;
-  } catch { return null; }
-}
-
-function renderedCodexRole(root, file) {
-  const source = readText(join(root, 'codex', 'agents', file));
-  if (source === null) return null;
-  const renderedPath = join(root, 'src', 'server.mjs').replace(/\\/g, '/');
-  return source.replace(/args = \[.*server\.mjs"\]/, `args = ["${renderedPath}"]`);
-}
-
-function managedPolicyBlock(root) {
-  const policy = readText(join(root, 'codex', 'AGENTS.md'))?.trim();
-  if (!policy) return null;
-  return `${POLICY_START}\n${policy}\n${POLICY_END}`;
-}
-
-export function codexLegacyPolicyDigest(text) {
-  const canonical = typeof text === 'string' ? text.replace(/\r\n/g, '\n').trim() : '';
-  return canonical ? createHash('sha256').update(canonical, 'utf8').digest('hex') : null;
-}
-
-export function stripKnownLegacyCodexPolicy(text, { knownHashes = CODEX_LEGACY_POLICY_HASHES } = {}) {
-  if (typeof text !== 'string') return text;
-  const start = POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const end = POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const match = new RegExp(`${start}[\\s\\S]*?${end}`, 'm').exec(text);
-  if (!match) return text;
-  const allowed = new Set(Array.isArray(knownHashes) ? knownHashes : []);
-  const prefix = text.slice(0, match.index);
-  const suffix = text.slice(match.index + match[0].length);
-  const keptPrefix = allowed.has(codexLegacyPolicyDigest(prefix)) ? '' : prefix;
-  const keptSuffix = allowed.has(codexLegacyPolicyDigest(suffix)) ? '' : suffix;
-  return `${keptPrefix}${match[0]}${keptSuffix}`;
-}
-
-function installGlobalCodexPolicy({ home, root, env = process.env }) {
-  const file = join(codexHomeDir(home, env), 'AGENTS.md');
-  const block = managedPolicyBlock(root);
-  if (!block) return { ok: false, action: 'global policy template missing' };
-  mkdirSync(dirname(file), { recursive: true });
-  const current = readText(file) ?? '';
-  const managed = new RegExp(`${POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
-  const template = readText(join(root, 'codex', 'AGENTS.md'))?.trim() ?? '';
-  let next;
-  if (managed.test(current)) next = current.replace(managed, block);
-  else if (current.trim() === template) next = `${block}\n`;
-  else next = `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`;
-  next = stripKnownLegacyCodexPolicy(next);
-  if (next !== current) {
-    backup(file);
-    writeFileSync(file, next);
-  }
-  return { ok: true, action: `global policy: ${file}` };
-}
-
-function globalCodexPolicyReady({ home, root = ROOT, env = process.env }) {
-  const block = managedPolicyBlock(root);
-  const text = readText(join(codexHomeDir(home, env), 'AGENTS.md'));
-  return !!block && typeof text === 'string' && text.includes(block);
-}
-
-function uninstallGlobalCodexPolicy({ home, env = process.env }) {
-  const file = join(codexHomeDir(home, env), 'AGENTS.md');
-  const current = readText(file);
-  if (typeof current !== 'string') return null;
-  const managed = new RegExp(`(?:\\r?\\n){0,2}${POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\r?\\n)?`, 'm');
-  if (!managed.test(current)) return null;
-  const next = current.replace(managed, '').trimEnd();
-  backup(file);
-  if (next.trim()) writeFileSync(file, `${next}\n`);
-  else rmSync(file);
-  return `codex global policy: removed managed block`;
-}
-
-function tomlSection(text, name) {
-  if (typeof text !== 'string') return null;
-  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const header = new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`, 'm').exec(text);
-  if (!header) return null;
-  const rest = text.slice(header.index + header[0].length);
-  const nextHeader = rest.search(/^\s*\[[^\]\r\n]+\]\s*(?:#.*)?$/m);
-  return nextHeader === -1 ? rest : rest.slice(0, nextHeader);
-}
-
-function existingServerTarget(block) {
-  if (typeof block !== 'string' || !/^\s*command\s*=\s*"node"\s*$/m.test(block)) return null;
-  const match = /^\s*args\s*=\s*\[\s*"([^"\r\n]*server\.mjs)"\s*\]\s*$/m.exec(block);
-  if (!match) return null;
-  try {
-    if (!statSync(match[1]).isFile()) return null;
-    const target = resolve(match[1]);
-    return process.platform === 'win32' ? target.toLowerCase() : target;
-  } catch { return null; }
-}
-
-function codexRoleTarget(file, expectedName) {
-  const text = readText(file);
-  if (typeof text !== 'string'
-    || !new RegExp(`^\\s*name\\s*=\\s*"${expectedName}"\\s*$`, 'm').test(text)) return null;
-  return existingServerTarget(tomlSection(text, 'mcp_servers.dsh-crew'));
-}
-
-function codexMcpTarget(configText) {
-  const section = tomlSection(configText, 'mcp_servers');
-  if (!section) return null;
-  const entry = /^\s*dsh-crew\s*=\s*\{\s*command\s*=\s*"node"\s*,\s*args\s*=\s*\[\s*"([^"\r\n]*server\.mjs)"\s*\]\s*\}\s*(?:#.*)?$/m.exec(section);
-  if (!entry) return null;
-  try {
-    if (!statSync(entry[1]).isFile()) return null;
-    const target = resolve(entry[1]);
-    return process.platform === 'win32' ? target.toLowerCase() : target;
-  } catch { return null; }
-}
-
-function isFile(file) {
-  try { return statSync(file).isFile(); } catch { return false; }
-}
-
-function claudePluginRootReady(root) {
-  if (typeof root !== 'string' || !root.trim() || !isFile(join(root, 'src', 'server.mjs'))) return false;
-  const plugin = readJson(join(root, '.claude-plugin', 'plugin.json'), null);
-  const mcp = plugin?.mcpServers?.['dsh-crew'];
-  return !!plugin
-    && typeof plugin.version === 'string'
-    && mcp?.command === 'node'
-    && Array.isArray(mcp.args)
-    && mcp.args.length === 1
-    && mcp.args[0] === '${CLAUDE_PLUGIN_ROOT}/src/server.mjs';
-}
-
-function managedClaudeFileManifest(root, { maxFiles = 512, maxBytes = 8 * 1024 * 1024 } = {}) {
-  const files = [];
-  let bytes = 0;
-  const add = (file, relativePath) => {
-    const info = lstatSync(file);
-    if (info.isSymbolicLink() || !info.isFile()) throw new Error('unsupported snapshot entry');
-    const content = readFileSync(file);
-    bytes += content.length;
-    if (bytes > maxBytes || files.length >= maxFiles) throw new Error('snapshot manifest bound exceeded');
-    files.push([relativePath.replace(/\\/g, '/'), createHash('sha256').update(content).digest('hex')]);
-  };
-  const walk = (directory, relativeDirectory) => {
-    if (!existsSync(directory)) return;
-    const info = lstatSync(directory);
-    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('unsupported snapshot directory');
-    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const file = join(directory, entry.name);
-      const relativePath = join(relativeDirectory, entry.name);
-      if (entry.isSymbolicLink()) throw new Error('snapshot symlink not allowed');
-      if (entry.isDirectory()) walk(file, relativePath);
-      else if (entry.isFile()) add(file, relativePath);
-      else throw new Error('unsupported snapshot entry');
-    }
-  };
-  try {
-    add(join(root, '.claude-plugin', 'plugin.json'), join('.claude-plugin', 'plugin.json'));
-    if (isFile(join(root, 'package.json'))) add(join(root, 'package.json'), 'package.json');
-    for (const directory of ['agents', 'commands', 'src']) walk(join(root, directory), directory);
-    return files;
-  } catch { return null; }
-}
-
-function sameManagedClaudeFiles(expectedRoot, snapshotRoot) {
-  if (!claudePluginRootReady(expectedRoot) || !claudePluginRootReady(snapshotRoot)) return false;
-  const expected = managedClaudeFileManifest(expectedRoot);
-  const snapshot = managedClaudeFileManifest(snapshotRoot);
-  return expected !== null && snapshot !== null && JSON.stringify(snapshot) === JSON.stringify(expected);
-}
-
-function claudeSnapshotReady(home, root) {
-  const installed = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'), {});
-  const record = installed?.plugins?.[PLUGIN_KEY];
-  const entries = Array.isArray(record) ? record : [record];
-  return entries.some((entry) => sameManagedClaudeFiles(root, entry?.installPath));
-}
-
-function claudePermissionsReady(settings) {
-  const allowed = Array.isArray(settings?.permissions?.allow) ? settings.permissions.allow : [];
-  return MCP_TOOLS.every((tool) => allowed.includes(`mcp__plugin_dsh-crew_dsh-crew__${tool}`));
-}
-
-// One-time migration from the pre-rename config dir (dsh-workers → dsh-crew).
-try {
-  const oldDir = join(homedir(), '.config', 'dsh-workers');
-  const newDir = join(homedir(), '.config', 'dsh-crew');
-  if (existsSync(oldDir) && !existsSync(newDir)) {
-    const { renameSync } = await import('node:fs');
-    renameSync(oldDir, newDir);
-  }
-} catch {}
-
-const GLOBAL_CONFIG_FILE = join(CONFIG_DIR_HOME(), 'config.json');
-function CONFIG_DIR_HOME() { return join(homedir(), '.config', 'dsh-crew'); }
-
-export const GLOBAL_CONFIG_DEFAULTS = {
-  default_tier: 'flash',
-  default_effort: 'max',
-  mode: 'auto',
-  default_timeout_seconds: 1800,
-  hub_url: 'http://127.0.0.1:3080',
-  // auto = orchestrator picks the tier; flash-only / pro-only clamp every
-  // dispatch to one tier at the tool layer regardless of what was requested.
-  tier_policy: 'flash-only',
-  // When a blocking flash run fails, retry the same task once on pro.
-  escalate_on_failure: false,
-  // ---- configurable-crew orchestration (see src/policy.mjs) ----
-  // Master switch for the whole worker dispatch path (hard, backend-enforced).
-  subagents_enabled: true,
-  // flash-only | pro-only | balanced | review-pipeline | custom
-  collaboration_mode: 'flash-only',
-  // direct-allowed | coordinator-first | dispatcher-only (host routing
-  // guidance — the Crew MCP backend cannot restrict the host's own tools).
-  main_agent_mode: 'direct-allowed',
-  // Per-tier state: disabled | manual | auto. Owned by the collaboration
-  // preset unless collaboration_mode is "custom".
-  flash_state: 'auto',
-  pro_state: 'disabled',
-  // Roles per tier: routing guidance only, not a keyword classifier.
-  flash_roles: ['implementation', 'simple_fix', 'tests', 'search_inspection'],
-  pro_roles: ['architecture', 'complex_debugging', 'refactor', 'code_review', 'implementation'],
-  // Automatic Pro review after a successful Flash run (review-pipeline forces
-  // this on; balanced/custom only when this flag is set).
-  pro_reviews_flash: false,
-  // Worker provider routing for HUB workers: which DSH provider backs each
-  // worker session. Fresh installs stay on the built-in DeepSeek provider;
-  // follow-dsh is an explicit opt-in that uses the provider selected in DSH
-  // Models (Flash/Pro still map to the selected Harness models).
-  // Standalone mode always uses deepseek-official + DEEPSEEK_API_KEY.
-  worker_provider_mode: 'deepseek-official',
-  // Ordered Harness provider/model selections. The configured flags preserve
-  // the distinction between a fresh recommendation and a user-cleared list.
-  flash_model_priority: [],
-  flash_model_priority_configured: false,
-  flash_model_fallback: 'harness-default',
-  pro_model_priority: [],
-  pro_model_priority_configured: false,
-  pro_model_fallback: 'harness-default',
-  // ---- configurable-crew multimodal switches ----
-  // False = the Crew describe_image tool and vision route are not registered
-  // at DSH boot (takes effect after a DSH restart). Provider/model values are
-  // kept untouched so re-enabling restores the previous setup.
-  vision_enabled: false,
-  imagegen_enabled: false,
-  // Multimodal bridge: which subscription CLI lends the text-only DS model
-  // eyes (describe_image) and a brush (generate_image).
-  vision_provider: 'off', // claude-code | codex | grok | agy | <custom id> | off
-  vision_model: 'haiku', // model passed to the vision CLI; free-form
-  imagegen_provider: 'off', // codex | agy | grok | <custom id> | off
-  // User-defined providers, each either an OpenAI-compatible HTTP endpoint or a
-  // local command. Entry shape:
-  //   { id, name, type: 'api' | 'cli', models: [],
-  //     api: base_url, api_key, imagegen_model
-  //     cli: vision_command, imagegen_command }
-  // CLI commands run via bash with shell-quoted placeholders: vision
-  // {image} {question} {model} (stdout is the answer), imagegen
-  // {prompt} {output} {size} (must write the file to {output}).
-  custom_providers: [],
-  // User-added model ids per provider, merged into the panel's model list.
-  extra_models: {},
-  // Hub-mode agent preset per tier: 'default' follows the DSH roster default.
-  // Harness Default uses the session-aware filesystem/shell stack. The DSH
-  // minimal preset's provider-native tools use the Host process cwd instead,
-  // so it is unsafe as the fresh default for jobs targeting another workspace.
-  preset_flash: 'default',
-  preset_pro: 'default',
-  // ---- v0.2 runtime execution (writable via the settings config endpoint) ----
-  // Concurrency cap for parallel workflows; isolation: worktree = run coding
-  // workers in per-job git worktrees (fail-closed for non-git workspaces),
-  // shared = legacy in-place behaviour.
-  max_parallel: 3,
-  isolation: 'worktree',
-  // ---- v0.2 role state overrides (writable; unset = derived by migration) ----
-  // Explicit worker/reviewer role states (auto | manual | disabled) and the
-  // automatic-review switch. When unset, migrateLegacyConfig derives them from
-  // collaboration_mode / tier_policy / pro_reviews_flash.
-  worker_state: undefined,
-  review_state: undefined,
-  auto_review: undefined,
-  // ---- per-model peak/off-peak scheduling ----
-  // Some providers price by wall clock (DeepSeek doubles its rate during peak
-  // hours). `models` lists only the restricted models — one absent from it is
-  // unrestricted — each at `warn` (selectable, flagged) or `block` (skipped, so
-  // the next candidate serves the job). Times are the operator's local wall
-  // clock at `timezone_offset_minutes`, defaulting to UTC+8 with DeepSeek's
-  // published peak hours expressed in it.
-  model_schedule: undefined,
-};
-
-export function mergeStoredGlobalConfig(stored) {
-  if (!stored || typeof stored !== 'object' || Array.isArray(stored)) return { ...GLOBAL_CONFIG_DEFAULTS };
-  const has = (key) => Object.prototype.hasOwnProperty.call(stored, key);
-  const merged = { ...GLOBAL_CONFIG_DEFAULTS, ...stored };
-  // Fields introduced by configurable Crew keep the prior release's behavior
-  // when an existing file predates them. Only a genuinely fresh config gets
-  // the new minimal defaults above.
-  if (!has('collaboration_mode')) {
-    merged.collaboration_mode = stored.tier_policy === 'flash-only' ? 'flash-only'
-      : stored.tier_policy === 'pro-only' ? 'pro-only' : 'balanced';
-  }
-  if (!has('flash_state') || !has('pro_state')) {
-    if (stored.tier_policy === 'flash-only') { merged.flash_state = 'auto'; merged.pro_state = 'disabled'; }
-    else if (stored.tier_policy === 'pro-only') { merged.flash_state = 'disabled'; merged.pro_state = 'auto'; }
-    else { merged.flash_state = 'auto'; merged.pro_state = 'auto'; }
-  }
-  if (!has('main_agent_mode')) merged.main_agent_mode = 'coordinator-first';
-  if (!has('worker_provider_mode')) merged.worker_provider_mode = 'deepseek-official';
-  // Existing configs that predate preset_flash should inherit the current safe
-  // Harness Default. The older implicit `minimal` migration is unsafe for
-  // workspace-targeted jobs on Windows; an explicit user-set `minimal` value
-  // is still preserved by the normal object merge above.
-  if (!has('preset_flash')) merged.preset_flash = 'default';
-  if (!has('vision_enabled')) merged.vision_enabled = stored.vision_provider !== 'off';
-  if (!has('imagegen_enabled')) merged.imagegen_enabled = stored.imagegen_provider !== 'off';
-  return merged;
-}
-
-export function readGlobalConfig({ configFile = GLOBAL_CONFIG_FILE } = {}) {
-  if (!existsSync(configFile)) return { ...GLOBAL_CONFIG_DEFAULTS };
-  return mergeStoredGlobalConfig(readJson(configFile, {}));
-}
-
-export function writeGlobalConfig(patch) {
-  mkdirSync(CONFIG_DIR_HOME(), { recursive: true });
-  const next = { ...readGlobalConfig() };
-  for (const [k, v] of Object.entries(patch ?? {})) {
-    if (v !== undefined && k in GLOBAL_CONFIG_DEFAULTS) next[k] = v;
-  }
-  for (const tier of ['flash', 'pro']) {
-    const key = `${tier}_model_priority`;
-    if (patch?.[key] !== undefined) {
-      next[key] = normalizeModelPriority(patch[key]);
-      next[`${tier}_model_priority_configured`] = true;
-    }
-  }
-  // Legacy clamp fields stay writable (session commands still read them), and
-  // a tier_policy write resyncs the new fields so old UIs can't drift apart
-  // from the new policy. Deprecated but harmless.
-  if (patch?.tier_policy !== undefined) {
-    next.tier_policy = patch.tier_policy;
-    if (patch.tier_policy === 'flash-only') { next.collaboration_mode = 'flash-only'; }
-    else if (patch.tier_policy === 'pro-only') { next.collaboration_mode = 'pro-only'; }
-    else if (next.collaboration_mode === 'flash-only' || next.collaboration_mode === 'pro-only') { next.collaboration_mode = 'balanced'; }
-  }
-  writeFileSync(GLOBAL_CONFIG_FILE, JSON.stringify(next, null, 2) + '\n');
-  return next;
-}
-
-/** What is currently installed where — drives the settings-page buttons. */
-export function installStatus({ home = homedir(), root = ROOT, env = process.env } = {}) {
-  const settings = readJson(join(home, '.claude', 'settings.json'), {});
-  const enabled = settings.enabledPlugins;
-  const claudeInstalled = !!(enabled && !Array.isArray(enabled) && enabled[PLUGIN_KEY]);
-  const hudWired = typeof settings.statusLine?.command === 'string'
-    && settings.statusLine.command.includes('worker-segment.sh');
-  const marketplaceRoot = settings?.extraKnownMarketplaces?.[MARKETPLACE_NAME]?.source?.path;
-  const installedPluginRecord = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'), {})?.plugins?.[PLUGIN_KEY];
-  const claudeFootprint = claudeInstalled || typeof marketplaceRoot === 'string' || installedPluginRecord !== undefined;
-  const claudeComponents = {
-    enabled: claudeInstalled,
-    marketplace: normalizedPath(marketplaceRoot) === normalizedPath(root) && claudePluginRootReady(root),
-    snapshot: claudeSnapshotReady(home, root),
-    permissions: claudePermissionsReady(settings),
-  };
-  const claudeMissing = Object.entries(claudeComponents).filter(([, present]) => !present).map(([key]) => key);
-  const codexRoot = codexHomeDir(home, env);
-  const configFile = join(codexRoot, 'config.toml');
-  const configText = readText(configFile) ?? '';
-  const workerFile = join(codexRoot, 'agents', 'ds-worker.toml');
-  const reviewerFile = join(codexRoot, 'agents', 'ds-reviewer.toml');
-  const workerTarget = codexRoleTarget(workerFile, 'ds-worker');
-  const reviewerTarget = codexRoleTarget(reviewerFile, 'ds-reviewer');
-  const mcpTarget = codexMcpTarget(configText);
-  const expectedTarget = normalizedPath(join(root, 'src', 'server.mjs'));
-  const expectedWorkerRole = renderedCodexRole(root, 'ds-worker.toml');
-  const expectedReviewerRole = renderedCodexRole(root, 'ds-reviewer.toml');
-  const expectedConfigPrompt = readText(join(root, 'codex', 'prompts', 'dsh-config.md'));
-  const expectedStatusPrompt = readText(join(root, 'codex', 'prompts', 'dsh-status.md'));
-  const components = {
-    worker_role: expectedWorkerRole !== null && readText(workerFile) === expectedWorkerRole,
-    reviewer_role: expectedReviewerRole !== null && readText(reviewerFile) === expectedReviewerRole,
-    config_prompt: expectedConfigPrompt !== null && readText(join(codexRoot, 'prompts', 'dsh-config.md')) === expectedConfigPrompt,
-    status_prompt: expectedStatusPrompt !== null && readText(join(codexRoot, 'prompts', 'dsh-status.md')) === expectedStatusPrompt,
-    mcp: !!expectedTarget && mcpTarget === expectedTarget,
-    target_alignment: !!expectedTarget && workerTarget === expectedTarget && reviewerTarget === expectedTarget && mcpTarget === expectedTarget,
-    global_policy: globalCodexPolicyReady({ home, root, env }),
-  };
-  const codexInstalled = Object.values(components).some(Boolean)
-    || existsSync(join(codexRoot, 'agents', 'ds-flash.toml'))
-    || existsSync(join(codexRoot, 'agents', 'ds-pro.toml'));
-  const missing = Object.entries(components).filter(([, present]) => !present).map(([key]) => key);
-  return {
-    claude: {
-      installed: claudeFootprint,
-      ready: claudeMissing.length === 0,
-      hud: hudWired,
-      components: claudeComponents,
-      missing: claudeMissing,
-    },
-    codex: { installed: codexInstalled, ready: missing.length === 0, components, missing },
-    zcode: zcodeStatus({ home, root }),
-  };
-}
-
-export function uninstallCodex({ home = homedir(), env = process.env } = {}) {
-  const actions = [];
-  // Both the v0.2 roles (ds-worker / ds-reviewer) and the deprecated v0.1
-  // aliases (ds-flash / ds-pro) are dsh-crew managed; uninstall removes only
-  // these, never a user's own role files.
-  for (const f of ['ds-flash.toml', 'ds-pro.toml', 'ds-worker.toml', 'ds-reviewer.toml']) {
-    const p = join(codexHomeDir(home, env), 'agents', f);
-    if (existsSync(p)) { backup(p); rmSync(p); actions.push(`removed: ${p} (backup kept)`); }
-  }
-  for (const f of ['dsh-config.md', 'dsh-status.md']) {
-    const p = join(codexHomeDir(home, env), 'prompts', f);
-    if (existsSync(p)) { rmSync(p); actions.push(`removed: ${p}`); }
-  }
-  const policyAction = uninstallGlobalCodexPolicy({ home, env });
-  if (policyAction) actions.push(policyAction);
-  // Remove only the dsh-crew entry from [mcp_servers], keeping any other
-  // MCP servers the user configured.
-  const configFile = join(codexHomeDir(home, env), 'config.toml');
-  if (existsSync(configFile)) {
-    const before = readFileSync(configFile, 'utf8');
-    const lineRe = /(^|\n)[ \t]*dsh-crew\s*=\s*\{[^\n]*\}/;
-    const after = lineRe.test(before) ? before.replace(lineRe, '') : before;
-    if (after !== before) {
-      backup(configFile);
-      writeFileSync(configFile, after.replace(/(^|\n){2,}/g, '\n\n').replace(/^\[mcp_servers\]\n?$/, ''));
-      actions.push(`codex config: removed dsh-crew MCP entry`);
-    }
-  }
-  return { ok: true, actions: actions.length ? actions : ['nothing to remove'] };
-}
-
-export async function installClaudeCode({ home = homedir(), statusline = false, root = ROOT } = {}) {
-  const actions = [];
-
-  // The repository carries its own marketplace manifest (.claude-plugin/
-  // marketplace.json with source "."), so the marketplace root IS the plugin
-  // checkout itself — no parent-directory layout assumption. This keeps the
-  // installer working when the repo is cloned anywhere (e.g. Desktop\dsh-crew).
-  // `root` lets an npx-managed install point every rendered path at the
-  // durable Crew-owned payload instead of a transient package extraction dir.
-  const mpDir = root;
-  actions.push(`marketplace: ${mpDir} (self-marketplace, source .)`);
-
-  // 2. settings.json: marketplace + enabledPlugins + permissions allowlist.
-  const settingsFile = join(home, '.claude', 'settings.json');
-  mkdirSync(dirname(settingsFile), { recursive: true });
-  const bak = backup(settingsFile);
-  if (bak) actions.push(`backup: ${bak}`);
-  const settings = readJson(settingsFile, {});
-
-  // Both fields are records (see json.schemastore.org/claude-code-settings.json).
-  // Older versions of this installer wrote arrays, which Claude Code ignores
-  // with a warning — migrate those in place.
-  const markets = (settings.extraKnownMarketplaces && !Array.isArray(settings.extraKnownMarketplaces)
-    && typeof settings.extraKnownMarketplaces === 'object') ? settings.extraKnownMarketplaces : {};
-  if (Array.isArray(settings.extraKnownMarketplaces)) actions.push('migrated legacy extraKnownMarketplaces array');
-  markets[MARKETPLACE_NAME] = { source: { source: 'directory', path: mpDir } };
-  if (markets['dsh-workers']) {
-    delete markets['dsh-workers'];
-    actions.push('removed pre-rename dsh-workers marketplace entry');
-  }
-  settings.extraKnownMarketplaces = markets;
-
-  const enabled = (settings.enabledPlugins && !Array.isArray(settings.enabledPlugins)
-    && typeof settings.enabledPlugins === 'object') ? settings.enabledPlugins : {};
-  if (Array.isArray(settings.enabledPlugins)) {
-    for (const key of settings.enabledPlugins) if (typeof key === 'string') enabled[key] = true;
-    actions.push('migrated legacy enabledPlugins array');
-  }
-  enabled[PLUGIN_KEY] = true;
-  if (enabled['dsh-workers@dsh-workers']) {
-    delete enabled['dsh-workers@dsh-workers'];
-    actions.push('removed pre-rename dsh-workers plugin entry');
-  }
-  settings.enabledPlugins = enabled;
-
-  settings.permissions = settings.permissions ?? {};
-  let allow = Array.isArray(settings.permissions.allow) ? settings.permissions.allow : [];
-  const preRename = allow.filter((r) => typeof r === 'string' && r.startsWith('mcp__plugin_dsh-workers_'));
-  if (preRename.length) {
-    allow = allow.filter((r) => !preRename.includes(r));
-    actions.push(`removed ${preRename.length} pre-rename permission rules`);
-  }
-  for (const tool of MCP_TOOLS) {
-    const rule = `mcp__plugin_dsh-crew_dsh-crew__${tool}`;
-    if (!allow.includes(rule)) allow.push(rule);
-  }
-  settings.permissions.allow = allow;
-
-  if (statusline && !settings.statusLine) {
-    settings.statusLine = { type: 'command', command: `bash ${join(root, 'statusline', 'statusline.sh')}` };
-    actions.push('statusline: installed');
-  } else if (statusline) {
-    actions.push('statusline: skipped (one already configured)');
-  }
-
-  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-  actions.push(`settings: registered ${PLUGIN_KEY} + ${MCP_TOOLS.length} permission rules`);
-
-  // Materialize the install through the claude CLI: registers the marketplace
-  // in the plugin cache (settings alone leave a stale/absent cache entry) and
-  // pulls the plugin so the next session loads it. Best-effort: settings are
-  // already correct, so a missing CLI just means one manual `plugin install`.
-  const registered = readJson(join(home, '.claude', 'plugins', 'known_marketplaces.json'), {})?.[MARKETPLACE_NAME];
-  const installedRecord = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'), {})?.plugins?.[PLUGIN_KEY];
-  const installedEntries = Array.isArray(installedRecord) ? installedRecord : [installedRecord];
-  const marketplaceCurrent = registered?.source?.source === 'directory'
-    && normalizedPath(registered.source.path) === normalizedPath(root)
-    && normalizedPath(registered.installLocation) === normalizedPath(root);
-  if (marketplaceCurrent && installedEntries.some((entry) => entry?.scope === 'user'
-    && sameManagedClaudeFiles(root, entry.installPath))) {
-    actions.push('cli: skipped (registered marketplace and snapshot already current)');
-    return { ok: true, actions };
-  }
-  if (home !== homedir()) {
-    actions.push('cli: skipped (non-default home; test mode)');
-    return { ok: true, actions };
-  }
-  try {
-    const { execSync } = await import('node:child_process');
-    const run = (cmd) => execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000 });
-    try { run(`claude plugin marketplace add ${JSON.stringify(mpDir)}`); actions.push('cli: marketplace registered'); }
-    catch { actions.push('cli: marketplace add skipped (already registered)'); }
-    // `plugin install` on an already-installed plugin is a no-op and leaves a
-    // stale snapshot in ~/.claude/plugins/cache — uninstall first so an update
-    // always re-copies the current code.
-    try { run(`claude plugin uninstall ${PLUGIN_KEY}`); } catch {}
-    // Newer Claude Code (>= 2.1.x) dropped the -y flag; older builds accepted
-    // it. Try without it first, fall back to the legacy flag.
-    try {
-      run(`claude plugin install ${PLUGIN_KEY} --scope user`);
-    } catch (errNoFlag) {
-      if (!String(errNoFlag?.message ?? '').includes('unknown option')) throw errNoFlag;
-      run(`claude plugin install ${PLUGIN_KEY} --scope user -y`);
-    }
-    actions.push(`cli: plugin snapshot refreshed (${PLUGIN_KEY})`);
-  } catch (err) {
-    actions.push(`cli: plugin install failed — run manually: claude plugin install ${PLUGIN_KEY} (${String(err?.message ?? err).slice(0, 120)})`);
-  }
-  return { ok: true, actions };
-}
-
-export function installCodex({ home = homedir(), scope, root = ROOT, env = process.env } = {}) {
-  const actions = [];
-  const agentsDir = scope === 'project' ? join(process.cwd(), '.codex', 'agents') : join(codexHomeDir(home, env), 'agents');
-  mkdirSync(agentsDir, { recursive: true });
-  const srcDir = join(root, 'codex', 'agents');
-  // Windows drive paths must render with forward slashes: backslashes in a
-  // TOML basic string are escape sequences (\\U\\u... are invalid), which made
-  // the role files unparseable for Codex Desktop. node accepts forward slashes
-  // on Windows, so the absolute path rendered as D:/... is both valid TOML and
-  // runnable. `root` targets the durable installed payload for npx installs.
-  const renderedPath = join(root, 'src', 'server.mjs').replace(/\\/g, '/');
-  for (const f of readdirSync(srcDir).filter((f) => f.endsWith('.toml'))) {
-    const dest = join(agentsDir, f);
-    const bak = backup(dest);
-    if (bak) actions.push(`backup: ${bak}`);
-    const rendered = renderedCodexRole(root, f);
-    writeFileSync(dest, rendered);
-    actions.push(`role: ${dest}`);
-  }
-  const promptsDir = scope === 'project' ? join(process.cwd(), '.codex', 'prompts') : join(codexHomeDir(home, env), 'prompts');
-  mkdirSync(promptsDir, { recursive: true });
-  const promptsSrc = join(root, 'codex', 'prompts');
-  for (const f of readdirSync(promptsSrc).filter((f) => f.endsWith('.md'))) {
-    writeFileSync(join(promptsDir, f), readFileSync(join(promptsSrc, f), 'utf8'));
-    actions.push(`prompt: ${join(promptsDir, f)}`);
-  }
-  if (scope !== 'project') {
-    const act = writeGlobalCodexMcpServer(home, renderedPath, env);
-    actions.push(...act);
-    const policy = installGlobalCodexPolicy({ home, root, env });
-    if (!policy.ok) return { ok: false, actions: [...actions, policy.action] };
-    actions.push(policy.action);
-  }
-  return { ok: true, actions };
-}
-
-/**
- * Codex Desktop reads the shared config at ~/.codex/config.toml, and the role
- * files alone only expose dsh MCP tools inside the ds-flash/ds-pro subagents.
- * To make dsh_worker_config (policy) visible to the MAIN Codex session, add a
- * top-level [mcp_servers] entry under dsh-crew — preserving any other servers
- * the user already configured. Idempotent (updates in place). Never requires
- * the codex CLI.
- */
-export function writeGlobalCodexMcpServer(home, renderedPath, env = process.env) {
-  const configFile = join(codexHomeDir(home, env), 'config.toml');
-  const entry = `dsh-crew = { command = "node", args = ["${renderedPath}"] }`;
-  const backupFile = backup(configFile);
-  const existing = existsSync(configFile) ? readFileSync(configFile, 'utf8') : '';
-  const hasSection = /(^|\n)\s*\[mcp_servers\]/.test(existing);
-  const sectionIdx = hasSection ? existing.search(/(^|\n)\s*\[mcp_servers\]/) : -1;
-
-  let next;
-  if (hasSection) {
-    // Section exists: find its extent (next top-level [section]) and patch the
-    // dsh-crew entry within it.
-    const afterHeader = sectionIdx + existing.slice(sectionIdx).indexOf(']') + 1;
-    const rest = existing.slice(afterHeader);
-    const nextHeader = rest.search(/(^|\n)\s*\[[^\]]+\]/);
-    const sectionBody = nextHeader === -1 ? rest : rest.slice(0, nextHeader);
-    const tail = nextHeader === -1 ? '' : rest.slice(nextHeader);
-    const lineRe = /(^|\n)([ \t]*)dsh-crew\s*=\s*\{[^\n]*\}/;
-    const patched = lineRe.test(sectionBody)
-      ? sectionBody.replace(lineRe, `$1$2${entry}`)
-      : `${sectionBody.replace(/\s*$/, '')}\n${entry}`;
-    next = existing.slice(0, afterHeader) + patched + tail;
-  } else {
-    // No [mcp_servers] section: append a fresh one.
-    const sep = existing && !/[\n]$/.test(existing) ? '\n' : '';
-    next = `${existing}${sep}[mcp_servers]\n${entry}\n`;
-  }
-  writeFileSync(configFile, next);
-  const actions = [];
-  if (backupFile) actions.push(`config backup: ${backupFile}`);
-  actions.push(`codex config: [mcp_servers] dsh-crew → ${renderedPath}`);
-  return actions;
-}
-
-export function installHudSegment({ home = homedir() } = {}) {
-  const settingsFile = join(home, '.claude', 'settings.json');
-  const settings = readJson(settingsFile, null);
-  if (!settings) return { ok: false, actions: ['settings.json not found'] };
-  const cmd = settings.statusLine?.command;
-  if (typeof cmd !== 'string' || !cmd.includes('claude-hud')) {
-    return { ok: false, actions: ['statusLine is not claude-hud; use statusline/statusline.sh directly instead'] };
-  }
-  const segment = join(ROOT, 'statusline', 'worker-segment.sh');
-  if (cmd.includes(segment)) return { ok: true, actions: ['already wired'] };
-  if (cmd.includes('worker-segment.sh')) {
-    // Wired to a stale copy (e.g. pre-rename path) — repoint the --extra-cmd at the current segment.
-    const next = cmd.replace(/--extra-cmd "bash [^"]*worker-segment\.sh"/, `--extra-cmd "bash ${segment}"`);
-    if (next === cmd) return { ok: false, actions: ['worker-segment.sh present but path not replaceable; rewire manually'] };
-    const bak = backup(settingsFile);
-    settings.statusLine.command = next;
-    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-    return { ok: true, actions: [...(bak ? [`backup: ${bak}`] : []), `statusLine: repointed worker-segment.sh to ${segment}`] };
-  }
-  let next = cmd;
-  if (!next.includes('CLAUDE_HUD_ALLOW_EXTRA_CMD')) {
-    next = next.replace(/exec\s+/, 'exec env CLAUDE_HUD_ALLOW_EXTRA_CMD=1 ');
-    if (!next.includes('CLAUDE_HUD_ALLOW_EXTRA_CMD')) return { ok: false, actions: ['could not find exec in statusLine command; wire manually'] };
-  }
-  const extra = ` --extra-cmd "bash ${segment}"`;
-  if (next.endsWith("'")) next = next.slice(0, -1) + extra + "'";
-  else next += extra;
-  const bak = backup(settingsFile);
-  settings.statusLine.command = next;
-  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-  return { ok: true, actions: [...(bak ? [`backup: ${bak}`] : []), 'statusLine: claude-hud now runs worker-segment.sh via --extra-cmd'] };
-}
-
-export function uninstallClaudeCode({ home = homedir() } = {}) {
-  const settingsFile = join(home, '.claude', 'settings.json');
-  const settings = readJson(settingsFile, null);
-  if (!settings) return { ok: true, actions: ['settings.json not found'] };
-  backup(settingsFile);
-  const mpDir = join(home, '.config', 'dsh-crew', 'marketplace');
-  if (Array.isArray(settings.extraKnownMarketplaces)) {
-    settings.extraKnownMarketplaces = settings.extraKnownMarketplaces.filter((m) => m?.path !== mpDir);
-  } else if (settings.extraKnownMarketplaces) {
-    delete settings.extraKnownMarketplaces[MARKETPLACE_NAME];
-  }
-  if (Array.isArray(settings.enabledPlugins)) {
-    settings.enabledPlugins = settings.enabledPlugins.filter((p) => p !== PLUGIN_KEY);
-  } else if (settings.enabledPlugins) {
-    delete settings.enabledPlugins[PLUGIN_KEY];
-  }
-  if (settings.permissions?.allow) {
-    settings.permissions.allow = settings.permissions.allow.filter((r) => !r.startsWith('mcp__plugin_dsh-crew_'));
-  }
-  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-  return { ok: true, actions: ['unregistered from settings.json (backup kept)'] };
-}
+// One-click installers: register the Claude Code plugin persistently and
+// render Codex agent roles with real paths. Called from the CLI entry or the
+// DSH settings page. All edits are backed up and idempotent.
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, readdirSync, rmSync, statSync, lstatSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { normalizeModelPriority } from '../model-routing.mjs';
+import { zcodeStatus } from './zcode.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const MARKETPLACE_NAME = 'dsh-crew';
+const PLUGIN_KEY = `dsh-crew@${MARKETPLACE_NAME}`;
+const POLICY_START = '<!-- DSH CREW MANAGED POLICY:START -->';
+const POLICY_END = '<!-- DSH CREW MANAGED POLICY:END -->';
+
+/**
+ * The directory Codex actually reads.
+ *
+ * Codex honours `CODEX_HOME` and falls back to `~/.codex`; writing only to the
+ * latter silently does nothing for anyone who set it — the registration stays
+ * frozen on whatever release was current when they set it, while every install
+ * reports success because the file it wrote really did change. Resolve the same
+ * way Codex does, and treat an empty or whitespace value as unset.
+ */
+export function codexHomeDir(home = homedir(), env = process.env) {
+  const override = typeof env?.CODEX_HOME === 'string' ? env.CODEX_HOME.trim() : '';
+  return override ? resolve(override) : join(home, '.codex');
+}
+export const CODEX_LEGACY_POLICY_HASHES = Object.freeze([
+  '2d6f3839bb3df4bda90f481726281292b1a4b4585298b1cf9ec56215295b5c78',
+]);
+// dsh_worker_config is included so the session commands (/dsh-crew:config,
+// /dsh-config) and any orchestrator policy lookup run without an extra
+// authorization prompt.
+export const MCP_TOOLS = ['dsh_run_worker', 'dsh_spawn_worker', 'dsh_worker_status', 'dsh_worker_result', 'dsh_worker_cancel', 'dsh_worker_config'];
+
+function backup(file) {
+  if (existsSync(file)) {
+    const bak = `${file}.dsh-crew-backup-${Date.now()}`;
+    copyFileSync(file, bak);
+    return bak;
+  }
+  return null;
+}
+
+function readJson(file, fallback) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return fallback; }
+}
+
+function readText(file) {
+  try { return readFileSync(file, 'utf8'); } catch { return null; }
+}
+
+function normalizedPath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    const path = resolve(value);
+    return process.platform === 'win32' ? path.toLowerCase() : path;
+  } catch { return null; }
+}
+
+function renderedCodexRole(root, file) {
+  const source = readText(join(root, 'codex', 'agents', file));
+  if (source === null) return null;
+  const renderedPath = join(root, 'src', 'server.mjs').replace(/\\/g, '/');
+  return source.replace(/args = \[.*server\.mjs"\]/, `args = ["${renderedPath}"]`);
+}
+
+function managedPolicyBlock(root) {
+  const policy = readText(join(root, 'codex', 'AGENTS.md'))?.trim();
+  if (!policy) return null;
+  return `${POLICY_START}\n${policy}\n${POLICY_END}`;
+}
+
+export function codexLegacyPolicyDigest(text) {
+  const canonical = typeof text === 'string' ? text.replace(/\r\n/g, '\n').trim() : '';
+  return canonical ? createHash('sha256').update(canonical, 'utf8').digest('hex') : null;
+}
+
+export function stripKnownLegacyCodexPolicy(text, { knownHashes = CODEX_LEGACY_POLICY_HASHES } = {}) {
+  if (typeof text !== 'string') return text;
+  const start = POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const end = POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`${start}[\\s\\S]*?${end}`, 'm').exec(text);
+  if (!match) return text;
+  const allowed = new Set(Array.isArray(knownHashes) ? knownHashes : []);
+  const prefix = text.slice(0, match.index);
+  const suffix = text.slice(match.index + match[0].length);
+  const keptPrefix = allowed.has(codexLegacyPolicyDigest(prefix)) ? '' : prefix;
+  const keptSuffix = allowed.has(codexLegacyPolicyDigest(suffix)) ? '' : suffix;
+  return `${keptPrefix}${match[0]}${keptSuffix}`;
+}
+
+function installGlobalCodexPolicy({ home, root, env = process.env }) {
+  const file = join(codexHomeDir(home, env), 'AGENTS.md');
+  const block = managedPolicyBlock(root);
+  if (!block) return { ok: false, action: 'global policy template missing' };
+  mkdirSync(dirname(file), { recursive: true });
+  const current = readText(file) ?? '';
+  const managed = new RegExp(`${POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+  const template = readText(join(root, 'codex', 'AGENTS.md'))?.trim() ?? '';
+  let next;
+  if (managed.test(current)) next = current.replace(managed, block);
+  else if (current.trim() === template) next = `${block}\n`;
+  else next = `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`;
+  next = stripKnownLegacyCodexPolicy(next);
+  if (next !== current) {
+    backup(file);
+    writeFileSync(file, next);
+  }
+  return { ok: true, action: `global policy: ${file}` };
+}
+
+function globalCodexPolicyReady({ home, root = ROOT, env = process.env }) {
+  const block = managedPolicyBlock(root);
+  const text = readText(join(codexHomeDir(home, env), 'AGENTS.md'));
+  return !!block && typeof text === 'string' && text.includes(block);
+}
+
+function uninstallGlobalCodexPolicy({ home, env = process.env }) {
+  const file = join(codexHomeDir(home, env), 'AGENTS.md');
+  const current = readText(file);
+  if (typeof current !== 'string') return null;
+  const managed = new RegExp(`(?:\\r?\\n){0,2}${POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\r?\\n)?`, 'm');
+  if (!managed.test(current)) return null;
+  const next = current.replace(managed, '').trimEnd();
+  backup(file);
+  if (next.trim()) writeFileSync(file, `${next}\n`);
+  else rmSync(file);
+  return `codex global policy: removed managed block`;
+}
+
+function tomlSection(text, name) {
+  if (typeof text !== 'string') return null;
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const header = new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`, 'm').exec(text);
+  if (!header) return null;
+  const rest = text.slice(header.index + header[0].length);
+  const nextHeader = rest.search(/^\s*\[[^\]\r\n]+\]\s*(?:#.*)?$/m);
+  return nextHeader === -1 ? rest : rest.slice(0, nextHeader);
+}
+
+function existingServerTarget(block) {
+  if (typeof block !== 'string' || !/^\s*command\s*=\s*"node"\s*$/m.test(block)) return null;
+  const match = /^\s*args\s*=\s*\[\s*"([^"\r\n]*server\.mjs)"\s*\]\s*$/m.exec(block);
+  if (!match) return null;
+  try {
+    if (!statSync(match[1]).isFile()) return null;
+    const target = resolve(match[1]);
+    return process.platform === 'win32' ? target.toLowerCase() : target;
+  } catch { return null; }
+}
+
+function codexRoleTarget(file, expectedName) {
+  const text = readText(file);
+  if (typeof text !== 'string'
+    || !new RegExp(`^\\s*name\\s*=\\s*"${expectedName}"\\s*$`, 'm').test(text)) return null;
+  return existingServerTarget(tomlSection(text, 'mcp_servers.dsh-crew'));
+}
+
+function codexMcpTarget(configText) {
+  const section = tomlSection(configText, 'mcp_servers');
+  if (!section) return null;
+  const entry = /^\s*dsh-crew\s*=\s*\{\s*command\s*=\s*"node"\s*,\s*args\s*=\s*\[\s*"([^"\r\n]*server\.mjs)"\s*\]\s*\}\s*(?:#.*)?$/m.exec(section);
+  if (!entry) return null;
+  try {
+    if (!statSync(entry[1]).isFile()) return null;
+    const target = resolve(entry[1]);
+    return process.platform === 'win32' ? target.toLowerCase() : target;
+  } catch { return null; }
+}
+
+function isFile(file) {
+  try { return statSync(file).isFile(); } catch { return false; }
+}
+
+function claudePluginRootReady(root) {
+  if (typeof root !== 'string' || !root.trim() || !isFile(join(root, 'src', 'server.mjs'))) return false;
+  const plugin = readJson(join(root, '.claude-plugin', 'plugin.json'), null);
+  const mcp = plugin?.mcpServers?.['dsh-crew'];
+  return !!plugin
+    && typeof plugin.version === 'string'
+    && mcp?.command === 'node'
+    && Array.isArray(mcp.args)
+    && mcp.args.length === 1
+    && mcp.args[0] === '${CLAUDE_PLUGIN_ROOT}/src/server.mjs';
+}
+
+function managedClaudeFileManifest(root, { maxFiles = 512, maxBytes = 8 * 1024 * 1024 } = {}) {
+  const files = [];
+  let bytes = 0;
+  const add = (file, relativePath) => {
+    const info = lstatSync(file);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error('unsupported snapshot entry');
+    const content = readFileSync(file);
+    bytes += content.length;
+    if (bytes > maxBytes || files.length >= maxFiles) throw new Error('snapshot manifest bound exceeded');
+    files.push([relativePath.replace(/\\/g, '/'), createHash('sha256').update(content).digest('hex')]);
+  };
+  const walk = (directory, relativeDirectory) => {
+    if (!existsSync(directory)) return;
+    const info = lstatSync(directory);
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('unsupported snapshot directory');
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = join(directory, entry.name);
+      const relativePath = join(relativeDirectory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error('snapshot symlink not allowed');
+      if (entry.isDirectory()) walk(file, relativePath);
+      else if (entry.isFile()) add(file, relativePath);
+      else throw new Error('unsupported snapshot entry');
+    }
+  };
+  try {
+    add(join(root, '.claude-plugin', 'plugin.json'), join('.claude-plugin', 'plugin.json'));
+    if (isFile(join(root, 'package.json'))) add(join(root, 'package.json'), 'package.json');
+    for (const directory of ['agents', 'commands', 'src']) walk(join(root, directory), directory);
+    return files;
+  } catch { return null; }
+}
+
+function sameManagedClaudeFiles(expectedRoot, snapshotRoot) {
+  if (!claudePluginRootReady(expectedRoot) || !claudePluginRootReady(snapshotRoot)) return false;
+  const expected = managedClaudeFileManifest(expectedRoot);
+  const snapshot = managedClaudeFileManifest(snapshotRoot);
+  return expected !== null && snapshot !== null && JSON.stringify(snapshot) === JSON.stringify(expected);
+}
+
+function claudeSnapshotReady(home, root) {
+  const installed = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'), {});
+  const record = installed?.plugins?.[PLUGIN_KEY];
+  const entries = Array.isArray(record) ? record : [record];
+  return entries.some((entry) => sameManagedClaudeFiles(root, entry?.installPath));
+}
+
+function claudePermissionsReady(settings) {
+  const allowed = Array.isArray(settings?.permissions?.allow) ? settings.permissions.allow : [];
+  return MCP_TOOLS.every((tool) => allowed.includes(`mcp__plugin_dsh-crew_dsh-crew__${tool}`));
+}
+
+// One-time migration from the pre-rename config dir (dsh-workers → dsh-crew).
+try {
+  const oldDir = join(homedir(), '.config', 'dsh-workers');
+  const newDir = join(homedir(), '.config', 'dsh-crew');
+  if (existsSync(oldDir) && !existsSync(newDir)) {
+    const { renameSync } = await import('node:fs');
+    renameSync(oldDir, newDir);
+  }
+} catch {}
+
+const GLOBAL_CONFIG_FILE = join(CONFIG_DIR_HOME(), 'config.json');
+function CONFIG_DIR_HOME() { return join(homedir(), '.config', 'dsh-crew'); }
+
+export const GLOBAL_CONFIG_DEFAULTS = {
+  default_tier: 'flash',
+  default_effort: 'max',
+  mode: 'auto',
+  default_timeout_seconds: 1800,
+  hub_url: 'http://127.0.0.1:3080',
+  // auto = orchestrator picks the tier; flash-only / pro-only clamp every
+  // dispatch to one tier at the tool layer regardless of what was requested.
+  tier_policy: 'flash-only',
+  // When a blocking flash run fails, retry the same task once on pro.
+  escalate_on_failure: false,
+  // ---- configurable-crew orchestration (see src/policy.mjs) ----
+  // Master switch for the whole worker dispatch path (hard, backend-enforced).
+  subagents_enabled: true,
+  // flash-only | pro-only | balanced | review-pipeline | custom
+  collaboration_mode: 'flash-only',
+  // direct-allowed | coordinator-first | dispatcher-only (host routing
+  // guidance — the Crew MCP backend cannot restrict the host's own tools).
+  main_agent_mode: 'direct-allowed',
+  // Per-tier state: disabled | manual | auto. Owned by the collaboration
+  // preset unless collaboration_mode is "custom".
+  flash_state: 'auto',
+  pro_state: 'disabled',
+  // Roles per tier: routing guidance only, not a keyword classifier.
+  flash_roles: ['implementation', 'simple_fix', 'tests', 'search_inspection'],
+  pro_roles: ['architecture', 'complex_debugging', 'refactor', 'code_review', 'implementation'],
+  // Automatic Pro review after a successful Flash run (review-pipeline forces
+  // this on; balanced/custom only when this flag is set).
+  pro_reviews_flash: false,
+  // Worker provider routing for HUB workers: which DSH provider backs each
+  // worker session. Fresh installs stay on the built-in DeepSeek provider;
+  // follow-dsh is an explicit opt-in that uses the provider selected in DSH
+  // Models (Flash/Pro still map to the selected Harness models).
+  // Standalone mode always uses deepseek-official + DEEPSEEK_API_KEY.
+  worker_provider_mode: 'deepseek-official',
+  // Ordered Harness provider/model selections. The configured flags preserve
+  // the distinction between a fresh recommendation and a user-cleared list.
+  flash_model_priority: [],
+  flash_model_priority_configured: false,
+  flash_model_fallback: 'harness-default',
+  pro_model_priority: [],
+  pro_model_priority_configured: false,
+  pro_model_fallback: 'harness-default',
+  // User-added model ids per provider, merged into the panel's model list.
+  extra_models: {},
+  // Hub-mode agent preset per tier: 'default' follows the DSH roster default.
+  // Harness Default uses the session-aware filesystem/shell stack. The DSH
+  // minimal preset's provider-native tools use the Host process cwd instead,
+  // so it is unsafe as the fresh default for jobs targeting another workspace.
+  preset_flash: 'default',
+  preset_pro: 'default',
+  // ---- v0.2 runtime execution (writable via the settings config endpoint) ----
+  // Concurrency cap for parallel workflows; isolation: worktree = run coding
+  // workers in per-job git worktrees (fail-closed for non-git workspaces),
+  // shared = legacy in-place behaviour.
+  max_parallel: 3,
+  isolation: 'worktree',
+  // ---- v0.2 role state overrides (writable; unset = derived by migration) ----
+  // Explicit worker/reviewer role states (auto | manual | disabled) and the
+  // automatic-review switch. When unset, migrateLegacyConfig derives them from
+  // collaboration_mode / tier_policy / pro_reviews_flash.
+  worker_state: undefined,
+  review_state: undefined,
+  auto_review: undefined,
+  // ---- per-model peak/off-peak scheduling ----
+  // Some providers price by wall clock (DeepSeek doubles its rate during peak
+  // hours). `models` lists only the restricted models — one absent from it is
+  // unrestricted — each at `warn` (selectable, flagged) or `block` (skipped, so
+  // the next candidate serves the job). Times are the operator's local wall
+  // clock at `timezone_offset_minutes`, defaulting to UTC+8 with DeepSeek's
+  // published peak hours expressed in it.
+  model_schedule: undefined,
+};
+
+/** Config keys removed with the vision / image-generation bridge. */
+export const REMOVED_MULTIMODAL_KEYS = Object.freeze([
+  'vision_enabled', 'imagegen_enabled', 'vision_provider', 'vision_model',
+  'imagegen_provider', 'custom_providers',
+]);
+
+export function mergeStoredGlobalConfig(stored) {
+  if (!stored || typeof stored !== 'object' || Array.isArray(stored)) return { ...GLOBAL_CONFIG_DEFAULTS };
+  const has = (key) => Object.prototype.hasOwnProperty.call(stored, key);
+  const merged = { ...GLOBAL_CONFIG_DEFAULTS, ...stored };
+  // Keys that belonged to the removed vision / image-generation bridge. The
+  // merge above keeps unknown stored keys for forward compatibility, so a file
+  // written by an older release would otherwise carry them forever. These are
+  // known-dead, so drop exactly them and leave every other unknown key alone.
+  for (const dead of REMOVED_MULTIMODAL_KEYS) delete merged[dead];
+  // Fields introduced by configurable Crew keep the prior release's behavior
+  // when an existing file predates them. Only a genuinely fresh config gets
+  // the new minimal defaults above.
+  if (!has('collaboration_mode')) {
+    merged.collaboration_mode = stored.tier_policy === 'flash-only' ? 'flash-only'
+      : stored.tier_policy === 'pro-only' ? 'pro-only' : 'balanced';
+  }
+  if (!has('flash_state') || !has('pro_state')) {
+    if (stored.tier_policy === 'flash-only') { merged.flash_state = 'auto'; merged.pro_state = 'disabled'; }
+    else if (stored.tier_policy === 'pro-only') { merged.flash_state = 'disabled'; merged.pro_state = 'auto'; }
+    else { merged.flash_state = 'auto'; merged.pro_state = 'auto'; }
+  }
+  if (!has('main_agent_mode')) merged.main_agent_mode = 'coordinator-first';
+  if (!has('worker_provider_mode')) merged.worker_provider_mode = 'deepseek-official';
+  // Existing configs that predate preset_flash should inherit the current safe
+  // Harness Default. The older implicit `minimal` migration is unsafe for
+  // workspace-targeted jobs on Windows; an explicit user-set `minimal` value
+  // is still preserved by the normal object merge above.
+  if (!has('preset_flash')) merged.preset_flash = 'default';
+  return merged;
+}
+
+export function readGlobalConfig({ configFile = GLOBAL_CONFIG_FILE } = {}) {
+  if (!existsSync(configFile)) return { ...GLOBAL_CONFIG_DEFAULTS };
+  return mergeStoredGlobalConfig(readJson(configFile, {}));
+}
+
+export function writeGlobalConfig(patch) {
+  mkdirSync(CONFIG_DIR_HOME(), { recursive: true });
+  const next = { ...readGlobalConfig() };
+  for (const [k, v] of Object.entries(patch ?? {})) {
+    if (v !== undefined && k in GLOBAL_CONFIG_DEFAULTS) next[k] = v;
+  }
+  for (const tier of ['flash', 'pro']) {
+    const key = `${tier}_model_priority`;
+    if (patch?.[key] !== undefined) {
+      next[key] = normalizeModelPriority(patch[key]);
+      next[`${tier}_model_priority_configured`] = true;
+    }
+  }
+  // Legacy clamp fields stay writable (session commands still read them), and
+  // a tier_policy write resyncs the new fields so old UIs can't drift apart
+  // from the new policy. Deprecated but harmless.
+  if (patch?.tier_policy !== undefined) {
+    next.tier_policy = patch.tier_policy;
+    if (patch.tier_policy === 'flash-only') { next.collaboration_mode = 'flash-only'; }
+    else if (patch.tier_policy === 'pro-only') { next.collaboration_mode = 'pro-only'; }
+    else if (next.collaboration_mode === 'flash-only' || next.collaboration_mode === 'pro-only') { next.collaboration_mode = 'balanced'; }
+  }
+  writeFileSync(GLOBAL_CONFIG_FILE, JSON.stringify(next, null, 2) + '\n');
+  return next;
+}
+
+/** What is currently installed where — drives the settings-page buttons. */
+export function installStatus({ home = homedir(), root = ROOT, env = process.env } = {}) {
+  const settings = readJson(join(home, '.claude', 'settings.json'), {});
+  const enabled = settings.enabledPlugins;
+  const claudeInstalled = !!(enabled && !Array.isArray(enabled) && enabled[PLUGIN_KEY]);
+  const hudWired = typeof settings.statusLine?.command === 'string'
+    && settings.statusLine.command.includes('worker-segment.sh');
+  const marketplaceRoot = settings?.extraKnownMarketplaces?.[MARKETPLACE_NAME]?.source?.path;
+  const installedPluginRecord = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'), {})?.plugins?.[PLUGIN_KEY];
+  const claudeFootprint = claudeInstalled || typeof marketplaceRoot === 'string' || installedPluginRecord !== undefined;
+  const claudeComponents = {
+    enabled: claudeInstalled,
+    marketplace: normalizedPath(marketplaceRoot) === normalizedPath(root) && claudePluginRootReady(root),
+    snapshot: claudeSnapshotReady(home, root),
+    permissions: claudePermissionsReady(settings),
+  };
+  const claudeMissing = Object.entries(claudeComponents).filter(([, present]) => !present).map(([key]) => key);
+  const codexRoot = codexHomeDir(home, env);
+  const configFile = join(codexRoot, 'config.toml');
+  const configText = readText(configFile) ?? '';
+  const workerFile = join(codexRoot, 'agents', 'ds-worker.toml');
+  const reviewerFile = join(codexRoot, 'agents', 'ds-reviewer.toml');
+  const workerTarget = codexRoleTarget(workerFile, 'ds-worker');
+  const reviewerTarget = codexRoleTarget(reviewerFile, 'ds-reviewer');
+  const mcpTarget = codexMcpTarget(configText);
+  const expectedTarget = normalizedPath(join(root, 'src', 'server.mjs'));
+  const expectedWorkerRole = renderedCodexRole(root, 'ds-worker.toml');
+  const expectedReviewerRole = renderedCodexRole(root, 'ds-reviewer.toml');
+  const expectedConfigPrompt = readText(join(root, 'codex', 'prompts', 'dsh-config.md'));
+  const expectedStatusPrompt = readText(join(root, 'codex', 'prompts', 'dsh-status.md'));
+  const components = {
+    worker_role: expectedWorkerRole !== null && readText(workerFile) === expectedWorkerRole,
+    reviewer_role: expectedReviewerRole !== null && readText(reviewerFile) === expectedReviewerRole,
+    config_prompt: expectedConfigPrompt !== null && readText(join(codexRoot, 'prompts', 'dsh-config.md')) === expectedConfigPrompt,
+    status_prompt: expectedStatusPrompt !== null && readText(join(codexRoot, 'prompts', 'dsh-status.md')) === expectedStatusPrompt,
+    mcp: !!expectedTarget && mcpTarget === expectedTarget,
+    target_alignment: !!expectedTarget && workerTarget === expectedTarget && reviewerTarget === expectedTarget && mcpTarget === expectedTarget,
+    global_policy: globalCodexPolicyReady({ home, root, env }),
+  };
+  const codexInstalled = Object.values(components).some(Boolean)
+    || existsSync(join(codexRoot, 'agents', 'ds-flash.toml'))
+    || existsSync(join(codexRoot, 'agents', 'ds-pro.toml'));
+  const missing = Object.entries(components).filter(([, present]) => !present).map(([key]) => key);
+  return {
+    claude: {
+      installed: claudeFootprint,
+      ready: claudeMissing.length === 0,
+      hud: hudWired,
+      components: claudeComponents,
+      missing: claudeMissing,
+    },
+    codex: { installed: codexInstalled, ready: missing.length === 0, components, missing },
+    zcode: zcodeStatus({ home, root }),
+  };
+}
+
+export function uninstallCodex({ home = homedir(), env = process.env } = {}) {
+  const actions = [];
+  // Both the v0.2 roles (ds-worker / ds-reviewer) and the deprecated v0.1
+  // aliases (ds-flash / ds-pro) are dsh-crew managed; uninstall removes only
+  // these, never a user's own role files.
+  for (const f of ['ds-flash.toml', 'ds-pro.toml', 'ds-worker.toml', 'ds-reviewer.toml']) {
+    const p = join(codexHomeDir(home, env), 'agents', f);
+    if (existsSync(p)) { backup(p); rmSync(p); actions.push(`removed: ${p} (backup kept)`); }
+  }
+  for (const f of ['dsh-config.md', 'dsh-status.md']) {
+    const p = join(codexHomeDir(home, env), 'prompts', f);
+    if (existsSync(p)) { rmSync(p); actions.push(`removed: ${p}`); }
+  }
+  const policyAction = uninstallGlobalCodexPolicy({ home, env });
+  if (policyAction) actions.push(policyAction);
+  // Remove only the dsh-crew entry from [mcp_servers], keeping any other
+  // MCP servers the user configured.
+  const configFile = join(codexHomeDir(home, env), 'config.toml');
+  if (existsSync(configFile)) {
+    const before = readFileSync(configFile, 'utf8');
+    const lineRe = /(^|\n)[ \t]*dsh-crew\s*=\s*\{[^\n]*\}/;
+    const after = lineRe.test(before) ? before.replace(lineRe, '') : before;
+    if (after !== before) {
+      backup(configFile);
+      writeFileSync(configFile, after.replace(/(^|\n){2,}/g, '\n\n').replace(/^\[mcp_servers\]\n?$/, ''));
+      actions.push(`codex config: removed dsh-crew MCP entry`);
+    }
+  }
+  return { ok: true, actions: actions.length ? actions : ['nothing to remove'] };
+}
+
+export async function installClaudeCode({ home = homedir(), statusline = false, root = ROOT } = {}) {
+  const actions = [];
+
+  // The repository carries its own marketplace manifest (.claude-plugin/
+  // marketplace.json with source "."), so the marketplace root IS the plugin
+  // checkout itself — no parent-directory layout assumption. This keeps the
+  // installer working when the repo is cloned anywhere (e.g. Desktop\dsh-crew).
+  // `root` lets an npx-managed install point every rendered path at the
+  // durable Crew-owned payload instead of a transient package extraction dir.
+  const mpDir = root;
+  actions.push(`marketplace: ${mpDir} (self-marketplace, source .)`);
+
+  // 2. settings.json: marketplace + enabledPlugins + permissions allowlist.
+  const settingsFile = join(home, '.claude', 'settings.json');
+  mkdirSync(dirname(settingsFile), { recursive: true });
+  const bak = backup(settingsFile);
+  if (bak) actions.push(`backup: ${bak}`);
+  const settings = readJson(settingsFile, {});
+
+  // Both fields are records (see json.schemastore.org/claude-code-settings.json).
+  // Older versions of this installer wrote arrays, which Claude Code ignores
+  // with a warning — migrate those in place.
+  const markets = (settings.extraKnownMarketplaces && !Array.isArray(settings.extraKnownMarketplaces)
+    && typeof settings.extraKnownMarketplaces === 'object') ? settings.extraKnownMarketplaces : {};
+  if (Array.isArray(settings.extraKnownMarketplaces)) actions.push('migrated legacy extraKnownMarketplaces array');
+  markets[MARKETPLACE_NAME] = { source: { source: 'directory', path: mpDir } };
+  if (markets['dsh-workers']) {
+    delete markets['dsh-workers'];
+    actions.push('removed pre-rename dsh-workers marketplace entry');
+  }
+  settings.extraKnownMarketplaces = markets;
+
+  const enabled = (settings.enabledPlugins && !Array.isArray(settings.enabledPlugins)
+    && typeof settings.enabledPlugins === 'object') ? settings.enabledPlugins : {};
+  if (Array.isArray(settings.enabledPlugins)) {
+    for (const key of settings.enabledPlugins) if (typeof key === 'string') enabled[key] = true;
+    actions.push('migrated legacy enabledPlugins array');
+  }
+  enabled[PLUGIN_KEY] = true;
+  if (enabled['dsh-workers@dsh-workers']) {
+    delete enabled['dsh-workers@dsh-workers'];
+    actions.push('removed pre-rename dsh-workers plugin entry');
+  }
+  settings.enabledPlugins = enabled;
+
+  settings.permissions = settings.permissions ?? {};
+  let allow = Array.isArray(settings.permissions.allow) ? settings.permissions.allow : [];
+  const preRename = allow.filter((r) => typeof r === 'string' && r.startsWith('mcp__plugin_dsh-workers_'));
+  if (preRename.length) {
+    allow = allow.filter((r) => !preRename.includes(r));
+    actions.push(`removed ${preRename.length} pre-rename permission rules`);
+  }
+  for (const tool of MCP_TOOLS) {
+    const rule = `mcp__plugin_dsh-crew_dsh-crew__${tool}`;
+    if (!allow.includes(rule)) allow.push(rule);
+  }
+  settings.permissions.allow = allow;
+
+  if (statusline && !settings.statusLine) {
+    settings.statusLine = { type: 'command', command: `bash ${join(root, 'statusline', 'statusline.sh')}` };
+    actions.push('statusline: installed');
+  } else if (statusline) {
+    actions.push('statusline: skipped (one already configured)');
+  }
+
+  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+  actions.push(`settings: registered ${PLUGIN_KEY} + ${MCP_TOOLS.length} permission rules`);
+
+  // Materialize the install through the claude CLI: registers the marketplace
+  // in the plugin cache (settings alone leave a stale/absent cache entry) and
+  // pulls the plugin so the next session loads it. Best-effort: settings are
+  // already correct, so a missing CLI just means one manual `plugin install`.
+  const registered = readJson(join(home, '.claude', 'plugins', 'known_marketplaces.json'), {})?.[MARKETPLACE_NAME];
+  const installedRecord = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'), {})?.plugins?.[PLUGIN_KEY];
+  const installedEntries = Array.isArray(installedRecord) ? installedRecord : [installedRecord];
+  const marketplaceCurrent = registered?.source?.source === 'directory'
+    && normalizedPath(registered.source.path) === normalizedPath(root)
+    && normalizedPath(registered.installLocation) === normalizedPath(root);
+  if (marketplaceCurrent && installedEntries.some((entry) => entry?.scope === 'user'
+    && sameManagedClaudeFiles(root, entry.installPath))) {
+    actions.push('cli: skipped (registered marketplace and snapshot already current)');
+    return { ok: true, actions };
+  }
+  if (home !== homedir()) {
+    actions.push('cli: skipped (non-default home; test mode)');
+    return { ok: true, actions };
+  }
+  try {
+    const { execSync } = await import('node:child_process');
+    const run = (cmd) => execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000 });
+    try { run(`claude plugin marketplace add ${JSON.stringify(mpDir)}`); actions.push('cli: marketplace registered'); }
+    catch { actions.push('cli: marketplace add skipped (already registered)'); }
+    // `plugin install` on an already-installed plugin is a no-op and leaves a
+    // stale snapshot in ~/.claude/plugins/cache — uninstall first so an update
+    // always re-copies the current code.
+    try { run(`claude plugin uninstall ${PLUGIN_KEY}`); } catch {}
+    // Newer Claude Code (>= 2.1.x) dropped the -y flag; older builds accepted
+    // it. Try without it first, fall back to the legacy flag.
+    try {
+      run(`claude plugin install ${PLUGIN_KEY} --scope user`);
+    } catch (errNoFlag) {
+      if (!String(errNoFlag?.message ?? '').includes('unknown option')) throw errNoFlag;
+      run(`claude plugin install ${PLUGIN_KEY} --scope user -y`);
+    }
+    actions.push(`cli: plugin snapshot refreshed (${PLUGIN_KEY})`);
+  } catch (err) {
+    actions.push(`cli: plugin install failed — run manually: claude plugin install ${PLUGIN_KEY} (${String(err?.message ?? err).slice(0, 120)})`);
+  }
+  return { ok: true, actions };
+}
+
+export function installCodex({ home = homedir(), scope, root = ROOT, env = process.env } = {}) {
+  const actions = [];
+  const agentsDir = scope === 'project' ? join(process.cwd(), '.codex', 'agents') : join(codexHomeDir(home, env), 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  const srcDir = join(root, 'codex', 'agents');
+  // Windows drive paths must render with forward slashes: backslashes in a
+  // TOML basic string are escape sequences (\\U\\u... are invalid), which made
+  // the role files unparseable for Codex Desktop. node accepts forward slashes
+  // on Windows, so the absolute path rendered as D:/... is both valid TOML and
+  // runnable. `root` targets the durable installed payload for npx installs.
+  const renderedPath = join(root, 'src', 'server.mjs').replace(/\\/g, '/');
+  for (const f of readdirSync(srcDir).filter((f) => f.endsWith('.toml'))) {
+    const dest = join(agentsDir, f);
+    const bak = backup(dest);
+    if (bak) actions.push(`backup: ${bak}`);
+    const rendered = renderedCodexRole(root, f);
+    writeFileSync(dest, rendered);
+    actions.push(`role: ${dest}`);
+  }
+  const promptsDir = scope === 'project' ? join(process.cwd(), '.codex', 'prompts') : join(codexHomeDir(home, env), 'prompts');
+  mkdirSync(promptsDir, { recursive: true });
+  const promptsSrc = join(root, 'codex', 'prompts');
+  for (const f of readdirSync(promptsSrc).filter((f) => f.endsWith('.md'))) {
+    writeFileSync(join(promptsDir, f), readFileSync(join(promptsSrc, f), 'utf8'));
+    actions.push(`prompt: ${join(promptsDir, f)}`);
+  }
+  if (scope !== 'project') {
+    const act = writeGlobalCodexMcpServer(home, renderedPath, env);
+    actions.push(...act);
+    const policy = installGlobalCodexPolicy({ home, root, env });
+    if (!policy.ok) return { ok: false, actions: [...actions, policy.action] };
+    actions.push(policy.action);
+  }
+  return { ok: true, actions };
+}
+
+/**
+ * Codex Desktop reads the shared config at ~/.codex/config.toml, and the role
+ * files alone only expose dsh MCP tools inside the ds-flash/ds-pro subagents.
+ * To make dsh_worker_config (policy) visible to the MAIN Codex session, add a
+ * top-level [mcp_servers] entry under dsh-crew — preserving any other servers
+ * the user already configured. Idempotent (updates in place). Never requires
+ * the codex CLI.
+ */
+export function writeGlobalCodexMcpServer(home, renderedPath, env = process.env) {
+  const configFile = join(codexHomeDir(home, env), 'config.toml');
+  const entry = `dsh-crew = { command = "node", args = ["${renderedPath}"] }`;
+  const backupFile = backup(configFile);
+  const existing = existsSync(configFile) ? readFileSync(configFile, 'utf8') : '';
+  const hasSection = /(^|\n)\s*\[mcp_servers\]/.test(existing);
+  const sectionIdx = hasSection ? existing.search(/(^|\n)\s*\[mcp_servers\]/) : -1;
+
+  let next;
+  if (hasSection) {
+    // Section exists: find its extent (next top-level [section]) and patch the
+    // dsh-crew entry within it.
+    const afterHeader = sectionIdx + existing.slice(sectionIdx).indexOf(']') + 1;
+    const rest = existing.slice(afterHeader);
+    const nextHeader = rest.search(/(^|\n)\s*\[[^\]]+\]/);
+    const sectionBody = nextHeader === -1 ? rest : rest.slice(0, nextHeader);
+    const tail = nextHeader === -1 ? '' : rest.slice(nextHeader);
+    const lineRe = /(^|\n)([ \t]*)dsh-crew\s*=\s*\{[^\n]*\}/;
+    const patched = lineRe.test(sectionBody)
+      ? sectionBody.replace(lineRe, `$1$2${entry}`)
+      : `${sectionBody.replace(/\s*$/, '')}\n${entry}`;
+    next = existing.slice(0, afterHeader) + patched + tail;
+  } else {
+    // No [mcp_servers] section: append a fresh one.
+    const sep = existing && !/[\n]$/.test(existing) ? '\n' : '';
+    next = `${existing}${sep}[mcp_servers]\n${entry}\n`;
+  }
+  writeFileSync(configFile, next);
+  const actions = [];
+  if (backupFile) actions.push(`config backup: ${backupFile}`);
+  actions.push(`codex config: [mcp_servers] dsh-crew → ${renderedPath}`);
+  return actions;
+}
+
+export function installHudSegment({ home = homedir() } = {}) {
+  const settingsFile = join(home, '.claude', 'settings.json');
+  const settings = readJson(settingsFile, null);
+  if (!settings) return { ok: false, actions: ['settings.json not found'] };
+  const cmd = settings.statusLine?.command;
+  if (typeof cmd !== 'string' || !cmd.includes('claude-hud')) {
+    return { ok: false, actions: ['statusLine is not claude-hud; use statusline/statusline.sh directly instead'] };
+  }
+  const segment = join(ROOT, 'statusline', 'worker-segment.sh');
+  if (cmd.includes(segment)) return { ok: true, actions: ['already wired'] };
+  if (cmd.includes('worker-segment.sh')) {
+    // Wired to a stale copy (e.g. pre-rename path) — repoint the --extra-cmd at the current segment.
+    const next = cmd.replace(/--extra-cmd "bash [^"]*worker-segment\.sh"/, `--extra-cmd "bash ${segment}"`);
+    if (next === cmd) return { ok: false, actions: ['worker-segment.sh present but path not replaceable; rewire manually'] };
+    const bak = backup(settingsFile);
+    settings.statusLine.command = next;
+    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+    return { ok: true, actions: [...(bak ? [`backup: ${bak}`] : []), `statusLine: repointed worker-segment.sh to ${segment}`] };
+  }
+  let next = cmd;
+  if (!next.includes('CLAUDE_HUD_ALLOW_EXTRA_CMD')) {
+    next = next.replace(/exec\s+/, 'exec env CLAUDE_HUD_ALLOW_EXTRA_CMD=1 ');
+    if (!next.includes('CLAUDE_HUD_ALLOW_EXTRA_CMD')) return { ok: false, actions: ['could not find exec in statusLine command; wire manually'] };
+  }
+  const extra = ` --extra-cmd "bash ${segment}"`;
+  if (next.endsWith("'")) next = next.slice(0, -1) + extra + "'";
+  else next += extra;
+  const bak = backup(settingsFile);
+  settings.statusLine.command = next;
+  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+  return { ok: true, actions: [...(bak ? [`backup: ${bak}`] : []), 'statusLine: claude-hud now runs worker-segment.sh via --extra-cmd'] };
+}
+
+export function uninstallClaudeCode({ home = homedir() } = {}) {
+  const settingsFile = join(home, '.claude', 'settings.json');
+  const settings = readJson(settingsFile, null);
+  if (!settings) return { ok: true, actions: ['settings.json not found'] };
+  backup(settingsFile);
+  const mpDir = join(home, '.config', 'dsh-crew', 'marketplace');
+  if (Array.isArray(settings.extraKnownMarketplaces)) {
+    settings.extraKnownMarketplaces = settings.extraKnownMarketplaces.filter((m) => m?.path !== mpDir);
+  } else if (settings.extraKnownMarketplaces) {
+    delete settings.extraKnownMarketplaces[MARKETPLACE_NAME];
+  }
+  if (Array.isArray(settings.enabledPlugins)) {
+    settings.enabledPlugins = settings.enabledPlugins.filter((p) => p !== PLUGIN_KEY);
+  } else if (settings.enabledPlugins) {
+    delete settings.enabledPlugins[PLUGIN_KEY];
+  }
+  if (settings.permissions?.allow) {
+    settings.permissions.allow = settings.permissions.allow.filter((r) => !r.startsWith('mcp__plugin_dsh-crew_'));
+  }
+  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+  return { ok: true, actions: ['unregistered from settings.json (backup kept)'] };
+}