xtrm-tools 2.1.28 → 2.1.30

package/cli/package.json

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

package/config/hooks.json

@@ -36,6 +36,11 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Bash|execute_shell_command|bash",
+        "script": "beads-claim-sync.mjs",
+        "timeout": 5000
+      },
       {
         "matcher": "Bash",
         "script": "main-guard-post-push.mjs",

package/config/instructions/agents-top.md

@@ -0,0 +1,30 @@
+# XTRM Agent Workflow (Short)
+
+This file is an **agent operating manual** (not a project overview).
+
+1. **Start with scope**
+   - Clarify task intent if ambiguous.
+   - Prefer semantic discovery (Serena + GitNexus) over broad grep-first exploration.
+
+2. **Track work in `bd`**
+   - Use `bd ready --json` / `bd update <id> --claim --json` before edits.
+   - Create discovered follow-ups with `--deps discovered-from:<id>`.
+
+3. **Branch per issue (strict)**
+   - Create a **new branch for each issue** from latest `main`.
+   - Do **not** continue new work on a previously used branch.
+   - Branch format: `feature/<issue-id>-<short-description>` (or `fix/...`, `chore/...`).
+
+4. **Edit safely**
+   - Use Serena symbol tools for code changes when possible.
+   - Run GitNexus impact checks before symbol changes and detect-changes before commit.
+
+5. **PR merge + return to main**
+   - Always merge via PR (squash merge preferred).
+   - After merge: switch to `main` and sync (`git reset --hard origin/main`).
+   - Delete merged branch locally and remotely (`git branch -d <branch>` and `git push origin --delete <branch>`).
+
+6. **Before finishing**
+   - Run relevant tests/linters.
+   - Close/update bead state.
+   - Ensure changes are committed and pushed.

package/config/instructions/claude-top.md

@@ -0,0 +1,30 @@
+# XTRM Agent Workflow (Short)
+
+This file is an **agent operating manual** (not a project overview).
+
+1. **Start with scope**
+   - Clarify task intent if ambiguous.
+   - Prefer semantic discovery (Serena + GitNexus) over broad grep-first exploration.
+
+2. **Track work in `bd`**
+   - Use `bd ready --json` / `bd update <id> --claim --json` before edits.
+   - Create discovered follow-ups with `--deps discovered-from:<id>`.
+
+3. **Branch per issue (strict)**
+   - Create a **new branch for each issue** from latest `main`.
+   - Do **not** continue new work on a previously used branch.
+   - Branch format: `feature/<issue-id>-<short-description>` (or `fix/...`, `chore/...`).
+
+4. **Edit safely**
+   - Use Serena symbol tools for code changes when possible.
+   - Run GitNexus impact checks before symbol changes and detect-changes before commit.
+
+5. **PR merge + return to main**
+   - Always merge via PR (squash merge preferred).
+   - After merge: switch to `main` and sync (`git reset --hard origin/main`).
+   - Delete merged branch locally and remotely (`git branch -d <branch>` and `git push origin --delete <branch>`).
+
+6. **Before finishing**
+   - Run relevant tests/linters.
+   - Close/update bead state.
+   - Ensure changes are committed and pushed.

package/config/pi/extensions/beads.ts

@@ -10,10 +10,18 @@ export default function (pi: ExtensionAPI) {
 	const getCwd = (ctx: any) => ctx.cwd || process.cwd();
 	const isBeadsProject = (cwd: string) => fs.existsSync(path.join(cwd, ".beads"));
 
-	// Pin session to PID — stable for the life of the Pi process, consistent across all extension handlers
-	const sessionId = process.pid.toString();
+	let cachedSessionId: string | null = null;
 
-	const getSessionClaim = async (cwd: string): Promise<string | null> => {
+	// Resolve a stable session ID across event types.
+	const getSessionId = (ctx: any): string => {
+		const fromManager = ctx?.sessionManager?.getSessionId?.();
+		const fromContext = ctx?.sessionId ?? ctx?.session_id;
+		const resolved = fromManager || fromContext || cachedSessionId || process.pid.toString();
+		if (resolved && !cachedSessionId) cachedSessionId = resolved;
+		return resolved;
+	};
+
+	const getSessionClaim = async (sessionId: string, cwd: string): Promise<string | null> => {
 		const result = await SubprocessRunner.run("bd", ["kv", "get", `claimed:${sessionId}`], { cwd });
 		if (result.code === 0) return result.stdout.trim();
 		return null;
@@ -32,12 +40,18 @@ export default function (pi: ExtensionAPI) {
 		return false;
 	};
 
+	pi.on("session_start", async (_event, ctx) => {
+		cachedSessionId = ctx?.sessionManager?.getSessionId?.() ?? ctx?.sessionId ?? ctx?.session_id ?? cachedSessionId;
+		return undefined;
+	});
+
 	pi.on("tool_call", async (event, ctx) => {
 		const cwd = getCwd(ctx);
 		if (!isBeadsProject(cwd)) return undefined;
+		const sessionId = getSessionId(ctx);
 
 		if (EventAdapter.isMutatingFileTool(event)) {
-			const claim = await getSessionClaim(cwd);
+			const claim = await getSessionClaim(sessionId, cwd);
 			if (!claim) {
 			    const hasWork = await hasTrackableWork(cwd);
 			    if (hasWork) {
@@ -46,7 +60,7 @@ export default function (pi: ExtensionAPI) {
 			        }
 			        return {
                         block: true,
-                        reason: `No active issue claim for this session (pid:${sessionId}).\n  bd update <id> --claim\n  bd kv set "claimed:${sessionId}" "<id>"`,
+                        reason: `No active issue claim for this session (${sessionId}).\n  bd update <id> --claim\n  bd kv set "claimed:${sessionId}" "<id>"`,
                     };
                 }
             }
@@ -55,7 +69,7 @@ export default function (pi: ExtensionAPI) {
 		if (isToolCallEventType("bash", event)) {
 			const command = event.input.command;
 			if (command && /\bgit\s+commit\b/.test(command)) {
-                const claim = await getSessionClaim(cwd);
+                const claim = await getSessionClaim(sessionId, cwd);
 				if (claim) {
 					return {
                         block: true,
@@ -71,6 +85,7 @@ export default function (pi: ExtensionAPI) {
 	pi.on("tool_result", async (event, ctx) => {
 		if (isBashToolResult(event)) {
 			const command = event.input.command;
+			const sessionId = getSessionId(ctx);
 
 			// Auto-claim on bd update --claim regardless of exit code.
 			// bd returns exit 1 with "already in_progress" when status unchanged — still a valid claim intent.
@@ -80,7 +95,7 @@ export default function (pi: ExtensionAPI) {
 					const issueId = issueMatch[1];
 					const cwd = getCwd(ctx);
 					await SubprocessRunner.run("bd", ["kv", "set", `claimed:${sessionId}`, issueId], { cwd });
-					const claimNotice = `\n\n✅ **Beads**: Session \`pid:${sessionId}\` claimed issue \`${issueId}\`. File edits are now unblocked.`;
+					const claimNotice = `\n\n✅ **Beads**: Session \`${sessionId}\` claimed issue \`${issueId}\`. File edits are now unblocked.`;
 					return { content: [...event.content, { type: "text", text: claimNotice }] };
 				}
 			}

package/config/pi/extensions/custom-footer.ts

@@ -1,7 +1,7 @@
 /**
  * XTRM Custom Footer Extension
  *
- * Displays: XTRM brand, Turn count, Model, Context%, CWD, Git branch
+ * Displays: XTRM brand, Model, Context%, CWD, Git branch, Beads chip
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
@@ -12,9 +12,6 @@ import * as fs from "node:fs";
 import { SubprocessRunner } from "./core/lib";
 
 export default function (pi: ExtensionAPI) {
-	// Pin session to PID — stable for the life of the Pi process, matches beads.ts
-	const SESSION_KEY = process.pid.toString();
-
 	interface BeadState {
 		claimId: string | null;
 		shortId: string | null;
@@ -31,11 +28,12 @@ export default function (pi: ExtensionAPI) {
 	};
 	const STATUS_BG: Record<string, string> = {
 		open: "\x1b[48;5;238m",
-		in_progress: "\x1b[48;5;28m",
+		in_progress: "\x1b[48;5;39m",
 		blocked: "\x1b[48;5;88m",
 	};
 
 	let capturedCtx: any = null;
+	let sessionId: string = "";
 	let beadState: BeadState = { claimId: null, shortId: null, status: null, openCount: 0, lastFetch: 0 };
 	let refreshing = false;
 	let requestRender: (() => void) | null = null;
@@ -49,9 +47,10 @@ export default function (pi: ExtensionAPI) {
 		if (refreshing || Date.now() - beadState.lastFetch < CACHE_TTL) return;
 		const cwd = getCwd();
 		if (!isBeadsProject(cwd)) return;
+		if (!sessionId) return;
 		refreshing = true;
 		try {
-			const claimResult = await SubprocessRunner.run("bd", ["kv", "get", `claimed:${SESSION_KEY}`], { cwd });
+			const claimResult = await SubprocessRunner.run("bd", ["kv", "get", `claimed:${sessionId}`], { cwd });
 			const claimId = claimResult.code === 0 ? claimResult.stdout.trim() || null : null;
 
 			let status: string | null = null;
@@ -61,7 +60,7 @@ export default function (pi: ExtensionAPI) {
 					try { status = JSON.parse(showResult.stdout)[0]?.status ?? null; } catch {}
 				}
 				if (status === "closed") {
-					await SubprocessRunner.run("bd", ["kv", "clear", `claimed:${SESSION_KEY}`], { cwd });
+					await SubprocessRunner.run("bd", ["kv", "clear", `claimed:${sessionId}`], { cwd });
 					beadState = { claimId: null, shortId: null, status: null, openCount: beadState.openCount, lastFetch: Date.now() };
 					requestRender?.();
 					return;
@@ -96,6 +95,8 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		capturedCtx = ctx;
+		// Get session ID from sessionManager/context (prefer UUID, consistent with hooks)
+		sessionId = ctx.sessionManager?.getSessionId?.() ?? ctx.sessionId ?? ctx.session_id ?? process.pid.toString();
 
 		ctx.ui.setFooter((tui, theme, footerData) => {
 			requestRender = () => tui.requestRender();
@@ -122,15 +123,16 @@ export default function (pi: ExtensionAPI) {
 					const branchStr = branch ? theme.fg("accent", `⎇ ${branch}`) : "";
 
 					const modelId = ctx.model?.id || "no-model";
-					const modelStr = theme.fg("accent", modelId);
+					const modelChip = `\x1b[48;5;238m\x1b[38;5;15m ${modelId} \x1b[0m`;
 
 					const sep = theme.fg("dim", " | ");
 
-					const leftParts = [brand, modelStr, usageStr, cwdStr];
-					if (branchStr) leftParts.push(branchStr);
-
+					const brandModel = `${brand} ${modelChip}`;
+					const leftParts = [brandModel, usageStr, cwdStr];
+					
 					const beadChip = buildBeadChip();
-					if (beadChip) leftParts.push(beadChip);
+					const branchWithChip = branchStr ? `${branchStr} ${beadChip}`.trim() : beadChip;
+					if (branchWithChip) leftParts.push(branchWithChip);
 
 					const left = leftParts.join(sep);
 					return [truncateToWidth(left, width)];
@@ -139,7 +141,7 @@ export default function (pi: ExtensionAPI) {
 		});
 	});
 
-	// Bust the bead cache immediately after any bd write so the chip reflects the new state
+	// Bust the bead cache immediately after any bd write
 	pi.on("tool_result", async (event: any) => {
 		const cmd = event?.input?.command;
 		if (cmd && /\bbd\s+(close|update|create|claim)\b/.test(cmd)) {

package/config/pi/pi-worktrees-settings.json

@@ -0,0 +1,6 @@
+{
+  "worktree": {
+    "parentDir": "../{{project}}.worktrees",
+    "onCreate": "npm install 2>/dev/null || true"
+  }
+}

package/config/pi/settings.json.template

@@ -7,7 +7,8 @@
   "packages": [
     "npm:@aliou/pi-guardrails",
     "npm:pi-gitnexus",
-    "npm:pi-serena-tools"
+    "npm:pi-serena-tools",
+    "npm:@zenobius/pi-worktrees"
   ],
   "steeringMode": "all",
   "followUpMode": "all",

package/hooks/beads-claim-sync.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// beads-claim-sync — PostToolUse hook
+// Auto-sets bd kv claim when bd update --claim is detected.
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+function readInput() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function isBeadsProject(cwd) {
+  return existsSync(join(cwd, '.beads'));
+}
+
+function isShellTool(toolName) {
+  return toolName === 'Bash' || toolName === 'bash' || toolName === 'execute_shell_command';
+}
+
+function commandSucceeded(payload) {
+  const tr = payload?.tool_response ?? payload?.tool_result ?? payload?.result;
+  if (!tr || typeof tr !== 'object') return true;
+
+  if (tr.success === false) return false;
+  if (tr.error) return false;
+
+  const numeric = [tr.exit_code, tr.exitCode, tr.status, tr.returncode].find((v) => Number.isInteger(v));
+  if (typeof numeric === 'number' && numeric !== 0) return false;
+
+  return true;
+}
+
+function main() {
+  const input = readInput();
+  if (!input || input.hook_event_name !== 'PostToolUse') process.exit(0);
+  if (!isShellTool(input.tool_name)) process.exit(0);
+  if (!commandSucceeded(input)) process.exit(0);
+
+  const cwd = input.cwd || process.cwd();
+  if (!isBeadsProject(cwd)) process.exit(0);
+
+  const command = input.tool_input?.command || '';
+  if (!/\bbd\s+update\b/.test(command) || !/--claim\b/.test(command)) {
+    process.exit(0);
+  }
+
+  const match = command.match(/\bbd\s+update\s+(\S+)/);
+  if (!match) process.exit(0);
+
+  const issueId = match[1];
+  const sessionId = input.session_id ?? input.sessionId;
+
+  if (!sessionId) {
+    process.stderr.write('Beads claim sync: no session_id in hook input\n');
+    process.exit(0);
+  }
+
+  const result = spawnSync('bd', ['kv', 'set', `claimed:${sessionId}`, issueId], {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 5000,
+  });
+
+  if (result.status !== 0) {
+    const err = (result.stderr || result.stdout || '').toString().trim();
+    if (err) process.stderr.write(`Beads claim sync warning: ${err}\n`);
+    process.exit(0);
+  }
+
+  process.stdout.write(JSON.stringify({
+    additionalContext: `\n✅ **Beads**: Session \`${sessionId}\` claimed issue \`${issueId}\`.`,
+  }));
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+main();

package/package.json

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