@tintinweb/pi-subagents 0.4.0 → 0.4.3

package/src/index.ts

@@ -204,8 +204,44 @@ export default function (pi: ExtensionAPI) {
     30_000,
   );
 
+  /** Helper: build event data for lifecycle events from an AgentRecord. */
+  function buildEventData(record: AgentRecord) {
+    const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
+    let tokens: { input: number; output: number; total: number } | undefined;
+    try {
+      if (record.session) {
+        const stats = record.session.getSessionStats();
+        tokens = {
+          input: stats.tokens?.input ?? 0,
+          output: stats.tokens?.output ?? 0,
+          total: stats.tokens?.total ?? 0,
+        };
+      }
+    } catch { /* session stats unavailable */ }
+    return {
+      id: record.id,
+      type: record.type,
+      description: record.description,
+      result: record.result,
+      error: record.error,
+      status: record.status,
+      toolUses: record.toolUses,
+      durationMs,
+      tokens,
+    };
+  }
+
   // Background completion: route through group join or send individual nudge
   const manager = new AgentManager((record) => {
+    // Emit lifecycle event based on terminal status
+    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+    const eventData = buildEventData(record);
+    if (isError) {
+      pi.events.emit("subagents:failed", eventData);
+    } else {
+      pi.events.emit("subagents:completed", eventData);
+    }
+
     // Skip notification if result was already consumed via get_subagent_result
     if (record.resultConsumed) {
       agentActivity.delete(record.id);
@@ -228,6 +264,31 @@ export default function (pi: ExtensionAPI) {
     // 'held' → do nothing, group will fire later
     // 'delivered' → group callback already fired
     widget.update();
+  }, undefined, (record) => {
+    // Emit started event when agent transitions to running (including from queue)
+    pi.events.emit("subagents:started", {
+      id: record.id,
+      type: record.type,
+      description: record.description,
+    });
+  });
+
+  // Expose manager via Symbol.for() global registry for cross-package access.
+  // Standard Node.js pattern for cross-package singletons (used by OpenTelemetry, etc.).
+  const MANAGER_KEY = Symbol.for("pi-subagents:manager");
+  (globalThis as any)[MANAGER_KEY] = {
+    waitForAll: () => manager.waitForAll(),
+    hasRunning: () => manager.hasRunning(),
+    spawn: (piRef: any, ctx: any, type: string, prompt: string, options: any) =>
+      manager.spawn(piRef, ctx, type, prompt, options),
+    getRecord: (id: string) => manager.getRecord(id),
+  };
+
+  // Wait for all subagents on shutdown, then dispose the manager
+  pi.on("session_shutdown", async () => {
+    delete (globalThis as any)[MANAGER_KEY];
+    await manager.waitForAll();
+    manager.dispose();
   });
 
   // Live widget: show running agents above editor
@@ -347,6 +408,7 @@ Guidelines:
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).
 - Use join_mode to control how background completion notifications are delivered. By default (smart), 2+ background agents spawned in the same turn are grouped into a single notification. Use "async" for individual notifications or "group" to force grouping.`,
     parameters: Type.Object({
       prompt: Type.String({
@@ -395,6 +457,11 @@ Guidelines:
           description: "If true, fork parent conversation into the agent. Default: false (fresh context).",
         }),
       ),
+      isolation: Type.Optional(
+        Type.Literal("worktree", {
+          description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
+        }),
+      ),
       join_mode: Type.Optional(
         Type.Union([
           Type.Literal("async"),
@@ -529,6 +596,7 @@ Guidelines:
       const inheritContext = params.inherit_context ?? customConfig?.inheritContext ?? false;
       const runInBackground = params.run_in_background ?? customConfig?.runInBackground ?? false;
       const isolated = params.isolated ?? customConfig?.isolated ?? false;
+      const isolation = params.isolation ?? customConfig?.isolation;
 
       // Build display tags for non-default config
       const parentModelId = ctx.model?.id;
@@ -541,6 +609,7 @@ Guidelines:
       if (modeLabel) agentTags.push(modeLabel);
       if (thinking) agentTags.push(`thinking: ${thinking}`);
       if (isolated) agentTags.push("isolated");
+      if (isolation === "worktree") agentTags.push("worktree");
       // Shared base fields for all AgentDetails in this call
       const detailBase = {
         displayName,
@@ -581,6 +650,7 @@ Guidelines:
           inheritContext,
           thinkingLevel: thinking,
           isBackground: true,
+          isolation,
           ...bgCallbacks,
         });
 
@@ -603,6 +673,15 @@ Guidelines:
         agentActivity.set(id, bgState);
         widget.ensureTimer();
         widget.update();
+
+        // Emit created event
+        pi.events.emit("subagents:created", {
+          id,
+          type: subagentType,
+          description: params.description,
+          isBackground: true,
+        });
+
         const isQueued = record?.status === "queued";
         return textResult(
           `Agent ${isQueued ? "queued" : "started"} in background.\n` +
@@ -669,6 +748,7 @@ Guidelines:
         isolated,
         inheritContext,
         thinkingLevel: thinking,
+        isolation,
         ...fgCallbacks,
       });
 
@@ -802,6 +882,7 @@ Guidelines:
 
       try {
         await steerAgent(record.session, params.message);
+        pi.events.emit("subagents:steered", { id: record.id, message: params.message });
         return textResult(`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.`);
       } catch (err) {
         return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
@@ -1077,9 +1158,12 @@ Guidelines:
     else if (Array.isArray(cfg.extensions)) fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
     if (cfg.skills === false) fmFields.push("skills: false");
     else if (Array.isArray(cfg.skills)) fmFields.push(`skills: ${cfg.skills.join(", ")}`);
+    if (cfg.disallowedTools?.length) fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
     if (cfg.inheritContext) fmFields.push("inherit_context: true");
     if (cfg.runInBackground) fmFields.push("run_in_background: true");
     if (cfg.isolated) fmFields.push("isolated: true");
+    if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`);
+    if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
 
     const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
 
