feat: support recursive worktree list and status

[patrickleet]

Change

Wire the host's existing recursive protocol option into worktree list/status, add -r/--recursive help and parsing, use the new discovery API, propagate recursive observation failures, and add usage documentation and public plugin regression coverage.

Merge order

Depends on the meta_cli API PR #33. Merge that first. This branch uses the new sibling path-dependency API and cannot build against the old meta_cli checkout. Release/build both updated repos together.

Why merge

Meta creates nested worktree members (for example root → open-source → atc), but legacy inventory stops at the parent worktree. This makes a successfully created child invisible to inventory consumers, including the planned ATC badge. Explicit recursive discovery supplies actual realized members without treating the configured project graph as realized checkouts.

Before / after

For a fixture with root, open-source, open-source/atc, and other/atc:

Invocation	Before	After
list/status without recursive	., open-source, other/atc	unchanged
list/status with recursive	., open-source, other/atc (flag ignored)	., open-source, open-source/atc, other/atc

Example usage (with both PRs)

meta git worktree list --recursive --json
meta git worktree status my-feature --recursive --json
meta git worktree status my-feature -r

Compatibility and safety

• Existing discovery API and default repository boundaries remain unchanged.
• No JSON field names/types change. The explicit recursive option adds member rows.
• Create/add/remove/prune/exec/diff and automatic context detection retain their existing discovery behavior.
• Read-only filesystem/Git observations; no migrations or Git mutations.
• Recursive scans skip hidden directories and do not follow directory symlinks. A 2,000,000-entry budget per set bounds traversal volume.
• Recursive traversal, malformed Git-file, or Git-status errors fail instead of emitting partial successful inventory. Default error behavior remains unchanged.
• Build directories add scan latency. list fails when any set is broken; status NAME isolates the selected set. Callers should impose a subprocess timeout and represent failures as unknown.

Testing

Executed on macOS against both PR branches in the same Meta workspace:

• cargo test --workspace: 581 passed, 0 failed, 0 ignored.
• cargo clippy --workspace --all-targets -- -D warnings: passed.
• cargo fmt --all -- --check: passed.
• New discovery tests cover nested members, default boundaries, repeated leaf names, absent members, deterministic aliases, malformed Git files, missing roots, hidden directories, and symlink cycles.
• New public plugin integration test uses real Git worktrees, exercises list/status with protocol and explicit flags (including both together), checks branch/untracked dirty state, and checks failure without partial JSON.
• Actual newly built host/plugin smoke: default list/status return root + open-source; recursive status returns all 14 realized members, including open-source/atc (about 1.3 seconds). Recursive list detects a broken Git pointer in an unrelated existing worktree and exits nonzero as intended.
• Linux/Windows execution and the separate Bats suite were not run locally; this is local evidence, not a claim of cross-platform CI success.

Tracks [[tasks/harmony-1932]], prerequisite for [[tasks/harmony-1918]].

Summary by CodeRabbit

• New Features
  • Added a --recursive (-r) option for listing worktrees and checking their status, including repositories nested beneath other repositories.
  • Recursive results include qualified worktree names in a consistent order. Recursive scans skip hidden directories and directory symlinks.
• Bug Fixes
  • Recursive requests now report scan and status errors instead of returning incomplete results. Failed scans do not produce partial JSON output.

Review follow-up verification

CodeRabbit findings addressed: relative Git links resolve at the checkout; recursive discovery validates admin metadata and backlinks; fixtures use real worktrees. Added missing-root public protocol coverage and function documentation. Latest combined workspace run: 581 passed, zero failed; Clippy and formatting pass.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e2e03510-654d-4c30-afa2-40c406cad664

📥 Commits

Reviewing files that changed from the base of the PR and between ac7ab64 and 1eb3355.

📒 Files selected for processing (6)

• RECURSIVE_WORKTREES.md
• src/commands/worktree/cli_types.rs
• src/commands/worktree/list.rs
• src/commands/worktree/mod.rs
• src/commands/worktree/status.rs
• tests/recursive_inventory.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

