repo-harness 0.25.0 → 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).
 
@@ -145,9 +146,8 @@ bun test
 
 ### Success looks like this
 
-Init writes repo-local files and two files under `HOME`: the repo registry
-entry and, when verification runs, the global Codex handoff packet under
-`~/.codex/handoffs/`. It writes no install-managed host files. When the
+Init writes repo-local files and one file under `HOME`: the repo registry
+entry. It writes no install-managed host files. When the
 required Herdr skill or the architecture projection preference is missing, init
 reports a skipped step that names `repo-harness update`. repo-harness supplies tools and evidence; the Bot
 decides what to schedule.
@@ -156,8 +156,8 @@ Apply ends with `=== Migration Report ===`, naming where generated hook behavior
 comes from, the user-level `~/.claude/settings.json` and `~/.codex/hooks.json`
 adapter target, the repo-local surfaces created or refreshed, and an
 `--- External Tooling ---` readiness block. Stable intent then lives in
-`docs/spec.md` and `docs/prds/`, task state in the GitHub issue and PR,
-resume state in `.ai/harness/handoff/`. If the dry run looks wrong, stop and
+`docs/spec.md` and `docs/prds/`, task and resume state in the GitHub issue,
+its claim comments and the PR. If the dry run looks wrong, stop and
 read
 [`hook-operations.md`](docs/reference-configs/hook-operations.md) first.
 
@@ -172,8 +172,6 @@ repo-harness upgrade decide --keep <path> # record an operator decision for a re
 repo-harness upgrade --registered # preview project refresh for every registered repo; no writes
 repo-harness uninstall --dry-run # preview owned user configuration cleanup
 repo-harness uninstall           # remove owned configuration; preserve user changes/history
-repo-harness mcp uninstall --dry-run # preview independent MCP setup cleanup
-repo-harness mcp uninstall --services-stopped # after stopping all MCP HTTP services
 ```
 
 `update` and `setup check` print one leftover count. `update` does not apply
@@ -216,10 +214,9 @@ release line have no supported historical proof and remain report-only.
 ## Why repo-harness
 
 - **File-backed sessions, not chat memory.** Separate Claude and Codex sessions
-  stay coordinated through the repo. `SessionStart` injects the prior session's
-  resume packet, and `Stop` writes the handoff and resume views. A session can
-  end mid-task and the next one resumes the exact next step, blockers, and
-  changed files without re-deriving them.
+  stay coordinated through the repo and its GitHub issue and PR. A session can
+  end mid-task. The next one reads the issue, the latest claim status and the
+  PR, and resumes the exact next step without re-deriving it.
 - **Token-lean by design.** Instead of grep-and-read loops that re-scan the repo
   every session, the harness leans on a pre-built CodeGraph index for structural
   queries and on progressive context loading: a stable ~12KB root context plus
@@ -237,7 +234,6 @@ In an adopted repo, the surface area is intentionally small:
 | `docs/spec.md` and `docs/reference-configs/` | Shared standards and stable product intent that every agent session can read. |
 | `docs/prds/` | Product intent and optional design briefs. |
 | `tasks/lessons.md` | The one local lesson ledger. Task identity and history stay in the issue and PR. |
-| `.ai/harness/handoff/` | Session journal and resumable status, derived from the issue, PR and repository state instead of chat memory. |
 
 ## Task Authority
 
@@ -265,7 +261,7 @@ callers while the contract lifecycle is removed.
 | **Session handoff** | Record the issue, branch, evidence and next action so another agent can continue |
 | **Progressive context loading** | A ~12KB stable root context plus ~1KB capability contracts loaded only for the files actually being touched |
 | **CodeGraph integration** | Structural queries (callers, callees, definitions) answered from a pre-built index instead of repeated grep-and-read passes |
-| **MCP planner sidecar** | ChatGPT reads real repo state and writes PRD/Sprint/Goal artifacts; Codex executes them, with no default source-code write access |
+| **MCP planner sidecar** | A local MCP client reads real repo state over stdio and writes PRD artifacts, with no default source-code write access |
 | **Claude + Codex alignment** | One user-level adapter contract, one workflow contract, and one set of repo-local artifacts shared by both hosts |
 
 ## How It Works
@@ -399,7 +395,7 @@ A dedicated linked checkout hosts one fleet `deep-reasoner` task-agent in the ad
 
 ### Bot merge
 
-A local Herdr Bot merges through the MCP `merge_pull_request` tool of the `orchestrator` profile. A cloud-only Bot runs `repo-harness publication merge` in a sandbox that has repo-harness, a working `gh auth` and a checkout. Both use the same executor. It merges only when `publication.acceptance_merge` is `on` in the policy on the PR base, and it needs strict required checks and enforce_admins on the default branch. A Bot record does not grant merge permission. See [the control Bot boundary](docs/control-bot-boundary.md#bot-modes-and-merge).
+A local Herdr Bot runs `repo-harness publication merge` in its shell. A cloud-only Bot runs the same command in a sandbox that has repo-harness, a working `gh auth` and a checkout. It merges only when `publication.acceptance_merge` is `on` in the policy on the PR base, and it needs strict required checks and enforce_admins on the default branch. A Bot record does not grant merge permission. See [the control Bot boundary](docs/control-bot-boundary.md#bot-modes-and-merge).
 
 ## Hooks
 
@@ -461,7 +457,7 @@ Read committed architecture facts or export a module review prompt:
 
 ```bash
 repo-harness module list --json
