@empirical-gauzza/cli 1.0.19 → 1.0.20

package/lib/doctor.js

@@ -1,116 +1,484 @@
-'use strict';
-
-const { log, warn, ANSI, colorize, supportsColor } = require('./ui');
-const { httpJson } = require('./http');
-const { parseOption } = require('./env');
-const { resolveAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
-const { withCliAnalyticsContext } = require('./memoryCommands');
-
-async function runDoctor(args) {
-  return withCliAnalyticsContext({ command: 'doctor' }, async () => {
-    const outputJson = parseOption(args, '--output', '') === 'json';
-    const checks = [];
-    let overallFail = false;
-    let overallWarn = false;
-
-    function addCheck(name, status, message) {
-      checks.push({ name, status, message });
-      if (status === 'fail') overallFail = true;
-      if (status === 'warn') overallWarn = true;
-    }
-
-    const token = resolveAccessToken();
-    if (!token) {
-      addCheck('token_presence', 'fail', 'No access token found. Run: empirical auth login, or configure headless credentials with empirical oauth bootstrap headless.');
-    } else {
-      addCheck('token_presence', 'ok', 'Access token found.');
-    }
-
-    let tokenType = null;
-    if (token) {
-      const parts = token.split('.');
-      if (parts.length === 3) {
-        tokenType = 'jwt';
-        addCheck('token_type', 'ok', 'Token is a JWT (3-part).');
-      } else {
-        tokenType = 'apikey';
-        addCheck('token_type', 'ok', 'Token is an API key (long alphanumeric).');
-      }
-    } else {
-      addCheck('token_type', 'fail', 'Cannot determine token type — no token found.');
-    }
-
-    if (token && tokenType === 'jwt') {
-      const parts = token.split('.');
-      try {
-        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
-        if (payload && typeof payload.exp === 'number') {
-          const nowSec = Math.floor(Date.now() / 1000);
-          if (payload.exp < nowSec) {
-            addCheck('token_expiry', 'fail', `Token expired at ${new Date(payload.exp * 1000).toISOString()}.`);
-          } else {
-            const remaining = payload.exp - nowSec;
-            addCheck('token_expiry', 'ok', `Token expires in ${remaining}s (at ${new Date(payload.exp * 1000).toISOString()}).`);
-          }
-        } else {
-          addCheck('token_expiry', 'warn', 'JWT has no `exp` claim — expiry unknown.');
-        }
-      } catch (_error) {
-        addCheck('token_expiry', 'warn', 'Could not decode JWT payload — expiry unknown.');
-      }
-    } else if (token && tokenType === 'apikey') {
-      addCheck('token_expiry', 'ok', 'API key — no expiry.');
-    }
-
-    let userData = null;
-    if (token) {
-      const baseUrl = resolveApiBaseUrl();
-      const meUrl = new URL('/api/v1/users/me', baseUrl).toString();
-      try {
-        const response = await httpJson(meUrl, 'GET', null, buildApiAuthHeaders(token));
-        userData = (response && response.data) ? response.data : response;
-        addCheck('api_connectivity', 'ok', `Connected. User: ${userData.email || userData.userId || 'unknown'}.`);
-      } catch (error) {
-        addCheck('api_connectivity', 'fail', `API request failed: ${error.message}`);
-      }
-    } else {
-      addCheck('api_connectivity', 'fail', 'Skipped — no token available.');
-    }
-
-    if (userData) {
-      const wsId = userData.workspaceId || userData.workspaceName || null;
-      if (wsId) {
-        addCheck('workspace', 'ok', `Workspace ID: ${wsId}.`);
-      } else {
-        addCheck('workspace', 'warn', 'No active workspace — using default brain.');
-      }
-    } else {
-      addCheck('workspace', 'fail', 'Skipped — API connectivity check failed.');
-    }
-
-    const overall = overallFail ? 'fail' : (overallWarn ? 'warn' : 'ok');
-
-    if (outputJson) {
-      log(JSON.stringify({ checks, overall }));
-    } else {
-      const statusLabel = (status) => {
-        if (status === 'ok') return colorize(ANSI.green, '[OK]  ');
-        if (status === 'warn') return colorize(ANSI.yellow, '[WARN]');
-        return colorize(ANSI.red, '[FAIL]');
-      };
-      for (const check of checks) {
-        log(`${statusLabel(check.status)} ${check.name.padEnd(20)} ${check.message}`);
-      }
-      log('');
-      log(`Overall: ${overall.toUpperCase()}`);
-    }
-
-    if (overallFail) {
-      process.exitCode = 1;
-    }
-  });
-}
-
-module.exports = {
-  runDoctor
-};
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log, warn, ANSI, colorize, supportsColor } = require('./ui');
+const { httpJson } = require('./http');
+const { parseOption, parseFlag } = require('./env');
+const { readJsonIfExists, readUtf8IfExists } = require('./fsUtils');
+const { resolveAccessToken, resolveApiBaseUrl, buildApiAuthHeaders, inspectToken } = require('./auth');
+const { withCliAnalyticsContext } = require('./memoryCommands');
+const { EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_URL, MEMORY_CATEGORIES } = require('./constants');
+const { detectInstallTargets } = require('./installers/detect');
+const { readInstalledVersions } = require('./pluginUpdateCheck');
+const { CORE_PLUGIN_NAME, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
+const { getEmpiricalHooksDir, getCodexHooksScriptsDir, getCodexHomeDir } = require('./installers/hooks');
+
+// ─── Host MCP config registration ─────────────────────────────────────────────
+// Each host stores "is the Empirical MCP server registered" in a different shape and location.
+// This mirrors what each installers/*.js file actually writes, so doctor can catch drift (a
+// stale/removed entry, a URL that no longer matches EMPIRICAL_MCP_URL) without shelling out to
+// the host CLI itself.
+
+function checkClaudeMcpConfig() {
+  const configPath = path.join(os.homedir(), '.claude.json');
+  const config = readJsonIfExists(configPath);
+  if (!config) {
+    return { ok: false, message: `No Claude config found at ${configPath}. Run: empirical install.` };
+  }
+  const entry = config.mcpServers && config.mcpServers[EMPIRICAL_MCP_NAME];
+  if (!entry) {
+    return {
+      ok: false,
+      message: `Empirical MCP server not registered in ${configPath}. Run: empirical install (or claude mcp add --scope user --transport http ${EMPIRICAL_MCP_NAME} ${EMPIRICAL_MCP_URL}).`
+    };
+  }
+  if (entry.url && entry.url !== EMPIRICAL_MCP_URL) {
+    return {
+      ok: false,
+      message: `Registered Claude MCP URL (${entry.url}) does not match the current endpoint (${EMPIRICAL_MCP_URL}). Run: empirical install to re-register.`
+    };
+  }
+  return { ok: true, message: `Registered in ${configPath} (url: ${entry.url || EMPIRICAL_MCP_URL}).` };
+}
+
+function checkCopilotMcpConfig() {
+  const configPath = path.join(os.homedir(), '.copilot', 'mcp-config.json');
+  const config = readJsonIfExists(configPath);
+  if (!config) {
+    return { ok: false, message: `No Copilot MCP config found at ${configPath}. Run: empirical install.` };
+  }
+  const entry = config.mcpServers && config.mcpServers[EMPIRICAL_MCP_NAME];
+  if (!entry) {
+    return {
+      ok: false,
+      message: `Empirical MCP server not registered in ${configPath}. Run: empirical install.`
+    };
+  }
+  if (entry.url && entry.url !== EMPIRICAL_MCP_URL) {
+    return {
+      ok: false,
+      message: `Registered Copilot MCP URL (${entry.url}) does not match the current endpoint (${EMPIRICAL_MCP_URL}). Run: empirical install to re-register.`
+    };
+  }
+  return { ok: true, message: `Registered in ${configPath} (url: ${entry.url || EMPIRICAL_MCP_URL}).` };
+}
+
+// Codex stores MCP servers in <CODEX_HOME>/config.toml as [mcp_servers.<name>] TOML tables.
+// There is no TOML dependency in this package, so this reads the section as text: find the
+// [mcp_servers.empirical] header, take everything up to the next top-level "[" header, and
+// regex out its url = "..." value. Good enough to detect presence/URL drift without a full parser.
+function checkCodexMcpConfig() {
+  const configPath = path.join(getCodexHomeDir(), 'config.toml');
+  const raw = readUtf8IfExists(configPath);
+  if (!raw) {
+    return { ok: false, message: `No Codex config found at ${configPath}. Run: empirical install.` };
+  }
+  const headerPattern = new RegExp(`\\[mcp_servers\\.(?:"${EMPIRICAL_MCP_NAME}"|${EMPIRICAL_MCP_NAME})\\]`);
+  const headerMatch = headerPattern.exec(raw);
+  if (!headerMatch) {
+    return {
+      ok: false,
+      message: `Empirical MCP server not registered in ${configPath}. Run: empirical install (or codex mcp add ${EMPIRICAL_MCP_NAME} --url ${EMPIRICAL_MCP_URL}).`
+    };
+  }
+  const sectionStart = headerMatch.index + headerMatch[0].length;
+  const nextHeaderIndex = raw.indexOf('\n[', sectionStart);
+  const section = raw.slice(sectionStart, nextHeaderIndex === -1 ? raw.length : nextHeaderIndex);
+  const urlMatch = /url\s*=\s*"([^"]+)"/.exec(section);
+  const registeredUrl = urlMatch ? urlMatch[1] : null;
+  if (registeredUrl && registeredUrl !== EMPIRICAL_MCP_URL) {
+    return {
+      ok: false,
+      message: `Registered Codex MCP URL (${registeredUrl}) does not match the current endpoint (${EMPIRICAL_MCP_URL}). Run: empirical install to re-register.`
+    };
+  }
+  return { ok: true, message: `Registered in ${configPath} (url: ${registeredUrl || EMPIRICAL_MCP_URL}).` };
+}
+
+const MCP_CONFIG_CHECKERS = {
+  claude: checkClaudeMcpConfig,
+  codex: checkCodexMcpConfig,
+  copilot: checkCopilotMcpConfig
+};
+
+// ─── Hooks presence ────────────────────────────────────────────────────────────
+// Mirrors what installers/hooks.js actually writes per host: script files on disk, plus a
+// registration entry inside that host's own hook manifest (settings.json / hooks.json / the
+// Copilot hooks file). A script can exist on disk but no longer be wired into the manifest (e.g.
+// the host rewrote its config and dropped the entry), so both are checked.
+
+function claudeHookStatus() {
+  const hooksDir = getEmpiricalHooksDir();
+  const scripts = ['claude-session-start.js', 'claude-user-prompt-submit.js', 'claude-stop.js'];
+  const missingScripts = scripts.filter((name) => !readUtf8IfExists(path.join(hooksDir, name)));
+
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const settings = readJsonIfExists(settingsPath) || {};
+  const hookEvents = ['SessionStart', 'UserPromptSubmit', 'Stop'];
+  const registeredEvents = hookEvents.filter((eventName) => {
+    const entries = settings.hooks && settings.hooks[eventName];
+    if (!Array.isArray(entries)) return false;
+    return entries.some((entry) => Array.isArray(entry.hooks)
+      && entry.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(hooksDir)));
+  });
+
+  return { missingScripts, missingRegistrations: hookEvents.filter((e) => !registeredEvents.includes(e)), manifestPath: settingsPath };
+}
+
+function codexHookStatus() {
+  const hooksDir = getCodexHooksScriptsDir();
+  const scripts = ['codex-session-start.js', 'codex-user-prompt-submit.js', 'codex-stop.js'];
+  const missingScripts = scripts.filter((name) => !readUtf8IfExists(path.join(hooksDir, name)));
+
+  const hooksJsonPath = path.join(getCodexHomeDir(), 'hooks.json');
+  const hooksFile = readJsonIfExists(hooksJsonPath) || {};
+  const hookEvents = ['SessionStart', 'UserPromptSubmit', 'Stop'];
+  const registeredEvents = hookEvents.filter((eventName) => {
+    const entries = hooksFile.hooks && hooksFile.hooks[eventName];
+    if (!Array.isArray(entries)) return false;
+    return entries.some((entry) => Array.isArray(entry.hooks)
+      && entry.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(hooksDir)));
+  });
+
+  return { missingScripts, missingRegistrations: hookEvents.filter((e) => !registeredEvents.includes(e)), manifestPath: hooksJsonPath };
+}
+
+function copilotHookStatus() {
+  const hooksDir = getEmpiricalHooksDir();
+  const scripts = ['copilot-session-start.js', 'copilot-user-prompt-submit.js', 'copilot-stop.js'];
+  const missingScripts = scripts.filter((name) => !readUtf8IfExists(path.join(hooksDir, name)));
+
+  const hookFilePath = path.join(os.homedir(), '.copilot', 'hooks', 'empirical-hooks.json');
+  const hookFile = readJsonIfExists(hookFilePath) || {};
+  const hookEvents = ['sessionStart', 'userPromptSubmitted', 'agentStop'];
+  const registeredEvents = hookEvents.filter((eventName) => {
+    const entries = hookFile.hooks && hookFile.hooks[eventName];
+    if (!Array.isArray(entries)) return false;
+    return entries.some((h) => h && typeof h.command === 'string' && h.command.includes(hooksDir));
+  });
+
+  return { missingScripts, missingRegistrations: hookEvents.filter((e) => !registeredEvents.includes(e)), manifestPath: hookFilePath };
+}
+
+const HOOK_STATUS_CHECKERS = {
+  claude: claudeHookStatus,
+  codex: codexHookStatus,
+  copilot: copilotHookStatus
+};
+
+// ─── MCP remote reachability ───────────────────────────────────────────────────
+// The MCP endpoint speaks Streamable HTTP (see packages/server/src/mcp/http.ts): a POST with a
+// JSON-RPC "initialize" body returns an SSE-framed response ("event: message\ndata: {...}\n\n"),
+// not a bare JSON document — confirmed against the live endpoint. httpJson only guarantees a
+// parsed body for real JSON, so a successful SSE response lands in `data.raw` and is unwrapped
+// here by hand.
+function extractJsonRpcResult(rawOrParsed) {
+  if (rawOrParsed && typeof rawOrParsed === 'object' && !rawOrParsed.raw) {
+    return rawOrParsed;
+  }
+  const raw = rawOrParsed && rawOrParsed.raw ? rawOrParsed.raw : '';
+  const dataLine = raw.split(/\r?\n/).find((line) => line.startsWith('data:'));
+  if (!dataLine) return null;
+  try {
+    return JSON.parse(dataLine.slice('data:'.length).trim());
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function checkMcpReachability(token) {
+  if (!token) {
+    return { ok: false, message: 'Skipped — no token available.' };
+  }
+  const body = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'empirical-doctor', version: '1.0.0' }
+    }
+  };
+  const headers = {
+    ...buildApiAuthHeaders(token),
+    Accept: 'application/json, text/event-stream'
+  };
+  const start = Date.now();
+  try {
+    const response = await httpJson(EMPIRICAL_MCP_URL, 'POST', body, headers, 10000);
+    const elapsedMs = Date.now() - start;
+    const parsed = extractJsonRpcResult(response);
+    if (!parsed) {
+      return { ok: false, message: `Reached ${EMPIRICAL_MCP_URL} (${elapsedMs}ms) but could not parse an MCP response.` };
+    }
+    if (parsed.error) {
+      return { ok: false, message: `MCP initialize returned an error: ${parsed.error.message || JSON.stringify(parsed.error)}` };
+    }
+    const serverInfo = parsed.result && parsed.result.serverInfo;
+    return {
+      ok: true,
+      message: `MCP initialize round trip succeeded in ${elapsedMs}ms (server: ${serverInfo ? `${serverInfo.name}@${serverInfo.version}` : 'unknown'}).`
+    };
+  } catch (error) {
+    const elapsedMs = Date.now() - start;
+    return { ok: false, message: `MCP request to ${EMPIRICAL_MCP_URL} failed after ${elapsedMs}ms: ${error.message}` };
+  }
+}
+
+// ─── --deep: write/query/delete round trip ────────────────────────────────────
+async function runDeepMemoryRoundTrip(token) {
+  const baseUrl = resolveApiBaseUrl();
+  const marker = `doctor-probe-${Date.now()}`;
+  const timings = {};
+
+  const recordUrl = new URL('/api/v1/memories', baseUrl).toString();
+  const category = MEMORY_CATEGORIES.includes('operations') ? 'operations' : MEMORY_CATEGORIES[0];
+  const payload = {
+    category,
+    summary: marker,
+    nodeType: 'observation',
+    tags: ['doctor-probe'],
+    data: { text: marker }
+  };
+
+  let recordId = null;
+  const recordStart = Date.now();
+  try {
+    const response = await httpJson(recordUrl, 'POST', payload, buildApiAuthHeaders(token));
+    timings.recordMs = Date.now() - recordStart;
+    const created = (response && response.data) ? response.data : response;
+    recordId = created && (created.id || created._id) ? (created.id || created._id) : null;
+    if (!recordId) {
+      return { ok: false, message: `Record leg succeeded (${timings.recordMs}ms) but no memory id was returned in the response.` };
+    }
+  } catch (error) {
+    timings.recordMs = Date.now() - recordStart;
+    return { ok: false, message: `Record leg failed after ${timings.recordMs}ms: ${error.message}` };
+  }
+
+  let found = false;
+  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
+  const queryStart = Date.now();
+  try {
+    const response = await httpJson(queryUrl, 'POST', { query: marker, topK: 5 }, buildApiAuthHeaders(token));
+    timings.queryMs = Date.now() - queryStart;
+    const results = (response && response.data && Array.isArray(response.data.results))
+      ? response.data.results
+      : (Array.isArray(response) ? response : []);
+    found = results.some((r) => r && r.id === recordId);
+  } catch (error) {
+    timings.queryMs = Date.now() - queryStart;
+    // Fall through to best-effort delete below so a query failure doesn't leave the probe memory
+    // stranded — deletion below still runs regardless.
+  }
+
+  let deleted = false;
+  let deleteError = null;
+  const deleteUrl = new URL(`/api/v1/memories/${encodeURIComponent(recordId)}`, baseUrl).toString();
+  const deleteStart = Date.now();
+  try {
+    await httpJson(deleteUrl, 'DELETE', null, buildApiAuthHeaders(token));
+    timings.deleteMs = Date.now() - deleteStart;
+    deleted = true;
+  } catch (error) {
+    timings.deleteMs = Date.now() - deleteStart;
+    deleteError = error.message;
+  }
+
+  const timingSummary = `record ${timings.recordMs}ms, query ${timings.queryMs}ms, delete ${timings.deleteMs}ms`;
+  if (!deleted) {
+    return {
+      ok: false,
+      message: `Round trip left a probe memory behind (id ${recordId}) — delete failed: ${deleteError}. ${timingSummary}.`
+    };
+  }
+  if (!found) {
+    return {
+      ok: 'warn',
+      message: `Wrote and deleted probe memory ${marker} cleanly, but the query leg did not find it (indexing lag or search-side issue). ${timingSummary}.`
+    };
+  }
+  return { ok: true, message: `Wrote, queried, and deleted probe memory ${marker} cleanly. ${timingSummary}.` };
+}
+
+async function runDoctor(args) {
+  return withCliAnalyticsContext({ command: 'doctor' }, async () => {
+    const outputJson = parseOption(args, '--output', '') === 'json';
+    const deep = parseFlag(args, '--deep');
+    const checks = [];
+    let overallFail = false;
+    let overallWarn = false;
+
+    function addCheck(name, status, message) {
+      checks.push({ name, status, message });
+      if (status === 'fail') overallFail = true;
+      if (status === 'warn') overallWarn = true;
+    }
+
+    const token = resolveAccessToken();
+    if (!token) {
+      addCheck('token_presence', 'fail', 'No access token found. Run: empirical auth login, or configure headless credentials with empirical oauth bootstrap headless.');
+    } else {
+      addCheck('token_presence', 'ok', 'Access token found.');
+    }
+
+    // Token type/expiry decoding is shared with `auth status`/`whoami` via auth.js's
+    // inspectToken, so the two commands can never silently disagree on what "expired" means.
+    const tokenInfo = inspectToken(token);
+    if (token) {
+      if (tokenInfo.tokenType === 'jwt') {
+        addCheck('token_type', 'ok', 'Token is a JWT (3-part).');
+      } else {
+        addCheck('token_type', 'ok', 'Token is an API key (long alphanumeric).');
+      }
+    } else {
+      addCheck('token_type', 'fail', 'Cannot determine token type — no token found.');
+    }
+
+    if (token && tokenInfo.tokenType === 'jwt') {
+      if (tokenInfo.expiresAt === null) {
+        addCheck('token_expiry', 'warn', 'JWT has no `exp` claim or could not be decoded — expiry unknown.');
+      } else if (tokenInfo.expired) {
+        addCheck('token_expiry', 'fail', `Token expired at ${tokenInfo.expiresAt}.`);
+      } else {
+        const remaining = Math.round((new Date(tokenInfo.expiresAt).getTime() - Date.now()) / 1000);
+        addCheck('token_expiry', 'ok', `Token expires in ${remaining}s (at ${tokenInfo.expiresAt}).`);
+      }
+    } else if (token && tokenInfo.tokenType === 'apikey') {
+      addCheck('token_expiry', 'ok', 'API key — no expiry.');
+    }
+
+    let userData = null;
+    if (token) {
+      const baseUrl = resolveApiBaseUrl();
+      const meUrl = new URL('/api/v1/users/me', baseUrl).toString();
+      try {
+        const response = await httpJson(meUrl, 'GET', null, buildApiAuthHeaders(token));
+        userData = (response && response.data) ? response.data : response;
+        addCheck('api_connectivity', 'ok', `Connected. User: ${userData.email || userData.userId || 'unknown'}.`);
+      } catch (error) {
+        addCheck('api_connectivity', 'fail', `API request failed: ${error.message}`);
+      }
+    } else {
+      addCheck('api_connectivity', 'fail', 'Skipped — no token available.');
+    }
+
+    if (userData) {
+      const wsId = userData.workspaceId || userData.workspaceName || null;
+      if (wsId) {
+        addCheck('workspace', 'ok', `Workspace ID: ${wsId}.`);
+      } else {
+        addCheck('workspace', 'warn', 'No active workspace — using default brain.');
+      }
+    } else {
+      addCheck('workspace', 'fail', 'Skipped — API connectivity check failed.');
+    }
+
+    // ─── MCP wiring diagnostics (C-007) ─────────────────────────────────────
+    const detectedTargets = detectInstallTargets();
+    if (detectedTargets.length === 0) {
+      addCheck('mcp_hosts_detected', 'warn', 'No supported host CLI detected (codex/claude/copilot). Nothing to check for MCP wiring.');
+    } else {
+      addCheck('mcp_hosts_detected', 'ok', `Detected: ${detectedTargets.map((t) => t.label).join(', ')}.`);
+    }
+
+    for (const target of detectedTargets) {
+      const checker = MCP_CONFIG_CHECKERS[target.id];
+      if (!checker) continue;
+      let result;
+      try {
+        result = checker();
+      } catch (error) {
+        result = { ok: false, message: `Could not inspect ${target.label} MCP config: ${error.message}` };
+      }
+      addCheck(`mcp_config_${target.id}`, result.ok ? 'ok' : 'fail', `${target.label}: ${result.message}`);
+    }
+
+    const mcpReachability = await checkMcpReachability(token);
+    addCheck('mcp_reachability', mcpReachability.ok ? 'ok' : 'fail', mcpReachability.message);
+
+    const pluginNames = [CORE_PLUGIN_NAME, ...OPTIONAL_PLUGIN_NAMES];
+    for (const target of detectedTargets) {
+      let versions;
+      try {
+        versions = readInstalledVersions(target.id, pluginNames);
+      } catch (error) {
+        versions = null;
+      }
+      if (!versions) {
+        addCheck(
+          `plugin_${target.id}`,
+          'warn',
+          `${target.label}: could not read plugin list (CLI not on PATH or "${target.id} plugin list" failed). Run: empirical plugin install ${target.id}.`
+        );
+        continue;
+      }
+      const coreVersion = versions[CORE_PLUGIN_NAME];
+      if (!coreVersion) {
+        addCheck(`plugin_${target.id}`, 'fail', `${target.label}: empirical-memory plugin not installed. Run: empirical plugin install ${target.id}.`);
+        continue;
+      }
+      const optionalInstalled = OPTIONAL_PLUGIN_NAMES.filter((name) => versions[name]);
+      const optionalSummary = optionalInstalled.length ? `; optional: ${optionalInstalled.map((name) => `${name}@${versions[name]}`).join(', ')}` : '; no optional plugins installed';
+      addCheck(`plugin_${target.id}`, 'ok', `${target.label}: empirical-memory@${coreVersion}${optionalSummary}.`);
+    }
+
+    for (const target of detectedTargets) {
+      const statusFn = HOOK_STATUS_CHECKERS[target.id];
+      if (!statusFn) continue;
+      let status;
+      try {
+        status = statusFn();
+      } catch (error) {
+        addCheck(`hooks_${target.id}`, 'fail', `${target.label}: could not inspect hooks: ${error.message}`);
+        continue;
+      }
+      if (status.missingScripts.length === 0 && status.missingRegistrations.length === 0) {
+        addCheck(`hooks_${target.id}`, 'ok', `${target.label}: SessionStart/UserPromptSubmit/Stop hook scripts present and registered in ${status.manifestPath}.`);
+      } else {
+        const parts = [];
+        if (status.missingScripts.length) parts.push(`missing script file(s): ${status.missingScripts.join(', ')}`);
+        if (status.missingRegistrations.length) parts.push(`not registered in ${status.manifestPath}: ${status.missingRegistrations.join(', ')}`);
+        addCheck(`hooks_${target.id}`, 'fail', `${target.label}: ${parts.join('; ')}. Run: empirical install.`);
+      }
+    }
+
+    // ─── --deep: live write/query/delete round trip ─────────────────────────
+    if (deep) {
+      if (!token) {
+        addCheck('deep_write_read_delete', 'fail', 'Skipped — no token available.');
+      } else {
+        const result = await runDeepMemoryRoundTrip(token);
+        const status = result.ok === true ? 'ok' : (result.ok === 'warn' ? 'warn' : 'fail');
+        addCheck('deep_write_read_delete', status, result.message);
+      }
+    }
+
+    const overall = overallFail ? 'fail' : (overallWarn ? 'warn' : 'ok');
+
+    if (outputJson) {
+      log(JSON.stringify({ checks, overall }));
+    } else {
+      const statusLabel = (status) => {
+        if (status === 'ok') return colorize(ANSI.green, '[OK]  ');
+        if (status === 'warn') return colorize(ANSI.yellow, '[WARN]');
+        return colorize(ANSI.red, '[FAIL]');
+      };
+      for (const check of checks) {
+        log(`${statusLabel(check.status)} ${check.name.padEnd(20)} ${check.message}`);
+      }
+      log('');
+      log(`Overall: ${overall.toUpperCase()}`);
+    }
+
+    if (overallFail) {
+      process.exitCode = 1;
+    }
+  });
+}
+
+module.exports = {
+  runDoctor
+};

