synabun 2.0.0-beta → 2.0.5

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

@@ -25,17 +25,12 @@ 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';
+import { applyTemporaryOptions, plansDirsOf, snapshotPlanFiles, planFileOfToolCall, removeTemporaryPlanFiles } from './claude-temporary.js';
 import { rootBypassBlock } from './claude-bypass-policy.js';
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
@@ -112,6 +107,7 @@ export const PANEL_CAPABILITIES = Object.freeze([
   'message_flags',    // session.hookEvents / promptSuggestions / subagentText / agentSummaries → the matching SDK options
   'task_control',     // inbound `stop_task` / `background_tasks` → `task_control_result`; system/session_crons events
   'origin_human',     // a query marked `typed: true` is sent with origin {kind:'human'}
+  'greeting',         // query `greetingId`: the model is told once what SynaBun greeted the user with (lib/greeting/)
   'session_requests', // inbound `session_request {id, what, args}` → `session_response`: context_usage, usage, mcp_status, mcp_reconnect, mcp_toggle, rewind_preview
   'rewind_stats',     // `rewind_result` carries filesChanged / insertions / deletions
   'session_title',    // query `title` names a new session where the CLI reads it
@@ -231,7 +227,7 @@ function log(...args) { console.log('[claude-sdk]', ...args); }
 
 // Panel sessions, a temporary chat (lib/claude-temporary.js): the plan files
 // Claude Code wrote for one that still have to be removed. path → { plansDirs,
-// since, ended, last }. One is removed once the pump of the process that wrote
+// since, before, ended, last }. One is removed once the pump of the process that wrote
 // it has settled (`ended`), and stays owed after that removal, whether it
 // removed the file or found none: the pump settles when the SDK's own cleanup
 // stops waiting for the process, which can be before the process is gone, and
@@ -348,15 +344,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 +489,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;
@@ -588,8 +603,9 @@ export class ClaudeSession {
       // `typesafe:'off'` on a query (the live skin test) keeps this CLI's hooks
       // from paying for judgments: they read the kill switch from their env.
       // (Panel sessions: the CLI reports running / idle / requires_action only when
-      // asked to; `idle` is its own word that a turn is over. See _noteSessionState.)
-      env: { ...cleanEnv(), ...(this.typesafeOff ? { SYNABUN_TYPESAFE: 'off' } : {}), ...(sessionOpts.env || {}), ...(accountEnv || {}), ...(this.panel ? { CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: '1' } : {}) },
+      // asked to; `idle` is its own word that a turn is over. See _noteSessionState.
+      // SYNABUN_PANEL_SESSION tells the user-level SynaBun hooks that the panel greets here, not they.)
+      env: { ...cleanEnv(), ...(this.typesafeOff ? { SYNABUN_TYPESAFE: 'off' } : {}), ...(sessionOpts.env || {}), ...(accountEnv || {}), ...(this.panel ? { CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: '1', SYNABUN_PANEL_SESSION: '1' } : {}) },
       abortController: this.abortController,
       stderr: (text) => {
         const t = String(text || '').trim();
@@ -629,6 +645,16 @@ export class ClaudeSession {
       // Resuming a session whose prompt cache has expired pays to write it
       // again: the CLI says how much at SessionStart.
       options.hooks = mergeHookMatchers(options.hooks, {
+        // The greeting SynaBun showed when this conversation opened (lib/greeting/): said to the
+        // model once, with the first prompt, as background. The model is never asked to greet.
+        UserPromptSubmit: [{
+          hooks: [async () => {
+            const note = gen === this._queryGen ? this._greetingNote : '';
+            if (!note) return {};
+            this._greetingNote = '';
+            return { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: note } };
+          }],
+        }],
         SessionStart: [{
           hooks: [async (input) => {
             if (gen === this._queryGen && input?.prompt_cache_likely_expired === true && Number(input?.estimated_cache_write_usd) > 0) {
@@ -730,54 +756,26 @@ export class ClaudeSession {
       // (Which of the session's MCP connections is SynaBun's is asked of the live process when a tool of one is called.)
       applyTemporaryOptions(options, { mcpUrl: deps.mcpUrl || '', mcpStatus: () => this.q?.mcpServerStatus?.() });
       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();
+      if (!this._tempSince) {
+        this._tempPlansBefore = snapshotPlanFiles(this._tempPlansDirs);
+        this._tempSince = Date.now();
       }
     }
+    // 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) {
       // Start the process now; hand it the input queue when the first prompt comes.
@@ -1096,7 +1094,7 @@ export class ClaudeSession {
   // stay owed and are swept once more when it can no longer be alive.
   _removeTemporaryPlans() {
     if (!this._tempPlans?.size) return;
-    const owed = { plansDirs: this._tempPlansDirs, since: this._tempSince, ended: false, last: false };
+    const owed = { plansDirs: this._tempPlansDirs, since: this._tempSince, before: this._tempPlansBefore, ended: false, last: false };
     for (const path of this._tempPlans) _temporaryPlansOwed.set(path, owed);
     this._tempPlans.clear();
     Promise.resolve(this.pumpPromise).catch(() => {}).then(() => {
@@ -1115,6 +1113,7 @@ export class ClaudeSession {
     this._tempLive = false;
     this._tempOver = false;
     this._tempSince = 0;
+    this._tempPlansBefore = null;
   }
 
   // Whether this message makes, keeps or may not make the conversation a
@@ -1256,94 +1255,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 +2145,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.
@@ -2904,6 +2827,17 @@ export class ClaudeSession {
       } catch {}
     }
 
+    // The panel echoes the id of the greeting it showed when this conversation opened: the model is
+    // told once, with this prompt (the UserPromptSubmit hook in _startQuery). A slash command takes none.
+    // (A prompt the person typed in the panel is also them being here, whether or not the user-level hooks are installed.)
+    if (this.panel && !warmOnly && msg.typed === true && typeof prompt === 'string' && prompt.trim() && typeof deps.greetingActivity === 'function') {
+      try { deps.greetingActivity({ cwd: cwd || this.cwd || null, words: prompt, temporary: this.temporary === true }); } catch { /* the prompt goes on */ }
+    }
+    if (this.panel && !warmOnly && typeof msg.greetingId === 'string' && typeof deps.greetingNote === 'function') {
+      try { this._greetingNote = String(deps.greetingNote(msg.greetingId, { skip: typeof prompt === 'string' && prompt.trimStart().startsWith('/') }) || ''); }
+      catch { this._greetingNote = ''; }
+    }
+
     // SynaBun skill injection runs FIRST; unrecognized /commands pass through to the CLI
     if (prompt && prompt.startsWith('/')) {
       try {

package/neural-interface/lib/claude-executable.js

@@ -0,0 +1,241 @@
+// ── Which Claude Code runs: the user's own installation ──
+//
+// Claude Code is installed by the user, separately from SynaBun (the native
+// installer, Homebrew, npm). Nothing in SynaBun carries a copy: the Claude
+// Agent SDK is installed without the executable it would otherwise bring (see
+// lib/external-tools.js at the package root), so every SDK call has to be told
+// which executable to start. This module is where that answer comes from, for
+// the side panel, the Assistant's Claude brain, native loops, session titles
+// and the model probe alike:
+//
+//   resolveClaudeLauncher        what a terminal or a shell would start: the
+//                                user's configured command, else the first
+//                                `claude` on PATH that is not inside SynaBun
+//   resolveClaudeSdkExecutable   what the SDK can start. It spawns with
+//                                shell:false, so an npm command file on Windows
+//                                is followed to the executable behind it
+//
+// A missing installation is an ordinary state, not a failure: both answer with
+// `path: null` and the caller says CLAUDE_NOT_INSTALLED.
+//
+// Every dependency is injectable (platform, PATH, the file system), so Windows
+// resolution is tested from any host. Nothing here throws.
+
+import { accessSync, constants, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { getAugmentedPath } from './augmented-path.js';
+import { resolveClaudeExecutableOverride } from './native-binary-runtime.js';
+
+/**
+ * What a session says when no Claude Code is installed. The words "Claude CLI
+ * not found" are what the side panel shows its install help on.
+ */
+export const CLAUDE_NOT_INSTALLED = 'Claude CLI not found. Claude Code is installed separately from SynaBun: install it, then send your message again.';
+
+/** A real executable first, then the command files a shell can run. */
+const WINDOWS_LAUNCHER_ORDER = ['.exe', '.cmd', '.bat', '.ps1'];
+
+const pathFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+
+function unique(values, pathImpl, insensitive) {
+  const seen = new Set();
+  const out = [];
+  for (const value of values) {
+    const text = String(value || '').trim();
+    if (!text) continue;
+    const normal = pathImpl.normalize(text);
+    const key = insensitive ? normal.toLowerCase() : normal;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(normal);
+  }
+  return out;
+}
+
+/**
+ * The launcher Windows should start, from a list in PATH order (as `where`
+ * prints it, or findOnPath below). PATH order decides between folders; inside
+ * one folder a real executable beats a command file, and npm's extensionless
+ * shell script (which Windows cannot start) is only ever the last resort.
+ */
+export function selectWindowsLauncher(launchers = [], accept = () => true) {
+  const accepted = unique(launchers, path.win32, true).filter(accept);
+  const folders = new Map();
+  for (const launcher of accepted) {
+    const folder = path.win32.dirname(launcher).toLowerCase();
+    if (!folders.has(folder)) folders.set(folder, []);
+    folders.get(folder).push(launcher);
+  }
+  for (const group of folders.values()) {
+    for (const extension of WINDOWS_LAUNCHER_ORDER) {
+      const hit = group.find(launcher => launcher.toLowerCase().endsWith(extension));
+      if (hit) return hit;
+    }
+  }
+  return accepted[0] || null;
+}
+
+function defaultIsLaunchable(file, platform) {
+  try {
+    if (!statSync(file).isFile()) return false;
+    if (platform !== 'win32') accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** PATH without any `node_modules/.bin` folder: a dependency's command is never the user's tool. */
+export function withoutPackageBins(pathValue, platform = process.platform) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  return String(pathValue || '').split(delimiter)
+    .filter(entry => entry && !/[\\/]node_modules[\\/]\.bin[\\/]?$/i.test(entry))
+    .join(delimiter);
+}
+
+/**
+ * Every file a command name resolves to, in PATH order, read from the file
+ * system (no `which`, no shell: a folder with a space in its name is just a
+ * folder). On Windows each folder is tried with the launcher extensions, then
+ * bare.
+ */
+export function findOnPath(command, {
+  platform = process.platform,
+  pathValue = getAugmentedPath(),
+  isLaunchable = defaultIsLaunchable,
+} = {}) {
+  const name = String(command || '').trim();
+  if (!name) return [];
+  const pathImpl = pathFor(platform);
+  const windows = platform === 'win32';
+  const names = windows && !pathImpl.extname(name) ? [...WINDOWS_LAUNCHER_ORDER.map(extension => name + extension), name] : [name];
+  const found = [];
+  for (const folder of String(pathValue || '').split(windows ? ';' : ':')) {
+    if (!folder) continue;
+    for (const candidate of names) {
+      const file = pathImpl.join(folder, candidate);
+      if (isLaunchable(file, platform)) found.push(file);
+    }
+  }
+  return unique(found, pathImpl, windows);
+}
+
+/**
+ * The Claude Code a terminal would start.
+ *
+ *   configured   cli-config.json → "claude-code": { "command": "…" } (Settings > Terminal):
+ *                a path is taken as it is, a name is looked up on PATH
+ *   path         the first `claude` on PATH
+ *
+ * Never a file inside SynaBun (`isInsideSynabun`) and never one from a
+ * `node_modules/.bin` folder on PATH: a copy that came with a dependency must
+ * not stand in for the user's own.
+ *
+ * @returns {{path: string|null, source: 'configured'|'path'|'missing', rejected: string[]}}
+ */
+export function resolveClaudeLauncher({
+  configured = '',
+  platform = process.platform,
+  pathValue = getAugmentedPath(),
+  isInsideSynabun = () => false,
+  exists = existsSync,
+  isLaunchable = defaultIsLaunchable,
+} = {}) {
+  const pathImpl = pathFor(platform);
+  const windows = platform === 'win32';
+  const rejected = [];
+  const outside = (file) => {
+    if (!isInsideSynabun(file)) return true;
+    rejected.push(file);
+    return false;
+  };
+  const lookup = (command) => {
+    const hits = findOnPath(command, { platform, pathValue: withoutPackageBins(pathValue, platform), isLaunchable }).filter(outside);
+    return (windows ? selectWindowsLauncher(hits) : hits[0]) || null;
+  };
+
+  const wanted = String(configured || '').trim();
+  if (wanted && wanted !== 'claude') {
+    const isPath = wanted.includes('/') || (windows && wanted.includes('\\'));
+    if (isPath) {
+      if (exists(wanted) && outside(wanted)) return { path: pathImpl.normalize(wanted), source: 'configured', rejected };
+    } else {
+      const hit = lookup(wanted);
+      if (hit) return { path: hit, source: 'configured', rejected };
+    }
+  }
+
+  const hit = lookup('claude');
+  return hit ? { path: hit, source: 'path', rejected } : { path: null, source: 'missing', rejected };
+}
+
+/**
+ * Where the executable behind an npm command file is, most likely first. npm
+ * puts `claude.cmd` next to `node_modules\@anthropic-ai\claude-code`, whose
+ * `bin\claude.exe` is the program (older releases: `cli.js`, run by Node). A
+ * `.bin` folder has the package one level up instead.
+ */
+export function windowsClaudeTargets(launcher) {
+  const pathImpl = path.win32;
+  const folder = pathImpl.dirname(String(launcher || ''));
+  const roots = [pathImpl.join(folder, 'node_modules')];
+  if (pathImpl.basename(folder).toLowerCase() === '.bin') roots.push(pathImpl.dirname(folder));
+  return roots.flatMap((root) => {
+    const packageDir = pathImpl.join(root, '@anthropic-ai', 'claude-code');
+    return [pathImpl.join(packageDir, 'bin', 'claude.exe'), pathImpl.join(packageDir, 'cli.js')];
+  });
+}
+
+/**
+ * The executable an Agent SDK call is given as `pathToClaudeCodeExecutable`.
+ *
+ *   override    cli-config.json → "claude-skin": { "sdkExecutable": "…" }, when it is usable
+ *   installed   the user's Claude Code (`launcher`, from resolveClaudeLauncher)
+ *
+ * The SDK starts this path itself, without a shell, so it has to be a program
+ * or a script: on Windows a `.cmd`, `.bat` or `.ps1` launcher is followed to
+ * what it runs. `path: null` means there is nothing to start; `reason` says
+ * why in a sentence a person can act on, `ignored` why an override was passed
+ * over.
+ *
+ * @returns {{path: string|null, source: 'override'|'installed'|'missing', kind: string|null, reason: string|null, ignored: string|null, launcher: string|null}}
+ */
+export function resolveClaudeSdkExecutable({
+  launcher = null,
+  sdkExecutable = null,
+  platform = process.platform,
+  exists = existsSync,
+  isInsideSynabun = () => false,
+  validate = resolveClaudeExecutableOverride,
+} = {}) {
+  const answer = (fields) => ({ path: null, source: 'missing', kind: null, reason: null, ignored: null, launcher: launcher || null, ...fields });
+  let ignored = null;
+
+  const explicit = typeof sdkExecutable === 'string' ? sdkExecutable.trim() : '';
+  if (explicit) {
+    const verdict = validate(explicit, { platform });
+    if (verdict.ok && verdict.path) return answer({ path: verdict.path, source: 'override', kind: verdict.kind });
+    ignored = verdict.reason || `Not usable: ${explicit}`;
+  }
+
+  const installed = typeof launcher === 'string' ? launcher.trim() : '';
+  // A bare name is what "nothing was found" looks like to older callers.
+  if (!installed || !(installed.includes('/') || installed.includes('\\'))) return answer({ reason: CLAUDE_NOT_INSTALLED, ignored });
+
+  const candidates = platform === 'win32' && !/\.exe$/i.test(installed) && !/\.[cm]?js$/i.test(installed)
+    ? windowsClaudeTargets(installed).filter(file => exists(file))
+    : [installed];
+  let refusal = null;
+  for (const candidate of candidates) {
+    if (isInsideSynabun(candidate)) { refusal = `${candidate} is inside SynaBun, not an installation of Claude Code`; continue; }
+    const verdict = validate(candidate, { platform });
+    if (verdict.ok && verdict.path) return answer({ path: verdict.path, source: 'installed', kind: verdict.kind, ignored });
+    refusal = verdict.reason || `Not usable: ${candidate}`;
+  }
+  return answer({
+    reason: refusal
+      ? `Claude Code was found at ${installed}, but it cannot be started from there: ${refusal}.`
+      : `Claude Code was found at ${installed}, but not the program that command runs. Reinstall Claude Code, or name its executable in cli-config.json ("claude-skin": { "sdkExecutable": "…" }).`,
+    ignored,
+  });
+}