engrm 0.3.4 → 0.4.1

package/dist/cli.js

@@ -18,16 +18,16 @@ var __export = (target, all) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync6 } from "fs";
-import { hostname as hostname2, homedir as homedir3 } from "os";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync6, statSync } from "fs";
+import { hostname as hostname2, homedir as homedir3, networkInterfaces as networkInterfaces2 } from "os";
 import { join as join6 } from "path";
-import { randomBytes as randomBytes3 } from "crypto";
+import { createHash as createHash2 } from "crypto";
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir, hostname } from "node:os";
+import { homedir, hostname, networkInterfaces } from "node:os";
 import { join } from "node:path";
-import { randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
 var CONFIG_DIR = join(homedir(), ".engrm");
 var SETTINGS_PATH = join(CONFIG_DIR, "settings.json");
 var DB_PATH = join(CONFIG_DIR, "engrm.db");
@@ -42,7 +42,22 @@ function getDbPath() {
 }
 function generateDeviceId() {
   const host = hostname().toLowerCase().replace(/[^a-z0-9-]/g, "");
-  const suffix = randomBytes(4).toString("hex");
+  let mac = "";
+  const ifaces = networkInterfaces();
+  for (const entries of Object.values(ifaces)) {
+    if (!entries)
+      continue;
+    for (const entry of entries) {
+      if (!entry.internal && entry.mac && entry.mac !== "00:00:00:00:00:00") {
+        mac = entry.mac;
+        break;
+      }
+    }
+    if (mac)
+      break;
+  }
+  const material = `${host}:${mac || "no-mac"}`;
+  const suffix = createHash("sha256").update(material).digest("hex").slice(0, 8);
   return `${host}-${suffix}`;
 }
 function createDefaultConfig() {
@@ -84,7 +99,10 @@ function createDefaultConfig() {
     observer: {
       enabled: true,
       mode: "per_event",
-      model: "haiku"
+      model: "sonnet"
+    },
+    transcript_analysis: {
+      enabled: false
     }
   };
 }
@@ -143,6 +161,9 @@ function loadConfig() {
       enabled: asBool(config["observer"]?.["enabled"], defaults.observer.enabled),
       mode: asObserverMode(config["observer"]?.["mode"], defaults.observer.mode),
       model: asString(config["observer"]?.["model"], defaults.observer.model)
+    },
+    transcript_analysis: {
+      enabled: asBool(config["transcript_analysis"]?.["enabled"], defaults.transcript_analysis.enabled)
     }
   };
 }
@@ -1039,6 +1060,335 @@ function getOutboxStats(db) {
   return stats;
 }
 
