NousResearch / NousResearch/hermes-agent

[Feature]: Add safe Kanban workspace rebinding after Project primary changes

Open
#93,046 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/config comp/cron P3 sweeper:risk-compatibility type/feature
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:

  1. A Project was initially created with a wrapper folder as primary; the actual Git repository was one level below it.
    1. Nineteen project-linked implementation cards materialized under <wrapper>/.worktrees/<task-id>.
    1. hermes project set-primary corrected the Project to the actual repository.
    1. Existing cards kept the old paths.
    1. 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.

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> and hermes kanban boards set-default-workdir should 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].
      • 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.
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.
Feature Type

CLI improvement

Scope

None

Contribution
  • I'd like to implement this myself and submit a PR
Debug Report (optional)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.