repo-harness 0.23.1 → 0.24.2

package/AGENTS.md

@@ -10,7 +10,7 @@
 - Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
 - Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Record authorized publication, the provider-confirmed merge SHA and parent SHA, `git revert <squash-commit>`, and the daily report. Do not create rollback tags.
 - Default worktrees are at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`). Commit or push before a reboot or a tmp cleanup.
-- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lease it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
+- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lock it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
 - Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
 - Select independent review by the diff's [Review by risk](docs/reference-configs/agentic-development-flow.md#review-by-risk) tier: none for low, one fresh-context review for medium, gatekeeper plus cross-model review for high; ordinary steps record diagnostics without approval loops.
 - When you delegate, investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They do not run build, typecheck or tests. They commit early in their own worktree and return early. In a shared checkout they do not commit; the parent commits. Evidence roles run the named check that is their task and do not commit. The parent agent owns task management, conflict resolution, build, typecheck, tests and integration. After integration, the parent removes each sub-agent worktree and branch whose commits are in the task branch and whose checkout is clean. It also removes the intermediate build output and temporary files that the work created. Other deletion still needs the user.
@@ -18,7 +18,7 @@
 - GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
 - When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
 - `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
-- When a branch changes a capability's responsibility, entrypoints, relations or flows, run `repo-harness architecture-projection check --json` before review and follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`).
+- When a branch changes a capability's responsibility, entrypoints, relations or flows, follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`). Handle architecture debt in the model and human prose. The archctx rolling writer publishes generated regions and the projection manifest; do not apply and commit them in a feature PR.
 - Preserve `agents/fleet/`, release checklists and downstream `assets/templates`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract.
 - `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
@@ -53,6 +53,8 @@
 - Isolate mutable HOME, repositories and process state; use real synchronization signals and preserve complete failure output.
 - Report failed, timed-out, incomplete or omitted coverage explicitly; do not manufacture receipts, waiver files or pre-fix logs.
 - Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description.
+- Before you write or change tests, load the `repo-harness-test` skill (`assets/skills/repo-harness-test/SKILL.md`).
+- When a local check and CI disagree, CI is the authority. Reproduce the failure with `bash scripts/check-ci.sh <lane>` before you change code; a global `repo-harness` or `repo-harness-hook` on `PATH` can hide a missing test setup.
 
 ## Handoff
 - Create a checkpoint only when context/session rollover or unresolved work needs it; ordinary completion stays in the PR description.
@@ -73,6 +75,9 @@
 - Prefer real companies, products, contracts, prices and user behavior as examples. Use a table for multi-object or multi-metric comparison. Split sections by question; drop introductions, transitions and summaries that exist only for completeness.
 - Paragraph deletion test: if removing a paragraph leaves the reader's understanding of facts, numbers, mechanism, cause, conditions and conclusion unchanged, remove it. Check first the paragraphs that start with "this shows", "note that", "therefore", "however" or "it must be stressed".
 
+## UI
+- Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.
+
 ## Codex
 - Own backend implementation and testing; Claude owns frontend implementation and interaction, and the parent coordinates scope and integration.
 - User-level `~/.codex/hooks.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Operator helpers run from the package through `repo-harness run <helper>`.

package/CLAUDE.md

@@ -10,7 +10,7 @@
 - Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
 - Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Record authorized publication, the provider-confirmed merge SHA and parent SHA, `git revert <squash-commit>`, and the daily report. Do not create rollback tags.
 - Default worktrees are at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`). Commit or push before a reboot or a tmp cleanup.
-- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lease it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
+- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lock it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
 - Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
 - Select independent review by the diff's [Review by risk](docs/reference-configs/agentic-development-flow.md#review-by-risk) tier: none for low, one fresh-context review for medium, gatekeeper plus cross-model review for high; ordinary steps record diagnostics without approval loops.
 - When you delegate, investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They do not run build, typecheck or tests. They commit early in their own worktree and return early. In a shared checkout they do not commit; the parent commits. Evidence roles run the named check that is their task and do not commit. The parent agent owns task management, conflict resolution, build, typecheck, tests and integration. After integration, the parent removes each sub-agent worktree and branch whose commits are in the task branch and whose checkout is clean. It also removes the intermediate build output and temporary files that the work created. Other deletion still needs the user.
@@ -18,7 +18,7 @@
 - GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
 - When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
 - `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
