repo-harness 0.25.0 → 0.25.1

package/README.md

@@ -145,9 +145,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 +155,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 +171,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 +213,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 +233,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 +260,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 +394,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 +456,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 +467,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 +502,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 +530,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 |
@@ -612,7 +596,6 @@ dependencies.
 | [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 |
 | [`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 +612,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.1`
+- Generated workflow stamp: `repo-harness@0.25.1+template@0.25.1`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/agents/fleet/orchestrator.md

@@ -1,7 +1,7 @@
 ---
 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"]
+tools: ["Read", "Grep", "Glob", "Bash", "TaskCreate", "TaskUpdate", "TaskList", "TaskGet"]
 model: opus
 effort: xhigh
 ---
@@ -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 `herdr agent prompt`. 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/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,92 @@
+// 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';
+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/herdr/webhook-notify/bot-event.mjs

@@ -0,0 +1,35 @@
+// The one bot event envelope. Herdr notify 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/webhook-notify/notify.mjs

@@ -1,6 +1,7 @@
 // Adapted from ~/herdr-plugins/webhook-notify. Config and identity come from Herdr.
 import { constants, closeSync, fchmodSync, fstatSync, mkdirSync, openSync, readSync, readdirSync, rmdirSync, existsSync, lstatSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { systemWorktreeRoot } from './worktree-location.mjs';
+import { NAME_PATTERN, botEvent } from './bot-event.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname, tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
@@ -63,7 +64,6 @@ function isTemporary(path, managedRoot) {
 }
 
 const ID_PATTERN = /^[\w.:@/-]{1,128}$/;
-const NAME_PATTERN = /^[\w.-]{1,128}$/;
 
 function readIdentityFile(path) {
   const stat = lstatSync(path);
@@ -75,12 +75,12 @@ function readIdentityFile(path) {
 // repo-harness task-agent session that owns this pane. A value that cannot be read, or
 // that two open sessions both claim, is left out: this notice never guesses a task.
 // Herdr's repo_key is a path. It only matches the session's repository_id here and never
-// leaves this function; the payload names the repository by Herdr's repo_name.
+// leaves this function; the bot event names the repository by Herdr's repo_name.
 function taskIdentity(data, context, session) {
   const key = context.worktree?.repo_key;
   const repoKey = typeof key === 'string' && key.length <= 1024 && !/[\u0000-\u001f]/.test(key) ? key : undefined;
   const name = context.worktree?.repo_name;
-  const identity = { ...(typeof name === 'string' && NAME_PATTERN.test(name) ? { repository: name } : {}) };
+  const identity = { repository: typeof name === 'string' && NAME_PATTERN.test(name) ? name : null };
   const root = context.worktree?.repo_root;
   if (typeof root !== 'string' || !isAbsolute(root)) return identity;
   try {
@@ -133,21 +133,22 @@ export async function notify(env = process.env, send = fetch, options = {}) {
   if (!config.WEBHOOK_URL || !config.WEBHOOK_KEY) throw new Error('Bot webhook config is missing.');
 
   const now = Date.now();
-  const payload = {
-    source: 'herdr', host: hostname(), session: config.NOTIFY_SESSION,
-    pane_id: data.pane_id, workspace_id: data.workspace_id, agent_status: data.agent_status,
+  const { repository, ...task } = taskIdentity(data, context, config.NOTIFY_SESSION);
+  const fields = {
+    host: hostname(), session: config.NOTIFY_SESSION, pane_id: data.pane_id, workspace_id: data.workspace_id,
     agent: data.agent ?? null, display_agent: data.display_agent ?? null, title: data.title ?? null,
     state_labels: data.state_labels ?? null, workspace_label: context.workspace_label ?? null,
-    tab_label: context.tab_label ?? null, ...taskIdentity(data, context, config.NOTIFY_SESSION), ts: new Date(now).toISOString(),
+    tab_label: context.tab_label ?? null, ...task,
   };
-  const trace = [payload.repository && `repo ${payload.repository}`, payload.task && `task ${payload.task}`,
-    payload.request_id && `request ${payload.request_id}`].filter(Boolean).join(' · ');
-  const where = [payload.workspace_label, payload.tab_label].filter(Boolean).join(' / ') || payload.workspace_id;
-  const text = `Herdr ${payload.agent_status}: ${payload.display_agent || payload.agent || 'agent'} @ ${where}` +
-    (payload.title ? `\n${payload.title}` : '') + `\npane ${payload.pane_id} · ${payload.host}` +
+  const envelope = botEvent({ source: 'herdr', repository, kind: `agent.${data.agent_status}`, ts: new Date(now).toISOString(), data: fields });
+  const trace = [repository && `repo ${repository}`, fields.task && `task ${fields.task}`,
+    fields.request_id && `request ${fields.request_id}`].filter(Boolean).join(' · ');
+  const where = [fields.workspace_label, fields.tab_label].filter(Boolean).join(' / ') || fields.workspace_id;
+  const text = `Herdr ${data.agent_status}: ${fields.display_agent || fields.agent || 'agent'} @ ${where}` +
+    (fields.title ? `\n${fields.title}` : '') + `\npane ${fields.pane_id} · ${fields.host}` +
     (trace ? `\n${trace}` : '');
   const targets = [
-    { channel: 'WEBHOOK', url: config.WEBHOOK_URL, body: payload,
+    { channel: 'WEBHOOK', url: config.WEBHOOK_URL, body: envelope,
       headers: { authorization: `Bearer ${config.WEBHOOK_KEY}`, 'x-webhook-key': config.WEBHOOK_KEY } },
     { channel: 'SLACK', url: config.SLACK_WEBHOOK_URL,
       body: { text: text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;') } },

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.
@@ -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
@@ -388,11 +375,12 @@ 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 |
 | `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
@@ -420,9 +408,20 @@ 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`.
 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`) 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.
 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 +675,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

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

@@ -96,6 +96,7 @@ When a task requires broad research, repo archaeology, multi-source synthesis, o
 - 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.

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

@@ -64,7 +64,8 @@ context is valid and records `model_relation` in the receipt.
 - Review: an acceptor returns one `AcceptanceReviewResult`. The session
   that runs the round publishes it with
   `repo-harness review publish --pr <n> --receipt <path>`. The merge
-  executor refuses an unresolved review thread.
+  executor refuses an unresolved review thread that a person started. A
+  thread that a review bot (a GitHub App account) started is advisory.
 - Merge: `repo-harness publication merge` runs only when
   `publication.acceptance_merge` is `on` on the PR base. Otherwise the
   owner merges.
@@ -78,7 +79,8 @@ context is valid and records `model_relation` in the receipt.
 ## Boundaries
 
 - Main merge requires current-task authorization, passing checks on the
-  exact head, no unresolved review threads and a current base.
+  exact head, no unresolved review threads that a person started and a
+  current base. Review bot threads are advisory.
 - Delete automatically only merged, clean, unowned worktrees and branches.
   Ask the user for every other deletion.
 - Credentials, permissions, sandbox grants and confirmation bypass need