xtrm-tools 0.5.19 → 0.5.21

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",

package/config/hooks.json

@@ -4,9 +4,6 @@
       {
         "script": "beads-compact-restore.mjs",
         "timeout": 5000
-      },
-      {
-        "script": "serena-workflow-reminder.py"
       }
     ],
     "UserPromptSubmit": [
@@ -16,6 +13,11 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "script": "worktree-boundary.mjs",
+        "timeout": 2000
+      },
       {
         "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
         "script": "beads-edit-gate.mjs",

package/hooks/beads-claim-sync.mjs

@@ -79,11 +79,21 @@ function getCloseReason(cwd, issueId, command) {
   return `Close ${issueId}`;
 }
 
+function stageUntracked(cwd) {
+  const result = runGit(['ls-files', '--others', '--exclude-standard'], cwd);
+  if (result.status !== 0) return;
+  const untracked = result.stdout.trim().split('\n').filter(Boolean);
+  if (untracked.length === 0) return;
+  runGit(['add', '--', ...untracked], cwd);
+}
+
 function autoCommit(cwd, issueId, command) {
   if (!hasGitChanges(cwd)) {
     return { ok: true, message: 'No changes detected — auto-commit skipped.' };
   }
 
+  stageUntracked(cwd);
+
   const reason = getCloseReason(cwd, issueId, command);
   const commitMessage = `${reason} (${issueId})`;
   const result = runGit(['commit', '-am', commitMessage], cwd, 15000);

package/hooks/beads-edit-gate.mjs

@@ -12,13 +12,26 @@ import {
   resolveSessionContext,
   resolveClaimAndWorkState,
   decideEditGate,
+  decideWorktreeBoundary,
 } from './beads-gate-core.mjs';
-import { withSafeBdContext } from './beads-gate-utils.mjs';
+import { withSafeBdContext, resolveCwd } from './beads-gate-utils.mjs';
 import { editBlockMessage, editBlockFallbackMessage } from './beads-gate-messages.mjs';
 
 const input = readHookInput();
 if (!input) process.exit(0);
 
+// Worktree boundary check — independent of beads, fires first
+const _cwd = resolveCwd(input);
+const _boundary = decideWorktreeBoundary(input, _cwd);
+if (!_boundary.allow) {
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: `🚫 Edit outside worktree boundary.\n  File:    ${_boundary.filePath}\n  Allowed: ${_boundary.worktreeRoot}\n\n  All edits must stay within the active worktree.`,
+  }));
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
 withSafeBdContext(() => {
   const ctx = resolveSessionContext(input);
   if (!ctx || !ctx.isBeadsProject) process.exit(0);

package/hooks/beads-gate-core.mjs

@@ -8,6 +8,7 @@
 // Dependencies: beads-gate-utils.mjs (adapters)
 
 import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import {
   resolveCwd,
   resolveSessionId,
@@ -16,6 +17,7 @@ import {
   getTotalWork,
   getInProgress,
   isIssueInProgress,
+  resolveWorktreeRoot,
 } from './beads-gate-utils.mjs';
 
 // ── Input parsing ────────────────────────────────────────────────────────────
@@ -88,6 +90,25 @@ export function resolveClaimAndWorkState(ctx) {
 
 // ── Decision functions ───────────────────────────────────────────────────────
 
+/**
+ * Decide whether a file edit is within the active worktree boundary.
+ * If the session cwd is inside .xtrm/worktrees/<name>, block any edit whose
+ * resolved path falls outside that worktree root.
+ * Returns { allow: boolean, filePath?: string, worktreeRoot?: string }
+ */
+export function decideWorktreeBoundary(input, cwd) {
+  const filePath = input?.tool_input?.file_path;
+  if (!filePath) return { allow: true };
+
+  const worktreeRoot = resolveWorktreeRoot(cwd);
+  if (!worktreeRoot) return { allow: true }; // not in a worktree — no constraint
+
+  const abs = resolve(cwd, filePath);
+  if (abs === worktreeRoot || abs.startsWith(worktreeRoot + '/')) return { allow: true };
+
+  return { allow: false, filePath: abs, worktreeRoot };
+}
+
 /**
  * Decide whether to allow or block an edit operation.
  * Returns { allow: boolean, reason?: string, sessionId?: string }

package/hooks/beads-gate-utils.mjs

@@ -151,6 +151,15 @@ export function isMemoryAckCommand(command) {
   return /\bbd\s+remember\b/.test(command) || /\btouch\s+\.beads\/\.memory-gate-done\b/.test(command);
 }
 
+/**
+ * If cwd is inside a .xtrm/worktrees/<name> directory, return the worktree root path.
+ * Returns null if not in a worktree.
+ */
+export function resolveWorktreeRoot(cwd) {
+  const m = cwd.match(/^(.+\/\.xtrm\/worktrees\/[^/]+)/);
+  return m ? m[1] : null;
+}
+
 /**
  * Clear the session claim key from bd kv. Non-fatal — best-effort cleanup.
  */

package/hooks/hooks.json

@@ -16,10 +16,33 @@
             "type": "command",
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/quality-check-env.mjs",
             "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/worktree-boundary.mjs",
+            "timeout": 2000
           },
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/serena-workflow-reminder.py"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-edit-gate.mjs",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-commit-gate.mjs",
+            "timeout": 5000
           }
         ]
       }