+// src/storage/migrations.ts
+var MIGRATIONS2 = [
+  {
+    version: 1,
+    description: "Initial schema: projects, observations, sessions, sync, FTS5",
+    sql: `
+      -- Projects (canonical identity across machines)
+      CREATE TABLE projects (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          canonical_id    TEXT UNIQUE NOT NULL,
+          name            TEXT NOT NULL,
+          local_path      TEXT,
+          remote_url      TEXT,
+          first_seen_epoch INTEGER NOT NULL,
+          last_active_epoch INTEGER NOT NULL
+      );
+
+      -- Core observations table
+      CREATE TABLE observations (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id      TEXT,
+          project_id      INTEGER NOT NULL REFERENCES projects(id),
+          type            TEXT NOT NULL CHECK (type IN (
+              'bugfix', 'discovery', 'decision', 'pattern',
+              'change', 'feature', 'refactor', 'digest'
+          )),
+          title           TEXT NOT NULL,
+          narrative       TEXT,
+          facts           TEXT,
+          concepts        TEXT,
+          files_read      TEXT,
+          files_modified  TEXT,
+          quality         REAL DEFAULT 0.5 CHECK (quality BETWEEN 0.0 AND 1.0),
+          lifecycle       TEXT DEFAULT 'active' CHECK (lifecycle IN (
+              'active', 'aging', 'archived', 'purged', 'pinned'
+          )),
+          sensitivity     TEXT DEFAULT 'shared' CHECK (sensitivity IN (
+              'shared', 'personal', 'secret'
+          )),
+          user_id         TEXT NOT NULL,
+          device_id       TEXT NOT NULL,
+          agent           TEXT DEFAULT 'claude-code',
+          created_at      TEXT NOT NULL,
+          created_at_epoch INTEGER NOT NULL,
+          archived_at_epoch INTEGER,
+          compacted_into  INTEGER REFERENCES observations(id) ON DELETE SET NULL
+      );
+
+      -- Session tracking
+      CREATE TABLE sessions (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id      TEXT UNIQUE NOT NULL,
+          project_id      INTEGER REFERENCES projects(id),
+          user_id         TEXT NOT NULL,
+          device_id       TEXT NOT NULL,
+          agent           TEXT DEFAULT 'claude-code',
+          status          TEXT DEFAULT 'active' CHECK (status IN ('active', 'completed')),
+          observation_count INTEGER DEFAULT 0,
+          started_at_epoch INTEGER,
+          completed_at_epoch INTEGER
+      );
+
+      -- Session summaries (generated on Stop hook)
+      CREATE TABLE session_summaries (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id      TEXT UNIQUE NOT NULL,
+          project_id      INTEGER REFERENCES projects(id),
+          user_id         TEXT NOT NULL,
+          request         TEXT,
+          investigated    TEXT,
+          learned         TEXT,
+          completed       TEXT,
+          next_steps      TEXT,
+          created_at_epoch INTEGER
+      );
+
+      -- Sync outbox (offline-first queue)
+      CREATE TABLE sync_outbox (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          record_type     TEXT NOT NULL CHECK (record_type IN ('observation', 'summary')),
+          record_id       INTEGER NOT NULL,
+          status          TEXT DEFAULT 'pending' CHECK (status IN (
+              'pending', 'syncing', 'synced', 'failed'
+          )),
+          retry_count     INTEGER DEFAULT 0,
+          max_retries     INTEGER DEFAULT 10,
+          last_error      TEXT,
+          created_at_epoch INTEGER NOT NULL,
+          synced_at_epoch  INTEGER,
+          next_retry_epoch INTEGER
+      );
+
+      -- Sync high-water mark and lifecycle job tracking
+      CREATE TABLE sync_state (
+          key   TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+      );
+
+      -- FTS5 for local offline search (external content mode)
+      CREATE VIRTUAL TABLE observations_fts USING fts5(
+          title, narrative, facts, concepts,
+          content=observations,
+          content_rowid=id
+      );
+
+      -- Indexes: observations
+      CREATE INDEX idx_observations_project ON observations(project_id);
+      CREATE INDEX idx_observations_project_lifecycle ON observations(project_id, lifecycle);
+      CREATE INDEX idx_observations_type ON observations(type);
+      CREATE INDEX idx_observations_created ON observations(created_at_epoch);
+      CREATE INDEX idx_observations_session ON observations(session_id);
+      CREATE INDEX idx_observations_lifecycle ON observations(lifecycle);
+      CREATE INDEX idx_observations_quality ON observations(quality);
+      CREATE INDEX idx_observations_user ON observations(user_id);
+
+      -- Indexes: sessions
+      CREATE INDEX idx_sessions_project ON sessions(project_id);
+
+      -- Indexes: sync outbox
+      CREATE INDEX idx_outbox_status ON sync_outbox(status, next_retry_epoch);
+      CREATE INDEX idx_outbox_record ON sync_outbox(record_type, record_id);
+    `
+  },
+  {
+    version: 2,
+    description: "Add superseded_by for knowledge supersession",
+    sql: `
+      ALTER TABLE observations ADD COLUMN superseded_by INTEGER REFERENCES observations(id) ON DELETE SET NULL;
+      CREATE INDEX idx_observations_superseded ON observations(superseded_by);
+    `
+  },
+  {
+    version: 3,
+    description: "Add remote_source_id for pull deduplication",
+    sql: `
+      ALTER TABLE observations ADD COLUMN remote_source_id TEXT;
+      CREATE UNIQUE INDEX idx_observations_remote_source ON observations(remote_source_id) WHERE remote_source_id IS NOT NULL;
+    `
+  },
+  {
+    version: 4,
+    description: "Add sqlite-vec for local semantic search",
+    sql: `
+      CREATE VIRTUAL TABLE vec_observations USING vec0(
+        observation_id INTEGER PRIMARY KEY,
+        embedding float[384]
+      );
+    `,
+    condition: (db) => isVecExtensionLoaded2(db)
+  },
+  {
+    version: 5,
+    description: "Session metrics and security findings",
+    sql: `
+      ALTER TABLE sessions ADD COLUMN files_touched_count INTEGER DEFAULT 0;
+      ALTER TABLE sessions ADD COLUMN searches_performed INTEGER DEFAULT 0;
+      ALTER TABLE sessions ADD COLUMN tool_calls_count INTEGER DEFAULT 0;
+
+      CREATE TABLE security_findings (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id      TEXT,
+          project_id      INTEGER NOT NULL REFERENCES projects(id),
+          finding_type    TEXT NOT NULL,
+          severity        TEXT NOT NULL DEFAULT 'medium' CHECK (severity IN ('critical', 'high', 'medium', 'low')),
+          pattern_name    TEXT NOT NULL,
+          file_path       TEXT,
+          snippet         TEXT,
+          tool_name       TEXT,
+          user_id         TEXT NOT NULL,
+          device_id       TEXT NOT NULL,
+          created_at_epoch INTEGER NOT NULL
+      );
+
+      CREATE INDEX idx_security_findings_session ON security_findings(session_id);
+      CREATE INDEX idx_security_findings_project ON security_findings(project_id, created_at_epoch);
+      CREATE INDEX idx_security_findings_severity ON security_findings(severity);
+    `
+  },
+  {
+    version: 6,
+    description: "Add risk_score, expand observation types to include standard",
+    sql: `
+      ALTER TABLE sessions ADD COLUMN risk_score INTEGER;
+
+      -- Recreate observations table with expanded type CHECK to include 'standard'
+      -- SQLite doesn't support ALTER CHECK, so we recreate the table
+      CREATE TABLE observations_new (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id      TEXT,
+          project_id      INTEGER NOT NULL REFERENCES projects(id),
+          type            TEXT NOT NULL CHECK (type IN (
+              'bugfix', 'discovery', 'decision', 'pattern',
+              'change', 'feature', 'refactor', 'digest', 'standard'
+          )),
+          title           TEXT NOT NULL,
+          narrative       TEXT,
+          facts           TEXT,
+          concepts        TEXT,
+          files_read      TEXT,
+          files_modified  TEXT,
+          quality         REAL DEFAULT 0.5 CHECK (quality BETWEEN 0.0 AND 1.0),
+          lifecycle       TEXT DEFAULT 'active' CHECK (lifecycle IN (
+              'active', 'aging', 'archived', 'purged', 'pinned'
+          )),
+          sensitivity     TEXT DEFAULT 'shared' CHECK (sensitivity IN (
+              'shared', 'personal', 'secret'
+          )),
+          user_id         TEXT NOT NULL,
+          device_id       TEXT NOT NULL,
+          agent           TEXT DEFAULT 'claude-code',
+          created_at      TEXT NOT NULL,
+          created_at_epoch INTEGER NOT NULL,
+          archived_at_epoch INTEGER,
+          compacted_into  INTEGER REFERENCES observations(id) ON DELETE SET NULL,
+          superseded_by   INTEGER REFERENCES observations(id) ON DELETE SET NULL,
+          remote_source_id TEXT
+      );
+
+      INSERT INTO observations_new SELECT * FROM observations;
+
+      DROP TABLE observations;
+      ALTER TABLE observations_new RENAME TO observations;
+
+      -- Recreate indexes
+      CREATE INDEX idx_observations_project ON observations(project_id);
+      CREATE INDEX idx_observations_project_lifecycle ON observations(project_id, lifecycle);
+      CREATE INDEX idx_observations_type ON observations(type);
+      CREATE INDEX idx_observations_created ON observations(created_at_epoch);
+      CREATE INDEX idx_observations_session ON observations(session_id);
+      CREATE INDEX idx_observations_lifecycle ON observations(lifecycle);
+      CREATE INDEX idx_observations_quality ON observations(quality);
+      CREATE INDEX idx_observations_user ON observations(user_id);
+      CREATE INDEX idx_observations_superseded ON observations(superseded_by);
+      CREATE UNIQUE INDEX idx_observations_remote_source ON observations(remote_source_id) WHERE remote_source_id IS NOT NULL;
+
+      -- Recreate FTS5 (external content mode — must rebuild after table recreation)
+      DROP TABLE IF EXISTS observations_fts;
+      CREATE VIRTUAL TABLE observations_fts USING fts5(
+          title, narrative, facts, concepts,
+          content=observations,
+          content_rowid=id
+      );
+      -- Rebuild FTS index
+      INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
+    `
+  },
+  {
+    version: 7,
+    description: "Add packs_installed table for help pack tracking",
+    sql: `
+      CREATE TABLE IF NOT EXISTS packs_installed (
+          name            TEXT PRIMARY KEY,
+          installed_at    INTEGER NOT NULL,
+          observation_count INTEGER DEFAULT 0
+      );
+    `
+  },
+  {
+    version: 8,
+    description: "Add message type to observations CHECK constraint",
+    sql: `
+      CREATE TABLE IF NOT EXISTS observations_v8 (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id      TEXT,
+          project_id      INTEGER NOT NULL REFERENCES projects(id),
+          type            TEXT NOT NULL CHECK (type IN (
+              'bugfix', 'discovery', 'decision', 'pattern',
+              'change', 'feature', 'refactor', 'digest', 'standard', 'message'
+          )),
+          title           TEXT NOT NULL,
+          narrative       TEXT,
+          facts           TEXT,
+          concepts        TEXT,
+          files_read      TEXT,
+          files_modified  TEXT,
+          quality         REAL DEFAULT 0.5 CHECK (quality BETWEEN 0.0 AND 1.0),
+          lifecycle       TEXT DEFAULT 'active' CHECK (lifecycle IN (
+              'active', 'aging', 'archived', 'purged', 'pinned'
+          )),
+          sensitivity     TEXT DEFAULT 'shared' CHECK (sensitivity IN (
+              'shared', 'personal', 'secret'
+          )),
+          user_id         TEXT NOT NULL,
+          device_id       TEXT NOT NULL,
+          agent           TEXT DEFAULT 'claude-code',
+          created_at      TEXT NOT NULL,
+          created_at_epoch INTEGER NOT NULL,
+          archived_at_epoch INTEGER,
+          compacted_into  INTEGER REFERENCES observations(id) ON DELETE SET NULL,
+          superseded_by   INTEGER REFERENCES observations(id) ON DELETE SET NULL,
+          remote_source_id TEXT
+      );
+      INSERT INTO observations_v8 SELECT * FROM observations;
+      DROP TABLE observations;
+      ALTER TABLE observations_v8 RENAME TO observations;
+      CREATE INDEX idx_observations_project ON observations(project_id);
+      CREATE INDEX idx_observations_project_lifecycle ON observations(project_id, lifecycle);
+      CREATE INDEX idx_observations_type ON observations(type);
+      CREATE INDEX idx_observations_created ON observations(created_at_epoch);
+      CREATE INDEX idx_observations_session ON observations(session_id);
+      CREATE INDEX idx_observations_lifecycle ON observations(lifecycle);
+      CREATE INDEX idx_observations_quality ON observations(quality);
+      CREATE INDEX idx_observations_user ON observations(user_id);
+      CREATE INDEX idx_observations_superseded ON observations(superseded_by);
+      CREATE UNIQUE INDEX idx_observations_remote_source ON observations(remote_source_id) WHERE remote_source_id IS NOT NULL;
+      DROP TABLE IF EXISTS observations_fts;
+      CREATE VIRTUAL TABLE observations_fts USING fts5(
+          title, narrative, facts, concepts,
+          content=observations,
+          content_rowid=id
+      );
+      INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
+    `
+  }
+];
+function isVecExtensionLoaded2(db) {
+  try {
+    db.exec("SELECT vec_version()");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getSchemaVersion(db) {
+  const result = db.query("PRAGMA user_version").get();
+  return result.user_version;
+}
+var LATEST_SCHEMA_VERSION2 = MIGRATIONS2.filter((m) => !m.condition).reduce((max, m) => Math.max(max, m.version), 0);
+
 // src/provisioning/provision.ts
 var DEFAULT_CANDENGO_URL = "https://www.candengo.com";
 
@@ -1086,12 +1436,12 @@ async function provision(baseUrl, request) {
 }
 
 // src/provisioning/browser-auth.ts
-import { randomBytes as randomBytes2 } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { execFile } from "node:child_process";
 var CALLBACK_TIMEOUT_MS = 120000;
 async function runBrowserAuth(candengoUrl) {
-  const state = randomBytes2(16).toString("hex");
+  const state = randomBytes(16).toString("hex");
   const { port, waitForCallback, stop } = await startCallbackServer(state);
   const redirectUri = `http://localhost:${port}/callback`;
   const authUrl = new URL("/connect/mem", candengoUrl);
@@ -1317,7 +1667,7 @@ function registerHooks() {
     hooks: [{ type: "command", command: preToolUseCmd }]
   }, "sentinel");
   hooks["PostToolUse"] = replaceEngrmHook(hooks["PostToolUse"], {
-    matcher: "Edit|Write|Bash|Read|mcp__.*",
+    matcher: "Edit|Write|Bash|Read|Grep|Glob|WebSearch|WebFetch|mcp__.*",
     hooks: [{ type: "command", command: postToolUseCmd }]
   }, "post-tool-use");
   hooks["ElicitationResult"] = replaceEngrmHook(hooks["ElicitationResult"], {
@@ -2214,6 +2564,9 @@ switch (command) {
   case "sentinel":
     await handleSentinel(args.slice(1));
     break;
+  case "doctor":
+    await handleDoctor();
+    break;
   default:
     printUsage();
     break;
@@ -2313,6 +2666,7 @@ async function initWithToken(baseUrl, token) {
     console.log(`
 Connected as ${result.user_email}`);
     printPostInit();
+    await checkDeviceLimits(baseUrl, result.api_key);
   } catch (error) {
     if (error instanceof ProvisionError) {
       console.error(`
@@ -2338,6 +2692,7 @@ async function initWithBrowser(baseUrl) {
     console.log(`
 Connected as ${result.user_email}`);
     printPostInit();
+    await checkDeviceLimits(baseUrl, result.api_key);
   } catch (error) {
     if (error instanceof ProvisionError) {
       console.error(`
@@ -2395,6 +2750,14 @@ function writeConfigFromProvision(baseUrl, result) {
       skip_patterns: [],
       daily_limit: 100,
       tier: "free"
+    },
+    observer: {
+      enabled: true,
+      mode: "per_event",
+      model: "haiku"
+    },
+    transcript_analysis: {
+      enabled: false
     }
   };
   saveConfig(config);
@@ -2469,6 +2832,14 @@ function initFromFile(configPath) {
       skip_patterns: [],
       daily_limit: 100,
       tier: "free"
+    },
+    observer: {
+      enabled: true,
+      mode: "per_event",
+      model: "haiku"
+    },
+    transcript_analysis: {
+      enabled: false
     }
   };
   saveConfig(config);
@@ -2534,6 +2905,14 @@ async function initManual() {
       skip_patterns: [],
       daily_limit: 100,
       tier: "free"
+    },
+    observer: {
+      enabled: true,
+      mode: "per_event",
+      model: "haiku"
+    },
+    transcript_analysis: {
+      enabled: false
     }
   };
   saveConfig(config);
@@ -2719,7 +3098,22 @@ function ensureConfigDir() {
 }
 function generateDeviceId2() {
   const host = hostname2().toLowerCase().replace(/[^a-z0-9-]/g, "");
-  const suffix = randomBytes3(4).toString("hex");
+  let mac = "";
+  const ifaces = networkInterfaces2();
+  for (const entries of Object.values(ifaces)) {
+    if (!entries)
+      continue;
+    for (const entry of entries) {
+      if (!entry.internal && entry.mac && entry.mac !== "00:00:00:00:00:00") {
+        mac = entry.mac;
+        break;
+      }
+    }
+    if (mac)
+      break;
+  }
+  const material = `${host}:${mac || "no-mac"}`;
+  const suffix = createHash2("sha256").update(material).digest("hex").slice(0, 8);
   return `${host}-${suffix}`;
 }
 async function handleInstallPack(flags) {
@@ -2819,6 +3213,231 @@ Restart Claude Code to use the new version.`);
     console.error("Update failed. Try manually: npm install -g engrm@latest");
   }
 }
+async function handleDoctor() {
+  const results = [];
+  const pass = (msg) => results.push({ symbol: "\u2713", message: msg, kind: "pass" });
+  const fail = (msg) => results.push({ symbol: "\u2717", message: msg, kind: "fail" });
+  const warn = (msg) => results.push({ symbol: "\u26A0", message: msg, kind: "warn" });
+  const info = (msg) => results.push({ symbol: "\u2139", message: msg, kind: "info" });
+  if (configExists()) {
+    pass("Configuration file exists");
+  } else {
+    fail("Configuration file not found \u2014 run: engrm init");
+    printDoctorReport(results);
+    return;
+  }
+  let config = null;
+  try {
+    config = loadConfig();
+    pass("Configuration is valid");
+  } catch (err) {
+    fail(`Configuration is invalid: ${err instanceof Error ? err.message : String(err)}`);
+    printDoctorReport(results);
+    return;
+  }
+  let db = null;
+  try {
+    db = new MemDatabase(getDbPath());
+    pass("Database opens successfully");
+  } catch (err) {
+    fail(`Database failed to open: ${err instanceof Error ? err.message : String(err)}`);
+    printDoctorReport(results);
+    return;
+  }
+  try {
+    const currentVersion = getSchemaVersion(db.db);
+    if (currentVersion >= LATEST_SCHEMA_VERSION2) {
+      pass(`Database schema is current (v${currentVersion})`);
+    } else {
+      warn(`Database schema is outdated (v${currentVersion}, latest is v${LATEST_SCHEMA_VERSION2})`);
+    }
+  } catch {
+    warn("Could not check database schema version");
+  }
+  const claudeJson = join6(homedir3(), ".claude.json");
+  try {
+    if (existsSync6(claudeJson)) {
+      const content = readFileSync6(claudeJson, "utf-8");
+      if (content.includes('"engrm"')) {
+        pass("MCP server registered in Claude Code");
+      } else {
+        warn("MCP server not registered in Claude Code \u2014 run: engrm init");
+      }
+    } else {
+      warn("Claude Code config not found (~/.claude.json)");
+    }
+  } catch {
+    warn("Could not check MCP server registration");
+  }
+  const claudeSettings = join6(homedir3(), ".claude", "settings.json");
+  try {
+    if (existsSync6(claudeSettings)) {
+      const content = readFileSync6(claudeSettings, "utf-8");
+      let hookCount = 0;
+      try {
+        const settings = JSON.parse(content);
+        const hooks = settings?.hooks ?? {};
+        for (const entries of Object.values(hooks)) {
+          if (Array.isArray(entries)) {
+            for (const entry of entries) {
+              const e = entry;
+              if (e.hooks?.some((h) => h.command?.includes("engrm") || h.command?.includes("session-start") || h.command?.includes("sentinel") || h.command?.includes("post-tool-use") || h.command?.includes("pre-compact") || h.command?.includes("stop") || h.command?.includes("elicitation"))) {
+                hookCount++;
+              }
+            }
+          }
+        }
+      } catch {}
+      if (hookCount > 0) {
+        pass(`Hooks registered (${hookCount} hook${hookCount === 1 ? "" : "s"})`);
+      } else {
+        warn("No Engrm hooks found in Claude Code settings");
+      }
+    } else {
+      warn("Claude Code settings not found (~/.claude/settings.json)");
+    }
+  } catch {
+    warn("Could not check hooks registration");
+  }
+  if (config.candengo_url) {
+    try {
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), 5000);
+      const start = Date.now();
+      const res = await fetch(`${config.candengo_url}/health`, { signal: controller.signal });
+      clearTimeout(timeout);
+      const elapsed = Date.now() - start;
+      if (res.ok) {
+        const host = new URL(config.candengo_url).hostname;
+        pass(`Server connectivity (${host}, ${elapsed}ms)`);
+      } else {
+        fail(`Server returned HTTP ${res.status}`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      fail(`Server unreachable: ${msg.includes("abort") ? "timeout (5s)" : msg}`);
+    }
+  } else {
+    fail("Server URL not configured");
+  }
+  if (config.candengo_url && config.candengo_api_key) {
+    try {
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), 5000);
+      const res = await fetch(`${config.candengo_url}/v1/account/me`, {
+        headers: { Authorization: `Bearer ${config.candengo_api_key}` },
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+      if (res.ok) {
+        const data = await res.json();
+        const email = data.email ?? config.user_email ?? "unknown";
+        pass(`Authentication valid (${email})`);
+      } else if (res.status === 401 || res.status === 403) {
+        fail("Authentication failed \u2014 API key may be expired");
+      } else {
+        fail(`Authentication check returned HTTP ${res.status}`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      fail(`Authentication check failed: ${msg.includes("abort") ? "timeout (5s)" : msg}`);
+    }
+  } else {
+    fail("Authentication not configured (missing URL or API key)");
+  }
+  try {
+    const outbox = getOutboxStats(db);
+    const failedCount = outbox["failed"] ?? 0;
+    if (failedCount > 10) {
+      warn(`Sync has stuck items (${failedCount} failed in outbox)`);
+    } else {
+      const pending = outbox["pending"] ?? 0;
+      pass(`Sync outbox healthy (${pending} pending, ${failedCount} failed)`);
+    }
+  } catch {
+    warn("Could not check sync outbox");
+  }
+  if (db.vecAvailable) {
+    pass("Embedding model available (sqlite-vec loaded)");
+  } else {
+    warn("Embedding model not available (FTS5 fallback active)");
+  }
+  try {
+    const totalActive = db.getActiveObservationCount();
+    if (totalActive > 0) {
+      let breakdownParts = [];
+      try {
+        const byLifecycle = db.db.query(`SELECT lifecycle, COUNT(*) as count FROM observations
+             WHERE superseded_by IS NULL AND lifecycle IN ('active', 'aging', 'pinned')
+             GROUP BY lifecycle`).all();
+        breakdownParts = byLifecycle.map((r) => `${r.lifecycle}: ${r.count.toLocaleString()}`);
+      } catch {}
+      const detail = breakdownParts.length > 0 ? ` (${breakdownParts.join(", ")})` : "";
+      pass(`${totalActive.toLocaleString()} observations${detail}`);
+    } else {
+      warn("No observations yet \u2014 start a Claude Code session to capture context");
+    }
+  } catch {
+    warn("Could not count observations");
+  }
+  try {
+    const dbPath = getDbPath();
+    if (existsSync6(dbPath)) {
+      const stats = statSync(dbPath);
+      const sizeMB = stats.size / (1024 * 1024);
+      const sizeStr = sizeMB >= 1 ? `${sizeMB.toFixed(1)} MB` : `${(stats.size / 1024).toFixed(0)} KB`;
+      info(`Database size: ${sizeStr}`);
+    }
+  } catch {}
+  db.close();
+  printDoctorReport(results);
+}
+function printDoctorReport(results) {
+  console.log(`
+Engrm Doctor \u2014 Diagnostic Report
+`);
+  for (const r of results) {
+    console.log(`  ${r.symbol} ${r.message}`);
+  }
+  const passes = results.filter((r) => r.kind === "pass").length;
+  const fails = results.filter((r) => r.kind === "fail").length;
+  const warns = results.filter((r) => r.kind === "warn").length;
+  const checks = results.filter((r) => r.kind !== "info").length;
+  const parts = [];
+  if (warns > 0)
+    parts.push(`${warns} warning${warns === 1 ? "" : "s"}`);
+  if (fails > 0)
+    parts.push(`${fails} failure${fails === 1 ? "" : "s"}`);
+  const summary = `${passes}/${checks} checks passed` + (parts.length > 0 ? `, ${parts.join(", ")}` : "");
+  console.log(`
+  ${summary}`);
+}
+async function checkDeviceLimits(baseUrl, apiKey) {
+  try {
+    const controller = new AbortController;
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    const resp = await fetch(`${baseUrl}/v1/mem/billing`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    if (!resp.ok)
+      return;
+    const billing = await resp.json();
+    const limits = billing.limits || {};
+    const usage = billing.usage || {};
+    if (limits.max_devices && usage.devices && usage.devices >= limits.max_devices) {
+      const upgradeUrl = billing.upgrade_url || "https://engrm.dev/billing";
+      console.warn(`
+\u26A0\uFE0F  Device limit reached (${usage.devices}/${limits.max_devices}).`);
+      console.warn(`   This device may not sync. Upgrade at: ${upgradeUrl}`);
+    }
+    if (limits.max_observations && usage.observations && usage.observations >= limits.max_observations) {
+      console.warn(`\u26A0\uFE0F  Observation limit reached (${usage.observations.toLocaleString()}/${limits.max_observations.toLocaleString()}).`);
+      console.warn(`   New observations won't sync until you upgrade or delete old data.`);
+    }
+  } catch {}
+}
 function printPostInit() {
   console.log(`
 Registering with Claude Code...`);
@@ -2860,6 +3479,7 @@ function printUsage() {
   console.log("  engrm update                Update to latest version");
   console.log("  engrm packs                 List available starter packs");
   console.log("  engrm install-pack <name>   Install a starter pack");
+  console.log("  engrm doctor                Run diagnostic checks");
   console.log("  engrm sentinel              Sentinel code audit commands");
   console.log("  engrm sentinel init-rules   Install Sentinel rule packs");
 }