# Events Schema & Naming Convention

The orchestrator emits **one** structured telemetry stream:
`.orchestrator/metrics/events.jsonl` (append-only NDJSON). There is no second
stream — `actions.jsonl` does not exist. Size-based rotation is handled once per
session at SessionStart (`events-rotation.mjs`).

## Canonical record shape

Every record is a single JSON line of the form:

```json
{ "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
`scripts/lib/events.mjs`** — never by hand-writing JSONL with `appendFile`/`jq`.
`emitEvent()` writes the canonical record AND fires the optional Clank Event Bus
webhook (when `CLANK_EVENT_SECRET` + `CLANK_EVENT_URL` are set) with the **same**
event name on both sides. Hand-rolled appenders drift: the JSONL and the webhook
end up with different names (the `stop` vs `orchestrator.session.stopped`
divergence that issue #609 fixed).

Shell and other non-Node emitters MUST route through the **`scripts/emit-event.mjs`**
CLI (`--type <name> --payload <json>` + optional `--file <path>`, plus `--json`/`--help`),
which wraps `emitEvent()` so they inherit the same canonical record + webhook fan-out
instead of `jq >> events.jsonl`. For callers that manage their own stream path,
`emitEvent(type, payload, { filePath })` accepts an additive optional path override
(default = the resolved `eventsFilePath()`); existing two-argument callers are unchanged.

## Quality-gate wave metrics consumers

The readers are two skill readers,
[`wave-loop-review.md` step 7](../skills/wave-executor/references/wave-loop-review.md)
and [`metrics-collection.md` § 1.7](../skills/session-end/metrics-collection.md),
and the convergence monitor (`scripts/lib/convergence-monitor.mjs`), which folds
`counts` only from gate records that also carry `wave_number`.
The two skill readers read `orchestrator.quality_gate.{passed,failed}` as flat
records, filtering by the existing own `semantic_session_id` and `wave_number`, then taking the
last matching record with `counts`. `counts.passed` supplies `suite_passed`;
`counts.failed` supplies `suite_failed`. Their identical jq selectors exclude
other sessions, other waves, and unrelated events without a time-window join.
They read the ledger raw (`jq -R` with `fromjson? | objects`), so an unreadable
line such as a torn tail is skipped instead of aborting `jq`. The old parsed-input
pipeline could emit an earlier matching value before a parse error; `tail -1`
then retained that stale value, and its success could hide the nonzero jq exit.
Known limit: if `appendFile` is interrupted mid-record, `fromjson?` discards the
whole truncated line, so `tail -1` can still return an older matching run. That
value alone does not establish the current gate result.
An event without `semantic_session_id` (emitters set it only from the session lock)
never matches and is treated like a gate outside the event wrapper.

Both emitters supply the same optional counts and wave keys: the CLI emits once
per CLI run; the library emits once per `runQualityGateWithRetry` call, never
per retry (`attempts` describes retries). Missing `counts` or `wave_number` stays
absent, never zero-filled. An empty selector or an event without counts, such
as fail-fast before the test suite, does not alone permit count fallback.
Telemetry remains best-effort; emission does not change gate exits or verdicts.
The event-name and reporting-variant contracts in the catalogue below still apply.

An empty counts selector cannot distinguish a missing event, missing wave attribution,
or an attributed event without counts after fail-fast. Inspect the own session's
records without the counts filter before deciding whether a documented count
fallback case applies:

```bash
jq -cR --argjson w "$WAVE" --arg s "$SEMANTIC_SESSION_ID" '
  fromjson? | objects
  | select((.event | type) == "string" and (.event | startswith("orchestrator.quality_gate.")))
  | select(.semantic_session_id == $s)
  | select(.wave_number == $w or .wave_number == null)
  | {event, semantic_session_id, wave_number, counts}
