synabun 2.0.0-beta → 2.0.0

package/neural-interface/i18n/en.json

@@ -136,6 +136,44 @@
     "stillOffline": "Still offline \u2014 start the server and try again",
     "runCommand": "Run this command to start the server:",
     "copyToClipboard": "Copy to clipboard",
+    "start": {
+      "asked": "Asked your system to start SynaBun. If your browser shows a prompt, choose Open.",
+      "unconfirmedMac": "No word from the launcher yet. If your browser is asking for permission, choose Open: a Terminal window then opens with the server.",
+      "unconfirmedWindows": "No word from the launcher yet. If your browser is asking for permission, choose Open: a console window then opens with the server.",
+      "unconfirmedLinux": "No word from the launcher yet. If your browser is asking for permission, choose Open: the server then starts in the background.",
+      "stalled": "Nothing has answered. If no prompt or window appeared, run the command below once: it also repairs this button.",
+      "launcherRunning": "The launcher is running.",
+      "terminalOpened": "A Terminal window was opened for the server.",
+      "terminalQuiet": "A Terminal window was opened {seconds} s ago, but the server has not started in it. Look at that window.",
+      "processStarted": "The server's supervisor was started.",
+      "checking": "Checking the install.",
+      "dependencies": "Installing dependencies with npm. A first start, or the first after an update, takes a few minutes.",
+      "browser": "Downloading the automation browser. This happens once.",
+      "build": "Building the MCP server.",
+      "snapshot": "Backing up your data before the first start of this version.",
+      "snapshotSized": "Backing up your data before the first start of this version: {files} files, {megabytes} MB.",
+      "server": "The server process is running. Waiting for it to answer.",
+      "listening": "The server is listening. Connecting.",
+      "answered": "The server answered the launcher. Connecting.",
+      "quiet": "Nothing new from the start for {seconds} s.",
+      "failed": "The start failed: {reason}",
+      "failedHint": "Run the command below to see the full output, or try again.",
+      "failedLog": "Launcher log: {path}",
+      "gaveUp": "The server was started but has not answered. Check its window, or run the command below.",
+      "online": "The server is up. Loading SynaBun.",
+      "trailLauncher": "Launcher started",
+      "trailTerminal": "Terminal opened",
+      "trailProcess": "Supervisor started",
+      "trailSupervisor": "Supervisor running",
+      "trailServer": "Server process started",
+      "trailListening": "Server listening",
+      "elapsedLabel": "Time since Start was pressed",
+      "headingStarting": "Starting the server",
+      "headingReady": "Server is up",
+      "headingFailed": "The server did not start"
+    },
+    "runCommandOr": "Or run this command:",
+    "runCommandSetup": "Run this command once. It also sets up the Start button:",
     "serverOffline": "Server Offline",
     "serverNotRunning": "The Neural Interface server is not running",
     "connectionFailed": "Connection Failed",
