ace-herdr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11805892b3ae5bdf74d4bdd555f8e508e7fe3693476d07fa537a41b9f891857e
+  data.tar.gz: 2aa907e23b109838153215ac004f344045220d2c77cf0f295a99c6ff55a75cb2
+SHA512:
+  metadata.gz: 53e2cbd3f3c97db17b5e14609e54deb210e0d7474886dc4f6fe7d78a33154df1cb7fe680a565aa500d534c0ce06235dd20445f9ae6bb867d5b989732c5a5fa70
+  data.tar.gz: 9397dfe3b7fb8ac0d9b42f2a43ad7ac56204c7b70197e5f1a6095a00f62f38ecb8d7a0967ca0ab5d68c91864656c86db25a9cc9bc0274fa65c63d74216771e09

data/.ace-defaults/herdr/config.yml

@@ -0,0 +1,26 @@
+# ace-herdr default configuration
+# Override in ~/.ace/herdr/config.yml or .ace/herdr/config.yml
+
+# Agent kind used when bootstrapping a pane without an agent
+# (herdr agent start --kind)
+default_agent_kind: pi
+
+# Push delivery retries; deterministic fixed backoff, no jitter
+delivery:
+  max_attempts: 3
+  backoff_seconds: [1, 2, 4]
+
+# Timeouts in seconds
+timeouts:
+  agent_start: 60
+  prompt: 30
+  wait: 30
+
+# Delivery record root (ADR-029 short-name layout), relative to project root
+deliveries_dir: .ace-local/herdr/deliveries
+
+# Tidy (spec 8wq.t.1w0): archive delivered records strictly older than this
+# many days (age = record updated_at); failed/retryable/pending are never
+# touched
+tidy:
+  delivered_retention_days: 7

data/.ace-defaults/herdr/tabs/agent.yml

@@ -0,0 +1,11 @@
+# Default tab preset: one pane hosting a pi agent (no initial prompt;
+# add `prompt:` under agent to submit one at creation).
+#
+# Override in ~/.ace/herdr/tabs/ or .ace/herdr/tabs/
+# (project wins; see ace-herdr docs/usage.md for the full schema).
+label: agent
+panes:
+  - label: agent
+    agent:
+      kind: pi
+      name: task-agent

data/.ace-defaults/herdr/workspaces/development.yml

