[roycepersonalassistant]

What does this PR do?

Fixes Kanban worktree resolution when an explicit repo-root anchor is itself a linked checkout. A linked root on a different branch now materializes <linked-root>/.worktrees/<task-id> on the requested task branch instead of silently reusing the anchor checkout.

The resolver preserves current sibling-isolation behavior by comparing Git common-directory identity: a foreign checkout owned by the surrounding repo still falls back to that repo’s canonical per-task worktree, while a standalone linked checkout is treated as the exact requested anchor. Existing targets are also validated against the requested branch before reuse.

Related Issue

N/A — regression found in a local Kanban worktree workflow.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✅ Tests (adding or improving test coverage)

Changes Made

• Update hermes_cli/kanban_db.py to distinguish standalone linked-root anchors from linked targets owned by a surrounding checkout.
• Reject an already-canonical or pre-existing materialized target whose checked-out branch differs from the requested task branch.
• Extend tests/hermes_cli/test_kanban_worktree_isolation.py with linked-root anchor, stale-target mismatch, same-branch reuse, sibling fallback, and canonical mismatch coverage.

How to Test

1. scripts/run_tests.sh tests/hermes_cli/test_kanban_worktree_isolation.py -q — 7 passed.
2. scripts/run_tests.sh tests/hermes_cli/test_kanban*.py tests/tools/test_kanban_tools.py -q -k "not dashboard_direct_status_change and not connect_falls_back_to_delete_on_locking_protocol and not wal_checkpoint_truncates_wal_file" — 881 passed.
3. .venv/bin/ruff check hermes_cli/kanban_db.py tests/hermes_cli/test_kanban_worktree_isolation.py and git diff --check — clean.

Broader-suite exclusions are environment/baseline-only: two dashboard tests require FastAPI unavailable in this dev venv; the WAL checkpoint test cannot create a WAL because bundled SQLite 3.50.4 is intentionally forced to DELETE journal mode; the clean-main logging-order test fails in the full file on current origin/main but passes in isolation. None touches worktree resolution.

Compatibility / Risk

• Same-branch linked worktree reuse is unchanged.
• Foreign sibling checkout fallback to <repo>/.worktrees/<task-id> is preserved.
• Intentional safety change: an already-canonical target on the wrong branch now raises instead of silently running on that branch.
• No schema, config, dependency, auth, runtime installation, or deployment changes.
• Rollback: revert commit 5006e4545.

Checklist

Code

• My commit messages follow Conventional Commits.
• I searched for existing PRs to make sure this is not a duplicate.
• My PR contains only changes related to this bug fix.
• I added regression tests for the changed behavior.
• I tested on macOS.

Documentation & Housekeeping

• Relevant resolver docstrings are updated.
• Config examples are N/A.
• Architecture/workflow docs are N/A.
• Cross-platform impact considered: logic uses existing Git subprocess/path helpers.
• Tool descriptions/schemas are N/A.

Merge/install intentionally not performed.

[teknium1]

Thanks for the focused worktree-isolation fix. The premise is confirmed on current main: hermes_cli/kanban_db.py:6422-6442 still returns a standalone linked checkout on its existing branch when no surrounding-repository fallback exists, and hermes_cli/kanban_db.py:6341-6348 still reuses an existing same-common-dir target without checking branch_name.

Problems

• website/docs/user-guide/features/kanban.md:68 says worktree:<path> pins the exact target path. This PR intentionally treats a mismatched linked checkout as an anchor and materializes a nested task worktree instead, so the user-facing contract should be clarified.

Suggested changes

• Update the worktree workspace documentation to describe the linked-root-anchor behavior and the resulting <linked-root>/.worktrees/<task-id> location.

Automated hermes-sweeper review.

[roycepersonalassistant]

Superseded by #81821, rebuilt from current upstream main with the requested linked-anchor documentation and passing focused tests.