-repo-harness module review-prompt capability.runtime-harness.engineer-bindings --json
+repo-harness module review-prompt capability.runtime-harness.task-agent-host --json
 ```
 
 The prompt uses HEAD content. It reports uncommitted paths and their content
@@ -472,29 +468,19 @@ shards arrive. Diff mode requires both `--base <rev>` and `--head <rev>`.
 
 ## MCP Connector
 
-As an optional sidecar, `repo-harness mcp` exposes workflow artifacts to MCP
-clients through the default `planner` profile. ChatGPT reads real repo state,
-writes PRDs under `docs/prds/`, and reads the linked GitHub issue — with no
-default source-code write access, arbitrary shell execution, or default runner. The task owner directs an explicitly addressed Herdr agent to execute the task goal.
+As an optional sidecar, `repo-harness mcp serve` exposes workflow artifacts to a
+local MCP client over stdio through the default `planner` profile or the
+`executor` profile. The client reads real repo state and writes PRDs under
+`docs/prds/`. It has no default source-code write access, no shell and no runner. The
+task owner directs an explicitly addressed Herdr agent to execute the task goal.
 
 ```bash
-repo-harness mcp setup chatgpt --repo .
-repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner
+repo-harness mcp serve --repo . --profile planner
+repo-harness mcp doctor --repo .
 ```
 
-Expose that local server through an HTTPS tunnel, register the `/mcp` URL, and
-the human workflow is:
-
-1. ChatGPT reads repo-harness workflow files through MCP.
-2. ChatGPT writes a PRD with `write_prd_from_idea`.
-3. ChatGPT lists existing PRDs under `docs/prds/` and reads the linked issue.
-4. The task owner orders GitHub issues through `repo-harness-issue-flow` and
-   sends the issue Goal to an explicitly addressed Herdr agent.
-
-General repo reader/writer tools, snapshot and index consistency, server
-profiles, and the opt-in dev runner:
-[`general-repo-mcp.md`](docs/reference-configs/general-repo-mcp.md). Direct-coding
-profile: [`chatgpt-coding-mcp.md`](docs/reference-configs/chatgpt-coding-mcp.md).
+General repo reader/writer tools, snapshot and index consistency, and server profiles:
+[`general-repo-mcp.md`](docs/reference-configs/general-repo-mcp.md).
 Index-stale, CodeGraph-down, and rollback operations:
 [`general-repo-mcp-codegraph.md`](deploy/runbooks/general-repo-mcp-codegraph.md).
 
@@ -517,7 +503,7 @@ Agents read source artifacts before derived summaries:
 | Current user prompt and referenced files | PR description |
 | `AGENTS.md` / `CLAUDE.md` | Changed files and diff |
 | The GitHub issue and PR | Verification Plan execution records and run trace |
-| Latest handoff in `.ai/harness/handoff/` | Residual risks and rollback |
+| Latest claim status comment on the issue | Residual risks and rollback |
 If it disagrees with the issue, PR, checks, or handoff, the source artifacts win.
 
 Runtime-heavy validators (Unity, browser E2E, mobile simulators, hardware rigs,
@@ -545,7 +531,6 @@ control context loading. They do not add a host permission boundary.
 | `repo-harness-ship` | Bot | Explicit publication and cleanup decisions |
 | `obsidian-memory` | Bot | Explicit memory recall or persistence |
 | `repo-harness-cross-review` | Bot | Generic review; direct advisory runtime retired |
-| `repo-harness-chatgpt` | Bot | Explicit integration mode and advisory decisions |
 | `repo-harness-setup` | Worker | Assigned install, migration, repair or scaffold |
 | `repo-harness-test` | Worker | Source tests and real fixtures |
 | `repo-harness-architecture` | Worker | Assigned model, projection or diagram work |
@@ -609,10 +594,9 @@ 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 |
-| [Oracle](https://github.com/steipete/oracle) by [Peter Steinberger](https://x.com/steipete) (`@steipete/oracle`, MIT) | Default GPT Pro / ChatGPT Web browser consult engine that the `chatgpt-browser` Oracle provider shells out to for `gptpro` consults | Externally-resolved binary (`--oracle-bin`, `REPO_HARNESS_ORACLE_BIN`, `node_modules/.bin`, or `PATH`); never auto-downloaded, and a missing binary is a hard `ORACLE_NOT_INSTALLED` failure |
 | 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 |
 
 ### GitHub Contributor Attribution
@@ -629,8 +613,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.25.0`
-- Generated workflow stamp: `repo-harness@0.25.0+template@0.25.0`
+- 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.
-tools: ["Read", "Grep", "Glob", "Bash"]
+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,8 +16,9 @@ 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` or the MCP tool `prompt_task_agent`. 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.
 
 You must not:
 - Edit product code, tests or configuration.

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/github-events/bot-event.mjs

@@ -0,0 +1,35 @@
+// 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}$/;
+
+const SOURCES = ['herdr', 'github'];
+const KIND_PATTERN = /^[a-z]+(\.[a-z_]+)+$/;
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isIsoTimestamp(value) {
+  return typeof value === 'string' && !Number.isNaN(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+
+export function assertBotEvent(value) {
+  const checks = [
+    ['protocol', value?.protocol === BOT_EVENT_PROTOCOL],
+    ['source', SOURCES.includes(value?.source)],
+    ['repository', value?.repository === null || (typeof value?.repository === 'string' && NAME_PATTERN.test(value.repository))],
+    ['kind', typeof value?.kind === 'string' && KIND_PATTERN.test(value.kind)],
+    ['ts', isIsoTimestamp(value?.ts)],
+    ['data', isPlainObject(value?.data)],
+  ];
+  const invalid = checks.find(([, valid]) => !valid);
+  if (invalid) throw new Error(`invalid bot event: ${invalid[0]}`);
+  return value;
+}
+
+export function botEvent({ source, repository, kind, ts, data }) {
+  return assertBotEvent({ protocol: BOT_EVENT_PROTOCOL, source, repository, kind, ts, data });
+}

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

@@ -0,0 +1,73 @@
+// GitHub event filter of the events Worker. The Worker entry can export only handlers (workerd),
+// so the rules live in this module.
+
+// The comment headers of assets/skills/repo-harness-issue-flow/references/templates.md.
+export const PROTOCOL_HEADERS = [
+  'repo-harness issue claim', 'repo-harness issue claim status', 'repo-harness boundary question',
+  'repo-harness scope change', 'repo-harness decision', 'repo-harness plan', 'repo-harness handoff',
+  'repo-harness acceptance claim', 'repo-harness acceptance record', 'repo-harness review reply',
+  'repo-harness unblocked', 'repo-harness integration status',
+];
+export const REQUIRED_CHECK = 'Required / CI';
+
+function pullRequest(payload) {
+  const pull = payload.pull_request;
+  return { number: pull.number, url: pull.html_url, head_sha: pull.head.sha };
+}
+
+const protocolHeader = (body) => {
+  const header = (body ?? '').split(/\r?\n/, 1)[0].trim();
+  return PROTOCOL_HEADERS.includes(header) ? header : null;
+};
+
+// One GitHub delivery gives one bot event or null. `debounce` names the PR whose later pushes replace this one.
+export function classify(name, payload, orchestratorLogin) {
+  const action = payload.action;
+  // GitHub logins are case-insensitive. The orchestrator must not wake itself with its own issues, comments or reviews.
+  const byOrchestrator = payload.sender?.login?.toLowerCase() === orchestratorLogin.toLowerCase();
+  switch (name) {
+    case 'issue_comment': {
+      const header = action === 'created' && !byOrchestrator ? protocolHeader(payload.comment.body) : null;
+      return header && { kind: 'issue.comment', data: { number: payload.issue.number, url: payload.comment.html_url, header } };
+    }
+    case 'issues':
+      if (action !== 'opened' || byOrchestrator) return null;
+      return { kind: payload.issue.title.startsWith('[CI repair]') ? 'issue.ci_repair' : 'issue.opened',
+        data: { number: payload.issue.number, url: payload.issue.html_url } };
+    case 'pull_request_review': {
+      const review = payload.review;
+      // GitHub wraps each single review comment and thread reply in an empty `commented` review; those arrive as review comments.
+      if (action !== 'submitted' || byOrchestrator || (review.state.toLowerCase() === 'commented' && !review.body)) return null;
+      return { kind: 'pr.review', data: { ...pullRequest(payload), url: review.html_url } };
+    }
+    case 'pull_request_review_comment': {
+      if (action !== 'created' || byOrchestrator) return null;
+      const url = payload.comment.html_url;
+      if (!payload.comment.in_reply_to_id) return { kind: 'pr.review_thread', data: { ...pullRequest(payload), url } };
+      // A reply belongs to an existing thread. Only a protocol reply, such as `review reply`, is a notice.
+      const header = protocolHeader(payload.comment.body);
+      return header && { kind: 'pr.review_reply', data: { ...pullRequest(payload), url, header } };
+    }
+    case 'pull_request':
+      if (action === 'closed') return { kind: payload.pull_request.merged ? 'pr.merged' : 'pr.closed', data: pullRequest(payload) };
+      if (action === 'synchronize') {
+        return { kind: 'pr.pushed', data: pullRequest(payload), debounce: `pr:${payload.repository.id}:${payload.pull_request.number}` };
+      }
+      return null;
+    case 'check_run': {
+      const run = payload.check_run;
+      // The job runs only for pull requests; other runs report it as skipped. The other jobs of a run are dropped.
+      if (action !== 'completed' || run.name !== REQUIRED_CHECK || run.conclusion === 'skipped') return null;
+      return { kind: 'ci.pr', data: { pull_requests: run.pull_requests.map((pull) => pull.number), url: run.html_url,
+        head_sha: run.head_sha, conclusion: run.conclusion } };
+    }
+    case 'workflow_run': {
+      const run = payload.workflow_run;
+      // `Required / CI` does not run on push. A cancelled run has no result.
+      if (action !== 'completed' || run.event !== 'push' || run.head_branch !== payload.repository.default_branch || run.conclusion === 'cancelled') return null;
+      return { kind: 'ci.main', data: { branch: run.head_branch, workflow: run.name, url: run.html_url, head_sha: run.head_sha, conclusion: run.conclusion } };
+    }
+    default:
+      return null;
+  }
+}

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

@@ -0,0 +1,91 @@
+// 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 wrangler bundles it.
+import { botEvent } from './bot-event.mjs';
+import { classify } from './filter.mjs';
+
+const DEBOUNCE_SECONDS = 60;
+const DELIVERY_TTL_SECONDS = 7 * 24 * 60 * 60;
+const MARK_TTL_SECONDS = 24 * 60 * 60;
+const MAX_BODY_BYTES = 1024 * 1024;
+const SEND_TIMEOUT_MS = 5_000;
+const DELIVERY_PATTERN = /^[\w-]{1,128}$/;
+const encoder = new TextEncoder();
+
+function hexBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < bytes.length; index++) bytes[index] = parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  return bytes;
+}
+
+async function signatureValid(secret, header, body) {
+  const match = /^sha256=([0-9a-f]{64})$/.exec(header ?? '');
+  if (!match) return false;
+  const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+  return crypto.subtle.verify('HMAC', key, hexBytes(match[1]), body);
+}
+
+async function sendToBot(env, event) {
+  const response = await fetch(env.BOT_WEBHOOK_URL, {
+    method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${env.BOT_WEBHOOK_KEY}`, 'x-webhook-key': env.BOT_WEBHOOK_KEY },
+    body: JSON.stringify(event),
+  });
+  if (!response.ok) throw new Error(`Bot webhook returned HTTP ${response.status}.`);
+}
+
+// KV is eventually consistent between locations. A stale read can repeat an event; it never drops one.
+const wasSent = async (env, delivery) => await env.EVENTS_STATE.get(`delivery:${delivery}`) !== null;
+
+async function deliver(env, { delivery, event, debounce, at }) {
+  if (await wasSent(env, delivery)) return 'duplicate';
+  if (debounce && Number(await env.EVENTS_STATE.get(debounce)) > at) return 'superseded';
+  await sendToBot(env, event);
+  // The Bot has the event. A failed mark write must not make the caller send it again.
+  try { await env.EVENTS_STATE.put(`delivery:${delivery}`, '1', { expirationTtl: DELIVERY_TTL_SECONDS }); }
+  catch { console.error(`Delivery ${delivery} was sent, but its dedupe mark was not written.`); }
+  return 'sent';
+}
+
+const reply = (status, text) => new Response(text, { status });
+
+export default {
+  async fetch(request, env) {
+    if (!env.GITHUB_WEBHOOK_SECRET || !env.BOT_WEBHOOK_URL || !env.BOT_WEBHOOK_KEY || !env.ORCHESTRATOR_LOGIN) return reply(500, 'Worker config is missing.');
+    if (request.method !== 'POST') return reply(405, 'POST only.');
+    const body = await request.arrayBuffer();
+    if (body.byteLength > MAX_BODY_BYTES) return reply(413, 'Payload is too large.');
+    if (!await signatureValid(env.GITHUB_WEBHOOK_SECRET, request.headers.get('x-hub-signature-256'), body)) return reply(401, 'Invalid signature.');
+    const delivery = request.headers.get('x-github-delivery') ?? '';
+    const name = request.headers.get('x-github-event') ?? '';
+    if (!DELIVERY_PATTERN.test(delivery) || !name) return reply(400, 'Missing GitHub delivery headers.');
+    let payload;
+    try { payload = JSON.parse(new TextDecoder().decode(body)); } catch { return reply(400, 'Invalid JSON.'); }
+    const match = classify(name, payload, env.ORCHESTRATOR_LOGIN);
+    if (!match) return reply(204, null);
+    const at = Date.now();
+    const event = botEvent({ source: 'github', repository: payload.repository.name, kind: match.kind, ts: new Date(at).toISOString(), data: match.data });
+    if (match.debounce) {
+      if (await wasSent(env, delivery)) return reply(200, 'duplicate');
+      // Each push moves the PR mark forward. The queued copy sends only when no later push arrived.
+      // Queue first: a failed mark write then repeats the older push instead of dropping this one.
+      await env.EVENTS_QUEUE.send({ delivery, at, event, debounce: match.debounce }, { delaySeconds: DEBOUNCE_SECONDS });
+      await env.EVENTS_STATE.put(match.debounce, String(at), { expirationTtl: MARK_TTL_SECONDS });
+      return reply(202, 'queued');
+    }
+    try {
+      return reply(200, await deliver(env, { delivery, at, event }));
+    } catch {
+      // GitHub records the failed delivery for a redelivery, and the queue retries it now.
+      await env.EVENTS_QUEUE.send({ delivery, at, event });
+      return reply(502, 'Bot delivery failed.');
+    }
+  },
+
+  async queue(batch, env) {
+    for (const message of batch.messages) {
+      try { await deliver(env, message.body); message.ack(); }
+      catch { message.retry(); }
+    }
+  },
+};

