fix(item): surface worktree creation failure reason in claim response

[getappz]

Summary

• create_worktree() soft-failed on any git worktree add error and returned None, so item_claim silently omitted worktree_path with no indication why.
• That silence is indistinguishable from a real circular claim/worktree dependency — hit live while working in appz-cli. The most likely actual cause is the known git_binary() PATH-shim self-deny bug class (fix(flare-output): don't fail RealLlm on a benign stdin broken-pipe #234/PR feat(git): worktree orphan audit + fix git_binary shims-dir self-deny #304): a stale daemon resolves git back through its own shim, which unconditionally denies git worktree, and the denial never surfaced past stderr.
• create_worktree now returns Result<PathBuf, String> instead of Option<PathBuf>; item_claim's response gets a worktree_error field when creation fails, instead of silently dropping worktree_path.

Test plan

• cargo build --workspace --all-features
• cargo clippy -p flare-git-core --all-features -- -D warnings
• cargo test -p flare-git-core -p agentflare worktree (27 passed)
• cargo test --bin agentflare item_claim (item_claim_response_includes_worktree_path passed)

Summary by CodeRabbit

• Bug Fixes
  • Worktree creation failures are now reported clearly instead of being silently omitted.
  • Claim acquisition responses now include an actionable error message when setup fails.
  • Successful worktree creation continues to return the expected worktree path.
• Tests
  • Updated worktree-related assertions to match the new success/error handling.
  • Added coverage for PATH filtering across case-insensitive and Windows path formats.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Worktree creation now returns Result<PathBuf, String>, reports creation errors to callers, and exposes those errors in acquired item claim responses. Shim PATH filtering now handles platform-specific case and separator differences with added tests.

Changes

Worktree error propagation

Layer / File(s)	Summary
Result-based worktree creation crates/flare-git-core/src/worktree.rs	create_worktree returns Ok for existing or newly created worktrees and Err with a logged message when creation fails; tests assert both outcomes.
Claim response error propagation src/worktree.rs, src/mcp_server/item.rs	The adapter and item_claim handler propagate the Result and serialize either worktree_path or worktree_error.

Shim PATH matching

Layer / File(s)	Summary
Normalized shim path filtering crates/agentflare-shim/src/lib.rs	PATH filtering compares normalized paths case-insensitively on macOS and Windows, accounts for Windows separators, and tests these platform-specific cases.

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

Sequence Diagram(s)

sequenceDiagram
  participant item_claim
  participant create_worktree
  participant git_worktree
  item_claim->>create_worktree: request worktree creation
  create_worktree->>git_worktree: add worktree
  git_worktree-->>create_worktree: path or creation error
  create_worktree-->>item_claim: worktree_path or worktree_error

Loading

Possibly related PRs

• getappz/agentflare#279: Modified the same worktree creation API and caller flow.
• getappz/agentflare#180: Modified the same worktree APIs and MCP call sites.
• getappz/agentflare#278: Implemented related shim PATH-dispatch and recursion-avoidance behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: exposing worktree creation failures in the claim response.
Description check	✅ Passed	The description includes the required Summary and Test plan sections with concrete details; the Notes for reviewers section is missing but not critical.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/claim-worktree-error-visibility

---

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

[coderabbitai]

🧹 Nitpick comments (1)

crates/flare-git-core/src/worktree.rs (1)

866-866: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the propagated worktree-error contract end to end.

• crates/flare-git-core/src/worktree.rs#L866-L866: assert that the returned error contains the item-specific prefix and non-empty underlying git detail.
• src/mcp_server/item.rs#L410-L417: add an item_claim regression test asserting worktree_error is serialized and worktree_path is omitted on failure.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/flare-git-core/src/worktree.rs` at line 866, The worktree failure
coverage only checks that an error exists. Update the test around the assertion
in the worktree error path to verify the returned error includes the
item-specific prefix and non-empty underlying git details. In
src/mcp_server/item.rs lines 410-417, add an item_claim regression test
confirming worktree_error is serialized on failure and worktree_path is omitted.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@crates/flare-git-core/src/worktree.rs`:
- Line 866: The worktree failure coverage only checks that an error exists.
Update the test around the assertion in the worktree error path to verify the
returned error includes the item-specific prefix and non-empty underlying git
details. In src/mcp_server/item.rs lines 410-417, add an item_claim regression
test confirming worktree_error is serialized on failure and worktree_path is
omitted.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d8c475e6-8070-4f46-b4fd-a22d773a907f

📥 Commits

Reviewing files that changed from the base of the PR and between 2a82d49 and 2e73fe7.

📒 Files selected for processing (3)

• crates/flare-git-core/src/worktree.rs
• src/mcp_server/item.rs
• src/worktree.rs

[getappz]

Followed up on "is this actually circular anywhere else" by auditing every place in the codebase that excludes a shim's own directory from PATH before resolving the real binary (the class of bug PR #304 fixed for git_binary()).

Found one more instance: path_without_shim_dir() in crates/agentflare-shim/src/lib.rs — shared exec plumbing used by both the flare-git-shim and agentflare-shim binaries — filtered shim_dir with a byte-equal PathBuf comparison instead of the case/separator-normalized paths_eq() already proven in git_binary(). On Windows/macOS a case or / vs \ mismatch would leave the shim's own directory in the filtered PATH, letting the shim resolve back to itself. The existing FLARE_GIT_SHIM_DEPTH recursion backstop would have capped the blast radius, but this closes the actual gap.

Grepped for every PATH self-exclusion filter site in the repo — these two (git_binary(), already fixed by #304, and this one) are the only ones. No other instance of the pattern exists.

Verified: cargo test -p agentflare-shim -p flare-git-shim -p flare-git-core -p agentflare (all pass, including the 13 flare-git-shim integration tests) and cargo clippy clean on all four crates.