@adhdev/daemon-core 0.9.76-rc.2 → 0.9.76-rc.20

package/src/commands/router.ts

@@ -30,10 +30,11 @@ import { SessionRegistry } from '../sessions/registry.js';
 import { LOG } from '../logging/logger.js';
 import { logCommand } from '../logging/command-log.js';
 import type { CommandLogEntry } from '../logging/command-log.js';
+import * as yaml from 'js-yaml';
 import { getRecentLogs, LOG_PATH } from '../logging/logger.js';
 import { createInteractionId, getRecentDebugTrace, recordDebugTrace } from '../logging/debug-trace.js';
 import { getSessionHostSurfaceKind, partitionSessionHostRecords } from '../session-host/runtime-surface.js';
-import { resolveMeshCoordinatorSetup } from './mesh-coordinator.js';
+import { createHermesManualMeshCoordinatorSetup, resolveMeshCoordinatorSetup } from './mesh-coordinator.js';
 import { buildSessionEntries } from '../status/builders.js';
 import { buildMachineInfo, buildStatusSnapshot } from '../status/snapshot.js';
 import { getSessionCompletionMarker } from '../status/snapshot.js';
@@ -41,6 +42,10 @@ import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDa
 
 type ReleaseChannel = 'stable' | 'preview';
 const CHANNEL_NPM_TAG: Record<ReleaseChannel, 'latest' | 'next'> = { stable: 'latest', preview: 'next' };
