session-orchestrator 3.22.0 → 3.24.0

package/docs/components.md

@@ -7,8 +7,8 @@ Detailed component inventory and architecture reference for Session Orchestrator
 ```mermaid
 flowchart LR
     USER([Operator]) -->|invokes /session| COORD[Coordinator]
-    COORD -->|reads| SK[Skills<br/>47 user-facing]
-    COORD -->|invokes| CMD[Commands<br/>27 slash-cmds]
+    COORD -->|reads| SK[Skills<br/>49 user-facing]
+    COORD -->|invokes| CMD[Commands<br/>28 slash-cmds]
     COORD -->|dispatches| AG[Agents<br/>15 typed sub-agents]
     AG -.->|parallel waves| W1[code-implementer]
     AG -.-> W2[test-writer]
@@ -18,23 +18,23 @@ flowchart LR
     COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
 ```
 
-## Skills (47 user-facing)
+## Skills (49 user-facing)
 
 - **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
 - **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`, `contract-version-bump`
-- **Planning & discovery:** `plan`, `discovery`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`, `grill`
+- **Planning & discovery:** `plan`, `discovery`, `journey-audit`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`, `grill`
 - **Architecture:** `architecture`, `domain-model`, `ubiquitous-language`
 - **Cross-session:** `evolve`, `convergence-monitoring`, `memory-cleanup`, `reconcile`, `sunset-review`, `eval`
 - **Vault & docs:** `vault-sync`, `vault-mirror`, `daily`, `docs-orchestrator`
-- **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `spinout`, `npm-publish`
+- **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `remote-offload`, `spinout`, `npm-publish`
 - **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`
 - **Content review:** `persona-panel`
 - **Operator ergonomics:** `eli5` (plain-language restatement of the last answer)
 - **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))
 
-## Commands (27)
+## Commands (28)
 
-`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/contract-version-bump`, `/eli5`.
+`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/contract-version-bump`, `/eli5`, `/journey-audit`.
 
 ## Agents (15 typed sub-agents)
 

package/docs/cursor-setup.md

