xtrm-tools 0.5.23 → 0.5.25

package/README.md

@@ -2,7 +2,7 @@
 
 > **Dual-runtime workflow system** — Claude Code plugin + Pi extension suite for workflow enforcement, code quality gates, issue tracking, and development automation.
 
-**Version 0.5.10** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
+**Version 0.5.24** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
 
 ---
 
@@ -80,9 +80,10 @@ Policies are the **single source of truth** for all enforcement rules. Located i
 | `session-flow.json` | both | Claim sync, stop gate, `xt end` reminder |
 | `beads.json` | both | Issue tracking gates |
 | `quality-gates.json` | both | Linting/typechecking |
-| `branch-state.json` | claude | Branch context injection |
+| `quality-gates-env.json` | both | Warns if tsc/ruff/eslint missing at session start |
+| `using-xtrm.json` | claude | Injects using-xtrm session manual at SessionStart |
 | `gitnexus.json` | claude | Knowledge graph enrichment |
-| `serena.json` | claude | Serena LSP workflow reminder |
+| `worktree-boundary.json` | claude | Blocks edits outside worktree when in `.xtrm/worktrees` |
 | `service-skills.json` | pi | Territory-based skill activation |
 
 ### Compiler
@@ -111,6 +112,8 @@ xtrm <command> [options]
 | `worktree clean` | Remove worktrees whose branch has been merged |
 | `claude` | Launch Claude Code in a sandboxed worktree |
 | `pi` | Launch Pi in a sandboxed worktree |