package/lib/help.js

@@ -19,6 +19,7 @@ function showHelp() {
   log('  empirical policy set --json <policy>');
   log('  empirical auth login                         Interactive browser login');
   log('  empirical auth logout                        Clear the locally stored session');
+  log('  empirical auth status                        Print user, token type, expiry, workspace as JSON (alias: whoami)');
   log('  empirical oauth bootstrap headless [--print-access-token]');
   log('                                                First-time token setup for CI/headless/API-key use');
   log('  empirical oauth bootstrap headless --write-env [--env-output <path>]');
@@ -74,6 +75,11 @@ function showHelp() {
   log('  empirical memory duplicates      List duplicate candidates for a memory');
   log('  empirical memory merge           Merge a duplicate memory into a canonical one');
   log('  empirical memory export          Export memories as portable JSON [--scope <personal|workspace>] [--out <path>]');
+  log('  empirical memory import <file>   Import a versioned memory export [--dry-run]');
+  log('  empirical memory stats           Counts by category/tag, total, oldest/newest [--format table]');
+  log('  empirical memory compact         Dry-run preview of merge/link candidates [--apply] [--category <cat>]');
+  log('  empirical memory delete --tag <t>|--category <c>|--all --confirm');
+  log('                                   Bulk soft-delete by tag/category/all (dry-run without --confirm)');
   log('  empirical kit create <name>      Create a new Kit [--workspace <workspaceId>]');
   log('  empirical kit add-source <kit> <git-url>');
   log('                                   Add a git Source to a Kit [--ref <ref>] [--path <subpath>]');
@@ -92,9 +98,9 @@ function showHelp() {
   log('                                   Push a local SKILL.md as an authored Skill [--kit <kitId>]');
   log('                                   Wrote or edited a SKILL.md? Push it so it follows you');
   log('                                   across machines/projects instead of staying local.');
-  log('  empirical skill history <authoredSkillId>');
+  log('  empirical skill history <authoredSkillId|name> [--kit <kitId>]');
   log('                                   Show version history for an authored Skill');
-  log('  empirical skill rollback <authoredSkillId> --to-version <n>');
+  log('  empirical skill rollback <authoredSkillId|name> --to-version <n> [--kit <kitId>]');
   log('                                   Roll an authored Skill back to a prior version');
   log('  empirical device list             List registered devices and active Kits');
   log('  empirical device show <deviceId>  Show effective Skills for a device');