@@ -525,7 +563,7 @@
           "help": "Storage, search, backups"
         },
         "ai_decisions": {
-          "label": "AI decisions",
+          "label": "Jev",
           "help": "Smart judgments and cost"
         },
         "projects": {
@@ -571,7 +609,7 @@
           "purpose": "See where your memories live, choose how SynaBun finds them, and keep a copy you can restore."
         },
         "ai_decisions": {
-          "title": "AI decisions",
+          "title": "Jev",
           "purpose": "Control where smart judgments help, what they may use, and how much they cost."
         },
         "projects": {
@@ -3597,6 +3635,7 @@
       "judgments": {
         "showEveryJudgmentAboutThisMemory": ": show every judgment about this memory in the log",
         "checkingTypesafe": "Checking TypeSafe…",
+        "learnMoreAtTypesafe": "Learn more at",
         "jevTypesafeSystemOneReturnsTyped": "Jev (TypeSafe System One) returns typed judgments where SynaBun used to guess with a regex or a similarity constant. The key is stored in",
         "andNeverLeavesTheServerOnly": "and never leaves the server; only its last four characters reach this page.",
         "apiKey": "API key",

package/neural-interface/i18n/pt-BR.json

@@ -131,6 +131,44 @@
     "stillOffline": "Ainda offline — inicie o servidor e tente novamente",
     "runCommand": "Execute este comando para iniciar o servidor:",
     "copyToClipboard": "Copiar para a área de transferência",
+    "start": {
+      "asked": "Pedimos ao sistema para iniciar o SynaBun. Se o navegador mostrar um aviso, escolha Abrir.",
+      "unconfirmedMac": "Ainda sem notícias do iniciador. Se o navegador estiver pedindo permissão, escolha Abrir: uma janela do Terminal abre em seguida com o servidor.",
+      "unconfirmedWindows": "Ainda sem notícias do iniciador. Se o navegador estiver pedindo permissão, escolha Abrir: uma janela de console abre em seguida com o servidor.",
+      "unconfirmedLinux": "Ainda sem notícias do iniciador. Se o navegador estiver pedindo permissão, escolha Abrir: o servidor inicia em seguida em segundo plano.",
+      "stalled": "Nada respondeu. Se nenhum aviso ou janela apareceu, execute o comando abaixo uma vez: ele também conserta este botão.",
+      "launcherRunning": "O iniciador está em execução.",
+      "terminalOpened": "Uma janela do Terminal foi aberta para o servidor.",
+      "terminalQuiet": "Uma janela do Terminal foi aberta há {seconds} s, mas o servidor não iniciou nela. Veja essa janela.",
+      "processStarted": "O supervisor do servidor foi iniciado.",
+      "checking": "Verificando a instalação.",
+      "dependencies": "Instalando dependências com o npm. A primeira inicialização, ou a primeira depois de uma atualização, leva alguns minutos.",
+      "browser": "Baixando o navegador de automação. Isso acontece uma única vez.",
+      "build": "Compilando o servidor MCP.",
+      "snapshot": "Fazendo backup dos seus dados antes da primeira inicialização desta versão.",
+      "snapshotSized": "Fazendo backup dos seus dados antes da primeira inicialização desta versão: {files} arquivos, {megabytes} MB.",
+      "server": "O processo do servidor está em execução. Aguardando a resposta dele.",
+      "listening": "O servidor está escutando. Conectando.",
+      "answered": "O servidor respondeu ao iniciador. Conectando.",
+      "quiet": "Nada de novo na inicialização há {seconds} s.",
+      "failed": "A inicialização falhou: {reason}",
+      "failedHint": "Execute o comando abaixo para ver a saída completa, ou tente novamente.",
+      "failedLog": "Log do iniciador: {path}",
+      "gaveUp": "O servidor foi iniciado, mas não respondeu. Verifique a janela dele ou execute o comando abaixo.",
+      "online": "O servidor está no ar. Carregando o SynaBun.",
+      "trailLauncher": "Iniciador acionado",
+      "trailTerminal": "Terminal aberto",
+      "trailProcess": "Supervisor iniciado",
+      "trailSupervisor": "Supervisor em execução",
+      "trailServer": "Processo do servidor iniciado",
+      "trailListening": "Servidor escutando",
+      "elapsedLabel": "Tempo desde que Iniciar foi pressionado",
+      "headingStarting": "Iniciando o servidor",
+      "headingReady": "Servidor no ar",
+      "headingFailed": "O servidor não iniciou"
+    },
+    "runCommandOr": "Ou execute este comando:",
+    "runCommandSetup": "Execute este comando uma vez. Ele também configura o botão Iniciar:",
     "serverOffline": "Servidor offline",
     "serverNotRunning": "O servidor do Neural Interface não está em execução",
     "connectionFailed": "Falha na conexão",
@@ -511,7 +549,7 @@
           "help": "Armazenamento, busca e backups"
         },
         "ai_decisions": {
-          "label": "Decisões de IA",
+          "label": "Jev",
           "help": "Avaliações inteligentes e custo"
         },
         "projects": {
@@ -557,7 +595,7 @@
           "purpose": "Veja onde suas memórias ficam, escolha como o SynaBun as encontra e mantenha uma cópia que você possa restaurar."
         },
         "ai_decisions": {
-          "title": "Decisões de IA",
+          "title": "Jev",
           "purpose": "Controle onde as avaliações inteligentes ajudam, o que podem usar e quanto custam."
         },
         "projects": {
@@ -3583,6 +3621,7 @@
       "judgments": {
         "showEveryJudgmentAboutThisMemory": ": mostrar no registro todas as avaliações desta memória",
         "checkingTypesafe": "Verificando TypeSafe…",
+        "learnMoreAtTypesafe": "Saiba mais em",
         "jevTypesafeSystemOneReturnsTyped": "Jev (TypeSafe System One) retorna avaliações tipadas onde o SynaBun antes fazia estimativas com regex ou uma constante de similaridade. A chave fica armazenada em",
         "andNeverLeavesTheServerOnly": "e nunca sai do servidor; apenas seus quatro últimos caracteres chegam a esta página.",
         "apiKey": "Chave de API",

package/neural-interface/lib/assistant-envelope.js

@@ -158,13 +158,16 @@ export function codexControlResponse(pending, response = {}) {
   // Codex matches a reply by id value and type: 0 and "0" are different requests to it.
   const base = { requestId: native.rpcId ?? pending.request_id, responseToken: randomUUID(), threadId: native.threadId || null, turnId: native.turnId || null, toolCallId: native.toolCallId || null };
   if (method === 'item/commandExecution/requestApproval' || method === 'item/fileChange/requestApproval') {
-    const available = Array.isArray(native.availableDecisions) && native.availableDecisions.length
-      ? native.availableDecisions.map((d) => (typeof d === 'string' ? d : Object.keys(d)[0]))
+    const available = Array.isArray(native.availableDecisions)
+      ? native.availableDecisions
       : ['accept', 'acceptForSession', 'decline', 'cancel'];
-    let decision;
-    if (response.decision && available.includes(response.decision)) decision = response.decision;
-    else if (allow) decision = response.always && available.includes('acceptForSession') ? 'acceptForSession' : 'accept';
-    else decision = response.cancel && available.includes('cancel') ? 'cancel' : 'decline';
+    // The UI puts policy amendment objects in result.decision and only their
+    // label in decision. Preserve the wire value for strict server validation.
+    let decision = response.result?.decision ?? response.decision;
+    if (decision == null) {
+      if (allow) decision = response.always && available.includes('acceptForSession') ? 'acceptForSession' : 'accept';
+      else decision = response.cancel && available.includes('cancel') ? 'cancel' : 'decline';
+    }
     return { ...base, result: { decision } };
   }
   if (method === 'item/permissions/requestApproval') {

package/neural-interface/lib/augmented-path.js

@@ -9,14 +9,21 @@
 // Extracted from server.js so the model catalog can share it: discovery spawns
 // the CLI by name too, and without this a daemon-started server silently
 // degrades to the static fallback model list. The version-skew guard has the
-// same dependency — it compares the installed CLI against the SDK-bundled one,
-// and a CLI it cannot resolve reads as "nothing to compare" rather than a skew.
+// same dependency — it compares the installed CLI against the release the Agent
+// SDK was built for, and a CLI it cannot resolve reads as "nothing to compare".
+//
+// SYNABUN_TOOL_DISCOVERY=path turns the additions off: the tools are then looked
+// for on the PATH this process was given and nowhere else. It is what a check
+// of "nothing is installed" needs on a machine where something is (the
+// packaged application's own run), and what a user sets to make SynaBun see
+// exactly their PATH.
 
 import os from 'node:os';
 import { join, dirname, delimiter } from 'node:path';
 import { existsSync } from 'node:fs';
 
 export function getAugmentedPath() {
+  if (process.env.SYNABUN_TOOL_DISCOVERY === 'path') return process.env.PATH || '';
   const home = os.homedir();
   const npmPrefix = process.env.NPM_CONFIG_PREFIX || process.env.npm_config_prefix || '';
   const extra = process.platform === 'win32'
@@ -38,7 +45,20 @@ export function getAugmentedPath() {
       join(home, '.npm-global', 'bin'),
       npmPrefix ? join(npmPrefix, 'bin') : '',
     ];
-  const entries = [...extra.filter(d => d && existsSync(d)), ...(process.env.PATH || '').split(delimiter)];
+  // Where the tools' own installers put them, for a PATH that names none of it:
+  // Claude Code's native installer (also on Windows), its older local install,
+  // OpenCode's install script. After the user's PATH, so that they never
+  // outrank a choice the user made there.
+  const fallback = [
+    join(home, '.local', 'bin'),
+    join(home, '.claude', 'local'),
+    join(home, '.opencode', 'bin'),
+  ];
+  const entries = [
+    ...extra.filter(d => d && existsSync(d)),
+    ...(process.env.PATH || '').split(delimiter),
+    ...fallback.filter(d => existsSync(d)),
+  ];
   const seen = new Set();
   return entries.filter((entry) => {
     if (!entry) return false;

package/neural-interface/lib/browser-language.js

@@ -0,0 +1,83 @@
+const DEFAULT_LOCALE = 'en-US';
+const DEFAULT_ACCEPT_LANGUAGE = 'en-US,en;q=0.9';
+// HTTP language ranges allow '*' and an optional qvalue with at most three decimals.
+const LANGUAGE_RANGE = /^(\*|[a-z]{1,8}(?:-[a-z0-9]{1,8})*)(?:[ \t]*;[ \t]*q[ \t]*=[ \t]*(0(?:\.\d{0,3})?|1(?:\.0{0,3})?))?$/i;
+
+function isAutomatic(value) {
+  return value == null || (typeof value === 'string' && !value.trim());
+}
+
+function canonicalLocale(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    return Intl.getCanonicalLocales(value.trim())[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+function parseAcceptLanguage(value) {
+  if (typeof value !== 'string' || /[\x00-\x08\x0a-\x1f\x7f]/.test(value)) return null;
+  const header = value.trim();
+  const entries = header.split(',').map(entry => entry.trim()).filter(Boolean);
+  if (!entries.length) return null;
+
+  const languages = new Set();
+  for (const entry of entries) {
+    const match = LANGUAGE_RANGE.exec(entry);
+    if (!match) return null;
+    const [, range, quality] = match;
+    if (range === '*' || (quality !== undefined && Number(quality) === 0)) continue;
+    // A valid HTTP language range need not be a locale supported by Intl (e.g. x-private).
+    const locale = canonicalLocale(range);
+    if (locale) languages.add(locale);
+  }
+  return { header, languages: [...languages] };
+}
+
+/** Resolve legacy settings and request headers without rewriting the saved config. */
+export function resolveBrowserLanguage(savedCfg = {}, requestAcceptLanguage) {
+  const savedLocale = canonicalLocale(savedCfg.locale);
+  const savedHeader = parseAcceptLanguage(savedCfg.acceptLanguage);
+  const requestHeader = savedHeader ? null : parseAcceptLanguage(requestAcceptLanguage);
+  const resolvedHeader = savedHeader || requestHeader || parseAcceptLanguage(DEFAULT_ACCEPT_LANGUAGE);
+  const locale = savedLocale || resolvedHeader.languages[0] || DEFAULT_LOCALE;
+  const warnings = [];
+  if (!isAutomatic(savedCfg.locale) && !savedLocale) {
+    warnings.push({ field: 'locale', value: locale });
+  }
+  if (!isAutomatic(savedCfg.acceptLanguage) && !savedHeader) {
+    warnings.push({ field: 'acceptLanguage', value: resolvedHeader.header });
+  }
+  if (!savedHeader && !isAutomatic(requestAcceptLanguage) && !requestHeader) {
+    warnings.push({ field: 'request Accept-Language', value: resolvedHeader.header });
+  }
+  return {
+    locale,
+    acceptLanguage: resolvedHeader.header,
+    languages: resolvedHeader.languages.length ? resolvedHeader.languages : [locale],
+    warnings,
+  };
+}
+
+/** Return a normalized copy; invalid explicit language fields throw with status/field. */
+export function validateBrowserLanguageConfig(config) {
+  const normalized = { ...config };
+  for (const field of ['locale', 'acceptLanguage']) {
+    if (!Object.hasOwn(config, field)) continue;
+    const value = config[field];
+    if (isAutomatic(value)) {
+      normalized[field] = null;
+      continue;
+    }
+    const validated = field === 'locale' ? canonicalLocale(value) : parseAcceptLanguage(value)?.header;
+    if (!validated) {
+      const help = field === 'locale'
+        ? 'use a single locale tag such as pt-BR, or leave it blank for automatic detection'
+        : 'use comma-separated language ranges (or *) with optional q weights between 0 and 1 (up to three decimal places), or leave it blank';
+      throw Object.assign(new Error(`Invalid ${field}: ${help}.`), { status: 400, field });
+    }
+    normalized[field] = validated;
+  }
+  return normalized;
+}

package/neural-interface/lib/claude-agent-bridge.js

@@ -25,14 +25,9 @@ import { detectProject as memoryProject } from '../../mcp-server/dist/config.js'
 // WS bound, so page-refresh reattach is the same object.
 
 import { query, startup } from '@anthropic-ai/claude-agent-sdk';
-import { CLAUDE_EFFORT_LEVELS, checkClaudeCliSkew, markAlignedClaudeExecutableFailed } from './claude-model-catalog.js';
-import {
-  claudeRuntime,
-  clearNativeBinaryCache,
-  isNativeBinaryLaunchFailure,
-  planRuntimeRecovery,
-  resolveClaudeExecutableOverride,
-} from './native-binary-runtime.js';
+import { CLAUDE_EFFORT_LEVELS } from './claude-model-catalog.js';
+import { CLAUDE_NOT_INSTALLED, resolveClaudeSdkExecutable } from './claude-executable.js';
+import { diagnoseLaunchFailure, isNativeBinaryLaunchFailure } from './native-binary-runtime.js';
 import { normalizePanelSession, startSignature, applyPanelSessionOptions, liveSettingsPatch, normalizeMcpServers, mergeTabMcpServers } from './claude-panel-session.js';
 import { SESSION_REQUESTS, runSessionRequest, slimRewind, slimMcpStatus } from './claude-panel-requests.js';
 import { applyTemporaryOptions, plansDirsOf, planFileOfToolCall, removeTemporaryPlanFiles } from './claude-temporary.js';
@@ -348,15 +343,9 @@ export class ClaudeSession {
     this.lastPrompt = null;
     this.stallRetries = 0;
 
-    // Native-runtime recovery latches. Set here and NOWHERE else — resetting
-    // them on query recreation would turn a permanently broken binary into an
-    // infinite repair/retry loop.
-    this._nativeRepairTried = false;
-    this._fallbackBin = null;
-    // The installed CLI the current Query runs on because it is newer than the
-    // bundled one (see ensureQuery). Per-Query, not a latch: a launch failure is
-    // latched process-wide in claude-model-catalog.js instead.
-    this._alignedBin = null;
+    // The Claude Code executable the current Query was started with (see
+    // ensureQuery): what a launch failure is diagnosed against.
+    this._claudeExecutable = null;
 
     this.pendingPerms = new Map(); // requestId → { toolName, resolve, input, kind, wire }
     this.alwaysAllowed = new Set();
@@ -499,6 +488,31 @@ export class ClaudeSession {
         return null;
       }
     }
+    // Which Claude Code runs this session: the user's own installation, always.
+    // SynaBun carries none (lib/external-tools.js at the package root) and the
+    // SDK is never left to look for one. The host answers (deps.claudeExecutable,
+    // lib/claude-executable.js): an explicit override from cli-config.json
+    // ("claude-skin": { "sdkExecutable": "…" }), else the installed Claude Code.
+    // The model picker lists that same installation's models, so an alias means
+    // in the session what it meant in the picker.
+    //
+    // Nothing installed is an ordinary state: the start is refused with the
+    // sentence the panel shows its install help on, and nothing was started.
+    // The SDK itself is never called without an executable; only a host that
+    // brings its own query factory and no resolver (a test) starts without one.
+    let executable = null;
+    if (typeof deps.claudeExecutable === 'function') {
+      try { executable = deps.claudeExecutable() || null; } catch { executable = null; }
+    } else if (deps.sdkExecutable) {
+      executable = resolveClaudeSdkExecutable({ sdkExecutable: deps.sdkExecutable });
+    }
+    const ownFactory = typeof (warm ? deps.startupFactory : deps.queryFactory) === 'function';
+    if (!executable?.path && (typeof deps.claudeExecutable === 'function' || !ownFactory)) {
+      this._closeWarm();
+      this._startRefused = { code: 'claude_not_installed', message: executable?.reason || CLAUDE_NOT_INSTALLED };
+      log(`session create refused: no Claude Code to run (${executable?.reason || 'not installed'})`);
+      return null;
+    }
     if (this._warm) {
       const w = this._warm;
       this._warm = null;
@@ -732,51 +746,20 @@ export class ClaudeSession {
       this._tempPlansDirs = plansDirsOf(options.env, { cwd: workDir, settings: options.settings });
       if (!this._tempSince) this._tempSince = Date.now();
     }
-    // Which Claude binary runs this session, first match wins:
-    //   1. an explicit override — cli-config.json → "claude-skin": { "sdkExecutable": "…" },
-    //      either a .js entrypoint (launched via node) or a native binary path;
-    //   2. the installed CLI we fell back to after the bundled one failed to launch;
-    //   3. the installed CLI when it is newer than the bundled one. The model picker
-    //      lists the installed CLI's models, and an older binary resolves the same
-    //      alias to an older model (alignedClaudeExecutable, claude-model-catalog.js);
-    //   4. the SDK's bundled, version-matched CLI.
-    //
-    // The SDK uses pathToClaudeCodeExecutable verbatim with zero validation, so
-    // everything is vetted here first — notably a bare command name, which would
-    // ENOENT under the SDK's spawn(shell:false).
-    const sdkExec = deps.sdkExecutable;
-    const override = resolveClaudeExecutableOverride(sdkExec);
-    this._alignedBin = null;
-    let runtimeLabel = 'bundled';
-    if (override.path) {
-      options.pathToClaudeCodeExecutable = override.path;
-      runtimeLabel = 'override';
-    } else if (sdkExec) {
-      log('ignoring sdkExecutable override:', override.reason);
-      this.send({ type: 'stderr', text: `Ignoring sdkExecutable override — ${override.reason}` });
-    }
-
-    if (!options.pathToClaudeCodeExecutable) {
-      let aligned = null;
-      if (!this._fallbackBin) {
-        try { aligned = deps.alignedClaudeBin?.() || null; } catch { aligned = null; }
-      }
-      if (this._fallbackBin) {
-        // A previous turn proved the bundled binary unusable; stay on the CLI we
-        // already fell back to rather than re-failing every turn.
-        options.pathToClaudeCodeExecutable = this._fallbackBin;
-        runtimeLabel = 'fallback';
-      } else if (aligned) {
-        options.pathToClaudeCodeExecutable = aligned;
-        this._alignedBin = aligned;
-        runtimeLabel = aligned;
-      } else {
-        // Called for its side effect only: this stats the binary the SDK is about
-        // to resolve and restores the execute bit if it is missing. We
-        // deliberately do NOT pass the resolved path on — letting the SDK resolve
-        // for itself keeps us correct even if its resolution logic changes.
-        claudeRuntime();
-      }
+    // The executable resolved at the top of this call. The SDK uses
+    // pathToClaudeCodeExecutable verbatim with zero validation, so it was vetted
+    // there — notably a bare command name, which would ENOENT under the SDK's
+    // spawn(shell:false).
+    let runtimeLabel = 'unset';
+    this._claudeExecutable = null;
+    if (executable?.ignored) {
+      log('ignoring sdkExecutable override:', executable.ignored);
+      this.send({ type: 'stderr', text: `Ignoring sdkExecutable override — ${executable.ignored}` });
+    }
+    if (executable?.path) {
+      options.pathToClaudeCodeExecutable = executable.path;
+      this._claudeExecutable = executable.path;
+      runtimeLabel = executable.source === 'override' ? 'override' : executable.path;
     }
 
     if (warm) {
@@ -1256,94 +1239,18 @@ export class ClaudeSession {
   }
 
   /**
-   * The bundled native CLI failed to launch.
+   * The user's Claude Code would not start.
    *
    * The SDK's own message for this always blames a musl/glibc mismatch, which is
-   * only ever right on Linux — on macOS and Windows the real cause is almost
-   * always a missing execute bit (npm does not preserve it for binaries shipped
-   * without a `bin` entry, and this repo commits node_modules).
-   *
-   * Recovery is: re-stat and repair → retry once → fall back to the user's
-   * installed CLI with a visible notice → give up with an accurate diagnosis.
+   * only ever right on Linux — elsewhere the cause is a missing execute bit, a
+   * quarantined download, a build for another processor or a file that is gone.
+   * There is no other runtime to move to (SynaBun carries none), so the turn
+   * ends with what is wrong with that installation and how to fix it.
    */
   _recoverNativeRuntime(err) {
-    const prompt = this.lastPrompt;
-    // The newer installed CLI this session was aligned to would not launch. Latch
-    // it off for the whole process and go back to the bundled runtime, which has
-    // its own repair path below if it fails too.
-    if (this._alignedBin) {
-      const failed = this._alignedBin;
-      this._alignedBin = null;
-      markAlignedClaudeExecutableFailed(failed);
-      log(`aligned CLI failed to launch (${failed}) — using the bundled runtime`);
-      this.sendEvent({
-        type: 'system',
-        subtype: 'runtime_notice',
-        level: 'warn',
-        message: `Your installed Claude CLI (${failed}) failed to launch; using the bundled runtime instead.`,
-      });
-      this._recreateQuery(prompt);
-      return;
-    }
-    // The cached verdict predates the failure; re-stat so a repair performed by
-    // another session (or the boot sweep) is visible.
-    clearNativeBinaryCache();
-    const runtime = claudeRuntime();
-
-    let fallbackBin = this._fallbackBin;
-    if (!fallbackBin) {
-      // getClaudeBin()'s last resort is the bare string 'claude'. The SDK spawns
-      // with shell:false, so a bare name is a guaranteed ENOENT — the override
-      // validator rejects it, leaving fallbackBin null and giving the user a
-      // real diagnosis instead of a second, more confusing failure.
-      const candidate = resolveClaudeExecutableOverride(deps.getClaudeBin?.());
-      if (candidate.ok && candidate.path) fallbackBin = candidate.path;
-    }
-
-    const plan = planRuntimeRecovery({
-      err,
-      runtime,
-      fallbackBin,
-      alreadyTried: this._nativeRepairTried,
-    });
-    log(`native runtime recovery: action=${plan.action} state=${runtime.state} kind=${plan.kind}`);
-
-    if (plan.action === 'retry') {
-      this._nativeRepairTried = true;
-      this.sendEvent({ type: 'system', subtype: 'runtime_notice', level: 'warn', message: plan.message });
-      this._recreateQuery(prompt);
-      return;
-    }
-
-    if (plan.action === 'fallback') {
-      this._fallbackBin = fallbackBin;
-      this.sendEvent({ type: 'system', subtype: 'runtime_notice', level: 'warn', message: plan.message });
-      // Report-only: the fallback CLI may be a different version than the SDK
-      // was built against, and alias ids like "opus[1m]" resolve per-binary — so
-      // a picked model can silently launch as another version.
-      this._announceSkew(fallbackBin);
-      this._recreateQuery(prompt);
-      return;
-    }
-
-    this._finishTurnWithError(plan.message);
-  }
-
-  _announceSkew(bin) {
-    Promise.resolve()
-      .then(() => checkClaudeCliSkew(bin, { log: () => {} }))
-      .then((skew) => {
-        if (!skew?.skewed || this.destroyed) return;
-        this.sendEvent({
-          type: 'system',
-          subtype: 'runtime_notice',
-          level: 'warn',
-          message: `Version skew: your installed Claude CLI is ${skew.discovered}, but the bundled `
-            + `runtime is ${skew.bundled}. Model aliases and effort levels resolve per-binary, so `
-            + 'behaviour may differ until the bundled binary is repaired.',
-        });
-      })
-      .catch(() => {});
+    const dx = diagnoseLaunchFailure({ err, executable: this._claudeExecutable });
+    log(`Claude Code failed to launch: kind=${dx.kind} executable=${this._claudeExecutable || 'unset'}`);
+    this._finishTurnWithError(dx.message);
   }
 
   _pushUserText(text, images, { human = false } = {}) {
@@ -2222,7 +2129,7 @@ export class ClaudeSession {
   // AskUserQuestion answers arrive as updatedInput {questions, answers} from the
   // existing frontend card. The CLI's AskUserQuestion tool reads ONLY the
   // top-level `answers` map, looked up by each question's exact `question` text
-  // (verified against the bundled CLI: missing/empty map → "The user did not
+  // (verified against the CLI itself: missing/empty map → "The user did not
   // answer the questions."). So: keep the original questions, pass the answers
   // map through, and re-key any answer the panel stored under a fallback key
   // (text/header) back onto the question text.