List and status now accept recursive options. Recursive mode discovers nested repositories and propagates discovery and status errors. Integration tests cover recursive and non-recursive results, including malformed nested Git files.

Changes

Recursive worktree commands

Layer / File(s)	Summary
Recursive CLI options and dispatch src/commands/worktree/cli_types.rs, src/commands/worktree/mod.rs	List and status accept --recursive and -r. The dispatcher injects the option for list and status when requested through the protocol and no equivalent flag is present. Help text documents the option.
Recursive list and status behavior src/commands/worktree/list.rs, src/commands/worktree/status.rs, tests/recursive_inventory.rs, RECURSIVE_WORKTREES.md	Recursive list and status discover nested repositories and propagate the described discovery and status errors. Tests check recursive and non-recursive JSON results and failures for a malformed nested .git file. Documentation describes discovery rules, scan limits, and failure behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Protocol
  participant WorktreeDispatcher
  participant handle_list
  participant handle_status
  participant RecursiveRepositoryDiscovery
  participant git_status_summary
  participant JSONResponse
  Protocol->>WorktreeDispatcher: Request recursive list or status
  alt List request
    WorktreeDispatcher->>handle_list: Pass list arguments with recursive option
    handle_list->>RecursiveRepositoryDiscovery: Discover repositories recursively
    RecursiveRepositoryDiscovery-->>handle_list: Return discovered repositories
    handle_list->>git_status_summary: Read repository status
    git_status_summary-->>handle_list: Return status or error
    handle_list->>JSONResponse: Return list result or error
  else Status request
    WorktreeDispatcher->>handle_status: Pass status arguments with recursive option
    handle_status->>RecursiveRepositoryDiscovery: Discover repositories recursively
    RecursiveRepositoryDiscovery-->>handle_status: Return discovered repositories
    handle_status->>git_status_summary: Read repository status
    git_status_summary-->>handle_status: Return status or error
    handle_status->>JSONResponse: Return status result or error
  end

Loading

Merge Risk: ⚪ Minimal · up to 1eb33

No confirmed issue blocks merging. The behavior when the configured worktree root is missing remains unverified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 1eb33

Recursive inventory is opt-in and reports failures rather than presenting incomplete results as clean. A malformed nested checkout can nevertheless prevent a full list from being returned. The new discovery implementation was not available for verification.

Retained concerns

• Low · reliability · inferred: One malformed nested checkout can make recursive list fail for every worktree set, withholding otherwise available inventory. This preserves fail-closed output integrity but reduces failure containment for consumers of the aggregate list.

Security review details

Security Blast Radius

• observed — With recursion enabled, list observes repositories across worktree sets, while status scans one resolved set and includes discovered repository paths and status details in JSON.

Security Findings and Attack Paths

• inferred — A malformed nested .git file can deny a recursive aggregate inventory without yielding a falsely successful partial result; the test demonstrates request failure, not a privilege-boundary bypass.

Trust Boundaries and Controls

• observed — Recursive status validates the requested name and resolves its worktree directory before calling discovery; the command does not take a separate nested-repository path argument.

Resilience and Maintainability Implications

• observed — The usage documentation advises consumers to bound subprocess runtime and treat recursive scan failure as unknown rather than empty or clean inventory.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 5 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: recursive support for worktree list and status commands.

Full details: Docstring Coverage

Explanation

Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 5 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{A rabbit hops where worktrees nest
Past leafy paths on a recursive quest
List the branches, check status too
Errors come through when scans find clues
JSON carries each result in view
Then home I bound beneath the moon <|fim_suffix|>}

_{Comment @coderabbitai help to get the list of available commands.}

[patrickleet]

Addressed the docstring coverage warning in b5a0dd1 and added a public protocol regression for the previously unverified missing-root behavior: list returns an empty inventory; named status fails, in both default and recursive modes. No actionable inline comments were present. Combined with the companion API fixes in meta_cli c8c87ab: 581 workspace tests passed, Clippy with -D warnings and formatting passed. Aggregate-list failure containment remains the explicitly documented contract; named status isolates a single set.