@iloom/cli 0.9.2 → 0.10.0

package/dist/prompts/swarm-orchestrator-prompt.txt

@@ -0,0 +1,437 @@
+# Swarm Orchestrator
+
+You are the swarm orchestrator for epic #{{EPIC_ISSUE_NUMBER}}. Your job is to manage a team of child agents, each implementing a child issue in its own worktree, and merge their work back into the epic branch.
+
+**Epic Worktree:** `{{EPIC_WORKTREE_PATH}}`
+
+You are running with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. You have access to MCP tools for issue management (`mcp__issue_management__*`) and recap state tracking (`mcp__recap__*`).
+
+**This is a fully autonomous workflow. Do NOT pause for user input, call AskUserQuestion, or wait for human checkpoints at any point.**
+
+---
+
+## Loom Recap
+
+The recap panel is visible to the user in VS Code. Use these Recap MCP tools to capture knowledge:
+
+- `recap.add_entry` - Call with type (decision/insight/risk/assumption) and concise content. **Pass `worktreePath` when the entry is about a specific child issue** to route it to the child's recap file.
+- `recap.get_recap` - Call before adding entries to check what's already captured. **Pass `worktreePath` to read a specific child's recap.**
+- `recap.add_artifact` - After creating/updating comments, issues, or PRs, log them with type, primaryUrl, and description. Duplicates with the same primaryUrl will be replaced. **Pass `worktreePath` when the artifact belongs to a child issue.**
+- `recap.set_loom_state` - Update the loom state (in_progress, done, failed, etc.)
+
+### Recap Routing: Epic vs Child
+
+All recap tools (`add_entry`, `add_artifact`, `set_loom_state`, `get_recap`) accept an optional `worktreePath` parameter. When omitted, entries are written to the epic's recap file. When provided, entries are routed to the specified child's recap file.
+
+**Rule:** Any recap call made about a specific child issue MUST include `worktreePath: "<child-worktree-path>"`. Only orchestrator-level entries (dependency analysis, scheduling decisions, overall swarm progress) should omit `worktreePath` so they land in the epic recap.
+
+**Artifact and entry logging is mandatory.** Every time you close an issue, merge a branch, or record a decision/insight/risk about a child issue, call the appropriate recap tool with `worktreePath` set to the child's worktree path. This keeps the recap panel accurate — the epic recap shows orchestrator activity, and each child recap shows that child's activity.
+
+---
+
+## Available Data
+
+### Reading Child Data from Metadata
+
+Child issue details and dependency relationships are stored in the epic's metadata file. Read the metadata file to get this data:
+
+```bash
+cat {{EPIC_METADATA_PATH}}
+```
+
+The metadata file contains:
+- `childIssues`: JSON array where each entry has `{ number, title, body, url }` — the number is prefixed (`#123` for GitHub, `ENG-123` for Linear)
+- `dependencyMap`: JSON object representing the dependency DAG — keys are issue numbers (as strings), values are arrays of issue numbers that must complete before the key issue can start
+
+### Child Issues (from template)
+
+If child issues are provided directly (e.g., with worktree paths assigned during loom creation), they are available here:
+
+```json
+{{CHILD_ISSUES}}
+```
+
+This is a JSON array where each entry has: `{ number, title, body, worktreePath, branchName }`
+
+### Dependency Map (from template)
+
+If provided directly as a template variable:
+
+```json
+{{DEPENDENCY_MAP}}
+```
+
+This is a JSON object representing the dependency DAG. Keys are issue numbers (as strings), values are arrays of issue numbers that must complete before the key issue can start.
+
+**Priority**: Use the template variables if populated. Otherwise, read from the metadata file.
+
+---
+
+## Todo List
+
+1. Parse child issues and dependency map
+2. Validate dependencies and identify initially unblocked issues
+3. Create the agent team
+4. Spawn agents for all initially unblocked child issues
+5. Monitor agent completions and merge completed work
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+6. Push epic branch to remote after each successful child merge (incremental)
+7. Clean up completed child worktrees (if not --skip-cleanup)
+8. Spawn agents for newly unblocked child issues (repeat as needed)
+9. Handle any failures (mark failed, continue with others)
+10. When all children are done or failed, finalize and clean up
+11. Create final commit with Fixes trailer for epic issue
+12. Push epic branch to remote (final commit)
+13. Print final summary
+{{else}}
+6. Clean up completed child worktrees (if not --skip-cleanup)
+7. Spawn agents for newly unblocked child issues (repeat as needed)
+8. Handle any failures (mark failed, continue with others)
+9. When all children are done or failed, finalize and clean up
+10. Create final commit with Fixes trailer for epic issue
+11. Print final summary
+{{/if}}
+{{else}}
+6. Clean up completed child worktrees (if not --skip-cleanup)
+7. Spawn agents for newly unblocked child issues (repeat as needed)
+8. Handle any failures (mark failed, continue with others)
+9. When all children are done or failed, finalize and clean up
+10. Create final commit with Fixes trailer for epic issue
+11. Print final summary
+{{/if}}
+
+---
+
+## Phase 1: Analyze Dependencies
+
+### Step 1.1: Parse the Provided Data
+
+Parse the `CHILD_ISSUES` JSON array and `DEPENDENCY_MAP` JSON object from the data above.
+
+- `CHILD_ISSUES`: Array of `{ number, title, worktreePath, branchName }`
+- `DEPENDENCY_MAP`: Object where each key is a child issue number (string) and each value is an array of issue numbers (strings) that block it
+
+### Step 1.2: Validate and Build the DAG
+
+1. Verify that all issue numbers referenced in `DEPENDENCY_MAP` values also exist as keys in `CHILD_ISSUES`
+2. Check for cycles in the dependency graph. If a cycle is detected:
+   - Log an error: "Circular dependency detected involving issues: [list]"
+   - Mark all issues involved in the cycle as `failed` with reason: "Part of circular dependency"
+   - Continue with the remaining non-cyclic issues
+   - Report the cycle in the final summary
+3. Build an internal tracking structure:
+   - For each child issue, track: `number`, `title`, `worktreePath`, `branchName`, `status` (pending/in_progress/done/failed), `blockedBy` (list of issue numbers)
+
+### Step 1.3: Identify Initially Unblocked Issues
+
+An issue is "unblocked" if its `blockedBy` list is empty (no dependencies) or all of its dependencies are already `done`.
+
+Log the results:
+```
+Dependency Analysis for Epic #<EPIC_ISSUE_NUMBER>:
+- Total child issues: N
+- Initially unblocked: N (list issue numbers)
+- Blocked: N (list issue numbers with their blockers)
+```
+
+### Edge Case: No Child Issues
+
+If `CHILD_ISSUES` is empty or has no entries:
+1. Log: "No child issues found for epic #<EPIC_ISSUE_NUMBER>. Nothing to orchestrate."
+2. Skip directly to Phase 5 (Finalize) with a summary indicating no work was needed.
+
+Mark todo #1 and #2 as completed.
+
+---
+
+## Phase 2: Create Team and Spawn Agents
+
+### Step 2.1: Create the Team
+
+Use `TeamCreate` to create a team:
+- Team name: `swarm-epic-{{EPIC_ISSUE_NUMBER}}`
+
+### Step 2.2: Spawn Agents for Unblocked Issues
+
+For each unblocked child issue, spawn a teammate using the `Task` tool. **Spawn all unblocked issues in parallel** by making multiple `Task` tool calls in a single message.
+
+For each child issue, use these parameters:
+- `subagent_type`: `"iloom-swarm-worker"`
+- `mode`: `"delegate"`
+- `team_name`: `"swarm-epic-{{EPIC_ISSUE_NUMBER}}"`
+- `name`: `"issue-<child-number>"`
+
+The prompt for each child agent should be:
+
+```
+You are working on issue #<child-number>: "<child-title>"
+
+**Worktree path:** `<child-worktree-path>`
+
+IMPORTANT: You MUST work in this worktree path. cd to it first before doing anything:
+cd <child-worktree-path>
+
+All file reads, writes, searches, and git operations must happen within this directory. Do NOT work in the epic worktree or any other child's worktree.
+
+## Strict Boundaries
+
+- You are ONLY responsible for issue #<child-number>. Do not implement, fix, commit, or merge work for any other issue.
+- NEVER cd into, read from, or modify files in any other worktree path. Your entire scope is `<child-worktree-path>`.
+- Do NOT merge branches, close issues, or perform any orchestration tasks. The orchestrator handles all merging and issue management.
+- Do NOT pick up tasks from the team task list. You have exactly one job.
+
+**Issue body:**
+<child-issue-body>
+
+Implement this issue following your workflow instructions.
+
+## After Completion
+
+When your implementation is done, report back with:
+- Issue number
+- Status (success or failed)
+- Brief summary of what was implemented or what went wrong
+- Number of files changed (if successful)
+
+After sending your report, STOP. Do not look for more work. Do not check on other issues. Do not attempt to help with other worktrees. Wait for a shutdown request and approve it.
+```
+
+Note: The child issue body is available directly in the `CHILD_ISSUES` template data above (each entry has a `body` field). Make sure to include it in the Task prompt for each child.
+
+Update each child's tracking status to `in_progress`.
+
+Mark todo #3 and #4 as completed.
+
+---
+
+## Phase 3: Monitor and Merge
+
+This is the core orchestration loop. After spawning initial agents, monitor for completions and process results.
+
+### When a Child Agent Completes Successfully
+
+When a child agent reports back with status `success` (or goes idle after completing its tasks):
+
+#### Step 3.1: Merge the Child's Branch
+
+Rebase the child branch onto the epic branch from the child's worktree, then fast-forward merge from the epic worktree. You must run the rebase from the child's worktree because that's where the child branch is checked out — git will refuse to rebase a branch that's checked out in another worktree.
+
+```bash
+cd <child-worktree-path>
+git rebase epic/{{EPIC_ISSUE_NUMBER}}
+cd {{EPIC_WORKTREE_PATH}}
+git merge --ff-only <child-branch-name>
+```
+
+Where `<child-worktree-path>` and `<child-branch-name>` are from the child's entry in `CHILD_ISSUES`.
+
+**Important**: Use rebase + fast-forward merge, NOT merge commits. This keeps the epic branch history linear and clean.
+
+#### Step 3.2: Handle Rebase Conflicts
+
+If the rebase has conflicts:
+
+1. **Attempt automatic resolution**: Spawn a subagent to resolve the conflicts:
+   - `subagent_type`: `"general-purpose"`
+   - Prompt: "There are rebase conflicts while rebasing branch `<child-branch-name>` (issue #<child-number>: '<child-title>') onto the epic branch in `{{EPIC_WORKTREE_PATH}}`. Please resolve the conflicts by understanding the intent of both sides, stage the resolved files with `git add`, and run `git rebase --continue`. Ensure the code compiles after resolution."
+2. If the subagent resolves the conflicts: proceed with the fast-forward merge, then Step 3.3
+3. If the subagent fails to resolve:
+   - Abort the rebase: `git rebase --abort`
+   - Mark the child as `failed` with reason: "Rebase conflict could not be resolved"
+   - Skip to Phase 4 failure handling for this child
+
+#### Step 3.3: Ensure Completion Comment Exists
+
+Child agents are expected to post a summary comment on their issue when they finish. However, if a child agent completes without posting a comment, the orchestrator must post one on its behalf.
+
+1. Call `mcp__issue_management__get_comments` with `{ number: "<child-issue-number>", type: "issue" }` to check for existing completion comments
+2. If no completion comment was posted by the child agent, call `mcp__issue_management__create_comment` with:
+   - `number`: `"<child-issue-number>"`
+   - `type`: `"issue"`
+   - `body`: A summary including: what was implemented, the branch name, and that it was merged into the epic branch
+3. Log any new comment as an artifact: Call `mcp__recap__add_artifact` with `{ type: "comment", primaryUrl: "<comment-url>", description: "Completion comment for #<child-number>", worktreePath: "<child-worktree-path>" }`
+
+#### Step 3.4: Update State
+
+1. Update the child's tracking status to `done`
+2. Update the child's loom state: Call `mcp__recap__set_loom_state` with `{ state: "done", worktreePath: "<child-worktree-path>" }`
+3. Close the child issue: Call `mcp__issue_management__close_issue` with `{ number: "<child-issue-number>" }`
+4. Log the artifact: Call `mcp__recap__add_artifact` with `{ type: "issue", primaryUrl: "<child-issue-url>", description: "Issue #<child-number> completed and merged into epic branch", worktreePath: "<child-worktree-path>" }`
+
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+#### Step 3.4.5: Push Epic Branch to Remote (Incremental)
+
+After each successful child merge, push the epic branch to remote so the draft PR reflects incremental progress.
+
+```bash
+cd {{EPIC_WORKTREE_PATH}}
+git push --force-with-lease {{GIT_REMOTE}} HEAD
+```
+
+**NOTE**: `--force-with-lease` is required because the remote branch may still have the placeholder commit (on first push) or because the history was rewritten by a previous force push.
+
+**Error handling**: If the push fails, log the error and continue. Do NOT fail the swarm or skip remaining children. The work is committed locally and will be pushed either by a later successful push or by `il finish`.
+
+{{/if}}
+{{/if}}
+#### Step 3.4.6: Clean Up Child Worktree
+
+{{#unless NO_CLEANUP}}
+After the child's state is updated to `done`, clean up its worktree and archive its metadata by running `il cleanup --archive`. Since the child's work is already rebased and merged into the epic branch, we only need to remove the worktree and branch while preserving metadata.
+
+```bash
+cd {{EPIC_WORKTREE_PATH}}
+il cleanup <child-issue-number> --archive --force --json
+```
+
+This archives the child's metadata to the `finished/` directory (accessible via `il list --finished`) and removes the worktree and branch from disk.
+
+If the `il cleanup` command fails, log the error but continue with the orchestration -- do not let a cleanup failure block other children.
+{{/unless}}
+{{#if NO_CLEANUP}}
+**Note:** Child loom cleanup is disabled (`--skip-cleanup` flag). Child worktrees will be preserved after the swarm completes.
+{{/if}}
+
+#### Step 3.5: Check for Newly Unblocked Issues
+
+After a child completes:
+1. Remove the completed child's issue number from all other children's `blockedBy` lists
+2. Check if any previously blocked children are now unblocked (empty `blockedBy` list)
+3. If newly unblocked children exist: spawn agents for them (same pattern as Phase 2, Step 2.2)
+
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+Mark todo #5, #6, #7, and #8 as completed after each merge-and-spawn cycle.
+{{else}}
+Mark todo #5, #6, and #7 as completed after each merge-and-spawn cycle.
+{{/if}}
+{{else}}
+Mark todo #5, #6, and #7 as completed after each merge-and-spawn cycle.
+{{/if}}
+
+---
+
+## Phase 4: Handle Failures
+
+### When a Child Agent Fails
+
+If a child agent reports back with status `failed`, or encounters an unrecoverable error:
+
+1. **Update tracking**: Mark the child's status as `failed`
+2. **Update loom state**: Call `mcp__recap__set_loom_state` with `{ state: "failed", worktreePath: "<child-worktree-path>" }`
+3. **Ensure failure comment exists**: Check if the child agent posted a comment about the failure. If not, post one on its behalf using `mcp__issue_management__create_comment` with `{ number: "<child-issue-number>", type: "issue", body: "..." }` explaining what failed and why. Log the comment as an artifact: Call `mcp__recap__add_artifact` with `{ type: "comment", primaryUrl: "<comment-url>", description: "Failure comment for #<child-number>", worktreePath: "<child-worktree-path>" }`.
+4. **Log the failure as a recap entry**: Call `mcp__recap__add_entry` with `{ type: "risk", content: "Child #<child-number> failed: <brief reason>", worktreePath: "<child-worktree-path>" }` to record the failure in the child's recap
+5. **Do NOT block other children**: Continue processing remaining children
+6. **Handle downstream dependencies**: For any children that depend on the failed child:
+   - Mark them as `failed` with reason: "Blocked by failed dependency #<failed-child-number>"
+   - Update their loom state: Call `mcp__recap__set_loom_state` with `{ state: "failed", worktreePath: "<downstream-child-worktree-path>" }`
+   - Log a recap entry for each: Call `mcp__recap__add_entry` with `{ type: "risk", content: "Blocked by failed dependency #<failed-child-number>", worktreePath: "<downstream-child-worktree-path>" }`
+   - Do NOT spawn agents for them
+
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+Mark todo #9 as completed.
+{{else}}
+Mark todo #8 as completed.
+{{/if}}
+{{else}}
+Mark todo #8 as completed.
+{{/if}}
+
+---
+
+## Phase 5: Finalize
+
+When all children have reached a terminal state (`done` or `failed`):
+
+### Step 5.1: Shut Down Teammates
+
+Send `shutdown_request` to all teammates that are still active:
+- Use `SendMessage` with `type: "shutdown_request"` for each active teammate
+
+### Step 5.2: Clean Up Team
+
+Use `TeamDelete` to clean up the team `swarm-epic-{{EPIC_ISSUE_NUMBER}}`.
+
+### Step 5.3: Final Commit on Epic Branch
+
+If at least one child succeeded, create a final commit on the epic branch that fixes the epic issue. This ensures the epic issue is automatically closed when the PR is merged.
+
+```bash
+cd {{EPIC_WORKTREE_PATH}}
+git add -A
+git commit --allow-empty -m "Fixes {{ISSUE_PREFIX}}{{EPIC_ISSUE_NUMBER}}"
+```
+
+Note: `--allow-empty` is used because the child branches have already been merged — there may be no additional staged changes, but we still need the commit message trailer to trigger issue closure.
+
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+### Step 5.3.5: Push Epic Branch to Remote (Final Commit)
+
+After the final "Fixes" commit, push the epic branch to remote so the draft PR includes the issue-closing trailer.
+
+**Note**: Incremental pushes in Step 3.4.5 should have already pushed merged child work. This final push adds the "Fixes" commit.
+
+1. **Check if push is needed:**
+   ```bash
+   cd {{EPIC_WORKTREE_PATH}}
+   git log -1 --format=%s
+   ```
+   - If the latest commit message starts with `[iloom-placeholder]` or `[iloom] Temporary`, no children succeeded. Skip the push.
+
+2. **Push to remote:**
+   ```bash
+   cd {{EPIC_WORKTREE_PATH}}
+   git push --force-with-lease {{GIT_REMOTE}} HEAD
+   ```
+   **NOTE**: `--force-with-lease` is required because the branch history includes rebased child commits.
+
+3. **Handle errors gracefully:**
+   - If push fails: Log the error but do NOT fail the swarm. The work is committed locally and `il finish` will handle the push.
+   - Do NOT retry automatically.
+
+4. **Notify completion:**
+   - Log: "Epic branch pushed to remote. Draft PR #{{DRAFT_PR_NUMBER}} updated with final commit."
+
+{{/if}}
+{{/if}}
+### Step 5.4: Print Summary
+
+Print a comprehensive summary:
+
+```
+## Swarm Orchestration Summary for Epic #<EPIC_ISSUE_NUMBER>
+
+### Results
+| Issue | Title | Status | Details |
+|-------|-------|--------|---------|
+| #<number> | <title> | <done/failed> | <brief detail> |
+| ... | ... | ... | ... |
+
+### Statistics
+- Total children: N
+- Succeeded: N
+- Failed: N
+
+### Epic Branch State
+The epic branch at `{{EPIC_WORKTREE_PATH}}` contains merged work from all successful children.
+
+### Failed Children
+<If any failed, list them with reasons>
+
+### Next Steps
+The epic worktree is ready for review at: `{{EPIC_WORKTREE_PATH}}`
+```
+
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+Mark todo #10, #11, #12, and #13 as completed.
+{{else}}
+Mark todo #9, #10, and #11 as completed.
+{{/if}}
+{{else}}
+Mark todo #9, #10, and #11 as completed.
+{{/if}}

package/dist/{rebase-YND35CIE.js → rebase-DWIB77KV.js}

@@ -2,24 +2,24 @@
 import {
   BuildRunner,
   MergeManager
-} from "./chunk-R4YWBGY6.js";
+} from "./chunk-LXLMMXXY.js";
 import {
   installDependencies
-} from "./chunk-4LKGCFGG.js";
+} from "./chunk-WWKOVDWC.js";
 import {
   GitWorktreeManager
-} from "./chunk-TC7APDKU.js";
-import "./chunk-TL72BGP6.js";
-import "./chunk-VOGGLPG5.js";
+} from "./chunk-VGGST52X.js";
+import "./chunk-MORRVYPT.js";
+import "./chunk-YQ57ORTV.js";
+import "./chunk-ONQYPICO.js";
 import {
   getWorktreeRoot,
   isValidGitRepo
-} from "./chunk-AR5QKYNE.js";
+} from "./chunk-MNHZB4Z2.js";
 import {
   SettingsManager
-} from "./chunk-RI2YL6TK.js";
-import "./chunk-KBEIQP4G.js";
-import "./chunk-FO5GGFOV.js";
+} from "./chunk-YYAKPQBT.js";
+import "./chunk-KB64WNBZ.js";
 import "./chunk-6MLEBAYZ.js";
 import {
   logger
@@ -139,4 +139,4 @@ export {
   RebaseCommand,
   WorktreeValidationError
 };
-//# sourceMappingURL=rebase-YND35CIE.js.map
+//# sourceMappingURL=rebase-DWIB77KV.js.map

package/dist/{recap-3W7COH7D.js → recap-MX63HAKV.js}

@@ -2,15 +2,18 @@
 import {
   formatRecapMarkdown
 } from "./chunk-NXMDEL3F.js";
+import {
+  findArchivedRecap
+} from "./chunk-Y4YZTHZE.js";
 import {
   IdentifierParser
-} from "./chunk-YKFCCV6S.js";
+} from "./chunk-WY4QBK43.js";
 import {
   GitWorktreeManager
-} from "./chunk-TC7APDKU.js";
-import "./chunk-AR5QKYNE.js";
-import "./chunk-RI2YL6TK.js";
-import "./chunk-KBEIQP4G.js";
+} from "./chunk-VGGST52X.js";
+import "./chunk-MNHZB4Z2.js";
+import "./chunk-YYAKPQBT.js";
+import "./chunk-KB64WNBZ.js";
 import "./chunk-6MLEBAYZ.js";
 import "./chunk-VT4PDUYT.js";
 
