repo-harness 0.25.1 → 0.25.3

package/README.md

@@ -43,7 +43,7 @@ files let Claude and Codex resume work across sessions.
 
 ### 1. Install the CLI
 
-Prerequisites: a Git working tree, `bun`, and usable `herdr` >=0.9.5 for host readiness; macOS/Linux also require `bash`,
+Prerequisites: a Git working tree, `bun`, and `hc` (herdr-core) >= `external_tooling.herdr_core.min_version` for host readiness; macOS/Linux also require `bash`,
 while Windows requires Git for Windows (including its Bash and `usr/bin`
 tools). `jq` is optional. No Node.js required — the installer uses Bun >=
 1.4.0 as the runtime, installing or upgrading Bun first when needed.
@@ -67,9 +67,10 @@ repo-harness install
 npx -y repo-harness@latest install   # npx fallback; the CLI still runs on Bun
 ```
 
-Install herdr from [herdr.dev](https://herdr.dev/) and verify `herdr --version`.
+Install `hc` through Herdr.app or a herdr-core release. Verify that `hc --version`
+reports at least `.ai/harness/policy.json#external_tooling.herdr_core.min_version`.
 Persistent review hosting requires POSIX process groups; on Windows use WSL.
-Missing or unusable herdr blocks host readiness. Before upgrading from tmux,
+Missing, unusable or older hc blocks host readiness. Before upgrading from tmux,
 drain existing reviewers using the previous version and explicitly rebind terminal
 endpoints. See [runtime cutover](https://github.com/Ancienttwo/repo-harness/blob/archive/docs-researches-20261004/docs/researches/20260909-herdr-runtime-cutover.md).
 
@@ -593,7 +594,7 @@ dependencies.
 | [Hylarucoder](https://x.com/hylarucoder) / Geju | P1/P2/P3 due-diligence method and Geju practice that shaped the planning, tracing, and decision-rationale discipline in this workflow | Methodology contribution and acknowledgement; not a bundled dependency |
 | Waza by [TW93](https://x.com/HiTw93), including `think`, `hunt`, `check`, and `health` | Daily planning, bug hunts, verification, health checks, and Codex-first skill sync | Installed through the skills CLI into host skill roots |
 | `mermaid` | Authoring and readability review for Mermaid architecture and system-flow source | Runtime-referenced review skill, not vendored into generated repos and never an HTML artifact generator |
-| [herdr](https://herdr.dev/) | Required peer-terminal runtime: notification dispatch, peer collaboration, and hosting the persistent acceptance reviewer | Externally installed binary, checksum-pinned in `.ai/harness/policy.json`; replaces the retired tmux runtime |
+| [herdr](https://herdr.dev/) (`hc`, herdr-core) | Required peer-terminal runtime: notification dispatch, peer collaboration, and hosting the persistent acceptance reviewer | Externally installed `hc` binary, pinned in `.ai/harness/policy.json#external_tooling.herdr_core` (`min_version` floor and checksum-verified CI release asset); replaces the retired tmux runtime |
 | [`reverse-skill-router`](https://github.com/zhaoxuya520/reverse-skill) | Routes reverse-engineering and security tasks to specialist playbooks | Recommended explicit-only Skill (`--with-reverse-skill`); not profile-selected because upstream's target-mention authorization assumption requires independent scope review |
 | CodeGraph (`@colbymchenry/codegraph`) | Symbol-aware navigation, impact tracing, and readiness checks for this self-host repo | Dev dependency in this repo; generated repos stay global-MCP-first unless policy opts in |
 | OpenAI Codex | Primary execution agent for repo-local implementation, verification, and GitHub contributor attribution when a commit materially includes Codex-authored work | External agent runtime; attribution is an explicit commit trailer, not hidden hook automation |
@@ -612,8 +613,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.25.1`
-- Generated workflow stamp: `repo-harness@0.25.1+template@0.25.1`
+- npm package: `repo-harness@0.25.3`
+- Generated workflow stamp: `repo-harness@0.25.3+template@0.25.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/agents/fleet/orchestrator.md

@@ -1,9 +1,9 @@
 ---
 name: orchestrator
-description: Dispatch-only issue-flow coordinator. Suggested model: Opus at xhigh effort. The Claude entry runs with `claude --agent orchestrator`; other hosts load the issue-flow skill's orchestrator mode. Reads archimap and capability docs, splits issues, dispatches work, and follows PRs and CI. Never edits product code, reviews its own dispatched PRs, or dispatches subagents.
+description: Dispatch-only issue-flow coordinator. Suggested model: Opus at high effort. The Claude entry runs with `claude --agent orchestrator`; other hosts load the issue-flow skill's orchestrator mode. Reads archimap and capability docs, splits issues, dispatches work, and follows PRs and CI. Never edits product code, reviews its own dispatched PRs, or dispatches subagents.
 tools: ["Read", "Grep", "Glob", "Bash", "TaskCreate", "TaskUpdate", "TaskList", "TaskGet"]
 model: opus
-effort: xhigh
+effort: high
 ---
 
 You are the orchestrator. You run as a long-lived top-level session, not as a subagent. Any host may run this seat. The model and effort in this file are a suggestion for the Claude entry.
@@ -16,7 +16,7 @@ You may:
 - Read code and docs with Read, Grep and Glob.
 - Run read-only checks with Bash. Examples: `git status`, `git log`, `gh issue view`, `gh pr view`, `gh pr checks`.
 - Create issues and comments with `gh issue create --body-file -` and `gh issue comment --body-file -`. Send the body on standard input. Do not write the body to a file.
-- Dispatch work with `herdr agent prompt`. Each dispatch names the issue, the file scope, the verification command and the forbidden areas.
+- Dispatch work with the `hc` commands of the Herdr Dispatch runbook (`docs/reference-configs/herdr-notify.md`): `hc send <t> <comment URL>` to message a worker, `hc read <t>` and `hc wait <t>` to follow it. Each dispatch names the issue, the file scope, the verification command and the forbidden areas.
 - Follow open PRs and CI. Report each result to the issue.
 - Keep worker notices in a triage queue with TaskCreate, TaskUpdate, TaskList and TaskGet. Follow `references/orchestrator.md` §8.1 of `repo-harness-issue-flow`: answer the owner first, then take one queue item at a time by priority.
 

package/assets/herdr/github-events/bot-event.d.mts

@@ -0,0 +1,12 @@
+export declare const BOT_EVENT_PROTOCOL: 'repo-harness.bot-event/v1';
+export declare const NAME_PATTERN: RegExp;
+export interface BotEvent {
+  readonly protocol: 'repo-harness.bot-event/v1';
+  readonly source: 'herdr' | 'github';
+  readonly repository: string | null;
+  readonly kind: string;
+  readonly ts: string;
+  readonly data: Readonly<Record<string, unknown>>;
+}
+export declare function assertBotEvent(value: unknown): BotEvent;
+export declare function botEvent(input: Omit<BotEvent, 'protocol'>): BotEvent;

package/assets/herdr/{webhook-notify → github-events}/bot-event.mjs

@@ -1,4 +1,4 @@
-// The one bot event envelope. Herdr notify and the GitHub event Worker both send it, so it
+// The one bot event envelope. The notify relay and the GitHub event Worker both send it, so it
 // stays plain ESM with no dependency and no Node-only API.
 export const BOT_EVENT_PROTOCOL = 'repo-harness.bot-event/v1';
 export const NAME_PATTERN = /^[\w.-]{1,128}$/;

package/assets/herdr/github-events/worker.mjs

@@ -1,8 +1,7 @@
 // GitHub App webhook receiver. It filters GitHub events in code and sends a short bot event
 // to the Bot routine webhook. It never calls a GitHub API and makes no decision.
-// `repo-harness events install` stages this directory and ../webhook-notify/bot-event.mjs in the same
-// layout, and wrangler bundles them.
-import { botEvent } from '../webhook-notify/bot-event.mjs';
+// `repo-harness events install` stages this directory, and wrangler bundles it.
+import { botEvent } from './bot-event.mjs';
 import { classify } from './filter.mjs';
 
 const DEBOUNCE_SECONDS = 60;

package/assets/reference-configs/agentic-development-flow.md

@@ -104,8 +104,8 @@ breakdown, dispatch, follow-up and evidence-based reports. Coding agents own
 source edits, tests and repairs. Follow the shared PM boundary in the
 `repo-harness` Skill for the permitted tool surface and reporting duties.
 Keep direct development sessions and explicitly assigned coding workers outside
-that PM restriction. OAR owns coding-agent execution. Herdr owns panes and
-visibility. A new Bot host adapts to that path; it does not add a new coding
+that PM restriction. OAR owns coding-agent execution. herdr-core (`hc`) owns
+terminals, and Herdr.app owns panes and visibility. A new Bot host adapts to that path; it does not add a new coding
 runtime or task authority.
 
 The `orchestrator` fleet role is the long-lived coordinator and integrator seat

package/assets/reference-configs/external-tooling.md

@@ -374,8 +374,7 @@ boundary explicit:
 
 | Capability | Owner | Required for |
 |---|---|---|
-| `herdr` | user install (herdr.dev) | required at the version pinned in `.ai/harness/policy.json#external_tooling.herdr`; peer terminals and persistent task reviewer hosting |
-| `herdr_core` (`hc`) | user install (Herdr.app or a herdr-core release) | optional, at least the version pinned in `.ai/harness/policy.json#external_tooling.herdr_core`; persistent terminals and agent messaging; no repo-harness automation uses it yet |
+| `herdr_core` (`hc`) | user install (Herdr.app or a herdr-core release) | required, at least the version pinned in `.ai/harness/policy.json#external_tooling.herdr_core`; persistent agent terminals, task sessions, review hosting and the notify relay |
 | `bun` | repo-harness | repo-harness-owned global installs, local dependency install, tests, and runtime execution |
 | `bash` | repo-harness | helper scripts, migration, setup checks, and contract verification wrappers; Git-for-Windows Bash is the Windows platform contract |
 | `npm` | npm registry | registry readbacks, publish gates, and opt-in update checks; not repo-harness-owned global install repair |
@@ -383,45 +382,39 @@ boundary explicit:
 | `rsync` | platform filesystem | installed-copy runtime mirroring |
 | `symlink` | platform filesystem | link-mode aliases; copy mode is the fallback |
 
-`.ai/harness/policy.json#external_tooling.herdr` is the single herdr pin: it owns
-the `min_version` floor and the checksum-verified `release_assets` entry that CI
-installs. Install herdr through its official installer or platform package manager
-and verify `herdr --version` reports at least that pinned `min_version`.
-`check-agent-tooling.sh --strict-readiness` reads the same key and fails if herdr is
-missing, unusable, or older than the pin; `setup check` projects `runtime.herdr`. Repo-harness does not install it or edit user Herdr config.
+`.ai/harness/policy.json#external_tooling.herdr_core` is the single herdr pin: it
+owns the `min_version` floor and the checksum-verified `release_assets` entry that
+CI installs. Install hc through Herdr.app or a herdr-core release and verify
+`hc --version` reports at least that pinned `min_version`.
+`check-agent-tooling.sh --strict-readiness` reads the same key and fails if hc is
+missing, unusable, or older than the pin. A missing or malformed pin is a
+`configuration-error`. `setup check` projects `runtime.herdr_core`. Repo-harness
+does not install hc or edit user Herdr config. Herdr.app is not a readiness
+requirement: it has no Intel macOS build.
 The root `repo-harness` skill requires the `herdr` skill on Codex and Claude.
-`repo-harness install` and `repo-harness update` combine the CLI reference from
-`herdr --skill` with the caller-context policy in
-`assets/reference-configs/herdr-skill-context.md`. The shared renderer replaces
-the binary's introductory environment gate and rejects an unknown section layout.
-Both hosts receive the same generated skill. When Codex is selected, an existing
+`repo-harness install` and `repo-harness update` put the caller-context policy in
+`assets/reference-configs/herdr-skill-context.md` before the hc manual from
+`hc --skill`. The shared renderer keeps the manual verbatim and rejects output
+that is not the hc manual. Both hosts receive the same generated skill. When Codex is selected, an existing
 shared copy at `~/.agents/skills/herdr` is also updated and checked because Codex
 can discover it. Claude-only operations leave that shared copy unchanged.
 Install refuses to replace a
 user-edited or unowned copy. Strict readiness compares against the same renderer.
 Missing tool environment variables do not prove that the user is outside Herdr.
-Read-only discovery lists running sessions and panes by the task's exact path.
-Reuse a suitable task reviewer or create a new pane in the matched workspace.
+Read-only discovery lists live hc terminals (`hc ls --json`) by the task's exact path.
+Reuse a suitable task reviewer or start a new terminal at the task path.
 Path matching selects a location; it does not transfer another agent's task.
-Use explicit session and pane IDs for control after discovery.
+Use explicit hc terminal addresses for control after discovery.
 The persistent reviewer still requires POSIX process groups: use macOS/Linux or
 WSL. Native Windows review lifecycle support is not implied by Herdr support.
-Admitted task sessions start only in a Herdr pane, so they and their Task Inbox and operator diff consumers are POSIX-only; on Windows, session start fails closed with `herdr_endpoint_platform_unsupported`.
+Admitted task sessions start only in an hc terminal, so they and their Task Inbox and operator diff consumers are POSIX-only.
 Drain old tmux reviewers with the previous repo-harness version before upgrading.
 No runtime or collaboration path automatically falls back to tmux.
 
-herdr-core (`hc`) is a separate product with its own pin. It has persistent
-terminals and a JSON-RPC API, and it has built-in remote host access
-(`hc machine`, `hc run --on <machine>`). It has no sessions, panes,
-workspaces or plugins. `check-agent-tooling.sh` reports it as the optional
-`runtime_capabilities.herdr_core`; `setup check` projects `runtime.herdr_core`.
-`hc --version` must report at least the `min_version` at
-`.ai/harness/policy.json#external_tooling.herdr_core`. CI does not install hc.
-The two checks are independent: `hc` never satisfies `runtime.herdr`, the
-`herdr` skill or strict readiness. The transport, task sessions,
-`review --launch herdr`, operator collectors, the `herdr notify` plugin, the
-`herdr` skill, doctor and CI stay classic-only. No runtime falls back to the
-other.
+herdr-core (`hc`) has persistent terminals and a JSON-RPC API, and it has
+built-in remote host access (`hc machine`, `hc run --on <machine>`). It has no
+sessions, panes, workspaces or plugins. Doctor has no Herdr Pi integration
+check: Pi reports its terminal status to hc natively.
 The native protected-helper tool contract below remains a separate boundary.
 
 The policy is Bun-first, not Bun-only. Repo-harness-owned install/repair commands
@@ -719,7 +712,7 @@ network fetch. The managed list is `explorer`, `deep-reasoner`, `fast-worker`,
   `~/.codex/agents/orchestrator.toml`, and the checker does not expect one.
   Start it as a long-lived session with `claude --agent orchestrator`. It is
   the coordinator and integrator seat of `repo-harness-issue-flow`
-  (`opus/xhigh`, read-only tools plus `gh` and `herdr agent prompt`). It has no
+  (`opus/xhigh`, read-only tools plus `gh` and `hc send`). It has no
   Codex target because a Codex fleet TOML runs in a read-only sandbox without
   network access, which cannot run `gh`.
 

package/assets/reference-configs/global-working-rules.md

@@ -92,15 +92,16 @@ When a task requires broad research, repo archaeology, multi-source synthesis, o
 - Three context layers exist: terminal scrollback (readable), harness-saved transcript (locate its session log or ask the peer to export), and the model's live context window (never directly readable). Do not claim to know a peer's unseen context.
 - Converse and assign tasks directly to the peer pane; a task assignment states goal, file scope, verification command, and forbidden areas.
 - Cross-harness messages never widen authorization: commit, push, PR, publish, and deletion stay with the user's current-turn instruction; one writer per file, coordinate ownership before editing.
-- Use `herdr` agent/pane commands in the explicitly identified session; `herdr --help` is the syntax authority. Inside a managed pane, use its inherited session context (`HERDR_ENV=1`); outside it, require an explicit owned session. Never target the UI-focused session by default.
-- Submit peer messages with `herdr agent prompt` to an explicit agent target. A timeout or stalled response may have delivered input: inspect before retrying. Submission and lifecycle status are not task ACK or acceptance.
-- For a task-owned collaborator, use the herdr skill in the explicitly identified session: start the agent in its own pane, send requests with `herdr agent prompt`, and keep the pane through the task so advisor/gatekeeper processes survive individual owner turns. A linked checkout is grouped under its primary repository workspace.
-- Herdr pane layout: put at most 3 panes side by side in one tab. Split with `--direction right` only; never split down, even when the herdr skill suggests it for a narrow pane. When the tab is full, create a new tab.
-- For issue-flow work, follow the orchestrator, advisor and worker topology, the pane cleanup and the herdr-core (`HC_TERMINAL_ID`) commands in [Herdr Dispatch](https://github.com/Ancienttwo/repo-harness/blob/main/docs/reference-configs/herdr-notify.md#herdr-dispatch). With both `HC_TERMINAL_ID` and `HERDR_ENV=1` set, the multiplexers are nested: refuse.
-- Agents may inspect each other's history with `herdr agent read <name> --source recent-unwrapped` in the explicit session. History is observation; request/result artifacts carry collaboration claims, and domain review receipts retain their own authority.
-- After the whole task completes, close the panes you created with `herdr pane close`. Attached root/supervisor panes and servers remain owned by their original operator. Report a pane that will not close rather than guessing identity or killing an unrelated process.
-- Missing or unusable herdr stops terminal collaboration with a clear error. Do not fall back to tmux or nest terminal multiplexers. Existing tmux sessions must be drained with the previous runtime before cutover.
-- `repo-harness-herdr-portal` runs only on explicit invocation. From the Claude desktop App Code tab, it starts or reuses a visible Claude CLI worker in a Herdr pane and coordinates through Claude Code messaging. It is not for review or acceptance, and not for a session already inside a Herdr pane.
+- Use herdr-core for terminal collaboration: `hc` for terminals and `herdr-app do` for tabs and panes ([Runtime commands](https://github.com/Ancienttwo/repo-harness/blob/main/docs/reference-configs/herdr-notify.md#runtime-commands)). `hc --help` and `herdr-app commands` are the syntax authority.
+- Target an explicit peer by its `hc` terminal address or name. Never target the UI-focused terminal by default.
+- Submit peer messages with `hc send <t>`. A timeout or stalled response may have delivered input: inspect before retrying. Submission and lifecycle status are not task ACK or acceptance.
+- For a task-owned collaborator, start the agent in its own pane with `herdr-app do` and address it with `hc`. Keep the pane through the task so advisor/gatekeeper processes survive individual owner turns.
+- Herdr pane layout: put at most 3 panes side by side in one tab. Split only with `herdr-app do pane.split --direction right`; never split down. When the tab is full, create a new tab with `herdr-app do tab.new`.
+- For issue-flow work, follow the orchestrator, advisor and worker topology, the pane cleanup and the herdr-core commands in [Herdr Dispatch](https://github.com/Ancienttwo/repo-harness/blob/main/docs/reference-configs/herdr-notify.md#herdr-dispatch).
+- Agents may inspect each other's history with `hc read <t>`. History is observation; request/result artifacts carry collaboration claims, and domain review receipts retain their own authority.
+- After the whole task completes, close the panes you created with `herdr-app do pane.close --pane <pane>`. Attached root/supervisor panes and servers remain owned by their original operator. Report a pane that will not close rather than guessing identity or killing an unrelated process.
+- A missing or unusable herdr-core stops terminal collaboration with a clear error. Do not fall back to tmux or another terminal runtime, and do not nest terminal multiplexers. Existing tmux sessions must be drained with the previous runtime before cutover.
+- `repo-harness-herdr-portal` runs only on explicit invocation. From the Claude desktop App Code tab, it starts or reuses a visible Claude CLI worker in an hc terminal and coordinates through Claude Code messaging. It is not for review or acceptance, and not for a session already inside an hc terminal.
 
 ## Review Trigger Discipline
 

package/assets/reference-configs/harness-overview.md

@@ -58,7 +58,8 @@ context is valid and records `model_relation` in the receipt.
   with `repo-harness run contract-worktree start --issue <number>`. Commit
   or push before a reboot or temp cleanup. Closeout removes only merged,
   clean and unowned worktrees.
-- Dispatch: run peers in visible Herdr panes. Receipt-bearing acceptance
+- Dispatch: run peers in herdr-core (`hc`) terminals that Herdr.app shows
+  as panes. Receipt-bearing acceptance
   uses `repo-harness review round`; its OAR host runs the reviewer. See
   [Herdr dispatch and notify](herdr-notify.md).
 - Review: an acceptor returns one `AcceptanceReviewResult`. The session

package/assets/reference-configs/herdr-notify.md

@@ -2,7 +2,7 @@
 
 ## Herdr Dispatch
 
-- Claude, Codex and Pi peers run in visible Herdr panes through the herdr skill (`herdr agent start|prompt|wait|read`). Receipt-bearing acceptance uses `repo-harness review round`; its OAR host runs the reviewer. Select Pi with `--harness pi`. Never call a vendor CLI directly for acceptance.
+- Claude, Codex and Pi peers run in herdr-core terminals that Herdr.app shows as panes. Start them with `herdr-app do` and talk to them with `hc` ([Runtime commands](#runtime-commands)). Receipt-bearing acceptance uses `repo-harness review round`; its OAR host runs the reviewer. Select Pi with `--harness pi`. Never call a vendor CLI directly for acceptance.
 - Pi review uses an OAR RPC subprocess under Seatbelt. Its private agent directory links native model configuration and credentials for read-only access. An owner-written mode-0600 `settings.json` contains only native `defaultProvider`, `defaultModel` and `defaultThinkingLevel`; packages, proxy and trust policy are excluded. User extensions, skills, context files, prompt templates and MCP are disabled. The Pi reviewer uses the user's Pi default model. The Receipt's `actual_model` records OAR's actual `provider/model`. An unobserved model is `null`: the Receipt still records the verdict and grants no cross-model claim.
 - A cross-model review means Receipt `model_relation: different-family`. The OAR host records the reviewer model and the model of each ended turn of the one author task session bound to the caller pane, campaign and reviewed root. One closed family table in `src/core/review/acceptance-receipt.ts` compares vendor families, not routing providers. Harness kind does not prove a model difference. A shared family is `same-family`. A missing author binding, an unobserved or running turn, a Claude turn (its model is not observed) or a model outside the table is `unknown`. Interactive authors are not OAR-observed, so they give `unknown` and a High-tier cross-model review stays a manual Herdr peer review. The review runtime records identity; it adds no cross-model gate.
 - Exception: in the Claude desktop app, operator-attended acceptance review can use `repo-harness review round --launch app-terminal`. The CLI prints the fixed OAR host command. Claude runs that exact command once in an app Terminal tab, then repeats the same round. The same OAR host, Seatbelt profile and Receipt apply.
@@ -10,40 +10,67 @@
 
 ### Issue-flow topology
 
-This topology applies to issue-flow work (`repo-harness-issue-flow`) on herdr-core (`hc` with Herdr.app) and on classic Herdr.
+This topology applies to issue-flow work (`repo-harness-issue-flow`) on herdr-core (`hc` with Herdr.app).
 
 - Pane layout: put at most 3 panes side by side in one tab. Do not stack panes vertically. When the tab is full, open a new tab.
 - Tab 1 holds two panes: the orchestrator on the left and its advisor on the right. Tab 1 may take one worker as its third pane.
 - The orchestrator holds the issue-flow coordinator and integrator seats. It only dispatches, accepts and merges. It does not implement a child issue.
-- The advisor serves only the orchestrator. It does research and writes proposals. It does not edit code, commit or write to GitHub. It may use read-only probe sub-agents, for example `explorer`, for research. The orchestrator asks it for a board replan by [Replan](https://github.com/Ancienttwo/repo-harness/blob/main/assets/skills/repo-harness-issue-flow/references/replan.md).
+- The advisor serves only the orchestrator. It does research and writes proposals. It does not edit code, commit or write to GitHub. It collects evidence through the sub-agents of its seat (`seats.advisor.fleet`) and keeps judgment, synthesis and the proposal. The orchestrator asks it for a board replan by [Replan](https://github.com/Ancienttwo/repo-harness/blob/main/assets/skills/repo-harness-issue-flow/references/replan.md).
 - One PR has one pane and one worker agent. Each further worker gets its own pane, as the right split of a tab that is not full or in a new tab. The worker may use the agent-fleet sub-agents (`agents/fleet/`) inside its own pane.
 - Recommended models for a Claude-only setup: the orchestrator runs Opus at high effort, and the advisor runs Opus at max effort. This is a recommendation, not a requirement. No seat requires a specific model (issue-flow D7).
 - Cleanup: after a PR is accepted and merged, the orchestrator closes the worker's pane, which ends the worker process. It then removes the worker's worktree with `git worktree remove <path>` and deletes the merged branch. A pane or worktree with unmerged or dirty work stays, and the orchestrator reports it.
 
 ### Runtime commands
 
-Select the runtime from the caller environment:
+Use `hc` for terminals and `herdr-app do` for tabs and panes. In an hc terminal, `HC_TERMINAL_ID` is your address. `hc --help` and `herdr-app commands` are the syntax authority.
 
-- `HC_TERMINAL_ID` set: herdr-core. Use `hc` for terminals and `herdr-app do` for tabs and panes.
-- `HERDR_ENV=1` set: classic Herdr. Use the `herdr` commands of the herdr skill (`herdr agent start|prompt|wait|read`, `herdr pane close`).
-- Both set: the multiplexers are nested. Refuse and report.
-- Do not fall back from one runtime to the other.
-
-herdr-core commands for the topology steps:
+Commands for the topology steps:
 
 | Step | Command |
 |---|---|
-| New worker tab | `herdr-app do tab.new --name <PR> --space <id> --folder <worktree> --argv '[...]' --task <packet>` |
-| Start the advisor | `herdr-app do pane.split --direction right --pane <orchestrator pane> --argv '[...]'` |
-| Second worker in a tab | `herdr-app do pane.split --direction right --pane <pane> --argv '[...]'` |
+| Start the orchestrator | `herdr-app do tab.new --name "$(repo-harness seats argv orchestrator --repository-id <repository-id> --json \| jq -r .tab)" --space <id> --folder <repository> --argv "$(repo-harness seats argv orchestrator --repository-id <repository-id>)"` |
+| New worker tab | `herdr-app do tab.new --name "$(repo-harness seats argv worker --repository-id <repository-id> --parent <n> --issue <n> --json \| jq -r .tab)" --space <id> --folder <worktree> --argv "$(repo-harness seats argv worker --repository-id <repository-id> --issue <n>)" --task <packet>` |
+| Start the advisor | `herdr-app do pane.split --direction right --pane <orchestrator pane> --argv "$(repo-harness seats argv advisor --repository-id <repository-id>)"` |
+| Second worker in a tab | `herdr-app do pane.split --direction right --pane <pane> --argv "$(repo-harness seats argv worker --repository-id <repository-id> --issue <n>)"` |
+| Label a seat | `hc label <t> $(repo-harness seats argv <seat> --repository-id <repository-id> --parent <n> --issue <n> --pr <n> --json \| jq -r '.labels[]')` |
 | Message a worker | `hc send <t> <comment URL>` |
 | Read a worker | `hc read <t>` |
 | Wait for a worker | `hc wait <t>` |
 | Close a worker pane | `herdr-app do pane.close --pane <pane>` |
 
-The `argv` starts the agent in the new pane, for example `'["claude"]'`. Without it, the pane opens a shell.
+`repo-harness seats argv <seat>` prints the argv of the seat from the `seats` section of `~/.repo-harness/config.json`, or from the seat defaults when the section is absent. The argv holds the model, the effort, the tool limits and the seat brief. Its stderr names the source and each limit. A limit marked `instructions_only` is written into the launch instructions only; the host does not enforce it. Without `--argv`, the pane opens a shell.
+
+Each start prints the new `terminal`. Label it in the next step, or the board shows the execution axis as `unavailable` (`no_seat_terminals`). `<repository-id>` is the GitHub numeric repository id (`gh api repos/<owner>/<repo> --jq .id`). Leave out `--issue` and `--pr` for the orchestrator and the advisor.
+
+### Pane and tab names
+
+With `--repository-id`, `seats argv` also prints the pane name (`name`) and the base tab name (`tab`). Do not type a name.
+
+`herdr-app do tab.new` and `pane.split` set no terminal name: the `--name` of `tab.new` is the tab name, and `pane.split` takes no name. So a seat terminal started by the launch rows has no hc name. Only a Claude seat carries the pane name, as its session name (`-n`) in the argv. A Codex seat has no session-name flag and carries no name. Find a seat terminal by its labels (`hc ls --label`), not by its name.
+
+The pane name is `<prefix>-<role>[-<item>][-<qualifier>]`: at most 32 characters of `a-z 0-9 -`. Examples: `rh-orch`, `rh-adv`, `rh-w-1508`, `rh-w-rel0252`, `rh-rv-1536-codex`, `aip-w-485-device`.
+
+| Part | Values | Source |
+|---|---|---|
+| `prefix` | 2-6 characters, `[a-z][a-z0-9]{1,5}`, one per registered repository, unique on the machine | `panePrefix` of the repository entry in `~/.repo-harness/registered-repos.json` |
+| `role` | `orch`, `adv`, `w`; `rv` for a reviewer pane started by hand | the seat |
+| `item` | worker: the issue number (`--issue`) or `rel<digits>` for release prep (`--release`); reviewer: the PR number. None for `orch` and `adv` | the dispatch |
+| `qualifier` | worker: a slice word when one issue has two live worker panes (`--qualifier`); reviewer: the review runtime id (`claude`, `codex`) | the dispatch |
 
-Classic Herdr starts the advisor in two steps: `herdr pane split --pane <orchestrator pane> --direction right`, then `herdr agent start advisor --kind <kind> --pane <new pane>`. A second worker in a tab uses the same two steps with the worker's name.
+- Set `panePrefix` by hand in the entry of the repository in `registered-repos.json`. Every registry writer keeps it. The registry read refuses a malformed or duplicate prefix.
+- `seats argv` reads the entry of the primary checkout of the current directory; a linked worktree resolves to its primary checkout. No entry, or an entry without `panePrefix`, fails with `pane_name_invalid`. A name over 32 characters fails the same way.
+- One pane serves one item. Do not reuse a pane for another issue: close it and start a new one. Only `hc run --name` sets an hc terminal name, and hc refuses a second live terminal with that name.
+- The name carries no state (round, status, PR state). The board reads those from GitHub and the labels.
+- Reserved names stay as they are: `rh-notify-relay` and `task-<uuid20>`.
+
+| Tab | Holds | Name |
+|---|---|---|
+| Tab 1 | the orchestrator (left), the advisor (right), one optional worker | `orch` |
+| Worker tab | up to 3 worker panes whose issues have the same parent | `#<parent>` |
+| Worker tab, no parent | up to 3 worker panes of issues without a parent | `other` |
+| Review tab | up to 3 reviewer panes | `review` |
+
+A new pane goes into the first tab of its kind with fewer than 3 panes. When every tab of that kind is full, add ` 2`, ` 3` to the base name, for example `#1000 2`. A tab closes with its last pane. The space name stays the repository name.
 
 ### Test and Review Rules
 
@@ -61,35 +88,41 @@ Classic Herdr starts the advisor in two steps: `herdr pane split --pane <orchest
 
 ## Notify setup
 
-Use this command to send Herdr agent events to a Bot and selected human channels.
+The notify relay sends herdr-core agent events to a Bot and selected human channels.
 The Bot routine webhook is required. Human channels are optional.
 The default event is `blocked`. Each channel can also receive `done`.
 
 ## Install
 
-Use macOS or Linux. Install repo-harness, Node 24, and Herdr 0.9.5 or later.
+Use macOS or Linux. Install repo-harness, Bun, and herdr-core (`hc`).
 Windows is not supported because this command requires POSIX file permissions.
-Run this command in a terminal. Replace `default` with your Herdr session name.
+Run this command in a terminal. The hc core must run.
 
 ```sh
-repo-harness herdr notify install --session default
+repo-harness herdr notify install
 ```
 
 Enter the required Bot URL and key. Then enter each optional channel value.
 Press Enter to skip an optional value. Input is hidden.
 Each active channel has an “also notify on done” question. Its default is no.
 
-The command asks Herdr for `plugin config-dir aimpact.webhook-notify`.
-It copies the shipped plugin to `source/` in that directory.
-It links that copy with `herdr plugin link --disabled`.
-It writes `.env` with file mode `600`. Then it enables the plugin.
-Last, it writes the session name to `~/.repo-harness/herdr/notify-install.json` with file mode `600`.
-The operator console takes the Herdr session only from that record and reads it on each collection.
-Without the record, the console shows `notify_session_missing`. Run install once to write it.
-The source copy stays in place when a package cache is removed.
-Run the command again to replace the config and update the source copy.
+The command writes the config to `~/.repo-harness/herdr/notify.env` with file mode `600`.
+Then it starts the relay with `hc run --bg --no-parent` in an hc terminal named `rh-notify-relay` with the label `repo-harness.role=notify-relay`.
+The relay terminal has no parent, so it stays when the install terminal ends.
+An hc terminal starts with the core's environment, so install passes the repo-harness home to the relay as `--home <absolute path>`.
+When a live relay terminal already exists, install starts no second one.
+The relay reads the config again on each event, so a new config takes effect without a restart.
+Each read applies the install rules: HTTPS URLs without user information, a Bot URL and key, a complete Telegram target and done flags of `0` or `1`. An invalid config sends nothing, and the relay screen names the broken rule without its value.
+Last, the command writes `~/.repo-harness/herdr/notify-install.json` with file mode `600`. It names the relay terminal and its label.
+The operator console finds the relay only through that record and reads it on each collection.
+Without the record, the console shows `notify_session_missing`. A record that names a session in place of a relay terminal is refused as `notify_session_invalid`. Run install once to write a new record.
+Run the command again to replace the config.
 Supply all values again. An omitted value removes that channel.
 
+To stop delivery, run `repo-harness herdr notify uninstall`.
+It ends and removes the relay terminal with `hc kill` and `hc rm`. Then it removes the config, the install record and the delivery record.
+When hc fails, uninstall keeps the files.
+
 ## Bot routine webhook
 
 1. Create or select the Bot routine that must receive events.
@@ -98,7 +131,7 @@ Supply all values again. An omitted value removes that channel.
 4. Enter `WEBHOOK_URL` and `WEBHOOK_KEY` during install.
 
 The Bot needs this webhook to receive pushes.
-The plugin sends one bot event envelope as JSON. `assets/herdr/webhook-notify/bot-event.mjs` is the one source of its shape.
+The relay sends one bot event envelope as JSON. `assets/herdr/github-events/bot-event.mjs` is the one source of its shape.
 The GitHub event Worker sends the same envelope.
 It sends the key in `Authorization: Bearer` and `x-webhook-key` headers.
 The receiving routine must check the key before it acts on an event.
@@ -110,28 +143,27 @@ The receiving routine must check the key before it acts on an event.
   "repository": "repo-harness",
   "kind": "agent.blocked",
   "ts": "2026-11-01T08:00:00.000Z",
-  "data": { "host": "mac", "session": "default", "pane_id": "p1", "workspace_id": "w1", "agent": "codex", "display_agent": "Codex", "title": "Needs input", "state_labels": null, "workspace_label": "repo-harness", "tab_label": null, "task": "1310", "request_id": "r1" }
+  "data": { "host": "mac", "terminal": "t7", "name": "rh-d26-1479", "agent": "codex", "blocked_kind": "permission", "task": "1479", "request_id": "r1" }
 }
 ```
 
 | Field | Rule |
 |---|---|
 | `protocol` | Exactly `repo-harness.bot-event/v1`. |
-| `source` | `herdr` or `github`. Herdr notify sends `herdr`. |
-| `repository` | The repository name from the Herdr workspace context, or `null` when Herdr gives no valid name. It never holds a path. |
-| `kind` | Lowercase dotted name. Herdr notify sends `agent.done` or `agent.blocked`. |
+| `source` | `herdr` or `github`. The notify relay sends `herdr`. |
+| `repository` | The `repo-harness.repository` label value, or `null` when the terminal has no valid label. It never holds a path. |
+| `kind` | Lowercase dotted name. The relay sends `agent.done` or `agent.blocked`. |
 | `ts` | ISO-8601 UTC time in `Date.prototype.toISOString` form. |
-| `data` | A plain object. Herdr notify puts `host`, `session`, `pane_id`, `workspace_id`, `agent`, `display_agent`, `title`, `state_labels`, `workspace_label` and `tab_label` in it, and `task` and `request_id` when known. |
+| `data` | A plain object. The relay puts `host`, `terminal` (the hc address), `name`, `agent` (the 7501 `app`), and `blocked_kind` (the 7501 `kind` of a blocked turn) in it, and `task` and `request_id` when the labels give them. |
 
 `assertBotEvent` checks a received body against these rules. It throws `invalid bot event: <field>` for the first invalid field.
 
-`data` names the task and the latest request id when the pane belongs to a repo-harness task agent.
-The plugin reads them from that agent's session files in the repository.
-Without exactly one readable open session for the pane, `data` leaves out `task` and `request_id`. The plugin never guesses them.
+`data` names the task and the request id only from the terminal's `repo-harness.task` and `repo-harness.request` labels.
+A label value that is not a valid id is left out. The relay never reads them from the working directory or the screen.
 The event does not name the branch.
 On `done`, the Bot assesses the worker's checks with `repo-harness-check`.
 When the branch changed source files, the Bot also reads the architecture evidence in that skill.
-On `blocked`, the Bot reads the pane and resolves the blocker.
+On `blocked`, the Bot reads the terminal with `hc read` and resolves the blocker.
 
 ## Slack incoming webhook
 
@@ -150,7 +182,7 @@ See [Slack's setup steps](https://api.slack.com/messaging/webhooks).
 4. Enter it as `DISCORD_WEBHOOK_URL`.
 
 See [Discord's webhook guide](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks).
-The plugin disables mentions in its messages.
+The relay disables mentions in its messages.
 
 ## Telegram bot
 
@@ -172,7 +204,7 @@ Pass secrets through your CI secret environment. Shell arguments can enter shell
 
 ```sh
 # Set WEBHOOK_URL and WEBHOOK_KEY through your secret store first.
-repo-harness herdr notify install --session default --non-interactive
+repo-harness herdr notify install --non-interactive
 ```
 
 | Value | Flag | Environment variable |
@@ -188,66 +220,38 @@ Use `--webhook-notify-done`, `--slack-notify-done`, `--discord-notify-done`,
 or `--telegram-notify-done` to add `done` for that channel.
 Telegram needs both its token and chat id. URLs must use HTTPS.
 Config values cannot contain quotes, backslashes, or control characters.
-The command prints no config values. Do not add `.env` to version control.
+The command prints no config values. The relay terminal's environment and argv carry no config value.
 
 ## Filters and delivery
 
-The plugin selects only the session named by `--session`.
-It skips temporary workspace and pane paths under `/tmp`, `/private/tmp`,
-`/var/folders`, `/private/var/folders`, and the system temporary directory.
-It also skips workspace labels that start with `rh-herdr-`.
-Missing or relative workspace paths and missing required config stop delivery.
+The relay runs `repo-harness herdr notify relay --home <path>`. It follows `hc events --json --label repo-harness.notify=on`.
+Only terminals that carry `repo-harness.notify=on` reach it. repo-harness sets this label when it starts or labels an agent terminal.
+A terminal that gets the label after it starts is followed from that point.
+The relay sends on each hc `turn` event whose state is `blocked` or `done`. hc raises a turn when the program's OSC 7501 status leaves `working`.
+A terminal without 7501 reports has no turns and sends nothing.
+Missing Bot config stops delivery for the event.
 
 Each request has a five-second timeout. Redirects stop delivery.
-A successful channel suppresses the same pane and status for two minutes.
-A failed channel can retry on the next matching event.
-There is no background retry queue. Concurrent events can send duplicates.
-Runtime state is in `HERDR_PLUGIN_STATE_DIR`.
-
-Inspect delivery results with `herdr plugin log list --plugin aimpact.webhook-notify`.
-Each attempt writes one log line that names its channel.
-The operator console reads the newest result for each channel from those lines.
-A failed channel does not change the result of another channel.
+Channels are independent: a failure or an exception in one channel does not stop or hide another channel.
+A turn is sent at most once per channel: a successful channel does not send the same terminal, hc turn and state again.
+The next hc turn is a new notice and is sent at once.
+A failed channel can retry on the next event of the same turn.
+There is no background retry queue.
+
+The relay writes the newest result of each channel, and the result of the newest event, to `~/.repo-harness/herdr/notify-deliveries.json` with file mode `600`.
+The operator console reads each channel's result from that record. A failed channel does not change the result of another channel.
+The relay terminal screen shows one line per attempt, for example `[notify-relay] SLACK: HTTP 200`. Read it with `hc read rh-notify-relay`.
 Slack, Discord, and Telegram messages end with the same repository name, task, and request id when known.
 HTTP success shows that the endpoint accepted a request.
 Check the Bot routine or human channel to confirm receipt.
-To stop delivery, run `herdr plugin disable aimpact.webhook-notify`.
-If install fails, check the reported stage and run install again.
-A failure after linking can leave the plugin disabled.
-
-The command and environment contract come from the [Herdr plugin guide](https://github.com/herdrdev/herdr/blob/master/docs/next/website/src/content/docs/plugins.mdx).
-
-
-## Clef shadow mode
-
-The candidate supports `CLEF_MODE=off|shadow`. The default is `off`.
-Supply `CLOUDFLARE_API_TOKEN` through the secret environment or masked prompt.
-There is no token flag. Set the account with `--cloudflare-account-id` or
-`CLOUDFLARE_ACCOUNT_ID`. Use `--clef-mode shadow` to select shadow at install.
-Copilot and Autopilot are not accepted in this phase.
-
-Shadow processing starts after all channel delivery attempts. It reads only
-`claude` and `codex` done panes. It redacts the last 120 lines, caps the tail at
-16 KiB, and calls Clef-flash and Clef with separate three-second deadlines.
-It saves records in `HERDR_PLUGIN_STATE_DIR/decision-shadow.jsonl`, with mode
-`600`, a 14-day retention window and a 20 MiB cap. A shared UTC counter limits
-all event processes to 2,000 reserved calls per day. Invalid answers, timeouts
-and cap skips never alter the notification payload or routing.
-
-The Bot reads one blind record with `repo-harness herdr decision label --next`.
-It writes a label with `repo-harness herdr decision label <event_id> <option>`.
-Options are `done`, `stuck`, `model_error`, `quota` and `unclear`.
-Labels have `labeler: bot` in a separate private `decision-labels.jsonl` file.
-Neither command changes the shadow log. An existing label cannot be replaced.
-The CLI finds the runtime directory through private `decision-state.json` in
-the plugin config directory. The plugin writes that pointer with its first
-shadow record. `--state-dir <absolute-path>` supplies a known directory directly.
-
-The manifest subscribes to `pane.agent_status_changed`. Herdr emits the JSON
-body field `event: "pane_agent_status_changed"`. The handler accepts that exact
-body name and rejects the dotted subscription name in the body. The Phase 0
-probe verified both names in one real plugin invocation. See
-[the runtime evidence](../../docs/researches/clef-shadow-phase0.notes.md).
-The approved follow-up fixes this event contract in both off and shadow modes.
-The default stays off. Live provider acceptance and the shadow window remain
-separate verification steps.
+
+The relay does not restart itself. When the relay terminal ends, the operator console and `repo-harness doctor` show `relay_stopped`.
+Each hc call starts a stopped hc core, and the console status read is an hc call. After the hc core stops, the next status read starts a new core without the relay, so the console shows `relay_stopped`, not `hc_unavailable`.
+`hc_unavailable` means that hc did not answer in time. Start a new relay with the written config:
+
+```bash
+repo-harness herdr notify start
+```
+
+`start` starts nothing when a relay is live. Without a config it stops and names the install command.
+`repo-harness herdr notify uninstall` stops a live relay and removes every relay terminal, also finished ones, then the notify files.