Agent pipelines
The vulpine-tools pipelines rounds, split from its README on 2026-10-15: the ripwire task map, the fallback kinds and report-now grace (round 9), start_unknown, stage usage and run evidence (round 10), the whole-stage usage, the start re-prompt and the herdr agent pack (round 11), and round 12: a command word held in a variable, the exact fleet usage read, the growth-only stall and the held agent_not_ready start.
Living doc, checked against the code 2026-11-14
How pi_herdr_dispatch pipeline starts, watches and settles a stage. The vulpine-tools README keeps the
tools, the tool-call guard and its rule packs.
The task map
When the host has ~/.local/bin/ripwire (or the brew/local path), a pipeline attaches a ripwire task map:
ripwire <worktree> --pack-task="<task>" --legend=compact, written to <workbench-dir>/<name>.context-map.xml beside
the worktree, never inside it. The stage mission’s first Context line points the agent at it.
VULPINE_DISPATCH_RIPWIRE=off disables it. A missing binary or a failed run never blocks a dispatch. verify.py adds
a read-only quality_delta layer from the same binary; it is never part of the verdict.
Agent kinds
- A stage’s
kindis one kind or a list of one to three.fallback_kindsgives each stage an order of kinds (at most three). - A kind the quota check refuses, or whose start or proof names an availability failure, is passed over (never the
last).
stage.kindrecords the kind that launched andstage.kind_skippedthe rest. The quota gate refuses only when every kind of a stage is over.
Starting a stage
- Every carrier reads the mission from
VULPINE_STAGE_MISSIONand echoes the stage’sfence. Gateway-made panes carryVULPINE_STAGE_MISSION. herdr’sagent.starttakes no environment. - The record is written before the agent starts. The fleet start checks the record’s rev before it starts a pane, so a retry never orphans an agent.
- Before anything is staged, a local start asks the login shell
command -v <program>in the worktree. A missing program is refused asagent_cli_missing.VULPINE_HERDR_START_PREFLIGHT(on) switches the check. - herdr’s readiness wait is 8000 ms for a Pi agent, which works its mission at once, and 60000 ms for claude, codex and
opencode.
VULPINE_HERDR_START_SHORT_WAIT(on) switches the short wait. - A start herdr answers
timeoutis read by its pane, andherdr agent renamegives the agent its name back. - A start whose mission never reached the transcript is re-prompted once (judged again after 30 s) before
missing_prompt. - A
start: unknownstage whose host lists no agent for it stalls at once (start_unknown). - A start herdr answers
agent_not_readyis held, not closed, while the agent readsblocked: startunknown,held: {by: "startup_dialog"}and awaiting: ...note, with no re-prompt into a dialog. The result says to fetch the operator and then advance, never retry. The Admin’s Pipelines row shows it as any held stage. retry, and anadvanceorrunof a running stage with no pane, adopt the herdr agent that carries the stage’s nonce as itsvulpine_fencetoken instead of starting a second one.
Watching and settling
- The screen watch keys on herdr’s
revisionmark. A stall at the limit asks the transcript first: a transcript that grew restarts the screen witness (read: "grew"); the same size or an unreadable one lets the stall stand. - Report-now grace: before the stall rule ends a quiet stage whose agent herdr still lists, the dispatch sends ONE
fixed report-now prompt, then waits
report_grace_minutes(0 to 60, default 10, 0 = off). - Dispatch fields:
canceled_grace_minutes(0 to 120, default 10) andmax_report_reminders(0 to 3, default 1). The Stop hook’s block budget follows the record’sreport_reminders(0 to 3). - advance sets a stale-fence report aside (
fence_refused,fence_note). A settle that failed on the network resumes once after 2 minutes. - Each no-report advance writes the stage’s
verdict_shadow({action, why, at}):needs_youwhileopen_menuorstartup_dialogholds it, elsetodaywhile its agent is quiet. It is record-only. - vulpine-glyphctl’s door wait is
dispatch_door_secs: 240 s with no wait, up to 300.
Usage and run evidence
- A proven start records
stage.usage(turns and token counts from the transcript). advance re-reads the transcript when it takes the report, sostage.usage(from: report) covers the whole stage. The read is capped at 8 MiB (truncatedpast it) and is never lower than the start proof’s counts. On a host with jq the read is exact; without jq it is the capped grep read. - The claude carrier’s PostToolUse hooks put
run_evidence(outcome, exit code, counts; never the output) on the mission’s report. Codex stages get a codex PostToolUse group (Bash| apply_patch), and a non-zero exit is a failure.fox9-hookkeeps a long report’s head and tail.
The herdr guard in the panes
The herdr agent pack (agent-packs/herdr.json) refuses agent start, workspace create, pane split, agent prompt,
send-keys, send-text and the closes to a subagent. The guard also reads a command word held in a variable: a variable
set to command -v X, which X, type -P X (with an || echo <path> fallback naming the same basename), a literal,
or one the agent’s environment holds is judged as the command it names. So "$(command -v herdr)" agent start is
refused like herdr agent start. Every pane carrier runs the same guard.
Installs
The carrier, the hook and vulpine-glyphctl’s door wait are operator installs: just herdr::deploy-pane-extensions <host>, just herdr::deploy-codex-guard and just herdr::deploy-report-carrier (codex asks once to trust the group).