+| `docs show` | Display frontmatter for README, CHANGELOG, docs/*.md |
+| `debug` | Watch xtrm hook and bd lifecycle events in real time |
 
 ### Flags
 
@@ -186,6 +189,9 @@ bd close <id> --reason "Done"  # Close when done
 
 | Version | Date | Highlights |
 |---------|------|------------|
+| 0.5.24 | 2026-03-21 | Hash-based docs drift detection; CLI docs cleanup; `docs` and `debug` commands documented |
+| 0.5.23 | 2026-03-21 | `xtrm debug` command for real-time event monitoring |
+| 0.5.20 | 2026-03-21 | `xtrm docs show` command; worktree-boundary hook; statusline injection |
 | 0.5.10 | 2026-03-21 | Install cleanup: removes stale `~/.claude/hooks/` + `~/.claude/skills/`; Qwen/Gemini dead code removed |
 | 0.5.9 | 2026-03-20 | Worktrees moved inside repo under `.xtrm/worktrees/` |
 | 0.5.8 | 2026-03-20 | session-flow rewrite: claim sync, stop gate, `xt end` reminder |

package/cli/dist/index.cjs

@@ -41303,14 +41303,15 @@ function resolveStatuslineScript() {
   const pluginsFile = import_node_path5.default.join((0, import_node_os5.homedir)(), ".claude", "plugins", "installed_plugins.json");
   try {
     const plugins = JSON.parse((0, import_node_fs4.readFileSync)(pluginsFile, "utf8"));
-    const entries = plugins?.plugins?.["xtrm-tools@xtrm-tools"];
-    if (entries?.length > 0) {
-      return import_node_path5.default.join(entries[0].installPath, "hooks", "statusline.mjs");
+    for (const [key, entries] of Object.entries(plugins?.plugins ?? {})) {
+      if (!key.startsWith("xtrm-tools@") || !entries?.length) continue;
+      const p = import_node_path5.default.join(entries[0].installPath, "hooks", "statusline.mjs");
+      if ((0, import_node_fs4.existsSync)(p)) return p;
     }
   } catch {
   }
   const fallback = import_node_path5.default.join((0, import_node_os5.homedir)(), ".claude", "hooks", "statusline.mjs");
-  return fallback;
+  return (0, import_node_fs4.existsSync)(fallback) ? fallback : null;
 }
 async function launchWorktreeSession(opts) {
   const { runtime, name } = opts;
@@ -55983,11 +55984,12 @@ var import_path18 = __toESM(require("path"), 1);
 var import_fs_extra17 = __toESM(require_lib2(), 1);
 var HOOK_CATALOG = [
   { file: "using-xtrm-reminder.mjs", event: "SessionStart", desc: "Injects using-xtrm session operating manual into system prompt" },
-  { file: "serena-workflow-reminder.py", event: "SessionStart", desc: "Injects Serena semantic editing workflow reminder" },
   { file: "gitnexus/gitnexus-hook.cjs", event: "PostToolUse", desc: "Adds GitNexus context for search and Serena tooling" },
-  { file: "branch-state.mjs", event: "UserPromptSubmit", desc: "Injects current git branch into prompt context" },
   { file: "quality-check.cjs", event: "PostToolUse", desc: "Runs JS/TS quality checks on mutating edits" },
   { file: "quality-check.py", event: "PostToolUse", desc: "Runs Python quality checks on mutating edits" },
+  { file: "quality-check-env.mjs", event: "SessionStart", desc: "Warns if tsc/ruff/eslint are missing at session start" },
+  { file: "worktree-boundary.mjs", event: "PreToolUse", desc: "Blocks edits outside .xtrm/worktrees when in worktree session" },
+  { file: "statusline.mjs", event: "statusLine", desc: "Renders 2-line status: XTRM model branch + claim/open issues" },
   { file: "beads-edit-gate.mjs", event: "PreToolUse", desc: "Blocks file edits if no beads issue is claimed", beads: true },
   { file: "beads-commit-gate.mjs", event: "PreToolUse", desc: "Blocks commits when no beads issue is in progress", beads: true },
   { file: "beads-stop-gate.mjs", event: "Stop", desc: "Blocks stop when there is an unclosed in_progress claim", beads: true },
@@ -56009,22 +56011,6 @@ async function readSkillsFromDir(dir) {
   }
   return skills;
 }
-async function readProjectSkillsFromDir(dir) {
-  if (!await import_fs_extra17.default.pathExists(dir)) return [];
-  const entries = await import_fs_extra17.default.readdir(dir);
-  const skills = [];
-  for (const name of entries.sort()) {
-    const readme = import_path18.default.join(dir, name, "README.md");
-    if (!await import_fs_extra17.default.pathExists(readme)) continue;
-    const content = await import_fs_extra17.default.readFile(readme, "utf8");
-    const descLine = content.split("\n").find((line) => {
-      const trimmed = line.trim();
-      return Boolean(trimmed) && !trimmed.startsWith("#") && !trimmed.startsWith("[") && !trimmed.startsWith("<");
-    }) || "";
-    skills.push({ name, desc: descLine.replace(/[*_`]/g, "").trim() });
-  }
-  return skills;
-}
 function resolvePkgRootFallback() {
   const candidates = [
     import_path18.default.resolve(__dirname, "../.."),
@@ -56048,9 +56034,7 @@ function createHelpCommand() {
     }
     const pkgRoot = resolvePkgRootFallback();
     const skillsRoot = repoRoot || pkgRoot || "";
-    const projectSkillsRoot = repoRoot || pkgRoot || "";
     const skills = skillsRoot ? await readSkillsFromDir(import_path18.default.join(skillsRoot, "skills")) : [];
-    const projectSkills = projectSkillsRoot ? await readProjectSkillsFromDir(import_path18.default.join(projectSkillsRoot, "project-skills")) : [];
     const W = 80;
     const hr = kleur_default.dim("-".repeat(W));
     const section = (title) => `
@@ -56059,24 +56043,11 @@ ${hr}`;
     const installSection = [
       section("INSTALL COMMANDS"),
       "",
-      `  ${kleur_default.bold("xtrm install all")}`,
-      `    ${kleur_default.dim("Global install: skills + all hooks (including beads gates) + MCP servers.")}`,
+      `  ${kleur_default.bold("xtrm install")}`,
+      `    ${kleur_default.dim("Install plugin + skills + hooks + MCP servers.")}`,
       `    ${kleur_default.dim("Checks for beads+dolt and prompts to install if missing.")}`,
       "",
-      `  ${kleur_default.bold("xtrm install basic")}`,
-      `    ${kleur_default.dim("Global install: skills + general hooks + MCP servers.")}`,
-      `    ${kleur_default.dim("No beads dependency -- safe to run with zero external deps.")}`,
-      "",
-      `  ${kleur_default.bold("xtrm install project")} ${kleur_default.dim("<tool-name | all>")}`,
-      `    ${kleur_default.dim("Project-scoped install into .claude/ of current git root.")}`,
-      `    ${kleur_default.dim("Run xtrm install project list to see available project skills.")}`,
-      "",
-      `  ${kleur_default.dim("Default target directories:")}`,
-      `    ${kleur_default.dim("~/.claude/hooks     (global hook scripts)")}`,
-      `    ${kleur_default.dim("~/.claude/skills    (global Claude skills)")}`,
-      `    ${kleur_default.dim("~/.agents/skills    (agents skills cache mirror)")}`,
-      "",
-      `  ${kleur_default.dim("Flags (all profiles): --dry-run  --yes / -y  --no-mcp  --force  --prune  --backport")}`
+      `  ${kleur_default.dim("Flags: --dry-run  --yes / -y  --no-mcp  --force  --prune  --backport")}`
     ].join("\n");
     const general = HOOK_CATALOG.filter((h) => !h.beads && !h.sessionFlow);
     const beads = HOOK_CATALOG.filter((h) => h.beads);
@@ -56106,23 +56077,14 @@ ${hr}`;
       "",
       skills.length ? skillRows : kleur_default.dim("  (none found -- run from repo root to see skills)")
     ].join("\n");
-    const psRows = projectSkills.map(
-      (s) => `  ${kleur_default.white(col(s.name, 30))}${kleur_default.dim(s.desc)}`
-    ).join("\n");
-    const psSection = [
-      section("PROJECT SKILLS + HOOKS"),
-      "",
-      projectSkills.length ? psRows : kleur_default.dim("  (none found in package)"),
-      "",
-      `  ${kleur_default.dim("Install: xtrm install project <name>  |  xtrm install project list")}`,
-      `  ${kleur_default.dim("Each project skill can install .claude/skills plus project hooks/settings.")}`
-    ].join("\n");
     const otherSection = [
       section("OTHER COMMANDS"),
       "",
       `  ${kleur_default.bold("xtrm status")}          ${kleur_default.dim("Show pending changes without applying them")}`,
       `  ${kleur_default.bold("xtrm clean")}           ${kleur_default.dim("Remove orphaned hooks and skills not in canonical repo")}`,
       `  ${kleur_default.bold("xtrm init")}            ${kleur_default.dim("Initialize project data (beads, gitnexus, service-registry)")}`,
+      `  ${kleur_default.bold("xtrm docs show")}       ${kleur_default.dim("Display frontmatter for README, CHANGELOG, docs/*.md")}`,
+      `  ${kleur_default.bold("xtrm debug")}           ${kleur_default.dim("Watch xtrm hook and bd lifecycle events in real time")}`,
       `  ${kleur_default.bold("xtrm reset")}           ${kleur_default.dim("Clear saved preferences and start fresh")}`,
       `  ${kleur_default.bold("xtrm end")}             ${kleur_default.dim("Close worktree session: rebase, push, PR, link issues, cleanup")}`,
       `  ${kleur_default.bold("xtrm worktree list")}   ${kleur_default.dim("List all active xt/* worktrees with status")}`,
@@ -56138,7 +56100,7 @@ ${hr}`;
       `  ${kleur_default.dim("Run 'xtrm <command> --help' for command-specific options.")}`,
       ""
     ].join("\n");
-    console.log([installSection, hooksSection, skillsSection, psSection, otherSection, resourcesSection].join("\n"));
+    console.log([installSection, hooksSection, skillsSection, otherSection, resourcesSection].join("\n"));
   });
 }
 
@@ -56907,143 +56869,190 @@ function createDocsCommand() {
 var import_node_child_process8 = require("child_process");
 var import_node_fs5 = require("fs");
 var import_node_path6 = require("path");
-function findProjectRoot(cwd) {
-  let dir = cwd;
-  for (let i = 0; i < 10; i++) {
-    if ((0, import_node_fs5.existsSync)((0, import_node_path6.join)(dir, ".beads"))) return dir;
-    const parent = (0, import_node_path6.join)(dir, "..");
-    if (parent === dir) break;
-    dir = parent;
+var KIND_LABELS = {
+  "session.start": { label: "SESS+", color: kleur_default.green },
+  "session.end": { label: "SESS-", color: kleur_default.dim },
+  "gate.edit.allow": { label: "EDIT+", color: kleur_default.green },
+  "gate.edit.block": { label: "EDIT-", color: kleur_default.red },
+  "gate.commit.allow": { label: "CMIT+", color: kleur_default.green },
+  "gate.commit.block": { label: "CMIT-", color: kleur_default.red },
+  "gate.stop.block": { label: "STOP-", color: kleur_default.red },
+  "gate.memory.triggered": { label: "MEMO-", color: kleur_default.yellow },
+  "gate.memory.acked": { label: "MEMO+", color: kleur_default.green },
+  "gate.worktree.block": { label: "WTRE-", color: kleur_default.red },
+  "bd.claimed": { label: "CLMD ", color: kleur_default.cyan },
+  "bd.closed": { label: "CLSD ", color: kleur_default.green },
+  "bd.committed": {
+    label: (outcome) => outcome === "error" ? "ACMT-" : "ACMT+",
+    color: (outcome) => outcome === "error" ? kleur_default.red : kleur_default.cyan
   }
-  return null;
-}
-function parseBdTable(output, columns2) {
-  const lines = output.split("\n").map((l) => l.trim()).filter(Boolean);
-  const sepIdx = lines.findIndex((l) => /^[-+\s]+$/.test(l) && l.includes("-"));
-  if (sepIdx < 1) return [];
-  const dataLines = lines.slice(sepIdx + 1).filter((l) => !l.startsWith("("));
-  return dataLines.map((line) => {
-    const cells = line.split("|").map((c) => c.trim());
-    const row = {};
-    columns2.forEach((col2, i) => {
-      row[col2] = cells[i] ?? "";
-    });
-    return row;
-  });
-}
-function queryEvents(cwd, whereExtra, limit) {
-  const cols = "id, created_at, runtime, session_id, worktree, layer, kind, outcome, tool_name, issue_id";
-  const colNames = ["id", "created_at", "runtime", "session_id", "worktree", "layer", "kind", "outcome", "tool_name", "issue_id"];
-  const where = whereExtra ? `WHERE ${whereExtra}` : "";
-  const sql = `SELECT ${cols} FROM xtrm_events ${where} ORDER BY created_at ASC, id ASC LIMIT ${limit}`;
-  const result = (0, import_node_child_process8.spawnSync)("bd", ["sql", sql], {
-    cwd,
-    stdio: ["pipe", "pipe", "pipe"],
-    encoding: "utf8",
-    timeout: 8e3
-  });
-  if (result.status !== 0) return [];
-  const rows = parseBdTable(result.stdout, colNames);
-  return rows.map((r) => ({
-    id: r.id,
-    created_at: r.created_at,
-    runtime: r.runtime,
-    session_id: r.session_id,
-    worktree: r.worktree === "<nil>" || !r.worktree ? null : r.worktree,
-    layer: r.layer,
-    kind: r.kind,
-    outcome: r.outcome,
-    tool_name: r.tool_name === "<nil>" || !r.tool_name ? null : r.tool_name,
-    issue_id: r.issue_id === "<nil>" || !r.issue_id ? null : r.issue_id
-  }));
+};
+var TOOL_ABBREVS = {
+  Bash: "BASH",
+  bash: "BASH",
+  execute_shell_command: "BASH",
+  Read: "READ",
+  Write: "WRIT",
+  Edit: "EDIT",
+  MultiEdit: "EDIT",
+  NotebookEdit: "NTED",
+  Glob: "GLOB",
+  Grep: "GREP",
+  WebFetch: "WBFT",
+  WebSearch: "WSRC",
+  Agent: "AGNT",
+  Task: "TASK",
+  LSP: "LSP "
+};
+function toolAbbrev(toolName) {
+  if (TOOL_ABBREVS[toolName]) return TOOL_ABBREVS[toolName];
+  if (toolName.startsWith("mcp__serena__")) return "SRNA";
+  if (toolName.startsWith("mcp__gitnexus__")) return "GTNX";
+  if (toolName.startsWith("mcp__deepwiki__")) return "WIKI";
+  if (toolName.startsWith("mcp__")) return "MCP ";
+  return toolName.slice(0, 4).toUpperCase();
+}
+function getLabel(event) {
+  if (event.kind === "tool.call") {
+    const abbrev = toolAbbrev(event.tool_name ?? "").padEnd(5);
+    return event.outcome === "error" ? kleur_default.red(abbrev) : kleur_default.dim(abbrev);
+  }
+  const def = KIND_LABELS[event.kind];
+  if (!def) {
+    const seg = (event.kind.split(".").pop() ?? "UNKN").slice(0, 4).toUpperCase();
+    const label = `${seg}${event.outcome === "block" ? "-" : "+"}`.padEnd(5);
+    return event.outcome === "block" ? kleur_default.red(label) : kleur_default.dim(label);
+  }
+  if (event.kind === "bd.committed") {
+    const label = event.outcome === "error" ? "ACMT-" : "ACMT+";
+    return event.outcome === "error" ? kleur_default.red(label) : kleur_default.cyan(label);
+  }
+  return def.color(
+    def.label
+  );
 }
-function fmtTime(created_at) {
-  try {
-    const d = new Date(created_at);
-    if (isNaN(d.getTime())) return created_at.slice(11, 19) || "??:??:??";
-    return d.toLocaleTimeString("en-GB", { hour12: false });
-  } catch {
-    return created_at.slice(11, 19) || "??:??:??";
+var SESSION_COLORS = [
+  kleur_default.blue,
+  kleur_default.green,
+  kleur_default.yellow,
+  kleur_default.cyan,
+  kleur_default.magenta
+];
+function buildColorMap(events) {
+  const map2 = /* @__PURE__ */ new Map();
+  for (const ev of events) {
+    if (!map2.has(ev.session_id)) {
+      map2.set(ev.session_id, SESSION_COLORS[map2.size % SESSION_COLORS.length]);
+    }
   }
