claws-code 0.8.0

package/scripts/monitor-arm-watch.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Layer 1 of per-worker Monitor enforcement.
+//
+// Catches the gap where lifecycle.monitors[] is pre-populated by mcp_server
+// atomically at spawn time, so the PostToolUse hook's monitors.some() check
+// is vacuously satisfied even when no OS-level stream-events.js process is
+// actually arming. This script sleeps grace_ms, then checks via pgrep whether
+// a real stream-events.js --wait <corrId> process is alive. If not, it
+// connects to the claws socket and publishes system.monitor.unarmed.
+//
+// Layer 2 (planned: hello-with-monitorCorrelationId) will close the loophole
+// structurally by having stream-events.js register its corrId via hello;
+// Layer 1 detects and emits a warning event.
+//
+// Idempotent: publishing system.monitor.unarmed twice for the same corrId is
+// harmless — consumers can dedupe on correlation_id.
+//
+// Usage: node monitor-arm-watch.js --corr-id <uuid> --term-id <id>
+//                                  [--grace-ms <ms>] --socket <path>
+// Exit codes: 0 = monitor found, 1 = unarmed (event published), 2 = error
+'use strict';
+
+const { spawnSync } = require('child_process');
+const net           = require('net');
+
+const rawArgs = process.argv.slice(2);
+let corrId     = null;
+let termId     = null;
+let graceMs    = 10000;
+let socketPath = null;
+
+for (let i = 0; i < rawArgs.length; i++) {
+  const a = rawArgs[i];
+  if      (a === '--corr-id')  { corrId     = rawArgs[++i] || null; }
+  else if (a === '--term-id')  { termId     = String(rawArgs[++i] ?? ''); }
+  else if (a === '--grace-ms') { graceMs    = parseInt(rawArgs[++i], 10) || 10000; }
+  else if (a === '--socket')   { socketPath = rawArgs[++i] || null; }
+}
+
+if (!corrId || !socketPath) {
+  process.stderr.write(`monitor-arm-watch: exit 2 | reason=missing-args | corr=${corrId}\n`);
+  process.exit(2);
+}
+
+// Emit a startup line immediately (before the grace-period sleep) so the log
+// file is non-empty even if we crash during the sleep or pgrep phases.
+process.stderr.write(
+  `monitor-arm-watch: starting | corr=${corrId} | term=${termId}` +
+  ` | socket=${socketPath} | cwd=${process.cwd()}\n`
+);
+
+(async () => {
+  await sleep(graceMs);
+
+  let pg;
+  try {
+    pg = spawnSync('/usr/bin/pgrep', ['-f', `stream-events.js.*--wait ${corrId}`], {
+      encoding: 'utf8',
+      timeout:  5000,
+    });
+  } catch (e) {
+    process.stderr.write(`monitor-arm-watch: exit 2 | reason=pgrep-spawn-failed:${e.message} | corr=${corrId}\n`);
+    process.exit(2);
+  }
+
+  if (pg.error) {
+    process.stderr.write(`monitor-arm-watch: exit 2 | reason=pgrep-error:${pg.error.message} | corr=${corrId}\n`);
+    process.exit(2);
+  }
+
+  if (pg.status === 0) {
+    // Monitor process is alive — nothing to do.
+    process.stderr.write(`monitor-arm-watch: exit 0 | reason=monitor-found | corr=${corrId}\n`);
+    process.exit(0);
+  }
+
+  if (pg.status === 1) {
+    // No matching process — publish warning event.
+    try {
+      await publishUnarmed(socketPath, {
+        terminal_id:    termId,
+        correlation_id: corrId,
+        grace_ms:       graceMs,
+        detected_at:    new Date().toISOString(),
+      });
+    } catch (e) {
+      process.stderr.write(`monitor-arm-watch: exit 2 | reason=socket-error:${e.message} | corr=${corrId}\n`);
+      process.exit(2);
+    }
+    process.stderr.write(`monitor-arm-watch: exit 1 | reason=unarmed-published | corr=${corrId}\n`);
+    process.exit(1);
+  }
+
+  process.stderr.write(`monitor-arm-watch: exit 2 | reason=pgrep-unexpected-status:${pg.status} | corr=${corrId}\n`);
+  process.exit(2);
+})();
+
+function publishUnarmed(sockPath, payload) {
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection(sockPath);
+    let buf   = '';
+    let state = 'hello'; // 'hello' → 'publish' → done
+    let done  = false;
+
+    const finish = (err) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { sock.destroy(); } catch {}
+      if (err) reject(err);
+      else resolve();
+    };
+
+    const timer = setTimeout(() => finish(new Error('socket timeout')), 5000);
+
+    const send = (obj) => {
+      const id = Math.random().toString(36).slice(2);
+      try { sock.write(JSON.stringify({ id, ...obj }) + '\n'); } catch (e) { finish(e); }
+    };
+
+    sock.on('connect', () => {
+      send({ cmd: 'hello', protocol: 'claws/2', peerName: 'monitor-arm-watch', role: 'observer' });
+    });
+
+    sock.on('data', (chunk) => {
+      buf += chunk.toString('utf8');
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line) continue;
+        try { JSON.parse(line); } catch { continue; }
+        if (state === 'hello') {
+          state = 'publish';
+          send({
+            cmd: 'publish', protocol: 'claws/2',
+            topic: 'system.monitor.unarmed',
+            payload,
+          });
+        } else if (state === 'publish') {
+          finish(null);
+        }
+      }
+    });
+
+    sock.on('error', (e) => finish(e));
+    sock.on('close', () => {
+      if (!done) finish(new Error('connection closed before publish ack'));
+    });
+  });
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}