-- When a branch changes a capability's responsibility, entrypoints, relations or flows, run `repo-harness architecture-projection check --json` before review and follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`).
+- When a branch changes a capability's responsibility, entrypoints, relations or flows, follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`). Handle architecture debt in the model and human prose. The archctx rolling writer publishes generated regions and the projection manifest; do not apply and commit them in a feature PR.
 - Preserve `agents/fleet/`, release checklists and downstream `assets/templates`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract.
 - `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
@@ -53,6 +53,8 @@
 - Isolate mutable HOME, repositories and process state; use real synchronization signals and preserve complete failure output.
 - Report failed, timed-out, incomplete or omitted coverage explicitly; do not manufacture receipts, waiver files or pre-fix logs.
 - Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description.
+- Before you write or change tests, load the `repo-harness-test` skill (`assets/skills/repo-harness-test/SKILL.md`).
+- When a local check and CI disagree, CI is the authority. Reproduce the failure with `bash scripts/check-ci.sh <lane>` before you change code; a global `repo-harness` or `repo-harness-hook` on `PATH` can hide a missing test setup.
 
 ## Handoff
 - Create a checkpoint only when context/session rollover or unresolved work needs it; ordinary completion stays in the PR description.
@@ -73,6 +75,9 @@
 - Prefer real companies, products, contracts, prices and user behavior as examples. Use a table for multi-object or multi-metric comparison. Split sections by question; drop introductions, transitions and summaries that exist only for completeness.
 - Paragraph deletion test: if removing a paragraph leaves the reader's understanding of facts, numbers, mechanism, cause, conditions and conclusion unchanged, remove it. Check first the paragraphs that start with "this shows", "note that", "therefore", "however" or "it must be stressed".
 
+## UI
+- Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.
+
 ## Claude Code
 - Own frontend implementation and interaction; Codex owns backend implementation and testing, and the parent coordinates scope and integration.
 - Use Claude Code's available tools within granted permissions; changes to tool grants, hooks or confirmation bypass require approval of the exact change.

package/README.md

@@ -115,10 +115,12 @@ bun test
 
 ### Success looks like this
 
-Successful init enables the architecture projection provider when that
-preference is unset. An explicit disabled choice is preserved. Dry-run does not
-write the preference. repo-harness supplies tools and evidence; the Bot decides
-what to schedule.
+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
+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.
 
 Apply ends with `=== Migration Report ===`, naming where generated hook behavior
 comes from, the user-level `~/.claude/settings.json` and `~/.codex/hooks.json`
@@ -327,20 +329,39 @@ accepted suggestion goes through the normal plan and pull request workflow.
 
 ```bash
 repo-harness external-source refresh   # one bounded, explicitly enabled GitHub observation
-repo-harness external-source bind      # one immutable revision to one pending canonical task
+repo-harness external-source bind --repo <id> --source-revision <digest> --session <selector.json>
+repo-harness external-source historical-bindings --repo <id>  # retired V1 records only
 repo-harness external-source bindings  # binding edges and current drift attention
 ```
 
 Intake is inert by design. An observed Issue mints no execution authority and
 does not become a runnable task on its own; binding attaches an immutable source
-revision to a task that already has an approved plan and contract.
+revision to an existing admitted session selected by its provider issue, immutable
+claim, approved grant and session binding digest. The selector comes from task
+session discovery. Binding never creates a claim or approval.
 
 ### Persistent acceptance review
 
+Before review, configure the repository's manual `external_sources` policy and
+provide working provider access. The default policy is off; initialization does
+not enable it. The trusted upstream Bot must authenticate the human, authorize
+the scope, and supply the bound request. Its integration calls
+`repo-harness review admit --repo <execution-checkout> --request <authorized-request.json>`.
+The request contains `{admission, approval, expectedRevision}`. Admission requires
+an explicit `execution_mode`: `contract` or `inline`. The mode is part of the
+approved admission digest; changing it requires new approval. Do not create an
+approval from these examples: actor IDs and authorization references are binding
+data, not authentication. Select the resulting active grant and policy digests
+below, and supply the current immutable issue claim. A contract or plan file
+cannot grant permission. A user waiver requires a separate upstream-authorized
+decision; waiver eligibility in an admission does not grant one.
+
+See [the control Bot boundary](docs/control-bot-boundary.md) for the integration contract.
+
 ```bash