@@ -1199,10 +1283,13 @@ thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit
 max_turns: <optional max agentic turns, default 50. Omit for default>
 prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
 extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
-skills: <true (inherit all), false (none). Default: true>
+skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
+disallowed_tools: <comma-separated tool names to block, even if otherwise available. Omit for none>
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
 run_in_background: <true to run in background by default. Default: false>
 isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
+memory: <"user" (global), "project" (per-project), or "local" (gitignored per-project) for persistent memory. Omit for none>
+isolation: <"worktree" to run in isolated git worktree. Omit for normal>
 ---
 
 <system prompt body — instructions for the agent>

package/src/memory.ts

@@ -0,0 +1,165 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → ~/.pi/agent-memory/{agent-name}/
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ */
+
+import { existsSync, readFileSync, mkdirSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import type { MemoryScope } from "./types.js";
+
+/** Maximum lines to read from MEMORY.md */
+const MAX_MEMORY_LINES = 200;
+
+/**
+ * Returns true if a name contains characters not allowed in agent/skill names.
+ * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
+ */
+export function isUnsafeName(name: string): boolean {
+  if (!name || name.length > 128) return true;
+  return !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export function isSymlink(filePath: string): boolean {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export function safeReadFile(filePath: string): string | undefined {
+  if (!existsSync(filePath)) return undefined;
+  if (isSymlink(filePath)) return undefined;
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the memory directory path for a given agent + scope + cwd.
+ * Throws if agentName contains path traversal characters.
+ */
+export function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string): string {
+  if (isUnsafeName(agentName)) {
+    throw new Error(`Unsafe agent name for memory directory: "${agentName}"`);
+  }
+  switch (scope) {
+    case "user":
+      return join(homedir(), ".pi", "agent-memory", agentName);
+    case "project":
+      return join(cwd, ".pi", "agent-memory", agentName);
+    case "local":
+      return join(cwd, ".pi", "agent-memory-local", agentName);
+  }
+}
+
+/**
+ * Ensure the memory directory exists, creating it if needed.
+ * Refuses to create directories if any component in the path is a symlink
+ * to prevent symlink-based directory traversal attacks.
+ */
+export function ensureMemoryDir(memoryDir: string): void {
+  // If the directory already exists, verify it's not a symlink
+  if (existsSync(memoryDir)) {
+    if (isSymlink(memoryDir)) {
+      throw new Error(`Refusing to use symlinked memory directory: ${memoryDir}`);
+    }
+    return;
+  }
+  mkdirSync(memoryDir, { recursive: true });
+}
+
+/**
+ * Read the first N lines of MEMORY.md from the memory directory, if it exists.
+ * Returns undefined if no MEMORY.md exists or if the path is a symlink.
+ */
+export function readMemoryIndex(memoryDir: string): string | undefined {
+  // Reject symlinked memory directories
+  if (isSymlink(memoryDir)) return undefined;
+
+  const memoryFile = join(memoryDir, "MEMORY.md");
+  const content = safeReadFile(memoryFile);
+  if (content === undefined) return undefined;
+
+  const lines = content.split("\n");
+  if (lines.length > MAX_MEMORY_LINES) {
+    return lines.slice(0, MAX_MEMORY_LINES).join("\n") + "\n... (truncated at 200 lines)";
+  }
+  return content;
+}
+
+/**
+ * Build the memory block to inject into the agent's system prompt.
+ * Also ensures the memory directory exists (creates it if needed).
+ */
+export function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  // Create the memory directory so the agent can immediately write to it
+  ensureMemoryDir(memoryDir);
+
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory
+
+You have a persistent memory directory at: ${memoryDir}/
+Memory scope: ${scope}
+
+This memory persists across sessions. Use it to build up knowledge over time.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo MEMORY.md exists yet. Create one at ${join(memoryDir, "MEMORY.md")} to start building persistent memory.`;
+
+  const instructions = `
+
+## Memory Instructions
+- MEMORY.md is an index file — keep it concise (under 200 lines). Lines after 200 are truncated.
+- Store detailed memories in separate files within ${memoryDir}/ and link to them from MEMORY.md.
+- Each memory file should use this frontmatter format:
+  \`\`\`markdown
+  ---
+  name: <memory name>
+  description: <one-line description>
+  type: <user|feedback|project|reference>
+  ---
+  <memory content>
+  \`\`\`
+- Update or remove memories that become outdated. Check for existing memories before creating duplicates.
+- You have Read, Write, and Edit tools available for managing memory files.`;
+
+  return header + memoryContent + instructions;
+}
+
+/**
+ * Build a read-only memory block for agents that lack write/edit tools.
+ * Does NOT create the memory directory — agents can only consume existing memory.
+ */
+export function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory (read-only)
+
+Memory scope: ${scope}
+You have read-only access to memory. You can reference existing memories but cannot create or modify them.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo memory is available yet. Other agents or sessions with write access can create memories for you to consume.`;
+
+  return header + memoryContent;
+}

package/src/prompts.ts

@@ -4,6 +4,14 @@
 
 import type { AgentConfig, EnvInfo } from "./types.js";
 
+/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+export interface PromptExtras {
+  /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
+  memoryBlock?: string;
+  /** Preloaded skill contents to inject. */
+  skillBlocks?: { name: string; content: string }[];
+}
+
 /**
  * Build the system prompt for an agent from its config.
  *
@@ -12,18 +20,32 @@ import type { AgentConfig, EnvInfo } from "./types.js";
  * - "append" with empty systemPrompt: pure parent clone
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(
   config: AgentConfig,
   cwd: string,
   env: EnvInfo,
   parentSystemPrompt?: string,
+  extras?: PromptExtras,
 ): string {
   const envBlock = `# Environment
 Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
 Platform: ${env.platform}`;
 
+  // Build optional extras suffix
+  const extraSections: string[] = [];
+  if (extras?.memoryBlock) {
+    extraSections.push(extras.memoryBlock);
+  }
+  if (extras?.skillBlocks?.length) {
+    for (const skill of extras.skillBlocks) {
+      extraSections.push(`\n# Preloaded Skill: ${skill.name}\n${skill.content}`);
+    }
+  }
+  const extrasSuffix = extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
+
   if (config.promptMode === "append") {
     const identity = parentSystemPrompt || genericBase;
 
@@ -44,7 +66,7 @@ You are operating as a sub-agent invoked to handle a specific task.
       ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
       : "";
 
-    return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection;
+    return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
   }
 
   // "replace" mode — env header + the config's full system prompt