@@ -5,32 +5,31 @@ Guide for using Session Orchestrator with Cursor IDE.
 ## Prerequisites
 
 - [Cursor IDE](https://cursor.com) installed (version 1.7+ recommended for hooks support)
-- jq installed (`brew install jq` / `apt install jq`)
+- Node.js 24+
 - A project repository with git initialized
 
 ## Installation
 
-### Option 1: Clone and symlink (recommended)
 ```bash
-# 1. Clone the session-orchestrator repo and install its dependencies
 git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator
 cd ~/Projects/session-orchestrator && npm install
-
-# 2. Symlink Cursor rules into your project
-node ~/Projects/session-orchestrator/scripts/cursor-install.mjs /path/to/your/project
+node ~/Projects/session-orchestrator/scripts/cursor-install.mjs /path/to/your-project
 ```
 
-### Option 2: Manual copy
-```bash
-# Copy .cursor/rules/ into your project
-cp -r path/to/session-orchestrator/.cursor/rules/ .cursor/rules/
-```
+The installer links four Cursor-native surfaces into the target project:
 
-## Configuration
+| Surface | Path | What Cursor does with it |
+|---|---|---|
+| Rules | `.cursor/rules/*.mdc` | Always-on + intelligent-apply guidance |
+| Commands | `.cursor/commands/*.md` | Slash commands (`/session`, `/go`, `/close`, …) |
+| Skills | `.cursor/skills/<name>/SKILL.md` | Skill discovery; wrappers point at canonical `skills/` |
+| Hooks | `.cursor/hooks.json` | Native hooks via `scripts/lib/cursor-hook-bridge.mjs` |
+
+Working **in this repo** does not need the installer — those paths are committed. Reload Cursor (or start a new agent chat) after a pull so `/session` appears.
 
-### Session Config in CLAUDE.md
+## Configuration
 
-Cursor reads CLAUDE.md natively — no separate config file needed! Add a `## Session Config` section to your project's `CLAUDE.md`:
+Cursor reads CLAUDE.md natively. Add a `## Session Config` section:
 
 ```markdown
 ## Session Config
@@ -45,33 +44,10 @@ enforcement: warn
 vcs: github
 ```
 
-Note: `agents-per-wave` is ignored on Cursor since tasks execute sequentially (no parallel Agent dispatch).
-
-### Hooks (Optional — not yet enforcing)
-
-> **The hook handlers do not currently fire on Cursor (#919).** Both are written
-> against Claude Code's `PreToolUse` payload — they require `tool_name === "Bash"`
-> plus `tool_input.command`, and they signal a decision with a Claude Code
-> `hookSpecificOutput` envelope. Fed a Cursor `beforeShellExecution` payload,
-> `hooks/enforce-commands.mjs` short-circuits at its first gate and writes **0
-> bytes to stdout and 0 bytes to stderr, exit 0** — so the harness sees no
-> decision and **the command runs**. It is a silent no-op, not a block and not
-> even a warning. Making this real needs a Cursor input/output adapter, the way
-> Pi has `scripts/lib/pi-hook-bridge.mjs`; no such adapter exists yet.
->
-> Until then, treat `hooks/hooks-cursor.json` as the *intended* mapping and do
-> not rely on it for command or scope enforcement on Cursor.
-
-Cursor supports hooks via Settings > Hooks. The intended mapping is:
-
-- **afterFileEdit**: `hooks/enforce-scope.mjs` for scope enforcement (post-hoc warning)
-- **beforeShellExecution**: `hooks/enforce-commands.mjs` for dangerous-command enforcement
-
-See `hooks/hooks-cursor.json` for the hook mapping reference.
+`agents-per-wave` is ignored on Cursor — tasks execute sequentially (no parallel Agent dispatch).
 
 ## Usage
 
-Commands work the same as in Claude Code:
 - `/session [housekeeping|feature|deep]` — Start a session
 - `/go` — Execute the agreed plan
 - `/close` — End session with verification
@@ -79,6 +55,8 @@ Commands work the same as in Claude Code:
 - `/discovery [scope]` — Run quality probes
 - `/evolve [analyze|review|list]` — Manage learnings
 
+Cursor has no Skill tool. Commands tell the agent to **Read** `skills/<name>/SKILL.md` and follow it.
+
 ## Key Differences from Claude Code
 
 | Aspect | Claude Code | Cursor IDE |
@@ -88,17 +66,18 @@ Commands work the same as in Claude Code:
 | State directory | .claude/ | .cursor/ |
 | Config file | CLAUDE.md | CLAUDE.md (same!) |
 | Task tracking | TaskCreate/TaskUpdate | Text-based checklists |
-| Pre-edit enforcement | PreToolUse hook (blocks) | None today — `afterFileEdit` handler is a no-op (#919) |
-| Command enforcement | PreToolUse hook (blocks) | None today — `beforeShellExecution` handler is a no-op (#919) |
+| Pre-edit enforcement | PreToolUse hook (blocks) | `preToolUse` via cursor-hook-bridge (blocks) |
+| Command enforcement | PreToolUse hook (blocks) | `beforeShellExecution` via cursor-hook-bridge (blocks) |
+| Post-edit | PostToolUse | `afterFileEdit` is post-hoc (cannot unwrite) |
 | Model | Claude via API | Model selected in Cursor settings |
 | Plan mode | EnterPlanMode tool | Instruction-based |
 
 ## Limitations
 
 1. **No parallel agents** — All wave tasks execute sequentially. Sessions take longer than in Claude Code.
-2. **No hook enforcement yet (#919)** — the handlers in `hooks/hooks-cursor.json` are Claude Code `PreToolUse` handlers. On a Cursor payload both `enforce-commands.mjs` and `enforce-scope.mjs` short-circuit at their first gate and produce **0 bytes on stdout and stderr with exit 0** — a silent no-op, so nothing is blocked and nothing is warned. Two independent adapters are missing: Cursor's payload field names differ from `tool_name` / `tool_input.*`, and Cursor does not read Claude Code's `hookSpecificOutput` decision envelope. Even once adapted, Cursor's `afterFileEdit` fires *after* the edit, so scope enforcement could at best warn, never prevent.
+2. **afterFileEdit cannot prevent an edit** — it fires after the write. Scope blocking belongs on `preToolUse`.
 3. **Model preference advisory** — The `model-preference-cursor` frontmatter in skills is advisory only. Select your model in Cursor settings.
-4. **No native plugin loader** — Skills are delivered as `.cursor/rules/*.mdc` files, not loaded from a plugin directory.
+4. **No Agent/Skill tools** — `pre-task-scope-disjoint` and `skill-invocation-telemetry` are not wired; commands Read skill files directly.
 
 ## Shared Knowledge
 
@@ -110,8 +89,8 @@ Switch freely between Claude Code, Codex, and Cursor on the same project — all
 
 ## Troubleshooting
 
-- **Rules not loading**: Ensure `.cursor/rules/` exists in your project root with `.mdc` files
-- **Commands not recognized**: Check that `000-session-orchestrator.mdc` has `alwaysApply: true`
-- **Hooks not firing**: Verify hooks are configured in Cursor Settings > Hooks
-- **jq not found**: Install jq for scope enforcement hooks
-- **State files not created**: Check `.cursor/` directory exists and is writable
+- **`/session` missing**: Confirm `.cursor/commands/session.md` exists. Reload Cursor. If this is another project, re-run `node scripts/cursor-install.mjs .`
+- **Rules not loading**: Ensure `.cursor/rules/` exists with `.mdc` files; `000-session-orchestrator.mdc` has `alwaysApply: true`
+- **Hooks not firing**: Confirm `.cursor/hooks.json` exists. Open Cursor Settings → Hooks. Restart Cursor if it was open during install.
+- **`'node' not found` in hook PATH**: See README troubleshooting. `hooks/run-node.sh` resolves Homebrew/nvm Node.
+- **State files not created**: Check `.cursor/` is writable

package/docs/events-schema.md

@@ -10,13 +10,45 @@ session at SessionStart (`events-rotation.mjs`).
 Every record is a single JSON line of the form:
 
 ```json
-{ "timestamp": "2026-05-28T14:35:13.123Z", "event": "orchestrator.session.ended", "...": "payload" }
+{ "timestamp": "2026-05-28T14:35:13.123Z", "event": "orchestrator.session.ended", "...": "payload", "schema_version": 1 }
 ```
 
+`schema_version` serialises **last**, after the payload spread — `emitEvent()` builds
+`{timestamp, event, ...correlation, ...payload}` first and only then calls
+`stampEventSchemaVersion()`, which adds the key when absent rather than inlining it up
+front (see below).
+
 - `timestamp` — ISO-8601 UTC string (trailing `Z`). Generated by `emitEvent()`.
 - `event` — the event name (see convention below).
+- `schema_version` — record schema version (currently `1`, `CURRENT_SCHEMA_VERSION` in
+  `scripts/lib/events-schema.mjs`). Stamped by `emitEvent()` on every write (#1177); a
+  caller-supplied `schema_version` in `payload` is never overwritten. **Validated before write:**
+  `validateEventRecord()` runs BEFORE the line is appended and BEFORE any webhook POST — a record
+  that fails validation throws `EventValidationError` (carrying `.errors` and `.eventType`) and
+  produces neither a ledger line nor a webhook call. `scripts/emit-event.mjs` maps a thrown
+  `EventValidationError` to exit `1` (a filesystem/I/O failure keeps its existing exit `2`).
+  `scripts/lib/tmux-layout/telemetry.mjs` stamps and validates synchronously on its own write path
+  and drops an invalid line rather than appending it. **The read path stays lenient**: an absent
+  `schema_version` is not itself invalid, so the 33,700 historical records written before #1177
+  remain valid (measured 2026-09-02, working tree @ `c3ab480`: `jq -c 'select(.schema_version ==
+  null)' .orchestrator/metrics/events.jsonl | wc -l`) — 20 of those, all from 2026-04-19, carry a
+  legacy `ts` field instead of `timestamp` and are known test-fixture leakage, not a live producer.
+  The webhook body (`{ event_type, source, payload }`) is unchanged by #1177 — it never carries
+  `schema_version`, which describes the JSONL record, not the wire contract with the external
+  consumer.
 - remaining keys — event-specific payload, shallow-merged.
 
+### Correlation keys (best-effort)
+
+`session_id` / `semantic_session_id` come from `sessionAttribution()` (`scripts/lib/events.mjs`).
+`emitEvent()` fills these keys automatically when the caller passed none — but **only** when a
+PROCESS-LOCAL witness (`CLAUDE_CODE_SESSION_ID`, or the hook-input session id) exactly equals the
+lock's raw `session_id`. STATE.md is **not** a witness. They are **omitted, never fabricated**,
+whenever that witness check fails or no readable lock exists — a made-up id would silently collide
+across every unattributed run, and attributing a record to a session it does not belong to is worse
+than leaving the field out (#1123). `wave` is filled the same way, but only from a `wave-scope.json`
+manifest bound to THIS SAME session — an unbound manifest is ignored — and coerced to an integer.
+
 ## Single emission path
 
 **All orchestrator events MUST be emitted via `emitEvent(type, payload)` from
@@ -55,31 +87,109 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 
 | Event | Emitter | Hook / trigger |
 |---|---|---|
-| `orchestrator.session.started` | `hooks/on-session-start.mjs` | SessionStart |
-| `orchestrator.session.ended` | `hooks/on-session-end.mjs` | SessionEnd |
-| `orchestrator.session.stopped` | `hooks/on-stop.mjs` | Stop |
+| `orchestrator.session.started` | `hooks/on-session-start.mjs` | SessionStart. **Optional, additive:** `peers_superseded` (number, GH#67) — the count of mechanically-detected peers (`mechanicalPeers`) whose `lockSuperseded === true` (a LIVE lock at this root is held by a different raw session_id than that registry-only peer — a HINT, not a verdict; see the GH#67 discussion above). Computed as `mechanicalPeersSuperseded` and rendered inline per peer via `supersessionMarker()` in the banner text. `peer_count` is deliberately left unchanged by this addition, so the supersession rate is measurable (`peers_superseded` / `peer_count`) instead of only inferred from banner prose (HR-105) |
+| `orchestrator.session.ended` | `hooks/on-session-end.mjs` | SessionEnd. **Payload:** `reason` (always), plus `session_id` / `semantic_session_id` / `duration_ms` — **each OMITTED, never fabricated, when it could not be measured** (#1068 AC1; `duration_ms` since the W5 F1 sweep). `duration_ms` is written ONLY when the ending session IS the one `.orchestrator/current-session.json` records (the `isRecordedSession` predicate, decided on the RAW stdin UUID) AND that file's start timestamp parsed. Until that fix it fell back to a hard `0`: **1082 of 1498** fleet records (72,2 % — 415 nonzero, 1 key absent, measured 2026-09-02) carried a zero that reads as a MEASURED zero-length session and is indistinguishable from one. An ABSENT `duration_ms` means NOT MEASURED, never "instant" — same omit-never-fabricate contract as `session.stopped` / `agent.stopped` above |
+| `orchestrator.session.stopped` | `hooks/on-stop.mjs` (`handleStop`) | Stop. **Payload:** `session_id`, `semantic_session_id`, `wave`, optional `branch` / `commit`, plus the pair `duration_ms` + `duration_source` (`stdin-start-ms` | `session-lock`). **The pair is written TOGETHER or omitted together — never `0`.** Until this change `duration_ms` was a hard `0` in **8.127 of 8.127** fleet records (measured 2026-09-02): the expression fell back to `0` because the harness never sends `start_ms`, and a fabricated zero reads as a MEASURED zero-length turn, indistinguishable from one. The span is now derived from `.orchestrator/session.lock` `started_at` — **ownership-gated on the RAW stdin `session_id`**, because a lock in this working copy routinely names a live PEER session (the resolved id is deliberately not used: it falls back to `current-session.json`, which is the foreign-identity inheritance the guard refuses). No owned, readable, parseable lock ⇒ both keys absent, which means NOT MEASURED and never "instant". **`duration_source` says WHICH span the number is, and the two are not the same quantity:** `session-lock` is SESSION-elapsed measured at this turn's end — Stop fires per TURN while `started_at` is stamped once per SESSION, so it GROWS MONOTONICALLY across a session's turns (the last Stop of a 3-hour session reports ~3 hours, not its final turn); `stdin-start-ms` is TURN-elapsed, the only first-party measurement of the turn itself, and the harness has never sent it. Do not sum `session-lock` spans over a session — that double-counts |
+| `orchestrator.session.backfill_completed` | `hooks/on-session-end.mjs` (`emitBackfillOutcome`) · `scripts/backfill-abandoned-sessions.mjs` (`emitBackfillCompleted`, the startup/CLI path, #1167) | SessionEnd, once per backfill call (#1068 AC2 — the backfill outcome is canonically queryable, the side-log is no longer the only result source) — and separately, once per record the startup/CLI path itself writes, which until #1167 wrote SILENTLY: the SessionEnd hook was the only emitter, so nothing distinguished "the backfill never ran" from "it ran at startup". Both producers mirror the same payload shape so one filter queries either. Payload: `kind` (`abandoned`\|`state-md-completed`), `action` (the backfill result action, e.g. `appended`\|`superseded`\|`skipped-already-recorded`\|`unknown`), plus `session_id`, `semantic_session_id`, `record_id`, `supersedes`, `reason` — each OMITTED when unknown, never `null`. Best-effort on both paths: emission is wrapped in try/catch so a telemetry failure never blocks the backfill it describes |
+| `orchestrator.session.root_left` | `scripts/lib/session-transition.mjs` (`leaveSourceRoot`) | a session left a repo root for good — the process-boundary teardown of Worktree-Auto-Promotion (#1069), emitted into the OLD root's stream after `deregisterSelf()` + `release()`, whether or not either found anything. NOT emitted when the teardown ABORTED (invalid args, a lock owned by another session, an unparseable lock): the event asserts a root was left, and on those branches none was. Payload: `session_id`, `semantic_session_id` (OMITTED when unknown, never `null`), `from_root_hash` (`repoPathHash()` of the abandoned root — the SAME hash the session registry keys its entries by, so a departure joins to the entry it removed), `from_root_basename` (matching the registry's `repo_name`), `reason` (e.g. `worktree-promotion`). **Never the absolute root:** this payload also travels over the optional Clank webhook with no redaction, and an absolute root on a developer host is `/Users/<operator>/…` — same rule as `board_written` / `mirror_completed` and `relativeWorktreePath` in `worktree-pipeline.mjs`. Its absence beside a live-looking registry entry is the phantom-peer signature the event exists to make visible |
 | `orchestrator.session.lock.acquired` | `hooks/_lib/lock-bootstrap.mjs` | SessionStart |
-| `orchestrator.session.lock.released` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) | after a `release()` that matched ownership (#952). Payload: `session_id`, `caller` (`on-session-end`\|`worktree-pipeline`), `outcome` (`deleted`\|`already-gone`), `verified`; hook-side additionally `lock_session_id`, `semantic_session_id`, `end_reason` (the SessionEnd reason — deliberately NOT `reason`, which the sibling `release_failed` uses for the failure reason); pipeline-side additionally `worktree_path`, `issue_iid`. `outcome: 'already-gone'` means the lock had ALREADY vanished between `readLock()` and `release()` — the forensically interesting case, since a successful release previously left no trace at all and a missing lock was therefore indistinguishable from a lock someone else deleted (#914 residual 3) |
+| `orchestrator.session.lock.released` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) · `scripts/lib/session-transition.mjs` (`leaveSourceRoot`) | after a `release()` that matched ownership (#952). Payload: `session_id`, `caller` (`on-session-end`\|`worktree-pipeline`\|`session-transition`), `outcome` (`deleted`\|`already-gone`), `verified`; hook-side additionally `lock_session_id`, `semantic_session_id`, `end_reason` (the SessionEnd reason — deliberately NOT `reason`, which the sibling `release_failed` uses for the failure reason); pipeline-side additionally `worktree_path`, `issue_iid`. The `session-transition` caller emits only this event and no `release_failed` sibling — a failed release there is reported to its caller as `{ ok: false, reason: 'lock-<reason>' }`, which the promotion prose must WARN on, so the stream is not the only witness. `outcome: 'already-gone'` means the lock had ALREADY vanished between `readLock()` and `release()` — the forensically interesting case, since a successful release previously left no trace at all and a missing lock was therefore indistinguishable from a lock someone else deleted (#914 residual 3) |
 | `orchestrator.session.lock.release_failed` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) | ownership matched but `release()` did NOT delete the lock (#724). Payload: `session_id`, `reason` (`fs-error`\|`session-mismatch`\|`not-deleted`\|`threw`), `caller`; pipeline-side additionally `worktree_path`, `issue_iid` |
 | `orchestrator.session.lock.reconcile_attempted` | `hooks/_lib/lock-reconcile.mjs` | SessionEnd, when NEITHER ownership check matched the recorded lock (#748). Payload: `session_id`, `action` (`reaped`\|`skipped`\|`unknown`), `reason` (e.g. `own-host-pid-alive`) |
 | `orchestrator.session.lock.reaped` | `scripts/lib/lock-reaper.mjs` | a dead lease was reaped. Payload: `session_id`, `semantic_session_id`, `host`, `pid`, `age_hours`, `reap_mode`, `current_session` |
-| `orchestrator.agent.stopped` | `hooks/on-stop.mjs` | SubagentStop |
+| `orchestrator.agent.stopped` | `hooks/on-stop.mjs` (`handleSubagentStop`) | SubagentStop, once per stopping subagent — the fleet's most frequent event (103.763 records / 19 repos, measured 2026-09-02). **Payload (#1190) — every field is OPTIONAL and the KEY IS OMITTED when the measurement could not be made; never `null`, never `'unknown'`, never a stand-in `0`/`false`:** `agent` (the stdin `agent_type`/`subagent_type`, trimmed) — **omitted when empty**, which is the #1190 fix itself: the previous `input?.agent_type ?? 'unknown'` never fired on the EMPTY STRING the harness actually sends, so 89.991 of the 103.763 historical records (86,7%) carry `agent: ""`. A consumer must read a MISSING `agent` as "the harness did not name the type", not as a broken emitter. `agent_id` (stdin `agent_id`\|`subagent_id`; opaque id, charset-guarded with `/^[A-Za-z0-9_-]{1,64}$/` before it is interpolated into any path). The remaining fields are derived from the agent's sidecar pair `<transcript-dir>/<parent-basename>/subagents/agent-<agent_id>.{jsonl,meta.json}` and are all omitted when that derivation is not possible (no `agent_id`, no `transcript_path`, or a rejected id): `transcript_found` (boolean — `false` here is a MEASURED absence, the probe ran; the key is ABSENT when it could not run), `tool_use_id` + `agent_type_meta` (from the `.meta.json` keys `toolUseId` / `agentType`; `agent_type_meta` is a SECOND witness for the type and is deliberately NOT merged into `agent`, so the empty-`agent_type` rate stays measurable), `duration_ms` + `duration_source` (`meta-birthtime` — the sidecar carries no spawn timestamp, so its birthtime IS the spawn moment; both keys omitted together when the stat fails, never a fabricated `0`), and `status` (`done`\|`partial`\|`blocked`\|`failed`\|`no-tests-needed`, from the last LINE-ANCHORED `STATUS:` marker in the final 64 KiB of the agent transcript — the anchoring rationale is `scripts/lib/wave-transcript-tail.mjs:105-112`, since a free-floating match fires on any agent that merely QUOTES the token). **`status` coverage is partial by measurement, not by accident: 61,7 %** — 71 `done` / 3 `partial` / 46 absent over **120 COMPLETED sidecars**, population: one operator's `~/.claude/projects/<this-repo>` directory, sidecars idle ≥ 30 min (`find … -path "*/subagents/agent-*.jsonl" -mmin +30 | head -120`), each read through `readStatusFromTranscriptTail`, measured 2026-09-02. Re-cut it with that command; the earlier "roughly a quarter to a half" came from an n=4 IN-FLIGHT sample and undercounted, because a running agent has not written its STATUS line yet. **An absent `status` means NOT FOUND, never success.** **Never the transcript text, the meta `description`, or an absolute path:** this payload also travels over the optional Clank webhook with no redaction — same rule as `board_written` / `session.root_left`. `session_id` / `semantic_session_id` / `schema_version` are stamped by `emitEvent()` |
 | `orchestrator.memory.propose_invoked` | `hooks/pre-bash-memory-propose-audit.mjs` | PreToolUse(Bash) |
-| `orchestrator.wave.started` / `.completed` | `hooks/post-tool-batch-wave-signal.mjs` | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612); an explicit injected `wave_signal` still takes precedence |
+| `orchestrator.wave.started` / `.completed` | `hooks/post-tool-batch-wave-signal.mjs` · `hooks/on-session-end.mjs` (`emitFinalWaveCompleted`, `.completed` only) | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612); an explicit injected `wave_signal` still takes precedence. **Second `.completed` emitter (#1193):** the batch hook closes wave N-1 only at an N-1→N transition, so the LAST wave of every session never received a completion — measured fleet-wide 2026-09-02 as **296 gaps over 296 wave runs** (1018 started vs 722 completed), exactly one missing final completion per run. SessionEnd now emits it. **Payload of that record:** `wave_number` (the `current-session.json` `last_wave`), `reason: 'session-end'`, `emitted_by: 'on-session-end'`, plus `session_id` / `semantic_session_id` — **omitted when unattested**, never fabricated. **Idempotent** via the `last_wave_completed` high-water mark in `.orchestrator/current-session.json`, written by BOTH emitters and preserved across `/clear`+compact by `on-session-start.mjs`; `last_wave` absent or `0` emits nothing (an Express-Path or coordinator-direct session never batched, and zero waves is the correct reading, not a gap). **Two gates on the SessionEnd emitter, both load-bearing:** (a) OWNERSHIP — `current-session.json` is a single repo-global file describing whichever session most recently ran SessionStart, routinely a different still-live session in a shared working copy, so the emit reuses `resolveSession()`'s `isRecordedSession` predicate; when false it emits nothing AND writes nothing, since writing the marker into a peer's file would silence the peer's own SessionEnd and preserve this very gap on the wrong session. (b) REASON — `reason === 'clear'` **and `reason === 'resume'`** are SKIPPED: the SessionEnd matcher is empty, so `/clear` fires the hook mid-wave while the LOGICAL session continues, and `on-session-start.mjs` preserves `last_wave` / `last_wave_completed` across a resume of the SAME logical session exactly as it does across a clear — so both end the HARNESS session, not the logical one. Closing the live wave on either is premature, and the preserved marker would then suppress the real completion later. Resume is the MORE common of the two (fleet n = 1498 `session.ended`, 2026-09-02: 12 `resume` vs 9 `clear`). Deliberately SessionEnd-only (`on-stop.mjs` is not mirrored) so the closed-vs-abandoned split stays measurable |
+| `orchestrator.wave.final_refused` | `hooks/on-session-end.mjs` (`emitFinalWaveCompleted` → `emitFinalRefused`, via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`, wrapped in its OWN try/catch — independent of the caller's outer catch — so a telemetry failure on one refusal can never surface as a teardown failure) | the SIBLING event to `orchestrator.wave.completed` above (#1201 Part B / Discovery D8) — fires exactly once per SessionEnd in which the final `.completed` was NOT emitted, one row per refusal. Deliberately a SEPARATE event name rather than `.completed` carrying `emitted:false`: existing consumers of `.completed` treat every row as a finished wave, and overloading it would silently corrupt that count. **Payload:** `reason` (always present, closed enum — verified against `emitFinalWaveCompleted`'s own call sites) `not-recorded` \| `clear` \| `resume` \| `unreadable` \| `session-id-mismatch` \| `no-wave` \| `already-completed` \| `exception`, `emitted_by: 'on-session-end'` (always), plus `session_id` / `semantic_session_id` — omitted when `null`, never fabricated. **Optional, absent-is-not-zero:** `wave_number` — present ONLY on the `already-completed` reason, the sole call site that passes a resolved `last_wave` through to `emitFinalRefused`; every other reason, INCLUDING `no-wave`, omits it (that path never resolved a wave number at all — the function's own JSDoc pins this: "only when `last_wave` was resolved to a positive number before the refusal (currently only `already-completed`)"). Six of the eight reasons were previously SILENT refusal paths with no trace anywhere (`.claude/rules/host-resources.md` § HR-105: "a refusal that writes nothing is unfalsifiable") |
 | `orchestrator.quality_gate.passed` / `.failed` | `scripts/run-quality-gate.mjs` (the gate CLI — live between waves) · `scripts/lib/quality-gate.mjs` (`emitGateEvent` inside `runQualityGateWithRetry`, reached ONLY under `verification-auto-fix.enabled: true` — default `false`, and `false` in this repo) | CLI: once per gate-CLI run. Library: once per `runQualityGateWithRetry` **call**, never per retry attempt (`attempts` carries that detail). The two paths never nest, so one run passes through exactly one emitter. **Payload (both):** `variant`, `exit_code`, plus `session_id` / `semantic_session_id` when `sessionAttribution()` finds a session lock (both omitted when it does not). CLI `variant` is the `--variant` value (`baseline`\|`incremental`\|`full-gate`\|`per-file`); the library pins `variant: 'auto-fix-loop'`. **CLI only:** `wave_number`. **Library only:** `attempts` (1…`maxRetries+1`) and `gate` (`lint`\|`typecheck`\|`test` — the fail-fast gate of the last attempt; omitted on the passing path). **Optional on both:** `counts: {passed, failed, total}`. **Absent is not zero — for both optional fields.** `counts` is admitted by the ONE shared policy `admitSuiteCounts()` (`scripts/lib/gates/gate-helpers.mjs`, #967 item 2), which returns `null` — never a zero triple — for an unmeasured or inconsistent input (test gate skipped/stubbed, fail-fast on lint or typecheck before the test step, no parseable `<N> passed` marker, or `passed + failed !== total`); both callers spread `...(counts ? { counts } : {})`, so the KEY is missing in those runs. A present `counts.failed: 0` therefore means "measured, zero failures", while an absent `counts` means "not measured" — reading a missing field as `0` mis-analyses the ledger in both directions. Same contract for `wave_number` (CLI, #966 step 1): resolved from the `.{pi,cursor,codex,claude}/wave-scope.json` sidecar, **omitted** — never `0` — when there is no sidecar or its `wave` is non-numeric/non-positive; a human running `npm run quality-gate` from a `git push` has no wave at all, so an invented wave 0 would have to be special-cased by every consumer. Note `total` is `passed + failed` and EXCLUDES skipped/todo (see `extractTestCounts`) |
+| `orchestrator.scope.foreign_session_ignored` | `hooks/enforce-scope.mjs` (Gate 3b, #1123) | PreToolUse Edit/Write — exactly once per gated tool call while a FOREIGN-session `wave-scope.json` is live: the manifest's `session`/`semantic_session` provably name another session, so the hook allows instead of enforcing. **Payload:** `hook`, `manifest` (path), `manifest_session` (string[]), `own_session` (string[]), `wave`, `file_path`. Legacy manifests without a `session` field never emit this — they stay enforced |
 | `orchestrator.grounding.injected` | `scripts/compute-grounding-injection.sh` (via `scripts/emit-event.mjs`) | grounding injection, when `PERSISTENCE=true` |
 | `orchestrator.handover.gated` | `skills/session-end/SKILL.md` Phase 1.65 (skill-prose, via `scripts/emit-event.mjs`) | Handover-Alignment-Gate outcome (#773). Payload: `candidates_total`, `auto_carry`, `asked`, `dropped`, `questions_asked`, `questions_answered`, `questions_deferred`, `path` (`fast_path`\|`triage`\|`weiterarbeiten`\|`fail_open`). Emitted exactly once per close — including the fail-open skip and the "Weiterarbeiten" abort — so never-measured paths become observable |
+| `orchestrator.vault.board_written` | `scripts/lib/vault-status/board-writer.mjs` (`emitBoardEvent`; name const `BOARD_EVENT`) | exactly ONE record per `mirrorBoard()` call, and therefore per `sweepBoard()` call — the sweep never double-emits. Call sites: the `mirrorBoard` wrapper through which all six inner return points funnel, and `sweepBoard`'s two paths (happy + enumeration-failure fallback). **Payload:** `action` (always — including every no-op: the five `skipped-vault-disabled` guards at `:803/:812/:817/:821/:829`, plus `skipped-handwritten`, `skipped-noop`, `skipped-write-failed`, `dry-run`, `written`), `caller` (always, `mirrorBoard`\|`sweepBoard`). **Optional, absent-is-not-zero:** `path_tail` (the BASENAME only — never the full path: under `01-projects/` the parent directory is the private project slug, and this payload also travels over the optional Clank webhook with no redaction), `rows`, `repos_swept`, `duration_ms`, plus `session_id` / `semantic_session_id` via `sessionAttribution(repoRoot)` (#1147 — the SAME root the record is pinned to, so attribution can never name a different tree than the ledger line; both keys omitted, never fabricated, when no `session.lock` is readable) — the numeric three admitted via `Number.isFinite(...)` / `typeof === 'string'`, NOT truthiness, so a measured `repos_swept: 0` survives while an unmeasured field is omitted. `lock` — an additive diagnostic object, `{ locked: boolean, reason?: string, stale_override?: string, waited_ms: number }` (snake_case like the sibling keys) — is present whenever `withBoardLock()`'s `onLockOutcome` fired, i.e. every non-dry-run path; `stale_override` carries the file-lock reason TOKEN (e.g. `mtime age 600002ms > 60000ms`) only when a stale lock was force-overridden, and the key is entirely absent on `dryRun`, which never takes the lock. This makes an unlocked fail-open write and a stale-override observable in aggregate for the first time — until now `onLockOutcome` had no production caller at all. The enumeration-failure fallback deliberately omits `repos_swept`. **A throw from the inner function emits nothing** — `action` is mandatory and a throw has no action the code knows; inventing one would put a fictional state in the ledger (#1073) |
+| `orchestrator.vault.narrative_mirrored` | `scripts/lib/vault-status/narrative-mirror.mjs` (`emitNarrativeEvent`; name const `NARRATIVE_EVENT`) | one record per `mirrorNarrative()` call, from the thin wrapper — every outcome plus the throw path (`action: 'error'`, then re-throws). The old body became `runNarrativeMirror()`, so an early return added later is telemetered by construction. Covered: `skipped-vault-disabled` ×4, `skipped-invalid-path`, `skipped-no-statemd`, `written`, `skipped-noop`, `skipped-handwritten`, `dry-run`. **Payload:** `action` (always); optional `path_tail` (BASENAME only, same reason as `board_written`), `chars`, `session_id`, `semantic_session_id` (via `sessionAttribution`), `error_code` (throw path only — the error MESSAGE is deliberately not recorded, it can quote a path or STATE.md prose). **Named gap with a revisit trigger:** when `repoRoot` is absent, NOTHING is emitted — `emitEvent` would fall back to `SO_PROJECT_DIR` and the two rootless unit tests would append synthetic records to this repo's real ledger on every suite run. This deliberately diverges from `board-writer.mjs`, which emits there (#1073) |
+| `orchestrator.vault.mirror_completed` | `scripts/lib/vault-mirror/telemetry.mjs` (`emitMirrorEvent`; name const `MIRROR_EVENT`), called from `scripts/lib/vault-mirror/process.mjs` (`emitAction`, reached from all **18** of its call sites — census `grep -n 'emitEntryAction' scripts/lib/vault-mirror/process.mjs`, 2026-08-23) and from the two `skipped-invalid` branches in `scripts/vault-mirror.mjs` | **ONE record per JSONL entry processed, EXCEPT `skipped-noop`** (#1151: noop dominates a steady-state run; its count survives in the run-event's `skipped` total + `action_breakdown`) — `created`, `updated`, every other `skipped-*`, and both invalid paths. Until #1147 it was **failure-only**: only the two `skipped-invalid` branches emitted, which is why this repo's ledger held **0** records of it against 1272 `orchestrator.secret_masker.applied` from the same CLI (measured 2026-08-23). A healthy run was therefore indistinguishable from a broken emitter — the gap the sibling `orchestrator.vault.mirror_run_completed` row below closes. **Payload:** `action` (the SAME string the entry wrote to stdout), `kind`, `line` (1-based JSONL line — the only locator when a record has no id). **Optional, absent-is-not-zero:** `record_id` (the record's `id` / `session_id`), `path` (**vault-RELATIVE**, never absolute: this payload also travels over the optional Clank webhook with no redaction — omitted on `skipped-invalid` and on the pre-path quality skips, which are reached before a target path exists), `skip_class` (`validation` | `mapper-crash`, invalid branches only — mirrors the stdout `reason` verbatim so the failure class stays groupable without string-matching), `reason` (the renderer's message on the invalid branches, or the existing `meta.reason` string on a quality skip — `confidence:X < min:Y` / `narrative:N < min:M` / `status:…` — REUSED from the stdout payload rather than recomputed; clamped to 300 chars), `dry_run`, `session_id` / `semantic_session_id`. `record_id` / `path` / `skip_class` / `reason` treat **`null` as not-measured** and are omitted: a `record_id: null` would read as "measured, empty id" rather than "this record had none". **Attribution is read at `SO_PROJECT_DIR`, explicitly** — `readLock()` defaults to `process.cwd()`, so a bare `sessionAttribution()` would attribute the record to whatever tree the process happens to run in while the ledger line lands under `CLAUDE_PROJECT_DIR`. Same root for both halves or neither. The ledger destination stays the 2-arg `emitEvent` default so every event of one run shares it: this CLI has no repo-root flag, and deriving one from `--source` would split a single run's telemetry across two ledgers |
+| `orchestrator.vault.mirror_run_completed` | `scripts/lib/vault-mirror/telemetry.mjs` (`emitMirrorRunEvent`; name const `MIRROR_RUN_EVENT`), called from `finishRun()` in `scripts/vault-mirror.mjs` — the ONE close-out function every exit routes through (the happy tail, the malformed-JSON abort, the filesystem-error abort, and the top-level `main().catch`), latched so it can only fire once | exactly ONE record per CLI run, **unconditionally** — beside the `orchestrator.secret_masker.applied` emit and BEFORE the `--strict-schema` abort, so a failing run still reports its denominator. **This event is the denominator the per-entry row above lacks:** a healthy run over an empty source emits zero per-entry records, and so does a run whose emitter is broken — from the ledger the two are identical (`.claude/rules/host-resources.md` § HR-105). **Payload:** `kind`, `total` (non-blank JSONL entries attempted), `created`, `updated`, `skipped` (every non-failure `skipped-*` class), `failed` (`skipped-invalid` — validation error or mapper crash; split out because those are the entries whose session silently ends up WITHOUT a vault note), `dry_run`. **These five counters are ALWAYS present, including as `0`** — this is the one place a written zero is the payload rather than a violation of "absent is not zero", because each was measured over the whole run; `total: 0` is a measured empty run and the record's ABSENCE is the broken-emitter signal. `created + updated + skipped + failed === total` for any run that does not abort (pinned by a test). **Optional, and the discriminator that keeps the counters honest:** `aborted` (`malformed-json` | `filesystem-error` | `unexpected-error` | `missing-vault-dir` | `vault-not-canonical` | `missing-source` (#1151: the three pre-loop exit-2 aborts now close the run out through finishRun())) — present ONLY when the run exited before its tail, absent means "ran to the end" and never "unknown". Its presence says the five counters are PARTIAL (every line after the abort was never attempted), so the classes stop partitioning `total` and that gap must be read as an abort, not as producer/consumer drift. Until it existed, the two `process.exit` calls inside the entry loop and the `main().catch` jumped straight over this emit: the runs an operator most wants counted were the ones that vanished from the ledger, in the exact shape ("no record") the paragraph above reserves for a broken emitter. **Optional:** `action_breakdown` (per-`action` counts, keyed by the same strings the entries wrote to stdout — enumerates only actions that OCCURRED, so a missing key there means zero occurrences; the always-present `total` makes that reading unambiguous, and the key itself is omitted when nothing was processed), plus `session_id` / `semantic_session_id` via the same `SO_PROJECT_DIR`-pinned `sessionAttribution` as the per-entry event |
+| `orchestrator.secret_masker.applied` | `scripts/vault-mirror.mjs` (beside the vault-mirror run) | once per vault-mirror run, unconditionally. Payload carries `channel: 'vault-mirror'`. **Undocumented until 2026-08-23, at which point it had over a thousand records** — and that omission actively misled: a census grepping event NAMES for `board\|mirror` returns 0 and reads as "the mirror emits nothing", while run-level presence was in fact already observable through THIS event's payload. Grep the `channel`, not the name |
+| `orchestrator.probes.completed` | `scripts/lib/session-start-probes.mjs` (`runSessionStartProbes`), called from `hooks/on-session-start.mjs` | once per SessionStart, after the Phase-4 measurement probes run. **This event is the whole point of #1073:** the 18 module-backed probes had **zero** mechanical callers across `hooks/`, npm scripts, CI and husky — their only caller was prose in `skills/session-start/SKILL.md` — and across the 336 session starts recorded up to 2026-08-23 there was **no banner event at all**, so whether they ever ran was unfalsifiable (`.claude/rules/host-resources.md` § HR-105). **Payload:** `total`, `ran`, `warned`, `skipped`, `errored`, `timed_out`, `duration_ms`, and `probes` — one `{id, outcome, reason?}` per probe — `reason` travels whenever one was recorded, because `module-absent` (a permanently dead entry) must be distinguishable from `network-probe-opt-in` (the intended default); `outcome` ∈ `ran-clean`\|`ran-warn`\|`ran-alert`\|`skipped`\|`timeout`\|`error`. Two invariants are asserted by tests: `total === probes.length` and `ran + skipped + errored + timed_out === total`. **The count is 18, not the 19 Phase 4 appears to list:** four Phase-4 items are prose-only measurements with no module and no entry function (SSOT freshness, quality baseline, Pencil design status, plugin freshness) — 22 measurements, 18 wireable probes. **Network probes (`ci-status`, `mirror-issues`) are excluded by default** and appear as `outcome: 'skipped', reason: 'network-probe-opt-in'` — never omitted, because omitting them would rebuild the defect one layer down. Opt in with `SO_PROBES_INCLUDE_NETWORK=1`. The grounds are measured, not assumed: `hooks/hooks.json` gives the WHOLE SessionStart hook `timeout: 5` seconds while each network probe carries its own 8 s CLI timeout, so one slow network probe alone exceeds the hook's entire budget and takes the started-event and the banner down with it; warm-and-authenticated best case measured 520 ms / 498 ms, paid on every start of every repo. **Budget:** `PROBE_BUDGET_MS = 2000`; measured median against this repo **968 ms** (5 runs, 855–1104), 130–229 ms in a fresh tmp repo. Revisit trigger: median past HALF the budget, or any single probe past the budget → move the slow probes off the hook's critical path, do NOT raise the number. **Named ceiling:** the deadline is enforced at await points, so it is hard for async/network probes and advisory for the two that shell out synchronously (`project-hygiene`, `tests-src-ratio`). Escape hatch: `SO_DISABLE_STARTUP_PROBES=1`. **Deliberately NOT gated on `enable-host-banner: false`** — that preference governs DISPLAY; gating the RUN on it would rebuild exactly the unfalsifiable blind spot this event removes |
+| `orchestrator.express_path.evaluated` | `scripts/lib/express-path.mjs` (`evaluateExpressPath`, emit in `_emitEvaluated`; name const `EXPRESS_PATH_EVENT`) | once per Phase-8.5 evaluation — **on refusal as well as activation**. Until #1119 this was unrecordable twice over: `scripts/lib/config.mjs` discarded the `express-path` key **even when the block was present** (synthetic probe: 88 keys emitted, none of them this one), and the decision lived only in `skills/session-start/phase-8-5-express-path.md` prose, so it fired only when a coordinator read that prose. Ledger evidence, measured 2026-08-23 @ `34321bc` (a count, so read it as history, not as state): **0** express events at that point, against 22 of the last 30 sessions running with no wave at all — every one of them `housekeeping`, the exact population the path targets. **Payload:** `activated` (always, boolean), `reasons` (always — the BLOCKING codes on refusal, the satisfied ones on activation; nothing short-circuits, so a refusal names every blocker and a reader can tell whether trimming the issue list alone would have helped). **Optional, absent-is-not-zero:** `enabled`, `session_type`, `task_count`, `parallel_agents_required`, plus `session_id`/`semantic_session_id` via `sessionAttribution`. An unmeasured `sessionType` or `taskCount` fails CLOSED (`reasons: ['session-type-unknown','task-count-unknown']`) — defaulting unknown scope to 0 would activate a gate-skipping path on data nobody supplied. **Four inputs, not three:** activation condition 3 carries two clauses (`≤ 3 issues` AND no parallel agents), which both condition matrices list as a non-activating row. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling through to `SO_PROJECT_DIR` — that is the wave-1 incident of this session (a probe with an unexported var wrote a synthetic record into the real fleet ledger) made structurally impossible; a regression test reproduces it. `events.mjs` is imported lazily so `config.mjs`'s 48-file import graph does not gain `platform.mjs`, which runs filesystem walk-ups at module load |
+| `orchestrator.foreign_dispatch.completed` | `scripts/lib/wave-executor/foreign-dispatch.mjs` (`dispatchForeign`, via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`) | once per foreign-model dispatch (#1150) — the replacement for `SubagentStop` telemetry, which cannot fire for a Bash-spawned `cursor-agent` child (no hook in the chain sees it). **Payload:** `model`, `role`, `ok`, `exit_code`, `timed_out`, `duration_s`, `changed_files` (count, tracked-modified ∪ untracked-new — `git diff` alone is blind to new files), `reason` (present on every refusal — `never-foreign-role`, `empty-diff`, `channel-unavailable`, `unsafe-*` — and on the failure classes of a completed run, so no failure class is reasonless), `hook_tampering` (tri-state: `true` = the child repointed/rewrote the shared `.git` hooks path, invalidates the run regardless of `ok`; `false` = fingerprint matched; absent/`null` = not measured, never read as clean), plus `session_id`/`semantic_session_id` via `sessionAttribution` (omitted, never fabricated, without a readable `session.lock`). Emitted on refusals too (`ok:false`), so a blocked dispatch is a record, not a silence |
+| `orchestrator.remote_dispatch.completed` | `scripts/lib/wave-executor/remote-dispatch.mjs` (`dispatchRemote`, via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`; name const `REMOTE_DISPATCH_EVENT`) | once per REMOTE-host dispatch over the `offload` CLI (#1160) — the sibling of `foreign_dispatch.completed` on the other channel: that one sends a task to a foreign MODEL on this machine, this one sends a task to Claude on ANOTHER machine. Same reason for existing — a Bash-spawned `offload` child fires no `SubagentStop` hook, so this is the only ledger record a remote dispatch produces. **Payload:** `host` (the `offload` alias, never a hostname or an IP), `role`, `run_id`, `ok`, `exit_code`, `duration_ms`, `patch_files` (COUNT of paths parsed from the returned patch — `+++ b/` plus the `diff --git` header, because a DELETED file's `+++` is `/dev/null`), `patch_bytes`, `reason` (present on every refusal — `never-foreign-role`, `unsafe-run-id`, `unsafe-host`, `unsafe-patch-path` — and on every failure class of a completed run: `usage-config`, `host-unreachable`, `remote-command-failed`, `sync-failed`, `timeout`, `empty-diff`, `rate-limited`, `write-lock-busy`, `channel-unavailable`; absent means success, so no failure class is reasonless), plus `session_id`/`semantic_session_id` via `sessionAttribution` (omitted, never fabricated, without a readable `session.lock`). **Emitted on refusals too** (`ok:false`, `exit_code: null`, `duration_ms: 0`, `patch_files: 0`) — a blocked dispatch is a record, not a silence, and the null exit code is what keeps "refused" distinguishable from "attempted and measured empty". **Deliberately EXCLUDED, pinned by a test:** the prompt text, the patch BODY, and `patch_path` — this payload also travels over the optional Clank webhook with no redaction, and a tmp patch path names the run id and the operator's host |
+| `orchestrator.wave_dispatch.scope_checked` | `hooks/pre-task-scope-disjoint.mjs` (name const `SCOPE_EVENT`; built by `decide()` as `verdict.telemetry`, emitted in `main()` via `emitEvent(..., {repoRoot: projectDir})` + `sessionAttribution(projectDir)`) | PreToolUse `Agent` — **once per dispatch DECISION** (#1092), awaited BEFORE the terminal `emitAllow`/`emitDeny`/`emitWarn`, all of which `process.exit()` and would discard a pending append. **Payload:** `hook`, `agent_id` (the coordinator's `description` + `subagent_type`, clamped to 120 chars), `declared_path_count`, `injected` (a `FILE-SCOPE` declaration was found AND at least one path survived parsing), `shape` (`fenced` \| `inline` \| `none` — which PARSER won, deliberately not a second spelling of `signal`: a fenced block whose lines are prose is `signal: 'unparseable', shape: 'none'`), `signal` (`marker-absent` \| `unparseable` \| `extracted` — the row-5-vs-row-6 distinction of the hook's error-class matrix), `ledger_result` (`no-scope` \| `allow` \| `allow-finished` \| `deny` \| `warn-ledger-corrupt` \| `warn-not-evaluable`), `collision_count` (collisions involving THIS dispatch, live or already-finished — `ledger_result` says which). **Optional, absent-is-not-zero:** `wave` (the number out of `waveKeyOf()`'s `w<N>` segment — **omitted, never `0`**, under the `<session>|w?|?` fallback, same contract as `quality_gate`'s `wave_number`), plus `session_id` / `semantic_session_id` via `sessionAttribution` — omitted, never fabricated, without a readable `session.lock`. **What it proves and what it does not:** that the hook SAW (or did not see) a declaration in the prompt the coordinator handed to the dispatch tool, and what the guard decided — the SEND side. It proves nothing about the block reaching the agent's context or the agent reading it; that receive-side half of #1092 stays open for want of a platform prompt-assembly boundary (`docs/scope-collision-guard.md` § 4.2). **No prompt body and no declared path is in the payload** (issue #1092 acceptance criterion 3) — counts and closed enums only, because this record also travels over the optional Clank webhook with no redaction. Rows 1–4 of the matrix emit nothing (no decision was made) and neither do the two crash rows 2/12 — a hook that fell over cannot describe itself, which is what the `GUARD INACTIVE` stderr banner is for |
+| `orchestrator.reconcile.completed` | `scripts/lib/reconcile/engine.mjs` (`emitReconcileCompleted`, called from the thin `runReconcile` wrapper; name const `RECONCILE_EVENT`) | one record per `runReconcile` call (#1192) — from the WRAPPER, so all three return points are covered: the empty short-circuit, the normal tail, and the never-throws catch. An inline emit would have missed two of them, including the empty corpus and the error path — the two runs an operator most needs recorded (`.claude/rules/host-resources.md` § HR-105). Same shape as `narrative_mirrored`'s wrapper, and the emit is try/catch-wrapped because `emitEvent` THROWS `EventValidationError`, which would otherwise break `runReconcile`'s never-throws contract. **Payload, all ALWAYS present including as `0`** (each was measured over the whole run, like `mirror_run_completed`'s counters): `trigger` (`skill` | `session-end` | `phase-skip` | `unknown` — written always, so the per-trigger denominator is complete; the two markdown callers depend on a coordinator passing it, hence the honest `unknown` default), `dry_run`, `learnings_total`, `eligible`, `proposals`, `rejected`, `capped`, `already_materialized` (`summary.alreadyMaterialized` — the REAL idempotent-skip count, #484), `written`, `duration_ms`. **Optional, absent-is-not-zero:** `targets` (the caller's effective target list; absent ⇒ none asserted), `store_records_dropped` (`summary.skipped` — absent ⇒ the candidate store was never INSPECTED: under `dryRun`, on the empty short-circuit, on the error path; a `0` there would be a false all-clear), and `aborted: 'engine-error'` + `reason` (clamped to 300 chars) — present ONLY when the never-throws guard fired; their absence means "ran to the end", never "unknown". **`dry_run` is the discriminator, not the event's absence:** the `phase-skip` caller runs dry on EVERY close and is the highest-volume trigger, so consumers filter `dry_run: false` for real runs. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling back to `SO_PROJECT_DIR` — most engine tests pass none, and the fallback would append synthetic records to the real fleet ledger on every `npm test` (#1119, same contract as `express_path.evaluated` and `narrative_mirrored`); a regression test pins it. **Engine identities — the counters are NOT a flat partition, and a live payload reads as inconsistent without them** (source: `scripts/lib/reconcile/engine.mjs:64-83`): `learnings_total === proposals + rejected`, and `capped` + `already_materialized` are DIAGNOSTIC SUB-COUNTS *inside* `rejected`, not siblings of it — each capped or already-materialized learning is also counted as rejected. Within the eligible set: `eligible − proposals − capped === already_materialized`. Worked against a live record: `learnings_total 164 = proposals 10 + rejected 154`, and `eligible 102 − proposals 10 − capped 72 = already_materialized 20` — with `capped 72` and `already_materialized 20` both sitting inside those 154. `already_materialized` is computed BEFORE the volume brake, so a terminal learning never consumes a new learning's quota. `session_id` / `semantic_session_id` / `wave` / `schema_version` are stamped by `emitEvent()` |
+| `orchestrator.evolve.completed` | `skills/evolve/SKILL.md` Phase 1 (persistence/no-session-data aborts) and Phase 3 Step 3.5 (skill-prose, via `scripts/emit-event.mjs`) | once per `/evolve analyze` run (default mode; #1200) — emitted immediately after Step 3.5's "Saved N new learnings, updated M existing. Total active: K." report, and on the two hard-abort paths that precede it (persistence disabled at Phase 1.2; no session data at Step 3.1). Until this addition `/evolve` reported completion in prose only — the whole class of `orchestrator.evolve.*` / `orchestrator.dialectic.*` events was **0 records across 164k fleet events** despite every run reporting success (#1200). **Payload (success), all FOUR counters ALWAYS present including as `0`** (same contract as `mirror_run_completed`'s counters): `appended` (new learnings written, Step 3.5(4)), `boosted` (existing learnings reinforced, Step 3.5(2)), `pruned` (`$PRUNE.archived` from the Step 3.5(5) `sweep-expired-learnings.mjs --prune` call — total entries archived this run, across every `_archive_reason`), `promoted` (always `0` from THIS call site — promotion to `public` scope is a separate CLI, `npm run share:hw-learnings -- --promote`, never invoked by `/evolve analyze` itself), `duration_ms`. **Payload (abort):** `aborted` (`persistence-disabled` \| `no-session-data`), `reason` (the abort message shown to the user, clamped to 300 chars), `duration_ms` |
+| `orchestrator.dialectic.completed` | `skills/evolve/SKILL.md` Phase 6 Step 6.4 / Step 6.5 (skill-prose, via `scripts/emit-event.mjs`) | once per `/evolve --dialectic` run (#1200) — emitted after Step 6.4's "Dialectic-derived: M deltas to USER.md, N deltas to AGENT.md…" report on both the dry-run (default) and `--apply` paths, and once per Step 6.5 error outcome (a dialectic run reaching Step 6.5 never also reaches Step 6.4, so exactly one of the two payload shapes below is emitted per run). Same fleet-zero gap as `evolve.completed` above. **Payload (success):** `mode` (`dry-run` \| `apply`), `user_deltas`, `agent_deltas`, `tokens_in`, `tokens_out`, `duration_ms`. **Payload (abort):** `aborted` (`unknown-model` \| `budget-exceeded` \| `would-empty-card` \| `empty-input` \| `subagent-crash`), `duration_ms` |
+| `orchestrator.dialectic.nudge_decided` | `scripts/lib/auto-dialectic.mjs` (`decideAndRecordAutoDialectic`, wrapping `shouldDispatchAutoDialectic` with an additive `emitEvent` call) | once per `decideAndRecordAutoDialectic()` call made with `record !== false` (#1200 part c) — the MECHANICAL sibling of the two skill-prose events above: those two cover a manual `/evolve` run, this one covers the session-end Phase 3.6.7 auto-dialectic NUDGE DECISION itself, which previously computed a trigger every close and recorded nothing. Emitted on ALL FOUR `shouldDispatchAutoDialectic()` return paths (kill-switch, no-new-input, cadence-threshold-met, under-threshold) — try/catch-wrapped, because `emitEvent()` throws `EventValidationError` on a malformed record and a telemetry failure must never change the decision the caller already has in hand. **Payload:** `decided` (boolean, mirrors `trigger` verbatim), `reason`, `cadence`, `sessions_since`, `learnings_since`, plus `session_id`/`semantic_session_id` via `sessionAttribution` (omitted, never fabricated, without a readable `session.lock`). **Deliberately never emitted** when the caller passes `record: false` — the read-only PROBE call site (`scripts/lib/session-end/phase-skip.mjs`'s Phase-3.6.x tail-skip aggregator) keeps calling the un-wrapped `shouldDispatchAutoDialectic()` directly instead, so its own documented side-effect-free contract ("reads only … writes NOTHING") is not broken by this event's write |
 
 Non-orchestrator names still present in the stream: `tmux-layout.{invoked,completed,degraded}`
-(tmux-layout skill) and `stagnation_detected`. (`grounding_injected` was migrated to
-the dotted `orchestrator.grounding.injected` in #611 — see the catalog above.)
+(tmux-layout skill) and `stagnation_detected`. The latter keeps its legacy bare name
+deliberately — it predates the `orchestrator.` convention, and renaming it in the same change
+that wired its first producer would have stacked a breaking stream change on top of a behaviour
+change (#1114). (`grounding_injected` WAS migrated, to the dotted
+`orchestrator.grounding.injected` in #611 — see the catalog above.)
+
+### `stagnation_detected` — two producers, one schema (#1114)
+
+| Producer | `source` | Trigger |
+|---|---|---|
+| Coordinator prose, `skills/wave-executor/wave-loop.md` § "Review Agent Outputs" | `"coordinator"` | post-wave review, per agent, when a stagnation pattern fires. Routed through `scripts/emit-event.mjs` / `emitEvent()` like every other event — the hand-rolled `>>` append it used to prescribe is gone |
+| `scripts/lib/wave-transcript-tail.mjs`, run as the `wave-transcript-tail` monitor (`monitors/monitors.json`, `when: on-skill-invoke:wave-executor`) | `"tail"` | live, while the wave runs: tails the own session's subagent transcripts and matches three executable regexes |
+
+**Payload:** `session` (the **SEMANTIC** session id — the value that matches
+`sessions.jsonl.session_id`, e.g. `main-2026-08-24-session-1`, measured 2026-08-25; this is the
+join key `skills/session-end/metrics-collection.md` filters on, `.session == $sid` where `$sid` is
+`$SESSION_ID`. A raw UUID here would join to nothing. The `session_id` / `semantic_session_id` pair
+that `sessionAttribution()` contributes is additive provenance beside it, and is OMITTED rather
+than fabricated when no `session.lock` is readable — so `session` is the field consumers rely on),
+`wave`, `agent`,
+`pattern`, `source`, `file` (project-relative path, or `null` when not applicable), `occurrences`.
+`pattern` ∈ `pagination-spiral` | `turn-key-repetition` | `error-echo` | `psa007-git-write` |
+`status-partial` — the first two are coordinator-only, the last two tail-only, and `error-echo` is
+produced by BOTH, so `source` is the only thing that tells those two records apart. `source` ∈
+`coordinator` | `tail` and is **additive**: a consumer that does not read it behaves unchanged.
+**Optional, absent-is-not-zero:** `error_class` (`edit-format-friction` | `scope-denied` |
+`command-blocked` | `other`) is present on `error-echo` ONLY and omitted for every other pattern —
+an absent field means "no class applies", never `"other"`. **`occurrences` is an
+AGGREGATION-WINDOW counter, not a fixed value.** Monitor output is rate-limited, so a key emits
+once when it reaches its threshold (`3` for `error-echo` and the two coordinator threshold
+patterns, `1` for the single-shot `psa007-git-write` / `status-partial`) and then RE-EMITS only
+every further `RE_EMIT_EVERY = 10` hits, carrying the running total. A single-shot detector that
+fires 21 times therefore produces `occurrences` `1`, `11`, `21` — three records, pinned by the
+`toEqual([1, 11, 21])` assertion in `tests/lib/wave-transcript-tail.test.mjs`. Read a value above the threshold as "this many hits
+so far in this window", never as "this many new hits". `agent_id` (tail-produced
+records only, additive): the per-dispatch agent id from the transcript filename — needed because
+`agent` carries the agent TYPE and a wave routinely runs several agents of one type (measured
+2026-08-25: 2 `Explore` in one wave), so restart-dedup keyed on type alone would suppress a
+sibling's genuine first finding. Coordinator-produced records omit it.
+
+**Measured before wiring — read as history, not as state.** 0 records in this repo's 30 785-line
+ledger (`grep -c '"stagnation_detected"' .orchestrator/metrics/events.jsonl` → 0, exit 1;
+2026-08-25 @ `ebce189`), and 0 across 97 816 event lines in 19 repos (asserted, source W1/D3
+2026-08-25 — re-measure before citing it further). That zero is the denominator the wiring is
+judged against (`.claude/rules/host-resources.md` § HR-105: a class at 0% is either genuinely rare
+or silently broken, and the two look identical from outside). Until #1114 the event had no
+producer at all — its only mechanical reference across `scripts/ hooks/ commands/` was a READER,
+`scripts/compute-grounding-injection.sh:88`, which filters on `error_class` + `file` and degrades
+correctly on records carrying neither. If the ledger still reads 0 after the tailer has observed
+five waves, that is a finding about the repo, not about the emitter.
+
+**Dated caveat — records written before `FIXTURE_CONTEXT_RE` are not reproducible.** The
+`psa007-git-write` record emitted 2026-08-25 ~05:01 was a false positive: a sibling agent seeding a
+test fixture in a `mktemp -d` scratch repo, whose index is not the shared one PSA-007 protects.
+`isGitWrite()` gained the fixture-context exclusion (`scripts/lib/wave-transcript-tail.mjs`) after
+that record was written, so replaying the same transcript against today's detector yields no hit.
+Read pre-exclusion `psa007-git-write` records as artefacts of the older detector — the ledger line
+stands as history and is not retracted, but it is not evidence about current behaviour. The same
+five 2026-08-25 04:59–05:01 records also carry the RAW session uuid in `session` (a bare
+`06461b1a-…` where the semantic `main-2026-08-25-session-N` belongs), which is the pre-fix shape —
+they join to no `sessions.jsonl` row and will not appear in a per-session roll-up.
 
 ## Consumers
 
 - `scripts/lib/convergence-monitor.mjs` — tails events.jsonl; reads `event_type ?? event`.
 - `scripts/lib/tmux-layout/telemetry-stats.mjs` — filters `event.startsWith('tmux-layout.')`.
 - `scripts/lib/events-rotation.mjs` — size-based archival.
-- `skills/session-end/metrics-collection.md` — jq roll-ups (incl. `orchestrator.grounding.injected`).
+- `skills/session-end/metrics-collection.md` — jq roll-ups (incl. `orchestrator.grounding.injected` and `stagnation_detected` → `stagnation_events`).
+- `scripts/compute-grounding-injection.sh` — filters `stagnation_detected` on `error_class` + `file` to build each agent's edit-friction history; ignores records carrying neither (which is every `psa007-git-write` / `status-partial` record).
 
 Renaming an existing event name is a breaking change to the stream + these
 consumers — verify with `grep` (PSA-006) and update consumers in lockstep.

package/docs/github-mirror-protection.md

@@ -0,0 +1,197 @@
+# GitHub-Mirror Branch Protection — Runbook
+
+GitLab issue #1079.
+
+## Why this matters — a mirror push IS a deploy here
+
+`.claude/rules/security.md` § "Session Config Command Trust" argues that
+commit-gated files (`test-command`, `custom-phases[].command`, …) are
+trustworthy **because** every change lands in `git log` and passes review
+before it can run. That argument depends on one premise: the path that
+**deploys** the change is the same path that **reviews** it.
+
+For this repo, that premise is broken on the GitHub mirror:
+
+```
+$ git remote -v
+origin  git@<gitlab-host>:<group>/session-orchestrator.git   # reviewed via MR
+github  https://github.com/Kanevry/session-orchestrator.git                  # pushed directly
+```
+
+- `origin` (GitLab) is the review path: every change lands via a Merge Request.
+- `github` (the mirror) is pushed **directly** by `git push github HEAD` in
+  `skills/session-end/SKILL.md` (see the `github-mirror-push` block, roughly
+  lines 781–825) — no MR, no review, no gate. Any session's `/close` does this
+  the moment a `github` remote exists (the block does not actually re-check the
+  `mirror: github` Session Config key at runtime, only the remote's presence).
+- The GitHub mirror's `main` branch is what a **Vercel Git integration**
+  deploys from. `vercel.json` in this repo sets security headers (CSP, HSTS)
+  and redirects. So a push to `github`'s `main` is not "just a mirror update"
+  — it is a production deploy of the public website, with no review gate in
+  between.
+
+A compromised mirror token, or any admin-scoped push, can therefore:
+- Remove `default-src 'self'` from the CSP — the mechanical guard behind the
+  "we make zero external requests" claim in the privacy policy, itself hosted
+  on the same domain.
+- Remove HSTS.
+- Add a wildcard redirect (`/(.*)`) to an arbitrary foreign domain.
+- Serve arbitrary HTML under the domain that also hosts the Impressum and
+  Datenschutzerklärung (German legal-notice pages).
+
+That is an escalation surface, not "just some stale mirror content".
+
+## Current measured state (2026-08-28 @ `70a1ca9`, read-only `gh api`)
+
+```json
+{
+  "repo": "Kanevry/session-orchestrator",
+  "branch": "main",
+  "enforce_admins": false,
+  "required_status_checks": { "strict": true, "contexts": ["test (ubuntu-latest)", "test (macos-latest)", "security"] },
+  "required_pull_request_reviews": false,
+  "allow_force_pushes": false,
+  "token_scopes": ["admin:public_key", "gist", "read:org", "repo", "workflow"],
+  "findings": [
+    { "id": "enforce-admins-disabled", "severity": "high", "message": "enforce_admins is false — an admin-scoped push (or token) bypasses required_status_checks entirely." },
+    { "id": "token-scope-too-broad", "severity": "medium", "message": "Token scope(s) admin:public_key, repo exceed what a mirror push needs (fine-grained contents:write on this one repo)." }
+  ]
+}
+```
+
+Reproduce with `node scripts/github-protection-audit.mjs` (see § Running the audit below).
+
+Reading this: required status checks ARE configured (3 contexts, `strict:
+true`) and force pushes are already disallowed — those two controls are
+sound. The gap is `enforce_admins: false`: **the checks above only bind
+non-admin pushes.** The mirror push in `skills/session-end/SKILL.md` runs
+under the same `gh`/git identity that authenticated the CLI — whatever scope
+that identity's token carries, an admin-scoped credential sails straight past
+`required_status_checks` because `enforce_admins` is off. Combined with the
+current token scopes (`repo` is full read/write across every repo the
+account can see, not scoped to this one), the blast radius of a leaked token
+is "push anything to `main`, unreviewed, checks or no checks."
+
+**Operator decision for this session (2026-08-28):** audit + runbook only.
+`enforce_admins` stays `false` and the token is not rotated or narrowed in
+this session — see § Required order below for why flipping it first would be
+actively harmful, and do these steps in order, not this one alone.
+
+## Required order — do not skip ahead
+
+Flipping `enforce_admins: true` **before** fixing the push path is a
+self-lockout: the mirror push in `skills/session-end/SKILL.md` runs
+`git push github HEAD` directly against `main` under an admin-scoped
+identity. With `enforce_admins: true` and `required_status_checks` set, that
+push would need `main`'s HEAD to already carry a green status check for the
+exact SHA being pushed — which a bare `git push` from a local mirror step can
+never satisfy (there is no PR, so no check run is ever attached to that SHA
+before the push happens). The next `/close` would fail outright.
+
+So the order is load-bearing, not a suggestion:
+
+### Step 1 (repo change, reviewable via MR) — stop pushing straight to protected `main`
+
+Change the `github-mirror-push` block in `skills/session-end/SKILL.md` so it
+no longer writes `main` directly. Two options, either is acceptable:
+
+- **Option A — branch + PR.** Push to `mirror/<date>` (or `mirror/<session-id>`)
+  instead of `main`, then open (or auto-merge, if the repo's protection allows
+  it later) a PR. Keeps the mirror push mechanism simple; adds a PR per close.
+- **Option B — deploy-key / bot identity with an explicit admin bypass.** Use a
+  dedicated deploy key or GitHub App installation scoped to `contents:write`
+  on this one repo, and add that bot identity to the branch protection's
+  "allow specified actors to bypass required pull requests" list (GitHub
+  Enterprise/Team feature — verify plan tier supports it before committing to
+  this path). Keeps the direct-push mechanism but makes the bypass an
+  explicit, auditable allowlist entry instead of "any admin token".
+
+This step is a normal code change — it goes through the GitLab MR review path
+like everything else in this repo. It is **not** a `gh api` operator action.
+
+### Step 2 (operator action) — narrow the token
+
+Once Step 1 lands (the push path no longer needs a broad admin-capable
+token), narrow what actually authenticates the mirror push:
+
+```bash
+# operator action — create a fine-grained PAT
+# 1. https://github.com/settings/tokens?type=beta
+# 2. Resource owner: Kanevry (or the account that owns the mirror)
+# 3. Repository access: "Only select repositories" → session-orchestrator
+# 4. Permissions: Contents → Read and write (this is the ONLY permission the
+#    mirror push needs). Leave every other permission at "No access".
+# 5. Set an expiration (this repo's Vercel-deploy blast radius argues for a
+#    short one, e.g. 90 days, with a calendar reminder to rotate).
+
+# operator action — verify the new token's actual scope before swapping it in
+gh auth status --hostname github.com
+
+# operator action — re-point the local git credential helper / gh auth login
+# at the new token, then re-run the audit script to confirm the scope finding
+# clears:
+node scripts/github-protection-audit.mjs
+```
+
+A fine-grained PAT reports differently from a classic PAT under
+`gh auth status` (no bracketed scope list — fine-grained tokens carry their
+permissions server-side, not as a local scope string). If `token_scopes`
+comes back empty for a fine-grained token, treat that as expected, not as a
+`parse-error` — the audit script's `token-scope-too-broad` finding is
+evaluated against the classic-scope list (`UNSAFE_TOKEN_SCOPES` in
+`scripts/github-protection-audit.mjs`) and does not currently classify
+fine-grained-token permissions; a human check of the token's configured
+permissions (step 4 above) is still required after this step.
+
+### Step 3 (operator action) — only now enable `enforce_admins`
+
+```bash
+# operator action — flip enforce_admins on, now that step 1 removed the
+# only path that needed to bypass it and step 2 has already narrowed the
+# credential that authenticates any remaining admin-scoped access.
+gh api -X POST repos/Kanevry/session-orchestrator/branches/main/protection/enforce_admins
+
+# operator action — verify
+node scripts/github-protection-audit.mjs
+# expect: "enforce_admins": true, and the "enforce-admins-disabled" finding
+# gone from the findings array.
+```
+
+Do not run this command until Steps 1 and 2 are both confirmed — that is the
+entire point of the ordering above.
+
+## Running the audit
+
+```bash
+node scripts/github-protection-audit.mjs
+```
+
+Read-only. Never calls `gh api -X PUT/PATCH/DELETE`, never touches the token.
+Prints exactly one JSON object on stdout:
+
+- **Success** (branch protection was measured, whether or not it found
+  anything to flag): the full envelope — `repo`, `branch`, `enforce_admins`,
+  `required_status_checks`, `required_pull_request_reviews`,
+  `allow_force_pushes`, `token_scopes`, and a `findings` array (may be empty
+  — an empty array means "measured and clean", not "did not check"). Exit
+  code `0`.
+- **Degraded** (the measurement itself could not be taken — `gh` missing, not
+  authenticated, timed out, or a query error): `{ "degraded": "<reason>",
+  "message": "..." }`. Exit code `2`. **Never read a degraded result as
+  "clean" — it means the audit could not run, not that nothing was found.**
+  `degraded` reasons: `no-github-remote`, `cli-missing`, `timeout`,
+  `auth-error`, `parse-error`, `query-failed`.
+
+Findings the script currently emits:
+
+| id | severity | fires when |
+|---|---|---|
+| `branch-not-protected` | critical | the branch has NO protection configured at all (HTTP 404 from the protection endpoint) |
+| `enforce-admins-disabled` | high | `enforce_admins.enabled` is `false` |
+| `token-scope-too-broad` | medium | the authenticated token carries a classic scope broader than a mirror push needs (`repo`, `admin:org`, `admin:repo_hook`, `admin:public_key`, `admin:enterprise`, `delete_repo`, `site_admin`) |
+| `no-required-status-checks` | medium | `required_status_checks` is absent or configured with zero contexts |
+
+Run it any time you change branch protection, rotate the mirror token, or
+touch the `github-mirror-push` block in `skills/session-end/SKILL.md` — it is
+the fastest way to confirm a change had the intended effect without hand
+re-deriving the `gh api` output.