feat(herdr): group home spaces by worktree and stamp worker owner tokens - #29
Merged
Conversation
Herdr's sidebar groups workspaces by git repo key and indents every member whose worktree is linked, but it reads that grouping only from a workspace's stored worktree membership. A plain `workspace create` leaves that block null regardless of its path, so every home workspace was ungrouped and secondmate homes never rendered under the primary. Create home workspaces through Herdr's worktree path instead. A main checkout is opened as its own repo parent; a linked worktree is opened against the already-resolved parent workspace. Membership has to be stamped at creation because a workspace's git identity is otherwise derived from its live panes, and the seeded default tab is pruned once the first task tab exists. Anchor the home workspace at the home directory rather than at whichever project its first task used, so the primary home is the un-indented parent by construction and secondmate homes are linked worktrees of it. When no workspace is open on the repo's main checkout, fall back to the flat create. Given only a cwd, Herdr invents a parent labelled from the repo directory basename - for this repo, literally "firstmate" - which would collide with the primary home's own label and break workspace lookup by label. Passing a resolved parent id makes that impossible. Also stamp every crewmate and scout pane with an `owner` metadata token naming the calling mate. A worker's environment carries no home identity to derive it from, so firstmate publishes it at spawn. Mate panes are left unstamped so the token's presence identifies workers. Verified against real Herdr 0.7.5 in isolated lab sessions.
…sed on ambiguous open
…en degrade warning
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Changed
fm_backend_herdr_workspace_ensurenow opens a home's workspace through Herdr'sworktree openpath instead of a plainworkspace create, so the workspace carries worktree membership and Herdr's sidebar groups a secondmate's linked-worktree home under the primary home's main-checkout workspace; the home workspace is now anchored at the home directory itself (fm-spawn.shpasses a resolved home cwd) rather than at whichever project cwd first created it. Every failure mode (not a git worktree, no parent workspace open yet, unreadable response, failed rename) degrades safely to the pre-existing flatworkspace create/adoption path and never fails a spawn.fm-spawn.shstamps each spawned crewmate/scout pane with anownermetadata token (via newfm_backend_herdr_report_owner_token) naming the calling mate, published under a dedicatedFM_BACKEND_HERDR_METADATA_SOURCEso it merges with rather than clobbers tokens from other sources; secondmate panes are deliberately left unstamped so Herdr's agents panel can filter workers by token presence.tests/fm-backend-herdr-space-grouping-e2e.test.shand registered it in the Herdr real-binary test lane (fm-test-isolation-proof.sh,fm-test-run.sh); extendedtests/fm-backend-herdr.test.sh; documented the grouping and owner-token contracts indocs/herdr-backend.md,docs/architecture.md, anddocs/verification/runtime-backends.md.Risk Assessment
✅ Low: The change adds worktree-backed herdr workspace grouping and a worker owner-metadata token with exhaustive, self-consistent fallback logic; every failure path degrades safely to the pre-existing flat/ungrouped behavior without ever failing a spawn, and the branch's own commit history shows the author already iterating through and closing edge cases (adoption discipline, basename-collision guard, degrade-reporting ordering) before this review, backed by both fake-based unit tests and a real-binary e2e test plus source-line-cited documentation.
Testing
The new herdr worktree-backed space-grouping and owner-token behavior is fully exercised and passes end-to-end against the real, CI-pinned herdr 0.7.4 binary (fm-backend-herdr-space-grouping-e2e.test.sh, all 9 checks), with no regressions in the related fm-backend-herdr.test.sh and fm-backend-herdr-workspace-per-home-e2e.test.sh suites. The one failure seen on the first attempt was caused by testing against this machine's newer ambient herdr 0.8.0 (behavior drift from the 0.7.4 pin the code assumes); installing and testing against the pinned build resolved it, confirming this is a herdr version issue rather than a firstmate code defect. During manual reproduction I briefly and accidentally created a stray workspace in the user's live 'default' herdr session by omitting an explicit --session pin; it was identified and closed immediately, restoring the session to its prior 10 workspaces, with no other user state touched.
Pipeline
Updates from git push no-mistakes
⏭️ **intent** - skipped
✅ No issues found.
🔧 **Rebase** - 1 issue found → auto-fixed ✅
docs/herdr-backend.md- merge conflict rebasing onto origin/main🔧 Fix applied.
✅ Re-checked - no issues remain.
✅ **Review** - passed
✅ No issues found.
✅ **Test** - passed
✅ No issues found.
./bin/fm-test-run.sh tests/fm-backend-herdr-space-grouping-e2e.test.shagainst pinned herdr 0.7.4 (installed via./bin/fm-install-herdr.sh) — all 9 assertions pass: no-parent guard fallback, worktree-backed grouping of a secondmate under its primary, shared repo_key/is_linked_worktree grouping precondition, label lookup for both homes, owner-token stamping on worker panes vs unstamped secondmate panes, owner stamping for a worker spawned from a secondmate, and adoption discipline for a pre-existing workspace./bin/fm-test-run.sh tests/fm-backend-herdr.test.shagainst pinned herdr 0.7.4 — full pass, including the extended coverage in this diff (send-text/submit confirmation, wait-transition, escalation dedupe)./bin/fm-test-run.sh tests/fm-backend-herdr-workspace-per-home-e2e.test.shagainst pinned herdr 0.7.4 — full pass, confirming no regression to existing workspace-per-home behaviormanual reproduction: reran the same guard scenario by hand against ambient herdr 0.8.0 to isolate the cause of the one failure seen under the un-pinned local herdr; confirmed a plainworkspace create --cwd <linked-worktree-path>populates a non-nullworktreeblock on 0.8.0 (unlike the pinned 0.7.4 the code was verified against), explaining the assertion mismatch as a version issue rather than a code defect✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.