NousResearch / NousResearch/hermes-agent
[Feature]: Add safe Kanban workspace rebinding after Project primary changes
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 247k
- Forks
- 52k
- PR merge metrics
- PR metrics pending
Description
Problem or Use Case
When a Project primary repository or board default_workdir is corrected after Kanban cards have been created, existing cards retain their materialized workspace_path. The cards continue targeting the old anchor even though hermes project show reports the corrected primary.
Observed on Windows 11 with Hermes v0.20.5:
- A Project was initially created with a wrapper folder as primary; the actual Git repository was one level below it.
-
- Nineteen project-linked implementation cards materialized under
<wrapper>/.worktrees/<task-id>.
- Nineteen project-linked implementation cards materialized under
-
hermes project set-primarycorrected the Project to the actual repository.
-
- Existing cards kept the old paths.
-
- Dispatch rejected them as outside a Git repository and consumed retries until the circuit breaker blocked the cards.
Recovery required recreating every affected card, rewiring dependencies, commenting and archiving the originals, and separately preserving partial worker output. This is error-prone and gives up stable task IDs.
- Dispatch rejected them as outside a Git repository and consumed retries until the circuit breaker blocked the cards.
Related work #92645, #92519, and #70865 guards new unanchored or unresolvable cards, but does not repair existing materialized cards after an intentional Project or board-anchor correction. #81336 handles missing worktrees; #91169/#91191 handles reciprocal Project-board binding. Those are adjacent but distinct.
Proposed Solution
Add a first-class, fail-closed rebind workflow for Project-derived Kanban workspaces.
Suggested shape:
hermes project set-primary <project> <path>andhermes kanban boards set-default-workdirshould detect active cards whose stored workspace_path was derived from the previous anchor and print an explicit affected-card count.-
- Provide a dry-run/apply repair command, for example
hermes kanban rebind-workspaces --project <project> --from <old-root> --to <new-root> [--apply].
- Provide a dry-run/apply repair command, for example
-
-
- Preserve task IDs, bodies, comments, runs, dependency edges, branches, retries, and review state; update only the workspace routing fields and append an auditable event.
-
-
-
-
- Refuse running/claimed tasks, ambiguous paths, explicit user overrides, branch collisions, and destinations that are not verified Git roots/worktree targets.
-
-
-
-
-
-
- Distinguish Project-derived paths from explicit workspace overrides, ideally with persisted provenance for newly created tasks.
-
-
-
-
-
-
-
-
- Verify every rewritten destination before committing the transaction and report exact changed/skipped/refused counts.
-
-
-
-
-
-
-
-
-
-
- Document that card workspace paths are snapshots at creation time and that changing a Project or board anchor does not silently mutate existing cards.
This should complement, not duplicate, the creation-time validation in the related PRs.
- Document that card workspace paths are snapshots at creation time and that changing a Project or board anchor does not silently mutate existing cards.
-
-
-
-
-
Alternatives Considered
- Manual recreate/link/unlink/archive preserves audit history but is too complex for bulk recovery and changes task IDs.
-
- Re-deriving every workspace dynamically at dispatch would make Project changes unexpectedly mutate active tasks and could redirect explicit overrides.
-
-
- Creation-time validation alone prevents some future incidents but cannot recover legacy or already-materialized rows.
A scoped, provenance-aware, dry-run-first rebind command is safer and more predictable.
- Creation-time validation alone prevents some future incidents but cannot recover legacy or already-materialized rows.
-
Feature Type
CLI improvement
Scope
None
Contribution
- I'd like to implement this myself and submit a PR
Debug Report (optional)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the hermes project set-primary and hermes kanban boards set-default-workdir entry points, then trace how active cards store and derive workspace_path. Review related issues #92645, #92519, #70865, #81336, #91169, and #91191 before choosing the rebind design. Done means a dry-run-first, fail-closed workflow preserves card state, distinguishes overrides, verifies destinations, and reports changed, skipped, and refused cards.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100