+const CHANNEL_SERVER_URL: Record<ReleaseChannel, string> = {
+    stable: 'https://api.adhf.dev',
+    preview: 'https://api-preview.adhf.dev',
+};
 
 function normalizeReleaseChannel(value: unknown): ReleaseChannel | null {
     if (typeof value !== 'string') return null;
@@ -59,6 +64,28 @@ function resolveUpgradeChannel(args: any): ReleaseChannel {
 }
 import * as fs from 'fs';
 
+type MeshCoordinatorConfigFormat = 'claude_mcp_json' | 'hermes_config_yaml';
+
+function loadYamlModule(): { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string } {
+    return yaml as { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string };
+}
+
+function getMcpServersKey(format: MeshCoordinatorConfigFormat): 'mcpServers' | 'mcp_servers' {
+    return format === 'hermes_config_yaml' ? 'mcp_servers' : 'mcpServers';
+}
+
+function parseMeshCoordinatorMcpConfig(text: string, format: MeshCoordinatorConfigFormat): Record<string, any> {
+    if (!text.trim()) return {};
+    if (format === 'claude_mcp_json') return JSON.parse(text);
+    const parsed = loadYamlModule().load(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+}
+
+function serializeMeshCoordinatorMcpConfig(config: Record<string, any>, format: MeshCoordinatorConfigFormat): string {
+    if (format === 'claude_mcp_json') return JSON.stringify(config, null, 2);
+    return loadYamlModule().dump(config, { noRefs: true, lineWidth: 120 });
+}
+
 // ─── Types ───
 
 export interface SessionHostControlPlane {
@@ -222,6 +249,43 @@ export class DaemonCommandRouter {
         this.deps = deps;
     }
 
+    private getCachedInlineMesh(meshId: string, inlineMesh?: unknown): any | undefined {
+        if (inlineMesh && typeof inlineMesh === 'object') {
+            this.inlineMeshCache.set(meshId, inlineMesh as any);
+            return inlineMesh as any;
+        }
+        return this.inlineMeshCache.get(meshId);
+    }
+
+    private async getMeshForCommand(meshId: string, inlineMesh?: unknown): Promise<{ mesh: any; inline: boolean } | null> {
+        try {
+            const { getMesh } = await import('../config/mesh-config.js');
+            const mesh = getMesh(meshId);
+            if (mesh) return { mesh, inline: false };
+        } catch { /* fall through to inline cache */ }
+        const cached = this.getCachedInlineMesh(meshId, inlineMesh);
+        return cached ? { mesh: cached, inline: true } : null;
+    }
+
+    private updateInlineMeshNode(meshId: string, mesh: any, node: any): void {
+        if (!mesh || !Array.isArray(mesh.nodes) || !node?.id) return;
+        const idx = mesh.nodes.findIndex((entry: any) => entry?.id === node.id || entry?.nodeId === node.id);
+        if (idx >= 0) mesh.nodes[idx] = node;
+        else mesh.nodes.push(node);
+        mesh.updatedAt = new Date().toISOString();
+        this.inlineMeshCache.set(meshId, mesh);
+    }
+
+    private removeInlineMeshNode(meshId: string, mesh: any, nodeId: string): boolean {
+        if (!mesh || !Array.isArray(mesh.nodes)) return false;
+        const idx = mesh.nodes.findIndex((entry: any) => entry?.id === nodeId || entry?.nodeId === nodeId);
+        if (idx === -1) return false;
+        mesh.nodes.splice(idx, 1);
+        mesh.updatedAt = new Date().toISOString();
+        this.inlineMeshCache.set(meshId, mesh);
+        return true;
+    }
+
     private async traceSessionHostAction<T>(
         action: string,
         args: any,
@@ -892,6 +956,7 @@ export class DaemonCommandRouter {
                     // Check channel-pinned dist-tag and resolve it to a concrete install version.
                     const latest = String(execNpmCommandSync(['view', `${pkgName}@${npmTag}`, 'version'], { encoding: 'utf-8', timeout: 10000 }, npmSurface)).trim();
                     LOG.info('Upgrade', `Latest ${pkgName}@${npmTag}: v${latest}`);
+                    updateConfig({ updateChannel: channel, serverUrl: CHANNEL_SERVER_URL[channel] } as any);
                     let currentInstalled: string | null = null;
                     try {
                         const currentJson = String(execNpmCommandSync(['ls', '-g', pkgName, '--depth=0', '--json'], {
@@ -1017,14 +1082,107 @@ export class DaemonCommandRouter {
                 const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
                 if (!meshId || !nodeId) return { success: false, error: 'meshId and nodeId required' };
                 try {
-                    const { removeNode } = await import('../config/mesh-config.js');
-                    const removed = removeNode(meshId, nodeId);
+                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
+                    const mesh = meshRecord?.mesh;
+                    const node = mesh?.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
+
+                    // If this is a worktree node, clean up the git worktree first
+                    if (node?.isLocalWorktree && node.workspace) {
+                        try {
+                            const sourceNode = node.clonedFromNodeId
+                                ? mesh?.nodes.find((n: any) => n.id === node.clonedFromNodeId || n.nodeId === node.clonedFromNodeId)
+                                : mesh?.nodes.find((n: any) => !n.isLocalWorktree);
+                            const repoRoot = sourceNode?.repoRoot || sourceNode?.workspace;
+                            if (repoRoot) {
+                                const { removeWorktree } = await import('../git/git-worktree.js');
+                                await removeWorktree(repoRoot, node.workspace);
+                            }
+                        } catch (e: any) {
+                            LOG.warn('MeshNode', `Worktree cleanup failed for ${nodeId}: ${e.message}`);
+                            // Continue with node removal even if worktree cleanup fails
+                        }
+                    }
+
+                    let removed = false;
+                    if (meshRecord?.inline) {
+                        removed = this.removeInlineMeshNode(meshId, mesh, nodeId);
+                    } else {
+                        const { removeNode } = await import('../config/mesh-config.js');
+                        removed = removeNode(meshId, nodeId);
+                    }
                     return { success: true, removed };
                 } catch (e: any) {
                     return { success: false, error: e.message };
                 }
             }
 
+            case 'clone_mesh_node': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const sourceNodeId = typeof args?.sourceNodeId === 'string' ? args.sourceNodeId.trim() : '';
+                const branch = typeof args?.branch === 'string' ? args.branch.trim() : '';
+                const baseBranch = typeof args?.baseBranch === 'string' ? args.baseBranch.trim() : undefined;
+                if (!meshId) return { success: false, error: 'meshId required' };
+                if (!sourceNodeId) return { success: false, error: 'sourceNodeId required' };
+                if (!branch) return { success: false, error: 'branch required' };
+
+                try {
+                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
+                    const mesh = meshRecord?.mesh;
+                    if (!mesh) return { success: false, error: 'Mesh not found' };
+
+                    const sourceNode = mesh.nodes?.find((n: any) => n.id === sourceNodeId || n.nodeId === sourceNodeId);
+                    if (!sourceNode) return { success: false, error: `Source node '${sourceNodeId}' not found in mesh` };
+
+                    const repoRoot = sourceNode.repoRoot || sourceNode.workspace;
+                    const { createWorktree } = await import('../git/git-worktree.js');
+                    const result = await createWorktree({
+                        repoRoot,
+                        branch,
+                        baseBranch,
+                        meshName: mesh.name,
+                    });
+
+                    let node: any;
+                    if (meshRecord.inline) {
+                        const { randomUUID } = await import('crypto');
+                        node = {
+                            id: `node_${randomUUID().replace(/-/g, '')}`,
+                            workspace: result.worktreePath,
+                            repoRoot: result.worktreePath,
+                            daemonId: sourceNode.daemonId,
+                            userOverrides: { ...(sourceNode.userOverrides || {}) },
+                            policy: { ...(sourceNode.policy || {}) },
+                            isLocalWorktree: true,
+                            worktreeBranch: result.branch,
+                            clonedFromNodeId: sourceNodeId,
+                        };
+                        this.updateInlineMeshNode(meshId, mesh, node);
+                    } else {
+                        const { addNode } = await import('../config/mesh-config.js');
+                        node = addNode(meshId, {
+                            workspace: result.worktreePath,
+                            repoRoot: result.worktreePath,
+                            daemonId: sourceNode.daemonId,
+                            userOverrides: { ...(sourceNode.userOverrides || {}) },
+                            isLocalWorktree: true,
+                            worktreeBranch: result.branch,
+                            clonedFromNodeId: sourceNodeId,
+                            policy: { ...(sourceNode.policy || {}) },
+                        });
+                        if (!node) return { success: false, error: 'Failed to register worktree node' };
+                    }
+
+                    return {
+                        success: true,
+                        node,
+                        worktreePath: result.worktreePath,
+                        branch: result.branch,
+                    };
+                } catch (e: any) {
+                    return { success: false, error: e.message };
+                }
+            }
+
             // ─── Mesh Coordinator Launch ───
             case 'launch_mesh_coordinator': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
@@ -1069,6 +1227,7 @@ export class DaemonCommandRouter {
                     const providerMeta = this.deps.providerLoader.resolve?.(cliType) || this.deps.providerLoader.getMeta(cliType);
                     const coordinatorSetup = resolveMeshCoordinatorSetup({
                         provider: providerMeta,
+                        cliType,
                         meshId,
                         workspace,
                     });
@@ -1096,7 +1255,8 @@ export class DaemonCommandRouter {
                         };
                     }
 
-                    if (coordinatorSetup.configFormat !== 'claude_mcp_json') {
+                    const configFormat = coordinatorSetup.configFormat as MeshCoordinatorConfigFormat;
+                    if (configFormat !== 'claude_mcp_json' && configFormat !== 'hermes_config_yaml') {
                         return {
                             success: false,
                             code: 'mesh_coordinator_unsupported',
@@ -1107,20 +1267,42 @@ export class DaemonCommandRouter {
                         };
                     }
 
-                    // 1. Write provider-declared MCP config to workspace for CLIs that auto-import it.
-                    const { existsSync, readFileSync, writeFileSync, copyFileSync } = await import('fs');
-                    const mcpConfigPath = coordinatorSetup.configPath;
-
-                    // Backup existing MCP config if present.
-                    const hadExistingMcpConfig = existsSync(mcpConfigPath);
-                    let existingMcpConfig: any = {};
-                    if (hadExistingMcpConfig) {
-                        try {
-                            existingMcpConfig = JSON.parse(readFileSync(mcpConfigPath, 'utf-8'));
-                            copyFileSync(mcpConfigPath, mcpConfigPath + '.backup');
-                        } catch { /* empty */ }
+                    // Build the coordinator prompt before mutating workspace config or launching.
+                    // Prompt generation failures are configuration/data-shape errors; fail closed so
+                    // broken mesh state is visible instead of silently launching with weaker rules.
+                    let systemPrompt = '';
+                    try {
+                        systemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType });
+                    } catch (error: any) {
+                        const message = error?.message || String(error);
+                        LOG.error('MeshCoordinator', `Failed to build coordinator prompt: ${message}`);
+                        return {
+                            success: false,
+                            code: 'mesh_coordinator_prompt_failed',
+                            error: `Failed to build Repo Mesh coordinator prompt: ${message}`,
+                            meshId,
+                            cliType,
+                            workspace,
+                        };
                     }
 
+                    // 1. Write provider-declared MCP config for CLIs that auto-import it.
+                    const { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } = await import('fs');
+                    const { dirname } = await import('path');
+                    const mcpConfigPath = coordinatorSetup.configPath;
+                    const hermesManualFallback = cliType === 'hermes-cli' && configFormat === 'hermes_config_yaml'
+                        ? createHermesManualMeshCoordinatorSetup(meshId, workspace)
+                        : null;
+                    const returnManualFallback = (message: string) => ({
+                        success: false,
+                        code: 'mesh_coordinator_manual_mcp_setup_required',
+                        error: message,
+                        meshId,
+                        cliType,
+                        workspace,
+                        meshCoordinatorSetup: hermesManualFallback,
+                    });
+
                     // Merge ADHDev mesh server into existing config.
                     // Pass full mesh data as env var so the MCP server can bootstrap
                     // without depending on meshes.json or a running daemon.
@@ -1131,41 +1313,76 @@ export class DaemonCommandRouter {
                     if (args?.inlineMesh) {
                         mcpServerEntry.env = {
                             ADHDEV_INLINE_MESH: JSON.stringify(mesh),
+                            ADHDEV_MCP_TRANSPORT: 'ipc',
                         };
                     }
+
+                    try {
+                        mkdirSync(dirname(mcpConfigPath), { recursive: true });
+                    } catch (error: any) {
+                        const message = `Could not prepare MCP config path for automatic setup: ${error?.message || error}`;
+                        LOG.error('MeshCoordinator', message);
+                        if (hermesManualFallback) return returnManualFallback(message);
+                        return { success: false, code: 'mesh_coordinator_config_write_failed', error: message, meshId, cliType, workspace };
+                    }
+
+                    // Backup existing MCP config if present.
+                    const hadExistingMcpConfig = existsSync(mcpConfigPath);
+                    let existingMcpConfig: Record<string, any> = {};
+                    if (hadExistingMcpConfig) {
+                        try {
+                            existingMcpConfig = parseMeshCoordinatorMcpConfig(readFileSync(mcpConfigPath, 'utf-8'), configFormat);
+                            copyFileSync(mcpConfigPath, mcpConfigPath + '.backup');
+                        } catch (error: any) {
+                            LOG.error('MeshCoordinator', `Failed to parse existing MCP config ${mcpConfigPath}: ${error?.message || error}`);
+                            return {
+                                success: false,
+                                code: 'mesh_coordinator_config_parse_failed',
+                                error: `Failed to parse existing MCP config at ${mcpConfigPath}`,
+                            };
+                        }
+                    }
+
+                    const mcpServersKey = getMcpServersKey(configFormat);
+                    const existingServers = existingMcpConfig[mcpServersKey];
                     const mcpConfig = {
                         ...existingMcpConfig,
-                        mcpServers: {
-                            ...(existingMcpConfig.mcpServers || {}),
+                        [mcpServersKey]: {
+                            ...(existingServers && typeof existingServers === 'object' && !Array.isArray(existingServers) ? existingServers : {}),
                             [coordinatorSetup.serverName]: mcpServerEntry,
                         },
                     };
-                    writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2), 'utf-8');
-                    LOG.info('MeshCoordinator', `Wrote ${mcpConfigPath} with ${coordinatorSetup.serverName} server`);
-
-                    // 2. Build coordinator system prompt
-                    let systemPrompt = '';
                     try {
-                        systemPrompt = buildCoordinatorSystemPrompt({ mesh });
-                    } catch {
-                        systemPrompt = `You are a Repo Mesh Coordinator for "${mesh.name}". Use the adhdev-mesh MCP tools (mesh_status, mesh_list_nodes, mesh_send_task, mesh_read_chat, mesh_launch_session, etc.) to orchestrate work across ${mesh.nodes.length} node(s).`;
+                        writeFileSync(mcpConfigPath, serializeMeshCoordinatorMcpConfig(mcpConfig, configFormat), 'utf-8');
+                    } catch (error: any) {
+                        const message = `Could not write MCP config for automatic setup: ${error?.message || error}`;
+                        LOG.error('MeshCoordinator', message);
+                        if (hermesManualFallback) return returnManualFallback(message);
+                        return { success: false, code: 'mesh_coordinator_config_write_failed', error: message, meshId, cliType, workspace };
                     }
+                    LOG.info('MeshCoordinator', `Wrote ${mcpConfigPath} with ${coordinatorSetup.serverName} server`);
 
                     const cliArgs: string[] = [];
+                    const launchEnv: Record<string, string> = {};
                     if (systemPrompt) {
-                        cliArgs.push('--append-system-prompt', systemPrompt);
+                        if (configFormat === 'hermes_config_yaml') {
+                            launchEnv.HERMES_EPHEMERAL_SYSTEM_PROMPT = systemPrompt;
+                        } else {
+                            cliArgs.push('--append-system-prompt', systemPrompt);
+                        }
                     }
                     if (cliType === 'claude-cli') {
                         cliArgs.push('--mcp-config', coordinatorSetup.configPath);
                     }
 
-                    // 3. Launch CLI session via existing cliManager
-                    // Pass coordinator system prompt via --append-system-prompt so the
-                    // CLI inherits its default behavior AND knows it is a mesh coordinator.
+                    // 3. Launch CLI session via existing cliManager.
+                    // Provider-specific prompt injection remains fail-closed: Claude gets
+                    // explicit CLI args, while Hermes reads HERMES_EPHEMERAL_SYSTEM_PROMPT.
                     const launchResult: any = await this.deps.cliManager.handleCliCommand('launch_cli', {
                         cliType,
                         dir: workspace,
                         cliArgs: cliArgs.length > 0 ? cliArgs : undefined,
+                        env: Object.keys(launchEnv).length > 0 ? launchEnv : undefined,
                         settings: {
                             meshCoordinatorFor: meshId
                         }

package/src/config/mesh-config.ts

@@ -160,9 +160,12 @@ export function deleteMesh(meshId: string): boolean {
 export interface AddNodeOptions {
     workspace: string;
     repoRoot?: string;
+    daemonId?: string;
     userOverrides?: Partial<RepoMeshNodeCapabilities>;
     policy?: RepoMeshNodePolicy;
     isLocalWorktree?: boolean;
+    worktreeBranch?: string;
+    clonedFromNodeId?: string;
 }
 
 export function addNode(meshId: string, opts: AddNodeOptions): LocalMeshNodeEntry | undefined {
@@ -183,9 +186,12 @@ export function addNode(meshId: string, opts: AddNodeOptions): LocalMeshNodeEntr
         id: `node_${randomUUID().replace(/-/g, '')}`,
         workspace: opts.workspace.trim(),
         repoRoot: opts.repoRoot,
+        daemonId: opts.daemonId,
         userOverrides: opts.userOverrides || {},
         policy: opts.policy || {},
         isLocalWorktree: opts.isLocalWorktree,
+        worktreeBranch: opts.worktreeBranch,
+        clonedFromNodeId: opts.clonedFromNodeId,
     };
 
     mesh.nodes.push(node);

package/src/git/git-worktree.ts

@@ -0,0 +1,214 @@
+/**
+ * Git Worktree — Create/remove/list worktrees for Repo Mesh node cloning
+ *
+ * Used by the `clone_mesh_node` daemon command to create isolated
+ * worktree-based nodes for parallel branch work within a mesh.
+ *
+ * Worktrees are placed outside the source repo to avoid .gitignore
+ * pollution and submodule conflicts:
+ *   <repoParent>/.adhdev-worktrees/<meshName>/<branch>/
+ */
+
+import * as path from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const WORKTREE_DIR_NAME = '.adhdev-worktrees';
+const GIT_TIMEOUT_MS = 30_000;
+const GIT_MAX_BUFFER = 4 * 1024 * 1024;
+
+// ─── Types ──────────────────────────────────────
+
+export interface WorktreeCreateOptions {
+    /** Absolute path to the source repo's git root */
+    repoRoot: string;
+    /** Branch name for the new worktree */
+    branch: string;
+    /** Starting point for the branch (default: HEAD) */
+    baseBranch?: string;
+    /** Mesh name, used for organizing worktree directories */
+    meshName: string;
+    /** Override the auto-resolved target directory */
+    targetDir?: string;
+}
+
+export interface WorktreeCreateResult {
+    success: true;
+    worktreePath: string;
+    branch: string;
+}
+
+export interface WorktreeEntry {
+    path: string;
+    head: string;
+    branch: string | null;
+    bare: boolean;
+}
+
+export interface WorktreeRemoveResult {
+    success: true;
+    removedPath: string;
+}
+
+// ─── Path Resolution ────────────────────────────
+
+/**
+ * Resolve the target directory for a new worktree.
+ * Places worktrees at: <repoParent>/.adhdev-worktrees/<meshName>/<branch>/
+ */
+export function resolveWorktreePath(repoRoot: string, meshName: string, branch: string): string {
+    // Sanitize branch name for filesystem (e.g. feat/auth → feat-auth)
+    const safeBranch = branch.replace(/[/\\:*?"<>|]/g, '-').replace(/^\.+|\.+$/g, '');
+    const safeMeshName = meshName.replace(/[/\\:*?"<>|]/g, '-').replace(/^\.+|\.+$/g, '');
+    const parentDir = path.dirname(repoRoot);
+    return path.join(parentDir, WORKTREE_DIR_NAME, safeMeshName, safeBranch);
+}
+
+// ─── Create ─────────────────────────────────────
+
+/**
+ * Create a new git worktree with a fresh branch.
+ *
+ * Runs: git worktree add <targetDir> -b <branch> [baseBranch]
+ */
+export async function createWorktree(opts: WorktreeCreateOptions): Promise<WorktreeCreateResult> {
+    const { repoRoot, branch, baseBranch, meshName } = opts;
+    const targetDir = opts.targetDir || resolveWorktreePath(repoRoot, meshName, branch);
+
+    if (existsSync(targetDir)) {
+        throw new Error(`Worktree target directory already exists: ${targetDir}`);
+    }
+
+    // Ensure parent directory exists
+    await mkdir(path.dirname(targetDir), { recursive: true });
+
+    const args = ['worktree', 'add', targetDir, '-b', branch];
+    if (baseBranch) {
+        args.push(baseBranch);
+    }
+
+    try {
+        await execFileAsync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER,
+            windowsHide: true,
+        });
+    } catch (error: any) {
+        const stderr = typeof error.stderr === 'string' ? error.stderr : '';
+        // Clean error messages for common failures
+        if (/already exists/i.test(stderr)) {
+            throw new Error(`Branch '${branch}' already exists or is checked out in another worktree`);
+        }
+        throw new Error(`git worktree add failed: ${stderr.trim() || error.message}`);
+    }
+
+    return {
+        success: true,
+        worktreePath: targetDir,
+        branch,
+    };
+}
+
+// ─── Remove ─────────────────────────────────────
+
+/**
+ * Remove a git worktree and clean up the directory.
+ *
+ * Runs: git worktree remove <worktreePath> --force
+ */
+export async function removeWorktree(repoRoot: string, worktreePath: string): Promise<WorktreeRemoveResult> {
+    if (!existsSync(worktreePath)) {
+        // Already gone — just prune
+        await pruneWorktrees(repoRoot);
+        return { success: true, removedPath: worktreePath };
+    }
+
+    try {
+        await execFileAsync('git', ['worktree', 'remove', worktreePath, '--force'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER,
+            windowsHide: true,
+        });
+    } catch (error: any) {
+        const stderr = typeof error.stderr === 'string' ? error.stderr : '';
+        throw new Error(`git worktree remove failed: ${stderr.trim() || error.message}`);
+    }
+
+    return { success: true, removedPath: worktreePath };
+}
+
+// ─── List ───────────────────────────────────────
+
+/**
+ * List all worktrees for a repository.
+ *
+ * Runs: git worktree list --porcelain
+ */
+export async function listWorktrees(repoRoot: string): Promise<WorktreeEntry[]> {
+    const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER,
+        windowsHide: true,
+    });
+
+    return parseWorktreeListOutput(stdout);
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into structured entries.
+ */
+export function parseWorktreeListOutput(output: string): WorktreeEntry[] {
+    const entries: WorktreeEntry[] = [];
+    const blocks = output.trim().split(/\n\n+/);
+
+    for (const block of blocks) {
+        if (!block.trim()) continue;
+        const lines = block.trim().split('\n');
+        const entry: WorktreeEntry = { path: '', head: '', branch: null, bare: false };
+
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                entry.path = line.slice('worktree '.length).trim();
+            } else if (line.startsWith('HEAD ')) {
+                entry.head = line.slice('HEAD '.length).trim();
+            } else if (line.startsWith('branch ')) {
+                const ref = line.slice('branch '.length).trim();
+                // refs/heads/feat/auth → feat/auth
+                entry.branch = ref.replace(/^refs\/heads\//, '');
+            } else if (line === 'bare') {
+                entry.bare = true;
+            }
+        }
+
+        if (entry.path) {
+            entries.push(entry);
+        }
+    }
+
+    return entries;
+}
+
+// ─── Prune ──────────────────────────────────────
+
+async function pruneWorktrees(repoRoot: string): Promise<void> {
+    try {
+        await execFileAsync('git', ['worktree', 'prune'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+        });
+    } catch {
+        // Prune is best-effort
+    }
+}

package/src/git/index.ts

@@ -73,3 +73,17 @@ export type {
 
 export { TurnSnapshotTracker } from './turn-snapshot-tracker.js';
 export type { TurnCompletedCallback } from './turn-snapshot-tracker.js';
+
+export {
+  createWorktree,
+  listWorktrees,
+  parseWorktreeListOutput,
+  removeWorktree,
+  resolveWorktreePath,
+} from './git-worktree.js';
+export type {
+  WorktreeCreateOptions,
+  WorktreeCreateResult,
+  WorktreeEntry,
+  WorktreeRemoveResult,
+} from './git-worktree.js';