claude-code-session-manager 0.104.2 → 0.106.0

package/src/main/lib/loginShellPath.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+const { execFile } = require('node:child_process');
+const path = require('node:path');
+
+const START = '__SM_PATH_START__';
+const END = '__SM_PATH_END__';
+const DEFAULT_TIMEOUT_MS = 3000;
+
+/**
+ * A packaged macOS app launched from Finder/Dock inherits only
+ * /usr/bin:/bin:/usr/sbin:/sbin, so nvm/asdf/volta/fnm/Homebrew installs of
+ * node, git and claude are invisible. Ask the user's login shell for its PATH.
+ * Complements cleanEnv.pathWithUserBins (fixed dirs, appended).
+ */
+
+/** @param {{shell?: string, platform?: string, timeoutMs?: number, env?: NodeJS.ProcessEnv}} [opts] */
+function resolveShell(opts) {
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  return opts.shell || env.SHELL || (platform === 'darwin' ? '/bin/zsh' : '/bin/bash');
+}
+
+/**
+ * Login-shell PATH, or null on timeout / non-zero exit / missing markers /
+ * win32 (fail-open: callers keep their current PATH).
+ * @param {{shell?: string, platform?: string, timeoutMs?: number, env?: NodeJS.ProcessEnv}} [opts]
+ * @returns {Promise<string|null>}
+ */
+function readLoginShellPath(opts = {}) {
+  const platform = opts.platform || process.platform;
+  if (platform === 'win32') return Promise.resolve(null);
+  const shell = resolveShell(opts);
+  const cmd = `printf '%s' '${START}'; printf '%s' "$PATH"; printf '%s' '${END}'`;
+  return new Promise((resolve) => {
+    try {
+      execFile(
+        shell,
+        ['-ilc', cmd],
+        { timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, env: opts.env || process.env, encoding: 'utf8' },
+        (err, stdout) => {
+          if (err) return resolve(null);
+          const out = String(stdout || '');
+          const s = out.indexOf(START);
+          if (s < 0) return resolve(null);
+          const from = s + START.length;
+          const e = out.indexOf(END, from);
+          if (e < 0) return resolve(null);
+          resolve(out.slice(from, e));
+        },
+      );
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * Prepend login-shell PATH entries not already present to env.PATH
+ * (order preserved, deduped, empties dropped).
+ * @param {{shell?: string, platform?: string, timeoutMs?: number, env?: NodeJS.ProcessEnv}} [opts]
+ * @returns {Promise<{applied: boolean, added: number}>}
+ */
+async function applyLoginShellPath(opts = {}) {
+  const platform = opts.platform || process.platform;
+  if (platform === 'win32') return { applied: false, added: 0 };
+  const loginPath = await readLoginShellPath(opts);
+  if (loginPath === null) return { applied: false, added: 0 };
+  const env = opts.env || process.env;
+  const current = (env.PATH || '').split(path.delimiter).filter(Boolean);
+  const seen = new Set(current);
+  const fresh = [];
+  for (const entry of loginPath.split(path.delimiter)) {
+    if (!entry || seen.has(entry)) continue;
+    seen.add(entry);
+    fresh.push(entry);
+  }
+  if (fresh.length) env.PATH = [...fresh, ...current].join(path.delimiter);
+  return { applied: true, added: fresh.length };
+}
+
+module.exports = { readLoginShellPath, applyLoginShellPath };

package/src/main/lib/machineProfile.cjs

@@ -16,6 +16,7 @@ const os = require('node:os');
 const crypto = require('node:crypto');
 const path = require('node:path');
 const claudeBin = require('./claudeBin.cjs');
+const { isPackagedApp } = require('./appRuntime.cjs');
 
 function resolveElectronApp() {
   try {
@@ -39,12 +40,13 @@ function resolvePackageVersion() {
 }
 
 /**
- * 'npx' when the app path lives inside an npm/npx cache dir, 'dev' when
+ * 'installer' for a packaged app build, 'npx' when the app path lives inside an npm/npx cache dir, 'dev' when
  * SM_DEV is set, else 'unknown'. Injectable so tests never depend on real
  * process state.
  */
-function resolveInstallChannel({ appPath = null, devFlag = !!process.env.SM_DEV } = {}) {
+function resolveInstallChannel({ appPath = null, devFlag = !!process.env.SM_DEV, packaged } = {}) {
   if (devFlag) return 'dev';
+  if (isPackagedApp(typeof packaged === 'boolean' ? { packaged } : undefined)) return 'installer';
   if (typeof appPath === 'string' && /[\\/](\.npm|_npx|npm-cache|npx-cache)[\\/]/i.test(appPath)) {
     return 'npx';
   }

package/src/main/lib/mcpStdioServer.cjs

@@ -0,0 +1,127 @@
+/**
+ * mcpStdioServer.cjs — zero-dependency MCP server over newline-delimited
+ * JSON-RPC 2.0 on stdio. Implements only what the scheduler MCP server uses:
+ * initialize, ping, tools/list, tools/call. Stdout carries protocol messages
+ * only; diagnostics go to stderr.
+ */
+'use strict';
+
+// Copied verbatim from @modelcontextprotocol/sdk dist/cjs/types.js
+// (LATEST_PROTOCOL_VERSION first).
+const SUPPORTED_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07'];
+
+const PARSE_ERROR = -32700;
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+
+/**
+ * @param {{
+ *   name: string,
+ *   version: string,
+ *   listTools: () => any[] | Promise<any[]>,
+ *   callTool: (params: any) => Promise<any>,
+ *   input?: NodeJS.ReadableStream,
+ *   output?: NodeJS.WritableStream,
+ * }} opts
+ */
+function createStdioServer({ name, version, listTools, callTool, input = process.stdin, output = process.stdout }) {
+  let buffer = '';
+  let started = false;
+  let closed = false;
+
+  function send(msg) {
+    if (closed) return;
+    try {
+      output.write(JSON.stringify(msg) + '\n');
+    } catch (err) {
+      process.stderr.write(`[mcpStdioServer] write failed: ${err && err.message}\n`);
+    }
+  }
+
+  function sendError(id, code, message) {
+    send({ jsonrpc: '2.0', id, error: { code, message } });
+  }
+
+  async function dispatch(msg) {
+    const hasId = msg && typeof msg === 'object' && msg.id !== undefined && msg.id !== null;
+    if (!hasId) return; // notification (or unusable message): never reply
+    const { id, method, params } = msg;
+    try {
+      let result;
+      switch (method) {
+        case 'initialize': {
+          const requested = params && params.protocolVersion;
+          result = {
+            protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS[0],
+            capabilities: { tools: {} },
+            serverInfo: { name, version },
+          };
+          break;
+        }
+        case 'ping':
+          result = {};
+          break;
+        case 'tools/list':
+          result = { tools: await listTools() };
+          break;
+        case 'tools/call':
+          result = await callTool(params);
+          break;
+        default:
+          sendError(id, METHOD_NOT_FOUND, `Method not found: ${method}`);
+          return;
+      }
+      send({ jsonrpc: '2.0', id, result });
+    } catch (err) {
+      sendError(id, INTERNAL_ERROR, err && err.message ? err.message : String(err));
+    }
+  }
+
+  function handleLine(line) {
+    if (line.endsWith('\r')) line = line.slice(0, -1);
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      sendError(null, PARSE_ERROR, 'Parse error');
+      return;
+    }
+    dispatch(msg).catch((err) => {
+      process.stderr.write(`[mcpStdioServer] dispatch failed: ${err && err.message}\n`);
+    });
+  }
+
+  function onData(chunk) {
+    buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    let idx;
+    while ((idx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+      handleLine(line);
+    }
+  }
+
+  function onEnd() {
+    close();
+  }
+
+  function start() {
+    if (started || closed) return;
+    started = true;
+    input.on('data', onData);
+    input.on('end', onEnd);
+  }
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    input.removeListener('data', onData);
+    input.removeListener('end', onEnd);
+    buffer = '';
+  }
+
+  return { start, close };
+}
+
+module.exports = { createStdioServer, SUPPORTED_PROTOCOL_VERSIONS };

package/src/main/lib/mcpToolCatalog.cjs

@@ -23,7 +23,7 @@ const { z } = require('zod');
 
 const CatalogEntrySchema = z.object({
   name: z.string().min(1),
-  group: z.enum(['scheduler', 'chat', 'feedback', 'help', 'project-home', 'macros']),
+  group: z.enum(['scheduler', 'chat', 'feedback', 'help', 'project-home', 'macros', 'customer-feedback']),
   purpose: z.string().min(1),
   whenToUse: z.string().min(1),
   whenNotToUse: z.string().min(1),
@@ -293,6 +293,31 @@ const MCP_TOOL_CATALOG = [
     notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted. "
       + 'The document is CSP-stamped after it is written, so the viewer sandbox is the real network fence — these checks are defence in depth.',
   },
+  {
+    name: 'customer_feedback_list',
+    group: 'customer-feedback',
+    purpose: "List the customers' feedback in the owner's local inbox (bug / feature / discussion items submitted "
+      + 'from the {F} feedback panel), optionally pulling new items from the feedback service first.',
+    whenToUse: 'Use to inspect what customers have submitted and each item\'s status. `pull` defaults to true '
+      + '(fetch new items first); pass `includeHidden: true` to include moderated-away items.',
+    whenNotToUse: 'WHEN NOT TO USE IT: this only works on the owner\'s machine (it needs the owner token) and is read-only. '
+      + 'Turning an item into an Epic is done by the human via Open as Epic in the {F} feedback panel — there is no tool '
+      + 'for it. A finding that belongs to another local project uses feedback_open_session instead.',
+    exampleArgs: { pull: true, includeHidden: false },
+    notes: 'Returns { ok, items, pulled? }. Not-configured machines get { ok:false, error } as an error result.',
+  },
+  {
+    name: 'customer_feedback_set_status',
+    group: 'customer-feedback',
+    purpose: 'Set the status of one customer feedback item (open | in_progress | resolved | wontfix) with an optional '
+      + 'note the customer sees, via the session-manager app\'s admin API.',
+    whenToUse: 'Use after inspecting an item with customer_feedback_list, to mark it in progress, resolved, or wontfix.',
+    whenNotToUse: 'WHEN NOT TO USE IT: this changes status only. Turning an item into an Epic is done by the human via '
+      + 'Open as Epic in the {F} feedback panel — there is no tool for it. Cross-project findings use '
+      + 'feedback_open_session. Never mark an item resolved unless the work has actually landed.',
+    exampleArgs: { id: 'fb_123', status: 'resolved', note: 'Fixed in 0.97.0' },
+    notes: 'The note is shown to the customer; keep it short (the inbox enforces a maximum length).',
+  },
   {
     name: 'macro_list',
     group: 'macros',

package/src/main/lib/openExternalApp.cjs

@@ -49,11 +49,11 @@ function findCommand(name) {
  *
  * @returns {Promise<{ ok: true, opener: string } | { ok: false, error: string }>}
  */
-function spawnDetached(cmd, args, opener = cmd) {
+function spawnDetached(cmd, args, opener = cmd, spawnFn = spawn, extraOpts = {}) {
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(cmd, args, { detached: true, stdio: 'ignore', env: cleanChildEnv() });
+      child = spawnFn(cmd, args, { detached: true, stdio: 'ignore', env: cleanChildEnv(), ...extraOpts });
     } catch (e) {
       resolve({ ok: false, error: `failed to launch ${opener}: ${e?.message ?? e}` });
       return;
@@ -116,12 +116,16 @@ async function openFileInEditor({ path: abs, line, col, editor }) {
 }
 
 /**
- * Open a directory in the OS file manager (Finder on macOS, Nautilus etc on Linux).
+ * Open a directory in the OS file manager (Finder on macOS, Nautilus etc on Linux,
+ * explorer.exe on Windows).
  *
  * @param {{ cwd: string }} opts
+ * @param {{ platform?: string, spawn?: Function }} [deps]
  * @returns {Promise<{ ok: true, opener: string } | { ok: false, error: string }>}
  */
-async function openInFinder({ cwd }) {
+async function openInFinder({ cwd }, deps = {}) {
+  const { platform = process.platform, spawn: spawnFn = spawn } = deps;
+  if (platform === 'win32') return spawnDetached('explorer.exe', [cwd], 'explorer', spawnFn);
   const errStr = await shell.openPath(cwd);
   if (errStr) return { ok: false, error: errStr };
   return { ok: true, opener: 'shell' };
@@ -132,28 +136,75 @@ async function openInFinder({ cwd }) {
  *
  * Linux: tries gnome-terminal → konsole → xfce4-terminal → xterm.
  * macOS: delegates to Terminal.app via `open -a`.
+ * Windows: `wt.exe -d <cwd>` when on PATH, else powershell.exe -NoExit in a new
+ * console via `cmd.exe /d /c start`.
  *
  * Arg shapes per terminal are preserved verbatim from index.cjs (AC impl note):
  *   gnome-terminal  → ['--working-directory=<cwd>']
  *   others          → ['-e', "bash -c \"cd '<cwd>' && exec bash\""]
  *
  * @param {{ cwd: string }} opts
+ * @param {{ platform?: string, spawn?: Function, findCommand?: (n: string) => string | null }} [deps]
  * @returns {Promise<{ ok: true, opener: string } | { ok: false, error: string }>}
  */
-async function openInTerminal({ cwd }) {
-  if (process.platform === 'linux') {
+async function openInTerminal({ cwd }, deps = {}) {
+  const { platform = process.platform, spawn: spawnFn = spawn, findCommand: find = findCommand } = deps;
+  if (platform === 'linux') {
     const terms = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'xterm'];
     for (const t of terms) {
-      if (!findCommand(t)) continue;
+      if (!find(t)) continue;
       const args = t === 'gnome-terminal'
         ? ['--working-directory=' + cwd]
         : ['-e', `bash -c "cd '${cwd.replace(/'/g, "'\\''")}' && exec bash"`];
-      return spawnDetached(t, args);
+      return spawnDetached(t, args, t, spawnFn);
     }
-  } else if (process.platform === 'darwin') {
-    return spawnDetached('open', ['-a', 'Terminal', cwd], 'Terminal.app');
+  } else if (platform === 'darwin') {
+    return spawnDetached('open', ['-a', 'Terminal', cwd], 'Terminal.app', spawnFn);
+  } else if (platform === 'win32') {
+    if (find('wt.exe')) return spawnDetached('wt.exe', ['-d', cwd], 'wt', spawnFn);
+    const setLoc = `Set-Location -LiteralPath '${cwd.replace(/'/g, "''")}'`;
+    return spawnDetached('cmd.exe',
+      ['/d', '/c', 'start', '', 'powershell.exe', '-NoExit', '-Command', setLoc],
+      'powershell', spawnFn, { windowsHide: true });
   }
   return { ok: false, error: 'no terminal found' };
 }
 
-module.exports = { spawnDetached, findCommand, openInEditor, openFileInEditor, openInFinder, openInTerminal };
+/** Escape a string for use inside an AppleScript double-quoted literal. */
+const appleScriptQuote = (s) => `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+/**
+ * Run a command in a visible OS terminal so the user sees and controls it
+ * (password prompts, installer dialogs). `command` MUST come from main-side
+ * code, never from the renderer. argv arrays only — never shell:true.
+ *
+ * @param {{ command: string, shell?: 'sh' | 'powershell' }} opts
+ * @param {{ platform?: string, spawn?: Function, find?: (n: string) => string | null }} [deps]
+ * @returns {Promise<{ ok: true, opener: string } | { ok: false, error: string }>}
+ */
+async function runInTerminal({ command, shell: shellKind }, deps = {}) {
+  const { platform = process.platform, spawn: spawnFn = spawn, find = findCommand } = deps;
+  if (typeof command !== 'string' || !command.trim()) return { ok: false, error: 'empty command' };
+  if (platform === 'darwin') {
+    const script = `tell application "Terminal"\nactivate\ndo script ${appleScriptQuote(command)}\nend tell`;
+    return spawnDetached('osascript', ['-e', script], 'Terminal.app', spawnFn);
+  }
+  if (platform === 'win32') {
+    return spawnDetached('cmd.exe',
+      ['/d', '/c', 'start', '', 'powershell.exe', '-NoExit', '-Command', command],
+      'powershell', spawnFn);
+  }
+  if (platform === 'linux') {
+    const inner = `${command}; exec bash`;
+    for (const t of ['gnome-terminal', 'konsole', 'xfce4-terminal', 'xterm']) {
+      if (!find(t)) continue;
+      const args = t === 'gnome-terminal'
+        ? ['--', 'bash', '-lc', inner]
+        : ['-e', 'bash', '-lc', inner];
+      return spawnDetached(t, args, t, spawnFn);
+    }
+  }
+  return { ok: false, error: 'no terminal found' };
+}
+
+module.exports = { spawnDetached, findCommand, openInEditor, openFileInEditor, openInFinder, openInTerminal, runInTerminal };

package/src/main/lib/otlpTraceExporter.cjs

@@ -0,0 +1,147 @@
+/**
+ * otlpTraceExporter — zero-dependency batching exporter that POSTs 0-duration
+ * spans to an OTLP/HTTP endpoint as JSON (ExportTraceServiceRequest).
+ *
+ * Replaces the @opentelemetry/* SDK for the one thing otel.cjs does: emit
+ * "event" spans. recordSpan() only queues (no I/O, never throws); a timer
+ * unref()'d so it can't hold the process open drains the queue in batches.
+ * A failed POST drops that batch and is surfaced via stats() — the app must
+ * keep working without telemetry. Field names mirror otlp-transformer's JSON.
+ */
+
+const crypto = require('node:crypto');
+
+function toAnyValue(v) {
+  switch (typeof v) {
+    case 'string': return { stringValue: v };
+    case 'boolean': return { boolValue: v };
+    case 'bigint': return { intValue: v.toString() };
+    case 'number':
+      if (!Number.isFinite(v)) return { stringValue: String(v) };
+      return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+    default:
+      try { return { stringValue: JSON.stringify(v) ?? String(v) }; } catch { return { stringValue: String(v) }; }
+  }
+}
+
+function toAttributes(obj) {
+  const out = [];
+  if (!obj || typeof obj !== 'object') return out;
+  for (const [key, v] of Object.entries(obj)) {
+    if (v === undefined || v === null) continue;
+    out.push({ key, value: toAnyValue(v) });
+  }
+  return out;
+}
+
+function createOtlpTraceExporter({
+  url,
+  headers,
+  serviceName,
+  scopeName,
+  maxQueue = 2048,
+  maxBatch = 512,
+  flushIntervalMs = 5000,
+  timeoutMs = 10000,
+} = {}) {
+  let queue = [];
+  let timer = null;
+  let closed = false;
+  let inFlight = Promise.resolve();
+  const counts = { exported: 0, dropped: 0, failed: 0, lastError: null };
+
+  function ensureTimer() {
+    if (timer || closed) return;
+    timer = setInterval(() => { flush(); }, flushIntervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  function recordSpan({ name, timeMs, attributes } = {}) {
+    try {
+      if (closed) return;
+      const ms = typeof timeMs === 'number' && Number.isFinite(timeMs) ? timeMs : Date.now();
+      const nanos = (BigInt(Math.round(ms)) * 1000000n).toString();
+      queue.push({
+        traceId: crypto.randomBytes(16).toString('hex'),
+        spanId: crypto.randomBytes(8).toString('hex'),
+        name: String(name),
+        kind: 1,
+        startTimeUnixNano: nanos,
+        endTimeUnixNano: nanos,
+        attributes: toAttributes(attributes),
+      });
+      if (queue.length > maxQueue) {
+        const over = queue.length - maxQueue;
+        queue.splice(0, over);
+        counts.dropped += over;
+      }
+      ensureTimer();
+    } catch (err) {
+      counts.lastError = err?.message || String(err);
+    }
+  }
+
+  async function post(spans) {
+    const body = JSON.stringify({
+      resourceSpans: [{
+        resource: { attributes: [{ key: 'service.name', value: { stringValue: String(serviceName) } }] },
+        scopeSpans: [{ scope: { name: String(scopeName) }, spans }],
+      }],
+    });
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { ...(headers || {}), 'content-type': 'application/json' },
+      body,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    try { await res.arrayBuffer(); } catch { /* body drain is best-effort */ }
+    if (!res.ok) throw new Error(`OTLP endpoint responded ${res.status}`);
+  }
+
+  async function drain() {
+    while (queue.length > 0) {
+      const batch = queue.splice(0, maxBatch);
+      try {
+        await post(batch);
+        counts.exported += batch.length;
+        counts.lastError = null;
+      } catch (err) {
+        counts.failed += 1;
+        counts.lastError = err?.message || String(err);
+        return; // drop this batch; the next tick retries whatever is left
+      }
+    }
+  }
+
+  function flush() {
+    const next = inFlight.then(drain, drain);
+    inFlight = next.catch(() => {});
+    return next.catch(() => {});
+  }
+
+  async function shutdown() {
+    closed = true;
+    if (timer) { clearInterval(timer); timer = null; }
+    let guard;
+    await Promise.race([
+      flush(),
+      new Promise((resolve) => { guard = setTimeout(resolve, timeoutMs); }),
+    ]);
+    clearTimeout(guard);
+    queue = [];
+  }
+
+  function stats() {
+    return {
+      queued: queue.length,
+      exported: counts.exported,
+      dropped: counts.dropped,
+      failed: counts.failed,
+      lastError: counts.lastError,
+    };
+  }
+
+  return { recordSpan, flush, shutdown, stats };
+}
+
+module.exports = { createOtlpTraceExporter };

package/src/main/lib/prereqs.cjs

@@ -0,0 +1,145 @@
+/**
+ * prereqs.cjs — first-run prerequisite checklist (git, Claude Code CLI,
+ * Claude sign-in, and Git Bash on Windows). Each missing item carries the
+ * OFFICIAL one-line install command so a UI can offer one-click installs.
+ * Detection only — never runs an installer. Probes are injectable
+ * (opts.execFile / hasCredentials / exists) so tests spawn nothing.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { promisify } = require('node:util');
+const childProcess = require('node:child_process');
+const { pathWithUserBins } = require('./cleanEnv.cjs');
+const { resolveClaudeBin } = require('./claudeBin.cjs');
+const { readCredentials } = require('./credentials.cjs');
+
+const PROBE_TIMEOUT_MS = 5000;
+const GIT_URL = 'https://git-scm.com/downloads';
+const CLAUDE_SETUP_URL = 'https://docs.claude.com/en/docs/claude-code/setup';
+const WINGET_GIT = 'winget install --id Git.Git -e --source winget';
+
+const execFileP = promisify(childProcess.execFile);
+
+/** Default probe: no shell, 5 s timeout, PATH widened with the user bin dirs. */
+function defaultExecFile(cmd, args) {
+  return execFileP(cmd, args, {
+    env: { ...process.env, PATH: pathWithUserBins() },
+    timeout: PROBE_TIMEOUT_MS,
+    windowsHide: true,
+  });
+}
+
+async function defaultHasCredentials() {
+  const r = await readCredentials();
+  return r.kind === 'ok';
+}
+
+function errText(e) {
+  const msg = (e && (e.message || e.code)) || String(e);
+  return String(msg).split('\n')[0].slice(0, 200);
+}
+
+/** Run a probe; resolves {ok, out} and never rejects (timeout/ENOENT → ok:false). */
+async function probe(execFile, cmd, args) {
+  try {
+    const r = await execFile(cmd, args);
+    const out = typeof r === 'string' ? r : (r && r.stdout) || '';
+    return { ok: true, out: String(out).trim(), error: null };
+  } catch (e) {
+    return { ok: false, out: '', error: errText(e) };
+  }
+}
+
+function item(id, label, ok, version, detail, fix) {
+  return { id, label, ok, version: ok ? version : null, detail: ok ? null : detail, fix: ok ? null : fix };
+}
+
+function gitFix(platform) {
+  if (platform === 'darwin') return { command: 'xcode-select --install', shell: 'sh', url: GIT_URL };
+  if (platform === 'win32') return { command: WINGET_GIT, shell: 'powershell', url: GIT_URL };
+  // linux: distro-specific — point at the package-manager docs instead of a command.
+  return { command: '', shell: 'sh', url: GIT_URL };
+}
+
+async function checkGit(platform, execFile) {
+  const ver = await probe(execFile, 'git', ['--version']);
+  let ok = ver.ok;
+  let detail = ver.error;
+  if (ok && platform === 'darwin') {
+    // /usr/bin/git on macOS is a stub that prompts for the Command Line Tools.
+    const xc = await probe(execFile, 'xcode-select', ['-p']);
+    if (!xc.ok) {
+      const which = await probe(execFile, 'which', ['git']);
+      if (!which.ok || which.out === '/usr/bin/git' || !which.out) {
+        ok = false;
+        detail = 'Xcode Command Line Tools are not installed';
+      }
+    }
+  }
+  const version = ver.out.replace(/^git version\s+/, '').split(/\s/)[0] || null;
+  const fix = gitFix(platform);
+  const missing = platform === 'linux'
+    ? `${detail || 'git not found'} — install it with your distro's package manager`
+    : (detail || 'git not found');
+  return item('git', 'Git', ok, version, missing, fix);
+}
+
+async function checkClaudeCli(platform, execFile, claudeBin) {
+  const bin = claudeBin || resolveClaudeBin();
+  const r = await probe(execFile, bin, ['--version']);
+  const win = platform === 'win32';
+  return item('claude-cli', 'Claude Code CLI', r.ok, r.out.split('\n')[0] || null,
+    r.error || 'claude not found', {
+      command: win ? 'irm https://claude.ai/install.ps1 | iex' : 'curl -fsSL https://claude.ai/install.sh | bash',
+      shell: win ? 'powershell' : 'sh',
+      url: CLAUDE_SETUP_URL,
+    });
+}
+
+async function checkClaudeAuth(platform, hasCredentials) {
+  let ok = false;
+  try { ok = !!(await hasCredentials()); } catch { ok = false; }
+  return item('claude-auth', 'Claude account', ok, null,
+    'Not signed in — run `claude` and sign in to your Claude account', {
+      command: 'claude',
+      shell: platform === 'win32' ? 'powershell' : 'sh',
+      url: CLAUDE_SETUP_URL,
+    });
+}
+
+function checkGitBash(exists) {
+  const candidates = [];
+  if (process.env.CLAUDE_CODE_GIT_BASH_PATH) candidates.push(process.env.CLAUDE_CODE_GIT_BASH_PATH);
+  candidates.push(path.win32.join(process.env.ProgramFiles || 'C:\\Program Files', 'Git', 'bin', 'bash.exe'));
+  let found = null;
+  for (const c of candidates) {
+    try { if (exists(c)) { found = c; break; } } catch { /* treat as absent */ }
+  }
+  return item('git-bash', 'Git Bash', !!found, found,
+    'Claude Code on Windows needs Git for Windows (bash.exe)',
+    { command: WINGET_GIT, shell: 'powershell', url: GIT_URL });
+}
+
+/**
+ * @param {{platform?: string, execFile?: Function, hasCredentials?: Function,
+ *          claudeBin?: string, exists?: (p: string) => boolean}} [opts]
+ * @returns {Promise<Array<{id:string,label:string,ok:boolean,version:string|null,detail:string|null,
+ *          fix:{command:string,shell:'sh'|'powershell',url?:string}|null}>>}
+ */
+async function checkPrereqs(opts = {}) {
+  const {
+    platform = process.platform,
+    execFile = defaultExecFile,
+    hasCredentials = defaultHasCredentials,
+    claudeBin,
+    exists = fs.existsSync,
+  } = opts;
+  const jobs = [checkGit(platform, execFile)];
+  if (platform === 'win32') jobs.push(Promise.resolve(checkGitBash(exists)));
+  jobs.push(checkClaudeCli(platform, execFile, claudeBin), checkClaudeAuth(platform, hasCredentials));
+  return Promise.all(jobs);
+}
+
+module.exports = { checkPrereqs };