package/scripts/rebuild-node-pty.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# Claws — force-rebuild node-pty against VS Code's Electron ABI
+#
+# Run when the extension keeps saying "[claws] running in pipe-mode
+# (node-pty unavailable)" and /claws-update didn't fix it. This script is
+# deliberately independent of /claws-update / /claws-fix — pure bash, shows
+# every step, so you (and I) can see exactly where things go wrong.
+#
+# Usage:
+#   # From repo clone:
+#   bash ~/.claws-src/scripts/rebuild-node-pty.sh
+#
+#   # Direct from GitHub (no clone needed):
+#   bash <(curl -fsSL https://raw.githubusercontent.com/neunaha/claws/main/scripts/rebuild-node-pty.sh)
+#
+# Env overrides:
+#   CLAWS_DIR=/path         Override ~/.claws-src location
+#   ELECTRON_VERSION=X.Y.Z  Force a specific Electron target (otherwise auto-detected)
+
+# Deliberately NOT using `set -e` — we want to continue past individual
+# step failures so the user sees the full diagnostic.
+
+INSTALL_DIR="${CLAWS_DIR:-$HOME/.claws-src}"
+C_RESET=$'\033[0m'; C_BOLD=$'\033[1m'
+C_GREEN=$'\033[0;32m'; C_YELLOW=$'\033[0;33m'; C_RED=$'\033[0;31m'; C_BLUE=$'\033[0;34m'; C_DIM=$'\033[2m'
+
+h1()   { printf "\n${C_BOLD}${C_BLUE}═══ %s ═══${C_RESET}\n" "$*"; }
+ok()   { printf "  ${C_GREEN}✓${C_RESET} %s\n" "$*"; }
+warn() { printf "  ${C_YELLOW}!${C_RESET} %s\n" "$*"; }
+bad()  { printf "  ${C_RED}✗${C_RESET} %s\n" "$*"; }
+info() { printf "  ${C_DIM}%s${C_RESET}\n" "$*"; }
+
+# ─── 0. Pre-flight ─────────────────────────────────────────────────────────
+h1 "Pre-flight"
+info "PLATFORM: $(uname -s) $(uname -r) $(uname -m)"
+info "node:     $(command -v node 2>/dev/null) $(node --version 2>/dev/null)"
+info "npm:      $(command -v npm 2>/dev/null) $(npm --version 2>/dev/null)"
+info "npx:      $(command -v npx 2>/dev/null)"
+if [ "$(uname -s)" = "Darwin" ]; then
+  if xcode-select -p &>/dev/null; then
+    ok "Xcode CLT at $(xcode-select -p)"
+  else
+    bad "Xcode Command Line Tools NOT installed"
+    warn "without them node-pty cannot compile. Install with:"
+    echo "      xcode-select --install"
+    echo "   then re-run this script."
+    exit 1
+  fi
+fi
+
+if [ ! -d "$INSTALL_DIR/extension" ]; then
+  bad "Claws source not found at $INSTALL_DIR/extension"
+  warn "install Claws first: bash <(curl -fsSL https://raw.githubusercontent.com/neunaha/claws/main/scripts/install.sh)"
+  exit 1
+fi
+ok "source clone at $INSTALL_DIR"
+
+NPTY_DIR="$INSTALL_DIR/extension/node_modules/node-pty"
+NPTY_BIN="$NPTY_DIR/build/Release/pty.node"
+ABI_FILE="$INSTALL_DIR/extension/dist/.electron-abi"
+
+# ─── 1. Detect VS Code's Electron version ──────────────────────────────────
+h1 "Detect VS Code Electron version"
+if [ -n "$ELECTRON_VERSION" ]; then
+  info "ELECTRON_VERSION env override: $ELECTRON_VERSION"
+elif [ "$(uname -s)" = "Darwin" ]; then
+  # M-36: TERM_PROGRAM-aware ordering + CURSOR_CHANNEL secondary signal.
+  _rn_tp="${TERM_PROGRAM:-}"
+  [ "$_rn_tp" = "vscode" ] && [ -n "${CURSOR_CHANNEL:-}" ] && _rn_tp="cursor"
+  _rn_tp=$(echo "$_rn_tp" | tr '[:upper:]' '[:lower:]')
+  case "$_rn_tp" in
+    cursor)   _rn_darwin_apps=('/Applications/Cursor.app' '/Applications/Visual Studio Code.app' '/Applications/Visual Studio Code - Insiders.app' '/Applications/Windsurf.app') ;;
+    windsurf) _rn_darwin_apps=('/Applications/Windsurf.app' '/Applications/Visual Studio Code.app' '/Applications/Visual Studio Code - Insiders.app' '/Applications/Cursor.app') ;;
+    *)        _rn_darwin_apps=('/Applications/Visual Studio Code.app' '/Applications/Visual Studio Code - Insiders.app' '/Applications/Cursor.app' '/Applications/Windsurf.app') ;;
+  esac
+  for _rn_app in "${_rn_darwin_apps[@]}"; do
+    plist="$_rn_app/Contents/Frameworks/Electron Framework.framework/Resources/Info.plist"
+    if [ -f "$plist" ]; then
+      v=$(plutil -extract CFBundleVersion raw "$plist" 2>/dev/null || true)
+      if [ -n "$v" ]; then
+        ELECTRON_VERSION="$v"
+        ok "$(basename "$_rn_app") uses Electron $v"
+        break
+      fi
+    else
+      info "$(basename "$_rn_app"): not installed"
+    fi
+  done
+elif [ "$(uname -s)" = "Linux" ]; then
+  # M-36: Linux Cursor/Windsurf paths + TERM_PROGRAM ordering.
+  _rn_tp="${TERM_PROGRAM:-}"
+  [ "$_rn_tp" = "vscode" ] && [ -n "${CURSOR_CHANNEL:-}" ] && _rn_tp="cursor"
+  _rn_tp=$(echo "$_rn_tp" | tr '[:upper:]' '[:lower:]')
+  _rn_linux_vscode=('/usr/share/code/electron' '/usr/lib/code/electron' '/opt/visual-studio-code/electron' '/snap/code/current/electron')
+  _rn_linux_cursor=('/usr/share/cursor/electron' '/opt/cursor/electron' '/snap/cursor/current/usr/share/cursor/electron')
+  _rn_linux_windsurf=('/usr/share/windsurf/electron' '/opt/windsurf/electron')
+  _rn_linux_candidates=()
+  case "$_rn_tp" in
+    cursor)   _rn_linux_candidates=("${_rn_linux_cursor[@]}" "${_rn_linux_vscode[@]}" "${_rn_linux_windsurf[@]}") ;;
+    windsurf) _rn_linux_candidates=("${_rn_linux_windsurf[@]}" "${_rn_linux_vscode[@]}" "${_rn_linux_cursor[@]}") ;;
+    *)        _rn_linux_candidates=("${_rn_linux_vscode[@]}" "${_rn_linux_cursor[@]}" "${_rn_linux_windsurf[@]}") ;;
+  esac
+  for _rn_ep in "${_rn_linux_candidates[@]}"; do
+    if [ -x "$_rn_ep" ]; then
+      v=$("$_rn_ep" --version 2>/dev/null | sed 's/^v//' || true)
+      if echo "$v" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+        ELECTRON_VERSION="$v"
+        ok "detected Electron $v from $_rn_ep"
+        break
+      fi
+    fi
+  done
+fi
+if [ -z "$ELECTRON_VERSION" ]; then
+  ELECTRON_VERSION="39.8.5"
+  warn "couldn't auto-detect — using fallback $ELECTRON_VERSION"
+fi
+
+# ─── 2. Current binary state ───────────────────────────────────────────────
+h1 "Current node-pty state"
+if [ -d "$NPTY_DIR" ]; then
+  ok "node-pty package installed at $NPTY_DIR"
+  pkg_ver=$(node -p "require('$NPTY_DIR/package.json').version" 2>/dev/null)
+  info "node-pty version: $pkg_ver"
+else
+  warn "node-pty not installed — running npm install first"
+  ( cd "$INSTALL_DIR/extension" && npm install --no-audit --no-fund --loglevel=error 2>&1 | tail -5 )
+fi
+
+if [ -f "$NPTY_BIN" ]; then
+  size=$(wc -c < "$NPTY_BIN" | tr -d ' ')
+  mtime=$(stat -f '%Sm' "$NPTY_BIN" 2>/dev/null || stat -c '%y' "$NPTY_BIN" 2>/dev/null)
+  info "binary exists: $size bytes, mtime $mtime"
+else
+  warn "binary NOT present at $NPTY_BIN"
+fi
+
+if [ -f "$ABI_FILE" ]; then
+  last_abi=$(cat "$ABI_FILE")
+  info "last-built ABI: Electron $last_abi"
+  if [ "$last_abi" = "$ELECTRON_VERSION" ]; then
+    ok "recorded ABI matches current Electron"
+  else
+    warn "recorded ABI '$last_abi' ≠ current Electron '$ELECTRON_VERSION' — rebuild needed"
+  fi
+else
+  warn "no ABI marker — treating as stale"
+fi
+
+# ─── 3. Force-rebuild with @electron/rebuild ───────────────────────────────
+h1 "Rebuilding node-pty for Electron $ELECTRON_VERSION"
+info "removing old binary + ABI marker to force a clean rebuild"
+rm -f "$NPTY_BIN" "$ABI_FILE" 2>/dev/null
+
+info "running: npx --yes @electron/rebuild --version=$ELECTRON_VERSION --only=node-pty --force"
+# M-36: 5-minute timeout ceiling — prevents indefinite hang on slow Electron header fetch.
+_rn_timeout_cmd=""
+if command -v timeout >/dev/null 2>&1; then _rn_timeout_cmd="timeout 300"
+elif command -v gtimeout >/dev/null 2>&1; then _rn_timeout_cmd="gtimeout 300"
+fi
+rebuild_log=$(mktemp -t claws-rebuild.XXXXXX.log)
+if ( cd "$INSTALL_DIR/extension" && $_rn_timeout_cmd npx --yes @electron/rebuild --version="$ELECTRON_VERSION" --only=node-pty --force ) >"$rebuild_log" 2>&1; then
+  ok "@electron/rebuild completed"
+  info "log: $rebuild_log (last 5 lines below)"
+  tail -5 "$rebuild_log" | sed 's/^/    /'
+else
+  _rn_rc=$?
+  if [ "$_rn_rc" = "124" ]; then
+    bad "@electron/rebuild timed out after 5 min — likely a slow Electron headers download. Check network / proxy settings."
+  else
+    bad "@electron/rebuild FAILED"
+  fi
+  info "full log: $rebuild_log"
+  info "last 20 lines:"
+  tail -20 "$rebuild_log" | sed 's/^/    /'
+  echo ""
+  bad "cannot proceed — node-pty will not work until the build succeeds"
+  exit 1
+fi
+
+# ─── 4. Verify the new binary ──────────────────────────────────────────────
+h1 "Verify new binary"
+if [ ! -f "$NPTY_BIN" ]; then
+  bad "rebuild reported success but $NPTY_BIN is still missing"
+  exit 1
+fi
+new_size=$(wc -c < "$NPTY_BIN" | tr -d ' ')
+new_mtime=$(stat -f '%Sm' "$NPTY_BIN" 2>/dev/null || stat -c '%y' "$NPTY_BIN" 2>/dev/null)
+ok "binary: $NPTY_BIN ($new_size bytes, mtime $new_mtime)"
+
+echo "$ELECTRON_VERSION" > "$ABI_FILE"
+ok "recorded Electron ABI → $ABI_FILE"
+
+# ─── 5. ABI sanity check ───────────────────────────────────────────────────
+# We can't fully simulate Electron's Node from a plain shell. But we can
+# detect the NODE_MODULE_VERSION embedded in the .node binary by looking at
+# raw bytes. Matching ABIs:
+#   Node 22 (Electron 39) → NODE_MODULE_VERSION=127
+#   Node 24 (system)      → NODE_MODULE_VERSION=131
+h1 "ABI sanity check"
+info "system node would load the binary as:"
+sys_load=$(node -e "try{require('$NPTY_BIN');console.log('LOADS IN SYSTEM NODE')}catch(e){console.log('FAILS IN SYSTEM NODE:',e.message.split('\\n')[0])}" 2>&1)
+info "    $sys_load"
+
+if echo "$sys_load" | grep -q "FAILS IN SYSTEM NODE.*NODE_MODULE_VERSION"; then
+  ok "binary REJECTED by system Node — this is the GOOD sign"
+  info "    it means the binary's ABI doesn't match system Node 24,"
+  info "    which is exactly what we want for Electron 39 (Node 22)"
+elif echo "$sys_load" | grep -q "LOADS IN SYSTEM NODE"; then
+  if [ "$ELECTRON_VERSION" = "39.8.5" ] || echo "$ELECTRON_VERSION" | grep -qE "^(3[0-9]|4[0-9])\."; then
+    bad "binary LOADS in system Node — that's WRONG for Electron $ELECTRON_VERSION"
+    warn "it means the rebuild actually targeted system Node, not Electron."
+    warn "this is the bug that keeps pipe-mode warnings active. Try:"
+    echo ""
+    echo "    cd $INSTALL_DIR/extension"
+    echo "    rm -rf node_modules/node-pty"
+    echo "    npm install node-pty"
+    echo "    npx @electron/rebuild --version=$ELECTRON_VERSION --only=node-pty --force"
+    echo ""
+    exit 1
+  else
+    ok "binary loads in system Node (expected for Electron versions that share Node ABI)"
+  fi
+else
+  warn "couldn't interpret result: $sys_load"
+fi
+
+# ─── 6. Done ───────────────────────────────────────────────────────────────
+h1 "Next step"
+echo ""
+printf "  ${C_BOLD}1. Reload VS Code${C_RESET}\n"
+echo "       Cmd+Shift+P → Developer: Reload Window"
+echo ""
+printf "  ${C_BOLD}2. Open the Output panel${C_RESET}\n"
+echo "       Cmd+Shift+U → dropdown → 'Claws'"
+echo "       You should see 'activating (typescript)' with NO pipe-mode warning."
+echo ""
+printf "  ${C_BOLD}3. Spawn a wrapped terminal${C_RESET}\n"
+echo "       + dropdown → 'Claws Wrapped Terminal'"
+echo "       Should open cleanly, no '[claws] running in pipe-mode' line."
+echo ""
+printf "  ${C_BOLD}If it still shows pipe-mode after reload:${C_RESET}\n"
+echo "       bash $INSTALL_DIR/scripts/report.sh \"\$(pwd)\""
+echo "       and share the generated ~/claws-report-*.txt"
+echo ""