@@ -53,7 +75,7 @@ You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
 
-  return replaceHeader + "\n\n" + config.systemPrompt;
+  return replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */

package/src/skill-loader.ts

@@ -0,0 +1,79 @@
+/**
+ * skill-loader.ts — Preload specific skill files and inject their content into the system prompt.
+ *
+ * When skills is a string[], reads each named skill from .pi/skills/ or ~/.pi/skills/
+ * and returns their content for injection into the agent's system prompt.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { isUnsafeName, safeReadFile } from "./memory.js";
+
+export interface PreloadedSkill {
+  name: string;
+  content: string;
+}
+
+/**
+ * Attempt to load named skills from project and global skill directories.
+ * Looks for: <dir>/<name>.md, <dir>/<name>.txt, <dir>/<name>
+ *
+ * @param skillNames  List of skill names to preload.
+ * @param cwd         Working directory for project-level skills.
+ * @returns Array of loaded skills (missing skills are skipped with a warning comment).
+ */
+export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
+  const results: PreloadedSkill[] = [];
+
+  for (const name of skillNames) {
+    // Unlike memory (which throws on unsafe names because it's part of agent setup),
+    // skills are optional — skip gracefully to avoid blocking agent startup.
+    if (isUnsafeName(name)) {
+      results.push({ name, content: `(Skill "${name}" skipped: name contains path traversal characters)` });
+      continue;
+    }
+    const content = findAndReadSkill(name, cwd);
+    if (content !== undefined) {
+      results.push({ name, content });
+    } else {
+      // Include a note about missing skills so the agent knows it was requested but not found
+      results.push({ name, content: `(Skill "${name}" not found in .pi/skills/ or ~/.pi/skills/)` });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Search for a skill file in project and global directories.
+ * Project-level takes priority over global.
+ */
+function findAndReadSkill(name: string, cwd: string): string | undefined {
+  const projectDir = join(cwd, ".pi", "skills");
+  const globalDir = join(homedir(), ".pi", "skills");
+
+  // Try project first, then global
+  for (const dir of [projectDir, globalDir]) {
+    const content = tryReadSkillFile(dir, name);
+    if (content !== undefined) return content;
+  }
+
+  return undefined;
+}
+
+/**
+ * Try to read a skill file from a directory.
+ * Tries extensions in order: .md, .txt, (no extension)
+ */
+function tryReadSkillFile(dir: string, name: string): string | undefined {
+  const extensions = [".md", ".txt", ""];
+
+  for (const ext of extensions) {
+    const path = join(dir, name + ext);
+    // safeReadFile rejects symlinks to prevent reading arbitrary files
+    const content = safeReadFile(path);
+    if (content !== undefined) return content.trim();
+  }
+
+  return undefined;
+}

package/src/types.ts

@@ -13,12 +13,20 @@ export type SubagentType = string;
 /** Names of the three embedded default agents. */
 export const DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as const;
 
+/** Memory scope for persistent agent memory. */
+export type MemoryScope = "user" | "project" | "local";
+
+/** Isolation mode for agent execution. */
+export type IsolationMode = "worktree";
+
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
   name: string;
   displayName?: string;
   description: string;
   builtinToolNames?: string[];
+  /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
+  disallowedTools?: string[];
   /** true = inherit all, string[] = only listed, false = none */
   extensions: true | string[] | false;
   /** true = inherit all, string[] = only listed, false = none */
@@ -34,6 +42,10 @@ export interface AgentConfig {
   runInBackground: boolean;
   /** Default for spawn: no extension tools */
   isolated: boolean;
+  /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
+  memory?: MemoryScope;
+  /** Isolation mode — "worktree" runs the agent in a temporary git worktree */
+  isolation?: IsolationMode;
   /** true = this is an embedded default agent (informational) */
   isDefault?: boolean;
   /** false = agent is hidden from the registry */
@@ -61,6 +73,10 @@ export interface AgentRecord {
   joinMode?: JoinMode;
   /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
   resultConsumed?: boolean;
+  /** Worktree info if the agent is running in an isolated worktree. */
+  worktree?: { path: string; branch: string };
+  /** Worktree cleanup result after agent completion. */
+  worktreeResult?: { hasChanges: boolean; branch?: string };
 }
 
 export interface EnvInfo {

package/src/worktree.ts

@@ -0,0 +1,162 @@
+/**
+ * worktree.ts — Git worktree isolation for agents.
+ *
+ * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
+ * On completion, if no changes were made, the worktree is cleaned up.
+ * If changes exist, a branch is created and returned in the result.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+export interface WorktreeInfo {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Branch name created for this worktree (if changes exist). */
+  branch: string;
+}
+
+export interface WorktreeCleanupResult {
+  /** Whether changes were found in the worktree. */
+  hasChanges: boolean;
+  /** Branch name if changes were committed. */
+  branch?: string;
+  /** Worktree path if it was kept. */
+  path?: string;
+}
+
+/**
+ * Create a temporary git worktree for an agent.
+ * Returns the worktree path, or undefined if not in a git repo.
+ */
+export function createWorktree(cwd: string, agentId: string): WorktreeInfo | undefined {
+  // Verify we're in a git repo with at least one commit (HEAD must exist)
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
+    execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 });
+  } catch {
+    return undefined;
+  }
+
+  const branch = `pi-agent-${agentId}`;
+  const suffix = randomUUID().slice(0, 8);
+  const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
+
+  try {
+    // Create detached worktree at HEAD
+    execFileSync("git", ["worktree", "add", "--detach", worktreePath, "HEAD"], {
+      cwd,
+      stdio: "pipe",
+      timeout: 30000,
+    });
+    return { path: worktreePath, branch };
+  } catch {
+    // If worktree creation fails, return undefined (agent runs in normal cwd)
+    return undefined;
+  }
+}
+
+/**
+ * Clean up a worktree after agent completion.
+ * - If no changes: remove worktree entirely.
+ * - If changes exist: create a branch, commit changes, return branch info.
+ */
+export function cleanupWorktree(
+  cwd: string,
+  worktree: WorktreeInfo,
+  agentDescription: string,
+): WorktreeCleanupResult {
+  if (!existsSync(worktree.path)) {
+    return { hasChanges: false };
+  }
+
+  try {
+    // Check for uncommitted changes in the worktree
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: worktree.path,
+      stdio: "pipe",
+      timeout: 10000,
+    }).toString().trim();
+
+    if (!status) {
+      // No changes — remove worktree
+      removeWorktree(cwd, worktree.path);
+      return { hasChanges: false };
+    }
+
+    // Changes exist — stage, commit, and create a branch
+    execFileSync("git", ["add", "-A"], { cwd: worktree.path, stdio: "pipe", timeout: 10000 });
+    // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
+    const safeDesc = agentDescription.slice(0, 200);
+    const commitMsg = `pi-agent: ${safeDesc}`;
+    execFileSync("git", ["commit", "-m", commitMsg], {
+      cwd: worktree.path,
+      stdio: "pipe",
+      timeout: 10000,
+    });
+
+    // Create a branch pointing to the worktree's HEAD.
+    // If the branch already exists, append a suffix to avoid overwriting previous work.
+    let branchName = worktree.branch;
+    try {
+      execFileSync("git", ["branch", branchName], {
+        cwd: worktree.path,
+        stdio: "pipe",
+        timeout: 5000,
+      });
+    } catch {
+      // Branch already exists — use a unique suffix
+      branchName = `${worktree.branch}-${Date.now()}`;
+      execFileSync("git", ["branch", branchName], {
+        cwd: worktree.path,
+        stdio: "pipe",
+        timeout: 5000,
+      });
+    }
+    // Update branch name in worktree info for the caller
+    worktree.branch = branchName;
+
+    // Remove the worktree (branch persists in main repo)
+    removeWorktree(cwd, worktree.path);
+
+    return {
+      hasChanges: true,
+      branch: worktree.branch,
+      path: worktree.path,
+    };
+  } catch {
+    // Best effort cleanup on error
+    try { removeWorktree(cwd, worktree.path); } catch { /* ignore */ }
+    return { hasChanges: false };
+  }
+}
+
+/**
+ * Force-remove a worktree.
+ */
+function removeWorktree(cwd: string, worktreePath: string): void {
+  try {
+    execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
+      cwd,
+      stdio: "pipe",
+      timeout: 10000,
+    });
+  } catch {
+    // If git worktree remove fails, try pruning
+    try {
+      execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+    } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Prune any orphaned worktrees (crash recovery).
+ */
+export function pruneWorktrees(cwd: string): void {
+  try {
+    execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+  } catch { /* ignore */ }
+}