@dashclaw/cli 0.3.2 → 0.4.0

package/README.md

@@ -83,16 +83,20 @@ Outputs an aligned table (total, sessions, cache savings, by-project breakdown f
 
 ### `dashclaw doctor`
 
-Diagnose your DashClaw instance and auto-fix safe issues. Checks database, configuration, auth, deployment, SDK reachability, and governance.
+Diagnose your DashClaw instance **and this machine**. Remote checks cover database, configuration, auth, deployment, SDK reachability, governance, and data hygiene; local checks cover what the server can't see — a stale compiled `mcp-server/lib`, `.gitattributes` drift, a local DB schema behind code, a disabled OpenClaw runtime plugin, a stale global CLI shim, broken Claude hook installs, and leaked machine-scope `DASHCLAW_*` env vars.
 
 ```bash
-dashclaw doctor                          # rich terminal output, auto-fix what it can
-dashclaw doctor --json                   # JSON output for CI/scripts
-dashclaw doctor --no-fix                 # diagnose only
-dashclaw doctor --category database,config
+dashclaw doctor                          # report-only (DEFAULT — applies nothing)
+dashclaw doctor --fix                    # apply safe auto-fixes, re-check, report what changed
+dashclaw doctor --json                   # JSON output for CI/scripts (includes local checks)
+dashclaw doctor --category database,config   # filter remote checks
+dashclaw doctor --repo /path/to/dashclaw     # point repo checks at a checkout
+dashclaw doctor --no-fix                 # accepted no-op alias (report-only is the default)
 ```
 
-The CLI invokes your instance's `/api/doctor` endpoints, so fixes that need filesystem access (env writes) are handled separately by self-hosters running `npm run doctor` locally.
+> **Changed in 0.4.0:** `dashclaw doctor` no longer applies remote auto-fixes by default — it reports and prints would-fix entries. Pass `--fix` to apply. Exit codes are unchanged (0 healthy, 1 otherwise).
+
+Detect-only classes are never auto-fixed: leaked machine env vars (removal instructions printed) and OpenClaw gateway configs (remediation text printed). The `.gitattributes` restore runs only when the diff is provably line-ending/whitespace-only. Remote fixes go through `POST /api/doctor/fix`; fixes that need server filesystem access remain self-hoster territory via `npm run doctor` (also report-only by default now, same `--fix` opt-in).
 
 ### `dashclaw code`
 

package/bin/dashclaw.js

@@ -81,10 +81,12 @@ ${bold('Usage:')}
   dashclaw approvals                     Interactive approval inbox
   dashclaw approve <actionId> [--reason]  Approve an action
   dashclaw deny <actionId> [--reason]     Deny an action
-  dashclaw doctor                        Diagnose and auto-fix your DashClaw instance
+  dashclaw doctor                        Diagnose your instance + this machine (report-only)
+    --fix                                Apply safe auto-fixes, then re-check and report
     --json                               Output as JSON (for CI/scripts)
-    --no-fix                             Diagnose only, skip auto-fixes
-    --category <list>                    Filter checks (e.g., database,config)
+    --no-fix                             Accepted no-op alias (report-only is the default)
+    --category <list>                    Filter remote checks (e.g., database,config)
+    --repo <path>                        Treat <path> as the DashClaw checkout for repo checks
   dashclaw code ingest [--dry-run]       Backfill Claude Code transcripts from ~/.claude/projects
     --projects-dir <path>                Override the default scan directory
   dashclaw code ingest-codex [--dry-run] Backfill Codex transcripts from ~/.codex/sessions
@@ -164,15 +166,23 @@ async function cmdLogout() {
 
 async function cmdDoctor() {
   const jsonFlag = args.includes('--json');
+  const fixFlag = args.includes('--fix');
   const noFixFlag = args.includes('--no-fix');
   const catIdx = args.indexOf('--category');
   const catValue = catIdx !== -1 ? args[catIdx + 1] : undefined;
+  const repoIdx = args.indexOf('--repo');
+  const repoValue = repoIdx !== -1 ? args[repoIdx + 1] : undefined;
+  const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
   await runDoctorCommand({
     baseUrl,
     apiKey,
     json: jsonFlag,
+    fix: fixFlag,
     noFix: noFixFlag,
     category: catValue,
+    repo: repoValue,
+    cliVersion: pkg.version,
   });
 }
 

package/lib/doctor.js

@@ -1,5 +1,11 @@
 // cli/lib/doctor.js
 import { bold, dim, green, yellow, red } from './render.js';
+import {
+  buildContext,
+  detectRepoRoot,
+  runLocalChecks,
+  applyLocalFixes,
+} from './local-doctor.js';
 
 // Brand orange (256-color ANSI). Used sparingly — header + key accents only.
 const BRAND = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
@@ -19,9 +25,17 @@ const CATEGORY_LABELS = {
   governance: 'Governance',
   shape: 'Shape (generated)',
   drift: 'Drift',
+  'openclaw-plugin': 'OpenClaw Plugin',
+  hosted: 'Hosted',
+  'data-hygiene': 'Data Hygiene',
+  'local-repo': 'Local Repo (this machine)',
+  'local-machine': 'Machine Setup (this machine)',
 };
 
-const CATEGORY_ORDER = ['database', 'config', 'auth', 'deployment', 'sdk', 'governance', 'shape', 'drift'];
+const CATEGORY_ORDER = [
+  'database', 'config', 'auth', 'deployment', 'sdk', 'governance', 'shape', 'drift',
+  'openclaw-plugin', 'hosted', 'data-hygiene', 'local-repo', 'local-machine',
+];
 
 // Next-step guidance by check ID, used when the check has no auto-fix.
 // Keep each line short and actionable.
@@ -36,6 +50,8 @@ const GUIDANCE = {
   sdk_auth: 'API key rejected — verify DASHCLAW_API_KEY matches the key on your instance.',
   gov_actions: 'Send your first governed action with claw.guard() via the SDK.',
   gov_stale: "Agents haven't reported in 7 days — check your agent pairings.",
+  remote_unreachable: 'Check DASHCLAW_BASE_URL and confirm your instance is deployed and awake.',
+  remote_auth: 'API key rejected — verify DASHCLAW_API_KEY matches the key on your instance.',
 };
 
 function hr(width = 72) {
@@ -44,16 +60,22 @@ function hr(width = 72) {
 
 /**
  * Return an actionable next-step string for a non-passing check, or null.
+ * In report-only mode (the default), fixable checks point at --fix.
  */
-function nextStepFor(check, { noFix }) {
+function nextStepFor(check, { fixMode }) {
   if (!check || check.status === 'pass') return null;
 
   // Auto-fixable check: direct the user to the fix.
   if (check.fix?.type === 'auto') {
-    if (noFix) {
-      return `${check.fix.description}. Re-run without ${bold('--no-fix')} to apply.`;
+    if (!isFixableByCli(check)) {
+      // Remote warn-status fix — POST /api/doctor/fix only applies on fail, so
+      // --fix won't attempt it; don't promise what this CLI won't do.
+      return `${check.fix.description} — run ${bold('npm run doctor -- --fix')} on the instance host.`;
     }
-    // Fix was attempted (or will run in this invocation); describe what it does.
+    if (!fixMode) {
+      return `would fix: ${check.fix.description}. Run ${bold('dashclaw doctor --fix')} to apply.`;
+    }
+    // Fix runs in this invocation; describe what it does.
     return check.fix.description + '.';
   }
 
@@ -71,42 +93,71 @@ function doctorHeaders(apiKey) {
   return { 'Content-Type': 'application/json', 'x-api-key': apiKey };
 }
 
-function exitFetchError(base, err) {
-  console.error(red(`\nError: Could not reach DashClaw at ${base}`));
-  console.error(dim(`  ${err.cause?.code || err.message}`));
-  console.error(dim(`  Check DASHCLAW_BASE_URL and confirm your instance is running.\n`));
-  process.exit(1);
+function unreachableCheck(base, detail) {
+  return {
+    id: 'remote_unreachable',
+    category: 'sdk',
+    status: 'fail',
+    title: 'Instance Reachable',
+    message: `Could not reach DashClaw at ${base} (${detail})`,
+    fix: null,
+  };
+}
+
+function authRejectedCheck(base, status) {
+  return {
+    id: 'remote_auth',
+    category: 'sdk',
+    status: 'fail',
+    title: 'API Key Accepted',
+    message: `API key rejected by ${base} (${status})`,
+    fix: null,
+  };
 }
 
-async function fetchDoctorResult({ base, apiKey, category }) {
+/**
+ * Fetch /api/doctor, degrading to a synthetic fail check instead of exiting —
+ * local checks still run and report when the instance is down.
+ */
+async function fetchRemoteResult({ base, apiKey, category, fetchImpl }) {
   const headers = doctorHeaders(apiKey);
   let res;
   try {
-    res = await fetch(doctorUrl(base, category), { headers });
+    res = await fetchImpl(doctorUrl(base, category), { headers });
   } catch (err) {
-    exitFetchError(base, err);
+    return { result: null, degraded: unreachableCheck(base, err.cause?.code || err.message), headers };
   }
-  await handleDoctorResponse(base, res);
-  return { result: await res.json(), headers };
-}
 
-async function handleDoctorResponse(base, res) {
   if (res.status === 401 || res.status === 403) {
-    console.error(red(`\nError: API key rejected by ${base} (${res.status}).`));
-    console.error(dim(`  Check DASHCLAW_API_KEY matches the key on your instance.\n`));
-    process.exit(1);
+    return { result: null, degraded: authRejectedCheck(base, res.status), headers };
   }
-
   if (!res.ok && res.status !== 503) {
     const errText = await res.text().catch(() => '');
-    console.error(red(`Doctor check failed (${res.status}): ${errText}`));
-    process.exit(1);
+    return { result: null, degraded: unreachableCheck(base, `${res.status} ${errText.slice(0, 120)}`), headers };
+  }
+
+  try {
+    return { result: await res.json(), degraded: null, headers };
+  } catch (err) {
+    return { result: null, degraded: unreachableCheck(base, `unparseable response: ${err.message}`), headers };
+  }
+}
+
+function computeSummary(checks) {
+  const summary = { pass: 0, warn: 0, fail: 0 };
+  for (const check of checks) {
+    if (check.status in summary) summary[check.status]++;
   }
+  return summary;
 }
 
-function exitJson(result) {
-  console.log(JSON.stringify(result, null, 2));
-  process.exit(result.status === 'healthy' ? 0 : 1);
+/** Merge remote result + local checks into one report (engine status semantics). */
+function mergeReport(remoteResult, degradedCheck, localChecks) {
+  const remoteChecks = remoteResult?.checks || [];
+  const checks = [...remoteChecks, ...(degradedCheck ? [degradedCheck] : []), ...localChecks];
+  const summary = computeSummary(checks);
+  const status = summary.fail > 0 ? 'unhealthy' : summary.warn > 0 ? 'needs_attention' : 'healthy';
+  return { status, summary, checks, timestamp: remoteResult?.timestamp || new Date().toISOString() };
 }
 
 function renderHeader(base) {
@@ -125,73 +176,86 @@ function groupChecks(checks) {
   return grouped;
 }
 
-function renderCheck(check, noFix) {
+function renderCheck(check, fixMode) {
   const icon = ICONS[check.status] || '?';
   const titleStyled = check.status === 'pass' ? check.title : bold(check.title);
   console.log(`  ${icon} ${titleStyled}`);
 
   if (check.status !== 'pass') {
     console.log(`    ${dim(check.message)}`);
-    const tip = nextStepFor(check, { noFix });
+    const tip = nextStepFor(check, { fixMode });
     if (tip) {
       console.log(`    ${dim('\u2192')} ${tip}`);
     }
   }
 }
 
-function renderGroupedChecks(checks, noFix) {
+function renderGroupedChecks(checks, fixMode) {
   const grouped = groupChecks(checks);
-  for (const cat of CATEGORY_ORDER) {
+  const orderedCategories = [
+    ...CATEGORY_ORDER,
+    ...Object.keys(grouped).filter((c) => !CATEGORY_ORDER.includes(c)),
+  ];
+  for (const cat of orderedCategories) {
     const categoryChecks = grouped[cat];
     if (!categoryChecks || categoryChecks.length === 0) continue;
 
     console.log(`  ${bold(CATEGORY_LABELS[cat] || cat)}`);
     for (const check of categoryChecks) {
-      renderCheck(check, noFix);
+      renderCheck(check, fixMode);
     }
     console.log();
   }
 }
 
-function autoFixableChecks(result) {
-  return result.checks.filter((c) => c.status === 'fail' && c.fix?.type === 'auto');
+/**
+ * A check this invocation's --fix would actually attempt: any non-pass local
+ * check with an auto fix, or a remote FAIL with an auto fix (the remote apply
+ * path posts fail-status checks only — warn-status remote fixes are server-side).
+ */
+function isFixableByCli(check) {
+  if (!check?.fix || check.fix.type !== 'auto' || check.status === 'pass') return false;
+  return check.local ? true : check.status === 'fail';
+}
+
+function fixableChecks(checks) {
+  return checks.filter(isFixableByCli);
 }
 
-async function applyDoctorFix({ base, headers, check }) {
+async function applyRemoteFix({ base, headers, check, fetchImpl }) {
   try {
-    const fixRes = await fetch(`${base}/api/doctor/fix`, {
+    const fixRes = await fetchImpl(`${base}/api/doctor/fix`, {
       method: 'POST',
       headers,
       body: JSON.stringify({ action: check.fix.action }),
     });
     const fixResult = await fixRes.json();
-    if (fixResult.applied) {
-      console.log(`  ${green('\u2192')} Fixed: ${fixResult.description}`);
-      return { fixed: 1, recheck: fixResult.recheck || null };
-    }
-    console.log(`  ${dim('\u2192')} Skipped: ${fixResult.description}`);
+    return { id: check.id, action: check.fix.action, applied: !!fixResult.applied, description: fixResult.description };
   } catch (err) {
-    console.log(`  ${red('\u2717')} Fix "${check.fix.action}" failed: ${err.cause?.code || err.message}`);
+    return {
+      id: check.id,
+      action: check.fix.action,
+      applied: false,
+      description: `Fix request failed: ${err.cause?.code || err.message}`,
+    };
   }
-  return { fixed: 0, recheck: null };
 }
 
-async function applyAutoFixes({ base, headers, result, noFix }) {
-  let fixCount = 0;
-  let latestRecheck = null;
-  if (noFix) return { fixCount, latestRecheck };
-
-  const fixable = autoFixableChecks(result);
-  if (fixable.length === 0) return { fixCount, latestRecheck };
-
-  console.log(`  ${bold('Applying auto-fixes...')}`);
-  for (const check of fixable) {
-    const outcome = await applyDoctorFix({ base, headers, check });
-    fixCount += outcome.fixed;
-    latestRecheck = outcome.recheck || latestRecheck;
+function renderWhatChanged(fixResults) {
+  console.log(`  ${bold('What changed')}`);
+  if (fixResults.length === 0) {
+    console.log(`  ${dim('Nothing \u2014 no auto-fixable issues found.')}`);
+    console.log();
+    return;
+  }
+  for (const result of fixResults) {
+    if (result.applied) {
+      console.log(`  ${green('\u2713')} Applied ${bold(result.action)}: ${result.description}`);
+    } else {
+      console.log(`  ${yellow('\u26a0')} Skipped ${bold(result.action)}: ${result.description}`);
+    }
   }
   console.log();
-  return { fixCount, latestRecheck };
 }
 
 function renderSummary(reporting) {
@@ -208,20 +272,12 @@ function renderSummary(reporting) {
   console.log();
 }
 
-function renderFixCount(fixCount) {
-  if (fixCount > 0) {
-    console.log(`  ${green('\u2713')} ${fixCount} issue${fixCount !== 1 ? 's' : ''} auto-fixed this run.`);
-  }
-}
-
-function renderNoFixHint(result, noFix) {
-  if (!noFix) return;
-  const autoFixable = result.checks.filter(
-    (c) => c.status !== 'pass' && c.fix?.type === 'auto',
-  ).length;
-  if (autoFixable > 0) {
+function renderFixHint(report, fixMode) {
+  if (fixMode) return;
+  const fixable = fixableChecks(report.checks).length;
+  if (fixable > 0) {
     console.log(
-      `  ${BRAND('\u2192')} ${autoFixable} issue${autoFixable !== 1 ? 's' : ''} can be auto-fixed. Run: ${bold('dashclaw doctor')}`,
+      `  ${BRAND('\u2192')} ${fixable} issue${fixable !== 1 ? 's' : ''} can be auto-fixed. Run: ${bold('dashclaw doctor --fix')}`,
     );
   }
 }
@@ -236,35 +292,80 @@ function renderHealthFooter(base, healthy) {
 }
 
 /**
- * Run doctor via the API and render results.
- * @param {{ baseUrl: string, apiKey: string, json?: boolean, noFix?: boolean, category?: string }} options
+ * Doctor flow: merged local + remote report; report-only by default; --fix
+ * applies local fixes locally and remote auto-fixes via POST /api/doctor/fix,
+ * re-checks, and prints a what-changed report. Returns the exit code.
+ *
+ * @param {{ baseUrl: string, apiKey: string, json?: boolean, fix?: boolean,
+ *           noFix?: boolean, category?: string, repo?: string, cliVersion?: string }} options
+ * @param {{ fetchImpl?: typeof fetch, local?: object }} [deps] - injectable for tests
  */
-export async function runDoctor({ baseUrl, apiKey, json, noFix, category }) {
+export async function runDoctorFlow(options, deps = {}) {
+  const { baseUrl, apiKey, json, fix, noFix, category, repo, cliVersion = '0.0.0' } = options;
+  const fetchImpl = deps.fetchImpl || fetch;
+  const local = deps.local || { buildContext, detectRepoRoot, runLocalChecks, applyLocalFixes };
+
+  // --no-fix is a no-op alias for the (report-only) default; it wins over --fix.
+  const fixMode = !!fix && !noFix;
   const base = baseUrl.replace(/\/+$/, '');
-  const { result, headers } = await fetchDoctorResult({ base, apiKey, category });
 
-  if (json) {
-    exitJson(result);
-  }
+  const ctx = local.buildContext({ cliVersion });
+  ctx.repoRoot = repo || local.detectRepoRoot({ cwd: ctx.cwd, fs: ctx.fs });
 
-  // --- Header ----------------------------------------------------------------
-  renderHeader(base);
+  // Local checks run concurrently with the remote fetch — added wall-clock is
+  // max(local, remote) - remote, not the sum.
+  const [remote, localChecks] = await Promise.all([
+    fetchRemoteResult({ base, apiKey, category, fetchImpl }),
+    local.runLocalChecks(ctx),
+  ]);
 
-  // --- Grouped checks --------------------------------------------------------
-  renderGroupedChecks(result.checks, noFix);
+  let report = mergeReport(remote.result, remote.degraded, localChecks);
+  let fixResults = [];
 
-  // --- Auto-fix (remote fixes only; local-only fixes blocked by API) --------
-  const { fixCount, latestRecheck } = await applyAutoFixes({ base, headers, result, noFix });
+  if (fixMode) {
+    const localFixable = fixableChecks(localChecks);
+    const remoteFixable = (remote.result?.checks || []).filter(
+      (c) => c.status === 'fail' && c.fix?.type === 'auto',
+    );
 
-  // --- Summary ---------------------------------------------------------------
-  const reporting = latestRecheck || result;
-  renderSummary(reporting);
+    fixResults = await local.applyLocalFixes(localFixable, ctx);
+    for (const check of remoteFixable) {
+      fixResults.push(await applyRemoteFix({ base, headers: remote.headers, check, fetchImpl }));
+    }
 
-  // --- Contextual footer -----------------------------------------------------
-  const healthy = reporting.status === 'healthy';
-  renderFixCount(fixCount);
-  renderNoFixHint(result, noFix);
+    // Re-check after applying so the report reflects the new state.
+    if (fixResults.some((r) => r.applied)) {
+      const [remote2, localChecks2] = await Promise.all([
+        fetchRemoteResult({ base, apiKey, category, fetchImpl }),
+        local.runLocalChecks(ctx),
+      ]);
+      report = mergeReport(remote2.result, remote2.degraded, localChecks2);
+    }
+  }
+
+  const healthy = report.status === 'healthy';
+
+  if (json) {
+    console.log(JSON.stringify(fixMode ? { ...report, fixes: fixResults } : report, null, 2));
+    return healthy ? 0 : 1;
+  }
+
+  renderHeader(base);
+  renderGroupedChecks(report.checks, fixMode);
+  if (fixMode) renderWhatChanged(fixResults);
+  renderSummary(report);
+  renderFixHint(report, fixMode);
   renderHealthFooter(base, healthy);
 
-  process.exit(healthy ? 0 : 1);
+  return healthy ? 0 : 1;
+}
+
+/**
+ * Run doctor and exit with its code (CLI entry).
+ * @param {{ baseUrl: string, apiKey: string, json?: boolean, fix?: boolean,
+ *           noFix?: boolean, category?: string, repo?: string, cliVersion?: string }} options
+ */
+export async function runDoctor(options) {
+  const code = await runDoctorFlow(options);
+  process.exit(code);
 }

package/lib/local-doctor.js

@@ -0,0 +1,532 @@
+// cli/lib/local-doctor.js
+// W4: local doctor checks that run on the operator machine — the server can't
+// see these. Repo-aware checks need the cwd (or --repo) to be a DashClaw
+// checkout; machine checks always run. Every fix is idempotent; detect-only
+// classes (env leak, OpenClaw plugin) NEVER mutate anything.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir as osHomedir } from 'node:os';
+import { execFile } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Context + adapters (injected in tests)
+// ---------------------------------------------------------------------------
+
+function realExec(cmd, args = [], opts = {}) {
+  // With shell:true, node concatenates args unescaped (DEP0190) — pass a
+  // single command string instead. Shell mode is only used for trusted,
+  // hardcoded commands (npm/dashclaw), never user input.
+  const useShell = opts.shell ?? false;
+  const command = useShell ? [cmd, ...args].join(' ') : cmd;
+  const commandArgs = useShell ? [] : args;
+  return new Promise((resolvePromise) => {
+    execFile(
+      command,
+      commandArgs,
+      {
+        timeout: opts.timeout ?? 30_000,
+        shell: useShell,
+        cwd: opts.cwd,
+        windowsHide: true,
+        ...(opts.env ? { env: { ...process.env, ...opts.env } } : {}),
+      },
+      (err, stdout, stderr) => {
+        if (err && err.code === 'ENOENT') {
+          resolvePromise({ code: -1, stdout: '', stderr: 'ENOENT', notFound: true });
+          return;
+        }
+        resolvePromise({
+          code: err ? (typeof err.code === 'number' ? err.code : 1) : 0,
+          stdout: String(stdout || ''),
+          stderr: String(stderr || ''),
+        });
+      },
+    );
+  });
+}
+
+function newestMtimeReal(dir) {
+  if (!existsSync(dir)) return null;
+  let newest = null;
+  const walk = (d) => {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        walk(full);
+      } else {
+        try {
+          const m = statSync(full).mtimeMs;
+          if (newest === null || m > newest) newest = m;
+        } catch {
+          // file vanished mid-walk — skip
+        }
+      }
+    }
+  };
+  walk(dir);
+  return newest;
+}
+
+const realFs = { existsSync, readFileSync, newestMtime: newestMtimeReal };
+
+export function buildContext(overrides = {}) {
+  return {
+    cwd: process.cwd(),
+    env: process.env,
+    platform: process.platform,
+    homedir: osHomedir(),
+    exec: realExec,
+    fs: realFs,
+    repoRoot: null,
+    cliVersion: '0.0.0',
+    ...overrides,
+  };
+}
+
+/**
+ * A directory is a DashClaw checkout if its package.json carries the platform
+ * name, or (renamed forks) it has the structural markers drizzle/ + mcp-server/.
+ */
+export function detectRepoRoot({ cwd, fs = realFs }) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(join(cwd, 'package.json'), 'utf8'));
+    if (pkg?.name === 'dashclaw-platform' || pkg?.name === 'dashclaw') return cwd;
+    if (fs.existsSync(join(cwd, 'drizzle')) && fs.existsSync(join(cwd, 'mcp-server'))) return cwd;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function check(id, category, status, title, message, fix = null) {
+  return { id, category, status, title, message, fix, local: true };
+}
+
+// ---------------------------------------------------------------------------
+// Repo-aware checks
+// ---------------------------------------------------------------------------
+
+async function checkMcpLibStale(ctx) {
+  const srcDir = join(ctx.repoRoot, 'mcp-server', 'src');
+  const libDir = join(ctx.repoRoot, 'mcp-server', 'lib');
+  const srcNewest = ctx.fs.newestMtime(srcDir);
+  if (srcNewest === null) return null; // no mcp-server src — nothing to verify
+  const libNewest = ctx.fs.newestMtime(libDir);
+
+  if (libNewest === null || srcNewest > libNewest) {
+    return check(
+      'local_mcp_lib_stale',
+      'local-repo',
+      'fail',
+      'Compiled mcp-server lib',
+      libNewest === null
+        ? 'mcp-server/lib is missing — the MCP server cannot serve current tools'
+        : 'mcp-server/lib is older than mcp-server/src — served tools are stale',
+      { type: 'auto', description: 'Rebuild mcp-server (npm run build in mcp-server/)', action: 'rebuild_mcp_lib' },
+    );
+  }
+  return check('local_mcp_lib_stale', 'local-repo', 'pass', 'Compiled mcp-server lib', 'lib is newer than src');
+}
+
+async function checkGitattributesDrift(ctx) {
+  const status = await ctx.exec('git', ['status', '--porcelain', '--', '.gitattributes'], { cwd: ctx.repoRoot });
+  if (status.code !== 0) return null; // not a git checkout — skip
+  if (!/^\s?M/m.test(status.stdout)) {
+    return check('local_gitattributes_drift', 'local-repo', 'pass', '.gitattributes drift', '.gitattributes is clean');
+  }
+
+  // Provable line-ending/whitespace-only proof: the whitespace-insensitive diff
+  // is empty while the file is modified.
+  const wsDiff = await ctx.exec(
+    'git',
+    ['diff', '--ignore-cr-at-eol', '--ignore-all-space', '--', '.gitattributes'],
+    { cwd: ctx.repoRoot },
+  );
+  if (wsDiff.stdout.trim() === '') {
+    return check(
+      'local_gitattributes_drift',
+      'local-repo',
+      'fail',
+      '.gitattributes drift',
+      '.gitattributes is modified but the diff is line-ending/whitespace-only — this silently blocks pull/push/worktree ops',
+      { type: 'auto', description: 'Restore .gitattributes from the index (git checkout -- .gitattributes)', action: 'restore_gitattributes' },
+    );
+  }
+  return check(
+    'local_gitattributes_drift',
+    'local-repo',
+    'warn',
+    '.gitattributes drift',
+    '.gitattributes has real content changes — review and commit or discard it manually (auto-restore refused)',
+  );
+}
+
+async function checkSchemaBehind(ctx) {
+  const dbUrl = ctx.env.DATABASE_URL || readRepoEnvVar(ctx, 'DATABASE_URL');
+  if (!dbUrl) {
+    return check(
+      'local_schema_behind',
+      'local-repo',
+      'pass',
+      'Local DB schema',
+      'Skipped — no DATABASE_URL configured for this checkout',
+    );
+  }
+
+  // Reuse the repo's own engine probe via the npm script (report-only) — the
+  // script carries the tsx loader the engine's extensionless .ts imports need.
+  const probe = await ctx.exec(
+    'npm',
+    ['run', 'doctor', '--', '--json', '--no-fix', '--category', 'database'],
+    { cwd: ctx.repoRoot, shell: ctx.platform === 'win32', timeout: 60_000, env: { ...ctx.env, DATABASE_URL: dbUrl } },
+  );
+  let result = null;
+  try {
+    // npm prepends a script banner before the JSON — parse from the first brace.
+    const stdout = probe.stdout || '';
+    result = JSON.parse(stdout.slice(stdout.indexOf('{')));
+  } catch {
+    return check(
+      'local_schema_behind',
+      'local-repo',
+      'warn',
+      'Local DB schema',
+      `Could not verify schema state (probe unreadable: ${(probe.stderr || probe.stdout || 'no output').slice(0, 120)}) — if you recently pulled schema changes, run npm run db:migrate`,
+    );
+  }
+
+  const schemaCheck = (result.checks || []).find((c) => c.id === 'db_schema');
+  if (schemaCheck && schemaCheck.status === 'fail') {
+    return check(
+      'local_schema_behind',
+      'local-repo',
+      'fail',
+      'Local DB schema',
+      `Local database schema is behind code: ${schemaCheck.message}. Until migrated, authenticated requests can 401`,
+      { type: 'auto', description: 'Apply pending schema (npm run db:migrate — idempotent)', action: 'run_db_migrate' },
+    );
+  }
+  return check('local_schema_behind', 'local-repo', 'pass', 'Local DB schema', 'Database schema matches code');
+}
+
+function readRepoEnvVar(ctx, name) {
+  for (const file of ['.env.local', '.env']) {
+    try {
+      const content = ctx.fs.readFileSync(join(ctx.repoRoot, file), 'utf8');
+      const match = content.match(new RegExp(`^\\s*${name}\\s*=\\s*(.+)$`, 'm'));
+      if (match) return match[1].trim().replace(/^["']|["']$/g, '');
+    } catch {
+      // file absent — keep looking
+    }
+  }
+  return null;
+}
+
+/** DETECT-ONLY: never mutates a gateway config. */
+async function checkOpenclawPlugin(ctx) {
+  const candidates = [
+    ctx.env.DASHCLAW_OPENCLAW_CONFIG,
+    join(ctx.homedir, '.openclaw', 'openclaw.json'),
+    join(ctx.cwd, 'openclaw.plugin.json'),
+  ].filter(Boolean);
+
+  let path = null;
+  for (const candidate of candidates) {
+    if (ctx.fs.existsSync(candidate)) {
+      path = candidate;
+      break;
+    }
+  }
+  if (!path) return null; // no gateway here — silent skip (matches server check)
+
+  let doc;
+  try {
+    doc = JSON.parse(ctx.fs.readFileSync(path, 'utf8'));
+  } catch (err) {
+    return check('local_openclaw_plugin', 'local-repo', 'warn', 'OpenClaw runtime plugin', `${path}: unparseable (${err.message}) — fix the JSON by hand; auto-repair of gateway configs is deliberately not supported`);
+  }
+
+  const entry = doc?.plugins?.entries?.['dashclaw-governance'] ?? (doc?.id === 'dashclaw-governance' ? doc : null);
+  if (!entry) return null; // plugin not installed here — silent skip
+
+  if (entry.enabled === false) {
+    return check(
+      'local_openclaw_plugin',
+      'local-repo',
+      'warn',
+      'OpenClaw runtime plugin',
+      `${path}: dashclaw-governance is disabled — gateway actions are NOT being governed. Re-enable it in the gateway config (set "enabled": true), then restart the gateway. Auto-mutation of gateway configs is deliberately not supported`,
+    );
+  }
+
+  const pluginPath = entry.path || entry.source || null;
+  if (pluginPath && !ctx.fs.existsSync(pluginPath)) {
+    return check(
+      'local_openclaw_plugin',
+      'local-repo',
+      'warn',
+      'OpenClaw runtime plugin',
+      `${path}: plugin path ${pluginPath} does not exist — the gateway will fail to load dashclaw-governance. Point it at a valid plugin checkout and restart the gateway`,
+    );
+  }
+
+  return check('local_openclaw_plugin', 'local-repo', 'pass', 'OpenClaw runtime plugin', 'dashclaw-governance entry looks healthy');
+}
+
+// ---------------------------------------------------------------------------
+// Machine checks
+// ---------------------------------------------------------------------------
+
+async function checkCliShimStale(ctx) {
+  let result;
+  try {
+    result = await ctx.exec('dashclaw', ['--version'], { shell: ctx.platform === 'win32', timeout: 15_000 });
+  } catch {
+    result = { notFound: true, code: -1, stdout: '' };
+  }
+  if (result.notFound || result.code !== 0) {
+    return check('local_cli_shim_stale', 'local-machine', 'pass', 'Global CLI shim', 'No global dashclaw shim on PATH');
+  }
+  const found = (result.stdout.match(/\d+\.\d+\.\d+/) || [])[0];
+  if (!found) {
+    return check('local_cli_shim_stale', 'local-machine', 'pass', 'Global CLI shim', 'Global shim did not report a version — skipped');
+  }
+  if (found !== ctx.cliVersion) {
+    return check(
+      'local_cli_shim_stale',
+      'local-machine',
+      'fail',
+      'Global CLI shim',
+      `PATH dashclaw is ${found}, current CLI is ${ctx.cliVersion} — stale shims shadow new commands`,
+      { type: 'auto', description: 'Reinstall the global CLI (npm i -g @dashclaw/cli)', action: 'reinstall_cli' },
+    );
+  }
+  return check('local_cli_shim_stale', 'local-machine', 'pass', 'Global CLI shim', `PATH dashclaw matches ${ctx.cliVersion}`);
+}
+
+function extractHookScriptPaths(command) {
+  // Tokenize respecting double quotes; keep tokens that look like file paths.
+  const tokens = command.match(/"[^"]+"|\S+/g) || [];
+  return tokens
+    .map((t) => t.replace(/^"|"$/g, ''))
+    .filter((t) => /[\\/]/.test(t) && /dashclaw/i.test(t) && /\.(py|cjs|mjs|js)$/i.test(t));
+}
+
+async function checkHooksTrust(ctx) {
+  const settingsPath = join(ctx.homedir, '.claude', 'settings.json');
+  let settings;
+  try {
+    settings = JSON.parse(ctx.fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    return check('local_hooks_trust', 'local-machine', 'pass', 'DashClaw Claude hooks', 'No global Claude settings — hooks not installed (skipped)');
+  }
+
+  const commands = [];
+  for (const eventEntries of Object.values(settings?.hooks || {})) {
+    if (!Array.isArray(eventEntries)) continue;
+    for (const entry of eventEntries) {
+      for (const hook of entry?.hooks || []) {
+        if (typeof hook?.command === 'string' && /dashclaw/i.test(hook.command)) {
+          commands.push(hook.command);
+        }
+      }
+    }
+  }
+  if (commands.length === 0) {
+    return check('local_hooks_trust', 'local-machine', 'pass', 'DashClaw Claude hooks', 'No DashClaw hooks installed (skipped)');
+  }
+
+  const missing = [];
+  for (const command of commands) {
+    for (const scriptPath of extractHookScriptPaths(command)) {
+      if (!ctx.fs.existsSync(scriptPath)) missing.push(scriptPath);
+    }
+  }
+  if (missing.length > 0) {
+    const installer = ctx.repoRoot
+      ? 'node scripts/install-hooks.mjs --global --governance'
+      : 'dashclaw install claude';
+    return check(
+      'local_hooks_trust',
+      'local-machine',
+      'fail',
+      'DashClaw Claude hooks',
+      `Hook script(s) missing: ${missing.join(', ')} — hooks silently no-op`,
+      { type: 'auto', description: `Re-run the hook installer (${installer})`, action: 'reinstall_hooks' },
+    );
+  }
+  return check('local_hooks_trust', 'local-machine', 'pass', 'DashClaw Claude hooks', `${commands.length} DashClaw hook(s) installed, scripts present`);
+}
+
+/** DETECT-ONLY: deleting user env vars is not trivially safe. */
+async function checkEnvLeak(ctx) {
+  const names = new Set();
+  const sources = [];
+
+  if (ctx.platform === 'win32') {
+    const scopes = [
+      { args: ['query', 'HKCU\\Environment'], label: 'User' },
+      { args: ['query', 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment'], label: 'Machine' },
+    ];
+    for (const scope of scopes) {
+      let result;
+      try {
+        result = await ctx.exec('reg', scope.args, { timeout: 15_000 });
+      } catch {
+        continue;
+      }
+      if (result.code !== 0) continue;
+      for (const match of result.stdout.matchAll(/^\s+(DASHCLAW_\w+)\s+REG_/gim)) {
+        names.add(match[1]);
+        sources.push(`${match[1]} (${scope.label} scope)`);
+      }
+    }
+    if (names.size > 0) {
+      const removal = [...names]
+        .map((n) => `[Environment]::SetEnvironmentVariable('${n}', $null, 'User')`)
+        .join('; ');
+      return check(
+        'local_env_leak',
+        'local-machine',
+        'warn',
+        'Leaked DASHCLAW_* env',
+        `Machine/user-scope env vars can shadow per-project config: ${sources.join(', ')}. To remove (PowerShell): ${removal}. Removal is manual by design`,
+      );
+    }
+  } else {
+    const profiles = ['.bashrc', '.zshrc', '.profile', '.bash_profile'];
+    for (const profile of profiles) {
+      let content;
+      try {
+        content = ctx.fs.readFileSync(join(ctx.homedir, profile), 'utf8');
+      } catch {
+        continue;
+      }
+      for (const match of content.matchAll(/^\s*(?:export\s+)?(DASHCLAW_\w+)\s*=/gm)) {
+        names.add(match[1]);
+        sources.push(`${match[1]} (~/${profile})`);
+      }
+    }
+    if (names.size > 0) {
+      return check(
+        'local_env_leak',
+        'local-machine',
+        'warn',
+        'Leaked DASHCLAW_* env',
+        `Shell-profile env vars can shadow per-project config: ${sources.join(', ')}. Remove the export lines from the listed profile(s) and restart your shell. Removal is manual by design`,
+      );
+    }
+  }
+
+  return check('local_env_leak', 'local-machine', 'pass', 'Leaked DASHCLAW_* env', 'No machine-scope DASHCLAW_* env vars found');
+}
+
+// ---------------------------------------------------------------------------
+// Runner + fixes
+// ---------------------------------------------------------------------------
+
+/**
+ * Run every applicable local check. Repo-aware checks run only when
+ * ctx.repoRoot is a DashClaw checkout; machine checks always run.
+ */
+export async function runLocalChecks(ctx) {
+  const checks = [];
+
+  if (ctx.repoRoot) {
+    for (const runner of [checkMcpLibStale, checkGitattributesDrift, checkSchemaBehind, checkOpenclawPlugin]) {
+      try {
+        const result = await runner(ctx);
+        if (result) checks.push(result);
+      } catch (err) {
+        checks.push(check(runner.name, 'local-repo', 'warn', runner.name, `Check errored: ${err.message}`));
+      }
+    }
+  }
+
+  for (const runner of [checkCliShimStale, checkHooksTrust, checkEnvLeak]) {
+    try {
+      const result = await runner(ctx);
+      if (result) checks.push(result);
+    } catch (err) {
+      checks.push(check(runner.name, 'local-machine', 'warn', runner.name, `Check errored: ${err.message}`));
+    }
+  }
+
+  return checks;
+}
+
+const LOCAL_FIX_HANDLERS = {
+  rebuild_mcp_lib: async (ctx) => {
+    const result = await ctx.exec('npm', ['run', 'build'], {
+      cwd: join(ctx.repoRoot, 'mcp-server'),
+      shell: ctx.platform === 'win32',
+      timeout: 300_000,
+    });
+    return result.code === 0
+      ? { applied: true, description: 'Rebuilt mcp-server/lib from src' }
+      : { applied: false, description: `mcp-server build failed: ${(result.stderr || result.stdout).slice(0, 200)}` };
+  },
+  restore_gitattributes: async (ctx) => {
+    const result = await ctx.exec('git', ['checkout', '--', '.gitattributes'], { cwd: ctx.repoRoot });
+    return result.code === 0
+      ? { applied: true, description: 'Restored .gitattributes from the index' }
+      : { applied: false, description: `git checkout failed: ${(result.stderr || '').slice(0, 200)}` };
+  },
+  run_db_migrate: async (ctx) => {
+    const result = await ctx.exec('npm', ['run', 'db:migrate'], {
+      cwd: ctx.repoRoot,
+      shell: ctx.platform === 'win32',
+      timeout: 300_000,
+    });
+    return result.code === 0
+      ? { applied: true, description: 'Applied pending schema via npm run db:migrate' }
+      : { applied: false, description: `db:migrate failed: ${(result.stderr || result.stdout).slice(0, 200)}` };
+  },
+  reinstall_cli: async (ctx) => {
+    const result = await ctx.exec('npm', ['i', '-g', '@dashclaw/cli'], {
+      shell: ctx.platform === 'win32',
+      timeout: 300_000,
+    });
+    return result.code === 0
+      ? { applied: true, description: 'Reinstalled the global @dashclaw/cli' }
+      : { applied: false, description: `npm i -g failed: ${(result.stderr || result.stdout).slice(0, 200)}` };
+  },
+  reinstall_hooks: async (ctx) => {
+    const result = ctx.repoRoot
+      ? await ctx.exec(process.execPath ?? 'node', ['scripts/install-hooks.mjs', '--global', '--governance'], {
+          cwd: ctx.repoRoot,
+          timeout: 120_000,
+        })
+      : await ctx.exec('dashclaw', ['install', 'claude'], { shell: ctx.platform === 'win32', timeout: 120_000 });
+    return result.code === 0
+      ? { applied: true, description: 'Re-ran the DashClaw hook installer' }
+      : { applied: false, description: `Hook installer failed: ${(result.stderr || result.stdout).slice(0, 200)}` };
+  },
+};
+
+/**
+ * Apply local auto-fixes for failing checks. Returns one result per attempted
+ * fix: { id, action, applied, description }.
+ */
+export async function applyLocalFixes(checks, ctx) {
+  const results = [];
+  for (const item of checks) {
+    if (!item?.fix || item.fix.type !== 'auto') continue;
+    const handler = LOCAL_FIX_HANDLERS[item.fix.action];
+    if (!handler) continue;
+    try {
+      const result = await handler(ctx);
+      results.push({ id: item.id, action: item.fix.action, ...result });
+    } catch (err) {
+      results.push({ id: item.id, action: item.fix.action, applied: false, description: `Fix errored: ${err.message}` });
+    }
+  }
+  return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dashclaw/cli",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "DashClaw terminal client — approve agent actions and diagnose your instance",
   "type": "module",
   "keywords": [