@@ -77,28 +100,6 @@
         ]
       }
     ],
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-edit-gate.mjs",
-            "timeout": 5000
-          }
-        ]
-      },
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-commit-gate.mjs",
-            "timeout": 5000
-          }
-        ]
-      }
-    ],
     "PreCompact": [
       {
         "hooks": [

package/hooks/statusline.mjs

@@ -1,29 +1,30 @@
 #!/usr/bin/env node
-// statusline.mjs — Claude Code statusLine command for xt claude worktree sessions
-// Two lines:
-//   Line 1 (plain):   XTRM  ⎇ <branch>
-//   Line 2 (colored): ◐ <claim title in italics>  OR  ○ N open
-// State file: .xtrm/statusline-claim (written by beads-claim-sync.mjs)
-// Results cached 5s in /tmp to avoid hammering bd on every render.
+// statusline.mjs — Claude Code statusLine for xt claude sessions
+// Line 1: XTRM  dim(model [xx%])  hostname  bold(dir)  dim(branch (status))  dim((venv))
+// Line 2: ◐ italic(claim title)  OR  ○ bold(N) open  — no background
+//
+// Colors: bold/dim/italic only — no explicit fg/bg, adapts to dark & light themes.
+// State: .xtrm/statusline-claim (written by beads-claim-sync.mjs)
+// Cache: /tmp per cwd, 5s TTL
 
 import { execSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
+import { join, basename, relative } from 'node:path';
+import { tmpdir, hostname } from 'node:os';
 import { createHash } from 'node:crypto';
 
-const cwd = process.cwd();
+// Claude Code passes statusline context as JSON on stdin
+let ctx = {};
+try { ctx = JSON.parse(readFileSync(0, 'utf8')); } catch {}
+
+const cwd = ctx?.workspace?.current_dir ?? process.cwd();
 const cacheKey = createHash('md5').update(cwd).digest('hex').slice(0, 8);
 const CACHE_FILE = join(tmpdir(), `xtrm-sl-${cacheKey}.json`);
 const CACHE_TTL = 5000;
 
 function run(cmd) {
   try {
-    return execSync(cmd, {
-      encoding: 'utf8', cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 2000,
-    }).trim();
+    return execSync(cmd, { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'], timeout: 2000 }).trim();
   } catch { return null; }
 }
 
@@ -39,76 +40,105 @@ function setCache(data) {
   try { writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), data })); } catch {}
 }
 
-// ANSI
-const R          = '\x1b[0m';
-const BOLD       = '\x1b[1m';
-const BOLD_OFF   = '\x1b[22m';
-const ITALIC     = '\x1b[3m';
-const ITALIC_OFF = '\x1b[23m';
-const FG_WHITE   = '\x1b[38;5;15m';
-const FG_ACCENT  = '\x1b[38;5;75m';
-const FG_MUTED   = '\x1b[38;5;245m';
-const BG_CLAIMED = '\x1b[48;5;17m';
-const BG_IDLE    = '\x1b[48;5;238m';
-
-// Data
+// ANSI — bold/dim/italic only; no explicit fg/bg colors
+const R  = '\x1b[0m';
+const B  = '\x1b[1m';   // bold on
+const B_ = '\x1b[22m';  // bold off (normal intensity)
+const D  = '\x1b[2m';   // dim on
+const I  = '\x1b[3m';   // italic on
+const I_ = '\x1b[23m';  // italic off
+
 let data = getCached();
 if (!data) {
-  const branch = run('git branch --show-current');
-  let claimTitle = null;
-  let openCount = 0;
+  // Model + token %
+  const modelId = ctx?.model?.display_name ?? ctx?.model?.id ?? null;
+  const pct = ctx?.context_window?.used_percentage;
+  const modelStr = modelId ? `${modelId}${pct != null ? ` [${Math.round(pct)}%]` : ''}` : null;
+
+  // Short hostname
+  const host = hostname().split('.')[0];
+
+  // Directory — repo-relative like the global script
+  const repoRoot = run('git rev-parse --show-toplevel');
+  let displayDir;
+  if (repoRoot) {
+    const rel = relative(repoRoot, cwd) || '.';
+    displayDir = rel === '.' ? basename(repoRoot) : `${basename(repoRoot)}/${rel}`;
+  } else {
+    displayDir = cwd.replace(process.env.HOME ?? '', '~');
+  }
 
-  const hasBeads = existsSync(join(cwd, '.beads'));
-  if (hasBeads) {
-    const claimFile = join(cwd, '.xtrm', 'statusline-claim');
-    let claimId = null;
-    if (existsSync(claimFile)) {
-      claimId = readFileSync(claimFile, 'utf8').trim() || null;
+  // Branch + git status indicators
+  let branch = null;
+  let gitStatus = '';
+  if (repoRoot) {
+    branch = run('git -c core.useBuiltinFSMonitor=false branch --show-current') || run('git rev-parse --short HEAD');
+    const porcelain = run('git -c core.useBuiltinFSMonitor=false --no-optional-locks status --porcelain') ?? '';
+    let modified = false, staged = false, deleted = false;
+    for (const l of porcelain.split('\n').filter(Boolean)) {
+      if (/^ M|^AM|^MM/.test(l)) modified = true;
+      if (/^A |^M /.test(l)) staged = true;
+      if (/^ D|^D /.test(l)) deleted = true;
     }
+    let st = (modified ? '*' : '') + (staged ? '+' : '') + (deleted ? '-' : '');
+    const ab = run('git -c core.useBuiltinFSMonitor=false --no-optional-locks rev-list --left-right --count @{upstream}...HEAD');
+    if (ab) {
+      const [behind, ahead] = ab.split(/\s+/).map(Number);
+      if (ahead > 0 && behind > 0) st += '↕';
+      else if (ahead > 0) st += '↑';
+      else if (behind > 0) st += '↓';
+    }
+    if (st) gitStatus = `(${st})`;
+  }
 
+  // Python venv
+  const venv = process.env.VIRTUAL_ENV ? `(${basename(process.env.VIRTUAL_ENV)})` : null;
+
+  // Beads
+  let claimId = null;
+  let claimTitle = null;
+  let openCount = 0;
+  if (existsSync(join(cwd, '.beads'))) {
+    const claimFile = join(cwd, '.xtrm', 'statusline-claim');
+    claimId = existsSync(claimFile) ? (readFileSync(claimFile, 'utf8').trim() || null) : null;
     if (claimId) {
       try {
         const raw = run(`bd show ${claimId} --json`);
-        if (raw) {
-          const parsed = JSON.parse(raw);
-          claimTitle = parsed?.[0]?.title ?? null;
-        }
+        claimTitle = raw ? (JSON.parse(raw)?.[0]?.title ?? null) : null;
       } catch {}
     }
-
     if (!claimTitle) {
-      const listOut = run('bd list');
-      const m = listOut?.match(/\((\d+)\s+open/);
+      const m = run('bd list')?.match(/\((\d+)\s+open/);
       if (m) openCount = parseInt(m[1], 10);
     }
   }
 
-  data = { branch, claimTitle, openCount };
+  data = { modelStr, host, displayDir, branch, gitStatus, venv, claimId, claimTitle, openCount };
   setCache(data);
 }
 
-// Render
-const { branch, claimTitle, openCount } = data;
-const cols = process.stdout.columns || 80;
-
-const brand = `${BOLD}${FG_ACCENT}XTRM${BOLD_OFF}${R}`;
-const branchStr = branch ? `${FG_MUTED}⎇ ${branch}${R}` : '';
-const line1 = [brand, branchStr].filter(Boolean).join('  ');
+const { modelStr, host, displayDir, branch, gitStatus, venv, claimId, claimTitle, openCount } = data;
 
-function padded(text, bg) {
-  const visible = text.replace(/\x1b\[[0-9;]*m/g, '');
-  const pad = Math.max(0, cols - visible.length);
-  return `${bg}${FG_WHITE}${text}${' '.repeat(pad)}${R}`;
-}
+// Line 1 — matches global format, XTRM prepended
+const parts = [`${B}XTRM${B_}`];
+if (modelStr) parts.push(`${D}${modelStr}${R}`);
+parts.push(host);
+if (displayDir) parts.push(`${B}${displayDir}${B_}`);
+if (branch) parts.push(`${D}${[branch, gitStatus].filter(Boolean).join(' ')}${R}`);
+if (venv) parts.push(`${D}${venv}${R}`);
+const line1 = parts.join(' ');
 
+// Line 2 — no background; open count bold
 let line2;
 if (claimTitle) {
-  const maxLen = cols - 4;
-  const title = claimTitle.length > maxLen ? claimTitle.slice(0, maxLen - 1) + '\u2026' : claimTitle;
-  line2 = padded(` \u25d0 ${ITALIC}${title}${ITALIC_OFF}`, BG_CLAIMED);
+  const cols = process.stdout.columns || 80;
+  const prefix = ` ◐ ${claimId} `;
+  const prefixLen = prefix.replace(/\x1b\[[0-9;]*m/g, '').length;
+  const maxLen = cols - prefixLen - 1;
+  const t = claimTitle.length > maxLen ? claimTitle.slice(0, maxLen - 1) + '…' : claimTitle;
+  line2 = `${prefix}${I}${t}${I_}`;
 } else {
-  const idle = openCount > 0 ? `\u25cb ${openCount} open` : '\u25cb no open issues';
-  line2 = padded(` ${idle}`, BG_IDLE);
+  line2 = ` ○ ${openCount > 0 ? `${B}${openCount}${B_} open` : 'no open issues'}`;
 }
 
 process.stdout.write(line1 + '\n' + line2 + '\n');

package/hooks/worktree-boundary.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// worktree-boundary.mjs — Claude Code PreToolUse hook
+// Blocks Write/Edit when the target file is outside the active worktree root.
+// Only active when session cwd is inside .xtrm/worktrees/<name>.
+// Fail-open: any unexpected error allows the edit through.
+//
+// Installed by: xtrm install
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const filePath = input?.tool_input?.file_path;
+if (!filePath) process.exit(0);
+
+// Detect worktree root from cwd
+const m = cwd.match(/^(.+\/\.xtrm\/worktrees\/[^/]+)/);
+if (!m) process.exit(0); // not in a worktree — no constraint
+
+const worktreeRoot = m[1];
+const abs = resolve(cwd, filePath);
+
+if (abs === worktreeRoot || abs.startsWith(worktreeRoot + '/')) process.exit(0);
+
+process.stdout.write(JSON.stringify({
+  decision: 'block',
+  reason: `🚫 Edit outside worktree boundary.\n  File:    ${abs}\n  Allowed: ${worktreeRoot}\n\n  All edits must stay within the active worktree.`,
+}));
+process.stdout.write('\n');
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "license": "MIT",
   "type": "module",

package/skills/sync-docs/SKILL.md

@@ -55,7 +55,30 @@ python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30
 python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30 --json
 ```
 
-A docs file is stale when frontmatter `source_of_truth_for` (or `tracks`) matches files changed in recent commits.
+A docs file is stale when:
+1. It declares `source_of_truth_for` globs in frontmatter
+2. AND there are commits affecting matching files AFTER the `synced_at` hash
+
+### synced_at Checkpoint
+
+Add `synced_at: <git-hash>` to doc frontmatter to mark the last sync point:
+
+```yaml
+---
+title: Hooks Reference
+updated: 2026-03-21
+synced_at: a1b2c3d  # git hash when doc was last synced
+source_of_truth_for:
+  - "hooks/**/*.mjs"
+---
+```
+
+After updating a doc, run:
+```bash
+python3 "skills/sync-docs/scripts/drift_detector.py" update-sync docs/hooks.md
+```
+
+This sets `synced_at` to current HEAD, marking the doc as synced.
 
 ---