xtrm-tools 0.5.0

package/config/pi/extensions/plan-mode/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@xtrm/pi-plan-mode",
+  "version": "1.0.0",
+  "description": "Plan mode extension for Pi - read-only exploration with plan extraction and bd integration",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": ["pi", "extension", "plan-mode", "xtrm"],
+  "author": "xtrm",
+  "license": "MIT"
+}

package/config/pi/extensions/plan-mode/utils.ts

@@ -0,0 +1,324 @@
+/**
+ * Pure utility functions for plan mode.
+ * Extracted for testability.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+// Destructive commands blocked in plan mode
+const DESTRUCTIVE_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\bchgrp\b/i,
+	/\bln\b/i,
+	/\btee\b/i,
+	/\btruncate\b/i,
+	/\bdd\b/i,
+	/\bshred\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+	/\byarn\s+(add|remove|install|publish)/i,
+	/\bpnpm\s+(add|remove|install|publish)/i,
+	/\bpip\s+(install|uninstall)/i,
+	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
+	/\bbrew\s+(install|uninstall|upgrade)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bsudo\b/i,
+	/\bsu\b/i,
+	/\bkill\b/i,
+	/\bpkill\b/i,
+	/\bkillall\b/i,
+	/\breboot\b/i,
+	/\bshutdown\b/i,
+	/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
+	/\bservice\s+\S+\s+(start|stop|restart)/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+// Safe read-only commands allowed in plan mode
+const SAFE_PATTERNS = [
+	/^\s*cat\b/,
+	/^\s*head\b/,
+	/^\s*tail\b/,
+	/^\s*less\b/,
+	/^\s*more\b/,
+	/^\s*grep\b/,
+	/^\s*find\b/,
+	/^\s*ls\b/,
+	/^\s*pwd\b/,
+	/^\s*echo\b/,
+	/^\s*printf\b/,
+	/^\s*wc\b/,
+	/^\s*sort\b/,
+	/^\s*uniq\b/,
+	/^\s*diff\b/,
+	/^\s*file\b/,
+	/^\s*stat\b/,
+	/^\s*du\b/,
+	/^\s*df\b/,
+	/^\s*tree\b/,
+	/^\s*which\b/,
+	/^\s*whereis\b/,
+	/^\s*type\b/,
+	/^\s*env\b/,
+	/^\s*printenv\b/,
+	/^\s*uname\b/,
+	/^\s*whoami\b/,
+	/^\s*id\b/,
+	/^\s*date\b/,
+	/^\s*cal\b/,
+	/^\s*uptime\b/,
+	/^\s*ps\b/,
+	/^\s*top\b/,
+	/^\s*htop\b/,
+	/^\s*free\b/,
+	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
+	/^\s*git\s+ls-/i,
+	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
+	/^\s*yarn\s+(list|info|why|audit)/i,
+	/^\s*node\s+--version/i,
+	/^\s*python\s+--version/i,
+	/^\s*curl\s/i,
+	/^\s*wget\s+-O\s*-/i,
+	/^\s*jq\b/,
+	/^\s*sed\s+-n/i,
+	/^\s*awk\b/,
+	/^\s*rg\b/,
+	/^\s*fd\b/,
+	/^\s*bat\b/,
+	/^\s*exa\b/,
+];
+
+export function isSafeCommand(command: string): boolean {
+	const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
+	const isSafe = SAFE_PATTERNS.some((p) => p.test(command));
+	return !isDestructive && isSafe;
+}
+
+export interface TodoItem {
+	step: number;
+	text: string;
+	completed: boolean;
+}
+
+export function cleanStepText(text: string): string {
+	let cleaned = text
+		.replace(/\*{1,2}([^*]+)\*{1,2}/g, "$1") // Remove bold/italic
+		.replace(/`([^`]+)`/g, "$1") // Remove code
+		.replace(
+			/^(Use|Run|Execute|Create|Write|Read|Check|Verify|Update|Modify|Add|Remove|Delete|Install)\s+(the\s+)?/i,
+			"",
+		)
+		.replace(/\s+/g, " ")
+		.trim();
+
+	if (cleaned.length > 0) {
+		cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+	}
+	if (cleaned.length > 50) {
+		cleaned = `${cleaned.slice(0, 47)}...`;
+	}
+	return cleaned;
+}
+
+export function extractTodoItems(message: string): TodoItem[] {
+	const items: TodoItem[] = [];
+	const headerMatch = message.match(/\*{0,2}Plan:\*{0,2}\s*\n/i);
+	if (!headerMatch) return items;
+
+	const planSection = message.slice(message.indexOf(headerMatch[0]) + headerMatch[0].length);
+	const numberedPattern = /^\s*(\d+)[.)]\s+\*{0,2}([^*\n]+)/gm;
+
+	const matches = Array.from(planSection.matchAll(numberedPattern));
+	for (const match of matches) {
+		const text = match[2]
+			.trim()
+			.replace(/\*{1,2}$/, "")
+			.trim();
+		if (text.length > 5 && !text.startsWith("`") && !text.startsWith("/") && !text.startsWith("-")) {
+			const cleaned = cleanStepText(text);
+			if (cleaned.length > 3) {
+				items.push({ step: items.length + 1, text: cleaned, completed: false });
+			}
+		}
+	}
+	return items;
+}
+
+export function extractDoneSteps(message: string): number[] {
+	const steps: number[] = [];
+	const matches = Array.from(message.matchAll(/\[DONE:(\d+)\]/gi));
+	for (const match of matches) {
+		const step = Number(match[1]);
+		if (Number.isFinite(step)) steps.push(step);
+	}
+	return steps;
+}
+
+export function markCompletedSteps(text: string, items: TodoItem[]): number {
+	const doneSteps = extractDoneSteps(text);
+	for (const step of doneSteps) {
+		const item = items.find((t) => t.step === step);
+		if (item) item.completed = true;
+	}
+	return doneSteps.length;
+}
+
+// =============================================================================
+// bd (beads) Integration Functions
+// =============================================================================
+
+/**
+ * Extract short ID from full bd issue ID.
+ * Example: "jaggers-agent-tools-xr9b.1" → "xr9b.1"
+ */
+export function getShortId(fullId: string): string {
+	const parts = fullId.split("-");
+	// Last part is the ID (e.g., "xr9b.1")
+	return parts[parts.length - 1];
+}
+
+/**
+ * Check if a directory is a beads project (has .beads directory).
+ */
+export function isBeadsProject(cwd: string): boolean {
+	return existsSync(join(cwd, ".beads"));
+}
+
+/**
+ * Derive epic title from user prompt or conversation messages.
+ */
+export function deriveEpicTitle(messages: Array<{ role: string; content?: unknown }>): string {
+	// Find the last user message
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "user") {
+			const content = msg.content;
+			if (typeof content === "string") {
+				// Extract first sentence or first 50 chars
+				const firstSentence = content.split(/[.!?\n]/)[0].trim();
+				if (firstSentence.length > 10 && firstSentence.length < 80) {
+					return firstSentence;
+				}
+				if (firstSentence.length >= 80) {
+					return `${firstSentence.slice(0, 77)}...`;
+				}
+			}
+		}
+	}
+	return "Plan execution";
+}
+
+/**
+ * Run a bd command and return the result.
+ */
+function runBd(args: string[], cwd: string): { stdout: string; stderr: string; status: number } {
+	const result = spawnSync("bd", args, {
+		cwd,
+		encoding: "utf8",
+		timeout: 30000,
+	});
+	return {
+		stdout: result.stdout || "",
+		stderr: result.stderr || "",
+		status: result.status ?? 1,
+	};
+}
+
+/**
+ * Create an epic in bd.
+ */
+export function bdCreateEpic(title: string, cwd: string): { id: string; title: string } | null {
+	const result = runBd(["create", title, "-t", "epic", "-p", "1", "--json"], cwd);
+	if (result.status === 0) {
+		try {
+			const data = JSON.parse(result.stdout);
+			if (Array.isArray(data) && data[0]) {
+				return { id: data[0].id, title: data[0].title };
+			}
+		} catch {
+			// Parse the ID from stdout if JSON parse fails
+			const match = result.stdout.match(/Created issue:\s*(\S+)/);
+			if (match) {
+				return { id: match[1], title };
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Create a task issue in bd under an epic.
+ */
+export function bdCreateIssue(
+	title: string,
+	description: string,
+	parentId: string,
+	cwd: string,
+): { id: string; title: string } | null {
+	const result = runBd(
+		["create", title, "-t", "task", "-p", "1", "--parent", parentId, "-d", description, "--json"],
+		cwd,
+	);
+	if (result.status === 0) {
+		try {
+			const data = JSON.parse(result.stdout);
+			if (Array.isArray(data) && data[0]) {
+				return { id: data[0].id, title: data[0].title };
+			}
+		} catch {
+			const match = result.stdout.match(/Created issue:\s*(\S+)/);
+			if (match) {
+				return { id: match[1], title };
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Claim an issue in bd.
+ */
+export function bdClaim(issueId: string, cwd: string): boolean {
+	const result = runBd(["update", issueId, "--claim"], cwd);
+	return result.status === 0;
+}
+
+/**
+ * Result of creating plan issues.
+ */
+export interface PlanIssuesResult {
+	epic: { id: string; title: string };
+	issues: Array<{ id: string; title: string }>;
+}
+
+/**
+ * Create an epic and issues from todo items.
+ */
+export function createPlanIssues(
+	epicTitle: string,
+	todos: TodoItem[],
+	cwd: string,
+): PlanIssuesResult | null {
+	const epic = bdCreateEpic(epicTitle, cwd);
+	if (!epic) return null;
+
+	const issues: Array<{ id: string; title: string }> = [];
+	for (const todo of todos) {
+		const issue = bdCreateIssue(todo.text, `Step ${todo.step} of plan: ${epicTitle}`, epic.id, cwd);
+		if (issue) {
+			issues.push(issue);
+		}
+	}
+
+	return { epic, issues };
+}

package/config/pi/extensions/quality-gates/index.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI, ToolResultEvent } from "@mariozechner/pi-coding-agent";
+import { SubprocessRunner, EventAdapter, Logger } from "../core/lib";
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+const logger = new Logger({ namespace: "quality-gates" });
+
+export default function (pi: ExtensionAPI) {
+	pi.on("tool_result", async (event, ctx) => {
+		if (!EventAdapter.isMutatingFileTool(event)) return undefined;
+
+		const cwd = ctx.cwd || process.cwd();
+		const filePath = EventAdapter.extractPathFromToolInput(event, cwd);
+		if (!filePath) return undefined;
+
+		const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+		const ext = path.extname(fullPath);
+
+		let scriptPath: string | null = null;
+		let runner: string = "node";
+
+		if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+			scriptPath = path.join(cwd, ".claude", "hooks", "quality-check.cjs");
+			runner = "node";
+		} else if (ext === ".py") {
+			scriptPath = path.join(cwd, ".claude", "hooks", "quality-check.py");
+			runner = "python3";
+		}
+
+		if (!scriptPath || !fs.existsSync(scriptPath)) return undefined;
+
+		const hookInput = JSON.stringify({
+			tool_name: event.toolName,
+			tool_input: event.input,
+			cwd: cwd,
+		});
+
+		const result = await SubprocessRunner.run(runner, [scriptPath], {
+			cwd,
+			input: hookInput,
+			env: { ...process.env, CLAUDE_PROJECT_DIR: cwd },
+			timeoutMs: 30000,
+		});
+
+		if (result.code === 0) {
+			if (result.stderr && result.stderr.trim()) {
+				const newContent = [...event.content];
+				newContent.push({ type: "text", text: `\n\n**Quality Gate**: ${result.stderr.trim()}` });
+				return { content: newContent };
+			}
+			return undefined;
+		}
+
+		if (result.code === 2) {
+			const newContent = [...event.content];
+			newContent.push({ type: "text", text: `\n\n**Quality Gate FAILED**:\n${result.stderr || result.stdout || "Unknown error"}` });
+			
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Quality Gate failed for ${path.basename(fullPath)}`, "error");
+			}
+
+			return { isError: true, content: newContent };
+		}
+
+		return undefined;
+	});
+}

package/config/pi/extensions/quality-gates/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@xtrm/pi-quality-gates",
+  "version": "1.0.0",
+  "description": "xtrm Pi extension: quality-gates",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "pi",
+    "extension",
+    "xtrm"
+  ],
+  "author": "xtrm",
+  "license": "MIT"
+}

package/config/pi/extensions/service-skills/index.ts

@@ -0,0 +1,108 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { SubprocessRunner } from "../core/lib";
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+const SERVICE_REGISTRY_FILES = [
+	"service-registry.json",
+	path.join(".claude", "skills", "service-registry.json"),
+];
+
+const GLOBAL_SKILL_ROOTS = [
+	path.join(process.env.HOME || "", ".agents", "skills"),
+	path.join(process.env.HOME || "", ".claude", "skills"),
+];
+
+export default function (pi: ExtensionAPI) {
+	const getCwd = (ctx: any) => ctx.cwd || process.cwd();
+
+	const resolveRegistryPath = (cwd: string): string | null => {
+		for (const rel of SERVICE_REGISTRY_FILES) {
+			const candidate = path.join(cwd, rel);
+			if (fs.existsSync(candidate)) return candidate;
+		}
+		return null;
+	};
+
+	const resolveSkillScript = (cwd: string, skillName: string, scriptName: string): string | null => {
+		const localPath = path.join(cwd, ".claude", "skills", skillName, "scripts", scriptName);
+		if (fs.existsSync(localPath)) return localPath;
+
+		for (const root of GLOBAL_SKILL_ROOTS) {
+			if (!root) continue;
+			const candidate = path.join(root, skillName, "scripts", scriptName);
+			if (fs.existsSync(candidate)) return candidate;
+		}
+
+		return null;
+	};
+
+	// 1. Catalog Injection
+	pi.on("before_agent_start", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		const registryPath = resolveRegistryPath(cwd);
+		if (!registryPath) return undefined;
+
+		const catalogerPath = resolveSkillScript(cwd, "using-service-skills", "cataloger.py");
+		if (!catalogerPath) return undefined;
+
+		const result = await SubprocessRunner.run("python3", [catalogerPath], {
+			cwd,
+			env: {
+				...process.env,
+				CLAUDE_PROJECT_DIR: cwd,
+				SERVICE_REGISTRY_PATH: registryPath,
+			},
+		});
+
+		if (result.code === 0 && result.stdout.trim()) {
+			return { systemPrompt: event.systemPrompt + "\n\n" + result.stdout.trim() };
+		}
+		return undefined;
+	});
+
+	const toClaudeToolName = (toolName: string): string => {
+		if (toolName === "bash") return "Bash";
+		if (toolName === "read_file") return "Read";
+		if (toolName === "write" || toolName === "create_text_file") return "Write";
+		if (toolName === "edit" || toolName === "replace_content" || toolName === "replace_lines" || toolName === "insert_at_line" || toolName === "delete_lines") return "Edit";
+		if (toolName === "search_for_pattern") return "Grep";
+		if (toolName === "find_file" || toolName === "list_dir") return "Glob";
+		return toolName;
+	};
+
+	// 2. Drift Detection (skill activation is before_agent_start only — not per-tool)
+	pi.on("tool_result", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		const registryPath = resolveRegistryPath(cwd);
+		if (!registryPath) return undefined;
+
+		const driftDetectorPath = resolveSkillScript(cwd, "updating-service-skills", "drift_detector.py");
+		if (!driftDetectorPath) return undefined;
+
+		const hookInput = JSON.stringify({
+			tool_name: toClaudeToolName(event.toolName),
+			tool_input: event.input,
+			cwd,
+		});
+
+		const result = await SubprocessRunner.run("python3", [driftDetectorPath], {
+			cwd,
+			input: hookInput,
+			env: {
+				...process.env,
+				CLAUDE_PROJECT_DIR: cwd,
+				SERVICE_REGISTRY_PATH: registryPath,
+			},
+			timeoutMs: 10000,
+		});
+
+		if (result.code === 0 && result.stdout.trim()) {
+			const newContent = [...event.content];
+			newContent.push({ type: "text", text: "\n\n" + result.stdout.trim() });
+			return { content: newContent };
+		}
+
+		return undefined;
+	});
+}

package/config/pi/extensions/service-skills/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@xtrm/pi-service-skills",
+  "version": "1.0.0",
+  "description": "xtrm Pi extension: service-skills",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "pi",
+    "extension",
+    "xtrm"
+  ],
+  "author": "xtrm",
+  "license": "MIT"
+}

package/config/pi/extensions/session-flow/index.ts

@@ -0,0 +1,131 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { isBashToolResult } from "@mariozechner/pi-coding-agent";
+import fs from "node:fs";
+import path from "node:path";
+import { SubprocessRunner, EventAdapter } from "../core/lib";
+import { readSessionState } from "../core/session-state";
+
+function isClaimCommand(command: string): { isClaim: boolean; issueId: string | null } {
+	if (!/\bbd\s+update\b/.test(command) || !/--claim\b/.test(command)) {
+		return { isClaim: false, issueId: null };
+	}
+	const match = command.match(/\bbd\s+update\s+(\S+)/);
+	return { isClaim: true, issueId: match?.[1] ?? null };
+}
+
+function statePathFrom(startCwd: string): string {
+	let current = path.resolve(startCwd || process.cwd());
+	for (;;) {
+		const candidate = path.join(current, ".xtrm-session-state.json");
+		if (fs.existsSync(candidate)) return candidate;
+		const parent = path.dirname(current);
+		if (parent === current) return path.join(startCwd, ".xtrm-session-state.json");
+		current = parent;
+	}
+}
+
+async function ensureWorktreeSessionState(cwd: string, issueId: string): Promise<{ ok: boolean; message?: string }> {
+	const repoRootResult = await SubprocessRunner.run("git", ["rev-parse", "--show-toplevel"], { cwd });
+	if (repoRootResult.code !== 0 || !repoRootResult.stdout) return { ok: false, message: "not a git repo" };
+	const repoRoot = repoRootResult.stdout.trim();
+
+	const gitDir = await SubprocessRunner.run("git", ["rev-parse", "--git-dir"], { cwd });
+	const commonDir = await SubprocessRunner.run("git", ["rev-parse", "--git-common-dir"], { cwd });
+	if (gitDir.code === 0 && commonDir.code === 0 && gitDir.stdout.trim() !== commonDir.stdout.trim()) {
+		return { ok: false, message: "already in linked worktree" };
+	}
+
+	const overstoryDir = path.join(repoRoot, ".overstory");
+	const worktreesBase = fs.existsSync(overstoryDir)
+		? path.join(overstoryDir, "worktrees")
+		: path.join(repoRoot, ".worktrees");
+	fs.mkdirSync(worktreesBase, { recursive: true });
+
+	const branch = `feature/${issueId}`;
+	const worktreePath = path.join(worktreesBase, issueId);
+	if (!fs.existsSync(worktreePath)) {
+		const branchExists = (await SubprocessRunner.run("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: repoRoot })).code === 0;
+		const addArgs = branchExists
+			? ["worktree", "add", worktreePath, branch]
+			: ["worktree", "add", worktreePath, "-b", branch];
+		const add = await SubprocessRunner.run("git", addArgs, { cwd: repoRoot, timeoutMs: 20000 });
+		if (add.code !== 0) {
+			return { ok: false, message: add.stderr || add.stdout || "worktree creation failed" };
+		}
+	}
+
+	const statePath = statePathFrom(repoRoot);
+	const payload = {
+		issueId,
+		branch,
+		worktreePath,
+		prNumber: null,
+		prUrl: null,
+		phase: "claimed",
+		conflictFiles: [],
+		startedAt: new Date().toISOString(),
+		lastChecked: new Date().toISOString(),
+	};
+	fs.writeFileSync(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+	return { ok: true, message: `Worktree created: ${worktreePath} Branch: ${branch}` };
+}
+
+export default function (pi: ExtensionAPI) {
+	const getCwd = (ctx: any) => ctx.cwd || process.cwd();
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (!isBashToolResult(event)) return undefined;
+		const cwd = getCwd(ctx);
+		if (!EventAdapter.isBeadsProject(cwd)) return undefined;
+
+		const command = event.input.command || "";
+		const { isClaim, issueId } = isClaimCommand(command);
+		if (!isClaim || !issueId) return undefined;
+
+		const ensured = await ensureWorktreeSessionState(cwd, issueId);
+		if (ensured.ok) {
+			const state = readSessionState(cwd);
+			const worktreePath = state?.worktreePath;
+			const nextStep = worktreePath
+				? `\nNext: cd ${worktreePath} && pi  (sandboxed session)`
+				: "";
+			const text = `\n\n🧭 Session Flow: ${ensured.message}${nextStep}`;
+			return { content: [...event.content, { type: "text", text }] };
+		}
+		return undefined;
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		const cwd = getCwd(ctx);
+		if (!EventAdapter.isBeadsProject(cwd)) return undefined;
+		const state = readSessionState(cwd);
+		if (!state) return undefined;
+
+		if (state.phase === "waiting-merge" || state.phase === "pending-cleanup") {
+			const pr = state.prNumber != null ? `#${state.prNumber}` : "(pending PR)";
+			const url = state.prUrl ? ` ${state.prUrl}` : "";
+			pi.sendUserMessage(
+				`⚠ PR ${pr}${url} is still pending. xtrm finish is deprecated for Pi workflow. ` +
+				"Use xtpi publish (when available) and external merge/cleanup steps.",
+			);
+			return undefined;
+		}
+
+		if (state.phase === "conflicting") {
+			const files = state.conflictFiles?.length ? state.conflictFiles.join(", ") : "unknown files";
+			pi.sendUserMessage(
+				`⚠ Conflicts in: ${files}. xtrm finish is deprecated for Pi workflow. ` +
+				"Resolve conflicts, then continue with publish-only flow.",
+			);
+			return undefined;
+		}
+
+		if (state.phase === "claimed" || state.phase === "phase1-done") {
+			pi.sendUserMessage(
+				`⚠ Session has an active worktree at ${state.worktreePath}. ` +
+				"Use publish-only workflow (no automatic push/PR/merge).",
+			);
+		}
+		return undefined;
+	});
+}

package/config/pi/extensions/session-flow/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@xtrm/pi-session-flow",
+  "version": "1.0.0",
+  "description": "xtrm Pi extension: session-flow",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "pi",
+    "extension",
+    "xtrm"
+  ],
+  "author": "xtrm",
+  "license": "MIT"
+}