---
title: "Agent pipelines"
description: "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."
type: "living"
source: "catalog/pi/extensions/vulpine-tools/pipelines-rounds.md"
verified: "2026-11-14"
group: "The brain"
---

> **Living doc**, checked against the code 2026-11-14

How `pi_herdr_dispatch pipeline` starts, watches and settles a stage. The [vulpine-tools README](/docs/the-brain/tool-policy) 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).

