| name | run-worktree-session |
| description | Run feature and fix implementation in a visible Herdr-managed Pi worktree session, with direct coordinator polling and a focused verify-commit-push-PR loop. Use when Index work moves from root investigation into implementation or returns for review and finish-pr fixes. |
run-worktree-session
The canonical/root Pi coordinates and remains active. The visible Pi in the exact Herdr
worktree workspace owns code mutations. Do not use hidden Agent subagents for
implementation or fix rounds, and do not create a watcher process or watcher pane.
1. Create or reuse the visible session
Follow create-worktree from the canonical root:
- derive the semantic branch, dashed folder, and absolute worktree path;
- create or reuse the exact Git worktree after collision checks;
- run
bun run worktree:setup <folder>;
- open or focus it with Herdr;
- start Pi only if the returned root pane has no existing agent.
The installed CLI contract is:
herdr worktree open --path "$WORKTREE" --label "$FOLDER" --focus --json
herdr agent start "$AGENT_ALIAS" --kind pi --pane "$PANE_ID"
herdr agent start "$AGENT_ALIAS" --kind pi --pane "$PANE_ID" -- --model provider/model:thinking
AGENT_ALIAS defaults to the dashed folder but must fit Herdr's live-name limit
[a-z][a-z0-9_-]{0,31}; shorten it when the folder is longer (the workspace label
stays the full dashed folder).
Capture the returned workspace and pane IDs. Reuse the existing workspace/Pi when
Herdr reports the worktree is already open. Reject a cwd, branch, workspace, pane, or
agent-name collision rather than sending work to the wrong checkout.
2. Deliver one complete handoff
Prepare one prompt file outside the repository containing:
- a stable handoff name, branch, dashed folder, and expected absolute worktree path;
- verified findings and agreed scope;
- key files, constraints, and exclusions;
- targeted verification commands;
- instructions to verify cwd/branch, commit, push, and open/update the PR;
- an instruction not to create another worktree or hidden implementation subagent.
Before delivery, inspect the visible agent and recent pane output:
herdr agent get "$AGENT_NAME"
herdr agent read "$AGENT_NAME" --source recent-unwrapped --lines 200
Send the full handoff as one atomic prompt only when the agent is ready and no
structured question or editor draft is active. --wait submits and waits in one call
for the first settled idle, done, or blocked state:
herdr agent prompt "$AGENT_NAME" "$(< /absolute/path/to/handoff.md)" --wait
Do not commit task-specific handoff files under .pi.
3. Wait event-driven from the coordinator
The coordinator stays active while implementation runs and waits on the same visible
agent. sleep polling is banned — Herdr waits are server-owned and event-driven,
and sleep both wastes wall-clock and hides blocked states. Do not delegate
observation to a background watcher process or watcher pane.
agent prompt --wait usually carries the whole turn. When a follow-up wait is needed
(after a timeout checkpoint or a resolved question), poll directly:
herdr agent get "$AGENT_NAME"
herdr agent read "$AGENT_NAME" --source recent-unwrapped --lines 200
herdr agent wait "$AGENT_NAME" --timeout 30000
A wait timeout is a polling checkpoint, not a failure. Read new output, handle any
question, and wait again until the agent reports completion or a real blocker.
Ground decisions in the visible output rather than assuming that working, idle, or
done alone proves success — idle and done are both settled states, and a settled
state still requires transcript and git/PR/test verification.
For parallel agents, issue multiple herdr agent prompt NAME "..." --wait (or
agent wait) tool calls in one turn so the server-owned waits run concurrently.
4. Answer questions safely
For routine implementation questions, inspect the pane and choose the recommended or
safest project-compliant option automatically. Examples include ordinary file edits,
targeted tests, commits, pushes, and PR creation.
Escalate to the user only for:
- genuine product or architecture ambiguity;
- destructive operations;
- external infrastructure mutation;
- credentials or secrets;
- merge approval.
Never infer merge approval.
agent prompt --wait and agent wait return blocked when Herdr recognizes an
approval or question UI. If a structured question, selector, or editor draft is
active, do not use herdr agent prompt: it can append text to stale input. Read
the pane, then answer the active UI through its pane ID with targeted text/keys:
herdr pane read "$PANE_ID" --source visible --lines 120
herdr pane send-text "$PANE_ID" "<safe answer>"
herdr pane send-keys "$PANE_ID" enter
For a selector, send only the navigation/confirmation keys required by the visible UI.
Re-read the pane afterward to verify that the answer landed in the intended control.
5. Verify session identity and implementation
The visible Pi must run before mutation:
pwd
git branch --show-current
git status --short --branch
The path and branch must match the handoff. Keep changes within scope. Run targeted
tests, lint, typechecks, and manual checks appropriate to the diff. Update required
docs, package versions, and generated artifacts before committing. Report failures
honestly.
After verification succeeds, the visible Pi:
- commits with a conventional commit message;
- pushes the semantic branch;
- opens or updates a PR into
dev with exact verification results and caveats.
Opening a PR is not merge approval. The coordinator's finish-pr workflow owns
readiness, explicit merge confirmation, deployment verification, issue updates, and
cleanup — including closing this Herdr workspace (by verified ID, never the canonical
root) before removing the Git worktree, so no stale sidebar entry survives.
6. Reuse for fix rounds
For review or finish-pr findings, return to the same Herdr workspace, pane, and Pi
agent. Send one consolidated fix prompt, poll directly, answer routine questions, and
wait for the focused checks/commit/push result. Do not create a fresh worktree, agent,
or prompt per comment.
Parallel work uses separate visible Herdr workspaces and separate Git worktrees, with
one writer per worktree. Merge or reconcile those branches deliberately; never let two
agents mutate one checkout.
See also
create-worktree — branch, setup, Herdr-open, and collision contracts.run-agent-orchestration — multi-task waves, role profiles, model routing, and the
full blocked-question escalation ladder across agents.address-code-review — factual thread inspection and visible fix-loop workflow.finish-pr — merge approval and post-merge operations.