package/scripts/report.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# Claws — diagnostic bundle generator
+# Usage: bash ~/.claws-src/scripts/report.sh [project-dir]
+#
+# Produces a single file with everything needed to diagnose install/runtime
+# issues: OS info, Node version, install log, extension state, VS Code
+# extension logs, project-local file presence. The output file path is
+# printed at the end — share it in a GitHub issue.
+
+set -eo pipefail
+
+PROJECT_ROOT="${1:-$(pwd)}"
+INSTALL_DIR="${CLAWS_DIR:-$HOME/.claws-src}"
+REPORT_DIR="${CLAWS_REPORT_DIR:-$HOME}"
+REPORT="$REPORT_DIR/claws-report-$(date +%Y%m%d-%H%M%S).txt"
+
+redact() {
+  # Replace the user's home path with $HOME to reduce leaked info in pastes.
+  # Also strip anything that looks like a token/key.
+  sed -e "s|$HOME|\$HOME|g" \
+      -e 's|[A-Za-z0-9]\{32,\}|<redacted>|g'
+}
+
+say() { echo "$@" >> "$REPORT"; }
+section() { echo "" >> "$REPORT"; echo "═════ $1 ═════" >> "$REPORT"; }
+
+{
+  echo "Claws Diagnostic Report"
+  echo "Generated: $(date)"
+  echo "Project:   $PROJECT_ROOT"
+  echo "Install:   $INSTALL_DIR"
+} > "$REPORT"
+
+section "System dependencies"
+PLATFORM="$(uname -s)"
+say "OS:            $(uname -a)"
+say "Shell:         $SHELL ($(basename "$SHELL"))"
+say "bash:          $BASH_VERSION"
+say ""
+say "git:           $(command -v git 2>/dev/null || echo '—') $(git --version 2>/dev/null || echo 'NOT INSTALLED')"
+say "node:          $(command -v node 2>/dev/null || echo '—') $(node --version 2>/dev/null || echo 'NOT INSTALLED')"
+if command -v node &>/dev/null; then
+  nm=$(node -e "console.log(process.versions.node.split('.')[0])" 2>/dev/null)
+  say "node major:    $nm$([ "$nm" -lt 18 ] 2>/dev/null && echo ' (TOO OLD — requires 18+)')"
+fi
+say "npm:           $(command -v npm 2>/dev/null || echo '—') $(npm --version 2>/dev/null || echo 'NOT INSTALLED')"
+say "python3:       $(command -v python3 2>/dev/null || echo '—') $(python3 --version 2>&1 | awk '{print $2}' || echo 'NOT INSTALLED')"
+say "npx:           $(command -v npx 2>/dev/null || echo '—')"
+case "$PLATFORM" in
+  Darwin)
+    say "xcode-select:  $(xcode-select -p 2>/dev/null || echo 'NOT INSTALLED')"
+    ;;
+  Linux)
+    say "g++:           $(command -v g++ 2>/dev/null || echo '—') $(g++ -dumpversion 2>/dev/null || echo '')"
+    say "make:          $(command -v make 2>/dev/null || echo '—')"
+    ;;
+esac
+
+section "Editor CLIs"
+for pair in \
+  "code:/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" \
+  "code-insiders:/Applications/Visual Studio Code - Insiders.app/Contents/Resources/app/bin/code-insiders" \
+  "cursor:/Applications/Cursor.app/Contents/Resources/app/bin/cursor" \
+  "windsurf:/Applications/Windsurf.app/Contents/Resources/app/bin/windsurf"; do
+  label="${pair%%:*}"
+  bundled="${pair#*:}"
+  if command -v "$label" &>/dev/null; then
+    say "  ✓ $label  ($(command -v "$label")) — $("$label" --version 2>&1 | head -1)"
+  elif [ -x "$bundled" ]; then
+    say "  ✓ $label  (bundled: $bundled) — $("$bundled" --version 2>&1 | head -1)"
+  else
+    say "  — $label  not found"
+  fi
+done
+
+section "Claws source clone"
+if [ -d "$INSTALL_DIR/.git" ]; then
+  say "Exists:    $INSTALL_DIR"
+  say "HEAD:      $(cd "$INSTALL_DIR" && git log --oneline -1 2>/dev/null)"
+  say "Branch:    $(cd "$INSTALL_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+  say "Remote:    $(cd "$INSTALL_DIR" && git config --get remote.origin.url 2>/dev/null)"
+else
+  say "MISSING:   $INSTALL_DIR (no git clone — installer may have failed at step 1)"
+fi
+
+section "Extension manifest + bundle"
+if [ -f "$INSTALL_DIR/extension/package.json" ]; then
+  say "Version:   $(node -e "console.log(require('$INSTALL_DIR/extension/package.json').version)" 2>/dev/null)"
+  say "Main:      $(node -e "console.log(require('$INSTALL_DIR/extension/package.json').main)" 2>/dev/null)"
+  say "Bundle:    $([ -f "$INSTALL_DIR/extension/dist/extension.js" ] && wc -c < "$INSTALL_DIR/extension/dist/extension.js" | tr -d ' ' || echo 'MISSING')"
+  say "Build SHA: $(cat "$INSTALL_DIR/extension/dist/.build-sha" 2>/dev/null || echo 'unknown')"
+
+  # Detailed node-pty state: installed? binary built? against which ABI?
+  # The Electron version matters — a binary built against system Node
+  # loads from `node` fine but fails inside VS Code's extension host.
+  NPTY_DIR="$INSTALL_DIR/extension/node_modules/node-pty"
+  NPTY_BIN="$NPTY_DIR/build/Release/pty.node"
+  NPTY_ABI=$(cat "$INSTALL_DIR/extension/dist/.electron-abi" 2>/dev/null || echo "unknown")
+  if [ -f "$NPTY_BIN" ]; then
+    say "node-pty:  ✓ installed, binary present ($(wc -c < "$NPTY_BIN" | tr -d ' ') bytes)"
+    say "           built for Electron $NPTY_ABI"
+  elif [ -d "$NPTY_DIR" ]; then
+    say "node-pty:  ✗ installed but BINARY MISSING — extension in pipe-mode fallback"
+    say "           fix with: /claws-fix"
+  else
+    say "node-pty:  ✗ not installed — pipe-mode fallback active"
+  fi
+else
+  say "MISSING manifest at $INSTALL_DIR/extension/package.json"
+fi
+
+section "Editor extension symlinks"
+for dir in "$HOME/.vscode/extensions" "$HOME/.vscode-insiders/extensions" "$HOME/.cursor/extensions" "$HOME/.windsurf/extensions"; do
+  if [ -d "$dir" ]; then
+    matches=$(find "$dir" -maxdepth 1 -name 'neunaha.claws-*' 2>/dev/null)
+    if [ -n "$matches" ]; then
+      echo "$dir:" >> "$REPORT"
+      ls -la "$dir" 2>/dev/null | grep 'neunaha.claws' >> "$REPORT" 2>&1 || true
+    fi
+  fi
+done
+
+section "Project-local files"
+for f in .mcp.json .claws-bin/mcp_server.js .claws-bin/shell-hook.sh .vscode/extensions.json CLAUDE.md; do
+  if [ -e "$PROJECT_ROOT/$f" ]; then
+    say "  ✓ $f  ($(wc -c < "$PROJECT_ROOT/$f" | tr -d ' ') bytes)"
+  else
+    say "  ✗ $f  MISSING"
+  fi
+done
+# Confirm neunaha.claws is in the recommendations list specifically
+if [ -f "$PROJECT_ROOT/.vscode/extensions.json" ]; then
+  if grep -q "neunaha.claws" "$PROJECT_ROOT/.vscode/extensions.json" 2>/dev/null; then
+    say "  ✓ .vscode/extensions.json recommends neunaha.claws"
+  else
+    say "  ✗ .vscode/extensions.json MISSING claws recommendation"
+  fi
+fi
+for d in .claude/commands .claude/rules .claude/skills; do
+  if [ -d "$PROJECT_ROOT/$d" ]; then
+    count=$(find "$PROJECT_ROOT/$d" -type f 2>/dev/null | wc -l | tr -d ' ')
+    say "  ✓ $d/  ($count files)"
+  else
+    say "  ✗ $d/  MISSING"
+  fi
+done
+
+section "Socket state"
+SOCK_PATH="$PROJECT_ROOT/.claws/claws.sock"
+if [ -S "$SOCK_PATH" ]; then
+  say "Socket:    $SOCK_PATH"
+  say "Mtime:     $(stat -f '%Sm' "$SOCK_PATH" 2>/dev/null || stat -c '%y' "$SOCK_PATH" 2>/dev/null)"
+  if command -v nc &>/dev/null; then
+    if echo '{"id":1,"cmd":"list"}' | nc -U "$SOCK_PATH" 2>/dev/null | head -c 200 | grep -q '"ok"'; then
+      say "Status:    LIVE — extension is listening"
+    else
+      say "Status:    STALE — file exists but no process listening"
+    fi
+  fi
+else
+  say "Socket:    NOT PRESENT at $SOCK_PATH  (extension not activated in this project yet)"
+fi
+
+section "MCP server handshake test"
+MCP_PATH="$INSTALL_DIR/mcp_server.js"
+[ -f "$PROJECT_ROOT/.claws-bin/mcp_server.js" ] && MCP_PATH="$PROJECT_ROOT/.claws-bin/mcp_server.js"
+if command -v node &>/dev/null && [ -f "$MCP_PATH" ]; then
+  say "Testing:   $MCP_PATH"
+  HANDSHAKE=$(node --no-deprecation -e '
+const { spawn } = require("child_process");
+const mcp = spawn("node", [process.argv[1]], { stdio: ["pipe", "pipe", "ignore"] });
+const req = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} });
+const msg = `Content-Length: ${Buffer.byteLength(req)}\r\n\r\n${req}`;
+let buf = "";
+const done = (c, o) => { try { mcp.kill(); } catch {}; process.stdout.write(o); process.exit(c); };
+const timer = setTimeout(() => done(1, "TIMEOUT"), 4000);
+mcp.stdout.on("data", d => { buf += d.toString("utf8"); if (buf.includes("claws")) { clearTimeout(timer); done(0, buf.slice(0, 200)); } });
+mcp.on("error", e => { clearTimeout(timer); done(1, "SPAWN_ERROR: " + e.message); });
+mcp.stdin.write(msg);
+' "$MCP_PATH" 2>&1)
+  say "Response:  ${HANDSHAKE:0:300}"
+fi
+
+section "Shell hook state"
+for rc in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile"; do
+  if [ -f "$rc" ]; then
+    if grep -q "CLAWS terminal hook" "$rc" 2>/dev/null; then
+      say "  ✓ $(basename "$rc") — hook installed"
+    else
+      say "  ✗ $(basename "$rc") — hook NOT installed"
+    fi
+  fi
+done
+
+section "Latest install log"
+LATEST_LOG=$(ls -t /tmp/claws-install-*.log 2>/dev/null | head -1)
+if [ -n "$LATEST_LOG" ] && [ -f "$LATEST_LOG" ]; then
+  say "File:      $LATEST_LOG"
+  say "Last 100 lines:"
+  tail -100 "$LATEST_LOG" | redact >> "$REPORT"
+else
+  say "No recent install log found in /tmp/claws-install-*.log"
+fi
+
+section "VS Code extension host logs (claws only, last 50 matches)"
+LOGDIR=$(ls -dt "$HOME/Library/Application Support/Code/logs/"*/ 2>/dev/null | head -1)
+if [ -n "$LOGDIR" ] && [ -d "$LOGDIR" ]; then
+  say "From:      $LOGDIR"
+  grep -r "claws\|neunaha" "$LOGDIR" 2>/dev/null | tail -50 | redact >> "$REPORT" || say "(no claws references)"
+else
+  say "No VS Code logs found at ~/Library/Application Support/Code/logs/"
+fi
+
+section "Report location"
+echo "" >> "$REPORT"
+echo "Share this file in an issue: https://github.com/neunaha/claws/issues/new" >> "$REPORT"
+echo "File path: $REPORT" >> "$REPORT"
+
+# Print to stdout for the caller
+echo ""
+echo "╔════════════════════════════════════════════════════════╗"
+echo "║  Claws diagnostic report written to:                   ║"
+echo "╚════════════════════════════════════════════════════════╝"
+echo "  $REPORT"
+echo ""
+echo "Summary of checks:"
+grep -E '✓|✗|MISSING|STALE|LIVE|Status:' "$REPORT" | head -30 | sed 's/^/  /'
+echo ""
+echo "Next steps:"
+echo "  1. Open the report:    cat \"$REPORT\""
+echo "  2. Share it:           https://github.com/neunaha/claws/issues/new"
+echo "  3. Or paste contents into a new issue — HOMEDIR already redacted."