@researai/deepscientist 1.5.17 → 1.6.0

package/bin/ds.js

@@ -36,12 +36,39 @@ const pythonCommands = new Set([
 const UPDATE_PACKAGE_NAME = String(packageJson.name || '@researai/deepscientist').trim() || '@researai/deepscientist';
 const UPDATE_CHECK_TTL_MS = 12 * 60 * 60 * 1000;
 
-const optionsWithValues = new Set(['--home', '--host', '--port', '--quest-id', '--mode', '--proxy', '--codex-profile', '--codex', '--auth']);
+const optionsWithValues = new Set(['--home', '--host', '--port', '--quest-id', '--mode', '--proxy', '--codex-profile', '--codex', '--auth', '--runner', '--debug-log']);
 
-function buildCodexOverrideEnv({ yolo = true, profile = null, binary = null } = {}) {
+function normalizeRunnerName(value, fallback = '') {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, '-');
+  if (!normalized) return fallback;
+  if (normalized === 'claude-code' || normalized === 'claudecode') return 'claude';
+  if (normalized === 'kimi-code' || normalized === 'kimicode') return 'kimi';
+  if (normalized === 'open-code' || normalized === 'open code' || normalized === 'opencode-ai' || normalized === 'opencodeai') return 'opencode';
+  return normalized.replace(/-/g, '');
+}
+
+function runnerDisplayName(value) {
+  const normalized = normalizeRunnerName(value, 'codex');
+  return {
+    codex: 'Codex',
+    claude: 'Claude Code',
+    kimi: 'Kimi Code',
+    opencode: 'OpenCode',
+  }[normalized] || normalized || 'runner';
+}
+
+function buildCodexOverrideEnv({ yolo = true, profile = null, binary = null, runner = null } = {}) {
   const normalizedProfile = typeof profile === 'string' ? profile.trim() : '';
   const normalizedBinary = typeof binary === 'string' ? binary.trim() : '';
+  const normalizedRunner = normalizeRunnerName(runner);
   const overrides = {};
+  if (normalizedRunner) {
+    overrides.DEEPSCIENTIST_DEFAULT_RUNNER = normalizedRunner;
+    overrides.DEEPSCIENTIST_ENABLE_RUNNER = normalizedRunner;
+  }
   if (normalizedBinary) {
     overrides.DEEPSCIENTIST_CODEX_BINARY = normalizedBinary;
   }
@@ -152,6 +179,7 @@ Usage:
   ds --restart
   ds --status
   ds doctor
+  ds --runner claude
   ds latex status
   ds --home ~/DeepScientist --port 20999
 
@@ -161,6 +189,8 @@ Launcher flags:
   --auth [true|false]   Require a 16-character local browser password. Default is false
   --tui                 Start the terminal workspace only
   --both                Start web + terminal workspace together
+  --debug               Show the TUI debug strip and write redacted JSONL snapshots when TUI is open
+  --debug-log <path>    Write TUI debug snapshots to this JSONL file. Default: /tmp/deepscientist_tui_debug.jsonl
   --no-browser          Do not auto-open the browser
   --daemon-only         Start the managed daemon and exit
   --status              Print managed daemon health as JSON
@@ -170,6 +200,7 @@ Launcher flags:
   --here                Create/use ./DeepScientist under the current working directory as home
   --proxy <url>         Use an outbound HTTP/WS proxy for npm and Python runtime traffic
   --yolo [true|false]   Control Codex YOLO mode. Default is true; pass false to restore on-request + workspace-write
+  --runner <name>      Select builtin runner for this launch: codex, claude, kimi, or opencode
   --codex-profile <id>  Run DeepScientist with a specific Codex profile, for example \`m27\`
   --codex <path>        Run DeepScientist with a specific Codex executable path for this launch
   --quest-id <id>       Open the TUI on one quest directly
@@ -610,6 +641,54 @@ function resolveHome(args) {
   return path.join(os.homedir(), 'DeepScientist');
 }
 
+function hasManagedDaemonState(home) {
+  const state = readDaemonState(home);
+  return Boolean(
+    state
+    && typeof state === 'object'
+    && (
+      state.daemon_id
+      || state.pid
+      || state.url
+      || state.launch_url
+      || state.home
+    )
+  );
+}
+
+function resolveManagementHome(rawArgs, options = {}) {
+  if (
+    options.home
+    || rawArgs.includes('--here')
+    || process.env.DEEPSCIENTIST_HOME
+    || process.env.DS_HOME
+  ) {
+    return options.home || resolveHome(rawArgs);
+  }
+
+  const cwdHome = normalizeHomePath(path.join(process.cwd(), 'DeepScientist'));
+  if (hasManagedDaemonState(cwdHome)) {
+    return cwdHome;
+  }
+
+  const defaultHome = normalizeHomePath(resolveHome(rawArgs));
+  if (hasManagedDaemonState(defaultHome)) {
+    return defaultHome;
+  }
+
+  const installs = readInstallIndex()
+    .installs
+    .map((item) => normalizeInstallRecord(item))
+    .filter(Boolean);
+  const indexedHomes = [...new Set(installs.map((item) => item.home).filter(Boolean))];
+  const managedHomes = indexedHomes.filter((home) => hasManagedDaemonState(home));
+  if (managedHomes.length === 1) {
+    return managedHomes[0];
+  }
+
+  return defaultHome;
+}
+
 function formatHttpHost(host) {
   const normalized = String(host || '').trim();
   if (!normalized) {
@@ -890,15 +969,19 @@ function pythonVersionText(probe) {
   return version;
 }
 
-function renderLaunchHints({ home, url, bindUrl, pythonSelection, yolo, authEnabled, authToken }) {
+function renderLaunchHints({ home, url, bindUrl, pythonSelection, yolo, authEnabled, authToken, runnerName }) {
+  const normalizedRunner = normalizeRunnerName(runnerName, 'codex');
   const runtimeRows = [
     ['Version', packageJson.version],
     ['Home', truncateMiddle(home)],
     ['Browser URL', url],
     ['Bind URL', bindUrl],
     ['Python', truncateMiddle(pythonVersionText(pythonSelection))],
-    ['Codex mode', yolo ? 'YOLO (never + danger-full-access)' : 'Default (on-request + workspace-write)'],
+    ['Runner', runnerDisplayName(normalizedRunner)],
   ];
+  if (normalizedRunner === 'codex') {
+    runtimeRows.push(['Codex mode', yolo ? 'YOLO (never + danger-full-access)' : 'Default (on-request + workspace-write)']);
+  }
   if (authEnabled && authToken) {
     runtimeRows.splice(4, 0, ['Auth token', authToken]);
   }
@@ -940,6 +1023,7 @@ function printLaunchCard({
   yolo,
   authEnabled,
   authToken,
+  runnerName,
 }) {
   const width = Math.max(72, Math.min(process.stdout.columns || 100, 108));
   const divider = colorize('\u001B[38;5;245m', '─'.repeat(Math.max(36, width - 6)));
@@ -1009,7 +1093,7 @@ function printLaunchCard({
   console.log(centerText('Need to move this installation later? Use ds migrate /new/path.', width));
   console.log(centerText(officialRepositoryLine(), width));
   console.log('');
-  renderLaunchHints({ home, url, bindUrl, pythonSelection, yolo, authEnabled, authToken });
+  renderLaunchHints({ home, url, bindUrl, pythonSelection, yolo, authEnabled, authToken, runnerName });
 }
 
 function escapeHtml(value) {
@@ -1021,21 +1105,28 @@ function escapeHtml(value) {
     .replaceAll("'", '&#39;');
 }
 
-function writeCodexPreflightReport(home, probe) {
+function writeRunnerPreflightReport(home, runnerName, probe) {
   const reportDir = path.join(home, 'runtime', 'preflight');
   ensureDir(reportDir);
-  const reportPath = path.join(reportDir, 'codex-preflight.html');
+  const normalizedRunner = normalizeRunnerName(runnerName, 'runner');
+  const runnerLabel = {
+    codex: 'Codex',
+    claude: 'Claude Code',
+    kimi: 'Kimi Code',
+    opencode: 'OpenCode',
+  }[normalizedRunner] || String(runnerName || 'runner').trim() || 'runner';
+  const reportPath = path.join(reportDir, `${normalizedRunner}-preflight.html`);
   const warnings = Array.isArray(probe?.warnings) ? probe.warnings : [];
   const errors = Array.isArray(probe?.errors) ? probe.errors : [];
   const guidance = Array.isArray(probe?.guidance) ? probe.guidance : [];
   const details = probe && typeof probe.details === 'object' ? probe.details : {};
   const profile = typeof details.profile === 'string' ? details.profile.trim() : '';
-  const intro = profile
-    ? `DeepScientist blocked startup because the Codex hello probe did not pass for profile \`${profile}\`. Verify that \`codex --profile ${profile}\` works on this machine and that the profile's provider-specific API key, Base URL, and model configuration are already set up.`
-    : 'DeepScientist blocked startup because the Codex hello probe did not pass. In most installs, `npm install -g @researai/deepscientist` also installs the bundled Codex dependency. If `codex` is still missing, repair it with `npm install -g @openai/codex`. Then run `codex login` (or just `codex`), finish authentication, run `ds doctor`, and launch `ds` again.';
-  const introZh = profile
-    ? `DeepScientist 启动前进行了 Codex 可用性检查，但 profile \`${profile}\` 的 hello 探测没有通过。请先确认 \`codex --profile ${profile}\` 在当前机器上可以正常启动，并确保该 profile 依赖的 provider API Key、Base URL 和模型配置都已经在 Codex 中配置好。`
-    : 'DeepScientist 启动前进行了 Codex 可用性检查，但 hello 探测没有通过。正常情况下，`npm install -g @researai/deepscientist` 也会一并安装 bundled Codex 依赖；如果此后 `codex` 仍不可用，请再执行 `npm install -g @openai/codex` 修复。然后运行 `codex login`（或直接运行 `codex`）完成认证，再执行 `ds doctor`，最后重新启动 `ds`。';
+  const intro = profile && normalizedRunner === 'codex'
+    ? `DeepScientist blocked startup because the ${runnerLabel} hello probe did not pass for profile \`${profile}\`. Verify that \`codex --profile ${profile}\` works on this machine and that the profile's provider-specific API key, Base URL, and model configuration are already set up.`
+    : `DeepScientist blocked startup because the selected runner (${runnerLabel}) did not pass its startup probe. Start DeepScientist with a runner that already works, or enter the web workspace with the default runner and configure another runner later from Settings.`;
+  const introZh = profile && normalizedRunner === 'codex'
+    ? `DeepScientist 启动前进行了 ${runnerLabel} 可用性检查，但 profile \`${profile}\` 的 hello 探测没有通过。请先确认 \`codex --profile ${profile}\` 在当前机器上可以正常启动，并确保该 profile 依赖的 provider API Key、Base URL 和模型配置都已经在 Codex 中配置好。`
+    : `DeepScientist 启动前检查了所选 runner（${runnerLabel}），但它没有通过启动探测。你可以先用已经可用的默认 runner 进入 Web 工作区，再在 Settings 里配置或切换 Claude Code / Kimi Code / OpenCode。`;
   const renderItems = (items, tone) =>
     items
       .map(
@@ -1048,7 +1139,7 @@ function writeCodexPreflightReport(home, probe) {
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>DeepScientist Codex check failed</title>
+    <title>DeepScientist runner check failed</title>
     <style>
       :root { color-scheme: light dark; font-family: Inter, system-ui, sans-serif; }
       body {
@@ -1095,12 +1186,12 @@ function writeCodexPreflightReport(home, probe) {
   <body>
     <main class="page">
       <section class="panel">
-        <h1>DeepScientist could not start Codex</h1>
+        <h1>DeepScientist could not start the selected runner</h1>
         <p class="meta">${escapeHtml(intro)}</p>
         <p class="meta">${escapeHtml(introZh)}</p>
 
         <h2>Summary</h2>
-        <p>${escapeHtml(probe?.summary || 'Codex startup probe failed.')}</p>
+        <p>${escapeHtml(probe?.summary || `${runnerLabel} startup probe failed.`)}</p>
 
         ${errors.length ? `<h2>Errors</h2><ul>${renderItems(errors, 'error')}</ul>` : ''}
         ${warnings.length ? `<h2>Warnings</h2><ul>${renderItems(warnings, 'warn')}</ul>` : ''}
@@ -1143,6 +1234,171 @@ function writeCodexPreflightReport(home, probe) {
   };
 }
 
+
+function readConfiguredDefaultRunner(home, fallback = 'codex') {
+  const configPath = path.join(home, 'config', 'config.yaml');
+  if (!fs.existsSync(configPath)) {
+    return fallback;
+  }
+  try {
+    const text = fs.readFileSync(configPath, 'utf8');
+    const match = text.match(new RegExp("^\\s*default_runner:\\s*[\"']?([^\"'\\n]+)[\"']?\\s*$", "m"));
+    const value = match ? String(match[1] || '').trim().toLowerCase() : '';
+    return value || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function readRunnerBootstrapState(home, runtimePython, runnerName, envOverrides = {}) {
+  const snippet = [
+    'import json, pathlib, sys',
+    'from deepscientist.config import ConfigManager',
+    'home = pathlib.Path(sys.argv[1])',
+    'runner = str(sys.argv[2])',
+    'manager = ConfigManager(home)',
+    'print(json.dumps(manager.runner_bootstrap_state(runner), ensure_ascii=False))',
+  ].join('\n');
+  const result = runSync(runtimePython, ['-c', snippet, home, runnerName], {
+    capture: true,
+    allowFailure: true,
+    env: {
+      ...process.env,
+      ...envOverrides,
+    },
+  });
+  if (result.status !== 0) {
+    return { runner: runnerName, ready: false, last_checked_at: null, last_result: {} };
+  }
+  try {
+    return JSON.parse(result.stdout || '{}');
+  } catch {
+    return { runner: runnerName, ready: false, last_checked_at: null, last_result: {} };
+  }
+}
+
+function probeRunnerBootstrap(home, runtimePython, runnerName, envOverrides = {}) {
+  const snippet = [
+    'import json, pathlib, sys',
+    'from deepscientist.config import ConfigManager',
+    'home = pathlib.Path(sys.argv[1])',
+    'runner = str(sys.argv[2])',
+    'manager = ConfigManager(home)',
+    'print(json.dumps(manager.probe_runner_bootstrap(runner, persist=True), ensure_ascii=False))',
+  ].join('\n');
+  const result = runSync(runtimePython, ['-c', snippet, home, runnerName], {
+    capture: true,
+    allowFailure: true,
+    env: {
+      ...process.env,
+      ...envOverrides,
+    },
+  });
+  let payload = null;
+  try {
+    payload = JSON.parse(result.stdout || '{}');
+  } catch {
+    payload = null;
+  }
+  if (payload && typeof payload === 'object') {
+    return payload;
+  }
+  return {
+    ok: false,
+    summary: `${runnerName} startup probe crashed before a structured result was returned.`,
+    warnings: [],
+    errors: [result.stderr || 'Unable to parse the startup probe result.'],
+    details: {
+      runner: runnerName,
+      exit_code: result.status ?? null,
+      stdout_excerpt: result.stdout || '',
+      stderr_excerpt: result.stderr || '',
+    },
+    guidance: [
+      `Run \`${runnerName}\` manually and complete any required setup.`,
+      'Then start DeepScientist again.',
+    ],
+  };
+}
+
+function readEnabledRunnerNames(home, runtimePython, envOverrides = {}) {
+  const snippet = [
+    'import json, pathlib, sys',
+    'from deepscientist.config import ConfigManager',
+    'home = pathlib.Path(sys.argv[1])',
+    'manager = ConfigManager(home)',
+    'payload = manager.load_runners_config()',
+    'print(json.dumps(sorted(name for name, cfg in payload.items() if isinstance(cfg, dict) and bool(cfg.get("enabled", False))), ensure_ascii=False))',
+  ].join('\n');
+  const result = runSync(runtimePython, ['-c', snippet, home], {
+    capture: true,
+    allowFailure: true,
+    env: {
+      ...process.env,
+      ...envOverrides,
+    },
+  });
+  if (result.status !== 0) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(result.stdout || '[]');
+    return Array.isArray(parsed) ? parsed.map((item) => String(item || '').trim().toLowerCase()).filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+
+function readRunnerReadyState(home, runtimePython, runnerName, envOverrides = {}) {
+  if (String(runnerName || '').trim().toLowerCase() === 'codex') {
+    const state = readCodexBootstrapState(home, runtimePython, envOverrides);
+    return { ready: Boolean(state.codex_ready), state };
+  }
+  const state = readRunnerBootstrapState(home, runtimePython, runnerName, envOverrides);
+  return { ready: Boolean(state.ready), state };
+}
+
+function probeRunnerReady(home, runtimePython, runnerName, envOverrides = {}) {
+  if (String(runnerName || '').trim().toLowerCase() === 'codex') {
+    return probeCodexBootstrap(home, runtimePython, envOverrides);
+  }
+  return probeRunnerBootstrap(home, runtimePython, runnerName, envOverrides);
+}
+
+function resolveStartupRunner(home, runtimePython, preferredRunner, envOverrides = {}, options = {}) {
+  const normalizedPreferred = normalizeRunnerName(preferredRunner, 'codex');
+  const enabled = readEnabledRunnerNames(home, runtimePython, envOverrides);
+  const allowFallback = options.allowFallback !== false;
+  const ordered = allowFallback
+    ? [
+        normalizedPreferred,
+        ...enabled.filter((name) => name !== normalizedPreferred),
+      ]
+    : [normalizedPreferred];
+  const seen = new Set();
+  const candidates = ordered.filter((name) => {
+    if (!name || seen.has(name)) return false;
+    seen.add(name);
+    return true;
+  });
+
+  let preferredProbe = null;
+  for (const runnerName of candidates) {
+    const bootstrap = readRunnerReadyState(home, runtimePython, runnerName, envOverrides);
+    if (bootstrap.ready) {
+      return { ok: true, runnerName, preferredRunner: normalizedPreferred, fallback: runnerName !== normalizedPreferred, probe: null };
+    }
+    const probe = probeRunnerReady(home, runtimePython, runnerName, envOverrides);
+    if (runnerName === normalizedPreferred) {
+      preferredProbe = probe;
+    }
+    if (probe && probe.ok === true) {
+      return { ok: true, runnerName, preferredRunner: normalizedPreferred, fallback: runnerName !== normalizedPreferred, probe };
+    }
+  }
+  return { ok: false, runnerName: normalizedPreferred, preferredRunner: normalizedPreferred, fallback: false, probe: preferredProbe };
+}
+
 function readCodexBootstrapState(home, runtimePython, envOverrides = {}) {
   const snippet = [
     'import json, pathlib, sys',
@@ -1211,10 +1467,12 @@ function probeCodexBootstrap(home, runtimePython, envOverrides = {}) {
   };
 }
 
-function createCodexPreflightError(home, probe) {
-  const report = writeCodexPreflightReport(home, probe);
-  const error = new Error(probe?.summary || 'Codex startup probe failed.');
-  error.code = 'DS_CODEX_PREFLIGHT';
+function createRunnerPreflightError(home, runnerName, probe) {
+  const report = writeRunnerPreflightReport(home, runnerName, probe);
+  const normalizedRunner = normalizeRunnerName(runnerName, 'codex');
+  const error = new Error(probe?.summary || `${normalizedRunner} startup probe failed.`);
+  error.code = 'DS_RUNNER_PREFLIGHT';
+  error.runnerName = normalizedRunner;
   error.reportPath = report.path;
   error.reportUrl = report.url;
   error.probe = probe;
@@ -1239,6 +1497,9 @@ function parseLauncherArgs(argv) {
   let auth = null;
   let codexProfile = null;
   let codexBinary = null;
+  let runner = null;
+  let tuiDebug = false;
+  let tuiDebugLogPath = null;
 
   if (args[0] === 'ui') {
     args.shift();
@@ -1257,6 +1518,7 @@ function parseLauncherArgs(argv) {
     else if (arg === '--open-browser') openBrowser = true;
     else if (arg === '--daemon-only') daemonOnly = true;
     else if (arg === '--skip-update-check') skipUpdateCheck = true;
+    else if (arg === '--debug') tuiDebug = true;
     else if (arg === '--here') continue;
     else {
       const parsedYolo = parseYoloArg(args, index, yolo);
@@ -1284,6 +1546,11 @@ function parseLauncherArgs(argv) {
         if (!next.ok) return { help: false, error: next.error };
         codexBinary = next.value;
         index += 1;
+      } else if (arg === '--runner') {
+        const next = readRequiredOptionValue(args, index, '--runner');
+        if (!next.ok) return { help: false, error: next.error };
+        runner = next.value;
+        index += 1;
       } else if (arg === '--host') {
         const next = readRequiredOptionValue(args, index, '--host');
         if (!next.ok) return { help: false, error: next.error };
@@ -1311,6 +1578,12 @@ function parseLauncherArgs(argv) {
         if (!next.ok) return { help: false, error: next.error };
         questId = next.value;
         index += 1;
+      } else if (arg === '--debug-log') {
+        const next = readRequiredOptionValue(args, index, '--debug-log');
+        if (!next.ok) return { help: false, error: next.error };
+        tuiDebugLogPath = next.value;
+        tuiDebug = true;
+        index += 1;
       } else if (arg === '--mode') {
         const next = readRequiredOptionValue(args, index, '--mode');
         if (!next.ok) return { help: false, error: next.error };
@@ -1341,10 +1614,13 @@ function parseLauncherArgs(argv) {
     skipUpdateCheck,
     yolo,
     auth,
-    codexProfile,
-    codexBinary,
-    error: null,
-  };
+	    codexProfile,
+	    codexBinary,
+	    runner,
+	    tuiDebug,
+	    tuiDebugLogPath,
+	    error: null,
+	  };
 }
 
 function printUpdateHelp() {
@@ -2656,7 +2932,9 @@ function syncUvProjectEnvironment(home, uvBinary, pythonTarget, editable) {
     args.splice(3, 0, '--compile-bytecode');
   }
   if (!editable) {
-    args.push('--no-editable');
+    // Force-refresh the local project package so same-version source installs
+    // don't reuse a stale cached wheel during runtime rebuilds.
+    args.push('--no-editable', '--reinstall-package', 'deepscientist');
   }
   step(2, 4, 'Syncing locked Python environment');
   const result = runSync(uvBinary, args, {
@@ -4279,6 +4557,7 @@ async function performSelfUpdate(home, options = {}) {
     };
   }
 
+  const npmBinary = resolveNpmBinary();
   const installResult = runNpmInstallLatest(home, npmBinary);
   if (!installResult.ok) {
     const message = summarizeUpdateFailure(installResult);
@@ -4674,7 +4953,7 @@ function readConfiguredUiAddressFromFile(home, fallbackHost, fallbackPort) {
   }
 }
 
-async function startDaemon(home, runtimePython, host, port, proxy = null, envOverrides = {}, authEnabled = false) {
+async function startDaemon(home, runtimePython, host, port, proxy = null, envOverrides = {}, authEnabled = false, runnerName = null, allowRunnerFallback = true) {
   const browserUrl = browserUiUrl(host, port);
   const daemonBindUrl = bindUiUrl(host, port);
   const state = readDaemonState(home);
@@ -4711,6 +4990,7 @@ async function startDaemon(home, runtimePython, host, port, proxy = null, envOve
         reused: true,
         authEnabled: stateAuthEnabled,
         authToken: resolvedAuthToken,
+        runnerName: normalizeRunnerName(runnerName || readConfiguredDefaultRunner(home, "codex"), "codex"),
       };
     }
     console.error(
@@ -4728,13 +5008,21 @@ async function startDaemon(home, runtimePython, host, port, proxy = null, envOve
     removeDaemonState(home);
   }
 
-  const bootstrapState = readCodexBootstrapState(home, runtimePython, envOverrides);
-  if (!bootstrapState.codex_ready) {
-    console.log('Codex is not marked ready yet. Running startup probe...');
-    const probe = probeCodexBootstrap(home, runtimePython, envOverrides);
-    if (!probe || probe.ok !== true) {
-      throw createCodexPreflightError(home, probe);
-    }
+  const requestedRunner = normalizeRunnerName(runnerName || readConfiguredDefaultRunner(home, "codex"), "codex");
+  const startupRunner = resolveStartupRunner(home, runtimePython, requestedRunner, envOverrides, {
+    allowFallback: allowRunnerFallback,
+  });
+  if (!startupRunner.ok) {
+    throw createRunnerPreflightError(home, requestedRunner, startupRunner.probe);
+  }
+  const effectiveRunner = startupRunner.runnerName;
+  const effectiveEnvOverrides = {
+    ...envOverrides,
+    DEEPSCIENTIST_DEFAULT_RUNNER: effectiveRunner,
+    DEEPSCIENTIST_ENABLE_RUNNER: effectiveRunner,
+  };
+  if (startupRunner.fallback) {
+    console.log(`WARNING: ${requestedRunner} is not ready yet. Starting DeepScientist with fallback runner \`${effectiveRunner}\` for this session.`);
   }
 
   ensureNodeBundle('src/ui', 'dist/index.html');
@@ -4744,7 +5032,7 @@ async function startDaemon(home, runtimePython, host, port, proxy = null, envOve
     host,
     port,
     proxy,
-    envOverrides,
+    envOverrides: effectiveEnvOverrides,
     authEnabled,
     authToken: desiredAuthToken,
   });
@@ -4764,7 +5052,7 @@ async function startDaemon(home, runtimePython, host, port, proxy = null, envOve
         host,
         port,
         proxy,
-        envOverrides,
+        envOverrides: effectiveEnvOverrides,
         daemonId: String((liveState || {}).daemon_id || ''),
       });
       if (supervisorPid) {
@@ -4776,6 +5064,7 @@ async function startDaemon(home, runtimePython, host, port, proxy = null, envOve
         reused: false,
         authEnabled,
         authToken: desiredAuthToken,
+        runnerName: effectiveRunner,
       };
     }
     await sleep(250);
@@ -4836,14 +5125,15 @@ function openBrowser(url) {
   return false;
 }
 
-function handleCodexPreflightFailure(error) {
-  if (!error || error.code !== 'DS_CODEX_PREFLIGHT') {
+function handleRunnerPreflightFailure(error) {
+  if (!error || error.code !== 'DS_RUNNER_PREFLIGHT') {
     return false;
   }
   const errorLabel = colorize('\u001B[1;38;5;196m', 'ERROR');
   const warningLabel = colorize('\u001B[1;38;5;214m', 'WARNING');
   console.error('');
-  console.error(`${errorLabel} DeepScientist could not start because Codex is not ready yet.`);
+  const runnerLabel = String(error.runnerName || 'codex').trim() || 'runner';
+  console.error(`${errorLabel} DeepScientist could not start because ${runnerLabel} is not ready yet.`);
   console.error(`Report: ${error.reportPath}`);
   if (Array.isArray(error.probe?.errors)) {
     for (const item of error.probe.errors) {
@@ -4873,7 +5163,7 @@ function handleCodexPreflightFailure(error) {
   return true;
 }
 
-function launchTui(url, questId, home, runtimePython, authToken = null) {
+function launchTui(url, questId, home, runtimePython, authToken = null, debugOptions = {}) {
   const entry = ensureNodeBundle('src/tui', 'dist/index.js');
   const args = [entry, '--base-url', url];
   if (questId) {
@@ -4882,6 +5172,12 @@ function launchTui(url, questId, home, runtimePython, authToken = null) {
   if (typeof authToken === 'string' && authToken.trim()) {
     args.push('--auth-token', authToken.trim());
   }
+  if (debugOptions && debugOptions.enabled) {
+    args.push('--debug');
+  }
+  if (debugOptions && typeof debugOptions.logPath === 'string' && debugOptions.logPath.trim()) {
+    args.push('--debug-log', debugOptions.logPath.trim());
+  }
   const child = spawn(process.execPath, args, {
     cwd: repoRoot,
     stdio: 'inherit',
@@ -5161,7 +5457,9 @@ async function launcherMain(rawArgs) {
     process.exit(1);
   }
 
-  const home = options.home || resolveHome(rawArgs);
+  const home = (options.stop || options.status || options.restart)
+    ? resolveManagementHome(rawArgs, options)
+    : (options.home || resolveHome(rawArgs));
   applyLauncherProxy(options.proxy);
   ensureDir(home);
   registerCurrentInstall(home);
@@ -5205,9 +5503,12 @@ async function launcherMain(rawArgs) {
     yolo: options.yolo,
     profile: options.codexProfile,
     binary: options.codexBinary,
+    runner: options.runner,
   });
   ensureInitialized(home, runtimePython);
-  await maybeHandleMiniMaxCodexVersion(home, runtimePython, options);
+  if (!options.runner || String(options.runner).trim().toLowerCase() === "codex") {
+    await maybeHandleMiniMaxCodexVersion(home, runtimePython, options);
+  }
   if (await maybeHandleStartupUpdate(home, rawArgs, options)) {
     return true;
   }
@@ -5236,9 +5537,20 @@ async function launcherMain(rawArgs) {
   step(4, 4, 'Starting local daemon and UI surfaces');
   let started;
   try {
-    started = await startDaemon(home, runtimePython, host, port, options.proxy, codexOverrideEnv, authEnabled);
+    const selectedRunner = normalizeRunnerName(options.runner || readConfiguredDefaultRunner(home, "codex"), "codex");
+    started = await startDaemon(
+      home,
+      runtimePython,
+      host,
+      port,
+      options.proxy,
+      codexOverrideEnv,
+      authEnabled,
+      selectedRunner,
+      !options.runner
+    );
   } catch (error) {
-    if (handleCodexPreflightFailure(error)) return true;
+    if (handleRunnerPreflightFailure(error)) return true;
     throw error;
   }
   const browserOpened = shouldOpenBrowser ? openBrowser(started.url) : false;
@@ -5254,6 +5566,7 @@ async function launcherMain(rawArgs) {
     yolo: options.yolo,
     authEnabled: started.authEnabled,
     authToken: started.authToken,
+    runnerName: started.runnerName || selectedRunner,
   });
 
   if (options.daemonOnly) {
@@ -5262,7 +5575,10 @@ async function launcherMain(rawArgs) {
   if (mode === 'web') {
     process.exit(0);
   }
-  launchTui(browserUiUrl(host, port), options.questId, home, runtimePython, started.authToken);
+  launchTui(browserUiUrl(host, port), options.questId, home, runtimePython, started.authToken, {
+    enabled: options.tuiDebug,
+    logPath: options.tuiDebugLogPath,
+  });
   return true;
 }
 
@@ -5305,24 +5621,34 @@ async function main() {
     const home = resolveHome(args);
     const pythonRuntime = ensurePythonRuntime(home);
     const runtimePython = pythonRuntime.runtimePython;
+    const runnerOptionForEnv = positional.value === 'doctor' || positional.value === 'docker'
+      ? null
+      : readOptionValue(args, '--runner');
     const codexOverrideEnv = buildCodexOverrideEnv({
       yolo: resolveYoloFlag(args, true),
       profile: readOptionValue(args, '--codex-profile'),
       binary: readOptionValue(args, '--codex'),
+      runner: runnerOptionForEnv,
     });
     if (positional.value === 'run' || positional.value === 'daemon') {
       maybePrintOptionalLatexNotice(home);
     }
     if (positional.value === 'run' || positional.value === 'daemon') {
-      const bootstrapState = readCodexBootstrapState(home, runtimePython, codexOverrideEnv);
-      if (!bootstrapState.codex_ready) {
+      const selectedRunner = normalizeRunnerName(readOptionValue(args, '--runner') || readConfiguredDefaultRunner(home, "codex"), "codex");
+      const bootstrapState = selectedRunner === "codex"
+        ? readCodexBootstrapState(home, runtimePython, codexOverrideEnv)
+        : readRunnerBootstrapState(home, runtimePython, selectedRunner, codexOverrideEnv);
+      const runnerReady = selectedRunner === "codex" ? Boolean(bootstrapState.codex_ready) : Boolean(bootstrapState.ready);
+      if (!runnerReady) {
         try {
-          const probe = probeCodexBootstrap(home, runtimePython, codexOverrideEnv);
+          const probe = selectedRunner === "codex"
+            ? probeCodexBootstrap(home, runtimePython, codexOverrideEnv)
+            : probeRunnerBootstrap(home, runtimePython, selectedRunner, codexOverrideEnv);
           if (!probe || probe.ok !== true) {
-            throw createCodexPreflightError(home, probe);
+            throw createRunnerPreflightError(home, selectedRunner, probe);
           }
         } catch (error) {
-          if (handleCodexPreflightFailure(error)) return;
+          if (handleRunnerPreflightFailure(error)) return;
           throw error;
         }
       }
@@ -5348,6 +5674,7 @@ module.exports = {
     legacyVenvRootPath,
     resolveUvBinary,
     resolveHome,
+    resolveManagementHome,
     parseLauncherArgs,
     generateBrowserAuthToken,
     appendBrowserAuthToken,