' .orchestrator/metrics/events.jsonl
```

This is a diagnostic, not a replacement counts source. No rows means no readable
matching event; a row without `wave_number` is not proof of this wave's run;
a row for this wave without `counts` supplies no measurement. Keep the session
filter and never copy counts from another session or wave, or from a row without
wave attribution. An event without `semantic_session_id` is not attributable by
this query either; diagnose missing session attribution from independent evidence
of the own gate run, not by adopting an unrelated unattributed event. Missing
attribution or an empty result alone does not prove a fallback source exists.

Count fallback is limited to three cases: pre-#954 sessions, a gate outside the
event wrapper, or missing wave attribution. Its source differs by reader: step 7
runs before § 3a writes this wave's header and falls back to the output of this
wave's own gate run; session end falls back to the STATE.md Wave History header
`— suite <passed>/<failed> on <platform>`.
An auto-fix call with a known wave uses the event selector. When neither an event
measurement nor an applicable count fallback supplies counts, omit the two
count fields: absence means unmeasured; a present zero means measured zero.

`suite_platform` comes separately from the platform of this wave's gate run
(step 7) or the header that run wrote (session end); there is **no platform field
in the event payload**. Omit it without such a measurement, and never infer it
from `variant`. Event-derived
counts may still be mirrored into the existing header as compatibility output,
not a second measurement source. Header and sessions.jsonl contracts are unchanged.

## Naming convention

Orchestrator-owned events use a dotted namespace:

```
orchestrator.<domain>.<verb>[.<sub>]
```

- lowercase alphanumeric segments; `_` allowed *within* a segment (`quality_gate`, `propose_invoked`);
- at least three segments (`orchestrator` + domain + verb).

Third-party / IDE events (e.g. `tmux-layout.*`) and not-yet-migrated legacy names
are accepted as-is — the convention is enforced only on the `orchestrator.`
namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
(`validateEventRecord`, `ORCHESTRATOR_EVENT_RE`), covered by
`tests/lib/events-schema.test.mjs`.

## Event catalog

| Event | Emitter | Hook / trigger |
|---|---|---|
| `orchestrator.session.started` | `hooks/on-session-start.mjs` | SessionStart. **Additive (#1650, 2026-10-17):** `recent_starts_count` (number) — foreign session-registry entries whose `started_at` lies within the last `recent_starts_window_min` minutes (number, currently `5`); self excluded, always present. The start-wave signal: the banner's WARN icon fires at `recent_starts_count >= 5` instead of on `peer_count`, which stays reported as information. Report only — it caps nothing (HR-104). **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). **Optional, additive (#1091, 2026-09-09):** `native_source` (string) — the harness-supplied SessionStart `source` (`startup` \| `resume` \| `clear` \| `compact` on Claude Code; other harnesses' enums pass through verbatim), OMITTED when stdin carries no `source`, never `null`/`""`. Measurement only: it makes "does the same raw `session_id` repeat under `source: resume`?" answerable from this ledger; no continuity logic reads it. The Claude Code matcher in `hooks/hooks.json` was widened to `startup\|resume\|clear\|compact` in the same change — before it, a native resume never invoked this hook at all. **Consequently, since this matcher widening (2026-09-09), this row fires once per SessionStart SOURCE, not once per logical session** — a session that resumes N times contributes N rows, so count DISTINCT `session_id` values to count sessions, and read `native_source` to tell which source produced each row. Companion field `resume_linkage` (`raw-id` \| `semantic` \| `none`, omitted together with `native_source`): `raw-id` = the stdin `session_id` equals the one in `current-session.json`, so the prior semantic id is REUSED and the wave high-water marks (`last_wave`, `last_batch`, `wave_start_sha`) are preserved; `semantic` = the pre-existing semantic-match branch; `none` = unverified restart, fresh id, no preservation (the #1091 contract: never guess continuity). **Optional, additive (#1443, 2026-09-25):** `head_sha` (string) — the full commit SHA of `HEAD` in the project root at SessionStart (`git rev-parse HEAD`; 40 hex, 64 on a SHA-256 repository), OMITTED when it cannot be measured (no repository, unborn `HEAD`, git unavailable), never `null`/`""`. `scripts/emit-session.mjs` reads it as the fallback for `session_start_ref` when STATE.md carries no `session-start-ref` — from the FIRST row whose `session_id` is the session's own raw id, never a later resume/compact row (a first row without `head_sha` yields no ref rather than a later row's sha), and never when the session's own registry entry shows `work_root` ≠ `session_root` (#1652 — the sha was measured in the SessionStart root, not the tree the session works in; omitted with a WARN); no usable sha from either source → the field is omitted with a WARN. **Optional, additive (#1668, 2026-10-17):** `upstream_sha` (string, full sha of `@{u}`) and `behind` (non-negative integer, `git rev-list --count HEAD..@{u}`) — read from LOCAL refs only (no fetch, 1 s bound per call), written together or OMITTED together (no upstream, timeout, unparseable output), never `0`/`null` as a stand-in for "not measured". `scripts/emit-session.mjs` drops the `head_sha` fallback ref with a WARN when `behind > 0` is measured: after a pull, `<head_sha>..HEAD` would also list the pulled-in upstream commits, and no sha known at session start (merge-base included, which equals `head_sha` for a checkout that is merely behind) bounds the range correctly. `behind: 0` and rows without the fields keep the previous behaviour |
| `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.telemetry.flush` | `hooks/on-session-end.mjs` (`flushTelemetry()`; result shaped by `classifyFlush()`) | SessionEnd, exactly once per teardown and LAST (#1138) — after backfill, lock release and deregistration are durable, because it is the only step that may touch the network. Emitted whatever the outcome. **Payload:** exactly `outcome`, `reason` and `reason_class` — no queue payload, no anon id — plus the `session_id` / `semantic_session_id` / `wave` / `schema_version` envelope `emitEvent()` stamps. `outcome`: `sent`, `queued`, `gated` or `skipped`. `reason`: `flush()`'s own reason IN FULL, bounded to `FLUSH_REASON_MAX_CHARS` (200) — so a sandbox refusal is written as `sandbox:temp-root`, not `sandbox` — or `persistence-disabled` (Session Config `persistence: false`; `flush()` is never called), or `error` (`flush()` threw). `reason_class`: the head token before the first `:` (`sandbox`, `gated`, `build-error`, `persistence-disabled`, `error`), for aggregation. **Until #1392 (2026-09-20) `classifyFlush()` CUT `reason` at its first `:`, so the health banner's `startsWith('sandbox:')` predicate could never match a record from this emitter** — the wire is now proven by `tests/hooks/on-session-end.test.mjs` § "telemetry-flush breadcrumb → flush-health banner (wiring, #1392)", which drives a real `flush()` refusal through the real writer into the real banner. Readers: `scripts/lib/telemetry-flush-health-banner.mjs` via its `session-start-probes.mjs` registry entry (newest record; warns on a `reason` starting with `sandbox:`), and `scripts/lib/sessions-staleness-banner.mjs`, which SKIPS it as a closing diagnostic |
| `orchestrator.turn.stopped` | `hooks/on-stop.mjs` (`handleStop`) | Stop, once per ASSISTANT TURN. **The canonical name for this event since 2026-09-06 (GitLab #1234); payload identical to the deprecated `orchestrator.session.stopped` row below, minus its `deprecated` marker.** **Why the rename:** the old name says *session*, the emitter fires per *turn*. Measured 2026-09-06 over the 90-day fleet window: **15.538 records against 2.016 distinct `orchestrator.session.started` ids = 7,7 per session**, with **184 for a single id**. Six consumers read it as a session-lifecycle signal and were therefore wrong by that factor — any "sessions stopped" count derived from it is a turn count. **A turn is not a session, and the count is not a rate:** to count sessions, count `session.started` ids; to count closes, count `sessions.jsonl` records with `status: completed`. **Migration:** both names carry the same payload for one generation; the legacy name additionally carries `deprecated: true`. Removal of `orchestrator.session.stopped`: **2027-03-06**. Readers should switch the name they match on and change nothing else. **NOT affected:** the SubagentStop branch keeps emitting `orchestrator.agent.stopped` — a different event whose per-agent cardinality is correct |
| `orchestrator.session.stopped` | `hooks/on-stop.mjs` (`handleStop`) | Stop. **Payload:** `session_id`, `semantic_session_id`, `wave`, optional `branch` / `commit`, optional `reaper_trigger` (`throttled` \| `spawned` \| `spawned-unthrottled` \| `error` — the outcome `maybeTriggerOrphanScan()` from `scripts/lib/orphan-reaper/trigger.mjs` returned for THIS fire; the key is ABSENT when `reaper.enabled` is false, which is configuration, not a measurement — and when the project dir cannot be resolved (no `*_PROJECT_DIR` and a deleted cwd): no config can be read then, so the trigger answers `disabled`, never `error` (#1498); `spawned-unthrottled` is a throttle marker the trigger could not stamp, and the healthy values are recorded too so it has a denominator — #1489 Pkt 10, HR-105/HR-106), 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. **DEPRECATED since 2026-09-06 (GitLab #1234), removal 2027-03-06** — superseded by `orchestrator.turn.stopped` above, which carries the identical payload under the name that matches what the emitter actually measures. Every record emitted under this name since the rename additionally carries `deprecated: true`, so a reader can tell at a glance that it matched the legacy name; a record WITHOUT that key predates 2026-09-06. Both names are emitted from the same payload object, so they can never disagree |
| `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`\|`skipped-key-occupied`\|`unknown`; `skipped-key-occupied` (#1388 P8) is the key-occupancy guard — the closing session's own identity was classified absent, yet a canonical non-stub record of a DIFFERENT session already holds `record_id`, so appending would have displaced it — distinct from `skipped-already-recorded`, which means this very session is already on file), 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.work_tree` | `hooks/pre-bash-staging-fence.mjs` (`recordWorkTrees`) | PreToolUse(Bash), BEFORE every `git commit` the command contains, for coordinator and wave agents alike (#1659). One record per commit and per targeted tree; the reader dedupes. **Payload:** `session_id` (the RAW harness id — a dispatched subagent carries the coordinator's raw id, so its commits count for the coordinator), `tree` (realpath of the commit's toplevel, resolved from the hook cwd, `cd <dir>` statements and `git -C <dir>`), `start_ref` (that tree's full `HEAD` sha before the commit). Reader: `scripts/lib/session-work-trees.mjs` (`readSessionWorkTrees`, first record per tree wins; `sessionCommitFiles` diffs each tree only inside itself), surfaced by `scripts/session-commit-files.mjs`. **Not recorded:** commits nested in `bash -c "…"`, a `cd` operand needing shell expansion, any commit after `pushd`/`popd`/`chdir`/`builtin cd` in the same command (directory unknown), the first commit on an unborn HEAD, anything while `SO_DISABLED_HOOKS=pre-bash-staging-fence`. Codex sessions record too since #1669 (the fence is wired in `hooks/hooks-codex.json`). **Misattributed:** subshell scope is not modelled — in `(cd x && git commit); git commit` the second commit is recorded for `x` too. A commit inside `$( … )` or backticks is judged after all outer statements (the lexer hoists the body, #1667): it is recorded for the start directory when no outer statement changed directory, and NOT recorded otherwise (#1670), so `echo $(git commit) && cd sub` never lands on `sub` |
| `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.fleet.checkin` | `scripts/fleet-checkin.mjs` | session-start Phase 7.6 / operations-contract peer preflight (#1462), once per written check-in. Payload: `session`, `repo`, `modus`, `kandidaten`, `navigator_state` (`active`\|`none`\|`unreadable`), plus the `emitEvent()` envelope. Never paths, quota or `auftrag_ref` |
| `orchestrator.fleet.checkin_rejected` | `scripts/fleet-checkin.mjs` | once per check-in whose semantic-id file was refused (#1839): `occupied` (another repo's check-in holds `checkin/<session>.json`) or `changed` (the target changed during the ownership check, fail-closed). With `occupied` and a native `session_uuid`, the CLI retries once under `checkin/<session_uuid>.json`; `fallback: 'uuid'` means that write succeeded (exit 0), `none` means nothing was written (exit 2, or exit 1 when the retry hit a write error). Payload: `session`, `repo`, `reason` (`occupied`\|`changed`), `fallback` (`uuid`\|`none`), plus the `emitEvent()` envelope. Never paths. Makes the cross-repo collision rate measurable — before it, a refusal exited 2 without any record |
| `orchestrator.session.lock.acquired` | `hooks/_lib/lock-bootstrap.mjs` | SessionStart. Payload: `session_id`, `semantic_session_id`, `mode`, `pid`, `host`, `ttl_hours`; `foreign_work_root` (`true`\|`false`\|`null`, #1636 Pkt 2) — a fresh registry peer works in this checkout while its lock sits in another one (ExitWorktree, #1634), `null` when the registry could not be read; a measurement for HR-101 before any conflict banner, absent only when its reader failed to load; `reclaimed` (`stale-heartbeat`\|`corrupt`\|`own-process`) only when this start took over a FOREIGN stale lock, an unparseable one, or (`own-process`, #1641) the live lock of its own predecessor in the same Claude Code process after `/clear` (a session re-acquiring its own stale lock under the same raw id is a refresh and carries no key) — the bootstrap's stderr WARN is discarded by the harness, so this key counts the takeovers that went through the FORCE path — not every takeover: a start whose FIRST `acquire()` runs while a rival holds the stale lock in its tombstone finds the path empty, creates its lock as on a fresh start and emits a bare `lock.acquired` (no `reclaimed`), while the rival loses its create and emits nothing (reproduced deterministically; seen in 3 of 220 two-racer trials by the #1494 review, 2026-10-02). The takeover is single-winner since #1494: of two starts that reclaim the same lock at once, the loser emits nothing here, gets `active` with the winner's lock and records `conflict_with_session_id` in `.orchestrator/current-session.json` — so two `reclaimed` records for one checkout within a second mean the race is back |
| `orchestrator.session.lock.released` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) · `scripts/lib/session-transition.mjs` (`leaveSourceRoot`) · `scripts/release-session-lock.mjs` (#1395, the verifying CLI that session-end Phase 3.8 invokes; `caller: 'session-end-phase-3-8'`, both ids passed EXPLICITLY because the lock is gone before the emit, and NO event on `outcome: 'absent'`) | after a `release()` that matched ownership (#952). **The fourth producer exists because Phase 3.8 was PROSE:** the coordinator deleted the lock by hand, so the SessionEnd hook later found `status: 'absent'` and emitted nothing — measured 2026-09-19 in this repo, 5 `lock.acquired` against 0 `lock.released`, and fleet-wide 110 terminal events against 702 acquisitions (15,7 %). Payload: `session_id`, `caller` (`on-session-end`\|`worktree-pipeline`\|`session-transition`\|`session-end-phase-3-8`), `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.read_anomaly` | `hooks/on-session-end.mjs` (teardown step (b), via `readLockDetailed()` from `scripts/lib/session-lock.mjs`); `hooks/_lib/lock-bootstrap.mjs` (SessionStart, `unreadable` only, #1494) | SessionStart emits it once when `acquire()` answers `unreadable`: the lock path exists but cannot be read, so the session runs without a lock (payload as below; `session_id` is the starting session's raw id). SessionEnd, at most once, when `.orchestrator/session.lock` EXISTS but cannot be used: the read failed with anything but ENOENT (`unreadable` — e.g. EISDIR, EACCES), or the content does not parse as a lock (`corrupt`). Neither release nor reconciliation runs then; before this event an unusable lock was indistinguishable from "no lock". **Payload:** `session_id` (the ending session's id as `resolveSession()` resolves it — the raw stdin id, falling back to the one `.orchestrator/current-session.json` records; `null` when neither names one), `status` (`'unreadable'` or `'corrupt'`), and `error` for `unreadable` only (the raw `err.message` — for an open failure it contains the absolute lock path). Because the payload supplies `session_id`, `emitEvent()` stamps NO `semantic_session_id` (a caller key suppresses the whole correlation envelope). An error path, so 0 records is a correct reading (this repo's `events.jsonl{.1,}`, 2026-09-19: 0). `scripts/lib/session-transition.mjs` deliberately does NOT emit it — it returns `lock-unreadable` / `lock-corrupt` to a caller that must WARN. Read only by `scripts/lib/sessions-staleness-banner.mjs`, which SKIPS it as a closing diagnostic |
| `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` (`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). `reaper_trigger` (same contract as on `orchestrator.session.stopped` above: the trigger outcome of this SubagentStop fire, absent while the reaper is disabled or the project dir cannot be resolved). 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), once per `node … memory-propose.mjs …` invocation the G3 regex matches — observe-only, the hook never denies. **Payload:** `session_id` (or `null`), `wave`, `cwd` (the working directory RELATIVE to the resolved project dir — `.` when equal, `scripts/lib` from a subdirectory; a directory OUTSIDE the project is written as `sha256:<12 hex>` of its resolved path, and so is EVERY cwd when the project dir is the filesystem root, the home dir or an ancestor of it (`/Users`), where the relative form would read `Users/<name>/…`; that 12-hex sha256 prefix is PSEUDONYMISATION, not anonymisation — a guessable path (a home dir, a usual checkout location) is recovered offline by hashing candidates; **never an absolute path** — until 2026-09-25 (#1439) it was `process.cwd()` verbatim, i.e. the operator's home path in an `events.jsonl` line; zero production readers), `exit_code` (always `null` — a PreToolUse hook runs BEFORE the command), plus the #1415 argv summary: `command_hash` (**sha256 of the RAW command, truncated to 16 hex — same recipe as `enforce-commands` after `8f15f77b`; never the command text**), `flags_present` (string[], the subset of `memory-propose.mjs`'s OWN flag NAMES — `type`, `subject`, `insight`, `evidence`, `confidence`, `dry-run`, `file-paths`, `help` — present in the command, in that fixed order; built by intersecting a CLOSED list, never by scraping `--\S+`, so a flag-shaped VALUE can never be reported as a flag) and `argv_length` (number, the raw command's character count). Until 2026-09-21 this row carried `argv_truncated`: 512 characters of command TEXT, redacted only per-VALUE for five flags, whose own caveat named its gaps (`--insight=$VAR`, `--insight=$(cat secret)`, a secret written anywhere else on the line). It went into an `events.jsonl` line (gitignored here via `.gitignore:57`; consumer repos may track it) and, with the Clank webhook configured, onto the network. **Measured 2026-09-21** (`rg argv_truncated` over `scripts/ hooks/ skills/ docs/`): **zero production readers** — the field's only consumers were this hook's own tests. Pinned in `tests/hooks/pre-bash-memory-propose-audit.test.mjs` in BOTH directions (summary fields present AND `argv_truncated`/`command` undefined), plus a negative test that string-searches the serialized record for every sentinel value — so nobody puts the raw field back beside the hash |
| `orchestrator.wave.completed` | `hooks/post-tool-batch-wave-signal.mjs` · `hooks/on-session-end.mjs` (`emitFinalWaveCompleted`) | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612), closing wave N at the N→N+1 transition; an explicit injected `wave_signal: 'wave-complete'` still takes precedence. **The former `started` sibling was REMOVED 2026-09-19** (operator decision, #1202 §11): it carried no measurement, its only reader was `scripts/lib/convergence-monitor.mjs`, and there it cost the one signal it could not feed — the batch hook wrote it in the same millisecond as completed{N}, so both shared a tail tick and it masked the (N-1, N) `shrinking_diff` pair. An injected `wave_signal: 'wave-start'` is still accepted and emits nothing; historical records stay in the ledgers and nothing reads them. **Re-emission ceiling (open):** a session that does not own `.orchestrator/current-session.json` never advances the marks below, so each of its batches re-emits completed{lastWave} until its own SessionStart takes the file over — measured 2026-09-19 as up to 579 emissions for one (session_id, wave_number) group. **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. **Diff-size keys on the BATCH-HOOK emitter only (#980):** `files_changed` (integer) + `files_changed_source: 'worktree-vs-wave-start-sha'` (the only value emitted today; present iff `files_changed` is). Measurement: the DEDUPED union of `git diff --name-only <wave_start_sha>` and `git ls-files --others --exclude-standard`, run in the project dir at the N→N+1 transition, where `wave_start_sha` is the `git rev-parse HEAD` the batch hook persisted into `.orchestrator/current-session.json` when wave N was OPENED (same ownership gate as the wave keys; written as `null` when git is unreadable, so a previous wave's sha can never inflate the next count). Worktree-vs-sha rather than `<sha>..HEAD` because the coordinator commits at session close, not per wave — a commit-only diff reads 0 for every wave of a normal session. **Both keys are OPTIONAL and absent-is-not-zero:** any git failure, a 1.5 s timeout, or a missing `wave_start_sha` omits them, and `scripts/lib/convergence-monitor.mjs` reads an absent key as `null`, so the `shrinking_diff` signal simply does not fire (it never reads a fabricated 0). The `on-session-end.mjs` final-wave `.completed` carries NEITHER key by design — no wave-open transition runs there, so it has no start sha to measure against |
| `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. **Name (CLI, #1459, 2026-10-01):** `.failed` when `exit_code` ≠ 0 OR the joined kill fields say `timed_out: true`, in every variant. The reporting variants (`baseline` \| `incremental` \| `per-file`) exit 0 even after a failing check, so for them `.passed` means "not killed", not "checks green" — the check verdict lives in the gate output, not in the event name. **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'`. **Pre-push emitters (outside the CLI):** `scripts/lib/pre-push-remote-gate.mjs` (`variant: 'full-gate'`, plus `remote_host`, `host`, `host_source`, `pushed_sha`) and `scripts/lib/pre-push-local-partial.mjs` (#1642, `variant: 'local-partial'`, `host: 'local'`, `host_source: 'fallback'`, `pushed_sha`, `base_sha`, `changed_count`, and `failed_checks` — a subset of `typecheck`\|`lint`\|`test` — only on `.failed`). `local-partial` blocks on red like `full-gate` but checks only the changed files, so gate-health (`variant == 'full-gate'`) does not count it; verification-evidence counts it like every other variant, because it is a blocking check that ran (#1643). **Both emitters:** optional `wave_number` (positive safe integer from the running own-session manifest at the event root). **CLI only, `full-gate --receipt` (#1897):** `reused_from` (`{tree, at}` — the suite did NOT run: a receipt for the identical content tree `tree` and gate definition, written at `at`, stood in for it; the envelope, `counts` and `failed_files` are that run's, the kill fields say nothing was spawned; **omitted** on every executed run). **CLI only:** `failed_files` (string[] — the failing test FILES `gate-full.mjs` names when the runner printed a file-level summary; **omitted, never `[]`**, when nothing named a file — an empty array would read as "no file failed"). **CLI and remote pre-push route, `full-gate` only (#1673):** `rerun` (`{files: string[], status: 'pass'|'fail'}` — the timeout-only failures `gate-full.mjs` re-ran serially and how that re-run ended; **omitted** when nothing was re-run). Beside `rerun.status: 'pass'` the event is `.passed` while `counts.failed` and `failed_files` still describe the first, parallel run. **Same two emitters, `full-gate` only (#1673 telemetry):** `rerun_skipped` (string — why a RED test step got NO serial re-run: the first failing re-run condition in `gate-full.mjs`, one of `gate-timeout` \| `exit-signal` \| `killed` \| `exit-code` (first run did not exit 1) \| `no-file-summary` (no `Test Files` line) \| the classifier's own `reason` verbatim from `extractTimeoutOnlyFailedFiles()` (`non-timeout-failure`, `parsed-<N>-of-<M>`, `uncounted-errors`, `line-outside-blocks`, `header-without-error`, `no-error-blocks`, `no-output`) \| `too-many-files` \| `unsafe-file-name` \| `report-path-unquotable` \| `test-command-not-rerunnable` (the test command's shape cannot carry appended vitest arguments)). The gate envelope publishes it as `test.rerun_skipped`; both emitters admit it through the ONE shared `admitRerunSkipped()` (`scripts/lib/quality-gate.mjs`, `/^[a-z0-9][a-z0-9-]{0,63}$/`) and drop anything else. **Omitted, never `null`/`""`,** when the test step passed, did not run, or a re-run ran — then `rerun` is present instead, and a re-run that ran and failed is `rerun.status: 'fail'`, not a skip. **CLI only, reporting variants only (`baseline` \| `incremental` \| `per-file`, #1487 point 3):** `check_failed` (boolean — `true` when the envelope's `typecheck` or `test` object carries `status: 'fail'`, `false` when both are `pass`/`skip`; **omitted** when the envelope is unparseable or a status is unknown, and always on `full-gate`, whose event name already carries the verdict). The event name and exit code of a reporting variant are unchanged — `check_failed` is where its check verdict lives. **Library only:** `attempts` (1…`maxRetries+1`) and `gate` (`lint`\|`typecheck`\|`test` — the fail-fast gate of the last attempt; omitted on the passing path). **Kill-ladder fields (#1439, #1457, 2026-09-25):** `timed_out` (boolean — the run hit its wall-clock ceiling and was killed), `survivors` (integer — pids still alive after the SIGKILL step, `0` when none; `null` when the post-kill check could not be measured, which on Windows means the CIM process snapshot failed, never read it as `0` (#1612); the pids themselves stay in the gate output / diagnostics bundle) and `kill_signals` (string[] — the signals actually sent, in order, e.g. `["SIGTERM","SIGKILL"]`; `[]` when none). Both emitters start from the ONE shared `gateKillFields()` (`scripts/lib/quality-gate.mjs`); from the library emitter `false` / `0` / `[]` are therefore measurements ("not killed"), not absence — the CLI emitter additionally passes them through `joinGateKillFields()` and may omit the keys (see below, #1457). The library always carries all three. The CLI JOINS two ladders with `joinGateKillFields()` (`scripts/lib/gates/gate-helpers.mjs`): the OUTER one over the gate sub-script as a whole (that run exits 124), and the INNER per-command ones the gate's JSON envelope publishes — every variant (`gate-full.mjs` on `typecheck`/`test`/`lint`, `gate-{baseline,incremental,per-file}.mjs` on `typecheck`/`test` since #1457 pkt 12) puts `timed_out` / `kill_signals` / `survivors` (pids) on each command object it actually spawned, so a single command killed by the per-command ceiling (exit 2) now reads `timed_out: true`. Join: `timed_out` = outer OR any inner, `kill_signals` = outer followed by each command's in execution order, `survivors` = outer count plus every inner pid count. **The CLI omits all three keys** when the inner side was not measured — an envelope without the per-command ladder (all four variants publish it since #1457 pkt 12, so today this means an older gate script) or an unparseable envelope — and the outer ladder did not fire; a fired outer ladder is reported alone. **Leftover groups (CLI and remote pre-push route, #1708):** when a command's process group was reaped after a NORMAL exit (#1704), the join adds `leftover_groups` (`[{command, pgid, signals, survivors}]`, one entry per such command, `command` ∈ `gate`\|`typecheck`\|`test`\|`lint`\|`test-rerun`); the key is **omitted, never `[]`**, when no command left one, and its `survivors` pids are NOT counted in the joined `survivors`. `command: "gate"` is the OUTER gate sub-script's own group (#1708 N2), CLI only — the remote pre-push route joins with an empty outer side: `gateKillFields()` emits it from `run.leftoverGroup`, and the join lists it first; `command: "test-rerun"` is the serial re-run's group (`test.rerun`, #1708 N3), listed right after `test` (execution order: typecheck, test, test-rerun, lint). **Library emitter (#1708 N2):** `gateKillFields()` also carries `leftover_groups` there — one entry, `command` = the failing gate of the last attempt (`lint`\|`typecheck`\|`test`), only when that command's group was reaped after a normal exit; omitted otherwise. The library reports the failing gate command of the last attempt, and `false` / `0` / `[]` on the passing path (every gate exited 0, so none was killed). **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` (both emitters, #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 not a positive safe integer; 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.coordinator_carveout_allowed` | `hooks/enforce-scope.mjs` (coordinator carveout, #245 / #1361) | exactly once per ALLOWED write BY THE COORDINATOR into one of the harness-owned in-repo files the carveout covers — `.claude/STATE.md` and its `.codex/` / `.cursor/` / `.pi/` siblings, plus the exact relative path of the live `wave-scope.json` the hook itself just read. Since #1361 a payload carrying `agent_id` is a dispatched subagent: it gets no carveout and falls through to Gate 7, where a manifest that does not grant the path is a DENY (a subagent permitted to write `wave-scope.json` could rewrite its own file scope and disarm every later gate of the wave; STATE.md is coordinator-owned per `skills/_shared/state-ownership.md`). **Payload:** `hook`, `manifest` (the manifest path), `wave`, `file_path` (the project-RELATIVE, forward-slash-normalized path — the carveout set is in-repo by construction, so no host-local absolute path enters the ledger) and `discriminator` (`'coordinator' \| 'malformed' \| 'absent'` — same enum and same meanings as `orchestrator.scope.memory_dir_allowed`: `'coordinator'` = `agent_type` present without `agent_id`; `'malformed'` = an `agent_id` key present but unusable (number, object, array, blank string), a fail-open that must stay rare; `'absent'` = no `agent_id` key at all, the harness's documented main-thread shape. `'subagent'` never appears here BECAUSE a subagent gets no carveout and so emits no allow) — exactly the five keys the `emitEvent` call passes, with `{ repoRoot: projectRoot }` as options. **Fail-safe:** awaited BEFORE `emitAllow()` (which calls `process.exit()` and would discard a pending append) and wrapped in its own `try {} catch {}`, so a telemetry failure can never flip the decision. Before #1361 this branch was a bare `emitAllow()` with no log and no event, so whether it ever fired was unfalsifiable after the fact (HR-105) | <!-- path-check: example -->
| `orchestrator.scope.foreign_session_ignored` | `hooks/enforce-scope.mjs` (Gate 3b, #1123) · `hooks/enforce-commands.mjs` · `hooks/post-bash-write-verify.mjs` (both Gate 3b, #1153 P1) | exactly once per gated tool call while a FOREIGN-session `wave-scope.json` is live: the manifest's `session_id`/`semantic_session_id` provably name another session (legacy `session`/`semantic_session` still read, #1153 P2), so the hook stands down instead of enforcing. Since #1504 point 6 only when EVERY existing candidate (`.pi` > `.cursor` > `.codex` > `.claude`) is foreign — a peer's higher-precedence manifest no longer hides this session's own one (`findOwnScopeFile()`, `scripts/lib/scope-gate.mjs`); `manifest` then names the first foreign candidate. **Payload:** `hook`, `manifest` (path), `manifest_session` (string[]), `own_session` (string[]), `wave`; additionally `file_path` from `enforce-scope` (PreToolUse Edit/Write) and `command_hash` from `enforce-commands` (PreToolUse Bash) — **sha256 auf 16 Hex gekuerzt, NIE das rohe Kommando.** Bis 2026-09-19 stand hier `command` im Klartext, und zwar als dokumentierter Vertrag, nicht als Versehen. Gemessen in EventDrop.at (#1140): **3.816 Zeilen** der GETRACKTEN `.orchestrator/metrics/events.jsonl` trugen ein rohes Kommando, darin **24 distinkte echte Produktions-Share-Codes** aus **17 fremden Kundenkonten** plus ein protokollierter `select access_pin_hash` — bei 23 dieser Events ist der Share-Code die VOLLSTAENDIGE Capability (`/event/<code>` oeffnet das Album ohne Anmeldung), und das Journal geht bei jedem Klon mit. Der Geschwisterhook `pre-bash-destructive-guard.mjs` fuehrte von Anfang an `command_hash` und sagt den Grund im eigenen Kopf; diese Zeile war die Ausnahme. Der Hash haelt das Ereignis zaehlbar und gruppierbar — genau die Eigenschaft, fuer die es laut `docs/scope-collision-guard.md` existiert; das Rohfeld hatte keinen Leser. Gepinnt in `tests/hooks/enforce-commands.test.mjs` in BEIDE Richtungen (Hash vorhanden UND `command` undefined), damit niemand das Rohfeld neben den Hash zuruecklegt. **Der zweite rohe Schreiber derselben Klasse — `hooks/pre-bash-staging-fence.mjs` (512 Zeichen rohes Kommando je Eintrag) — ist seit #1404 (2026-09-20) geschlossen:** der Fence speichert jetzt die Pfad-Operanden plus `command_hash`, nie den Kommandotext. Belegt mit einem Test-Secret im Kommando: `grep -c` auf die Fence-Datei findet es 0-mal, ebenso 0 Vorkommen eines `command`-Feldes. Der einzige Leser (`hooks/wave-scope-commit-guard.mjs`) vergleicht seitdem Pfadlisten statt den Rohtext per Regex zu durchsuchen — was nebenbei `git add -A` abdeckt, das der Regex-Leser nie erkannte. **Die DRITTE und letzte Stelle derselben Klasse — `hooks/pre-bash-memory-propose-audit.mjs` (`argv_truncated`: 512 Zeichen nur flag-redigiertes Kommando in `orchestrator.memory.propose_invoked`, also in die GETRACKTE `events.jsonl` und optional an den Webhook) — ist seit #1415 (2026-09-21) geschlossen, analog `8f15f77b` und #1404:** der Hook schreibt jetzt `command_hash` + `flags_present` + `argv_length`, nie den Kommandotext. Gemessen vor dem Fix: 0 Produktionsleser des Rohfelds. Damit ist die Klasse zu — kein Hook dieses Repos legt mehr rohen Kommandotext in ein Event oder eine Kontrolldatei. `post-bash-write-verify` (PostToolUse Bash) carries neither — it reports on the working tree, not on one tool input. Legacy manifests without a session-binding field never emit this — they stay enforced |
| `orchestrator.scope.memory_dir_allowed` | `hooks/enforce-scope.mjs` (Gate 5c, #1295) | exactly once per ALLOWED write BY THE COORDINATOR (#1352 — a payload carrying `agent_id` is a dispatched subagent, gets no carve-out and falls through to the normal gates) into THIS repo's harness auto-memory directory `~/.claude/projects/<encodeProjectDir(repoRoot)>/memory/` — the single out-of-repo carveout, evaluated only on the out-of-root branch (Gate 6) and only when a `wave-scope.json` manifest is live, so the in-repo gates are untouched. **Payload:** `hook`, `manifest` (the manifest path), `wave`, `file_path` (the REALPATH-resolved candidate) and, since #1352, `discriminator` (`'coordinator' \| 'malformed' \| 'absent'` — `'coordinator'` = `agent_type` present without `agent_id`; `'malformed'` = an `agent_id` key present but unusable (number, object, array, blank string), a fail-open that must stay rare; `'absent'` = no `agent_id` key at all, the harness's documented main-thread shape. `'subagent'` never appears here BECAUSE a subagent gets no carve-out and so emits no allow) — exactly the five keys the `emitEvent` call passes, with `{ repoRoot: projectRoot }` as options. **Fail-safe:** awaited BEFORE `emitAllow()` (which calls `process.exit()` and would discard a pending append) and wrapped in its own `try {} catch {}`, so a telemetry failure can never flip the decision. This row is the audit trail for the carveout: it is the only place an out-of-repo ALLOW becomes measurable after the fact |
| `orchestrator.scope.refused_grant_allowed` | `hooks/enforce-scope.mjs` (Gate 5b WARN branch, `recordRefusedGrantOncePerWave()`, #1485 point 1) | the FIRST time per wave that Gate 5b honours an explicit absolute (out-of-repo) grant which `gradeScopeEntry()` grades `error` — i.e. one `scripts/validate-wave-scope.mjs` would refuse before dispatch. The WARN itself still fires on every such write; this record does not. **Dedupe:** marker `.orchestrator/tmp/gate5b-refused-grant/<session>-w<wave>` created with `flag: "wx"` (O_EXCL — of two racing hook processes exactly one emits); `<session>` = manifest `session_id` (legacy `session`), else payload `session_id`, else `CLAUDE_CODE_SESSION_ID`, else `no-session`; a marker failure other than EEXIST still emits. **Payload:** `hook`, `manifest` (path), `wave`, `grant` (the matched allowedPaths entry), `code` (the grader's refusal code, e.g. `filesystem-root`, `home-grant`), `file_path` (the realpath-resolved candidate). **Why it exists:** the validator has no mechanical caller, so a manifest that skipped the prose validation steps reached Gate 5b ungraded and left nothing countable (owner decision 2026-10-02, option (b)). Zero cost on the normal path — only the Gate 5b `error` branch reaches it |
| `orchestrator.scope.manifest_hidden_by_session_root` | `hooks/enforce-scope.mjs` (Gate 3 no-manifest branch, `recordHiddenManifestOncePerWave()`, #1504 point 3) | the FIRST Edit/Write per (session, wave, session-root basename) for which `resolveSessionRoot()` resolved a root WITHOUT a manifest — a nested or sibling repo the agent `cd`'d into, an entered worktree — while the harness-stated launch dir (`CLAUDE_PROJECT_DIR` → `CODEX_PROJECT_DIR` → `CURSOR_PROJECT_DIR` → `PI_PROJECT_DIR`) carries a manifest that is not provably a peer's (own, or unbound/legacy: one that WOULD have been enforced). The write is still ALLOWED — this is the trace the named revisit trigger in `resolveSessionRoot` (`scripts/lib/platform.mjs`) waits for. Silent on the ordinary no-manifest allow: nothing is checked while the session root IS the launch dir (HR-101). Deduped by an exclusive-create marker under `<launch>/.orchestrator/tmp/scope-root-relocated/`; written to the LAUNCH repo's ledger. **Payload:** `hook`, `manifest` (path at the launch root), `launch_root`, `session_root`, `wave`, `file_path` |
| `orchestrator.scope.sidecar_mismatch` | `hooks/post-bash-write-verify.mjs` (`bindPeerSidecar()` notify branch, #1514 point 6) | exactly once per NEW hash of a wave's aggregate scope sidecar (`filescopes/wave-<N>.scopes.json`) that differs from the hash bound to the standing `wave-scope.json` — the same once-marker (`sidecarNotified` in the trusted snapshot) that gates the ⚠ mismatch notice (#1504 point 5), so a repeat call against the same changed sidecar records nothing and a further change records again. While the mismatch stands NO `peer-session-*` record is honoured. **Payload:** `hook`, `sidecar` (path RELATIVE to the repo root, forward slashes), `wave`. Written to the manifest root's ledger. Exists because the notice alone left its firing rate unfalsifiable (HR-105) |
| `orchestrator.scope.unbound_manifest` | `scripts/wave-scope-binding.mjs` (#1153 P4) | wave-executor § Scope Manifest, when the binding step resolves to `{}` — `attributionForRecord()` found no `.orchestrator/session.lock`, or the lock's `session_id` did not match this process's own identity, so the manifest about to be written names NOBODY. **Payload:** `wave` (number\|string\|null), `role` (string\|null), `reason` (currently only `no-confirmed-session-attribution`). Exactly one per invocation, and only on the unbound path — a bound binding emits nothing. An unbound manifest is the FAIL-CLOSED direction (it enforces against every session in the checkout) and is therefore otherwise silent; this event is what makes it countable instead of indistinguishable from a coordinator who skipped the step |
| `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 seven 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-vault-not-canonical` (the vault's git origin is not a canonical Meta-Vault — #1450; nothing written, no lock), `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, release?: 'not-owner' \| 'busy' }` (snake_case like the sibling keys; `release` is present only when the lock release after the write did not succeed — the lease expired mid-write so a successor may have run, or the release guard gave up — #1336) — 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-vault-not-canonical` (the vault's git origin is not a canonical Meta-Vault — #1450; nothing written), `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 **19** of its call sites, one of them the `skipForeignOwner` helper that the session branches share — census `grep -n 'emitEntryAction' scripts/lib/vault-mirror/process.mjs` minus the definition and 2 trailing-comment hits, 2026-10-02 @ `adeb1f32`) and from the two `skipped-invalid` branches plus the `--kind session` dedup pass (`skipped-duplicate-session`, which calls `emitAction` directly — #1291) 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. `skipped-duplicate-session` (#1291): a `--kind session` line whose `session_id` a LATER line in the same source supersedes (crash-recovery re-append, #1068 stub/supersede pair) — never dispatched, the winning line renders the one note; the record carries `record_id` (the `session_id`) and `line` (the LOSING line), and `path` is absent by design, because no target file exists for a line that was never dispatched (its stdout line carries `action`, `path: null`, `kind`, `id`, `line`). `skipped-foreign-owner` (#1503): the generator note already at the target path belongs to another owner — its `source-record` frontmatter field is present and is not a key of this write (for sessions: not on any line of `--source`, superseded duplicates included; a learning record mismatch is routed to the `<slug>-<uuid8>` disambiguation instead, `skipped-collision-resolved`), or, sessions only, it is this generator's note for a DIFFERENT session id (sessions have no disambiguation scheme). `--force` does not bypass it; a note that still leaks a secret under the current masker is healed over the guard (`updated`, `healed_leak: true`). The note is left untouched and one `SKIP foreign owner` line goes to stderr; the record carries `record_id`, the vault-relative `path` of the refused note, and `reason` (constant: `source-record mismatch` \| `id mismatch` — no value read from disk is echoed), and the class counts into the run event's `skipped`. 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:…` — or on `skipped-foreign-owner`, or the constant `newer record owns the main note` on an `updated` learning-note takeover (its `displaced_id` goes to stdout only), 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: the repo root that decides the vault namespace (#1503: `--repo-root`, else the git repo containing `--source`) is deliberately NOT used for the ledger, because routing telemetry by it would split a single run's records 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, `--kind session` included: a duplicate `session_id` line collapsed by the dedup pass is counted as `skipped-duplicate-session` (#1291), so it stays inside `skipped` instead of falling out of the partition (pinned by tests for both kinds). **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()) \| `source-repo-mismatch` (#1503: a fourth pre-loop exit-2 abort — an explicit `--repo-root` and the git repo containing `--source` resolve to different vault namespaces, so the run stops before its first entry and writes nothing)) — 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` | Three producers, one per masking call site: `scripts/vault-mirror.mjs` (beside the vault-mirror run, `channel: 'vault-mirror'`), `scripts/lib/vault-status/narrative-mirror.mjs` (`channel: 'narrative-mirror'`), `scripts/export-hw-learnings.mjs` (`channel: 'export-hw-learnings'`) | once per masking pass at each producer, unconditionally. **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 — the three channels above are DISTINCT producers, not one call site with three labels, so a per-channel count is a per-producer count |
| `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?, work_ms?, follow_up?, follow_up_stage?, measure?}` 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`. `work_ms` (integer, rounded) is present on every `ran-*` and `timeout` element and on an `error` from a throwing `severityOf`/`render` (`severity-threw`/`render-threw` — the probe's work did run), and absent on `skipped` and on any other `error`: the probe's OWN work time — wall-clock elapsed minus the time the event loop was blocked by synchronous work, measured from timer lateness (`startLoopBlockedMeter`). It is the quantity the `timeout` verdict is computed from; probe-level `duration_ms` is deliberately NOT persisted, because under parallel launch it ranks contention, not work. Read `work_ms` as exact for a preemptible probe and as a LOWER BOUND for a synchronous one (the meter subtracts a blocker's own blocking time from its own `work_ms` too), so never rank the synchronous probes by it. `follow_up` (`budget-exceeded`) marks a `ran-*` result whose follow-up ran out of budget and fell back to the delivered result. `follow_up_stage` (#1735) names the follow-up branch that was running when it fell back or threw — for `ci-status` one of `pushed-sha`, `red-history`, `head-sha` — and is absent when the probe named none or its follow-up succeeded. `measure` (#1489) is a flat object of what the probe MEASURED, present only on a `ran-*` element of a probe whose registry entry declares `telemetry(result)`, warn or not: at most 8 snake_case keys, each a finite number or `null` — strings are dropped by the runner (`probeMeasure`), because this payload also travels over the optional webhook unredacted and a string is how a path or a repo slug gets there. Absent means not measured, never zero. Today only `events-retention` declares one: `{coverage_days, archives, max_backups, required_days}` (`coverage_days` rounded to 3 decimals — always a number: a ledger with no stamp at all is no longer measured as `null` but answered `unmeasurable` (`degraded`, recorded `ran-warn`) and persists no `measure`, #1498; `required_days` `null` when no reader declares a finite window), so a retention warning that never fires can be told apart from a dead one (HR-105). 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: 10` seconds (5 until #1859) while each network probe carries its own 8 s CLI timeout, so one slow network probe alone eats most of the hook's 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 budget is PER PROBE and denominated in that probe's own work time (`work_ms`), not one shared wall-clock deadline — a shared wall deadline charged every probe for its siblings' non-preemptible `execFileSync` calls. A synchronous probe (`project-hygiene`, `tests-src-ratio`) still cannot be preempted by a timer that cannot run, so the bound is hard for async/network probes and advisory for synchronous ones. 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.offload.synced` | **not emitted in this repo** — the `offload` CLI in projects-baseline (`scripts/remote-offload/offload`, `log_sync_event`, offload 1.4.1) | once per SUCCESSFUL sync step — `offload sync`, and `run`, `gate`, `claude` unless `--no-sync`, and `session` only with `--sync`; a failed sync writes nothing. Appended to `<repo>/.orchestrator/metrics/events.jsonl` only when that directory already exists (never created; a missing `jq` or a failed append is a warning, never an error). Registered here so readers of `events.jsonl` can name the record (#1299). **Payload:** `schema_version` (1), `host` (the offload alias), `repo`, `direction` (always `local->host`), `local_sha`, `snapshot`, `files` and `deleted` (counts), `deleted_paths` (array). No `session_id` — the CLI has no session context |
| `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: sessionRoot})` — written to `eventsFilePath(sessionRoot)`, the session root's repo ledger (a linked worktree maps to its main checkout, #1514 point 1), with `sessionAttribution(sessionRoot)` read at the session root from `resolveSessionRoot()` in `scripts/lib/platform.mjs` (#1492, which replaced the hook-local `sessionRootOf()`): the repo root of the payload `cwd` — the git toplevel the hook already holds, else the nearest `.git` ancestor of that `cwd` (a spawn-free walk, so a timed-out toplevel lookup cannot fall back to the launch directory) — lifted to `<P>` when it is a harness subagent worktree `<P>/.claude/worktrees/agent-<hex>`, and replaced by the launch dir (`$CLAUDE_PROJECT_DIR`, on the Cursor/Pi bridges their `*_PROJECT_DIR`, which is the payload cwd) when it lies strictly above it (never above the launch dir; bridge sessions therefore follow their cwd, as before #1492); only when `cwd` is in no repo the launch dir from env, else that `cwd`; never the subdirectory a `cd` moved to, which split ledger and records into `<root>/sub/.orchestrator/` before #1489 Pkt 6, and never the LAUNCH dir `$CLAUDE_PROJECT_DIR` keeps after the session enters a worktree — preferred there (be6a2e3e), it put every worktree session of one launch dir on ONE ledger, dropped `wave`, and moved the records away from the worktree `events.jsonl` that `scope-echo --verify` reads) | 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` \| `deny-stale-base` — the last one set by `main()`, not `decide()`: the #1485 stale-worktree-base check refused a dispatch the collision verdict alone would have let through, so a refused dispatch is never counted as an allow (#1489 Pkt 8); a collision deny beside a stale base keeps `deny`; every value starting with `deny` means the dispatch did NOT happen), optional `collision_result` (present exactly when `ledger_result` is `deny-stale-base`: the value `decide()` returned and `main()` replaced — `no-scope` \| `allow` \| `allow-finished` \| `warn-ledger-corrupt` \| `warn-not-evaluable` — so a corrupt or unevaluable ledger behind a stale-base deny is not reported on stderr alone), `collision_count` (collisions involving THIS dispatch, live or already-finished — `ledger_result` says which), optional `known_files_skipped` (`budget-exhausted` \| `git-error` — present only when the tracked-file listing for glob expansion degraded to empty, matrix row 8: `budget-exhausted` = the fire's shared 1500 ms git deadline ran out first, #1489 Pkt 7), `marker_found` (a declaration of any recognised shape was seen — `signal !== 'marker-absent'`; NOT a second spelling of `injected`, which additionally requires a path to have survived), `echo_instruction_present` (an `End your final report with the line: SCOPE-DIGEST: <8hex>` line was found in the SAME prompt). **Optional, absent-is-not-zero — the digest trio (#1092):** `scope_digest` (8-hex `scopeDigest()` over the paths extracted FROM THE PROMPT — the join key `scope-echo --verify` uses; **OMITTED for an empty scope**, never the digest of the empty string, which is a real 8-hex value that would join every marker-absent Discovery dispatch to every other), `instructed_digest` (the 8-hex the echo line names — omitted when no line was found), `digest_consistent` (`scope_digest === instructed_digest` — omitted unless BOTH are present; `false` is agent A's fenced block beside agent B's echo line, caught at dispatch time with no filesystem read). All three are computed inside `scopeDigestFields()`, which is TOTAL by construction: a throwing digest function costs the FIELD, never the verdict. **Why a digest and not `agent_id`:** measured 2026-09-16 over this host's ledger — 609 `scope_checked` against 51 `scope_echo_checked`, agent-id set overlap **zero** (send writes `description` + `subagent_type`, receive writes the coordinator's short handle), so the two halves were unjoinable. **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` at the session root (a worktree entered after launch usually has none: the lock is written at the launch dir — measured 2026-10-02 — and is never borrowed from there, where it may name a peer). **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.wave_dispatch.scope_echo_checked` | `scripts/lib/scope-echo.mjs` (name const `SCOPE_ECHO_EVENT`; verdict built by `checkScopeEcho()`, payload by `scopeEchoPayload()`, emitted from the CLI's `--emit` path via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`) | **coordinator-invoked, post-wave — once per agent** that reported in a wave, at `skills/wave-executor/references/wave-loop-review.md` step 3d-bis, after Edit-Persistence Verify. Never emitted at dispatch time and never by a hook. **Payload:** `agent_id` (the coordinator's agent id, clamped to 120 chars — omitted when not passed), `applicable` (boolean; `false` when the agent's DECLARED file-scope was EMPTY — nothing to echo a digest against — paired with `reason: 'scope-empty'`, so consumers filter this never-instructed population out of the echo rate before computing it), `echoed` (the report carried a well-formed `SCOPE-DIGEST: <8 hex>` marker), `match` (the echoed digest equals the digest of that agent's `<state-dir>/filescopes/wave-<N>/<agent-id>.json`), `expected_digest` / `actual_digest` (8-hex or `null`), `reason` (`echo-absent` \| `digest-mismatch` \| `scope-file-unreadable` \| `scope-empty` — present whenever `match` or `applicable` is false). **Optional, absent-is-not-zero:** `wave` (**omitted, never `0`**, when the caller passes no wave number — same contract as `scope_checked`'s `wave`), plus `session_id` / `semantic_session_id` via `sessionAttribution`. **What it proves and what it does not:** that the agent's final report carried the digest the coordinator injected beside the `FILE-SCOPE` block — the **receive** side of #1092, i.e. the line survived the round trip into the agent's context and back. It does NOT prove the model read, understood or obeyed the scope: the digest stands in the prompt and can be copied without ever reading the paths (the named BV-004 ceiling, `docs/scope-collision-guard.md` § 4.2). It is INFORMATIONAL — `match:false` or `echoed:false` blocks nothing and triggers no re-dispatch. **No path and no prompt body is in the payload** (issue #1092 acceptance criterion 3), same reason as the row above: this record also travels over the optional Clank webhook with no redaction |
| `orchestrator.wave_dispatch.scope_materialized` | `scripts/materialize-wave-scope.mjs` (name const `SCOPE_MATERIALIZED_EVENT`, defined in `scripts/lib/scope-echo.mjs`; emitted from `main()` after stdout, fire-and-forget with a `.catch`) | **once per `materialize-wave-scope` CLI run**, i.e. once per wave manifest (`wave-loop-scope-manifest.md` § 3.2). Never emitted by the exported `materializeWaveScope()` function — the seam is the CLI, so a library caller writes no record. **Payload:** `wave`, `agent_count` (the records of DISPATCHED agents — excluding every `peer-session-*` record, which gets no per-agent file, AND the `coordinator` record, matched by exact id via `isCoordinatorRecordId` in `scripts/lib/scope-gate.mjs`: it does get a per-agent file, but no dispatch carries it, and counted, its usually empty `files` read as two agents sharing one scope, #1493.2), `digest_count` (DISTINCT `scopeDigest()` values among those same dispatched-agent records' non-empty file arrays — lower than `agent_count` means two agents were handed the identical scope), `transport_observable`, plus `session_id` / `semantic_session_id` via `sessionAttribution`. **`transport_observable` is the DEGRADATION half of #1092:** true iff a `PreToolUse` entry with matcher `Agent` is registered in the plugin's active `hooks/hooks.json`. On Codex / Cursor / Pi it is false BY DESIGN (no `Agent` dispatch tool — the asymmetry is registered in `DOCUMENTED_ASYMMETRIES`), and there a missing `scope_checked` record is **not** evidence of a missing injection; `scope-echo --verify` reads this field and degrades every verdict to `echo-only`. **Fails CLOSED** on any unreadable hooks file: observability we cannot prove would produce false `injection-missing` accusations. `repoRoot` is the state directory's PARENT, never `process.cwd()`, so a run from a subdirectory cannot write into another repo's ledger. Silent on failure — the corpus pins byte-empty stderr on this command's success path |
| `orchestrator.wave_dispatch.scope_verified` | `scripts/lib/scope-echo.mjs` (name const `SCOPE_VERIFIED_EVENT`; report by `verifyWaveScope()`, payload by `scopeVerifiedPayload()`, emitted from the `--verify --emit` path) | **coordinator-invoked, post-wave — exactly ONCE per wave** (`wave-loop-review.md` step 3d-bis, after the per-agent `--emit` calls). This is the JOIN of the three halves — `scope_checked`, the `<state-dir>/filescopes/wave-<N>/*.json` artefacts, and `scope_echo_checked` — **keyed on the digest, never on `agent_id`** (see the `scope_checked` row for the zero-overlap measurement that forces it). **Payload:** `wave`, `transport_observable`, `dispatches`, `injected`, `echoed`, `malformed_lines`, `malformed_scope_files`, `by_verdict` (a count per verdict), `digests` (the 8-hex keys the row covers). `malformed_lines` counts the ledger lines the join could not parse (a writer killed mid-append leaves a truncated line — a measured shape here) and is **ALWAYS present, including as `0`**, like the three counters beside it: it is the honesty check on the denominator, because a join that silently dropped half the ledger otherwise writes a record byte-identical to a clean wave (HR-105). `malformed_lines > 0` means every count and verdict in the row is a FLOOR, not a census; the human table says so beside them. `malformed_scope_files` (#1379 P2) is the same honesty check on the FILE side — the per-agent `<state-dir>/filescopes/wave-<N>/*.json` files the join could not read or parse, also **ALWAYS present, including as `0`**; before it existed a corrupt scope file was skipped silently, so `digest-unknown` / `injection-missing` could not be told apart from a genuinely missing injection. A file that parses but holds an empty/non-array scope is NOT counted — an empty scope is legitimate. **Deliberately NO `agent_id` and no path** — unlike its two halves, this record carries a LIST, and an agent id is a free-form coordinator string that has carried private project slugs; the per-agent verdicts stay on stdout, where they never reach the webhook. **Verdict enum — SIX members** (precedence order, one row per digest, all kebab-case): `duplicate-claim` (≥2 distinct agent ids claimed one digest — agent A's scope reported for agent B) · `echoed-not-injected` (an echo names a digest no dispatch claimed) · `digest-unknown` (no scope file on disk carries it) · `matched` · `injected-not-echoed` (the normal state during a wave, before reports land) · `injection-missing` (a scope file no dispatch claimed and no agent echoed — the omitted-injection case, #1092 AC-2). **Degraded value, NOT a seventh member:** `echo-only` — what EVERY verdict collapses to when `transport_observable` is false; the precedence chain never produces it, so it is absent from `SCOPE_VERDICTS`. **Spelling migration:** `injection-missing` was `injection_missing` (the one snake_case member) until 2026-09-16 — records written before that date may carry the old key in `by_verdict`, and there is no dual-emit, so a consumer reading history must accept both. **Exit 0 for every verdict** — the tool reports; the wave-executor turns `injection-missing` / `duplicate-claim` into a STATE.md deviation, never a block |
| `orchestrator.wave_dispatch.worktree_base_checked` | `hooks/pre-task-scope-disjoint.mjs` (name const `WORKTREE_BASE_EVENT`; facts by `worktreeBaseFacts()`, deny text by `staleWorktreeDeny()`, emitted in `main()` via `emitEvent(..., {repoRoot: sessionRoot})` — written to `eventsFilePath(sessionRoot)`, the session root's repo ledger (a linked worktree maps to its main checkout, #1514 point 1), with `sessionAttribution(sessionRoot)` read at the same session root as `scope_checked` (git toplevel of the payload `cwd`, else the nearest `.git` ancestor of that `cwd` (a spawn-free walk, so a timed-out toplevel lookup cannot fall back to the launch directory), else `$CLAUDE_PROJECT_DIR`, else `cwd`; #1489 Pkt 6), which is deliberately NOT the settings root `base_ref` is read from (`settingsRootOf()`, below) — awaited BEFORE the terminal emit) | PreToolUse `Agent` — once per dispatch whose `tool_input.isolation === "worktree"` (#1413, #1424, #1485). **Payload (measured):** `hook`, `head` (full sha, `git rev-parse --verify HEAD^{commit}` in the payload `cwd`), `base` (the commit the harness will branch the agent worktree from), `base_ref` (read in precedence order `<project>/.claude/settings.local.json` → `<project>/.claude/settings.json` → `$CLAUDE_CONFIG_DIR`-or-`~/.claude`/`settings.json`, where `<project>` is the settings root `settingsRootOf()`: `$CLAUDE_PROJECT_DIR` — the launch dir, kept after entering a worktree, where the harness applies project settings from — else the git toplevel of the payload `cwd`, else that `cwd`; the FIRST file that sets `worktree.baseRef` to `"head"` or `"fresh"` decides; `"head"` — then `base` = `head`; `"fresh"` or unset — then `base` = `refs/remotes/origin/HEAD`), `base_ref_source` ∈ `local` \| `project` \| `user` \| `default` (which layer decided; managed settings and `--settings` are invisible to a hook — a `"head"` there reads as `default` when no visible file sets the key, but as that file's source when a visible file says `"fresh"`, so a wrong deny from this blind spot can carry any source), `stale` (`git merge-base --is-ancestor <head> <base>` exited 1 in a full-history repo whose FETCH_HEAD — `git rev-parse --git-path FETCH_HEAD` — is younger than 24 h: the worktree would MISS commits of HEAD; a base AHEAD of HEAD is not stale), optional `missing_commits` (`git rev-list --count base..head`, stale only), optional `subagent_type`, `decision` (`"deny"` iff `stale === true`, else `"allow"`), plus the `session_id` / `semantic_session_id` envelope. **Payload (non-measurement):** `hook`, `stale: null`, `skipped` ∈ `no-origin-head` \| `shallow` (is-ancestor exit 1 in a shallow clone — missing history, not a measured mismatch) \| `stale-remote-ref` (is-ancestor exit 1, but FETCH_HEAD is older than 24 h or absent: the harness — Claude Code 2.1.287 bundle, read 2026-10-02 — first runs `git fetch origin <default>` with a 5 s timeout and branches from the FETCHED tip, which may contain HEAD; the hook never fetches) \| `git-error` \| `git-budget` (the hook fire's ONE shared git deadline — 1500 ms across all its git calls, sized to fit the 5 s `hooks.json` timeout beside the 2 s ledger lock — ran out or cut a call short; it replaces whichever reason the cut call would have produced, because a timed-out lookup is no evidence, #1489 Pkt 7) \| `probe-error`, `decision: "allow"`, plus the envelope — no `head`, no `base` (a skip accuses nobody). **Written for EVERY `worktree` dispatch — every outcome AND every skip** — so the deny rate is `decision:"deny" / all records of this name` (HR-105). **Emits NOTHING only when `isolation` is absent** (HR-101). **DENIES the dispatch on a measured mismatch only** (owner decision 2026-10-02, option (a)); unknown is never mismatch — every skip is allowed; a collision deny keeps its own reason; a stale-base deny is decided BEFORE the scope-ledger cycle and writes no ledger claim (the dispatch did not happen). **Why it exists:** the agent worktree's base belongs to the HARNESS (the `Agent` tool has no base-ref field). Documented at code.claude.com/docs/en/worktrees § "Choose the base branch" (read 2026-10-02): "Subagent worktrees use the same base branch as `--worktree`, so they branch from your repository's default branch unless `worktree.baseRef` is set to `"head"`". #1485 measured it: agent worktrees on `main` (`0efb3e97`), six commits behind the branch HEAD (`47c49652`). The #1413/#1424 model (base = STATE.md `session-start-ref`, warn-only) is replaced; it fit s18 (2026-09-19, worktrees on `8f15f77b` after commit `240efda6`) only because that session ran on `main`, where origin/HEAD was the start commit; the `identity-mismatch` / `no-state-md` / `no-start-ref` / `no-own-id` skip reasons and the `session_start_ref` field are gone with it |
| `orchestrator.hook.import_probe_failed` | `hooks/post-edit-import-probe.mjs` | PostToolUse(Edit\|Write\|MultiEdit), after a module listed in `hooks/_lib/hook-import-set.json` (the committed hook-reachable allowlist) fails the probe. **Payload:** `file` (repo-relative), `check` (`eslint` \| `import` — which of the two checks caught it), `error` (the first offending message: a `no-undef`/fatal ESLint message, or the import diagnostic line), `reachable_from` (the hook entry basenames that import this module — the blast radius, since a throwing helper turns every tool call into "Internal hook error — request blocked" host-wide, #1224), `duration_ms`. Emitted ONLY on failure; a clean edit produces no record, so the event count IS the incident count |
| `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), `candidate_store_merged` (boolean — the `reconcile-candidates.jsonl` idempotency-sidecar merge, derived from `summary.written` at `scripts/lib/reconcile/engine.mjs:791`, which is the engine's ONLY disk write. It is NOT a rule-write signal: the engine never touches `.claude/rules/`, and this event is emitted BEFORE the operator-approval AUQ. For "a rule reached `.claude/rules/`" read `orchestrator.reconcile.rules_written` (row below) — its `rules_written` count is the only field that carries that claim. **Renamed from `written` in #1315** because the old name read as "rule files were written" and was misread on exactly that basis (#1307). The legacy key `written` is STILL emitted, carrying the identical boolean from the same expression so the two can never disagree — deprecated, removal **2027-03-13**, same one-generation dual-emit convention as the `orchestrator.session.stopped` → `orchestrator.turn.stopped` rename (#1234). `schema_version` is NOT bumped: it versions the record envelope, and the payload contract here stays additive), `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` (path-redacted, THEN clamped to 300 chars: `redactLocalPaths` in `scripts/lib/reconcile/engine.mjs` replaces the absolute repo root with `<repo>` and the home directory with `~` before the clamp, so an engine error message never writes a host-local path into the ledger) — 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.reconcile.rules_written` | `scripts/lib/reconcile/writer.mjs` (`emitRulesWritten`, called from the tail of `writeApprovedRules`; name const `RULES_WRITTEN_EVENT`) | one record per rule-WRITE pass (#1307) — the companion `orchestrator.reconcile.completed` is emitted by the `runReconcile` wrapper, which runs BEFORE the operator-approval AUQ and before this module is reached at all, so a `dry_run: false` record there proves the engine ran and merged the candidate store, NEVER that a rule reached `.claude/rules/`: an operator who declines every proposal emits a byte-identical record to one who approves five. This event is the one that proves the write. Emitted from the FUNCTION TAIL, so both return points are covered — the normal pass and the lock-acquisition failure (which is a zero-write pass carrying `write_errors: 1`). **Payload, all ALWAYS present including as `0`:** `rules_written` (FILE count, not proposal count — one approved proposal written to two targets counts twice), `approved_proposals` (how many the operator approved), `rejected_archived` (records appended to `.orchestrator/reconcile.rejected.log`), `write_errors` (`result.errors.length`). **Optional, absent-is-not-zero:** `targets` (allowlisted to the CLOSED `TARGET_DIRS` key set — `repo-local` \| `baseline` — because the list originates in operator-authored Session Config and an unknown value would be a verbatim echo of untrusted text; absent ⇒ none in effect). **A ZERO-WRITE PASS IS EMITTED, and the discriminator is a FIELD, never the event's absence** (same convention this table states for `dry_run` one row up, and `.claude/rules/host-resources.md` § HR-105): `rules_written: 0` with `approved_proposals: 0` is *the operator declined everything*, while `rules_written: 0` with a non-zero `approved_proposals` and `write_errors` is *every write was refused by a guard* — outcomes a success-only emitter would collapse into one silence, together with *the writer was never reached*. The ONE case that emits nothing is the caller's true no-op (neither an approved nor a rejected item), which returns before the lock is taken. **The emit is not a write:** the #693 FA2/FA3 brandmauer is unchanged — `writeApprovedRules` is still the only module that writes rule files and still writes only operator-approved items. **A missing `repoRoot` SKIPS the emit silently** (same #1119 contract as the row above), and the whole emit is try/catch-wrapped to stderr because `emitEvent` THROWS `EventValidationError`, which would otherwise break `writeApprovedRules`'s never-throws contract. `session_id` / `semantic_session_id` / `wave` / `schema_version` are stamped by `emitEvent()` |
| `orchestrator.security.delta` | `scripts/lib/security-delta/telemetry.mjs` (`emitDeltaEvent`, payload built by `buildDeltaEventPayload`; called from `scripts/security-delta.mjs`; name const `SECURITY_DELTA_EVENT` in `scripts/lib/security-delta/contract.mjs`) | one record per Security-Delta run (#1769, stage 1) — NOT emitted under mode `off` or with `--no-event`. **Payload, COUNTS ONLY** (events.jsonl may be POSTed to a webhook, so no package name, version, file path, advisory id, fingerprint or check `reason` ever enters it): `mode` (`warn` \| `strict`), `status` (`clean` \| `findings` \| `degraded` \| `skipped`), `verdict` (`pass` \| `warn` \| `block`), `checks` (`{ <check id>: { status, checked, unchecked, findings, ms } }` for `lockfile`, `runtime-floor`, `floating-tag`, `gitleaks`, `age-gate`, `package-floor` — the last added in #1769 stage 3), `findings_total`, `introduced_total`, `blocking_total`, `by_class` and `by_severity` (count maps over the closed contract enums, every key present including as `0`; `by_class` includes `package-floor`), `ms_total`, `ms_network` (the slowest network check's own wall time — an upper bound, not pure HTTP time), `budget_exceeded` (boolean — a check was cut off at the total budget and reported `degraded`). The emit is try/catch-wrapped to one stderr WARN: telemetry never fails the run. `session_id` / `semantic_session_id` / `wave` / `schema_version` are stamped by `emitEvent()` |
| `orchestrator.security.secret_emitted` | `hooks/post-bash-write-verify.mjs` (`detectSecretEmission`; detector `detectSecretOutput` in `scripts/lib/secret-output-detector.mjs`, needles from `secretNeedleEntries` in `scripts/lib/secret-masker.mjs`) | one record per Bash PostToolUse call whose `tool_response` (object `stdout`/`stderr`, or a string) contained the value of a qualifying env key of the hook process (SEC-008, #1786) — runs before every write-verify early exit, gated only by `shouldRunHook('post-bash-write-verify')`. **Payload, NEVER A VALUE** (no value, prefix, hash or value length): `detector` (`value`), `env_keys` (sorted, unique key NAMES), `matches` (total occurrences), `tool_name` (`Bash`), `truncated` (boolean — a stream exceeded the 64 KiB head+tail scan window). Best-effort emit; failure never blocks the visible `systemMessage`. A value is found raw and in its one-level JSON-escaped form; double-encoded, line-wrapped, base64 or URL-encoded values are not. On Cursor the bridge forwards the hook's `systemMessage` and `additionalContext` of a non-blocking `postToolUse` / `afterFileEdit` result as `additional_context` (`scripts/lib/cursor-hook-bridge.mjs` `toCursorHookOutput`, #1799; de-duplicated, capped at 3000 characters); the repo holds no measurement yet that Cursor shows that field on a non-blocking event, so there the event stays the reliable signal. `session_id` / `semantic_session_id` / `wave` / `schema_version` are stamped by `emitEvent()` |
| `orchestrator.evolve.completed` | `scripts/lib/learnings/evolve-telemetry.mjs` (`emitEvolveCompleted`), called from `scripts/sweep-expired-learnings.mjs`'s `--prune --apply` exit path (#1206) for the success form, and from `skills/evolve/SKILL.md` Phase 1 (persistence/no-session-data aborts, skill-prose via `scripts/emit-event.mjs` — no mechanical pipeline call site precedes either gate) for the two abort forms | once per `/evolve analyze` run (default mode; #1200, mechanized #1206) — the success form is now the SAME command that performs the Step 3.5(5) store write, so the event can no longer be forgotten independently of the write it reports on (previously a separate `emit-event.mjs` call in skill prose, one edit away from drifting out of sync). Until #1200 `/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. **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` — this SAME call's own returned `archived` total, 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`. **Optional, absent-is-not-zero:** `skipped` (HR-105 — an array of optional-step slugs, e.g. `skill-evolution-off` \| `vault-mirror-off`, that RAN but were themselves skipped this run; present only when non-empty, and distinct from the `aborted` form below — "ran, a step inside it skipped" is not "did not run at all"). **Payload (abort):** `aborted` (`persistence-disabled` \| `no-session-data`), `reason` (the abort message shown to the user, clamped to 300 chars), `duration_ms`. A `--prune --dry-run` preview run emits NOTHING — a preview never wrote anything, so it must not report a completed run either; `emitEvolveCompleted()` also refuses to emit (stderr WARN, never a throw) without an explicit `repoRoot`, same #1119 fail-closed contract as `emitReconcileCompleted` |
| `orchestrator.dialectic.completed` | `scripts/lib/learnings/evolve-telemetry.mjs` (`recordDialecticRun`), called from `scripts/dialectic-deriver.mjs`'s `runDialecticDeriver()` for SIX outcomes — its FOUR return values (`empty-input`, `budget-exceeded`, `would-empty-card`, and the dry-run `ok` success form), each recorded at its return point, plus the two THROWN aborts (`unknown-model` from `validateModel()`, `subagent-crash` from a failed `dispatchAgent` call), each recorded at the throw point by `recordThrownAbort()` before the original error is rethrown unchanged (#1221) — and from `skills/evolve/references/evolve-dialectic-mode.md` Step 6.4's apply branch for the ONE outcome the pipeline cannot see: apply-mode success, which needs the post-merge `mergePeerCard()` stats `runDialecticDeriver()` does not have. Step 6.5 records nothing (a second record there would double-count the run) | once per `/evolve --dialectic` run (#1200, mechanized #1206). Same fleet-zero gap as `evolve.completed` above, now closed the same way: the pipeline function records every outcome it can see — all five abort slugs, the two throw-based ones included since #1221 — and only apply-mode's merge-dependent success remains a skill-prose call site. **Payload (success):** `mode` (`dry-run` \| `apply`), `user_deltas`, `agent_deltas` — the two modes measure DIFFERENT quantities, so never compare a dry-run delta with an apply delta. Dry-run: `countManagedSections()` on the PROPOSED diff text — non-string or empty → 0; if the body carries `<!-- BEGIN MANAGED: … -->` sentinels → their count; otherwise the count of `## ` headings, fence-aware (headings inside ```` ``` ```` / `~~~` blocks do not count); a non-empty body with no headings → 1. Apply: `mergePeerCard()`'s own `stats.replaced + stats.appended` per target — managed (sentinel) sections of the card actually replaced or newly appended by the merge; hand-authored sections are `preserved` and never counted, `tokens_in`, `tokens_out`, `duration_ms`. **Payload (abort):** `aborted` (`unknown-model` \| `budget-exceeded` \| `would-empty-card` \| `empty-input` \| `subagent-crash`), `duration_ms`. Same #1119 refusal as `emitEvolveCompleted` — `recordDialecticRun()` skips the emit (stderr WARN) without an explicit `repoRoot` |
| `orchestrator.dialectic.nudge_decided` | **HISTORICAL — no emission since 2026-09-09.** The producer wrapper (`decideAndRecordAutoDialectic` in `scripts/lib/auto-dialectic.mjs`, #1200 part c) was REMOVED in #1288 after its only caller — session-end Phase 3.6.7 — was retired; the session-start `maintenance-due` probe (`scripts/lib/maintenance-due-banner.mjs`) reads the side-effect-free `shouldDispatchAutoDialectic()` instead. | never — no emitter exists. Row kept so records written before 2026-09-09 stay readable. **Payload (historical):** `decided` (boolean, mirrored `trigger`), `reason`, `cadence`, `sessions_since`, `learnings_since`, plus `session_id`/`semantic_session_id` via `sessionAttribution`. |
| `orchestrator.learnings.sweep_applied` | `scripts/lib/session-end/tail-runner.mjs` (`runExpiredSweep`, emit in `emitSweepApplied`; name const `SWEEP_EVENT`) | once per APPLIED session-end Phase 3.6.4 Expired-Learnings Sweep — emitted only on the write path, never on a plan-skip, a no-plan call, or the never-throws error branch, so a record's presence is proof the active store was actually rewritten. This event exists because the apply path did not: until #723-B4 was wired here, `sweepExpiredLearnings` had no session-end caller at all (census 2026-09-09 — definition, the `dryRun: true` probe in `phase-skip.mjs`, the standalone CLI, tests), so 0 sweeps were ever applied across three consumer repos while 628 learnings stayed resident. The sweep CLI (`scripts/sweep-expired-learnings.mjs:210`) deliberately emits nothing, and `orchestrator.evolve.completed` covers only the `--prune --apply` sibling — this is the ONLY record of a time-driven sweep. **Payload:** `scanned` (entries read from `learnings.jsonl`), `archived` (entries moved to `learnings-archive.jsonl`; a measured `0` is emitted, since the planner can legitimately RUN on a fail-open probe-error), `malformed` (unparseable store lines the rewrite kept verbatim at the end of `learnings.jsonl` and never archived — ALWAYS a number, a measured `0` when the read found none, so a store carrying torn lines is visible in the ledger and not only on stderr; #1489), `source` (always `session-end-3.6.4`, separating this producer from any future one), plus `session_id` / `semantic_session_id` via `sessionAttribution(repoRoot)` — the SAME root the record is pinned to via `emitEvent(..., {repoRoot})`, both keys OMITTED rather than fabricated when no `session.lock` is readable. Emission is best-effort and wrapped in its own catch: a telemetry failure never changes the sweep's return value, and — like the sweep itself — can never block a session close. |
| `orchestrator.learnings.session_write_applied` | `scripts/apply-session-learnings.mjs` (emit in `emitSessionWriteApplied` at the tail of `main`, after the write; name const `SESSION_WRITE_EVENT`) | at most once per `--apply` run of the session-end / `/plan retro` learnings writer (#1446 / GH#69) — the ONLY sanctioned session-end write path for `learnings.jsonl`, which replaced the hand-executed Phase 3.6 step 4g "atomic rewrite with `>`" (the prose producer that wrote file paths into `scope`). Emitted only on a real write under `--apply`, AFTER `pruneLearnings()` rewrote the store, so a record's presence is proof the write ran; a dry run (the DEFAULT), an `--apply` run that wrote nothing (e.g. an empty store with nothing to add, where `pruneLearnings()` returns before touching the file), an input/validation error (exit 1) and a store/IO error (exit 2) emit nothing. **Payload:** `file` (the store path RELATIVE to `--repo-root`), `appended` (new learnings validated and added), `confirmed` / `contradicted` (existing learnings updated by id), `decayed` (existing learnings passively decayed by `learning-decay-rate`), `pruned` (records archived as `expired` or `pruned`; consolidation losers are not counted here), plus `session_id` / `semantic_session_id` via `sessionAttribution(repoRoot)` — the SAME root the record is pinned to via `emitEvent(..., {repoRoot})`, both keys OMITTED when no `session.lock` is readable. Skipped with a stderr WARN when `--file` lies outside `--repo-root`, so the record is never pinned to a repo whose store was not written. Best-effort: a telemetry failure never changes the exit code. |
| `orchestrator.learnings.malformed_dropped` | `scripts/sweep-expired-learnings.mjs` (`emitMalformedDropped`, called from `runDropMalformed` after `dropMalformedLines()` in `scripts/lib/learnings/expiry-sweep.mjs`; name const `DROP_MALFORMED_EVENT`) | once per APPLIED `--drop-malformed` run (#1500) — the one sanctioned removal of an unparseable `learnings.jsonl` line, which every rewrite otherwise keeps verbatim (#1489) and the store WARN forbids hand-editing. Emitted only after the store was snapshotted and rewritten, so a record's presence is proof the drop happened; a dry run (the DEFAULT), a refused line (exit 1 — not unparseable, or still holding a readable record behind a BOM or fused after a torn one while `--accept-embedded` was not given), a store changed since the dry run (exit 3) and an I/O or validation failure (exit 2) emit nothing. `--apply` refuses to start without `--repo-root` (and with `--file` outside it), so an applied drop always leaves exactly one record — no ambient root (#1119). **Payload, all ALWAYS present:** `file` (the store path RELATIVE to `--repo-root`), `dropped` (lines removed), `lines` (their 1-based store line numbers as of the dry run's generation), `remaining_malformed` (unparseable lines the rewrite still kept — `0` when none), `record_bearing` (dropped lines that still held a readable record, which only `--accept-embedded` lets through — `0` when none; non-zero means a learning went with the line and lives on only in the snapshot), `snapshot` (the full pre-drop copy of the store, `<stem>.pre-drop-malformed.jsonl.bak-<ISO>` beside it, RELATIVE to `--repo-root`, both judged on realpaths; outside the keep-3 `.bak` rotation, so the dropped text stays recoverable. `.orchestrator/metrics/*.jsonl.bak-*` gitignores it in this repo, and in a consumer repo once bootstrap's `#store-lock-ignore` snippet has run — before that, a `git add -A` commits it), `source` (always `sweep-expired-learnings-cli`), plus `session_id` / `semantic_session_id` via `sessionAttribution(repoRoot)`, both OMITTED when no `session.lock` is readable. **Not in the payload, deliberately:** the dropped text — the record travels over the optional webhook unredacted; the snapshot holds it. Best-effort: a telemetry failure never changes the exit code. |
| `orchestrator.rules.expiry_sweep_applied` | `scripts/sweep-expired-rules.mjs` (emit at the tail of `main`, after the writes; name const `RULE_EXPIRY_SWEEP_EVENT` in `scripts/lib/reconcile/rule-expiry-sweep.mjs`) | once per APPLIED generated-rule expiry sweep (#1377) — the `.claude/rules/*.md` counterpart of `orchestrator.learnings.sweep_applied` one corpus over: that one archives expired LEARNINGS, this one removes the expired ENTRIES the reconcile engine generated from them. Emitted on the `--apply` path ONLY and AFTER the rewrites/deletes, so a record's presence is proof that tracked rule files actually changed; a `--dry-run` (the DEFAULT) emits nothing, which is why the discriminator here is the event's presence and not a `dry_run` field. This event exists because the removal half did not: `rule-loader.mjs` stopped INJECTING an expired generated rule at read time and nothing ever removed one from disk, so an expired file stayed tracked and kept counting against `generated-byte-ceiling` while shipping to no wave. **Payload, all ALWAYS present including as `0`:** `rewritten` (files whose expired prose blocks were removed — their `## Provenance` pairs are KEPT as `markers only`, because `/reconcile` dedupes on those markers and dropping one re-proposes the learning), `deleted` (files whose every substantive entry expired; each one's pairs are stamped terminal via `markCandidateProcessed` BEFORE the unlink), `stamped` (candidate records stamped for those deletes — `0` whenever `deleted` is `0`), `write_errors` (per-file failures; a non-zero value also makes the CLI exit 2), `expired_entries` (entries the plan judged expired across all files), `files_scanned` (machine-generated rule files enumerated), `source` (always `sweep-expired-rules-cli`, separating this producer from any future session-end caller). A ZERO-WRITE APPLY IS EMITTED: `rewritten: 0` + `deleted: 0` is *nothing was expired*, while a non-zero `write_errors` beside them is *every write was refused* — outcomes a success-only emitter would collapse into one silence (`.claude/rules/host-resources.md` § HR-105). **Not in the payload, deliberately:** the per-file plans, including the `no-1to1-mapping` skips and the unresolvable `learning-id`s. Those carry learning subjects and rule slugs, and this record travels verbatim over the optional Clank webhook with no redaction — the full plan stays on stdout (`--json`). The emit is try/catch-wrapped because `emitEvent` THROWS `EventValidationError`, which must never turn a completed sweep into a failed one; `session_id` / `semantic_session_id` / `wave` / `schema_version` are stamped by `emitEvent()` |
| `orchestrator.session.shape_resolved` | `scripts/lib/session-shape.mjs` (`resolveAndRecordSessionShape`, emit in `_emitShapeResolved`; name const `SESSION_SHAPE_EVENT`), reachable as an entrypoint via `scripts/session-shape.mjs` | once per session-shape resolution, at the moment the coordinator turns the confirmed mode into an execution plan. Until this event existed the shape lived in PROSE at 27 sites contradicting each other in 8 answers (measured 2026-09-09), so "how many waves did this session actually run" was unanswerable from the ledger — which is why 6 consumer-repo `housekeeping` sessions ran the full 5-wave deep shape unnoticed. **Payload:** `session_type` (always), `total_waves`, `waves_config_honored` (false exactly when the ultradeep profile ignored the Session Config `waves` value — the fixed 7-wave shape of `skills/session-plan/SKILL.md` § Role-to-Wave Mapping; PRD AC-9's `waves < 7` rejection was dropped 2026-09-09), `discovery`, `agent_caps` (one clamped cap per wave, in wave order — `min(tier raw, agents-per-wave)`, `0` on a coordinator-direct wave), `coordinator_direct_waves` (the 1-based `n` of every coordinator-direct wave; `[]` is a MEASURED empty list, not an omission — a housekeeping shape must read `[1]` and a plain deep shape `[]`), `shape_version` (the `SESSION_SHAPE_VERSION` contract the record was produced under). **Optional, absent-is-not-zero:** `session_profile` (OMITTED, never `null`/`''`, when the session has no profile — a written null would read as "measured, no profile"; value set is the closed `VALID_SESSION_PROFILES`), `task_count`, plus `session_id`/`semantic_session_id` via `sessionAttribution(repoRoot)` — the SAME root the record is pinned to, omitted rather than fabricated without a readable `session.lock`. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling through to `SO_PROJECT_DIR` (#941), and `--no-event` skips it entirely so a planning dry-run cannot record a session that never ran. `events.mjs` is imported lazily so a pure-resolver consumer does not gain `platform.mjs` and its module-load filesystem walk-ups |
| `orchestrator.issue_budget.reconciled` | `scripts/lib/issue-budget-reconcile.mjs` (`reconcileIssueBudget`, emit in `emitIssueBudgetReconciled`; name const `ISSUE_BUDGET_RECONCILED_EVENT`) | once per session close — the cross-check between what the session RECORDED as created (`record.issues_created.length`) and what the issue-budget ledger CHARGED. It exists because `readBudgetState` returns a ZEROED state for a MISSING counter file, so "the hook never ran for a single create" and "the session created nothing" are byte-identical in its return value; measured 2026-09-09 on a real session record with **26** recorded creations, **0** charged and no counter file under either accounting key. **Payload:** `verdict` (always — `match` \| `escaped` \| `no-ledger` \| `stale-record`; `no-ledger` is the absent-ledger case above, `stale-record` the inverse), `recorded`, `charged`, `exempt`, `overflow`, `escaped` (= `max(0, recorded − charged − exempt)`), and `ledgers` — one record per accounting key looked up (`key`: `semantic`\|`raw`, `path` — **repo-RELATIVE** `.orchestrator/runtime/issue-budget/<hash>.json`, never absolute: this payload also travels over the optional Clank webhook with no redaction, and an absolute ledger path names the operator's home directory and the private repo slug; the absolute form stays in the local WARN text only, `found`, `charged`, `exempt`); a fifth verdict `corrupt-ledger` marks a file that exists but has a non-integer `count`. **BOTH keys are read and SUMMED**, because the accounting key is semantic only when `current-session.json` verified the raw id (`resolveIssueBudgetSessionId`) — measured in one consumer repo: 25 of 36 counter files keyed semantic, 11 keyed raw, so reading one key reports a phantom escape for every session that used the other. `found` is measured with `existsSync` BEFORE the read and is the only thing that separates `no-ledger` from a real zero — read an absent `found` as "not measured", never as "no spend". The counter file is looked up under `resolveEventsLedgerRoot(repoRoot)` (#1729): from a linked worktree that is the main checkout, where the PreToolUse hook charged it; before #1729 every worktree session that filed an issue read a false `no-ledger` here. Plus `session_id`/`semantic_session_id` via `sessionAttribution`. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling through to `SO_PROJECT_DIR` (#941); `events.mjs` is imported lazily because the verdict path does not need it (`platform.mjs` is reached statically through `issue-budget.mjs` since #1729) |
| `orchestrator.events.rotated` | `scripts/lib/events-rotation.mjs` (`maybeRotate()`, called once per SessionStart) | **The first line of every new active `events.jsonl`, written synchronously between the rename and any other append.** It is the ledger's record of its own break: before #1401 a rotation wrote nothing durable — only a `console.error` whose stderr the harness discards — so a rotation and a DELETED archive were byte-identical from outside, and a 53.896-line archive destroyed on 2026-09-19 left no trace anywhere. **Payload:** `archived_as` (absolute path of the archive — **PROVENANCE ONLY since #1411, not a pointer to resolve**: `readEventsWithRotations()` in `events.mjs` resolves the tombstone by BASENAME against the active file's own sibling `_archive/`, and deliberately ignores an absolute hit outside it, because that hit can only be a FOREIGN checkout — validating this ledger against another repo's archive was a silent false negative. Since #1423 EXISTENCE is not reading: the sibling counts only when it was an actual SOURCE of the read (a name matching `ARCHIVE_NAME_RE`); a sibling that EXISTS but was never read yields the gap kind `unindexed-archive` (with `path`), not silence. The reader's return contract is three-state: `complete` is `true` (measured whole), `false` (measured with a gap — kinds `missing-archive` \| `unindexed-archive` \| `ring-hole` \| `unreadable-source`) or `null` (not measured: no readable source at all); `notices` is a separate array (`unindexed-archive-file` for a hand-placed `_archive/` file with no tombstone) that never moves `complete`. The stored absolute path breaks the moment the checkout moves or a sibling git worktree reads it, which is routine here; archives are never renamed after creation, which is why the `.1`..`.N` ring was retired), `size_before` (bytes of the rotated file), `lines` (records + unreadable lines), `first_ts` / `last_ts` (earliest/latest parseable timestamp in the archive — `null`, never absent, when the archive carried none: "range unknown" must be distinguishable from "field not written by this version"), `malformed_lines` (lines that were not readable JSON objects; `0` is a measured zero). **Optional, additive:** `pruned` (array of archive paths deleted to honour `events-rotation.max-backups`) — present only when something was pruned, so the deletion is itself in the ledger. Emitted by a raw `appendFileSync`, not `emitEvent()`: it must be the first line, and the correlation envelope describes a session rather than a file operation. It still passes through `stampEventSchemaVersion()` + `validateEventRecord()` |
| `discovery_validator_violation` | `hooks/post-subagent-discovery-validator.mjs` | SubagentStop, when `discovery-validator.enabled: true` (default `false`). One record per distinct normalized claim per session; log + warn only, the hook never blocks and always exits 0. Legacy bare name, like `stagnation_detected`. Field contract in § `discovery_validator_violation` below |
| `orchestrator.issue_budget.refunded` | `hooks/post-bash-issue-budget-refund.mjs` (`emitRefundDecision`; name const `ISSUE_BUDGET_REFUNDED_EVENT`) | once per refund DECISION — one record per `PostToolUseFailure` delivery whose command contains at least one `gh`/`glab issue create` statement, emitted on the no-op branches too so a census over N sessions has a denominator and not only a numerator. Before #1353 a refund wrote a stderr line only, which under exit 0 reaches the debug log alone: the refund path was unfalsifiable in the sense of `.claude/rules/host-resources.md` HR-105. **Payload:** `reason` (always, CLOSED enum — `refunded` \| `not-charged` \| `chain-not-attributable` \| `counter-at-zero` \| `no-signal`), `unit` (`count` \| `exempt` \| `null` — which counter was given back, read off the honoured charge records; `exempt` only when EVERY refund landed on the exempt counter, `null` whenever nothing was refunded), `statement_count` (issue-create statements `findIssueCreateStatements` found), plus `session_id`/`semantic_session_id` via `sessionAttribution`. Branch mapping: `no-signal` = G2b (a failure event carrying no failure FIELD), `chain-not-attributable` = G3b (the create is not the whole command, so the exit code judges neither), `refunded` = G5 with at least one honoured charge record, `not-charged` = G5 with none (parked at the cap, a re-delivered failure, or an identity-less call `refundBooking` answers `no-session` for). **`counter-at-zero` has no branch in the hook today**: a matched record whose counter is already 0 is absorbed by `refundBooking`'s never-below-zero guard and returns `refunded` like any other match, so the case is not observable without a new field on the shared core's verdict (`scripts/lib/issue-budget.mjs`) — the enum value is reserved, not dead. `mode: off` emits NOTHING (G4 returns before it, and there was no charge to give back). **No command text, issue title or path is in the payload** — it travels verbatim over the optional Clank webhook with no redaction, same rule as `orchestrator.issue_budget.reconciled`. `events.mjs` is imported lazily, awaited AND caught: a throwing emit must never change the hook's exit code or output |
| `orchestrator.reaper.scan_completed` | `scripts/lib/orphan-reaper/scan.mjs` (`runOrphanScan`, re-exported by `scripts/lib/orphan-reaper.mjs`, emitted through `deps.emitEvent`; name const `REAPER_SCAN_EVENT`) | at most ONE record per orphan scan (Epic #1425 B5/B6), and **only when the scan found something** — `candidates + reported + killed > 0`, or `instrument_suspect` is true. A scan that found nothing emits nothing: the reaper is wired to a `PostToolBatch`-class hook, and a per-fire record would be exactly the always-on signal `.claude/rules/host-resources.md` HR-101 calls a broken instrument. **Payload:** `scanned` (rows in the `ps` snapshot), `candidates`, `reported`, `rejected`, `killed` (COUNTS, not the arrays the function returns), `unattributed` (of the `reported`, how many carried NO `sessionId` on their ledger record — broken out because it is a PRODUCER defect, not a decision: the foreign-session guard was inert across 377 of 377 live records and the generic `reported` count could not show it), `peer_liveness` (`measured` — `detectPeers()` answered, possibly with an empty list — or `unmeasured` — the probe could not answer at all; the two are opposite facts and an unmeasured probe must never read as “no peers are alive”), `survived_sigkill` (killed entries still alive after the ladder — never booked as success, PRD B6), `dry_run`, `duration_ms`, `instrument_suspect` (the false-alarm rate over the last 50 audit decisions exceeds the 10 % HR-101 ceiling — REPORTED, never acted on: the answer to a suspect instrument is re-aiming it, not re-thresholding it). **Optional:** `false_alarm_rate` (0..1) — **OMITTED, never 0**, below the 10-decision floor `falseAlarmRate()` requires; an absent rate means "no population yet", and a fabricated zero would read as a measured-clean instrument. Correlation keys come from `emitEvent()`'s own attribution against the passed `repoRoot`. Per-decision detail (trigger, threshold, ist-value, pid/pgid, command signature, outcome) lives in the separate B5 audit `.orchestrator/metrics/reaper-audit.jsonl`, not in this record |
| `orchestrator.ledger.unreadable` | `scripts/lib/orphan-reaper/scan.mjs` (`runOrphanScan`, emitted through `deps.emitEvent`; name const `LEDGER_UNREADABLE_EVENT`, #1505 point 5a) | at most ONE record per orphan scan that ends `skipped: 'ledger-unreadable'` — the process register could not be read, so the scan measured nothing. The CLI's exit 2 for that case is ignored by the detached hook child; this record is what makes a switched-off scan COUNTABLE (HR-105). Throttled with the scan, so never a per-fire signal (HR-101). **Payload:** `path` (repo-relative register path, `.orchestrator/runtime/gate-processes.jsonl` — never a host path), `reason` (`refused` — the reader returned `state: 'unreadable'`: a symlink, a non-regular file, EACCES — or `reader-threw`), `consumer` (`orphan-reaper`). Correlation keys come from `emitEvent()`'s own attribution against the passed `repoRoot`. A failing emit never fails the scan |

Non-orchestrator names still present in the stream: `tmux-layout.{invoked,completed,degraded}`
(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.)

### `discovery_validator_violation`

Written by the `SubagentStop` hook `hooks/post-subagent-discovery-validator.mjs` when
`discovery-validator.enabled: true` (default `false`). One record per distinct normalized
claim per session. Log + warn only — the hook never blocks and always exits 0.

| Field | Type | Always | Meaning |
|---|---|---|---|
| `event` | string | yes | `discovery_validator_violation` |
| `timestamp` | ISO string | yes | write time |
| `agent` | string | yes | agent type, or `unknown` when unresolvable |
| `agent_source` | `payload`\|`meta`\|`none` | yes | where `agent` came from |
| `agent_description` | string | no | sidecar description, ≤120 chars |
| `payload_keys` | string[] | no | sorted stdin keys; only when `agent_source: none` |
| `agent_id` | string | no | harness per-process agent id |
| `session_id` | string | no | `parent_session_id`, else `session_id` |
| `claim_text` | string | yes | the offending line, clamped to 200 chars |
| `occurrences` | number | yes | repeats of this claim inside the scanned tail |
| `kind` | `distributional`\|`gate-verdict`\|`claim-mismatch` | yes | claim class; **absent on pre-w4-1 records, which are `distributional` by construction** |

**`claim-mismatch` only** (#1385 R1) — a claimed test count that no observed vitest run
carries. The comparison reads the `tool_result` side of the same transcript window, so the
claim cannot serve as its own evidence. That inversion was the defect: `RUN_RECEIPT_RE` is
report-wide and matches `\d+\s+passed`, so before this class a self-asserted number WAS its
own receipt (`STATUS: done / Tests pass: 5129 passed / 0 failed.` → no violation, while an
honest `alles grün` without a number → two).

| Field | Type | Meaning |
|---|---|---|
| `mismatch` | `count` | sub-kind |
| `claimed` | `{passed: number, failed: number\|null}` | the asserted counts; `failed` is `null` when the line names none |
| `observed` | `{passed, failed, total}[]` | the **last 3** vitest summaries found in the window |
| `observed_n` | number | how many were found in total |

No command text is ever recorded — only counts (precedent: `8f15f77b`, `command_hash` instead
of the raw command). No observation in the window means no `claim-mismatch` record: evidence
absence is the `gate-verdict` class's job. Measured firing rate before landing: **4 of 1044**
real subagent transcripts (0,38 %; 0,64 % of the 622 with at least one vitest observation),
reached by fixing the parser twice — never by loosening the threshold.

### `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/telemetry/sync.mjs` — `deriveSessionFromEvents` reads across rotations; carries `ledger_complete` (`true|false|null`) / `ledger_gaps` and writes ONE stderr line naming the gap kinds when the verdict is `false` (#1423). `scripts/lib/maintenance-due-banner.mjs` and `scripts/backfill-abandoned-sessions.mjs` walk the same source sequence newest-first via `scanEventsBackwards` / `listEventSourcesNewestFirst` (#1414) instead of the active file alone.
- `scripts/lib/tmux-layout/telemetry-stats.mjs` — filters `event.startsWith('tmux-layout.')`; since #1407 it reads ACROSS rotations (`readEventsWithRotations`) and surfaces an incomplete ledger on stderr plus `ledgerComplete` (`true` \| `false` \| `null` = no source at all, #1423) / `ledgerGaps` / `notices` in its JSON — a `null` ledger gets its own "UNMEASURED, not zero" WARN — because "all-time" over the active file alone means "since the last rotation".
- `scripts/lib/events-rotation.mjs` — size-based archival.
- `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.