package/assets/herdr/github-events/wrangler.json

@@ -0,0 +1,11 @@
+{
+  "name": "repo-harness-github-events",
+  "main": "worker.mjs",
+  "compatibility_date": "2025-09-01",
+  "workers_dev": true,
+  "kv_namespaces": [{ "binding": "EVENTS_STATE" }],
+  "queues": {
+    "producers": [{ "binding": "EVENTS_QUEUE", "queue": "repo-harness-github-events" }],
+    "consumers": [{ "queue": "repo-harness-github-events", "max_retries": 10, "retry_delay": 60 }]
+  }
+}

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

@@ -9,7 +9,7 @@
 2. Open a branch; isolate a worktree when concurrent edits overlap. Preserve unrelated work.
 3. Make small, bounded commits. Ordinary tasks live in the PR description: goal, changes, verification, risk and rollback.
 4. Freeze the candidate and verify once: typecheck plus affected tests. Reviewers and closeout consume the same evidence. Reopen acceptance only for blocking defects or changed inputs that affect the result. Record non-blocking improvements separately; do not change the frozen candidate for them.
-5. A model may squash-merge into main only when the current task explicitly authorizes main publication, the branch contains the current main tip, the required checks pass on that exact head, and GitHub has no outstanding change requests or unresolved review threads. An explicit no-merge instruction always wins. The next merge does not wait for the main push CI of the previous merge. Pending main push CI is not an extra acceptance gate. Read its status before the next merge; when it fails, the next merge is the revert or the fix. Each PR still meets its own exact-head and current-main requirements. Record the GitHub merge SHA and parent SHA. Record `git revert --no-edit <squash-commit>`. Do not create rollback tags.
+5. A model may squash-merge into main only when the current task explicitly authorizes main publication, the branch contains the current main tip, the required checks pass on that exact head, and GitHub has no outstanding change requests or unresolved review threads that a person started. A thread that a review bot (a GitHub App account such as Codex or Copilot) started is advisory and does not block the merge. An explicit no-merge instruction always wins. The next merge does not wait for the main push CI of the previous merge. Pending main push CI is not an extra acceptance gate. Read its status before the next merge; when it fails, the next merge is the revert or the fix. Each PR still meets its own exact-head and current-main requirements. Record the GitHub merge SHA and parent SHA. Record `git revert --no-edit <squash-commit>`. Do not create rollback tags.
 6. Run the full suite daily, automatically open a repair task on failure, and produce the daily merge/check/rollback report. Run the [Lessons Retro](#lessons-retro) in the same nightly window.
 7. Use the [Report SOP](#report-sop) for formal progress, phase and final reports to the user, including the daily user summary. Raw automated CI reports are evidence inputs; they do not replace that summary and do not require this format.
 
@@ -93,7 +93,7 @@ An internal PR uses Daily Flow step 5 and the main-merge boundary in [Four opera
 An external PR never uses the internal flow. A worker produces the ready-for-GO bundle from `references/pr-verification.md`, whose hazard scan uses the [change hazard list](#change-hazards). The PR merges only after automated checks pass and the repository owner gives an explicit GO for the reviewed head SHA. Merge with `gh pr merge <pr> --squash --match-head-commit <reviewed-sha>`. A new head SHA needs a new bundle and a new GO.
 
 ## Four operation boundaries
-- Main merge requires explicit current-task authorization, current automated checks, no outstanding change requests or unresolved review threads, exact head/base and conflict safety.
+- Main merge requires explicit current-task authorization, current automated checks, no outstanding change requests or unresolved review threads that a person started, exact head/base and conflict safety.
 - Only merged, clean, inactive worktrees/branches may be deleted automatically; other deletion requires the user.
 - Credentials, permissions, sandbox/write grants and confirmation-bypass settings require user approval of the exact change.
 - Release and production effects require user approval of the exact artifact and operation.
@@ -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
@@ -138,6 +138,10 @@ The diff sets the tier. The author does not: a human change and a model change w
 
 Review follows the `repo-harness-issue-flow` skill, [references/acceptor.md](../../assets/skills/repo-harness-issue-flow/references/acceptor.md). The tier selects the depth: no independent review for Low, one fresh-context review for Medium, and the gatekeeper plus one cross-model review for High, one round each. The Acceptor SOP owns the round, findings and publish steps.
 
+Low accept-seat skip: a Low PR whose `Required / CI` is SUCCESS on the PR head and whose PR body holds the author verification evidence (the commands and their outcomes) takes no accept seat and no acceptance record. Do not dispatch a Codex, Herdr or OAR accept seat for it. `Required / CI` and that evidence are the proof surface. A Low PR that lacks either condition is not eligible to merge until both hold. Medium and High keep the full Acceptor SOP.
+
+Worked example (docs-only Low path): the PR edits `docs/bot-onboarding.md` only. The author runs one check command and records the command and its outcome (exit 0) in the PR body. `Required / CI` is SUCCESS on the PR head. The PR needs no reviewer, and it is eligible to merge with no accept seat and no acceptance record.
+
 Rules for every tier:
 - The reviewer reads the current diff only. A defect in code the diff did not touch is a non-blocking note; open an issue for it, do not add a finding.
 - From the second round, the reviewer reads only the hunks that changed after the previous round. The three-round limit stays.
@@ -145,6 +149,7 @@ Rules for every tier:
 - A low tier adds no review. A new test file or a rebase does not raise the tier.
 - Changing implementation and test assertions together does not raise the tier. Within the tier's existing review, check whether assertions preserve the intended behavior and whether removed or weakened coverage has a valid requirement-based reason. At Low, the author performs this check in self-review. Record the reason for each assertion change in the PR; never change assertions only to make a test pass. Do not dispatch a separate test-review gate.
 - A parent, coordinator or merge session reuses recorded acceptance when the reviewed diff, relevant base context, verification inputs and environment still match, and the review meets the current tier. The PR records the reviewed revision or diff, commands, results and finding dispositions. A change of session or reviewer is not a reason to repeat acceptance.
+- A batch integration PR (`repo-harness-issue-flow`, [references/orchestrator.md](../../assets/skills/repo-harness-issue-flow/references/orchestrator.md) §9.3) reuses the acceptance record of each member when every member merged without conflict and the batch adds no commit of its own. It needs no new review round. A Low member has no acceptance record to reuse. Required checks on the batch head still apply.
 - After a change, verify the affected behavior and review the changed hunks with their affected context. Retain valid evidence for unchanged scope; add only missing tier coverage. A rebase alone does not require a new full review, but changed base behavior or conflict resolution can invalidate affected evidence. Reuse never substitutes for required checks on the current head or the current-main merge requirement.
 - A downstream repository maps its own release surfaces, for example public API, wire format, DDL/SQL and permissions, to the High tier.
 

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

@@ -131,7 +131,7 @@ then `repo-harness uninstall --recover-interrupted` to apply it. This explicit
 recovery restores the recorded fragments even if they were edited after interruption;
 sibling fields remain. The target must include every affected host.
 
-Package-manager globals, the official Codex plugin, independent MCP setup/workspaces,
+Package-manager globals, the official Codex plugin, the MCP config,
 archives and runtime history remain. Repository unadoption and package removal are
 separate operations; this command does not enumerate other repositories or remove
 third-party packages. Remove the CLI package only after configuration cleanup.
@@ -308,31 +308,18 @@ updates skills.
 
 ### Waza
 
-Both hosts:
+Every host uses one command. The `codex` agent writes the staging copy in
+`~/.agents/skills`:
 
 ```bash
-bunx skills add tw93/Waza -g -a claude-code codex -s think hunt check health -y
+bunx skills add tw93/Waza -g -a codex -s think hunt check health -y
 ```
 
-Single host:
-
-```bash
-bunx skills add tw93/Waza -g -a claude-code -s think hunt check health -y
-```
+Then `repo-harness install` links the host skill roots to the staging copy.
 
-Replace `claude-code` with `codex` when installing for Codex only.
-
-After installing or updating through the skills CLI, verify Codex has its own
-runtime copy:
+Verify that the Codex skills and shared rules match the staging copy:
 
 ```bash
-for d in think hunt check health; do
-  rsync -a --delete ~/.agents/skills/$d/ ~/.codex/skills/$d/
-done
-mkdir -p ~/.codex/rules
-for f in anti-patterns.md chinese.md durable-context.md english.md; do
-  cp ~/.agents/rules/$f ~/.codex/rules/$f
-done
 for d in think hunt check health; do
   diff -qr ~/.agents/skills/$d ~/.codex/skills/$d
 done
@@ -387,42 +374,47 @@ 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) | 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 |
 | `npx` / `skills_cli` | external Skills CLI | Waza and Mermaid skill bootstrap/update commands |
-| `rsync` | platform filesystem | Waza staging-to-Codex sync and installed-copy runtime mirroring |
+| `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.
-Rebind endpoints explicitly as `herdr-cli-agent`; old adapter policy, capabilities
-and live session metadata are not translated. The self-host runtime remains off.
 No runtime or collaboration path automatically falls back to tmux.
+
+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
@@ -676,13 +668,7 @@ boundary for untrusted repositories.
 
 ```bash
 bunx skills update
-for d in think hunt check health; do
-  rsync -a --delete ~/.agents/skills/$d/ ~/.codex/skills/$d/
-done
-mkdir -p ~/.codex/rules
-for f in anti-patterns.md chinese.md durable-context.md english.md; do
-  cp ~/.agents/rules/$f ~/.codex/rules/$f
-done
+repo-harness install
 for d in think hunt check health; do
   diff -qr ~/.agents/skills/$d ~/.codex/skills/$d
 done
@@ -726,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`.