@@ -0,0 +1,23 @@
+# Default workspace preset: a work tab with a shell and a pi agent side by
+# side, plus a scratch shell tab.
+#
+# Override in ~/.ace/herdr/workspaces/ or .ace/herdr/workspaces/
+# (project wins; see ace-herdr docs/usage.md for the full schema).
+label: development
+focus: true
+tabs:
+  - label: work
+    panes:
+      - label: shell
+      - label: agent
+        agent:
+          kind: pi
+          name: development-agent
+          prompt: Ready to work on the current task.
+    splits:
+      - direction: right
+        target: shell
+        pane: agent
+  - label: scratch
+    panes:
+      - label: shell

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `ace-herdr` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-27
+
+### Added
+- `ace-herdr tidy` (spec 8wq.t.1w0): dry-run-by-default cleanup of finished agent panes and delivery records. Pane closure requires positive completion evidence only (observed `done` agent state, or a pane whose native `pane process-info` shows no live foreground process — herdr omits `foreground_processes` when empty) re-confirmed by a fresh probe immediately before the rename-to-`done`-then-close mutation; revived or uncertain candidates are excluded and never mutated. Delivered records strictly older than the new `tidy.delivered_retention_days` config key (default 7) are atomically archived to `deliveries_dir/archive/` after a lock-guarded reload re-proves eligibility; `pending`/`retryable`/`failed` and unreadable records are never touched, an unreadable record encountered during apply is preserved and reported instead of aborting. Archival never breaks delivery idempotency (`deliver`/`--resume` consult the archive copy, so identical re-delivery still short-circuits and conflicts still fail closed). Deterministic one-line JSON report with explicit empty states; an unreachable herdr runtime fails with an explicit error and no partial report.
+- Terminal-control surface matching the ace-tmux intent vocabulary (spec 8wq.t.k84), keeping one-line JSON output: `ace-herdr list` (panes/tabs/workspaces, `--workspace` scoping, explicit empty arrays), `ace-herdr send` (declaration-ordered `--cmd`/`--msg`/`--key`; agent-aware routing sends one self-submitting `agent prompt` on agent panes with `agent_blocked`/`agent_prompt_stalled` gating and drop-and-report of a single trailing `--key Enter`; invalid shapes fail closed before any transport call), `ace-herdr capture` (raw `pane read` text, `--source visible|recent`), `ace-herdr wait --for output --pattern` (literal match, immediate check then poll, seconds→ms conversion, timeout CLI error) alongside the unchanged agent wait, and `--list-presets`.
+- Preset-driven creation: `ace-herdr workspace <preset>` / `ace-herdr tab <preset>` compose YAML layouts through the ADR-022 cascade (`.ace/herdr/` > `~/.ace/herdr/` > gem `.ace-defaults/herdr/`, ships `workspaces/development.yml` + `tabs/agent.yml`), with recursive `preset:` inheritance (deep merge, array concat, cycle detection, fail-closed missing references), deterministic creation order (workspace → tabs → root pane + splits → renames → pane commands → readiness-gated agent starts; herdr's seeded initial tab is closed once the declared tabs exist), CLI `--cwd` overrides (CLI > tab > root > pane), and pre-creation layout validation (unplaced panes, duplicate placements, unknown split targets/directions fail closed and create nothing). Includes a tmux-intent ↔ herdr-command parity table in `docs/usage.md`.
+- `Ace::Herdr::Organisms::ControlSurface`: owner of the terminal-control behavior — native JSON normalization into public payloads, send validation/routing, and preset instantiation.
+- `Ace::Herdr::Molecules::PresetLoader` (ADR-022 cascade discovery) and `Ace::Herdr::Molecules::PresetResolver` (`preset:` reference resolution).
+- `Ace::Herdr::Molecules::HerdrExecutor`: native operations for workspace/tab/pane listing, pane read/send-text/send-keys, pane wait-output, pane split, workspace create, agent send-keys, and focus flags on tab/workspace creation; typed `TabNotFoundError`/`WorkspaceNotFoundError` classification; herdr machine codes are now carried in executor error messages (for example `pane_not_found: ...`); output-wait timeouts raise `WaitTimeoutError`.
+- Gem bootstrap (spec 8wm.t.vs0): push delivery + agent bootstrap for the Herdr runtime, implementing the ace-hitl provider delivery contract (`deliver(ref, answer)` -> `DeliverResult` with `:delivered`/`:retryable`/`:failed`).
+- `Ace::Herdr::Organisms::Deliverer`: idempotent per event id with write-ahead delivery records under `.ace-local/herdr/deliveries/` (0600, atomic writes; the full answer is persisted so a crash never loses it, recoverable via `ace-herdr deliver --resume`), per-event lock serializing concurrent deliveries, duplicate-identical short-circuit, fail-closed content/destination conflicts, bootstrap of missing agents (`herdr agent start` with shell-escaped `HERDR_SESSION`/`HERDR_PANE` exported into the pane shell), a readiness gate before prompting, retry limits with fixed deterministic backoff (covering prompt and probe failures), and terminal-failure reporting — including the ambiguous crash window after a submitted prompt, reported instead of silently resent.
+- `Ace::Herdr::Organisms::Dispatcher`: one-command subagent dispatch — tab + `herdr agent start` + prompt with deterministic defaults (caller's workspace, label = agent/pane name, prompt from file/stdin/`--no-prompt`); workspace and pane identifiers are token-validated and shell-escaped before they reach a pane shell.
+- `ace-herdr` CLI: `deliver`, `dispatch`, `wait`, `close` (JSON output, exception-based exit codes per ADR-023).
+- `Ace::Herdr::Molecules::HerdrExecutor`: the single seam to the herdr CLI (argv arrays per ADR-031) with typed error classification from herdr's machine-readable codes (`agent_blocked`, `agent_prompt_stalled`, `pane_not_found`, `timeout`).
+- Config cascade (ADR-022) defaults: `default_agent_kind`, delivery retry limits/backoff, timeouts, deliveries dir (ADR-029).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+<div align="center">
+  <h1> ACE - HERDR </h1>
+
+  Zero-token push delivery and agent bootstrap for the Herdr runtime, behind the ace-hitl provider delivery contract.
+
+  <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-herdr"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-herdr.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[Usage Guide](docs/usage.md)
+
+`ace-herdr` is to herdr what `ace-tmux` is to tmux: a deterministic, zero-token wrapper over the `herdr` CLI. It implements the ace-hitl push-delivery contract — `deliver(ref, answer)` maps to `herdr agent prompt <pane>`, bootstrapping the agent first (`herdr agent start`) when the pane has none, so an answer is never lost — and adds one-command agent dispatch, noiseless monitoring, and closure on top.
+
+## How It Works
+
+1. Every ace-hitl ask captures a reverse address (`HERDR_SESSION` / `HERDR_PANE`, schema `ace.hitl.ref/v1`). `ace-herdr deliver` pushes an answer back to that address.
+2. Delivery is idempotent per event id: write-ahead delivery records under `.ace-local/herdr/deliveries/` make retries safe — identical content is never delivered twice.
+3. If the target pane has no agent, `ace-herdr` bootstraps one (`herdr agent start --kind <kind> --pane <pane>`), waits for readiness, and exports `HERDR_SESSION` / `HERDR_PANE` into the agent's environment.
+4. Retryable failures back off on a fixed deterministic schedule; terminal failures are reported and persisted in the delivery record.
+5. `ace-herdr dispatch`, `wait`, and `close` give agents one-command subagent lifecycle with sensible defaults (same workspace as the caller, label = task id, prompt from file or stdin).
+
+## Use Cases
+
+- Push an HITL answer to the pane that asked, even if its agent was restarted since.
+- Dispatch a subagent in one command with deterministic defaults and no LLM decisions.
+- Wait for agent readiness or completion without scraping pane noise.
+- Close out finished agent panes (rename/close) and return their result.
+
+## Installation
+
+Install as part of the ACE toolkit (see the repo README), or add to your Gemfile:
+
+```ruby
+gem "ace-herdr"
+```
+
+## Testing
+
+Fast tests only (no live herdr needed):
+
+```bash
+ace-test ace-herdr
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/usage.md

@@ -0,0 +1,306 @@
+---
+doc-type: user
+title: ace-herdr Usage
+purpose: Full CLI and configuration reference for ace-herdr: push delivery, agent bootstrap, the terminal-control surface (list, send, capture, wait, presets), and tidy cleanup.
+ace-docs:
+  last-updated: 2026-09-28
+  last-checked: 2026-09-28
+---
+
+# Usage
+
+`ace-herdr` is a zero-token wrapper over the `herdr` CLI. It implements the ace-hitl push-delivery contract -- `deliver(ref, answer)` -> `herdr agent prompt <pane>` -- one-command agent dispatch, noiseless waiting and pane closure, the terminal-control intents known from `ace-tmux` (`list`, `send`, `capture`, output waits, preset-driven workspace/tab creation), and dry-run-first cleanup of finished panes and delivery records (`tidy`). No LLM is consulted anywhere in the gem.
+
+## Command Surface
+
+- `ace-herdr deliver [OPTIONS]`
+- `ace-herdr dispatch [OPTIONS]`
+- `ace-herdr list [--panes|--tabs|--workspaces] [--workspace ID] [--quiet]`
+- `ace-herdr send [--cmd TEXT] [--msg TEXT...] [--key NAME...] --pane ID [--quiet]`
+- `ace-herdr capture --pane ID [--lines N] [--source visible|recent]`
+- `ace-herdr wait --pane ID (--for output --pattern PATTERN | --for agent [--until ...]) [--timeout S] [--quiet]`
+- `ace-herdr close [OPTIONS]`
+- `ace-herdr tidy [--apply] [--quiet]`
+- `ace-herdr workspace <preset> [--cwd PATH] [--quiet]`
+- `ace-herdr tab <preset> [--workspace ID] [--cwd PATH] [--quiet]`
+- `ace-herdr --list-presets [workspaces|tabs]`
+
+## Output policy
+
+Control commands print exactly one deterministic JSON line on stdout; `--quiet` suppresses it. Failures surface herdr's machine error codes in the CLI error message (for example `pane_not_found: pane w9:p1 not found`) and exit non-zero. The one exception is `capture`, which prints raw pane text without any JSON wrapping.
+
+herdr *sessions* (server persistence) are intentionally not exposed; the tmux session analogue is the herdr **workspace**.
+
+## tmux-intent ↔ herdr-command parity
+
+Every common terminal-control intent available through `ace-tmux` is available through `ace-herdr` (herdr 0.9.1). Parity is of INTENT and FLAG VOCABULARY, not byte-format: ace-herdr keeps one-line JSON where ace-tmux renders human tables.
+
+| ace-tmux intent | ace-herdr command | Native herdr call |
+|---|---|---|
+| `list` (panes) | `list` / `list --panes` | `pane list` |
+| `list --windows` | `list --tabs` | `tab list` |
+| `list --sessions` | `list --workspaces` | `workspace list` |
+| `send --cmd` | `send --cmd` | `pane run` (plain) / `agent prompt` (agent pane) |
+| `send --msg` / `--key` | `send --msg` / `--key` | `pane send-text` / `pane send-keys`; `agent prompt` / `agent send-keys` |
+| `capture` | `capture` | `pane read` |
+| `wait --for output` | `wait --for output --pattern` | `pane wait-output` |
+| `wait --for agent` | `wait --until` (agent state) | `agent wait` |
+| `start <preset>` | `workspace <preset>` | `workspace create` + tabs/panes |
+| `window <preset>` | `tab <preset>` | `tab create` + splits |
+| `--list-presets` | `--list-presets` | -- (config cascade) |
+| `attach` / `detach` | ❌ out of scope | human-facing; no automation equivalent |
+| layout strings / `select-layout` | ❌ out of scope | herdr has split/resize only |
+
+## `ace-herdr list`
+
+Inspect live state. Panes are the default scope; `--workspace <id>` scopes panes and tabs.
+
+```bash
+ace-herdr list                          # panes across all workspaces
+ace-herdr list --workspace w1           # panes in one workspace
+ace-herdr list --tabs --workspace w1    # tabs in one workspace
+ace-herdr list --workspaces             # workspaces
+```
+
+Output: `{"panes":[{"id":"w1:p1","tab":"w1:t1","workspace":"w1","title":"~","cwd":"/tmp","focused":true,"agent_status":"idle"},...]}` -- `{"tabs":[{id, workspace, title, number, pane_count, focused}...]}` for `--tabs`, `{"workspaces":[{id, title, number, tab_count, pane_count, focused}...]}` for `--workspaces`. Empty results are a success with an empty array, never an error.
+
+## `ace-herdr send`
+
+Send a command, raw text, or named keys. Input reaches the pane in **declaration order** (an intentional divergence from ace-tmux's msgs-then-keys; order is expressive here, so it is preserved, not normalized). At least one input token is required -- none is a usage error before any transport call.
+
+```bash
+ace-herdr send --pane p5 --cmd 'bundle exec rake test'
+ace-herdr send --pane p5 --msg 'continue with option 2' --key Enter
+ace-herdr send --pane p5 --key Esc --cmd 'reset'     # rejected -- see rules
+ace-herdr send --pane p5 --key enter
+```
+
+### Plain pane (raw input, declaration order)
+
+- `--cmd TEXT` is exactly one `pane run` submission (text + Enter). It must be declared before every `--key`; trailing keys are sent after the submission (post-submission keystrokes such as `y`/`n` confirmations). Leading keys (`--key Esc --cmd run`) are rejected before any transport call.
+- `--msg a --msg b` types raw text without submitting, concatenated in order.
+- `--key K...` sends named keys in order; each `enter` submits pending text.
+- `--cmd` combined with `--msg` is a usage error before any transport call (fail closed, nothing sent).
+- Multi-Enter sequences submit per Enter.
+- Output: `{"pane":"p5","sent":"cmd"}` for command-led sends, `"text"` for message-led sends, `"keys"` for key-only sends.
+
+### Agent pane (prompt semantics)
+
+When the target pane hosts a live agent (`herdr agent get`), the same flags route to agent transport -- replacing ace-tmux's INTERACTIVE_CLI_COMMANDS/busy-pattern heuristics with native agent state:
+
+- `--cmd T`, or concatenated `--msg` texts (joined with newlines), becomes **one** agent prompt that submits itself -- message-only input submits once on an agent pane (intended divergence from plain panes).
+- At most one trailing `--key Enter` is dropped and reported: `{"pane":"p5","sent":"prompt","dropped_keys":["Enter"]}` -- this guarantees exactly-one submission instead of erroring.
+- `--key`-only sequences go to `agent send-keys` (`esc`, `ctrl+c`, ...); at most one `enter` total.
+- Submission is gated natively: a blocked agent rejects pre-send with a CLI error carrying `agent_blocked` (never silently dropped); a stalled prompt surfaces `agent_prompt_stalled`.
+- Rejected before transport: keys interleaved between or after messages other than the single trailing `enter`; multiple `enter` keys; `--cmd` with non-Enter keys; `--cmd` combined with `--msg`.
+
+## `ace-herdr capture`
+
+Print pane content as raw text (no JSON wrapping). Read-only -- agent routing rules do not apply.
+
+```bash
+ace-herdr capture --pane p5                     # last 40 lines of history
+ace-herdr capture --pane p5 --lines 40 --source recent
+ace-herdr capture --pane p5 --source visible    # the agent screen
+```
+
+## `ace-herdr wait`
+
+Wait for an agent state or matching pane output.
+
+```bash
+ace-herdr wait --pane p5                                  # agent: idle, done, or blocked
+ace-herdr wait --pane p5 --until done --timeout 120       # agent: one state
+ace-herdr wait --pane p5 --for output --pattern 'tests? OK' --timeout 30
+```
+
+- Agent form (default; unchanged): `--until idle,working,blocked,done,unknown`, output `{"pane":"p5","state":"ready"}`.
+- Output form: `--for output --pattern PATTERN` (literal substring, matching ace-tmux's observable contract). herdr checks existing pane content immediately, then polls; `--timeout` is seconds (gem converts to milliseconds). Output `{"pane":"p5","matched":true}`; a timeout is a CLI error (non-zero exit).
+- The modes are mutually exclusive: `--pattern` requires `--for output`; `--until` requires the agent form.
+
+## `ace-herdr workspace` / `ace-herdr tab` (presets)
+
+Declare a workspace or tab layout in YAML and create it in one command -- `workspace <preset>` mirrors `ace-tmux start`, `tab <preset>` mirrors `ace-tmux window`.
+
+```bash
+ace-herdr workspace development
+ace-herdr workspace development --cwd /path/to/project
+ace-herdr tab agent --workspace w1
+ace-herdr --list-presets               # merged inventory, both types
+ace-herdr --list-presets workspaces
+```
+
+### Preset cascade (ADR-022)
+
+Presets load nearest-wins and the `--list-presets` inventory reflects the merged set:
+
+1. project `.ace/herdr/{workspaces,tabs}/*.yml` (highest)
+2. user `~/.ace/herdr/{workspaces,tabs}/*.yml`
+3. gem `.ace-defaults/herdr/{workspaces,tabs}/*.yml` -- ships `workspaces/development.yml` and `tabs/agent.yml`
+
+A project file with the same name overrides a gem/user file; names unique to a level still appear in the merged listing.
+
+### Schema
+
+```yaml
+# .ace/herdr/workspaces/development.yml
+label: development          # workspace label (defaults to the preset name)
+cwd: /workspace/project     # root cwd (tab/panes inherit; ~ expands)
+focus: true                 # pass --focus to workspace create
+tabs:
+  - preset: agent           # a tab may inherit a tab preset (recursive; overlay wins)
+    label: work             # ...and override any field
+  - label: editor
+    cwd: /workspace/project # tab cwd overrides the root cwd
+    focus: false
+    panes:
+      - label: shell        # the FIRST pane is the tab's root pane
+      - label: agent
+        cwd: /workspace/project
+        agent:              # declares an agent pane
+          kind: pi          # default: config default_agent_kind
+          name: development-agent
+          prompt: Review the current task.
+    splits:                 # every pane after the first must be placed by a split
+      - direction: right    # herdr-native right|down; horizontal|vertical accepted
+        target: shell       # pane label to split from (default: the root pane)
+        pane: agent         # the declared pane placed by this split
+        ratio: 0.5
+```
+
+```yaml
+# .ace/herdr/tabs/agent.yml -- a tab preset uses the tab-level fields directly
+label: agent
+panes:
+  - label: agent
+    agent:
+      kind: pi
+      name: task-agent
+```
+
+Creation is deterministic and ordered: the workspace is created first, then tabs/panes in declared order (root pane from `tab create`, further panes from `pane split`, panes renamed to their labels), then pane `command`s run, then declared agents start readiness-gated (`agent start` blocks until the pane is interactive; vs0 bootstrap order: reverse address exported into the pane shell, agent start, optional prompt). herdr seeds every new workspace with an initial tab; once the preset's declared tabs exist that seeded tab is closed, so only declared tabs remain (a preset with no `tabs:` keeps the seeded one). All layouts are validated before any herdr call -- an unplaced pane, a duplicate split placement, an unknown split target, or an unknown direction fails closed and creates nothing.
+
+Output: `{"workspace":"w2","tabs":[{"tab":"w2:t1","panes":["w2:p1","w2:p2"],"commands":1,"agents":["development-agent"]}]}`; the tab command reports the single tab object. `--cwd` overrides the resolved root/tab cwd (CLI > tab > root > pane inheritance).
+
+Unknown preset: CLI error listing the available names (ace-tmux `--list-presets` parity), for example `Error: Unknown workspace preset 'nope' (available: development)`.
+
+## `ace-herdr deliver`
+
+Push an answer to an agent pane.
+
+```bash
+# Answer from a file, explicit ref
+ace-herdr deliver --session ws-1 --pane p5 --event-id evt-1 --answer-file answer.md
+
+# Answer from stdin, ref from the environment (inside the asking pane)
+echo 'the answer' | ace-herdr deliver
+
+# Bootstrap a specific agent kind if the pane has none
+ace-herdr deliver --session ws-1 --pane p5 --kind codex --label 8wm.t.vs0 --answer-file a.md
+```
+
+Options: `--session`, `--pane` (default: `HERDR_SESSION` / `HERDR_PANE`), `--event-id` (default: derived from the ref and content digest), `--kind`, `--label`, `--answer-file` (default: stdin), `--resume <event-id>` (re-deliver the stored answer from the record; no ref or answer input needed).
+
+Output: one JSON line `{"ref":{...},"state":"delivered|retryable|failed"}`. Exit code is non-zero unless the state is `delivered`.
+
+### The delivery contract
+
+`ace-hitl ask` captures the asker's reverse address fail-closed from the environment (`HERDR_SESSION` / `HERDR_PANE`, schema `ace.hitl.ref/v1`). `ace-herdr deliver` pushes an answer back to that address:
+
+1. A write-ahead delivery record carrying the full answer is persisted under `.ace-local/herdr/deliveries/<event-id>.json` (mode 0600, atomic rename) before any herdr contact, so a crash can never lose the answer. A crashed run is recovered with `--resume <event-id>`.
+2. Delivery is idempotent per event id and serialized by a per-event lock: concurrent deliveries prompt once. Re-delivering identical content after a `delivered` record short-circuits without contacting herdr; different content or a different destination for the same event id fails closed.
+3. If the target pane has no agent, one is bootstrapped (`herdr agent start`), the reverse address is exported into the pane shell (`export HERDR_SESSION=... HERDR_PANE=...`; values are token-validated and shell-escaped), and delivery waits for the agent to become idle before prompting.
+4. Transient failures (readiness timeout, `agent_prompt_stalled`, socket/binary unavailability -- at the probe as well as the prompt) persist their history and report `retryable` within `delivery.max_attempts`.
+5. Terminal failures (`agent_blocked` pre-send rejection, missing pane, agent start failure) report `failed` immediately with the error persisted in the record history.
+6. An interrupted run whose last recorded event is a prompt submission without an outcome is ambiguous: the answer may already have been delivered. Re-running reports `failed` ("previous run crashed after submitting") instead of silently resending.
+
+Result states follow the ace-hitl contract (spec 8wm.t.vrz §1.2): `delivered`, `retryable` (safe to re-push identical content), `failed` (terminal).
+
+## `ace-herdr dispatch`
+
+Start an agent in one command: tab + `herdr agent start` + prompt, all with deterministic defaults.
+
+```bash
+ace-herdr dispatch --label 8wm.t.vs0 --kind pi --prompt-file prompt.md
+ace-herdr dispatch --label review --pane p7 --cwd /path/to/project
+ace-herdr dispatch --label 8wm.t.vs0 --no-prompt
+```
+
+Defaults: the caller's herdr workspace (flag `--workspace` > `HERDR_WORKSPACE_ID` > `herdr pane current`), the label as agent and pane name, the prompt from `--prompt-file` or stdin (`--no-prompt` skips submission). The new agent's environment receives `HERDR_SESSION` (workspace id) and `HERDR_PANE` (pane id) so its own `ace-hitl ask` calls carry a working reverse address.
+
+Output: one JSON line `{"workspace":...,"pane":...,"agent":...,"kind":...,"tab_created":...,"prompted":...}`.
+
+## `ace-herdr close`
+
+Close out a finished agent pane; optionally rename first.
+
+```bash
+ace-herdr close --pane p5 --rename done       # rename, then close
+ace-herdr close --pane p5 --keep --rename wip # rename only
+```
+
+## `ace-herdr tidy`
+
+Report cleanable agent panes and delivery records as one deterministic JSON line; **dry run by default** -- nothing is closed, moved, or removed without `--apply`.
+
+```bash
+ace-herdr tidy            # dry run: report candidates, zero side effects
+ace-herdr tidy --apply    # close eligible panes, archive old delivered records
+ace-herdr tidy --quiet    # suppress the report
+```
+
+Output: `{"apply":false,"retention_days":7,"panes":{"candidates":[...],"preserved":[...],"closed":[...],"excluded":[...]},"deliveries":{"candidates":[...],"protected":[...],"archived":[...],"preserved":[...]}}`. Entries are ordered by pane id / event id; every bucket is always present (an explicit empty array means "nothing to do", never an error).
+
+### Pane closure: positive evidence only
+
+A pane qualifies as a `candidate` solely on positive completion evidence:
+
+- the agent in the pane was **observed** in state `done` (`agent get`), or
+- the pane has **no foreground process** (`pane process-info` reports an empty process list).
+
+`unknown` or unreadable evidence is preserve-only: `unknown` status, a missing field, a malformed response, or a probe failure puts the pane in `preserved` with the reason (`active` / `unknown` / `unreadable`) -- no proof is never treated as dead. Panes whose process could not be read are reported, not closed.
+
+With `--apply`, every candidate is **re-probed immediately before mutation**: only a second positive reading closes it (rename to `done`, then close -- the `close` semantics). A candidate that revived in between (`idle`/`working`) or whose fresh probe turned uncertain or failed is moved to `excluded` with the reason and never mutated. A pane that vanished in the meantime is `excluded` as `gone` -- there is nothing left to close.
+
+### Delivery record retention
+
+Delivered records under `deliveries_dir` whose `updated_at` is **strictly older** than `tidy.delivered_retention_days` (default 7; an exact-threshold record stays) become `candidates`; with `--apply` they are atomically moved to `deliveries_dir/archive/<event-id>.json` (mode 0600 preserved) and reported in `archived` with the archive path. Age parsing is RFC 3339 only; a delivered record with a missing or invalid `updated_at` is `preserved` (`invalid_updated_at`), never guessed.
+
+`pending`, `retryable`, and `failed` records are **never touched** (they are audit/recovery state) and are listed in `protected`. Malformed or unreadable record files are `preserved` as `unreadable`, never removed. Lock files, temp files, and the archive directory itself are ignored. Before each archival the record is re-loaded under its per-event lock: a record that changed after discovery (no longer delivered or no longer old enough) is left in place and reported as `preserved` (`changed`); one that turned unreadable is `preserved` (`unreadable`) without aborting the run. Archival never breaks delivery idempotency: `deliver`/`--resume` consult the archive copy, so re-delivering an archived event still short-circuits (identical content) or fails closed (conflicting content) instead of re-prompting.
+
+Errors: if the herdr runtime is unreachable, `tidy` fails with an explicit CLI error before reporting anything (no partial report, no mutation). No LLM is consulted anywhere; the report costs zero tokens.
+
+## Configuration
+
+Defaults (`.ace-defaults/herdr/config.yml`), overridable in `~/.ace/herdr/config.yml` or `.ace/herdr/config.yml`:
+
+```yaml
+default_agent_kind: pi          # herdr agent kind used for bootstrap/dispatch/preset agents
+delivery:
+  max_attempts: 3               # prompt attempts per delivery sequence
+  backoff_seconds: [1, 2, 4]    # fixed deterministic backoff, no jitter
+timeouts:
+  agent_start: 60               # seconds to interactive readiness (also preset agents)
+  prompt: 30
+  wait: 30                      # readiness gate / ace-herdr wait (both wait modes)
+deliveries_dir: .ace-local/herdr/deliveries
+tidy:
+  delivered_retention_days: 7   # archive delivered records strictly older than this (tidy)
+```
+
+## Delivery records
+
+Records are JSON, one file per event id under `deliveries_dir` (relative to the working directory, mode 0600): event id, reverse address, SHA-256 answer digest, the full answer (so a crash never loses content), state (`pending` / `delivered` / `retryable` / `failed`), attempt count, and an append-only history of bootstrap, readiness, and prompt events with errors. Records are written atomically and guarded by a per-event lock. Re-running `deliver` with the same event id and content resumes or short-circuits; with different content or a different destination it fails closed.
+
+## Error semantics
+
+Commands raise a CLI error (non-zero exit) carrying herdr's machine code where one exists:
+
+- Unknown pane/tab/workspace: `pane_not_found: ...`, `tab_not_found: ...`, `workspace_not_found: ...`
+- herdr binary or socket unavailable: explicit CLI error, no partial output
+- Blocked agent: `agent_blocked: ...` (terminal -- never silently dropped); stalled prompt: `agent_prompt_stalled: ...` (transient)
+- Output wait timeout: `timeout: ...`
+- Unknown preset: usage error listing the available preset names
+- Invalid send shapes: usage error **before any transport call** (nothing is sent)
+
+Exit `0` means success (including an explicit empty `list` result or a satisfied wait).

data/exe/ace-herdr

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ace/herdr"
+
+# No args -> show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start CLI with exception-based exit code handling (per ADR-023)
+begin
+  exit_code = Ace::Herdr::CLI.start(args)
+  exit(exit_code) if exit_code.is_a?(Integer) && exit_code.nonzero?
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+end

data/lib/ace/herdr/atoms/answer_digest.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Ace
+  module Herdr
+    module Atoms
+      # SHA-256 hex digest of delivery content; pure function
+      module AnswerDigest
+        module_function
+
+        def call(content)
+          Digest::SHA256.hexdigest(content.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/capture.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Capture < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Print recent pane output as raw text (no JSON wrapping)
+
+            --source visible reads the current screen; recent (default)
+            reads terminal history. Read-only: agent routing rules do not
+            apply.
+          DESC
+
+          example [
+            "--pane p5",
+            "--pane p5 --lines 40",
+            "--pane p5 --source visible"
+          ]
+
+          option :pane, type: :string, desc: "Target pane id"
+          option :lines, type: :integer, desc: "Number of lines (default: 40)"
+          option :source, type: :string, desc: "Snapshot source: visible or recent (default: recent)"
+
+          def initialize(executor: nil)
+            @executor = executor
+          end
+
+          def call(**options)
+            translate_errors do
+              cli_error("--pane is required") if options[:pane].to_s.empty?
+              source = options[:source] || "recent"
+              unless %w[visible recent].include?(source)
+                cli_error("--source must be visible or recent")
+              end
+              control = Organisms::ControlSurface.new(executor: executor)
+              print control.capture(
+                pane: options.fetch(:pane), source: source,
+                lines: options[:lines] || Organisms::ControlSurface::DEFAULT_LINES
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/close.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Close < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Rename and/or close a finished agent pane, returning the result
+          DESC
+
+          example [
+            "--pane p5 --rename done",
+            "--pane p5",
+            "--pane p5 --keep --rename 'review done'"
+          ]
+
+          option :pane, type: :string, desc: "Target pane id"
+          option :rename, type: :string, desc: "New pane label applied before closing"
+          option :keep, type: :boolean, desc: "Rename only; do not close the pane"
+
+          def initialize(executor: nil)
+            @executor = executor
+          end
+
+          def call(**options)
+            translate_errors do
+              cli_error("--pane is required") if options[:pane].to_s.empty?
+              renamed = false
+              closed = false
+              if options[:rename]
+                executor.pane_rename(options.fetch(:pane), options[:rename])
+                renamed = true
+              end
+              unless options[:keep]
+                executor.pane_close(options.fetch(:pane))
+                closed = true
+              end
+              puts JSON.generate(pane: options.fetch(:pane), renamed: renamed, closed: closed)
+            end
+          end
+        end
+      end
+    end
+  end
+end