@venturewild/workspace 0.3.7 → 0.3.8

package/server/src/doctor.mjs

@@ -1,375 +1,375 @@
-// `wild-workspace doctor` — one pre/post-flight diagnostic for a real user's
-// machine. The riskiest moment for a brand-new (non-technical) user is the
-// install itself: no Claude yet, wrong Node, a busy port, a daemon binary that
-// didn't resolve, an unclaimed slug. When something breaks we need to SEE it —
-// ideally fix it — without making them feel stupid (docs/user-experience.md §5).
-//
-// runDoctor() returns a structured report (every check is { id, label, status,
-// detail, hint }); the CLI renders it with ✅/⚠️/❌ and the operator channel
-// serves the same JSON. Every external touch-point (agent detect, auth probe,
-// daemon resolve, port check, account load, service status, registry fetch) is
-// an injected seam so the test suite never spawns a process or hits the network.
-
-import os from 'node:os';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { buildConfig, APP_VERSION } from './config.mjs';
-import { detectAgents, pickDefaultAgent } from './agent.mjs';
-import { probeAgentReadiness } from './agent-readiness.mjs';
-import { resolveDaemonBinary, resolveDaemonVersion, expectedDaemonVersion } from './daemon-bin.mjs';
-import { checkPort } from './preview.mjs';
-import { loadAccount } from './account.mjs';
-import { serviceStatus } from './service.mjs';
-import { probeHealth, probeHealthVersion } from './supervisor.mjs';
-import { listLogs, diagnosticsDir, globalDir } from './logpaths.mjs';
-
-// The daemon version the currently-RUNNING daemon was spawned under — the marker
-// the supervisor writes to ~/.wild-workspace/daemon-runtime.json (the daemon's
-// own /health reports no version). null when unread (never started / no marker).
-function readRunningDaemonVersion(env = process.env) {
-  try {
-    const file = path.join(globalDir(env), 'daemon-runtime.json');
-    const v = JSON.parse(fs.readFileSync(file, 'utf8'))?.daemonVersion;
-    return typeof v === 'string' ? v : null;
-  } catch {
-    return null;
-  }
-}
-
-const STATUS_ICON = { ok: '✅', warn: '⚠️', fail: '❌', info: 'ℹ️' };
-
-// Native installer is Claude's canonical path today (npm i -g still works as a
-// fallback). Shown verbatim to the user, so keep it copy-pasteable.
-const CLAUDE_INSTALL_HINT =
-  'Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash  (Windows: irm https://claude.ai/install.ps1 | iex)';
-
-function nodeMajor(version = process.version) {
-  const m = /^v?(\d+)/.exec(String(version));
-  return m ? Number(m[1]) : 0;
-}
-
-// RC3: probe the LIVE public tunnel end-to-end — out to Cloudflare, through the
-// relay, down the daemon's tunnel, back to this server. This is the check the old
-// `doctor` lacked: it only resolved the slug in the registry (claimed in the DB),
-// which stays green even when `<slug>.venturewild.llc` is 502. A 200 here proves
-// the whole chain works; a 5xx/timeout is the exact RC2 "linked but unreachable".
-async function probeTunnel(slug, fetchImpl, timeoutMs = 8000) {
-  const url = `https://${encodeURIComponent(slug)}.venturewild.llc/api/health`;
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-  try {
-    const res = await fetchImpl(url, { signal: ctrl.signal, headers: { 'cache-control': 'no-cache' } });
-    let version = null;
-    try { version = (await res.json())?.version || null; } catch { /* non-JSON */ }
-    return { reachable: true, status: res.status, version, url };
-  } catch (e) {
-    return { reachable: false, error: String(e?.message || e), url };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-// Reach the bmo-sync registry: resolve the user's slug if linked, else /health.
-async function probeRegistry(config, fetchImpl) {
-  const base = String(config.bmoSyncServerUrl || '').replace(/\/$/, '');
-  const slug = config.account?.slug || null;
-  const url = slug
-    ? `${base}/api/slug/resolve/${encodeURIComponent(slug)}`
-    : `${base}/api/health`;
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), 5000);
-  try {
-    const res = await fetchImpl(url, { signal: ctrl.signal });
-    return { reachable: true, status: res.status, slug, url };
-  } catch (e) {
-    return { reachable: false, error: String(e?.message || e), slug, url };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/**
- * Run every diagnostic check. All deps are injectable for testing.
- * @returns {{version,generatedAt,platform,summary,checks,logs}}
- */
-export async function runDoctor(opts = {}, deps = {}) {
-  const config = opts.config || deps.config || buildConfig({});
-  const env = deps.env || process.env;
-  const d = {
-    detectAgents: deps.detectAgents || detectAgents,
-    probeReadiness: deps.probeAgentReadiness || probeAgentReadiness,
-    resolveDaemon: deps.resolveDaemonBinary || resolveDaemonBinary,
-    checkPort: deps.checkPort || checkPort,
-    loadAccount: deps.loadAccount || loadAccount,
-    serviceStatus: deps.serviceStatus || serviceStatus,
-    listLogs: deps.listLogs || listLogs,
-    fetchImpl: deps.fetchImpl || ((...a) => globalThis.fetch(...a)),
-    probeRunningVersion: deps.probeRunningVersion || probeHealthVersion,
-    daemonInstalledVersion: deps.daemonInstalledVersion || (() => resolveDaemonVersion({ env })),
-    daemonExpectedVersion: deps.daemonExpectedVersion || (() => expectedDaemonVersion()),
-    daemonRunningVersion: deps.daemonRunningVersion || (() => readRunningDaemonVersion(env)),
-  };
-  const checks = [];
-  const add = (c) => checks.push(c);
-  // Run a check body, capturing a thrown error as a non-fatal 'warn' so one bad
-  // check never aborts the whole report.
-  const guarded = async (id, label, body) => {
-    try {
-      add({ id, label, ...(await body()) });
-    } catch (e) {
-      add({ id, label, status: 'warn', detail: `check errored: ${String(e?.message || e)}`, hint: null });
-    }
-  };
-
-  // 1. Node runtime
-  await guarded('node', 'Node.js runtime', async () => {
-    const major = nodeMajor();
-    const detail = `${process.version} on ${os.platform()}-${os.arch()}`;
-    return major >= 18
-      ? { status: 'ok', detail, hint: null }
-      : { status: 'fail', detail, hint: 'Claude Code + wild-workspace need Node 18 or newer. Update Node, then retry.' };
-  });
-
-  // 2. Claude installed?
-  let claude = null;
-  await guarded('agent', 'Claude Code installed', async () => {
-    const agents = await d.detectAgents();
-    claude = (agents || []).find((a) => a.id === 'claude' && a.available) || null;
-    if (!claude) {
-      const fallback = pickDefaultAgent(agents || []);
-      if (fallback?.available) {
-        return { status: 'info', detail: `Claude not found; using ${fallback.label}.`, hint: null };
-      }
-      return { status: 'fail', detail: 'no `claude` on PATH', hint: CLAUDE_INSTALL_HINT };
-    }
-    return { status: 'ok', detail: claude.resolvedPath || claude.binary, hint: null };
-  });
-
-  // 3. Claude signed in AND able to run turns?
-  if (claude) {
-    await guarded('agentAuth', 'Claude ready to think', async () => {
-      const v = await d.probeReadiness(claude, undefined, env);
-      switch (v.status) {
-        case 'ready':
-          return { status: 'ok', detail: v.email ? `signed in as ${v.email}` : 'signed in', hint: null };
-        case 'subscribe':
-          return {
-            status: 'warn',
-            detail: v.email ? `signed in as ${v.email}, no active plan` : 'signed in, no active plan',
-            hint: 'Claude Code needs a Claude Pro plan (or higher). Subscribe at claude.ai, then retry.',
-          };
-        case 'login':
-          return { status: 'fail', detail: 'not signed in', hint: 'Run `claude auth login`, sign in, then retry.' };
-        case 'missing':
-          return { status: 'fail', detail: 'Claude not installed', hint: CLAUDE_INSTALL_HINT };
-        default:
-          return { status: 'info', detail: `readiness unknown (${v.status})`, hint: 'Will be confirmed on the first agent turn.' };
-      }
-    });
-  }
-
-  // 4. bmo-sync daemon binary resolvable?
-  await guarded('daemonBinary', 'Sync daemon binary', async () => {
-    const r = d.resolveDaemon({ env });
-    if (!r) {
-      return { status: 'fail', detail: 'WILD_WORKSPACE_DAEMON_BIN is set but the file is missing', hint: 'Unset it or point it at a real binary.' };
-    }
-    if (r.source === 'path') {
-      return {
-        status: 'warn',
-        detail: 'no bundled daemon found — relying on PATH; cross-device sync may be off',
-        hint: 'Reinstall: npm i -g @venturewild/workspace (pulls the daemon for your platform).',
-      };
-    }
-    return { status: 'ok', detail: `${r.path} (${r.source})`, hint: null };
-  });
-
-  // 4b. Daemon version drift (the go-live stale-process finding, Part 8). Three
-  // versions should agree: what the meta package PINS (expected), what's actually
-  // on disk (installed subpackage), and what the live daemon was spawned under
-  // (running marker). A mismatch is the exact "support channel silently 504s after
-  // an update" chain — the meta package updated but the daemon binary on disk
-  // lagged, or the daemon kept running old code. Surfaced so the fix (reinstall /
-  // restart) is obvious instead of invisible.
-  await guarded('daemonVersion', 'Sync daemon version', async () => {
-    const expected = d.daemonExpectedVersion();
-    const installed = d.daemonInstalledVersion();
-    const running = d.daemonRunningVersion();
-    const bits = [`pinned=${expected || '?'}`, `installed=${installed || 'PATH/vendor'}`, `running=${running || 'not started'}`];
-    const detail = bits.join(' ');
-    // Meta pins a version but the on-disk daemon subpackage is a DIFFERENT one →
-    // `npm i -g` didn't refresh the optionalDependency (the Windows dev box lag).
-    if (expected && installed && expected !== installed) {
-      return {
-        status: 'warn',
-        detail,
-        hint: `The daemon on disk (${installed}) does not match what this version pins (${expected}). Reinstall to refresh it: npm i -g @venturewild/workspace@latest`,
-      };
-    }
-    // The live daemon is running an older binary than what's installed → it needs
-    // a recycle (the always-on supervisor does this on its next tick).
-    if (installed && running && installed !== running) {
-      return {
-        status: 'warn',
-        detail,
-        hint: `The running daemon (${running}) is older than installed (${installed}). Always-on recycles it automatically; or restart sync (\`wild-workspace daemon stop\` then \`wild-workspace\`).`,
-      };
-    }
-    if (!installed) {
-      // PATH/vendor resolution — can't compare versions; the daemonBinary check
-      // above already warns about the missing bundled binary.
-      return { status: 'info', detail, hint: null };
-    }
-    return { status: 'ok', detail, hint: null };
-  });
-
-  // 5. Workspace port
-  await guarded('port', `Workspace port :${config.port}`, async () => {
-    const inUse = await d.checkPort(config.port);
-    return inUse
-      ? { status: 'info', detail: 'in use — your workspace is likely already running (or another app holds it)', hint: null }
-      : { status: 'ok', detail: 'free', hint: null };
-  });
-
-  // 5b. Running server version vs installed (RC3). `doctor` runs as the
-  // freshly-invoked CLI, so APP_VERSION here == the version installed on disk.
-  // If a server is answering :port with a DIFFERENT version, it's running stale
-  // code from before the last upgrade — the "kept running 0.1.14 after 0.2.1"
-  // failure. Surface it so the fix (restart) is obvious instead of invisible.
-  await guarded('runningVersion', 'Running version', async () => {
-    const running = await d.probeRunningVersion(config.port);
-    if (!running) {
-      return { status: 'info', detail: `no server answering :${config.port} (not started yet)`, hint: null };
-    }
-    if (running === APP_VERSION) {
-      return { status: 'ok', detail: `v${running} (matches installed)`, hint: null };
-    }
-    return {
-      status: 'warn',
-      detail: `running v${running}, but v${APP_VERSION} is installed`,
-      hint: 'A workspace server is running older code than what is installed. Restart it (close the app — always-on restarts it clean) to finish the upgrade.',
-    };
-  });
-
-  // 6. Account linked (slug)
-  let account = null;
-  await guarded('account', 'Workspace account linked', async () => {
-    account = d.loadAccount(config.dataDir);
-    if (account?.slug) {
-      return { status: 'ok', detail: `${account.slug} (${account.email || 'no email'}) → https://${account.slug}.venturewild.llc`, hint: null };
-    }
-    return { status: 'warn', detail: 'not linked yet', hint: 'Run `wild-workspace login <blob>` with the code from workspace.venturewild.llc.' };
-  });
-
-  // 7. Registry reachable + slug status
-  await guarded('registry', 'Sync server reachable', async () => {
-    const r = await probeRegistry({ ...config, account: account || config.account }, d.fetchImpl);
-    if (!r.reachable) {
-      return { status: 'fail', detail: `can't reach ${r.url}: ${r.error}`, hint: 'Check the internet connection, then retry.' };
-    }
-    if (r.slug) {
-      if (r.status === 200) return { status: 'ok', detail: `slug "${r.slug}" is claimed`, hint: null };
-      if (r.status === 404) return { status: 'warn', detail: `slug "${r.slug}" is not claimed on the server`, hint: 'Re-run the claim, or `wild-workspace login` with a fresh blob.' };
-      return { status: 'warn', detail: `slug resolve returned HTTP ${r.status}`, hint: null };
-    }
-    return r.status < 500
-      ? { status: 'ok', detail: `reachable (HTTP ${r.status})`, hint: null }
-      : { status: 'warn', detail: `server returned HTTP ${r.status}`, hint: null };
-  });
-
-  // 7b. Public URL reachable end-to-end (RC3). Only meaningful once linked. This
-  // is the half the old doctor was blind to — the registry check above can be
-  // green (slug claimed) while this is red (tunnel down). Together they tell the
-  // two apart: claimed-but-unreachable ⟹ the daemon link is broken (RC2), the
-  // operator/auto-relink path is the fix.
-  await guarded('tunnel', 'Public URL reachable', async () => {
-    const slug = account?.slug || config.account?.slug || null;
-    if (!slug) {
-      return { status: 'info', detail: 'not linked — no public URL yet', hint: null };
-    }
-    const r = await probeTunnel(slug, d.fetchImpl);
-    if (!r.reachable) {
-      return {
-        status: 'fail',
-        detail: `${r.url} unreachable: ${r.error}`,
-        hint: 'The public link is down. Restart sync (`wild-workspace daemon stop` then `wild-workspace`), or the operator `relink-account` fix.',
-      };
-    }
-    if (r.status >= 500) {
-      return {
-        status: 'fail',
-        detail: `${r.url} returned HTTP ${r.status} (tunnel down — slug claimed but not linked)`,
-        hint: 'The daemon is not linked to the relay. Restart sync (`wild-workspace daemon stop` then `wild-workspace`).',
-      };
-    }
-    if (r.status >= 400) {
-      // 401/403/404 = the chain works; auth/slug is the nuance, not a tunnel fault.
-      return { status: 'warn', detail: `reachable but HTTP ${r.status} (auth/slug check)`, hint: null };
-    }
-    return { status: 'ok', detail: `live (HTTP ${r.status}${r.version ? `, v${r.version}` : ''})`, hint: null };
-  });
-
-  // 8. Always-on / autostart
-  await guarded('service', 'Always-on (autostart)', async () => {
-    const s = await d.serviceStatus({ port: config.port }, { probeImpl: (p) => probeHealth(p) });
-    if (s.supported === false) {
-      return { status: 'info', detail: `not yet on ${s.platform} — run \`wild-workspace\` to start it`, hint: null };
-    }
-    const bits = [`installed=${s.installed ? 'yes' : 'no'}`, `supervisor=${s.supervisorAlive ? 'up' : 'down'}`, `server=${s.serverUp ? 'up' : 'down'}`];
-    return { status: s.installed ? 'ok' : 'info', detail: bits.join(' '), hint: s.installed ? null : 'Enable with `wild-workspace service install`.' };
-  });
-
-  const logs = d.listLogs(env);
-  const summary = checks.reduce(
-    (acc, c) => ((acc[c.status] = (acc[c.status] || 0) + 1), acc),
-    { ok: 0, warn: 0, fail: 0, info: 0 },
-  );
-
-  return {
-    version: APP_VERSION,
-    generatedAt: new Date().toISOString(),
-    platform: `${os.platform()}-${os.arch()}`,
-    summary,
-    checks,
-    logs,
-  };
-}
-
-// Render a report to a human string (used by the CLI). The operator channel
-// sends the JSON instead.
-export function renderDoctor(report) {
-  const lines = [];
-  lines.push(`wild-workspace doctor — v${report.version}  (${report.platform})`);
-  lines.push('');
-  for (const c of report.checks) {
-    lines.push(`${STATUS_ICON[c.status] || '•'}  ${c.label}: ${c.detail}`);
-    if (c.hint && (c.status === 'fail' || c.status === 'warn')) {
-      lines.push(`      → ${c.hint}`);
-    }
-  }
-  lines.push('');
-  const { ok, warn, fail } = report.summary;
-  lines.push(`Summary: ${ok} ok · ${warn} warning${warn === 1 ? '' : 's'} · ${fail} problem${fail === 1 ? '' : 's'}`);
-  lines.push('');
-  lines.push('Logs:');
-  for (const l of report.logs) {
-    lines.push(`  ${l.exists ? '·' : ' '} ${l.name.padEnd(10)} ${l.file}${l.exists ? ` (${l.size} bytes)` : ' (none yet)'}`);
-  }
-  return lines.join('\n');
-}
-
-// Persist the JSON report under ~/.wild-workspace/diagnostics/. Returns the
-// file path (or null if it couldn't be written). Best-effort.
-export function writeDoctorBundle(report, env = process.env) {
-  try {
-    const dir = diagnosticsDir(env);
-    fs.mkdirSync(dir, { recursive: true });
-    const stamp = report.generatedAt.replace(/[:.]/g, '-');
-    const file = path.join(dir, `doctor-${stamp}.json`);
-    fs.writeFileSync(file, JSON.stringify(report, null, 2));
-    return file;
-  } catch {
-    return null;
-  }
-}
+// `wild-workspace doctor` — one pre/post-flight diagnostic for a real user's
+// machine. The riskiest moment for a brand-new (non-technical) user is the
+// install itself: no Claude yet, wrong Node, a busy port, a daemon binary that
+// didn't resolve, an unclaimed slug. When something breaks we need to SEE it —
+// ideally fix it — without making them feel stupid (docs/user-experience.md §5).
+//
+// runDoctor() returns a structured report (every check is { id, label, status,
+// detail, hint }); the CLI renders it with ✅/⚠️/❌ and the operator channel
+// serves the same JSON. Every external touch-point (agent detect, auth probe,
+// daemon resolve, port check, account load, service status, registry fetch) is
+// an injected seam so the test suite never spawns a process or hits the network.
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { buildConfig, APP_VERSION } from './config.mjs';
+import { detectAgents, pickDefaultAgent } from './agent.mjs';
+import { probeAgentReadiness } from './agent-readiness.mjs';
+import { resolveDaemonBinary, resolveDaemonVersion, expectedDaemonVersion } from './daemon-bin.mjs';
+import { checkPort } from './preview.mjs';
+import { loadAccount } from './account.mjs';
+import { serviceStatus } from './service.mjs';
+import { probeHealth, probeHealthVersion } from './supervisor.mjs';
+import { listLogs, diagnosticsDir, globalDir } from './logpaths.mjs';
+
+// The daemon version the currently-RUNNING daemon was spawned under — the marker
+// the supervisor writes to ~/.wild-workspace/daemon-runtime.json (the daemon's
+// own /health reports no version). null when unread (never started / no marker).
+function readRunningDaemonVersion(env = process.env) {
+  try {
+    const file = path.join(globalDir(env), 'daemon-runtime.json');
+    const v = JSON.parse(fs.readFileSync(file, 'utf8'))?.daemonVersion;
+    return typeof v === 'string' ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+const STATUS_ICON = { ok: '✅', warn: '⚠️', fail: '❌', info: 'ℹ️' };
+
+// Native installer is Claude's canonical path today (npm i -g still works as a
+// fallback). Shown verbatim to the user, so keep it copy-pasteable.
+const CLAUDE_INSTALL_HINT =
+  'Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash  (Windows: irm https://claude.ai/install.ps1 | iex)';
+
+function nodeMajor(version = process.version) {
+  const m = /^v?(\d+)/.exec(String(version));
+  return m ? Number(m[1]) : 0;
+}
+
+// RC3: probe the LIVE public tunnel end-to-end — out to Cloudflare, through the
+// relay, down the daemon's tunnel, back to this server. This is the check the old
+// `doctor` lacked: it only resolved the slug in the registry (claimed in the DB),
+// which stays green even when `<slug>.venturewild.llc` is 502. A 200 here proves
+// the whole chain works; a 5xx/timeout is the exact RC2 "linked but unreachable".
+async function probeTunnel(slug, fetchImpl, timeoutMs = 8000) {
+  const url = `https://${encodeURIComponent(slug)}.venturewild.llc/api/health`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal, headers: { 'cache-control': 'no-cache' } });
+    let version = null;
+    try { version = (await res.json())?.version || null; } catch { /* non-JSON */ }
+    return { reachable: true, status: res.status, version, url };
+  } catch (e) {
+    return { reachable: false, error: String(e?.message || e), url };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Reach the bmo-sync registry: resolve the user's slug if linked, else /health.
+async function probeRegistry(config, fetchImpl) {
+  const base = String(config.bmoSyncServerUrl || '').replace(/\/$/, '');
+  const slug = config.account?.slug || null;
+  const url = slug
+    ? `${base}/api/slug/resolve/${encodeURIComponent(slug)}`
+    : `${base}/api/health`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 5000);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal });
+    return { reachable: true, status: res.status, slug, url };
+  } catch (e) {
+    return { reachable: false, error: String(e?.message || e), slug, url };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run every diagnostic check. All deps are injectable for testing.
+ * @returns {{version,generatedAt,platform,summary,checks,logs}}
+ */
+export async function runDoctor(opts = {}, deps = {}) {
+  const config = opts.config || deps.config || buildConfig({});
+  const env = deps.env || process.env;
+  const d = {
+    detectAgents: deps.detectAgents || detectAgents,
+    probeReadiness: deps.probeAgentReadiness || probeAgentReadiness,
+    resolveDaemon: deps.resolveDaemonBinary || resolveDaemonBinary,
+    checkPort: deps.checkPort || checkPort,
+    loadAccount: deps.loadAccount || loadAccount,
+    serviceStatus: deps.serviceStatus || serviceStatus,
+    listLogs: deps.listLogs || listLogs,
+    fetchImpl: deps.fetchImpl || ((...a) => globalThis.fetch(...a)),
+    probeRunningVersion: deps.probeRunningVersion || probeHealthVersion,
+    daemonInstalledVersion: deps.daemonInstalledVersion || (() => resolveDaemonVersion({ env })),
+    daemonExpectedVersion: deps.daemonExpectedVersion || (() => expectedDaemonVersion()),
+    daemonRunningVersion: deps.daemonRunningVersion || (() => readRunningDaemonVersion(env)),
+  };
+  const checks = [];
+  const add = (c) => checks.push(c);
+  // Run a check body, capturing a thrown error as a non-fatal 'warn' so one bad
+  // check never aborts the whole report.
+  const guarded = async (id, label, body) => {
+    try {
+      add({ id, label, ...(await body()) });
+    } catch (e) {
+      add({ id, label, status: 'warn', detail: `check errored: ${String(e?.message || e)}`, hint: null });
+    }
+  };
+
+  // 1. Node runtime
+  await guarded('node', 'Node.js runtime', async () => {
+    const major = nodeMajor();
+    const detail = `${process.version} on ${os.platform()}-${os.arch()}`;
+    return major >= 18
+      ? { status: 'ok', detail, hint: null }
+      : { status: 'fail', detail, hint: 'Claude Code + wild-workspace need Node 18 or newer. Update Node, then retry.' };
+  });
+
+  // 2. Claude installed?
+  let claude = null;
+  await guarded('agent', 'Claude Code installed', async () => {
+    const agents = await d.detectAgents();
+    claude = (agents || []).find((a) => a.id === 'claude' && a.available) || null;
+    if (!claude) {
+      const fallback = pickDefaultAgent(agents || []);
+      if (fallback?.available) {
+        return { status: 'info', detail: `Claude not found; using ${fallback.label}.`, hint: null };
+      }
+      return { status: 'fail', detail: 'no `claude` on PATH', hint: CLAUDE_INSTALL_HINT };
+    }
+    return { status: 'ok', detail: claude.resolvedPath || claude.binary, hint: null };
+  });
+
+  // 3. Claude signed in AND able to run turns?
+  if (claude) {
+    await guarded('agentAuth', 'Claude ready to think', async () => {
+      const v = await d.probeReadiness(claude, undefined, env);
+      switch (v.status) {
+        case 'ready':
+          return { status: 'ok', detail: v.email ? `signed in as ${v.email}` : 'signed in', hint: null };
+        case 'subscribe':
+          return {
+            status: 'warn',
+            detail: v.email ? `signed in as ${v.email}, no active plan` : 'signed in, no active plan',
+            hint: 'Claude Code needs a Claude Pro plan (or higher). Subscribe at claude.ai, then retry.',
+          };
+        case 'login':
+          return { status: 'fail', detail: 'not signed in', hint: 'Run `claude auth login`, sign in, then retry.' };
+        case 'missing':
+          return { status: 'fail', detail: 'Claude not installed', hint: CLAUDE_INSTALL_HINT };
+        default:
+          return { status: 'info', detail: `readiness unknown (${v.status})`, hint: 'Will be confirmed on the first agent turn.' };
+      }
+    });
+  }
+
+  // 4. bmo-sync daemon binary resolvable?
+  await guarded('daemonBinary', 'Sync daemon binary', async () => {
+    const r = d.resolveDaemon({ env });
+    if (!r) {
+      return { status: 'fail', detail: 'WILD_WORKSPACE_DAEMON_BIN is set but the file is missing', hint: 'Unset it or point it at a real binary.' };
+    }
+    if (r.source === 'path') {
+      return {
+        status: 'warn',
+        detail: 'no bundled daemon found — relying on PATH; cross-device sync may be off',
+        hint: 'Reinstall: npm i -g @venturewild/workspace (pulls the daemon for your platform).',
+      };
+    }
+    return { status: 'ok', detail: `${r.path} (${r.source})`, hint: null };
+  });
+
+  // 4b. Daemon version drift (the go-live stale-process finding, Part 8). Three
+  // versions should agree: what the meta package PINS (expected), what's actually
+  // on disk (installed subpackage), and what the live daemon was spawned under
+  // (running marker). A mismatch is the exact "support channel silently 504s after
+  // an update" chain — the meta package updated but the daemon binary on disk
+  // lagged, or the daemon kept running old code. Surfaced so the fix (reinstall /
+  // restart) is obvious instead of invisible.
+  await guarded('daemonVersion', 'Sync daemon version', async () => {
+    const expected = d.daemonExpectedVersion();
+    const installed = d.daemonInstalledVersion();
+    const running = d.daemonRunningVersion();
+    const bits = [`pinned=${expected || '?'}`, `installed=${installed || 'PATH/vendor'}`, `running=${running || 'not started'}`];
+    const detail = bits.join(' ');
+    // Meta pins a version but the on-disk daemon subpackage is a DIFFERENT one →
+    // `npm i -g` didn't refresh the optionalDependency (the Windows dev box lag).
+    if (expected && installed && expected !== installed) {
+      return {
+        status: 'warn',
+        detail,
+        hint: `The daemon on disk (${installed}) does not match what this version pins (${expected}). Reinstall to refresh it: npm i -g @venturewild/workspace@latest`,
+      };
+    }
+    // The live daemon is running an older binary than what's installed → it needs
+    // a recycle (the always-on supervisor does this on its next tick).
+    if (installed && running && installed !== running) {
+      return {
+        status: 'warn',
+        detail,
+        hint: `The running daemon (${running}) is older than installed (${installed}). Always-on recycles it automatically; or restart sync (\`wild-workspace daemon stop\` then \`wild-workspace\`).`,
+      };
+    }
+    if (!installed) {
+      // PATH/vendor resolution — can't compare versions; the daemonBinary check
+      // above already warns about the missing bundled binary.
+      return { status: 'info', detail, hint: null };
+    }
+    return { status: 'ok', detail, hint: null };
+  });
+
+  // 5. Workspace port
+  await guarded('port', `Workspace port :${config.port}`, async () => {
+    const inUse = await d.checkPort(config.port);
+    return inUse
+      ? { status: 'info', detail: 'in use — your workspace is likely already running (or another app holds it)', hint: null }
+      : { status: 'ok', detail: 'free', hint: null };
+  });
+
+  // 5b. Running server version vs installed (RC3). `doctor` runs as the
+  // freshly-invoked CLI, so APP_VERSION here == the version installed on disk.
+  // If a server is answering :port with a DIFFERENT version, it's running stale
+  // code from before the last upgrade — the "kept running 0.1.14 after 0.2.1"
+  // failure. Surface it so the fix (restart) is obvious instead of invisible.
+  await guarded('runningVersion', 'Running version', async () => {
+    const running = await d.probeRunningVersion(config.port);
+    if (!running) {
+      return { status: 'info', detail: `no server answering :${config.port} (not started yet)`, hint: null };
+    }
+    if (running === APP_VERSION) {
+      return { status: 'ok', detail: `v${running} (matches installed)`, hint: null };
+    }
+    return {
+      status: 'warn',
+      detail: `running v${running}, but v${APP_VERSION} is installed`,
+      hint: 'A workspace server is running older code than what is installed. Restart it (close the app — always-on restarts it clean) to finish the upgrade.',
+    };
+  });
+
+  // 6. Account linked (slug)
+  let account = null;
+  await guarded('account', 'Workspace account linked', async () => {
+    account = d.loadAccount(config.dataDir);
+    if (account?.slug) {
+      return { status: 'ok', detail: `${account.slug} (${account.email || 'no email'}) → https://${account.slug}.venturewild.llc`, hint: null };
+    }
+    return { status: 'warn', detail: 'not linked yet', hint: 'Run `wild-workspace login <blob>` with the code from workspace.venturewild.llc.' };
+  });
+
+  // 7. Registry reachable + slug status
+  await guarded('registry', 'Sync server reachable', async () => {
+    const r = await probeRegistry({ ...config, account: account || config.account }, d.fetchImpl);
+    if (!r.reachable) {
+      return { status: 'fail', detail: `can't reach ${r.url}: ${r.error}`, hint: 'Check the internet connection, then retry.' };
+    }
+    if (r.slug) {
+      if (r.status === 200) return { status: 'ok', detail: `slug "${r.slug}" is claimed`, hint: null };
+      if (r.status === 404) return { status: 'warn', detail: `slug "${r.slug}" is not claimed on the server`, hint: 'Re-run the claim, or `wild-workspace login` with a fresh blob.' };
+      return { status: 'warn', detail: `slug resolve returned HTTP ${r.status}`, hint: null };
+    }
+    return r.status < 500
+      ? { status: 'ok', detail: `reachable (HTTP ${r.status})`, hint: null }
+      : { status: 'warn', detail: `server returned HTTP ${r.status}`, hint: null };
+  });
+
+  // 7b. Public URL reachable end-to-end (RC3). Only meaningful once linked. This
+  // is the half the old doctor was blind to — the registry check above can be
+  // green (slug claimed) while this is red (tunnel down). Together they tell the
+  // two apart: claimed-but-unreachable ⟹ the daemon link is broken (RC2), the
+  // operator/auto-relink path is the fix.
+  await guarded('tunnel', 'Public URL reachable', async () => {
+    const slug = account?.slug || config.account?.slug || null;
+    if (!slug) {
+      return { status: 'info', detail: 'not linked — no public URL yet', hint: null };
+    }
+    const r = await probeTunnel(slug, d.fetchImpl);
+    if (!r.reachable) {
+      return {
+        status: 'fail',
+        detail: `${r.url} unreachable: ${r.error}`,
+        hint: 'The public link is down. Restart sync (`wild-workspace daemon stop` then `wild-workspace`), or the operator `relink-account` fix.',
+      };
+    }
+    if (r.status >= 500) {
+      return {
+        status: 'fail',
+        detail: `${r.url} returned HTTP ${r.status} (tunnel down — slug claimed but not linked)`,
+        hint: 'The daemon is not linked to the relay. Restart sync (`wild-workspace daemon stop` then `wild-workspace`).',
+      };
+    }
+    if (r.status >= 400) {
+      // 401/403/404 = the chain works; auth/slug is the nuance, not a tunnel fault.
+      return { status: 'warn', detail: `reachable but HTTP ${r.status} (auth/slug check)`, hint: null };
+    }
+    return { status: 'ok', detail: `live (HTTP ${r.status}${r.version ? `, v${r.version}` : ''})`, hint: null };
+  });
+
+  // 8. Always-on / autostart
+  await guarded('service', 'Always-on (autostart)', async () => {
+    const s = await d.serviceStatus({ port: config.port }, { probeImpl: (p) => probeHealth(p) });
+    if (s.supported === false) {
+      return { status: 'info', detail: `not yet on ${s.platform} — run \`wild-workspace\` to start it`, hint: null };
+    }
+    const bits = [`installed=${s.installed ? 'yes' : 'no'}`, `supervisor=${s.supervisorAlive ? 'up' : 'down'}`, `server=${s.serverUp ? 'up' : 'down'}`];
+    return { status: s.installed ? 'ok' : 'info', detail: bits.join(' '), hint: s.installed ? null : 'Enable with `wild-workspace service install`.' };
+  });
+
+  const logs = d.listLogs(env);
+  const summary = checks.reduce(
+    (acc, c) => ((acc[c.status] = (acc[c.status] || 0) + 1), acc),
+    { ok: 0, warn: 0, fail: 0, info: 0 },
+  );
+
+  return {
+    version: APP_VERSION,
+    generatedAt: new Date().toISOString(),
+    platform: `${os.platform()}-${os.arch()}`,
+    summary,
+    checks,
+    logs,
+  };
+}
+
+// Render a report to a human string (used by the CLI). The operator channel
+// sends the JSON instead.
+export function renderDoctor(report) {
+  const lines = [];
+  lines.push(`wild-workspace doctor — v${report.version}  (${report.platform})`);
+  lines.push('');
+  for (const c of report.checks) {
+    lines.push(`${STATUS_ICON[c.status] || '•'}  ${c.label}: ${c.detail}`);
+    if (c.hint && (c.status === 'fail' || c.status === 'warn')) {
+      lines.push(`      → ${c.hint}`);
+    }
+  }
+  lines.push('');
+  const { ok, warn, fail } = report.summary;
+  lines.push(`Summary: ${ok} ok · ${warn} warning${warn === 1 ? '' : 's'} · ${fail} problem${fail === 1 ? '' : 's'}`);
+  lines.push('');
+  lines.push('Logs:');
+  for (const l of report.logs) {
+    lines.push(`  ${l.exists ? '·' : ' '} ${l.name.padEnd(10)} ${l.file}${l.exists ? ` (${l.size} bytes)` : ' (none yet)'}`);
+  }
+  return lines.join('\n');
+}
+
+// Persist the JSON report under ~/.wild-workspace/diagnostics/. Returns the
+// file path (or null if it couldn't be written). Best-effort.
+export function writeDoctorBundle(report, env = process.env) {
+  try {
+    const dir = diagnosticsDir(env);
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = report.generatedAt.replace(/[:.]/g, '-');
+    const file = path.join(dir, `doctor-${stamp}.json`);
+    fs.writeFileSync(file, JSON.stringify(report, null, 2));
+    return file;
+  } catch {
+    return null;
+  }
+}