@jokerized/getresearchdone 0.4.1

package/dist/lib/worktree.js

@@ -0,0 +1,999 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { execGit, output, error, getMilestoneInfo, loadConfig, findPhaseInternal, generateSlugInternal, } = require('./utils');
+// ─── Internal Helpers ─────────────────────────────────────────────────────────
+/**
+ * Compute the worktree directory path for a given milestone and phase.
+ * Uses project-local .worktrees/ directory to avoid OS temp cleanup issues.
+ * Resolves cwd via realpathSync to handle macOS symlinks.
+ */
+function worktreePath(cwd, milestone, phase) {
+    const resolvedCwd = fs.realpathSync(cwd);
+    return path.join(resolvedCwd, '.worktrees', `grd-worktree-${milestone}-${phase}`);
+}
+/**
+ * Ensure .worktrees/ directory exists and is listed in .gitignore.
+ */
+function ensureWorktreesDir(cwd) {
+    const worktreesDir = path.join(cwd, '.worktrees');
+    if (!fs.existsSync(worktreesDir)) {
+        fs.mkdirSync(worktreesDir, { recursive: true });
+    }
+    // Add .worktrees/ to .gitignore if not already present
+    const gitignorePath = path.join(cwd, '.gitignore');
+    let gitignoreContent = '';
+    try {
+        gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT') {
+            // Non-ENOENT errors (EISDIR, EPERM, etc.) are unexpected — re-throw
+            throw e;
+        }
+        // No .gitignore yet — will create
+    }
+    if (!gitignoreContent.includes('.worktrees')) {
+        const newline = gitignoreContent.length > 0 && !gitignoreContent.endsWith('\n') ? '\n' : '';
+        try {
+            fs.writeFileSync(gitignorePath, gitignoreContent + newline + '.worktrees/\n', 'utf-8');
+        }
+        catch (e) {
+            process.stderr.write('Warning: could not update .gitignore: ' + e.message + '\n');
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Compute the branch name for a worktree using the config template.
+ */
+function worktreeBranch(cwd, milestone, phase, slug) {
+    const config = loadConfig(cwd);
+    const template = config.phase_branch_template || 'grd/{milestone}/{phase}-{slug}';
+    return template
+        .replace('{milestone}', milestone)
+        .replace('{phase}', phase)
+        .replace('{slug}', slug || phase);
+}
+/**
+ * Compute the milestone branch name using the config template.
+ */
+function milestoneBranch(cwd, milestoneVersion) {
+    const config = loadConfig(cwd);
+    const template = config.milestone_branch_template || 'grd/{milestone}-{slug}';
+    const milestone = getMilestoneInfo(cwd);
+    const version = milestoneVersion || milestone.version;
+    const slug = generateSlugInternal(milestone.name) || 'milestone';
+    return template.replace('{milestone}', version).replace('{slug}', slug);
+}
+/**
+ * Parse git worktree list --porcelain output into structured entries.
+ * Each entry is separated by a blank line and has fields:
+ *   worktree /path/to/worktree
+ *   HEAD abc123
+ *   branch refs/heads/branch-name
+ *   (optional) locked
+ */
+function parsePorcelainWorktrees(porcelainOutput) {
+    if (!porcelainOutput || !porcelainOutput.trim())
+        return [];
+    const blocks = porcelainOutput.trim().split(/\n\n+/);
+    const entries = [];
+    for (const block of blocks) {
+        const lines = block.trim().split('\n');
+        const entry = { path: '', head: '', branch: '', locked: false };
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                entry.path = line.slice('worktree '.length);
+            }
+            else if (line.startsWith('HEAD ')) {
+                entry.head = line.slice('HEAD '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                entry.branch = line.slice('branch '.length).replace('refs/heads/', '');
+            }
+            else if (line === 'locked') {
+                entry.locked = true;
+            }
+        }
+        if (entry.path) {
+            entries.push(entry);
+        }
+    }
+    return entries;
+}
+/**
+ * Extract phase and milestone from a GRD worktree directory name.
+ * Expected format: grd-worktree-{milestone}-{phase}
+ */
+function parseWorktreeName(wtPath) {
+    const dirName = path.basename(wtPath);
+    const match = dirName.match(/^grd-worktree-(.+)-(\d+)$/);
+    if (!match)
+        return null;
+    return { milestone: match[1], phase: match[2] };
+}
+/**
+ * Get all GRD-managed worktrees (filtering out main and non-GRD entries).
+ * Looks for worktrees in the project-local .worktrees/ directory.
+ */
+function getGrdWorktrees(cwd) {
+    const listResult = execGit(cwd, ['worktree', 'list', '--porcelain']);
+    if (listResult.exitCode !== 0)
+        return [];
+    const all = parsePorcelainWorktrees(listResult.stdout);
+    let resolvedCwd;
+    try {
+        resolvedCwd = fs.realpathSync(cwd);
+    }
+    catch {
+        return [];
+    }
+    const worktreesDir = path.join(resolvedCwd, '.worktrees');
+    return all
+        .filter((wt) => wt.path.startsWith(worktreesDir) && path.basename(wt.path).startsWith('grd-worktree-'))
+        .map((wt) => {
+        const meta = parseWorktreeName(wt.path);
+        return {
+            path: wt.path,
+            branch: wt.branch,
+            phase: meta ? meta.phase : '',
+            milestone: meta ? meta.milestone : '',
+            locked: wt.locked,
+        };
+    });
+}
+// ─── CLI Commands ─────────────────────────────────────────────────────────────
+/**
+ * Create a new git worktree for a phase.
+ *
+ * Creates a worktree at {cwd}/.worktrees/grd-worktree-{milestone}-{phase}
+ * with a branch following the configured phase_branch_template pattern.
+ * Ensures .worktrees/ directory exists and is listed in .gitignore.
+ *
+ * @param cwd - Project working directory
+ * @param options - Worktree creation options (phase, milestone, slug, startPoint, force)
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreeCreate(cwd, options, raw) {
+    const { phase, slug, startPoint } = options;
+    if (!phase) {
+        error('phase is required for worktree create');
+        return; // unreachable — error() calls process.exit()
+    }
+    // Resolve milestone from options or ROADMAP.md
+    const milestone = options.milestone || getMilestoneInfo(cwd).version;
+    const branchSlug = slug || phase;
+    // Ensure .worktrees/ directory exists and is in .gitignore
+    ensureWorktreesDir(cwd);
+    const wtPath = worktreePath(cwd, milestone, phase);
+    const branch = worktreeBranch(cwd, milestone, phase, branchSlug);
+    // Check if worktree already exists
+    if (fs.existsSync(wtPath)) {
+        output({ error: 'Worktree already exists', path: wtPath }, raw);
+        return; // unreachable — output() calls process.exit()
+    }
+    // Verify we are in a git repo
+    const revParse = execGit(cwd, ['rev-parse', '--git-dir']);
+    if (revParse.exitCode !== 0) {
+        output({ error: 'Not a git repository', details: revParse.stderr }, raw);
+        return; // unreachable
+    }
+    // Validate start-point exists if provided
+    if (startPoint) {
+        const check = execGit(cwd, ['rev-parse', '--verify', startPoint]);
+        if (check.exitCode !== 0) {
+            output({ error: `Start point '${startPoint}' not found`, details: check.stderr }, raw);
+            return; // unreachable
+        }
+    }
+    // Create the worktree with a new branch, optionally from a start point
+    const gitArgs = ['worktree', 'add', '-b', branch, wtPath];
+    if (startPoint) {
+        gitArgs.push(startPoint);
+    }
+    // Check if branch already exists (before attempting worktree add)
+    if (!options.force) {
+        const branchCheck = execGit(cwd, [
+            'rev-parse',
+            '--verify',
+            'refs/heads/' + branch,
+        ]);
+        if (branchCheck.exitCode === 0) {
+            output({ error: `Branch '${branch}' already exists`, branch }, raw);
+            return; // unreachable
+        }
+    }
+    const result = execGit(cwd, gitArgs);
+    if (result.exitCode !== 0) {
+        output({ error: 'Failed to create worktree', details: result.stderr, branch }, raw);
+        return; // unreachable
+    }
+    const out = {
+        path: wtPath,
+        branch,
+        phase,
+        milestone,
+        created: new Date().toISOString(),
+    };
+    if (startPoint) {
+        out.start_point = startPoint;
+    }
+    output(out, raw, `Worktree created: ${out.path} (branch: ${out.branch})`);
+}
+/**
+ * Remove a git worktree by phase identifier or direct path.
+ *
+ * Gracefully handles non-existent worktrees (returns success with already_gone flag).
+ * Calls git worktree prune after removal to clean git state.
+ *
+ * @param cwd - Project working directory
+ * @param options - Removal options containing phase, milestone, path, or force flag
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreeRemove(cwd, options, raw) {
+    let wtPath;
+    if (options.path) {
+        wtPath = options.path;
+    }
+    else if (options.phase) {
+        const milestone = options.milestone || getMilestoneInfo(cwd).version;
+        wtPath = worktreePath(cwd, milestone, options.phase);
+    }
+    else {
+        error('Either --phase or --path is required for worktree remove. Specify which worktree to remove using --phase <N> or --path <worktree-path>. Example: worktree remove --phase 3. To list active worktrees: grd-tools.js worktree list');
+        return; // unreachable — error() calls process.exit()
+    }
+    // If path does not exist on disk, return graceful response
+    if (!fs.existsSync(wtPath)) {
+        // Also try to prune from git's perspective
+        execGit(cwd, ['worktree', 'prune']);
+        output({ removed: true, path: wtPath, already_gone: true }, raw);
+        return; // unreachable
+    }
+    // Try to remove via git worktree remove (--force for GRD-managed temp worktrees)
+    const removeResult = execGit(cwd, ['worktree', 'remove', wtPath, '--force'], {
+        allowBlocked: true,
+    });
+    if (removeResult.exitCode !== 0) {
+        process.stderr.write('Warning: git worktree remove failed: ' +
+            (removeResult.stderr || 'unknown error').trim() +
+            '\n');
+    }
+    // Prune to clean git state
+    execGit(cwd, ['worktree', 'prune']);
+    // Clean up the temp directory if it still exists
+    if (fs.existsSync(wtPath)) {
+        fs.rmSync(wtPath, { recursive: true, force: true });
+    }
+    output({ removed: true, path: wtPath }, raw);
+}
+/**
+ * List all active GRD-managed worktrees.
+ *
+ * Parses git worktree list --porcelain output and filters to only
+ * GRD-created worktrees (those in .worktrees/ with grd-worktree- prefix).
+ * Returns empty array if no worktrees exist.
+ *
+ * @param cwd - Project working directory
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreeList(cwd, raw) {
+    const worktrees = getGrdWorktrees(cwd);
+    output({ worktrees, count: worktrees.length }, raw);
+}
+/**
+ * Remove stale worktrees whose disk directories no longer exist.
+ *
+ * A worktree is stale if its path does not exist on disk or is empty.
+ * Locked worktrees are never removed regardless of disk state.
+ *
+ * @param cwd - Project working directory
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreeRemoveStale(cwd, raw) {
+    const worktrees = getGrdWorktrees(cwd);
+    const removed = [];
+    for (const wt of worktrees) {
+        // Never remove locked worktrees
+        if (wt.locked)
+            continue;
+        // Check if path exists and is non-empty
+        let isStale = false;
+        try {
+            if (!fs.existsSync(wt.path)) {
+                isStale = true;
+            }
+            else {
+                const entries = fs.readdirSync(wt.path);
+                if (entries.length === 0) {
+                    isStale = true;
+                }
+            }
+        }
+        catch {
+            isStale = true;
+        }
+        if (isStale) {
+            // Remove from git's worktree tracking
+            execGit(cwd, ['worktree', 'remove', wt.path, '--force'], { allowBlocked: true });
+            removed.push(wt.path);
+        }
+    }
+    // Final prune to clean any remaining stale references
+    execGit(cwd, ['worktree', 'prune']);
+    output({ removed, count: removed.length }, raw);
+}
+/**
+ * Push worktree branch to remote and create a PR via gh CLI.
+ *
+ * Both error paths return structured JSON (exit 0) so callers (orchestrators,
+ * MCP) receive parseable output rather than a crash.
+ *
+ * @param cwd - Project working directory
+ * @param options - Options object containing phase, milestone, title, body, and base branch
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreePushAndPR(cwd, options, raw) {
+    const { phase } = options;
+    if (!phase) {
+        output({ error: 'phase is required for worktree push-pr' }, raw);
+        return; // unreachable
+    }
+    // Resolve milestone
+    const milestone = options.milestone || getMilestoneInfo(cwd).version;
+    // Compute worktree path
+    const wtPath = worktreePath(cwd, milestone, phase);
+    // Verify worktree directory exists on disk
+    if (!fs.existsSync(wtPath)) {
+        output({ error: `Worktree not found at ${wtPath}`, phase, milestone }, raw);
+        return; // unreachable
+    }
+    // Read the actual branch name from the worktree HEAD (more robust than recomputing)
+    const headResult = execGit(wtPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const branch = headResult.exitCode === 0 && headResult.stdout
+        ? headResult.stdout.trim()
+        : worktreeBranch(cwd, milestone, phase, phase); // fallback
+    // Derive slug from branch name for title generation
+    const phaseInfo = findPhaseInternal(cwd, phase);
+    const slug = phaseInfo && phaseInfo.phase_slug
+        ? phaseInfo.phase_slug
+        : branch.split('/').pop()?.replace(/^\d+-/, '') || phase;
+    // Push branch to origin from worktree directory
+    const pushResult = execGit(wtPath, ['push', '-u', 'origin', branch], {
+        allowBlocked: true,
+    });
+    if (pushResult.exitCode !== 0) {
+        output({
+            error: 'Failed to push branch',
+            details: pushResult.stderr,
+            phase,
+            milestone,
+            branch,
+        }, raw);
+        return; // unreachable
+    }
+    // Resolve base branch
+    const config = loadConfig(cwd);
+    const baseBranch = options.base || config.base_branch || 'main';
+    // Build PR title
+    const title = options.title || `Phase ${phase}: ${slug} (${milestone})`;
+    // Build PR body
+    const body = options.body || `## Phase ${phase}\n\nMilestone: ${milestone}\nBranch: ${branch}\n`;
+    // Create PR via gh CLI
+    let ghOutput;
+    try {
+        ghOutput = execFileSync('gh', ['pr', 'create', '--title', title, '--body', body, '--base', baseBranch, '--head', branch], { cwd: wtPath, stdio: 'pipe', encoding: 'utf-8' });
+    }
+    catch (ghErr) {
+        // gh failed — return structured error with push_succeeded flag
+        const stderr = ghErr.stderr
+            ? String(ghErr.stderr).trim()
+            : ghErr.message || 'Unknown gh error';
+        output({
+            error: 'Failed to create PR via gh CLI',
+            details: stderr,
+            push_succeeded: true,
+            phase,
+            milestone,
+            branch,
+            base: baseBranch,
+            title,
+            body,
+        }, raw);
+        return; // unreachable
+    }
+    // gh pr create outputs the PR URL on stdout
+    const prUrl = ghOutput.trim();
+    const urlParts = prUrl.split('/');
+    const prNumber = urlParts.length > 0 ? urlParts[urlParts.length - 1] : null;
+    output({
+        pr_url: prUrl,
+        pr_number: prNumber,
+        branch,
+        base: baseBranch,
+        title,
+        body,
+        phase,
+        milestone,
+    }, raw);
+}
+// ─── Programmatic Helpers (evolve, autopilot) ────────────────────────────────
+/**
+ * Create a worktree for the evolve loop.
+ * Returns a result object instead of calling output() — suitable for
+ * programmatic callers that need the path/branch info.
+ *
+ * Worktree directory: {cwd}/.worktrees/grd-evolve-{YYYYMMDD-HHmmss}
+ * Branch name: grd/evolve/{YYYYMMDD-HHmmss}
+ *
+ * @param cwd - Project working directory
+ * @returns EvolveWorktreeResult with path, branch, baseBranch, and created timestamp, or EvolveWorktreeError with error message
+ */
+function createEvolveWorktree(cwd) {
+    // Verify git repo
+    const revParse = execGit(cwd, ['rev-parse', '--git-dir']);
+    if (revParse.exitCode !== 0) {
+        return { error: 'Not a git repository' };
+    }
+    const now = new Date();
+    const stamp = now
+        .toISOString()
+        .replace(/[-:T]/g, '')
+        .replace(/\.\d+Z$/, '')
+        .slice(0, 15);
+    // stamp format: YYYYMMDD + HHmmss (15 chars)
+    const tag = `${stamp.slice(0, 8)}-${stamp.slice(8)}`;
+    const config = loadConfig(cwd);
+    const baseBranch = config.base_branch || 'main';
+    ensureWorktreesDir(cwd);
+    const resolvedCwd = fs.realpathSync(cwd);
+    const wtPath = path.join(resolvedCwd, '.worktrees', `grd-evolve-${tag}`);
+    const branch = `grd/evolve/${tag}`;
+    if (fs.existsSync(wtPath)) {
+        return { error: `Worktree already exists at ${wtPath}` };
+    }
+    const result = execGit(cwd, ['worktree', 'add', '-b', branch, wtPath, baseBranch]);
+    if (result.exitCode !== 0) {
+        return { error: `Failed to create worktree: ${result.stderr}` };
+    }
+    return {
+        path: wtPath,
+        branch,
+        baseBranch,
+        created: now.toISOString(),
+    };
+}
+/**
+ * Remove an evolve worktree and prune git state.
+ * Gracefully handles already-removed worktrees.
+ */
+function removeEvolveWorktree(cwd, wtPath) {
+    if (!fs.existsSync(wtPath)) {
+        execGit(cwd, ['worktree', 'prune']);
+        return { removed: true, already_gone: true };
+    }
+    execGit(cwd, ['worktree', 'remove', wtPath, '--force'], { allowBlocked: true });
+    execGit(cwd, ['worktree', 'prune']);
+    if (fs.existsSync(wtPath)) {
+        fs.rmSync(wtPath, { recursive: true, force: true });
+    }
+    return { removed: true };
+}
+/**
+ * Push a worktree branch to remote and create a PR via gh CLI.
+ * Returns structured result instead of calling output().
+ */
+function pushAndCreatePR(cwd, wtPath, options = {}) {
+    // Read branch from worktree HEAD
+    const headResult = execGit(wtPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    if (headResult.exitCode !== 0) {
+        return { error: 'Failed to determine worktree branch' };
+    }
+    const branch = headResult.stdout.trim();
+    const config = loadConfig(cwd);
+    const baseBranch = options.base || config.base_branch || 'main';
+    // Push branch
+    const pushResult = execGit(wtPath, ['push', '-u', 'origin', branch], {
+        allowBlocked: true,
+    });
+    if (pushResult.exitCode !== 0) {
+        return {
+            error: `Failed to push branch: ${pushResult.stderr}`,
+            push_succeeded: false,
+        };
+    }
+    const title = options.title || `Evolve: improvements on ${branch}`;
+    const body = options.body || `Automated improvements from the evolve loop.\n\nBranch: ${branch}\n`;
+    // Create PR via gh CLI
+    let ghOutput;
+    try {
+        ghOutput = execFileSync('gh', ['pr', 'create', '--title', title, '--body', body, '--base', baseBranch, '--head', branch], { cwd: wtPath, stdio: 'pipe', encoding: 'utf-8' });
+    }
+    catch (ghErr) {
+        const stderr = ghErr.stderr
+            ? String(ghErr.stderr).trim()
+            : ghErr.message || 'Unknown gh error';
+        return { error: `Failed to create PR: ${stderr}`, push_succeeded: true };
+    }
+    return {
+        pr_url: ghOutput.trim(),
+        branch,
+        base: baseBranch,
+    };
+}
+// ─── Milestone Branch Operations ──────────────────────────────────────────────
+/**
+ * Ensure the milestone branch exists, creating it from baseBranch if needed.
+ */
+function cmdWorktreeEnsureMilestoneBranch(cwd, options, raw) {
+    const milestoneVersion = options.milestone || getMilestoneInfo(cwd).version;
+    const config = loadConfig(cwd);
+    const baseBranch = options.baseBranch || config.base_branch || 'main';
+    const branch = milestoneBranch(cwd, milestoneVersion);
+    // Check if branch already exists
+    const check = execGit(cwd, ['rev-parse', '--verify', branch]);
+    if (check.exitCode === 0) {
+        output({ branch, already_existed: true }, raw);
+        return; // unreachable
+    }
+    // Verify base branch exists
+    const baseCheck = execGit(cwd, ['rev-parse', '--verify', baseBranch]);
+    if (baseCheck.exitCode !== 0) {
+        output({ error: `Base branch '${baseBranch}' not found`, details: baseCheck.stderr }, raw);
+        return; // unreachable
+    }
+    // Create branch without checkout
+    const result = execGit(cwd, ['branch', branch, baseBranch]);
+    if (result.exitCode !== 0) {
+        output({ error: 'Failed to create milestone branch', details: result.stderr }, raw);
+        return; // unreachable
+    }
+    output({ branch, already_existed: false, base_branch: baseBranch }, raw);
+}
+/**
+ * Merge a phase branch into the target branch.
+ *
+ * Target branch is determined by: options.base > config.base_branch > milestone branch.
+ * When --base is provided, merges directly into that branch (no milestone branch required).
+ * Otherwise falls back to the milestone branch for backward compatibility.
+ *
+ * Records the current branch, checks out the target branch, merges the
+ * phase branch with --no-ff, and restores the original branch. On conflict,
+ * aborts the merge and restores the original branch.
+ *
+ * @param cwd - Project working directory
+ * @param options - Merge options including phase, milestone, slug, branch, base, deleteBranch, and strategy
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreeMerge(cwd, options, raw) {
+    const { phase, slug, deleteBranch } = options;
+    if (!phase) {
+        error('phase is required for worktree merge. Usage: worktree merge --phase <N>. Add the --phase flag, e.g.: worktree merge --phase 2');
+        return; // unreachable — error() calls process.exit()
+    }
+    const milestoneVersion = options.milestone || getMilestoneInfo(cwd).version;
+    const phaseBranch = options.branch || worktreeBranch(cwd, milestoneVersion, phase, slug || phase);
+    // Determine target branch: explicit --base, or milestone branch (with fallback to config base_branch)
+    let targetBranch;
+    if (options.base) {
+        // Explicit base branch — merge directly into it (no milestone branch needed)
+        targetBranch = options.base;
+    }
+    else {
+        // Try milestone branch first (backward compat); fall back to config.base_branch
+        const msBranch = milestoneBranch(cwd, milestoneVersion);
+        const msCheck = execGit(cwd, ['rev-parse', '--verify', msBranch]);
+        if (msCheck.exitCode === 0) {
+            targetBranch = msBranch;
+        }
+        else {
+            const config = loadConfig(cwd);
+            targetBranch = config.base_branch || 'main';
+        }
+    }
+    // Verify target branch exists
+    const targetCheck = execGit(cwd, ['rev-parse', '--verify', targetBranch]);
+    if (targetCheck.exitCode !== 0) {
+        output({ error: `Target branch '${targetBranch}' not found` }, raw);
+        return; // unreachable
+    }
+    // Verify phase branch exists
+    const phaseCheck = execGit(cwd, ['rev-parse', '--verify', phaseBranch]);
+    if (phaseCheck.exitCode !== 0) {
+        output({ error: `Phase branch '${phaseBranch}' not found` }, raw);
+        return; // unreachable
+    }
+    // Record current branch
+    const headResult = execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const originalBranch = headResult.exitCode === 0 ? headResult.stdout.trim() : 'main';
+    // Checkout target branch
+    const coResult = execGit(cwd, ['checkout', targetBranch]);
+    if (coResult.exitCode !== 0) {
+        output({
+            error: `Failed to checkout target branch '${targetBranch}'`,
+            details: coResult.stderr,
+        }, raw);
+        return; // unreachable
+    }
+    // Get phase info for merge commit message
+    const phaseInfo = findPhaseInternal(cwd, phase);
+    const phaseName = phaseInfo ? phaseInfo.phase_name || slug || phase : slug || phase;
+    // Merge phase branch with --no-ff
+    const mergeResult = execGit(cwd, [
+        'merge',
+        '--no-ff',
+        phaseBranch,
+        '-m',
+        `Merge phase ${phase}: ${phaseName}`,
+    ]);
+    if (mergeResult.exitCode !== 0) {
+        // Merge conflict — abort and restore original branch
+        execGit(cwd, ['merge', '--abort']);
+        const abortRestore = execGit(cwd, ['checkout', originalBranch]);
+        if (abortRestore.exitCode !== 0) {
+            process.stderr.write(`[grd] WARNING: failed to restore branch ${originalBranch} after merge abort\n`);
+        }
+        output({
+            error: 'Merge conflict',
+            details: mergeResult.stderr,
+            target_branch: targetBranch,
+            phase_branch: phaseBranch,
+        }, raw);
+        return; // unreachable
+    }
+    // Optionally delete phase branch
+    if (deleteBranch) {
+        execGit(cwd, ['branch', '-d', phaseBranch]);
+    }
+    // Restore original branch
+    const restoreResult = execGit(cwd, ['checkout', originalBranch]);
+    const restoredBranch = restoreResult.exitCode === 0;
+    if (!restoredBranch) {
+        process.stderr.write(`[grd] WARNING: failed to restore branch ${originalBranch} after merge\n`);
+    }
+    output({
+        merged: true,
+        target_branch: targetBranch,
+        phase_branch: phaseBranch,
+        phase,
+        branch_deleted: !!deleteBranch,
+        original_branch_restored: restoredBranch,
+    }, raw);
+}
+// ─── Hook Handlers ────────────────────────────────────────────────────────────
+/**
+ * Hook handler for WorktreeCreate events from Claude Code.
+ *
+ * When Claude Code creates a worktree natively (via `isolation: worktree`),
+ * this hook fires to optionally rename the branch to GRD's naming convention
+ * and log the lifecycle event. No-op when GRD is inactive or branching disabled.
+ *
+ * @param cwd - Project working directory
+ * @param wtPath - Path to the created worktree ($WORKTREE_PATH)
+ * @param wtBranch - Branch name of the created worktree ($WORKTREE_BRANCH)
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreeHookCreate(cwd, wtPath, wtBranch, raw) {
+    // No-op when GRD is inactive
+    if (!fs.existsSync(path.join(cwd, '.planning'))) {
+        output({ skipped: true, reason: 'no .planning directory' }, raw);
+        return; // unreachable
+    }
+    // No-op when branching is disabled
+    const config = loadConfig(cwd);
+    if (config.branching_strategy === 'none') {
+        output({ skipped: true, reason: 'branching disabled' }, raw);
+        return; // unreachable
+    }
+    // Check if branch already follows GRD convention (starts with 'grd/')
+    if (wtBranch && wtBranch.startsWith('grd/')) {
+        output({
+            hooked: true,
+            worktree_path: wtPath,
+            branch: wtBranch,
+            renamed: false,
+            reason: 'branch already follows GRD convention',
+        }, raw);
+        return; // unreachable
+    }
+    // Try to extract phase info from the worktree path for branch rename
+    const dirName = path.basename(wtPath || '');
+    const phaseMatch = dirName.match(/(\d+)$/);
+    if (phaseMatch) {
+        const phase = phaseMatch[1];
+        try {
+            const milestone = getMilestoneInfo(cwd);
+            const phaseInfo = findPhaseInternal(cwd, phase);
+            const slug = phaseInfo
+                ? generateSlugInternal(phaseInfo.phase_slug || phaseInfo.phase_name || '') || phase
+                : phase;
+            const grdBranch = worktreeBranch(cwd, milestone.version, phase, slug);
+            if (grdBranch !== wtBranch) {
+                const renameResult = execGit(wtPath, ['branch', '-m', wtBranch, grdBranch]);
+                if (renameResult.exitCode === 0) {
+                    output({
+                        hooked: true,
+                        worktree_path: wtPath,
+                        branch: grdBranch,
+                        renamed: true,
+                        original_branch: wtBranch,
+                    }, raw);
+                    return; // unreachable
+                }
+                // Rename failed — log warning to stderr and continue
+                process.stderr.write('Warning: branch rename failed: ' +
+                    (renameResult.stderr || 'git branch rename failed').trim() +
+                    '\n');
+                output({
+                    hooked: true,
+                    worktree_path: wtPath,
+                    branch: wtBranch,
+                    renamed: false,
+                    rename_failed: true,
+                    reason: renameResult.stderr || 'git branch rename failed',
+                }, raw);
+                return; // unreachable
+            }
+        }
+        catch (_e) {
+            // Could not determine milestone/phase info — log creation without rename
+        }
+    }
+    // Default: log creation without rename
+    output({
+        hooked: true,
+        worktree_path: wtPath,
+        branch: wtBranch,
+        renamed: false,
+    }, raw);
+}
+/**
+ * Hook handler for WorktreeRemove events from Claude Code.
+ *
+ * Logs the worktree removal for tracking. Intentionally minimal —
+ * Phase 46 will add state cleanup here if needed.
+ * No-op when GRD is inactive or branching disabled.
+ *
+ * @param cwd - Project working directory
+ * @param wtPath - Path to the removed worktree ($WORKTREE_PATH)
+ * @param wtBranch - Branch name of the removed worktree ($WORKTREE_BRANCH)
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout and exits)
+ */
+function cmdWorktreeHookRemove(cwd, wtPath, wtBranch, raw) {
+    // No-op when GRD is inactive
+    if (!fs.existsSync(path.join(cwd, '.planning'))) {
+        output({ skipped: true, reason: 'no .planning directory' }, raw);
+        return; // unreachable
+    }
+    // No-op when branching is disabled
+    const config = loadConfig(cwd);
+    if (config.branching_strategy === 'none') {
+        output({ skipped: true, reason: 'branching disabled' }, raw);
+        return; // unreachable
+    }
+    const result = {
+        hooked: true,
+        worktree_path: wtPath,
+        branch: wtBranch,
+        action: 'remove_logged',
+    };
+    // Try to extract phase/milestone metadata from the worktree path
+    // Expected GRD format: grd-worktree-{milestone}-{phase}
+    try {
+        const meta = parseWorktreeName(wtPath || '');
+        if (meta) {
+            result.phase_detected = meta.phase;
+            result.milestone_detected = meta.milestone;
+        }
+    }
+    catch (_e) {
+        // Best-effort: metadata extraction failure is not an error
+    }
+    output(result, raw, `Worktree hook: ${result.worktree_path}`);
+}
+// ─── Hook Handlers ────────────────────────────────────────────────────────────
+/**
+ * Hook handler for TeammateIdle events.
+ * Called when a teammate spawned via Agent tool becomes idle.
+ * Supports {continue: false, stopReason: "..."} response to stop the teammate.
+ *
+ * Environment variables from hook payload:
+ * - AGENT_ID: unique identifier of the idle agent
+ * - AGENT_TYPE: type of the agent (e.g., "task", "teammate")
+ */
+function cmdTeammateIdleHook(_cwd, raw) {
+    const agentId = process.env.AGENT_ID || 'unknown';
+    const agentType = process.env.AGENT_TYPE || 'unknown';
+    // For now, allow all teammates to continue.
+    // Future: filter by agent_type to stop non-GRD agents or agents that have completed their work.
+    const result = {
+        ok: true,
+        hook: 'TeammateIdle',
+        agent_id: agentId,
+        agent_type: agentType,
+        action: 'continue',
+    };
+    if (raw) {
+        process.stdout.write(`TeammateIdle: agent=${agentId} type=${agentType} action=continue\n`);
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+}
+/**
+ * Hook handler for TaskCompleted events.
+ * Called when a background task completes.
+ * Supports {continue: false, stopReason: "..."} response to stop the task.
+ *
+ * Environment variables from hook payload:
+ * - AGENT_ID: unique identifier of the completed task agent
+ * - AGENT_TYPE: type of the agent
+ */
+function cmdTaskCompletedHook(_cwd, raw) {
+    const agentId = process.env.AGENT_ID || 'unknown';
+    const agentType = process.env.AGENT_TYPE || 'unknown';
+    const result = {
+        ok: true,
+        hook: 'TaskCompleted',
+        agent_id: agentId,
+        agent_type: agentType,
+        action: 'acknowledged',
+    };
+    if (raw) {
+        process.stdout.write(`TaskCompleted: agent=${agentId} type=${agentType}\n`);
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+}
+/**
+ * Hook handler for InstructionsLoaded events.
+ * Called when CLAUDE.md or rules files are loaded.
+ * Used for plugin setup verification (e.g., confirm .planning/ exists).
+ *
+ * Environment variables from hook payload:
+ * - AGENT_ID: unique identifier of the agent loading instructions
+ * - AGENT_TYPE: type of the agent
+ */
+function cmdInstructionsLoadedHook(cwd, raw) {
+    const agentId = process.env.AGENT_ID || 'unknown';
+    const agentType = process.env.AGENT_TYPE || 'unknown';
+    const planningDir = path.join(cwd, '.planning');
+    const planningExists = fs.existsSync(planningDir);
+    const result = {
+        ok: true,
+        hook: 'InstructionsLoaded',
+        agent_id: agentId,
+        agent_type: agentType,
+        planning_exists: planningExists,
+    };
+    if (raw) {
+        process.stdout.write(`InstructionsLoaded: agent=${agentId} planning=${planningExists}\n`);
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+}
+/**
+ * Hook handler for StopFailure events (Claude Code v2.1.78+).
+ *
+ * Fires when a turn ends due to an API-level failure (rate limit, auth failure,
+ * network error). GRD uses this to log failures to autopilot.log so the
+ * autopilot/evolve retry logic can detect and act on them.
+ *
+ * Environment variables from hook payload:
+ * - STOP_REASON: reason the turn stopped (e.g., "rate_limit", "auth_failure", "api_error")
+ * - ERROR_MESSAGE: error message text (optional)
+ * - AGENT_ID: unique identifier of the affected agent (optional)
+ *
+ * Note: allowRead sandbox setting (v2.1.77) can re-allow read access within
+ * denyRead regions — relevant for plugin data paths that need to check autopilot.log.
+ *
+ * @param cwd - Project working directory
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout)
+ */
+function cmdStopFailureHook(cwd, raw) {
+    const stopReason = process.env.STOP_REASON || 'unknown';
+    const errorMessage = process.env.ERROR_MESSAGE || '';
+    const agentId = process.env.AGENT_ID || 'unknown';
+    // Check if autopilot.log exists — indicates an active autopilot/evolve session
+    const autopilotLogPath = path.join(cwd, '.planning', 'autopilot', 'autopilot.log');
+    const autopilotActive = fs.existsSync(autopilotLogPath);
+    let logged = false;
+    if (autopilotActive) {
+        // Append timestamped failure entry to autopilot.log
+        const timestamp = new Date().toISOString();
+        const logEntry = `[${timestamp}] STOP_FAILURE: reason=${stopReason} error=${errorMessage || '(none)'} agent=${agentId}\n`;
+        try {
+            fs.appendFileSync(autopilotLogPath, logEntry, 'utf-8');
+            logged = true;
+        }
+        catch (writeErr) {
+            process.stderr.write(`[grd] WARNING: failed to write StopFailure to autopilot.log: ${writeErr.message}\n`);
+        }
+    }
+    const result = {
+        ok: true,
+        hook: 'StopFailure',
+        stop_reason: stopReason,
+        error_message: errorMessage,
+        agent_id: agentId,
+        logged,
+    };
+    if (raw) {
+        process.stdout.write(`StopFailure: reason=${stopReason} agent=${agentId} logged=${logged}\n`);
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+}
+/**
+ * Hook handler for PostCompact events (Claude Code v2.1.76+).
+ *
+ * Fires after context compaction completes. GRD acknowledges the event and
+ * continues — this hook is informational only. Future use: could trigger
+ * context reload or state refresh to account for compacted history.
+ *
+ * Environment variables from hook payload:
+ * - AGENT_ID: unique identifier of the agent (optional)
+ * - AGENT_TYPE: type of the agent (optional)
+ *
+ * @param _cwd - Project working directory (unused — compaction is informational)
+ * @param raw - If true, output raw text instead of JSON
+ * @returns void (outputs JSON or raw text to stdout)
+ */
+function cmdPostCompactHook(_cwd, raw) {
+    const agentId = process.env.AGENT_ID || 'unknown';
+    const agentType = process.env.AGENT_TYPE || 'unknown';
+    const result = {
+        ok: true,
+        hook: 'PostCompact',
+        agent_id: agentId,
+        agent_type: agentType,
+        acknowledged: true,
+    };
+    if (raw) {
+        process.stdout.write(`PostCompact: agent=${agentId} type=${agentType} acknowledged=true\n`);
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+}
+// ─── Exports ──────────────────────────────────────────────────────────────────
+module.exports = {
+    worktreePath,
+    worktreeBranch,
+    ensureWorktreesDir,
+    createEvolveWorktree,
+    removeEvolveWorktree,
+    pushAndCreatePR,
+    cmdWorktreeCreate,
+    cmdWorktreeRemove,
+    cmdWorktreeList,
+    cmdWorktreeRemoveStale,
+    cmdWorktreePushAndPR,
+    milestoneBranch,
+    cmdWorktreeEnsureMilestoneBranch,
+    cmdWorktreeMerge,
+    cmdWorktreeHookCreate,
+    cmdWorktreeHookRemove,
+    cmdTeammateIdleHook,
+    cmdTaskCompletedHook,
+    cmdInstructionsLoadedHook,
+    cmdStopFailureHook,
+    cmdPostCompactHook,
+};
+//# sourceMappingURL=worktree.js.map