Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 kind is one kind or a list of one to three. fallback_kinds gives 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.kind records the kind that launched and stage.kind_skipped the 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_MISSION and echoes the stage’s fence. Gateway-made panes carry VULPINE_STAGE_MISSION. herdr’s agent.start takes 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 as agent_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 timeout is read by its pane, and herdr agent rename gives 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: unknown stage whose host lists no agent for it stalls at once (start_unknown).
  • A start herdr answers agent_not_ready is held, not closed, while the agent reads blocked: start unknown, held: {by: "startup_dialog"} and a waiting: ... 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 an advance or run of a running stage with no pane, adopt the herdr agent that carries the stage’s nonce as its vulpine_fence token instead of starting a second one.

Watching and settling

  • The screen watch keys on herdr’s revision mark. 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) and max_report_reminders (0 to 3, default 1). The Stop hook’s block budget follows the record’s report_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_you while open_menu or startup_dialog holds it, else today while 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, so stage.usage (from: report) covers the whole stage. The read is capped at 8 MiB (truncated past 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-hook keeps 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).

Was this page helpful?