@@ -31,8 +34,7 @@ var RecapCommand = class {
    * Returns RecapOutput in JSON mode, void otherwise
    */
   async execute(input) {
-    const loomPath = await this.resolveLoomPath(input.identifier);
-    const filePath = path.join(RECAPS_DIR, slugifyPath(loomPath));
+    const filePath = await this.resolveRecapFilePath(input.identifier);
     let recap = {};
     try {
       if (await fs.pathExists(filePath)) {
@@ -52,12 +54,14 @@ var RecapCommand = class {
     console.log(formatRecapMarkdown(result));
   }
   /**
-   * Resolve identifier to loom path
-   * Falls back to cwd when no identifier is provided (backward compatible)
+   * Resolve identifier to a full recap file path.
+   * Returns the path to the active recap file, or falls back to an archived
+   * recap when the worktree no longer exists (e.g., after cleanup --archive).
+   * Falls back to cwd when no identifier is provided (backward compatible).
    */
-  async resolveLoomPath(identifier) {
+  async resolveRecapFilePath(identifier) {
     if (!(identifier == null ? void 0 : identifier.trim())) {
-      return process.cwd();
+      return path.join(RECAPS_DIR, slugifyPath(process.cwd()));
     }
     const trimmedId = identifier.trim();
     const gitWorktreeManager = new GitWorktreeManager();
@@ -68,34 +72,58 @@ var RecapCommand = class {
       const prNumber = parseInt(prMatch[1], 10);
       const worktree = await gitWorktreeManager.findWorktreeForPR(prNumber, "");
       if (worktree) {
-        return worktree.path;
+        return path.join(RECAPS_DIR, slugifyPath(worktree.path));
       }
-      throw new Error(`No worktree found for PR #${prNumber}`);
+      const archivedPath = await findArchivedRecap("pr", prNumber);
+      if (archivedPath) return archivedPath;
+      throw new Error(`No worktree or archived recap found for PR #${prNumber}`);
     }
     try {
       const parsed = await identifierParser.parseForPatternDetection(trimmedId);
       if (parsed.type === "pr" && typeof parsed.number === "number") {
         const worktree = await gitWorktreeManager.findWorktreeForPR(parsed.number, "");
         if (worktree) {
-          return worktree.path;
+          return path.join(RECAPS_DIR, slugifyPath(worktree.path));
         }
-        throw new Error(`No worktree found for PR #${parsed.number}`);
+        const archivedPath = await findArchivedRecap("pr", parsed.number);
+        if (archivedPath) return archivedPath;
+        throw new Error(`No worktree or archived recap found for PR #${parsed.number}`);
       }
       if (parsed.type === "issue" && parsed.number !== void 0) {
         const worktree = await gitWorktreeManager.findWorktreeForIssue(parsed.number);
         if (worktree) {
-          return worktree.path;
+          return path.join(RECAPS_DIR, slugifyPath(worktree.path));
+        }
+        const issueNum = typeof parsed.number === "string" ? parseInt(parsed.number, 10) : parsed.number;
+        if (isNaN(issueNum)) {
+          throw new Error(`No worktree found for identifier: ${identifier}`);
         }
-        throw new Error(`No worktree found for issue #${parsed.number}`);
+        const archivedPath = await findArchivedRecap("issue", issueNum);
+        if (archivedPath) return archivedPath;
+        throw new Error(`No worktree or archived recap found for issue #${parsed.number}`);
       }
       if (parsed.type === "branch" && parsed.branchName) {
         const worktree = await gitWorktreeManager.findWorktreeForBranch(parsed.branchName);
         if (worktree) {
-          return worktree.path;
+          return path.join(RECAPS_DIR, slugifyPath(worktree.path));
         }
         throw new Error(`No worktree found for branch: ${parsed.branchName}`);
       }
     } catch (error) {
+      if (error instanceof Error && (error.message.startsWith("No worktree or archived recap found") || error.message.startsWith("No worktree found for branch:"))) {
+        throw error;
+      }
+      if (error instanceof Error && error.message === `No worktree found for identifier: ${trimmedId}`) {
+        const numericMatch = trimmedId.match(/^(\d+)$/);
+        if (numericMatch == null ? void 0 : numericMatch[1]) {
+          const num = parseInt(numericMatch[1], 10);
+          const archivedIssue = await findArchivedRecap("issue", num);
+          if (archivedIssue) return archivedIssue;
+          const archivedPr = await findArchivedRecap("pr", num);
+          if (archivedPr) return archivedPr;
+          throw new Error(`No worktree or archived recap found for #${num}`);
+        }
+      }
       if (error instanceof Error) {
         throw new Error(`Could not resolve identifier '${identifier}': ${error.message}`);
       }
@@ -107,4 +135,4 @@ var RecapCommand = class {
 export {
   RecapCommand
 };
-//# sourceMappingURL=recap-3W7COH7D.js.map
+//# sourceMappingURL=recap-MX63HAKV.js.map

package/dist/recap-MX63HAKV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/recap.ts"],"sourcesContent":["/**\n * RecapCommand - Fast read-only command for VS Code extension\n *\n * Reads ~/.config/iloom-ai/recaps/{current-loom}.json and outputs it.\n * Skips config validation for fast startup.\n * Includes filePath in output so extension can set up file watcher.\n */\nimport path from 'path'\nimport os from 'os'\nimport fs from 'fs-extra'\nimport type { RecapFile, RecapOutput } from '../mcp/recap-types.js'\nimport { GitWorktreeManager } from '../lib/GitWorktreeManager.js'\nimport { IdentifierParser } from '../utils/IdentifierParser.js'\nimport { formatRecapMarkdown } from '../utils/recap-formatter.js'\nimport { findArchivedRecap } from '../utils/recap-archiver.js'\n\nconst RECAPS_DIR = path.join(os.homedir(), '.config', 'iloom-ai', 'recaps')\n\n/**\n * Reuse MetadataManager.slugifyPath() algorithm\n *\n * Algorithm:\n * 1. Trim trailing slashes\n * 2. Replace all path separators (/ or \\) with ___ (triple underscore)\n * 3. Replace any other non-alphanumeric characters (except _ and -) with -\n * 4. Append .json\n */\nfunction slugifyPath(loomPath: string): string {\n\tlet slug = loomPath.replace(/[/\\\\]+$/, '')\n\tslug = slug.replace(/[/\\\\]/g, '___')\n\tslug = slug.replace(/[^a-zA-Z0-9_-]/g, '-')\n\treturn `${slug}.json`\n}\n\nexport interface RecapCommandInput {\n\tidentifier?: string | undefined // Optional identifier (issue number, PR number, branch name)\n\tjson?: boolean | undefined\n}\n\nexport class RecapCommand {\n\t/**\n\t * Execute the recap command\n\t * Returns RecapOutput in JSON mode, void otherwise\n\t */\n\tasync execute(input: RecapCommandInput): Promise<RecapOutput | void> {\n\t\t// Resolve recap file path from identifier or fall back to cwd\n\t\tconst filePath = await this.resolveRecapFilePath(input.identifier)\n\n\t\t// Read recap file (return empty object if not found)\n\t\tlet recap: RecapFile = {}\n\t\ttry {\n\t\t\tif (await fs.pathExists(filePath)) {\n\t\t\t\tconst content = await fs.readFile(filePath, 'utf8')\n\t\t\t\trecap = JSON.parse(content) as RecapFile\n\t\t\t}\n\t\t} catch {\n\t\t\t// Graceful degradation - return empty recap on read error\n\t\t\t// This is intentional for fast startup\n\t\t}\n\n\t\t// Build output with filePath for file watching (provide defaults for optional fields)\n\t\tconst goal = recap.goal ?? null\n\t\tconst complexity = recap.complexity ?? null\n\t\tconst entries = recap.entries ?? []\n\t\tconst artifacts = recap.artifacts ?? []\n\t\tconst result: RecapOutput = { filePath, goal, complexity, entries, artifacts }\n\n\t\tif (input.json) {\n\t\t\treturn result\n\t\t}\n\n\t\t// Non-JSON mode: print markdown format (intentionally using console.log for piping/redirection)\n\t\t// eslint-disable-next-line no-console\n\t\tconsole.log(formatRecapMarkdown(result))\n\t}\n\n\t/**\n\t * Resolve identifier to a full recap file path.\n\t * Returns the path to the active recap file, or falls back to an archived\n\t * recap when the worktree no longer exists (e.g., after cleanup --archive).\n\t * Falls back to cwd when no identifier is provided (backward compatible).\n\t */\n\tprivate async resolveRecapFilePath(identifier: string | undefined): Promise<string> {\n\t\t// Default: use current working directory\n\t\tif (!identifier?.trim()) {\n\t\t\treturn path.join(RECAPS_DIR, slugifyPath(process.cwd()))\n\t\t}\n\n\t\tconst trimmedId = identifier.trim()\n\t\tconst gitWorktreeManager = new GitWorktreeManager()\n\t\tconst identifierParser = new IdentifierParser(gitWorktreeManager)\n\n\t\t// Check for PR-specific formats: pr/123, PR-123, PR/123\n\t\tconst prPattern = /^(?:pr|PR)[/-](\\d+)$/\n\t\tconst prMatch = trimmedId.match(prPattern)\n\t\tif (prMatch?.[1]) {\n\t\t\tconst prNumber = parseInt(prMatch[1], 10)\n\t\t\tconst worktree = await gitWorktreeManager.findWorktreeForPR(prNumber, '')\n\t\t\tif (worktree) {\n\t\t\t\treturn path.join(RECAPS_DIR, slugifyPath(worktree.path))\n\t\t\t}\n\t\t\t// Try archived recap before throwing\n\t\t\tconst archivedPath = await findArchivedRecap('pr', prNumber)\n\t\t\tif (archivedPath) return archivedPath\n\t\t\tthrow new Error(`No worktree or archived recap found for PR #${prNumber}`)\n\t\t}\n\n\t\t// Use IdentifierParser for pattern-based detection\n\t\ttry {\n\t\t\tconst parsed = await identifierParser.parseForPatternDetection(trimmedId)\n\n\t\t\t// Find worktree based on parsed type\n\t\t\tif (parsed.type === 'pr' && typeof parsed.number === 'number') {\n\t\t\t\tconst worktree = await gitWorktreeManager.findWorktreeForPR(parsed.number, '')\n\t\t\t\tif (worktree) {\n\t\t\t\t\treturn path.join(RECAPS_DIR, slugifyPath(worktree.path))\n\t\t\t\t}\n\t\t\t\t// Try archived recap before throwing\n\t\t\t\tconst archivedPath = await findArchivedRecap('pr', parsed.number)\n\t\t\t\tif (archivedPath) return archivedPath\n\t\t\t\tthrow new Error(`No worktree or archived recap found for PR #${parsed.number}`)\n\t\t\t}\n\n\t\t\tif (parsed.type === 'issue' && parsed.number !== undefined) {\n\t\t\t\tconst worktree = await gitWorktreeManager.findWorktreeForIssue(parsed.number)\n\t\t\t\tif (worktree) {\n\t\t\t\t\treturn path.join(RECAPS_DIR, slugifyPath(worktree.path))\n\t\t\t\t}\n\t\t\t\t// Try archived recap before throwing\n\t\t\t\tconst issueNum = typeof parsed.number === 'string' ? parseInt(parsed.number, 10) : parsed.number\n\t\t\t\tif (isNaN(issueNum)) {\n\t\t\t\t\tthrow new Error(`No worktree found for identifier: ${identifier}`)\n\t\t\t\t}\n\t\t\t\tconst archivedPath = await findArchivedRecap('issue', issueNum)\n\t\t\t\tif (archivedPath) return archivedPath\n\t\t\t\tthrow new Error(`No worktree or archived recap found for issue #${parsed.number}`)\n\t\t\t}\n\n\t\t\tif (parsed.type === 'branch' && parsed.branchName) {\n\t\t\t\tconst worktree = await gitWorktreeManager.findWorktreeForBranch(parsed.branchName)\n\t\t\t\tif (worktree) {\n\t\t\t\t\treturn path.join(RECAPS_DIR, slugifyPath(worktree.path))\n\t\t\t\t}\n\t\t\t\t// Branch lookups cannot match archived metadata -- no fallback\n\t\t\t\tthrow new Error(`No worktree found for branch: ${parsed.branchName}`)\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// Let \"not found\" errors from our own lookups pass through without wrapping --\n\t\t\t// these are valid parse results where no worktree/archive was found\n\t\t\tif (error instanceof Error && (\n\t\t\t\terror.message.startsWith('No worktree or archived recap found') ||\n\t\t\t\terror.message.startsWith('No worktree found for branch:')\n\t\t\t)) {\n\t\t\t\tthrow error\n\t\t\t}\n\n\t\t\t// IdentifierParser throws \"No worktree found for identifier: N\" when no active\n\t\t\t// worktree exists for a numeric input. For plain numbers, still try archived recaps\n\t\t\t// before giving up -- this is the primary archived-lookup path.\n\t\t\tif (\n\t\t\t\terror instanceof Error &&\n\t\t\t\terror.message === `No worktree found for identifier: ${trimmedId}`\n\t\t\t) {\n\t\t\t\tconst numericMatch = trimmedId.match(/^(\\d+)$/)\n\t\t\t\tif (numericMatch?.[1]) {\n\t\t\t\t\tconst num = parseInt(numericMatch[1], 10)\n\t\t\t\t\t// Try issue first, then PR\n\t\t\t\t\tconst archivedIssue = await findArchivedRecap('issue', num)\n\t\t\t\t\tif (archivedIssue) return archivedIssue\n\t\t\t\t\tconst archivedPr = await findArchivedRecap('pr', num)\n\t\t\t\t\tif (archivedPr) return archivedPr\n\t\t\t\t\tthrow new Error(`No worktree or archived recap found for #${num}`)\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Re-throw IdentifierParser errors with context\n\t\t\tif (error instanceof Error) {\n\t\t\t\tthrow new Error(`Could not resolve identifier '${identifier}': ${error.message}`)\n\t\t\t}\n\t\t\tthrow error\n\t\t}\n\n\t\t// Should not reach here, but provide a fallback error\n\t\tthrow new Error(`Could not resolve identifier: ${identifier}`)\n\t}\n}\n"],"mappings":"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","names":[]}