claws-code 0.8.0

package/extension/src/backends/vscode/claws-pty.ts

@@ -0,0 +1,483 @@
+import * as vscode from 'vscode';
+import { spawn, spawnSync, ChildProcessWithoutNullStreams } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CaptureStore } from '../../capture-store';
+
+interface NodePtyModule {
+  spawn(
+    shell: string,
+    args: string[],
+    opts: {
+      name?: string;
+      cols?: number;
+      rows?: number;
+      cwd?: string;
+      env?: NodeJS.ProcessEnv;
+    },
+  ): NodePtyProcess;
+}
+
+interface NodePtyProcess {
+  pid: number;
+  onData(cb: (data: string) => void): void;
+  onExit(cb: (e: { exitCode: number; signal?: number }) => void): void;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+interface LoadAttempt {
+  path: string;
+  message: string;
+  code?: string;
+}
+
+let nodePtyCache: NodePtyModule | null = null;
+let loadedFromPath: string | null = null;
+let lastLoadError: { message: string; code?: string; stack?: string; attempts: LoadAttempt[] } | null = null;
+
+// Resolution order for node-pty. We always prefer the bundled copy at
+// <extension>/native/node-pty because it ships with the VSIX — it works even
+// when node_modules/ is stripped (which is what .vscodeignore does). Standard
+// resolution is kept as a fallback so `npm link`'d dev installs still work.
+function resolveCandidates(): string[] {
+  // __dirname is <extension>/dist at runtime (esbuild output) or
+  // <extension>/out in ts-node/dev. Either way, ../native/node-pty lands on
+  // the bundled copy.
+  const bundled = path.join(__dirname, '..', 'native', 'node-pty');
+  return [bundled, 'node-pty'];
+}
+
+// Load node-pty. We cache ONLY successful loads — failures are retried on
+// the next spawn so that if node-pty appears on disk mid-session (e.g. after
+// /claws-update compiles it), new terminals pick it up without a VS Code
+// reload. The full error from EACH failed require() is captured for the
+// diagnostic surface (exposed via loadNodePtyStatus() for the Health Check
+// command).
+function loadNodePty(logger?: (msg: string) => void): NodePtyModule | null {
+  if (nodePtyCache) return nodePtyCache;
+
+  const attempts: LoadAttempt[] = [];
+  for (const candidate of resolveCandidates()) {
+    try {
+      logger?.(`[node-pty] trying ${candidate}`);
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const mod = require(candidate) as NodePtyModule;
+      nodePtyCache = mod;
+      loadedFromPath = candidate;
+      lastLoadError = null;
+      logger?.(`[node-pty] loaded successfully from ${candidate}`);
+      return nodePtyCache;
+    } catch (err: unknown) {
+      const e = err as NodeJS.ErrnoException;
+      const attempt: LoadAttempt = {
+        path: candidate,
+        message: e.message || String(err),
+        code: e.code,
+      };
+      attempts.push(attempt);
+      logger?.(`[node-pty]   FAILED: ${attempt.message}${attempt.code ? ` (code=${attempt.code})` : ''}`);
+    }
+  }
+
+  const primary = attempts[0] ?? { path: '(none)', message: 'no candidates' };
+  lastLoadError = {
+    message: primary.message,
+    code: primary.code,
+    attempts,
+    stack: attempts.map((a) => `  ${a.path}: ${a.message}`).join('\n'),
+  };
+  if (logger) {
+    logger(`[node-pty] load FAILED — tried ${attempts.length} candidate(s):`);
+    for (const a of attempts) {
+      logger(`[node-pty]   ${a.path}: ${a.message}${a.code ? ` (${a.code})` : ''}`);
+    }
+    logger(`[node-pty] this causes wrapped terminals to fall back to pipe-mode.`);
+    logger(`[node-pty] fix: run 'Claws: Rebuild Native PTY' from the command palette`);
+  }
+  return null;
+}
+
+export function loadNodePtyStatus(): {
+  loaded: boolean;
+  loadedFrom?: string;
+  error?: { message: string; code?: string; attempts: LoadAttempt[] };
+} {
+  if (nodePtyCache) return { loaded: true, loadedFrom: loadedFromPath ?? undefined };
+  if (lastLoadError) {
+    return {
+      loaded: false,
+      error: {
+        message: lastLoadError.message,
+        code: lastLoadError.code,
+        attempts: lastLoadError.attempts,
+      },
+    };
+  }
+  return { loaded: false };
+}
+
+export interface ClawsPtyOptions {
+  terminalId: string;
+  shellPath?: string;
+  shellArgs?: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  captureStore: CaptureStore;
+  logger: (msg: string) => void;
+  /** Called synchronously when VS Code invokes Pseudoterminal.open(). */
+  onOpenHook?: () => void;
+  /** Called on the first byte of output from the spawned process. */
+  onFirstOutputHook?: () => void;
+  /** AF-AC Phase 1: called as the first action in handleExit, before closeEmitter.fire.
+   *  Fires from IPty.onExit (node-pty) or child_process 'exit' — the OS-authoritative signal. */
+  onProcessExitHook?: (exitCode: number) => void;
+  /** AC-1: when present, set as CLAWS_TERMINAL_CORR_ID env var on the spawned pty process.
+   *  Uses cross-platform {env: {...}} option on node-pty spawn — identical on darwin/linux/win32. */
+  correlationId?: string;
+}
+
+export class ClawsPty implements vscode.Pseudoterminal {
+  private readonly writeEmitter = new vscode.EventEmitter<string>();
+  private readonly closeEmitter = new vscode.EventEmitter<number | void>();
+
+  readonly onDidWrite: vscode.Event<string> = this.writeEmitter.event;
+  readonly onDidClose: vscode.Event<number | void> = this.closeEmitter.event;
+
+  private ptyProc: NodePtyProcess | null = null;
+  private childProc: ChildProcessWithoutNullStreams | null = null;
+  private isOpen = false;
+  private openedAt: number | null = null;
+  private readonly createdAt = Date.now();
+  private firstOutputFired = false;
+
+  constructor(private readonly opts: ClawsPtyOptions) {}
+
+  get pid(): number | null {
+    return this.ptyProc?.pid ?? this.childProc?.pid ?? null;
+  }
+
+  get mode(): 'pty' | 'pipe' | 'none' {
+    if (this.ptyProc) return 'pty';
+    if (this.childProc) return 'pipe';
+    return 'none';
+  }
+
+  /** True once VS Code has invoked our `open()` hook. */
+  hasOpened(): boolean {
+    return this.openedAt != null;
+  }
+
+  /** Wall-clock ms since this ClawsPty was constructed. */
+  ageMs(): number {
+    return Date.now() - this.createdAt;
+  }
+
+  /**
+   * Returns the foreground process running under the shell managed by this
+   * PTY. Uses pgrep to find the most recent child of the shell PID, then ps
+   * to get its basename. Falls back to the shell PID itself if no child is
+   * found. Returns { pid: null, basename: null } if the PTY has no spawned
+   * process yet.
+   */
+  getForegroundProcess(): { pid: number | null; basename: string | null } {
+    const shellPid = this.ptyProc?.pid ?? this.childProc?.pid;
+    if (!shellPid) return { pid: null, basename: null };
+    if (process.platform === 'win32') {
+      // ConPTY stub: pgrep/ps do not exist on Windows. Return the shell PID and
+      // the basename of the configured shell path as the best approximation.
+      // The safety gate uses basename for TUI detection; 'unknown' triggers a
+      // warning (not a hard block), so this is safe for v0.8.
+      const shell = this.opts.shellPath || '';
+      const basename = shell ? (shell.split(/[\\/]/).pop() ?? null) : null;
+      return { pid: shellPid, basename };
+    }
+    try {
+      const pgrepResult = spawnSync('pgrep', ['-P', String(shellPid)], { encoding: 'utf8', timeout: 500 });
+      const childOutput = (pgrepResult.stdout ?? '').trim();
+      let targetPid: number = shellPid;
+      if (childOutput) {
+        const childPids = childOutput.split('\n').filter(Boolean);
+        const candidatePid = parseInt(childPids[childPids.length - 1], 10);
+        if (!isNaN(candidatePid)) targetPid = candidatePid;
+      }
+      const psResult = spawnSync('ps', ['-p', String(targetPid), '-o', 'comm='], { encoding: 'utf8', timeout: 500 });
+      let basename = (psResult.stdout ?? '').trim() || null;
+      // If the child process has already exited, fall back to the shell itself.
+      if (!basename && targetPid !== shellPid) {
+        const fallback = spawnSync('ps', ['-p', String(shellPid), '-o', 'comm='], { encoding: 'utf8', timeout: 500 });
+        basename = (fallback.stdout ?? '').trim() || null;
+        targetPid = shellPid;
+      }
+      return { pid: targetPid, basename };
+    } catch {
+      return { pid: shellPid, basename: null };
+    }
+  }
+
+  open(initialDimensions: vscode.TerminalDimensions | undefined): void {
+    this.isOpen = true;
+    this.openedAt = Date.now();
+    this.opts.onOpenHook?.();
+    const shell = this.opts.shellPath || defaultShell();
+    const args = this.opts.shellArgs ?? defaultShellArgs(shell);
+    const cwd = this.opts.cwd || os.homedir();
+    // CLAWS_WRAPPED=1 is set ONLY when ptyProc is real, so the shell hook
+    // (scripts/shell-hook.sh) and any user-side check can distinguish a real
+    // wrapped pty from the pipe-mode degraded fallback. Set it here as the
+    // base env; we re-stamp it below once we know which path won.
+    const env = sanitizeEnv(process.env, { ...(this.opts.env || {}), TERM: 'xterm-256color' });
+    const cols = initialDimensions?.columns ?? 80;
+    const rows = initialDimensions?.rows ?? 24;
+
+    const nodePty = loadNodePty(this.opts.logger);
+    if (nodePty) {
+      // Warn if spawn-helper is not executable (darwin/linux only — win32 has no spawn-helper).
+      // node-pty uses posix_spawnp to exec spawn-helper; a non-executable file causes
+      // posix_spawnp to fail, degrading every wrapped terminal to pipe-mode silently.
+      // This check does NOT auto-fix the mode — only warns, so the upstream source bug is visible.
+      if (process.platform !== 'win32') {
+        const platKey = `${process.platform}-${process.arch}`;
+        const spawnHelperPath = path.join(__dirname, '..', 'native', 'node-pty', 'prebuilds', platKey, 'spawn-helper');
+        if (fs.existsSync(spawnHelperPath)) {
+          try {
+            const mode = fs.statSync(spawnHelperPath).mode;
+            if ((mode & 0o111) === 0) {
+              this.opts.logger(
+                `[claws-pty] spawn-helper at ${spawnHelperPath} is not executable (mode ${(mode & 0o777).toString(8)}). ` +
+                `node-pty.spawn will fail with posix_spawnp; falling back to pipe-mode. ` +
+                `Fix: chmod +x ${spawnHelperPath} (or rebuild VSIX after AC-1.1).`,
+              );
+            }
+          } catch { /* stat failed — proceed; spawn will surface the error */ }
+        }
+      }
+      try {
+        const ptyEnv: NodeJS.ProcessEnv = { ...env, CLAWS_WRAPPED: '1', CLAWS_TERMINAL_ID: this.opts.terminalId };
+        if (this.opts.correlationId) ptyEnv.CLAWS_TERMINAL_CORR_ID = this.opts.correlationId;
+        this.ptyProc = nodePty.spawn(shell, args, { cols, rows, cwd, env: ptyEnv, name: 'xterm-256color' });
+        this.ptyProc.onData((data) => this.handleOutput(data));
+        this.ptyProc.onExit(({ exitCode }) => this.handleExit(exitCode));
+        this.opts.logger(`[claws-pty ${this.opts.terminalId}] node-pty spawned ${shell} pid=${this.ptyProc.pid} (real pty)`);
+        return;
+      } catch (err) {
+        this.opts.logger(`[claws-pty ${this.opts.terminalId}] node-pty spawn failed: ${(err as Error).message}. Falling back to child_process pipe-mode.`);
+        this.ptyProc = null;
+      }
+    }
+
+    // Pipe-mode fallback. Log loudly to the Output channel AND emit the
+    // yellow banner into the terminal so the user sees it both ways.
+    try {
+      // Mark pipe-mode explicitly so the shell hook can warn.
+      const pipeEnv: NodeJS.ProcessEnv = { ...env, CLAWS_PIPE_MODE: '1', CLAWS_TERMINAL_ID: this.opts.terminalId };
+      if (this.opts.correlationId) pipeEnv.CLAWS_TERMINAL_CORR_ID = this.opts.correlationId;
+      this.childProc = spawn(shell, args, { cwd, env: pipeEnv, stdio: ['pipe', 'pipe', 'pipe'] });
+      this.childProc.stdout.on('data', (d: Buffer) => this.handleOutput(d.toString('utf8')));
+      this.childProc.stderr.on('data', (d: Buffer) => this.handleOutput(d.toString('utf8')));
+      this.childProc.on('exit', (code) => this.handleExit(code ?? 0));
+      const loadErr = lastLoadError?.message || 'unknown reason';
+      this.opts.logger(`[claws-pty ${this.opts.terminalId}] PIPE-MODE active (node-pty unavailable): ${loadErr}`);
+      this.opts.logger(`[claws-pty ${this.opts.terminalId}] TUIs will not render correctly. Run 'Claws: Health Check' for diagnostics.`);
+      this.opts.logger(`[claws-pty ${this.opts.terminalId}] child_process fallback ${shell} pid=${this.childProc.pid}`);
+      this.writeEmitter.fire('\x1b[33m[claws] running in pipe-mode (node-pty unavailable); TUIs may render poorly\x1b[0m\r\n');
+      this.writeEmitter.fire('\x1b[2m[claws] run "Claws: Health Check" in the command palette for why\x1b[0m\r\n');
+    } catch (err) {
+      this.opts.logger(`[claws-pty ${this.opts.terminalId}] SPAWN FAILED: ${(err as Error).message}`);
+      this.writeEmitter.fire(`\x1b[31m[claws] failed to spawn shell: ${(err as Error).message}\x1b[0m\r\n`);
+      this.closeEmitter.fire(1);
+    }
+  }
+
+  close(): void {
+    if (!this.isOpen) return;
+    this.isOpen = false;
+    if (this.ptyProc) {
+      try { this.ptyProc.kill(); } catch { /* ignore */ }
+      this.ptyProc = null;
+    }
+    if (this.childProc) {
+      try { this.childProc.kill(); } catch { /* ignore */ }
+      this.childProc = null;
+    }
+  }
+
+  handleInput(data: string): void {
+    if (!this.isOpen) return;
+    if (this.ptyProc) {
+      this.ptyProc.write(data);
+    } else if (this.childProc?.stdin.writable) {
+      this.childProc.stdin.write(data);
+    }
+  }
+
+  setDimensions(dimensions: vscode.TerminalDimensions): void {
+    if (this.ptyProc) {
+      try { this.ptyProc.resize(dimensions.columns, dimensions.rows); } catch { /* ignore */ }
+    }
+  }
+
+  writeInjected(text: string, withNewline: boolean, bracketedPaste: boolean): void {
+    if (!this.isOpen) return;
+    const body = bracketedPaste ? `\x1b[200~${text}\x1b[201~` : text;
+    this.writeRaw(body);
+    if (!withNewline) return;
+    // For bracketed paste, the trailing CR must arrive in a separate write
+    // after a short delay so the TUI's paste-detection window closes first.
+    // Otherwise Ink-based TUIs (Claude Code) bundle the CR into the paste
+    // burst and it never registers as a discrete Enter keypress.
+    if (bracketedPaste) {
+      setTimeout(() => this.writeRaw('\r'), 30);
+    } else {
+      this.writeRaw('\r');
+    }
+  }
+
+  private writeRaw(data: string): void {
+    if (!this.isOpen) return;
+    if (this.ptyProc) {
+      this.ptyProc.write(data);
+    } else if (this.childProc?.stdin.writable) {
+      this.childProc.stdin.write(data);
+    }
+  }
+
+  private handleOutput(data: string): void {
+    this.writeEmitter.fire(data);
+    this.opts.captureStore.append(this.opts.terminalId, data);
+    if (!this.firstOutputFired) {
+      this.firstOutputFired = true;
+      this.opts.onFirstOutputHook?.();
+    }
+  }
+
+  private handleExit(code: number): void {
+    this.opts.onProcessExitHook?.(code);
+    if (this.isOpen) {
+      this.isOpen = false;
+      this.closeEmitter.fire(code);
+    }
+  }
+}
+
+// ─── Shell resolution ─────────────────────────────────────────────────────
+
+/**
+ * Pick the shell to spawn a wrapped terminal under.
+ *
+ * Order:
+ *   1. $SHELL (user's configured login shell — respect their choice)
+ *   2. /bin/bash (more common default on Linux)
+ *   3. /bin/zsh (default on macOS Catalina+)
+ *   4. /bin/sh (POSIX bottom floor — always present)
+ *
+ * We deliberately don't hardcode zsh: on headless Linux boxes, zsh often
+ * isn't installed at all and falling back to it produces ENOENT at spawn.
+ */
+export function defaultShell(): string {
+  if (process.platform === 'win32') {
+    return process.env.COMSPEC || 'powershell.exe';
+  }
+  if (process.env.SHELL) return process.env.SHELL;
+  const candidates = ['/bin/bash', '/bin/zsh', '/bin/sh'];
+  for (const c of candidates) {
+    try {
+      if (fs.existsSync(c)) return c;
+    } catch { /* ignore */ }
+  }
+  return '/bin/sh';
+}
+
+/**
+ * Pick default argv for the chosen shell.
+ *
+ * We always pass `-i` (interactive) so the shell reads its per-user rc file
+ * (`.zshrc`, `.bashrc`, `fish.config`) — this is what makes aliases, PATH
+ * adjustments, and prompt customisation show up.
+ *
+ * We add `-l` (login) ONLY when the user has a login-shell profile file on
+ * disk (`.zprofile`, `.bash_profile`, `.profile`). Adding `-l` unconditionally
+ * is a footgun: many users have slow `.profile` scripts (nvm init, asdf init,
+ * cargo env…) that would then run on EVERY wrapped-terminal creation.
+ * Defaulting to `-i` alone is the fast path — explicit login-profile files
+ * signal the user actually wants login-shell semantics.
+ */
+export function defaultShellArgs(shell: string): string[] {
+  if (process.platform === 'win32') return [];
+  const base = shell.split('/').pop() || shell;
+  if (base === 'zsh' || base === 'bash' || base === 'fish' || base === 'sh') {
+    const home = process.env.HOME || os.homedir();
+    const loginFiles = ['.zprofile', '.bash_profile', '.profile'];
+    let hasLoginProfile = false;
+    for (const f of loginFiles) {
+      try {
+        if (fs.existsSync(path.join(home, f))) { hasLoginProfile = true; break; }
+      } catch { /* ignore */ }
+    }
+    return hasLoginProfile ? ['-i', '-l'] : ['-i'];
+  }
+  return [];
+}
+
+// ─── Env sanitization ─────────────────────────────────────────────────────
+
+/**
+ * Strip VS Code/Electron/npm-lifecycle environment vars before forwarding to
+ * the user's shell. Leaves standard user env (PATH, HOME, USER, LANG, LC_*,
+ * SHELL, EDITOR, VISUAL, TERM, DISPLAY, etc.) intact.
+ *
+ * Why: VS Code's process environment is polluted with internal variables
+ * like VSCODE_IPC_HOOK, VSCODE_PID, ELECTRON_RUN_AS_NODE, plus npm_* vars
+ * from however it was started. Propagating these to the user's shell
+ * confuses `claude` (which inspects ELECTRON_*) and produces bogus
+ * "running inside Electron" warnings.
+ *
+ * `overrides` wins over `baseEnv`, and any `undefined` in `overrides`
+ * explicitly deletes the key from the result.
+ */
+export function sanitizeEnv(
+  baseEnv: NodeJS.ProcessEnv,
+  overrides: NodeJS.ProcessEnv = {},
+): NodeJS.ProcessEnv {
+  const DROP_PREFIXES = ['VSCODE_', 'ELECTRON_', 'CHROME_', 'GOOGLE_API_', 'npm_'];
+  const DROP_EXACT = new Set([
+    'INIT_CWD',
+    'VSCODE_PID',
+    'VSCODE_CWD',
+    'VSCODE_IPC_HOOK',
+    'VSCODE_IPC_HOOK_CLI',
+    'VSCODE_NLS_CONFIG',
+    'VSCODE_CODE_CACHE_PATH',
+    'VSCODE_CRASH_REPORTER_PROCESS_TYPE',
+    'VSCODE_HANDLES_UNCAUGHT_ERRORS',
+    'VSCODE_INJECTION',
+    'VSCODE_L10N_BUNDLE_LOCATION',
+    'NODE_OPTIONS', // Often set to --inspect by debug; let user shell pick its own.
+  ]);
+
+  const shouldDrop = (key: string): boolean => {
+    const upper = key.toUpperCase();
+    if (DROP_EXACT.has(key) || DROP_EXACT.has(upper)) return true;
+    for (const p of DROP_PREFIXES) {
+      if (upper.startsWith(p.toUpperCase())) return true;
+    }
+    return false;
+  };
+
+  const out: NodeJS.ProcessEnv = {};
+  for (const [k, v] of Object.entries(baseEnv)) {
+    if (v === undefined) continue;
+    if (shouldDrop(k)) continue;
+    out[k] = v;
+  }
+  for (const [k, v] of Object.entries(overrides)) {
+    if (v === undefined) {
+      delete out[k];
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}

package/extension/src/backends/vscode/status-bar.ts

@@ -0,0 +1,99 @@
+// Claws status bar item. Right-aligned, priority 100, click → Health Check.
+// Color shifts to warning / error based on server + node-pty state.
+
+import * as vscode from 'vscode';
+import * as path from 'path';
+import { loadNodePtyStatus } from './claws-pty';
+import { ClawsServer } from '../../server';
+
+export interface StatusBarOptions {
+  activated: boolean;
+  version: string;
+  getServers: () => Map<string, ClawsServer>;
+  getTerminalCount: () => number;
+}
+
+export interface StatusBarHandle {
+  item: vscode.StatusBarItem;
+  timer: NodeJS.Timeout;
+  update: () => void;
+  dispose: () => void;
+}
+
+/**
+ * Create the status bar item and start a 30-second refresh timer. Caller
+ * owns the lifecycle — call `dispose()` on deactivate to clear the timer
+ * and dispose the item.
+ */
+export function createStatusBar(
+  context: vscode.ExtensionContext,
+  opts: StatusBarOptions,
+): StatusBarHandle {
+  const item = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 100);
+  item.name = 'Claws';
+  item.text = '$(terminal) Claws';
+  item.command = 'claws.healthCheck';
+  item.show();
+  context.subscriptions.push(item);
+
+  const update = (): void => renderStatusBar(item, opts);
+
+  // Refresh every 30s so pid counts, node-pty status, socket liveness stay
+  // current even without terminal-lifecycle events firing.
+  const timer = setInterval(update, 30_000);
+  if (typeof timer.unref === 'function') timer.unref();
+
+  update();
+
+  const dispose = (): void => {
+    clearInterval(timer);
+    try { item.dispose(); } catch { /* ignore */ }
+  };
+
+  return { item, timer, update, dispose };
+}
+
+function renderStatusBar(item: vscode.StatusBarItem, opts: StatusBarOptions): void {
+  const servers = opts.getServers();
+  const npty = loadNodePtyStatus();
+
+  let state: 'ok' | 'warn' | 'err' = 'ok';
+  let hint = '';
+
+  if (!opts.activated) {
+    state = 'err';
+    hint = 'bridge disabled (no workspace open)';
+  } else if (servers.size === 0) {
+    state = 'err';
+    hint = 'no socket servers running';
+  } else if (npty.loaded === false && npty.error) {
+    state = 'warn';
+    hint = 'pipe-mode (node-pty not loaded)';
+  }
+
+  const termCount = opts.getTerminalCount();
+  const iconPrefix = state === 'err' ? '$(error)' : state === 'warn' ? '$(warning)' : '$(terminal)';
+  item.text = `${iconPrefix} Claws${termCount > 0 ? ` (${termCount})` : ''}`;
+  item.color = state === 'err'
+    ? new vscode.ThemeColor('statusBarItem.errorForeground')
+    : state === 'warn'
+      ? new vscode.ThemeColor('statusBarItem.warningForeground')
+      : undefined;
+
+  const tooltip = new vscode.MarkdownString(undefined, true);
+  tooltip.isTrusted = false;
+  tooltip.appendMarkdown(`**Claws** · v${opts.version}\n\n`);
+  if (hint) tooltip.appendMarkdown(`_${hint}_\n\n`);
+  tooltip.appendMarkdown(`**Sockets** (${servers.size}):\n`);
+  if (servers.size === 0) {
+    tooltip.appendMarkdown(`· _none_\n`);
+  } else {
+    for (const [root, srv] of servers.entries()) {
+      tooltip.appendMarkdown(`· \`${path.basename(root)}\` → \`${srv.getSocketPath() ?? '(pending)'}\`\n`);
+    }
+  }
+  tooltip.appendMarkdown(`\n**Terminals**: ${termCount}\n\n`);
+  tooltip.appendMarkdown(`**node-pty**: ${npty.loaded ? 'loaded' : npty.error ? 'not loaded (pipe-mode)' : 'not attempted yet'}\n\n`);
+  tooltip.appendMarkdown(`_Click for Health Check_`);
+  item.tooltip = tooltip;
+}