+  return map2;
 }
-function fmtKind(kind, outcome) {
-  const dot = outcome === "block" ? kleur_default.red("\u25CF") : kleur_default.green("\u25CB");
-  const label = kind.padEnd(36);
-  const colored = outcome === "block" ? kleur_default.red(label) : kleur_default.green(label);
-  return `${dot} ${colored}`;
+function extendColorMap(map2, events) {
+  for (const ev of events) {
+    if (!map2.has(ev.session_id)) {
+      map2.set(ev.session_id, SESSION_COLORS[map2.size % SESSION_COLORS.length]);
+    }
+  }
 }
-function fmtSession(sessionId) {
-  const short = sessionId.length > 8 ? sessionId.slice(0, 8) : sessionId;
-  return kleur_default.dim(short);
+function fmtTime(ts) {
+  return new Date(ts).toLocaleTimeString("en-GB", { hour12: false });
 }
-function fmtMeta(event) {
+function buildDetail(event) {
   const parts = [];
-  if (event.tool_name) parts.push(kleur_default.cyan(event.tool_name.padEnd(10)));
-  if (event.issue_id) parts.push(kleur_default.yellow(event.issue_id));
-  if (event.worktree) parts.push(kleur_default.dim(`[${event.worktree}]`));
+  let d = null;
+  if (event.data) {
+    try {
+      d = JSON.parse(event.data);
+    } catch {
+    }
+  }
+  if (event.kind === "tool.call") {
+    if (d?.cmd) parts.push(kleur_default.dim(d.cmd.slice(0, 60)));
+    if (d?.file) parts.push(kleur_default.dim(d.file));
+    if (d?.pattern) parts.push(kleur_default.dim(`/${d.pattern}/`));
+    if (d?.url) parts.push(kleur_default.dim(d.url.slice(0, 60)));
+    if (d?.query) parts.push(kleur_default.dim(d.query.slice(0, 60)));
+    if (d?.prompt) parts.push(kleur_default.dim(d.prompt.slice(0, 60)));
+  } else {
+    if (event.issue_id) parts.push(kleur_default.yellow(event.issue_id));
+    if (d?.file) parts.push(kleur_default.dim(d.file));
+    if (d?.msg) parts.push(kleur_default.dim(d.msg.slice(0, 60)));
+    if (d?.reason_code) parts.push(kleur_default.dim(`[${d.reason_code}]`));
+    if (event.worktree) parts.push(kleur_default.dim(`wt:${event.worktree}`));
+  }
   return parts.join("  ") || kleur_default.dim("\u2014");
 }
-function printEvent(event) {
-  const time3 = kleur_default.dim(`[${fmtTime(event.created_at)}]`);
-  const session = fmtSession(event.session_id);
-  const kind = fmtKind(event.kind, event.outcome);
-  const meta3 = fmtMeta(event);
-  console.log(`  ${time3} ${session}  ${kind}  ${meta3}`);
+function formatLine(event, colorMap) {
+  const time3 = kleur_default.dim(fmtTime(event.ts));
+  const colorFn = colorMap.get(event.session_id) ?? kleur_default.white;
+  const session = colorFn(event.session_id.slice(0, 8));
+  const label = getLabel(event);
+  const detail = buildDetail(event);
+  return `${time3}  ${session}  ${label}  ${detail}`;
 }
 function printHeader() {
-  const h = kleur_default.dim;
-  const col2 = (s, w) => s.padEnd(w);
   console.log(
-    `  ${h(col2("[TIME]", 10))} ${h(col2("SESSION", 10))}  ${h("\u25CF/\u25CB")} ${h(col2("KIND", 37))}  ${h("TOOL/ISSUE")}`
+    `  ${kleur_default.dim("TIME      ")}  ${kleur_default.dim("SESSION ")}  ${kleur_default.dim("LABEL")}  ${kleur_default.dim("DETAIL")}`
   );
-  console.log(`  ${kleur_default.dim("\u2500".repeat(90))}`);
+  console.log(`  ${kleur_default.dim("\u2500".repeat(72))}`);
 }
-function buildWhereClause(opts, sinceTs) {
-  const clauses = [];
-  if (sinceTs) {
-    clauses.push(`created_at >= '${sinceTs}'`);
+function findDbPath(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    if ((0, import_node_fs5.existsSync)((0, import_node_path6.join)(dir, ".beads"))) return (0, import_node_path6.join)(dir, ".xtrm", "debug.db");
+    const parent = (0, import_node_path6.join)(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
   }
+  return null;
+}
+function buildWhere(opts, base) {
+  const clauses = [];
+  if (base) clauses.push(base);
   if (opts.session) {
     const s = opts.session.replace(/'/g, "''");
     clauses.push(`session_id LIKE '${s}%'`);
   }
   if (opts.type) {
-    const layer = opts.type.replace(/'/g, "''");
-    clauses.push(`layer = '${layer}'`);
+    const t3 = opts.type.replace(/'/g, "''");
+    clauses.push(`kind LIKE '${t3}.%' OR kind = '${t3}'`);
   }
-  return clauses.join(" AND ");
+  return clauses.length ? clauses.join(" AND ") : "";
 }
-function watch(cwd, opts) {
-  const seenIds = /* @__PURE__ */ new Set();
-  let lastTs = null;
-  const fiveMinsAgo = new Date(Date.now() - 5 * 60 * 1e3).toISOString().replace("T", " ").slice(0, 19);
-  const initialWhere = buildWhereClause(opts, fiveMinsAgo);
-  const initial = queryEvents(cwd, initialWhere, 200);
+function queryEvents(dbPath, where, limit) {
+  const sql = `SELECT id,ts,session_id,runtime,worktree,kind,tool_name,outcome,issue_id,duration_ms,data FROM events${where ? ` WHERE ${where}` : ""} ORDER BY id ASC LIMIT ${limit}`;
+  const result = (0, import_node_child_process8.spawnSync)("sqlite3", [dbPath, "-json", sql], {
+    stdio: ["pipe", "pipe", "pipe"],
+    encoding: "utf8",
+    timeout: 5e3
+  });
+  if (result.status !== 0 || !result.stdout.trim()) return [];
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return [];
+  }
+}
+function follow(dbPath, opts) {
+  const sinceTs = Date.now() - 5 * 60 * 1e3;
+  const initial = queryEvents(dbPath, buildWhere(opts, `ts >= ${sinceTs}`), 200);
+  const colorMap = buildColorMap(initial);
+  let lastId = 0;
   if (initial.length > 0) {
     for (const ev of initial) {
-      seenIds.add(ev.id);
-      if (!lastTs || ev.created_at > lastTs) lastTs = ev.created_at;
-      if (opts.json) {
-        console.log(JSON.stringify(ev));
-      } else {
-        printEvent(ev);
-      }
+      if (ev.id > lastId) lastId = ev.id;
+      opts.json ? console.log(JSON.stringify(ev)) : console.log("  " + formatLine(ev, colorMap));
     }
-  } else {
-    if (!opts.json) console.log(kleur_default.dim("  (no recent events \u2014 waiting for new ones)\n"));
+  } else if (!opts.json) {
+    console.log(kleur_default.dim("  (no recent events \u2014 waiting for new ones)\n"));
   }
   const interval = setInterval(() => {
-    const overlapTs = lastTs ? new Date(new Date(lastTs.replace(" +0000 UTC", "Z")).getTime() - 2e3).toISOString().replace("T", " ").slice(0, 19) : new Date(Date.now() - 1e4).toISOString().replace("T", " ").slice(0, 19);
-    const where = buildWhereClause(opts, overlapTs);
-    const events = queryEvents(cwd, where, 50);
-    const newEvents = events.filter((ev) => !seenIds.has(ev.id));
-    for (const ev of newEvents) {
-      seenIds.add(ev.id);
-      if (!lastTs || ev.created_at > lastTs) lastTs = ev.created_at;
-      if (opts.json) {
-        console.log(JSON.stringify(ev));
-      } else {
-        printEvent(ev);
+    const events = queryEvents(dbPath, buildWhere(opts, `id > ${lastId}`), 50);
+    if (events.length > 0) {
+      extendColorMap(colorMap, events);
+      for (const ev of events) {
+        if (ev.id > lastId) lastId = ev.id;
+        opts.json ? console.log(JSON.stringify(ev)) : console.log("  " + formatLine(ev, colorMap));
       }
     }
   }, 2e3);
@@ -57054,44 +57063,36 @@ function watch(cwd, opts) {
   });
 }
 function createDebugCommand() {
-  return new Command("debug").description("Watch xtrm hook and bd lifecycle events in real time").option("--all", "Show full history instead of watching", false).option("--session <id>", "Filter by session ID (prefix match)").option("--type <layer>", "Filter by layer: gate | bd").option("--json", "Output raw JSON lines", false).action((opts) => {
+  return new Command("debug").description("Watch xtrm events: tool calls, gate decisions, bd lifecycle").option("-f, --follow", "Follow new events (default)", false).option("--all", "Show full history and exit", false).option("--session <id>", "Filter by session ID (prefix match)").option("--type <domain>", "Filter by domain: tool | gate | bd | session").option("--json", "Output raw JSON lines", false).action((opts) => {
     const cwd = process.cwd();
-    const root = findProjectRoot(cwd);
-    if (!root) {
-      console.error(kleur_default.red("\n  \u2717 No beads project found (.beads directory missing)\n"));
-      console.error(kleur_default.dim("  Run from inside an xtrm project.\n"));
-      process.exit(1);
+    const dbPath = findDbPath(cwd);
+    if (!dbPath || !(0, import_node_fs5.existsSync)(dbPath)) {
+      if (!opts.json) {
+        console.log(kleur_default.bold("\n  xtrm event log"));
+        console.log(kleur_default.dim("  No events yet \u2014 DB initializes on first hook fire.\n"));
+        console.log(kleur_default.dim("  Run from inside an xtrm project with beads initialized.\n"));
+      }
+      return;
     }
     if (!opts.json) {
       console.log(kleur_default.bold("\n  xtrm event log"));
-      if (opts.all) {
-        console.log(kleur_default.dim("  Showing full history\n"));
-      } else {
-        console.log(kleur_default.dim("  Watching for events \u2014 Ctrl+C to stop\n"));
-      }
+      console.log(kleur_default.dim(opts.all ? "  Full history\n" : "  Following \u2014 Ctrl+C to stop\n"));
       printHeader();
     }
     if (opts.all) {
-      const where = buildWhereClause(opts, null);
-      const events = queryEvents(root, where, 200);
+      const events = queryEvents(dbPath, buildWhere(opts, ""), 1e3);
       if (events.length === 0) {
-        if (!opts.json) {
-          console.log(kleur_default.dim("\n  No events recorded yet."));
-          console.log(kleur_default.dim("  Events appear here as hooks fire and bd lifecycle runs.\n"));
-        }
+        if (!opts.json) console.log(kleur_default.dim("\n  No events recorded yet.\n"));
       } else {
+        const colorMap = buildColorMap(events);
         for (const ev of events) {
-          if (opts.json) {
-            console.log(JSON.stringify(ev));
-          } else {
-            printEvent(ev);
-          }
+          opts.json ? console.log(JSON.stringify(ev)) : console.log("  " + formatLine(ev, colorMap));
         }
         if (!opts.json) console.log("");
       }
       return;
     }
-    watch(root, opts);
+    follow(dbPath, opts);
   });
 }