-repo-harness review round --contract tasks/contracts/<task>.contract.md --reviewer-repo <linked-checkout> --herdr-endpoint <address.json>
-repo-harness review status --contract tasks/contracts/<task>.contract.md
-repo-harness review close --contract tasks/contracts/<task>.contract.md
+repo-harness review round --repository-id <repository-id> --issue-id <issue-id> --campaign-id <campaign-id> --grant-sha256 <approved-grant-sha256> --policy-sha256 <policy-sha256> --actor <actor-id> --reviewer-repo <linked-checkout> --herdr-endpoint <address.json> --verification <native-report> --claim-ref <claim-reference> --claim-revision <claim-sha256>
+repo-harness review status --repository-id <repository-id> --issue-id <issue-id> --campaign-id <campaign-id> --grant-sha256 <approved-grant-sha256> --policy-sha256 <policy-sha256> --actor <actor-id>
+repo-harness review close --repository-id <repository-id> --issue-id <issue-id> --campaign-id <campaign-id> --grant-sha256 <approved-grant-sha256> --policy-sha256 <policy-sha256> --actor <actor-id>
 ```
 
 In the Claude desktop app without Herdr, add `--launch app-terminal` and omit `--herdr-endpoint`. The first call prints the fixed host command. Claude runs it once in an app Terminal tab, then repeats the round. OAR, Seatbelt and the Receipt stay the same.
@@ -564,8 +585,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.23.1`
-- Generated workflow stamp: `repo-harness@0.23.1+template@0.23.1`
+- npm package: `repo-harness@0.24.2`
+- Generated workflow stamp: `repo-harness@0.24.2+template@0.24.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/herdr/webhook-notify/notify.mjs

@@ -1,12 +1,16 @@
 // Adapted from ~/herdr-plugins/webhook-notify. Config and identity come from Herdr.
-import { existsSync, lstatSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { constants, closeSync, fchmodSync, fstatSync, mkdirSync, openSync, readSync, rmdirSync, existsSync, lstatSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { systemWorktreeRoot } from './worktree-location.mjs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { hostname, tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { parseEnv } from 'node:util';
 import { pathToFileURL } from 'node:url';
 
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { POLICY_VERSION, paneStatusRequest, decodeClefAnswer, decisionBand } from './pane-status.mjs';
+
 const DEBOUNCE_MS = 120_000;
 const TIMEOUT_MS = 5_000;
 const log = (message) => console.error(`[webhook-notify] ${message}`);
@@ -61,7 +65,7 @@ function isTemporary(path, managedRoot) {
 export async function notify(env = process.env, send = fetch, options = {}) {
   const event = objectJson(env.HERDR_PLUGIN_EVENT_JSON);
   const context = objectJson(env.HERDR_PLUGIN_CONTEXT_JSON);
-  if (event.event !== 'pane.agent_status_changed') return;
+  if (event.event !== 'pane_agent_status_changed') return;
   const data = event.data;
   if (!data || !['done', 'blocked'].includes(data.agent_status)) return;
   if (typeof data.pane_id !== 'string' || !data.pane_id || typeof data.workspace_id !== 'string') throw new Error('Invalid event identity.');
@@ -131,6 +135,181 @@ export async function notify(env = process.env, send = fetch, options = {}) {
       }
     } catch { log(`${target.channel}: delivery failed.`); }
   }
+  // Shadow work starts only after all existing notification attempts finish.
+  if (config.CLEF_MODE === 'shadow' && config.CLOUDFLARE_ACCOUNT_ID && config.CLOUDFLARE_API_TOKEN
+    && data.agent_status === 'done' && ['claude', 'codex'].includes(data.agent)) {
+    try { await shadowDecision(env, config, data, send); }
+    catch { log('Shadow record failed.'); }
+  }
+}
+
+const runFile = promisify(execFile);
+const SHADOW_LIMIT = 20 * 1024 * 1024;
+const RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+const MODELS = ['clef-flash', 'clef'];
+
+// Fixed data-safety rules. These patterns never classify the pane outcome.
+export function redactTail(text, config = {}) {
+  let value = text.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+  for (const [key, secret] of Object.entries(config)) {
+    if (secret && /(?:TOKEN|KEY|URL|ACCOUNT_ID|CHAT_ID)$/.test(key)) value = value.replaceAll(secret, '[redacted]');
+  }
+  return value
+    .replace(/\b[A-Z][A-Z0-9_]*(?:\s*=\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s]+)/gi, '[redacted]')
+    .replace(/\bBearer\s+[^\s"'<>]+/gi, 'Bearer [redacted]')
+    .replace(/\b(?:sk-[A-Za-z0-9_-]+|gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+)/g, '[redacted]')
+    .replace(/\b[0-9a-fA-F]{32,}\b/g, '[redacted]')
+    .replace(/[A-Za-z0-9+/_-]{40,}={0,2}/g, '[redacted]');
+}
+
+function boundedTail(raw, config) {
+  const lines = raw.replace(/\r\n/g, '\n').split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  const redacted = redactTail(lines.slice(-120).join('\n'), config);
+  const bytes = Buffer.from(redacted);
+  // Avoid splitting a UTF-8 character at the start of the retained suffix.
+  let start = Math.max(0, bytes.length - 16 * 1024);
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
+  const tail = bytes.subarray(start).toString('utf8');
+  return { tail, tail_lines: tail ? tail.split('\n').length : 0, tail_truncated: lines.length >= 120 || start > 0 };
+}
+
+function privateRead(path, limit) {
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > limit || stat.uid !== process.getuid?.()) throw new Error('Invalid shadow file.');
+    fchmodSync(fd, 0o600);
+    const bytes = Buffer.alloc(stat.size);
+    let count = 0;
+    while (count < bytes.length) {
+      const read = readSync(fd, bytes, count, bytes.length - count, count);
+      if (!read) throw new Error('Incomplete shadow file.');
+      count += read;
+    }
+    return bytes.toString('utf8');
+  } catch (error) { if (error.code === 'ENOENT') return ''; throw error; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function privateWrite(path, text) {
+  const temporary = `${path}-${randomUUID()}`;
+  try {
+    writeFileSync(temporary, text, { mode: 0o600, flag: 'wx' });
+    renameSync(temporary, path);
+  } finally { try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+}
+
+async function withShadowLock(dir, action) {
+  const lock = join(dir, 'decision-shadow.lock');
+  const deadline = Date.now() + 2000;
+  for (;;) {
+    try { mkdirSync(lock, { mode: 0o700 }); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST' || Date.now() >= deadline) throw error;
+      await new Promise(resolve => setTimeout(resolve, 10));
+    }
+  }
+  try { return action(); } finally { rmdirSync(lock); }
+}
+
+async function reserveCalls(dir, now) {
+  return withShadowLock(dir, () => {
+    const path = join(dir, 'decision-budget.json');
+    const raw = privateRead(path, 1024);
+    const day = new Date(now).toISOString().slice(0, 10);
+    const saved = raw ? JSON.parse(raw) : { day, calls: 0 };
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(saved.day) || !Number.isSafeInteger(saved.calls)
+      || saved.calls < 0 || saved.calls > 2000 || saved.day > day) throw new Error('Invalid call budget.');
+    const count = saved.day === day ? saved.calls : 0;
+    const allowed = Math.min(MODELS.length, 2000 - count);
+    privateWrite(path, JSON.stringify({ day, calls: count + allowed }));
+    return allowed;
+  });
+}
+
+async function saveShadow(dir, record) {
+  await withShadowLock(dir, () => {
+    const path = join(dir, 'decision-shadow.jsonl');
+    const raw = privateRead(path, SHADOW_LIMIT);
+    const cutoff = Date.now() - RETENTION_MS;
+    const lines = raw.split('\n').filter(Boolean).filter(line => {
+      const ts = Date.parse(JSON.parse(line).ts);
+      if (!Number.isFinite(ts)) throw new Error('Invalid shadow timestamp.');
+      return ts >= cutoff;
+    });
+    lines.push(JSON.stringify(record));
+    let size = lines.reduce((sum, line) => sum + Buffer.byteLength(line) + 1, 0);
+    let start = 0;
+    while (size > SHADOW_LIMIT && start < lines.length) size -= Buffer.byteLength(lines[start++]) + 1;
+    privateWrite(path, lines.slice(start).join('\n') + '\n');
+  });
+}
+
+async function saveRecord(env, record) {
+  await saveShadow(env.HERDR_PLUGIN_STATE_DIR, record);
+  privateWrite(join(env.HERDR_PLUGIN_CONFIG_DIR, 'decision-state.json'), JSON.stringify({ protocol: 1, state_dir: env.HERDR_PLUGIN_STATE_DIR }));
+}
+
+async function modelDecision(model, state, config, send) {
+  const started = performance.now();
+  const controller = new AbortController();
+  let timer;
+  try {
+    const response = await Promise.race([
+      (async () => {
+        const reply = await send(`https://api.cloudflare.com/client/v4/accounts/${config.CLOUDFLARE_ACCOUNT_ID}/ai/run/@cf/cloudflare/${model}`, {
+          method: 'POST', redirect: 'error', signal: controller.signal,
+          headers: { 'content-type': 'application/json', authorization: `Bearer ${config.CLOUDFLARE_API_TOKEN}` },
+          body: JSON.stringify(paneStatusRequest(state, model)),
+        });
+        if (!reply.ok || reply.redirected) throw new Error('Clef unavailable.');
+        const envelope = await reply.json();
+        if (envelope?.success !== true) throw new Error('Clef unavailable.');
+        return decodeClefAnswer(envelope.result, model);
+      })(),
+      new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('Clef timeout.')); }, 3000); }),
+    ]);
+    return { model, ...response, band: decisionBand(response), latency_ms: Math.round(performance.now() - started) };
+  } catch { return { model, status: 'unavailable', latency_ms: Math.round(performance.now() - started) }; }
+  finally { clearTimeout(timer); }
+}
+
+async function shadowDecision(env, config, data, send) {
+  const record = {
+    event_id: randomUUID(), ts: new Date().toISOString(), pane_id: data.pane_id,
+    agent: data.agent, herdr_status: data.agent_status, policy_version: POLICY_VERSION,
+    tail_sha256: null, tail: null, models: [],
+  };
+  let state;
+  try {
+    if (!/^[a-f0-9]{32}$/i.test(config.CLOUDFLARE_ACCOUNT_ID)) throw new Error('Invalid account id.');
+    if (typeof env.HERDR_BIN_PATH !== 'string' || !isAbsolute(env.HERDR_BIN_PATH)) throw new Error('Herdr binary path is missing.');
+    // Do not pass channel or Cloudflare secrets to the read-only Herdr child.
+    const childEnv = { ...env };
+    for (const key of Object.keys(childEnv)) if (key.startsWith('CLOUDFLARE_') || /^(WEBHOOK_|SLACK_|DISCORD_|TELEGRAM_)/.test(key)) delete childEnv[key];
+    const raw = (await runFile(env.HERDR_BIN_PATH, ['pane', 'read', data.pane_id, '--source', 'recent', '--lines', '120'], {
+        env: childEnv, encoding: 'utf8', timeout: 2000, maxBuffer: 1024 * 1024,
+      })).stdout;
+    state = { agent: data.agent, herdr_status: data.agent_status, pane_title: redactTail(String(data.title ?? ''), config).slice(0, 512), ...boundedTail(raw, config) };
+    record.tail = state.tail;
+    record.tail_sha256 = createHash('sha256').update(state.tail).digest('hex');
+  } catch {
+    record.models = MODELS.map(model => ({ model, status: 'unavailable' }));
+    await saveRecord(env, record);
+    return;
+  }
+  let allowed;
+  try { allowed = await reserveCalls(env.HERDR_PLUGIN_STATE_DIR, Date.now()); }
+  catch {
+    record.models = MODELS.map(model => ({ model, status: 'unavailable' }));
+    await saveRecord(env, record);
+    return;
+  }
+  record.models = await Promise.all(MODELS.map((model, index) => index < allowed
+    ? modelDecision(model, state, config, send) : { model, status: 'skipped_cap' }));
+  await saveRecord(env, record);
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/assets/herdr/webhook-notify/pane-status.mjs

@@ -0,0 +1,74 @@
+// Pure pane decision contract. The plugin projection must match these bytes.
+export const POLICY_VERSION = 'pane-status-shadow-v1';
+export const OPTIONS = Object.freeze(['done', 'stuck', 'model_error', 'quota', 'unclear']);
+const thresholds = Object.freeze({ suggest: null, apply: null });
+export const POLICY = Object.freeze({
+  review: 0.60, shadow: 0.85,
+  labels: Object.freeze({ stuck: thresholds, model_error: thresholds, quota: thresholds }),
+  escalate: Object.freeze(['stuck']),
+});
+const QUESTIONS = {
+  "pane.outcome": {
+    "type": "choice",
+    "instructions": "A terminal coding agent stopped and now waits at its input prompt. Read the end of its terminal output. Decide why it stopped.",
+    "criteria": {
+      "done": "The agent finished the work it was given. Its last message reports a result: a summary, a RESULT block, a PR or commit link, or a test outcome (pass or fail). It waits for a new task.",
+      "stuck": "The agent stopped before the work was finished, for a reason inside the task. It asks the operator a question, waits for a choice or confirmation, repeats the same failed step, or says it cannot continue without help.",
+      "model_error": "The model provider or the agent CLI reported an error that ended the turn. Examples of situations: an API or server error, the model is overloaded or unavailable, the request or context is too large, the connection failed, the CLI crashed.",
+      "quota": "The provider refused more work because of a usage limit: a rate limit, a usage or plan cap, a credit or billing limit, or a message that the limit resets at a later time.",
+      "unclear": "The output does not show enough to decide, or the screen shows something other than an agent session (a shell prompt, an editor, empty output)."
+    }
+  },
+  "pane.result_present": {
+    "type": "noul",
+    "instructions": "Does the last agent message state a final result of the assigned work?"
+  },
+  "pane.provider_message": {
+    "type": "noul",
+    "instructions": "Does the output end with a message from the model provider or the CLI, not from the agent's own reasoning?"
+  }
+};
+
+export function paneStatusRequest(state, model = 'clef-flash') {
+  if (!['clef-flash', 'clef'].includes(model) || !['claude', 'codex'].includes(state.agent)
+    || state.herdr_status !== 'done' || typeof state.pane_title !== 'string'
+    || !Number.isInteger(state.tail_lines) || state.tail_lines < 0 || state.tail_lines > 120
+    || typeof state.tail_truncated !== 'boolean' || typeof state.tail !== 'string'
+    || new TextEncoder().encode(state.tail).length > 16 * 1024) throw new Error('Invalid pane state.');
+  return { model, state: {
+    agent: state.agent, herdr_status: state.herdr_status, pane_title: state.pane_title,
+    tail_lines: state.tail_lines, tail_truncated: state.tail_truncated, tail: state.tail,
+  }, questions: structuredClone(QUESTIONS) };
+}
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const probability = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+export function decodeClefAnswer(value, model = 'clef-flash') {
+  const invalid = { status: 'invalid' };
+  if (!object(value) || value.model !== model || !object(value.answers) || !object(value.usage)
+    || !Number.isSafeInteger(value.usage.input_tokens) || value.usage.input_tokens < 0
+    || !Number.isSafeInteger(value.usage.output_tokens) || value.usage.output_tokens < 0) return invalid;
+  const answer = value.answers['pane.outcome'];
+  if (!object(answer) || answer.type !== 'choice' || !OPTIONS.includes(answer.choice)
+    || !probability(answer.confidence) || !object(answer.probabilities)
+    || Object.keys(answer.probabilities).length !== OPTIONS.length
+    || OPTIONS.some(option => !probability(answer.probabilities[option]))) return invalid;
+  const probabilities = Object.fromEntries(OPTIONS.map(option => [option, answer.probabilities[option]]));
+  if (Math.abs(Object.values(probabilities).reduce((sum, p) => sum + p, 0) - 1) > 0.010000000001
+    || Object.values(probabilities).some(p => p > probabilities[answer.choice])) return invalid;
+  const evidence = {};
+  for (const id of ['pane.result_present', 'pane.provider_message']) {
+    const item = value.answers[id];
+    if (!object(item) || item.type !== 'noul' || !probability(item.noul)) return invalid;
+    evidence[id] = item.noul;
+  }
+  return { status: 'ok', choice: answer.choice, probabilities, confidence: answer.confidence,
+    input_tokens: value.usage.input_tokens, evidence };
+}
+
+// Promoted thresholds stay null. Shadow bands use the provisional threshold.
+export function decisionBand(answer, mode = 'shadow') {
+  if (answer.status !== 'ok' || answer.choice === 'unclear' || answer.confidence < POLICY.review) return 'abstain';
+  const threshold = mode === 'shadow' ? POLICY.shadow : POLICY.labels[answer.choice]?.[mode];
+  return threshold !== null && threshold !== undefined && answer.confidence >= threshold ? 'act' : 'review';
+}

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

@@ -1,7 +1,7 @@
 # Agentic development flow
 
 - Default task worktrees use `/tmp/<repo>-wt-<slug>` on POSIX. Native Windows uses `os.tmpdir()` as the root. The stored default is `{{system_tmp}}/{{repo}}-wt-{{slug}}`. Runtime code resolves the temp token. Explicit stored templates stay unchanged. Commit or push work before a reboot or age-based tmp cleanup, such as `systemd-tmpfiles`. These cleaners can remove checkouts. Missing entries are pruned. The sweep saves missing registration identities before global prune. Later batches finish deferred branch cleanup. Unmerged branches remain.
-- Closeout removes a merged, clean checkout and its branch. It releases only that checkout's own canonical marker after merge proof under the topology lock. The sweep keeps dirty, locked, marked or leased worktrees. It keeps branch reflogs without a commit-creation message and missing or unreadable reflogs. Fast-forward, target-only automatic merges, reset and rebase-finish messages do not count. Dispatch must establish an unmerged commit or keep the worktree dirty, marked or leased. A merged, clean, unowned branch with its own commits can be swept.
+- Closeout removes a merged, clean checkout and its branch. It releases only that checkout's own canonical marker after merge proof under the topology lock. The sweep keeps dirty, locked and marked worktrees. It keeps branch reflogs without a commit-creation message and missing or unreadable reflogs. Fast-forward, target-only automatic merges, reset and rebase-finish messages do not count. Dispatch must establish an unmerged commit or keep the worktree dirty, locked or marked. A merged, clean, unowned branch with its own commits can be swept.
 - `start` recovers only a real target directory registered by this clone on the expected branch, under the topology lock, with no lock or other owner. Recovery requires a current-user-owned checkout directory without group or other write access, a regular owned Git pointer, its matching admin backpointer, and the original directory identity saved by start. Git metadata can be group-writable but must not be other-writable. Start still creates a checkout when uid is unavailable; recovery then refuses. Exact removal retires the identity after Git readback. Missing identity or a replacement directory blocks recovery. Files, symlinks, unregistered paths and other branches are refused. Cleanup refuses a registered worktree whose branch is missing. MCP cleanup also refuses active markers. Sweep reports name processed paths. Deferred entries are reported as counts. `kept` excludes deferred entries. A command timeout sends SIGTERM to the direct child only. A grandchild can briefly extend the deadline. No detached cleanup process starts. Herdr notifications accept registered default task worktrees and paths inside them. Other temporary paths and `rh-herdr-` labels stay filtered.
 
 ## Daily Flow
@@ -9,10 +9,24 @@
 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.
-5. A model may squash-merge into main only when the current task explicitly authorizes main publication, automatic checks pass, and GitHub has no outstanding change requests or unresolved review threads. An explicit no-merge instruction always wins. 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. An explicit no-merge instruction always wins. The next merge does not wait for the main push CI of the previous merge. Main push CI is an alarm: when it fails, the next merge is the revert or the fix. 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.
 
+## CI cost
+Size PR CI by the diff, the same as step 4. A full suite on each small PR spends runner time and adds no evidence that the affected tests and the daily run do not already give. The repo-harness source repository uses this shape in `.github/workflows/ci.yml`.
+
+- Triggers: run PR checks on `pull_request`. Do not also trigger `push` on feature branches; that runs each commit twice. A `push` to the default branch runs the affected selection for the merged diff, not the full suite.
+- Superseded runs: set `concurrency` to one group per PR number with `cancel-in-progress: true` for `pull_request` events only. Do not cancel scheduled runs.
+- Selection: a first job reads the diff against the PR base and outputs a mode. Later jobs read the mode in a job-level `if:`.
+  - A docs-only diff (`docs/**/*.md`, README, CHANGELOG, `tasks/`, `plans/`) skips build and test jobs when no test or script reads the changed files. Keep link and format checks. A document that is program input, such as a projected copy, a parsed contract or a generated region, runs its consumer tests.
+  - A code diff runs typecheck plus the tests that the diff affects. Use the runner's change detection (`vitest --changed`, `jest --changedSince`, `nx affected`, `turbo run --filter=...[<base>]`, `pytest --testmon`) or an import-graph selector.
+  - A change to a shared input (lockfile, root build or test config, CI workflow, a test helper with no mapped consumer) runs the full suite on that PR. A selector that cannot map a changed file widens the run; it never shrinks it.
+- Required checks: skip a job with a job-level `if:`, not with workflow-level `paths` or `paths-ignore`. GitHub counts a skipped job as passing for a required check. A workflow that never starts leaves its required check pending and blocks the merge.
+- Full suite: run it on `schedule` (daily) and `workflow_dispatch` against one default-branch SHA, and on the release SHA before a release. A daily failure opens a repair task (step 6).
+- Matrix: each axis must change the runtime that the tests run on. When the test runner is pinned, for example one Bun version, a Node-version axis reaches only the scripts and tests that spawn Node. Run only that subset on the axis; a full suite on 3 OS × 3 Node versions repeats each OS run three times. On a PR, run a matrix cell only when the diff touches code that depends on its axis. The daily run covers each cell with its dependent subset. Set `fail-fast: false` so one cell failure does not hide the others.
+- Limits: set `timeout-minutes` on each job; the GitHub default of 360 minutes lets a hung job spend all of it. Cache dependencies keyed on the lockfile.
+
 ## Report SOP
 - Give a Feynman report: explain the work to a reader who does not know this project. Use plain language. Explain the goal, user value, how it works, completed work and remaining gaps. Explain each technical term at first use.
 - State the conclusion, changes, reasons, verification and remaining risks. Link each claim to its source or label it as an inference. Use observed results. Name failed, incomplete and omitted checks.
@@ -109,6 +123,9 @@ Rules for every tier:
 - From the second round, the reviewer reads only the hunks that changed after the previous round. The three-round limit stays.
 - When an independent review ran, the PR description lists each finding with its disposition: fixed, or closed with the reason.
 - A low tier adds no review. A new test file or a rebase does not raise the tier.
+- A parent or coordinator reuses a worker's recorded independent review of the same diff when that review meets the diff's tier. Only a changed diff, or a missing tier review, needs a new review.
+- A downstream repository maps its own release surfaces, for example public API, wire format, DDL/SQL and permissions, to the High tier.
+
 A worker gets Goal, Scope, Context, Acceptance, Verify, Rollback, Timebox, Forbidden, Report and Standing as defined in [the delegation brief](sprint-contracts.md#delegation-brief), then loads concrete techniques on demand. Do not put routing catalogs or every technology guide in its brief.
 
 A coding session that spawns sub-agents is their parent. Investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They do not run build, typecheck or tests. They commit early in their own worktree and return early. In a shared checkout they do not commit; the parent commits. An evidence role whose task is a named check, such as a root-cause reproduction or an evaluation profile, still runs that check and does not commit. The brief's Verify section names the checks that the parent runs after integration. The parent owns task management, conflict resolution, build, typecheck, tests and integration. After integration, the parent removes each sub-agent worktree and branch whose commits are in the task branch and whose checkout is clean. It also removes the intermediate build output and temporary files that the work created. Other deletion still needs the user.
@@ -121,3 +138,5 @@ Stop and ask the user when a command or result names `unknown`, `ambiguous`, `pe
 Architecture docs remain references. Update them only when responsibilities or boundaries change; no per-edit drift queue, workstream sync or automatic agent-context block. Ordinary work has no plan/contract/review/notes or promote/archive prerequisite. Notes are optional for non-obvious decisions; PRDs are for real new products.
 
 Park a gate; do not block on it. A gate is a decision that only the human can make. It is one of four kinds: an irreversible action, a product or preference call that no experiment settles, a standing rule that contradicts observed reality, or a dead end that survived a replan. Frontier nudges, retries, CI flake triage, review-thread triage, format fixes and "should I keep going" never reach the human. The GitHub issue and PR are the task authority. When the task has an issue, post a parked gate in the issue status comment (the `repo-harness issue status` format) under a `Gates:` list. When the task has a PR but no issue, park it under a `Gates:` list in the PR description. When the task has neither, park it in the catch-up reply of the current conversation. Give each gate an id, the question, the options, the recommended option, and what happens if no answer arrives by a stated time. Route the remaining work around the gate. The [catch-up reply](#report-sop) lists open gates first. A reply to a gate is a human comment on the same issue. The Bot reads that comment back before it acts on it.
+
+For a multi-PR coordination run, the issue and its PRs are the coordination state. An active plan's `## Task Breakdown` still lists the execution steps. A run log, when kept, is an append-only list of events. Derive an owner summary from the run log, or write the summary once at closeout. Approval text goes in the PR description, not in a separate file.

package/assets/reference-configs/document-generation.md

@@ -33,6 +33,6 @@ Create these only when the agent has concrete repo evidence or the user asks:
 - Let capability `CLAUDE.md` and `AGENTS.md` carry local contract projections; root docs stay concise.
 - Keep complete workstream TODOs in `tasks/workstreams/<domain>/<capability>/`; contract blocks should link to them instead of becoming task logs.
 - Keep onboarding docs split by reader: agents read active source artifacts first; humans review the Human Review Card, diff, latest trace, and rollback first.
-- `.archcontext/model/` owns architecture boundaries. After a model change, run `repo-harness architecture-projection apply --json` to regenerate the machine sections of `docs/architecture/`. Agents own semantic snapshots, the hand-written module sections and embedded Mermaid source.
+- `.archcontext/model/` owns architecture boundaries. Agents change the model, semantic decisions and human-written sections. The archctx rolling writer publishes generated regions and diagrams. Do not apply and commit generated output in feature PRs.
 - Treat Markdown Mermaid as the only architecture diagram artifact; do not generate standalone HTML.
 - Treat `mermaid` as an external authoring/review skill at `~/.codex/skills/mermaid`; do not copy or inline its assets into generated repos.