session-orchestrator 5.0.0 → 5.2.0

package/docs/events-schema.md

@@ -103,6 +103,7 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.wave.started` / `.completed` | `hooks/post-tool-batch-wave-signal.mjs` · `hooks/on-session-end.mjs` (`emitFinalWaveCompleted`, `.completed` only) | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612); an explicit injected `wave_signal` still takes precedence. **Second `.completed` emitter (#1193):** the batch hook closes wave N-1 only at an N-1→N transition, so the LAST wave of every session never received a completion — measured fleet-wide 2026-09-02 as **296 gaps over 296 wave runs** (1018 started vs 722 completed), exactly one missing final completion per run. SessionEnd now emits it. **Payload of that record:** `wave_number` (the `current-session.json` `last_wave`), `reason: 'session-end'`, `emitted_by: 'on-session-end'`, plus `session_id` / `semantic_session_id` — **omitted when unattested**, never fabricated. **Idempotent** via the `last_wave_completed` high-water mark in `.orchestrator/current-session.json`, written by BOTH emitters and preserved across `/clear`+compact by `on-session-start.mjs`; `last_wave` absent or `0` emits nothing (an Express-Path or coordinator-direct session never batched, and zero waves is the correct reading, not a gap). **Two gates on the SessionEnd emitter, both load-bearing:** (a) OWNERSHIP — `current-session.json` is a single repo-global file describing whichever session most recently ran SessionStart, routinely a different still-live session in a shared working copy, so the emit reuses `resolveSession()`'s `isRecordedSession` predicate; when false it emits nothing AND writes nothing, since writing the marker into a peer's file would silence the peer's own SessionEnd and preserve this very gap on the wrong session. (b) REASON — `reason === 'clear'` **and `reason === 'resume'`** are SKIPPED: the SessionEnd matcher is empty, so `/clear` fires the hook mid-wave while the LOGICAL session continues, and `on-session-start.mjs` preserves `last_wave` / `last_wave_completed` across a resume of the SAME logical session exactly as it does across a clear — so both end the HARNESS session, not the logical one. Closing the live wave on either is premature, and the preserved marker would then suppress the real completion later. Resume is the MORE common of the two (fleet n = 1498 `session.ended`, 2026-09-02: 12 `resume` vs 9 `clear`). Deliberately SessionEnd-only (`on-stop.mjs` is not mirrored) so the closed-vs-abandoned split stays measurable. **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. **Payload (both):** `variant`, `exit_code`, plus `session_id` / `semantic_session_id` when `sessionAttribution()` finds a session lock (both omitted when it does not). CLI `variant` is the `--variant` value (`baseline`\|`incremental`\|`full-gate`\|`per-file`); the library pins `variant: 'auto-fix-loop'`. **CLI only:** `wave_number`. **Library only:** `attempts` (1…`maxRetries+1`) and `gate` (`lint`\|`typecheck`\|`test` — the fail-fast gate of the last attempt; omitted on the passing path). **Optional on both:** `counts: {passed, failed, total}`. **Absent is not zero — for both optional fields.** `counts` is admitted by the ONE shared policy `admitSuiteCounts()` (`scripts/lib/gates/gate-helpers.mjs`, #967 item 2), which returns `null` — never a zero triple — for an unmeasured or inconsistent input (test gate skipped/stubbed, fail-fast on lint or typecheck before the test step, no parseable `<N> passed` marker, or `passed + failed !== total`); both callers spread `...(counts ? { counts } : {})`, so the KEY is missing in those runs. A present `counts.failed: 0` therefore means "measured, zero failures", while an absent `counts` means "not measured" — reading a missing field as `0` mis-analyses the ledger in both directions. Same contract for `wave_number` (CLI, #966 step 1): resolved from the `.{pi,cursor,codex,claude}/wave-scope.json` sidecar, **omitted** — never `0` — when there is no sidecar or its `wave` is non-numeric/non-positive; a human running `npm run quality-gate` from a `git push` has no wave at all, so an invented wave 0 would have to be special-cased by every consumer. Note `total` is `passed + failed` and EXCLUDES skipped/todo (see `extractTestCounts`) |
+| `orchestrator.scope.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. **Payload:** `hook`, `manifest` (path), `manifest_session` (string[]), `own_session` (string[]), `wave`; additionally `file_path` from `enforce-scope` (PreToolUse Edit/Write) and `command` from `enforce-commands` (PreToolUse Bash). `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.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 |
@@ -117,8 +118,10 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.express_path.evaluated` | `scripts/lib/express-path.mjs` (`evaluateExpressPath`, emit in `_emitEvaluated`; name const `EXPRESS_PATH_EVENT`) | once per Phase-8.5 evaluation — **on refusal as well as activation**. Until #1119 this was unrecordable twice over: `scripts/lib/config.mjs` discarded the `express-path` key **even when the block was present** (synthetic probe: 88 keys emitted, none of them this one), and the decision lived only in `skills/session-start/phase-8-5-express-path.md` prose, so it fired only when a coordinator read that prose. Ledger evidence, measured 2026-08-23 @ `34321bc` (a count, so read it as history, not as state): **0** express events at that point, against 22 of the last 30 sessions running with no wave at all — every one of them `housekeeping`, the exact population the path targets. **Payload:** `activated` (always, boolean), `reasons` (always — the BLOCKING codes on refusal, the satisfied ones on activation; nothing short-circuits, so a refusal names every blocker and a reader can tell whether trimming the issue list alone would have helped). **Optional, absent-is-not-zero:** `enabled`, `session_type`, `task_count`, `parallel_agents_required`, plus `session_id`/`semantic_session_id` via `sessionAttribution`. An unmeasured `sessionType` or `taskCount` fails CLOSED (`reasons: ['session-type-unknown','task-count-unknown']`) — defaulting unknown scope to 0 would activate a gate-skipping path on data nobody supplied. **Four inputs, not three:** activation condition 3 carries two clauses (`≤ 3 issues` AND no parallel agents), which both condition matrices list as a non-activating row. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling through to `SO_PROJECT_DIR` — that is the wave-1 incident of this session (a probe with an unexported var wrote a synthetic record into the real fleet ledger) made structurally impossible; a regression test reproduces it. `events.mjs` is imported lazily so `config.mjs`'s 48-file import graph does not gain `platform.mjs`, which runs filesystem walk-ups at module load |
 | `orchestrator.foreign_dispatch.completed` | `scripts/lib/wave-executor/foreign-dispatch.mjs` (`dispatchForeign`, via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`) | once per foreign-model dispatch (#1150) — the replacement for `SubagentStop` telemetry, which cannot fire for a Bash-spawned `cursor-agent` child (no hook in the chain sees it). **Payload:** `model`, `role`, `ok`, `exit_code`, `timed_out`, `duration_s`, `changed_files` (count, tracked-modified ∪ untracked-new — `git diff` alone is blind to new files), `reason` (present on every refusal — `never-foreign-role`, `empty-diff`, `channel-unavailable`, `unsafe-*` — and on the failure classes of a completed run, so no failure class is reasonless), `hook_tampering` (tri-state: `true` = the child repointed/rewrote the shared `.git` hooks path, invalidates the run regardless of `ok`; `false` = fingerprint matched; absent/`null` = not measured, never read as clean), plus `session_id`/`semantic_session_id` via `sessionAttribution` (omitted, never fabricated, without a readable `session.lock`). Emitted on refusals too (`ok:false`), so a blocked dispatch is a record, not a silence |
 | `orchestrator.remote_dispatch.completed` | `scripts/lib/wave-executor/remote-dispatch.mjs` (`dispatchRemote`, via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`; name const `REMOTE_DISPATCH_EVENT`) | once per REMOTE-host dispatch over the `offload` CLI (#1160) — the sibling of `foreign_dispatch.completed` on the other channel: that one sends a task to a foreign MODEL on this machine, this one sends a task to Claude on ANOTHER machine. Same reason for existing — a Bash-spawned `offload` child fires no `SubagentStop` hook, so this is the only ledger record a remote dispatch produces. **Payload:** `host` (the `offload` alias, never a hostname or an IP), `role`, `run_id`, `ok`, `exit_code`, `duration_ms`, `patch_files` (COUNT of paths parsed from the returned patch — `+++ b/` plus the `diff --git` header, because a DELETED file's `+++` is `/dev/null`), `patch_bytes`, `reason` (present on every refusal — `never-foreign-role`, `unsafe-run-id`, `unsafe-host`, `unsafe-patch-path` — and on every failure class of a completed run: `usage-config`, `host-unreachable`, `remote-command-failed`, `sync-failed`, `timeout`, `empty-diff`, `rate-limited`, `write-lock-busy`, `channel-unavailable`; absent means success, so no failure class is reasonless), plus `session_id`/`semantic_session_id` via `sessionAttribution` (omitted, never fabricated, without a readable `session.lock`). **Emitted on refusals too** (`ok:false`, `exit_code: null`, `duration_ms: 0`, `patch_files: 0`) — a blocked dispatch is a record, not a silence, and the null exit code is what keeps "refused" distinguishable from "attempted and measured empty". **Deliberately EXCLUDED, pinned by a test:** the prompt text, the patch BODY, and `patch_path` — this payload also travels over the optional Clank webhook with no redaction, and a tmp patch path names the run id and the operator's host |
-| `orchestrator.wave_dispatch.scope_checked` | `hooks/pre-task-scope-disjoint.mjs` (name const `SCOPE_EVENT`; built by `decide()` as `verdict.telemetry`, emitted in `main()` via `emitEvent(..., {repoRoot: projectDir})` + `sessionAttribution(projectDir)`) | PreToolUse `Agent` — **once per dispatch DECISION** (#1092), awaited BEFORE the terminal `emitAllow`/`emitDeny`/`emitWarn`, all of which `process.exit()` and would discard a pending append. **Payload:** `hook`, `agent_id` (the coordinator's `description` + `subagent_type`, clamped to 120 chars), `declared_path_count`, `injected` (a `FILE-SCOPE` declaration was found AND at least one path survived parsing), `shape` (`fenced` \| `inline` \| `none` — which PARSER won, deliberately not a second spelling of `signal`: a fenced block whose lines are prose is `signal: 'unparseable', shape: 'none'`), `signal` (`marker-absent` \| `unparseable` \| `extracted` — the row-5-vs-row-6 distinction of the hook's error-class matrix), `ledger_result` (`no-scope` \| `allow` \| `allow-finished` \| `deny` \| `warn-ledger-corrupt` \| `warn-not-evaluable`), `collision_count` (collisions involving THIS dispatch, live or already-finished — `ledger_result` says which). **Optional, absent-is-not-zero:** `wave` (the number out of `waveKeyOf()`'s `w<N>` segment — **omitted, never `0`**, under the `<session>|w?|?` fallback, same contract as `quality_gate`'s `wave_number`), plus `session_id` / `semantic_session_id` via `sessionAttribution` — omitted, never fabricated, without a readable `session.lock`. **What it proves and what it does not:** that the hook SAW (or did not see) a declaration in the prompt the coordinator handed to the dispatch tool, and what the guard decided — the SEND side. It proves nothing about the block reaching the agent's context or the agent reading it; that receive-side half of #1092 stays open for want of a platform prompt-assembly boundary (`docs/scope-collision-guard.md` § 4.2). **No prompt body and no declared path is in the payload** (issue #1092 acceptance criterion 3) — counts and closed enums only, because this record also travels over the optional Clank webhook with no redaction. Rows 1–4 of the matrix emit nothing (no decision was made) and neither do the two crash rows 2/12 — a hook that fell over cannot describe itself, which is what the `GUARD INACTIVE` stderr banner is for |
+| `orchestrator.wave_dispatch.scope_checked` | `hooks/pre-task-scope-disjoint.mjs` (name const `SCOPE_EVENT`; built by `decide()` as `verdict.telemetry`, emitted in `main()` via `emitEvent(..., {repoRoot: projectDir})` + `sessionAttribution(projectDir)`) | PreToolUse `Agent` — **once per dispatch DECISION** (#1092), awaited BEFORE the terminal `emitAllow`/`emitDeny`/`emitWarn`, all of which `process.exit()` and would discard a pending append. **Payload:** `hook`, `agent_id` (the coordinator's `description` + `subagent_type`, clamped to 120 chars), `declared_path_count`, `injected` (a `FILE-SCOPE` declaration was found AND at least one path survived parsing), `shape` (`fenced` \| `inline` \| `none` — which PARSER won, deliberately not a second spelling of `signal`: a fenced block whose lines are prose is `signal: 'unparseable', shape: 'none'`), `signal` (`marker-absent` \| `unparseable` \| `extracted` — the row-5-vs-row-6 distinction of the hook's error-class matrix), `ledger_result` (`no-scope` \| `allow` \| `allow-finished` \| `deny` \| `warn-ledger-corrupt` \| `warn-not-evaluable`), `collision_count` (collisions involving THIS dispatch, live or already-finished — `ledger_result` says which), `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`. **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` (records that got a per-agent file, i.e. excluding `peer-session-*`), `digest_count` (DISTINCT `scopeDigest()` values among those 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`, `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. **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.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` (clamped to 300 chars) — present ONLY when the never-throws guard fired; their absence means "ran to the end", never "unknown". **`dry_run` is the discriminator, not the event's absence:** the `phase-skip` caller runs dry on EVERY close and is the highest-volume trigger, so consumers filter `dry_run: false` for real runs. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling back to `SO_PROJECT_DIR` — most engine tests pass none, and the fallback would append synthetic records to the real fleet ledger on every `npm test` (#1119, same contract as `express_path.evaluated` and `narrative_mirrored`); a regression test pins it. **Engine identities — the counters are NOT a flat partition, and a live payload reads as inconsistent without them** (source: `scripts/lib/reconcile/engine.mjs:64-83`): `learnings_total === proposals + rejected`, and `capped` + `already_materialized` are DIAGNOSTIC SUB-COUNTS *inside* `rejected`, not siblings of it — each capped or already-materialized learning is also counted as rejected. Within the eligible set: `eligible − proposals − capped === already_materialized`. Worked against a live record: `learnings_total 164 = proposals 10 + rejected 154`, and `eligible 102 − proposals 10 − capped 72 = already_materialized 20` — with `capped 72` and `already_materialized 20` both sitting inside those 154. `already_materialized` is computed BEFORE the volume brake, so a terminal learning never consumes a new learning's quota. `session_id` / `semantic_session_id` / `wave` / `schema_version` are stamped by `emitEvent()` |
 | `orchestrator.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()` |
@@ -126,6 +129,7 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.dialectic.completed` | `scripts/lib/learnings/evolve-telemetry.mjs` (`recordDialecticRun`), called from `scripts/dialectic-deriver.mjs`'s `runDialecticDeriver()` for its FOUR return-based outcomes (`empty-input`, `budget-exceeded`, `would-empty-card`, and the dry-run `ok` success form — all four are values the function itself returns, so it records each one mechanically at the exact return point), and from `skills/evolve/SKILL.md` Step 6.4's apply branch / Step 6.5's two THROWN outcomes (`unknown-model` from `validateModel()`, `subagent-crash` from a failed `dispatchAgent`/`Agent()` call — neither is a `runDialecticDeriver()` return value, so only the skill-prose catcher one layer up can record them; apply-mode success similarly needs the post-merge `mergePeerCard()` stats `runDialecticDeriver()` does not have) | 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 itself for every outcome it alone can determine, and only the two throw-based aborts (of Step 6.5's five-slug abort enum) plus apply-mode's merge-dependent success remain 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), `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.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". 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 so no consumer of the reconcile module gains `platform.mjs`'s module-load filesystem walk-ups |
 | `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 |

package/docs/install.md

@@ -0,0 +1,128 @@
+# Install, Upgrade, Uninstall
+
+Everything the README's short install block leaves out: the full requirement
+matrix, the per-harness install commands with their caveats, how an upgrade is
+detected and performed, and exactly what remains in your repository after an
+uninstall.
+
+- [Requirements](#requirements)
+- [Install](#install)
+- [Upgrade](#upgrade)
+- [Uninstall](#uninstall)
+
+## Requirements
+
+| | |
+|---|---|
+| **Node.js** | **24 or later** (`node --version`) ; `package.json` `engines.node` is `>=24.0.0`. The plugin is ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/). |
+| **A coding agent** | Claude Code, Codex CLI, Cursor IDE, or Pi. This is a workflow layer *on top of* one of them, not a replacement. |
+| **Harness version** | Codex CLI **0.144.4 or later** ([codex-setup.md](codex-setup.md)). No minimum is pinned for Claude Code, Cursor, or Pi; if `/plugin` (or the Cursor/Pi installer) runs, the plugin loads. |
+| **OS** | macOS and Linux are tested in CI. Windows is untested and best-effort; shell hooks and the optional Bash/`jq` MCP server need WSL or Git Bash. |
+| **Git** | A git repository. Session-orchestrator reads git state at every session start and commits at close. |
+
+## Install
+
+| Platform | Install |
+|---|---|
+| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry` (run both inside Claude Code). |
+| **Codex CLI** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs` |
+| **Cursor IDE** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/cursor-install.mjs /path/to/your/project` |
+| **Pi** | `pi install npm:session-orchestrator` ; dev fallback: `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` |
+
+### Headless Claude Code (`claude -p`): two commands need the namespaced form
+
+`session` and `plan` are reserved terminal-only built-in names in non-interactive
+sessions. Under `claude -p` the bare form answers `"/session isn't available in
+this environment."` — that is the harness, not the plugin, and no frontmatter or
+manifest field overrides it (claude 2.1.273, measured 2026-09-16). Use the
+namespaced form:
+
+```bash
+claude -p "/session-orchestrator:session deep"
+claude -p "/session-orchestrator:plan feature"
+```
+
+Every other command keeps its bare form (`/go`, `/close`, `/test`, …), and
+interactive sessions are unaffected.
+
+### Claude Code: install the Node dependencies once
+
+For Claude Code, also install the package's Node dependencies **once** and
+restart Claude Code. First locate the installed plugin:
+
+```bash
+claude plugin list --json
+```
+
+Find the enabled `session-orchestrator@kanevry` entry, then replace the
+placeholder below with its `installPath` value:
+
+```bash
+cd "/absolute/installPath/from/the/list" && npm install
+```
+
+If that entry is missing or disabled, resolve it through `/plugin` first. Use
+the path reported for that entry; another cached version or a nested dependency
+is not the installed plugin.
+
+Setup guides: [Codex](codex-setup.md) · [Cursor IDE](cursor-setup.md) ·
+[Pi](pi-setup.md). Per-IDE notes on which instruction file each harness reads:
+[instruction-file-resolution](../skills/_shared/instruction-file-resolution.md).
+
+## Upgrade
+
+```text
+/plugin update session-orchestrator@kanevry     # Claude Code
+```
+
+Restart the harness afterwards, and re-run `npm install` in the plugin directory
+when the release adds dependencies. On Cursor and the Pi clone fallback, upgrade
+with `git pull` in your clone followed by the same install script you originally
+ran. Manage npm-installed Pi packages through Pi's package manager. For Codex,
+follow the [refresh instructions](codex-setup.md#refresh-and-explicit-cache-invalidation)
+for your marketplace source, then reload the skill picker or restart Codex.
+
+### How you learn that you are behind
+
+Session-start tells you when the running copy is behind:
+`scripts/lib/plugin-update-banner.mjs` compares the version of the code **that
+is actually loaded** against the published npm version and warns in the
+session-start banner (minor or major; patch-only updates stay silent). It fails
+silent: offline, a non-2xx response, or a malformed answer produces *no
+statement*, never a false "up to date".
+
+### Across a major version
+
+**[migration-v5.md](migration-v5.md)** covers the current release: the
+agent-status reader API changes and close-time discovery is enabled by default.
+If upgrading from before v4, also follow **[migration-v4.md](migration-v4.md)**
+for the removed skills, commands and scripts and their replacements.
+[migration-v3.md](migration-v3.md) documents the older v2 → v3 path and the
+shape both guides follow (what changes · prerequisites · per-platform steps ·
+what stays · known issues · rollback).
+
+## Uninstall
+
+Remove the plugin through your harness's own plugin manager: `/plugin` in Claude
+Code (marketplace entry `session-orchestrator@kanevry`), `codex plugin remove`
+on Codex CLI ([codex-setup.md](codex-setup.md)), or Pi's package manager for an
+npm-installed Pi package. On Cursor and the Pi clone fallback, delete the files
+the installer wrote into your project.
+
+### What stays behind in your repo
+
+None of it is removed by uninstalling, and all of it is plain text you can
+delete by hand:
+
+- `.orchestrator/`: `bootstrap.lock`, `metrics/` (your session and learning JSONL records), `policy/`, `steering/`, `runtime/`, `peers/`, `session.lock`
+- `STATE.md` under your harness's state directory (`.claude/STATE.md` on Claude Code; see [Platform support](../README.md#platform-support)) <!-- path-check: example -->
+- The `## Session Config` block you added to your instruction file
+- `.claude/rules/*.md` if you vendored the rule library via `/bootstrap --sync-rules`
+
+Deleting `.orchestrator/metrics/` deletes your session history. Telemetry
+requires explicit consent ([telemetry.md](telemetry.md)). The session-start
+update check (`scripts/lib/plugin-update-banner.mjs`) makes an anonymous `GET`
+to the npm registry to compare your installed version against the latest
+release. Successful results are cached for 24 hours per repo; failed checks can
+retry at the next session start. Set `SO_DISABLE_UPDATE_CHECK=1` (or
+`DO_NOT_TRACK=1`) to turn it off.

package/docs/persona-panel.md

@@ -422,7 +422,7 @@ or commit them if you want an auditable history.
 
 ## See Also
 
-- `commands/persona-panel.md` — command reference: argument syntax, flag validation, examples
+- `skills/persona-panel/SKILL.md` — command reference: argument syntax, flag validation, examples
 - `skills/persona-panel/SKILL.md` — full skill spec: 6 phases, catalog format, dispatch
   mechanics, consolidation logic, sidecar schema
 - `skills/persona-panel/persona-format.md` — persona file format specification: frontmatter

package/docs/pi-setup.md

@@ -76,7 +76,7 @@ The package manifest in `package.json` exposes:
 
 - `pi.extensions`: `./pi/extensions/session-orchestrator.ts`
 - `pi.skills`: `./skills`
-- `pi.prompts`: `./pi/prompts/*.md` generated from `commands/*.md`
+- `pi.prompts`: `./pi/prompts/*.md` generated from `commands/*.md` plus every skill with explicit `user-invocable: true`
 
 The extension uses `hooks/hooks-pi.json` and `scripts/lib/pi-hook-bridge.mjs` to translate Pi events into the existing hook stdin contract.
 

package/docs/rule-authoring.md

@@ -112,7 +112,7 @@ Before `syncRules()` writes a source file into a consumer repo's `.claude/rules/
 
 | Probe | Severity | Rejects / flags |
 |-------|----------|------------------|
-| `paths-frontmatter` | error | A top-level `paths:` frontmatter key — `rule-loader.mjs` only recognises `globs:`; a `paths:` key is silently ignored and the rule loads always-on instead of the intended glob-scoped subset. |
+| `paths-frontmatter` | error | A top-level `paths:` frontmatter key **in a `rules/` library source**. Since #795 `rule-loader.mjs` accepts `paths:` as an alias for `globs:`, so such a rule IS glob-scoped — this is a vendoring-CONVENTION gate (`globs:` is the canonical form for vendored rules, #742), not a loader-compatibility gate. Its population is what `syncRules()` reads, i.e. `<pluginRoot>/rules/**` as listed by `rules/_index.md`; the consolidated files under `.claude/rules/` are `paths:`-canonical (see § Consolidated rules point 3) and are never its input. |
 | `provenance-header` | error (opt-in via `requireProvenance`, default `true` in `syncRules()`) | Missing provenance header on a library source — without it, `rules-sync.mjs` mis-detects the file as a local override on the next re-sync and can never update it again. |
 | `placeholder` | error | Unfilled placeholder tokens: `{{PROJECT_NAME}}`-style handlebars, a `## TODO: Customize` heading, or a `<!-- TODO:` comment — skeleton content, not a finished rule. |
 | `zero-match-globs` | warn | A `globs:` pattern matching 0 files in the target repo's tracked file list (`git ls-files`, falling back to a directory walk). Legitimately possible in a freshly-scaffolded repo. |
@@ -285,19 +285,25 @@ them silently loses a learning or regenerates it:
    TTL past what its type registry granted it.) State the rule in the file
    itself, so the next editor does not "fix" it upward.
 
-3. **Keep BOTH `globs:` and `paths:`, as byte-identical mirrors, each the
-   UNION of the parts.** The merged file loads for any path any of its parts
-   covered, so both lists are the union of theirs — never `globs:` alone.
-   `rule-loader.mjs` resolves `globs:` for wave-time injection, while Claude
-   Code's OWN native rule loader reads ONLY `paths:` and treats a rule
-   lacking it as unconditional, always-on (`check-rules.mjs` check #1108,
-   measured this session) — a `globs:`-only merged file is scoped everywhere
-   it is inspected and loads everywhere it is used, exactly the
-   instruction-budget failure consolidation exists to prevent. `rule-loader.mjs`
-   still resolves `globs:` and `paths:` with `globs:` winning SILENTLY when
-   both are present (issue #795, `parseGlobsFrontmatter`), but keeping the two
-   lists identical makes that precedence moot — there is no divergent value
-   left for it to pick between.
+3. **`paths:` is the canonical scope key, and it carries the UNION of the
+   parts.** The merged file loads for any path any of its parts covered, so its
+   list is the union of theirs. `paths:` is the key Claude Code's OWN native
+   rule loader reads, and it treats a rule lacking it as unconditional,
+   always-on (`check-rules.mjs` check #1108) — exactly the instruction-budget
+   failure consolidation exists to prevent. `globs:` is an accepted ALIAS, not a
+   second required mirror: `rule-loader.mjs` resolves either key
+   (`parseGlobsFrontmatter`, issue #795) and `instruction-budget-guard.mjs`
+   (`:960`) goes through that same parser, so a `paths:`-only file is
+   glob-scoped for every reader in this repo and still counts under
+   `bySurface.pathScoped`. Measured 2026-09-16 over the live tree
+   (`for f in .claude/rules/*.md; do awk '/^---$/{n++;next} n==1 && /^(paths|globs):/{print FILENAME": "$1}' "$f"; done`):
+   10 path-scoped rule files — 9 `paths:`-only, 1 (`cli-design.md`) carrying
+   both. `globs:` is canonical only for rules VENDORED OUT through the `rules/`
+   fleet library, where `validate-vendored-rules.mjs`'s `paths-frontmatter`
+   probe enforces it (issue #742); that probe judges `rules/` sources only and
+   never sees a consolidated file under `.claude/rules/`. Carrying both keys is
+   allowed, but NEVER with different values: `globs:` wins SILENTLY when both
+   are present (#795), and `check-rules.mjs` fails a divergent pair outright.
 
 4. **Substance in, boilerplate out.** Each absorbed learning becomes an `###`
    heading carrying its original rule sentence, plus its evidence line. What is
@@ -330,6 +336,69 @@ This writes `.orchestrator/runtime/reconcile-candidates.jsonl` (creating it if
 absent). Verify with a dry run: `alreadyMaterialized` must equal
 absorbed + dropped, not absorbed alone.
 
+#### The expiry sweep (`scripts/sweep-expired-rules.mjs`, #1377)
+
+`rule-loader.mjs` stops INJECTING a generated rule once its `expires-at` has
+passed; nothing removed one from disk, so an expired consolidated file stayed
+tracked, kept costing bytes against `generated-byte-ceiling`, and kept reading
+as live corpus to every human and every grep. The sweep
+(`scripts/lib/reconcile/rule-expiry-sweep.mjs`, CLI
+`node scripts/sweep-expired-rules.mjs`, `--dry-run` default) closes that gap
+under four contracts, all of them consequences of the four merge rules above:
+
+1. **Prose goes, the pair STAYS.** An expired entry's `###` block is deleted;
+   its provenance pair is converted to the `markers only` shape already present
+   in the corpus — a same-line HTML comment appended to the `- learning-id:`
+   bullet, leaving the backticked value regex-visible to
+   `BODY_LEARNING_ID_RE`. Per point 1, deleting the pair would make the
+   learning look unmaterialized and `/reconcile` would regenerate it. **A pair
+   is never deleted while its file survives.**
+
+2. **Two fail-open cases, both reported rather than guessed.** An entry carries
+   no date of its own; its date is recoverable only via `learning-id` →
+   `.orchestrator/metrics/learnings.jsonl` `expires_at` (measured 2026-09-17 @
+   `9e8146b4`: 87 of 92 unique ids resolve, 5 do not). An **unresolvable id**
+   keeps its entry and blocks the file delete. An **ambiguous file** — where the
+   `###` headings do not map 1:1 onto the non-`markers only` pairs, because
+   several learnings were merged into one prose entry — gets `action: 'keep'`
+   plus a `skipped` record with reason `no-1to1-mapping`. Measured the same day,
+   the 1:1 mapping held in 3 of the 7 live files
+   (`measurement-discipline` 12/12, `process-contracts` 6/6,
+   `toolchain-and-build` 10/10) and failed in the other 4. Malformed
+   `learnings.jsonl` lines are COUNTED (`malformedLines`), never skipped.
+
+3. **Deleting a whole file obeys the stamp-before-delete rule above.** A file is
+   deleted only when it has zero kept AND zero unresolved pairs, and EVERY pair
+   on it — markers-only ones included, since those are dedupe markers too — is
+   stamped via `markCandidateProcessed` BEFORE the `unlink`. Stamping afterwards
+   leaves a window in which neither the file nor a terminal verdict exists.
+
+4. **The header is recomputed only for a file the sweep actually rewrites.**
+   Point 2's earliest-date rule is re-applied over the pairs that remain and
+   are not expired, in the frontmatter and in the body sentence
+   ``**`expires-at` <D> = the EARLIEST of the <N> absorbed dates**``. A file
+   with nothing expired is left BYTE-IDENTICAL, so a recompute-on-every-run
+   cannot silently shorten a healthy file's TTL. The discrepancy is reported as
+   the plan's `advisory` field instead — computed over every RESOLVABLE pair on
+   the file and emitted BEFORE the `no-1to1-mapping` skip, so an ambiguous file
+   still gets one. Measured 2026-09-17
+   (`node scripts/sweep-expired-rules.mjs --json`, 7 files scanned, 0 expired),
+   **6 of the 7 files carry a discrepancy**: `identity-and-locks` 2026-10-01 vs
+   2026-10-02, `measurement-discipline` 2026-10-04 vs 2026-10-02,
+   `process-contracts` 2026-10-04 vs 2026-10-27,
+   `review-and-adapter-contracts` 2026-10-04 vs 2026-10-02, `test-hygiene`
+   2026-10-20 vs 2026-10-07, `toolchain-and-build` 2026-10-01 vs 2026-10-16 —
+   only `guard-design` agrees with its content. Three are the harmful direction,
+   a header OUTLIVING its content (`measurement-discipline`,
+   `review-and-adapter-contracts`, `test-hygiene`); the other three expire
+   earlier than they need to, which costs injection and loses nothing. `N`
+   counts the pairs remaining in the file, which is the total pair count — an
+   absorbed date stays absorbed after its prose is gone, and all 7 live
+   sentences carry that number.
+
+`--apply` emits `orchestrator.rules.expiry_sweep_applied` after the writes
+succeed (see `docs/events-schema.md`); a dry run emits nothing.
+
 ## Authoring Examples
 
 ### (a) Hand-authored always-on rule (no frontmatter)

package/docs/scope-collision-guard.md

@@ -157,6 +157,8 @@ Why it exists: the in-ledger `scopeSignals` counter (§ 4.1, rows 5/6) is a **wa
 
 A cryptographic proof still needs that platform boundary: no mechanism inside this repo can distinguish a copied digest from a read one.
 
+**The digest now JOINS the two halves (#1092, 2026-09-16).** Everything above stays true — what changed is that the halves became joinable at all. `scope_checked` carries `scope_digest` (`scopeDigest()` over the paths extracted from the prompt, omitted for an empty scope rather than defaulted to the empty-string digest), `echo_instruction_present`, `instructed_digest` and `digest_consistent`; `scope_echo_checked` already carried `expected_digest` / `actual_digest`; and `materialize-wave-scope` writes one `scope_materialized` record per wave carrying `transport_observable`. `node scripts/lib/scope-echo.mjs --verify --wave <N> --state-dir <dir>` joins all three **on the digest, never on `agent_id`** — measured 2026-09-16 over this host's ledger, 609 send-side against 51 receive-side records whose agent-id sets overlap in ZERO elements (send records the dispatch `description` + `subagent_type`, receive the coordinator's short handle), so before the digest the two halves could not be paired even in principle. Its closed verdict enum — `matched` · `injected-not-echoed` · `echoed-not-injected` · `injection-missing` · `digest-unknown` · `duplicate-claim`, all degrading to `echo-only` when the transport is unobservable — is what makes the issue's AC-2 (an omitted injection turning an end-to-end probe red) a measurable state rather than an unfalsifiable absence. `digest_consistent: false` additionally catches agent A's fenced block beside agent B's echo line **at dispatch time**, from the prompt alone. None of this raises the ceiling above: a joined digest still proves transport of a LINE, never obedience.
+
 **Revisit-Trigger** (verbatim from issue #1092, for the transport half this section deliberately does NOT close):
 
 > Implement when the platform exposes a stable prompt-assembly hook or when a coordinator-owned digest event can be proven against the real dispatched transcript.

package/docs/session-config-reference.md

@@ -332,7 +332,7 @@ slopcheck:
 | `memory-cleanup-threshold` | integer | `5` | Recommend `/memory-cleanup` after N accumulated session memory files. |
 | `memory-cleanup-soft-limit` | integer | `180` | Hard ceiling on accumulated memory files before the cleanup nudge escalates from a soft suggestion to a strong recommendation. PRD F2.2 / issue #502. Used by `scripts/lib/auto-dream.mjs`. |
 
-**Nudge retirement (2026-09-09, #1246-adjacent).** The two session-end nudges that used to read these thresholds — Phase 3.6.5 Auto-Dream and Phase 3.6.7 Auto-Dialectic — are RETIRED as standalone close-time prompts: measured across consumer repos, the auto-dialectic nudge recorded `decided: true` while nobody ever ran it, and memory-cleanup had run in only 1 of 3 repos, because both fired at the moment the operator is closing down, not the moment they can act. `shouldDispatchAutoDream()` and `shouldDispatchAutoDialectic()` are unchanged as pure signal functions and still consult these two keys — but they are now called from the session-START `maintenance-due` probe (`scripts/lib/maintenance-due-banner.mjs`, see § Reconcile below), which reads them as two of its six signals and reports a single `⚠ maintenance due: N of 6 …` banner at the one moment the operator can actually run `/session housekeeping`.
+**Nudge retirement (2026-09-09, #1246-adjacent).** The two session-end nudges that used to read these thresholds — Phase 3.6.5 Auto-Dream and Phase 3.6.7 Auto-Dialectic — are RETIRED as standalone close-time prompts: measured across consumer repos, the auto-dialectic nudge recorded `decided: true` while nobody ever ran it, and memory-cleanup had run in only 1 of 3 repos, because both fired at the moment the operator is closing down, not the moment they can act. `shouldDispatchAutoDream()` and `shouldDispatchAutoDialectic()` are unchanged as pure signal functions and still consult these two keys — but they are now called from the session-START `maintenance-due` probe (`scripts/lib/maintenance-due-banner.mjs`, see § Reconcile below), which reads them as two of its seven signals and reports a single `⚠ maintenance due: N of 7 …` banner at the one moment the operator can actually run `/session housekeeping`.
 | `learning-expiry-days` | integer | `30` | Legacy/default expiry window used by review/extend flows. New analyzer learnings preserve a candidate-supplied `expires_at` or derive expiry from `LEARNING_TTL_DAYS[type]` (for example, `autonomy-verdict` is 90 days). |
 | `learnings-surface-top-n` | integer | `15` | Cap on how many learnings the session-start Phase 5.6 and session-plan Step 0.5 sections surface, ranked by confidence descending. `0` = do not surface any learnings. Applies to Project Intelligence output. |
 | `learning-decay-rate` | float (0.0 ≤ x < 1.0) | `0.05` | Confidence decay applied to every untouched learning at session-end (after touched-set update, before prune). `0.0` = disable decay. A learning starting at `0.5` confidence survives ~10 untouched sessions with default decay. |
@@ -1008,7 +1008,7 @@ dialectic:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `dialectic.cadence` | integer | `5` | Number of sessions between auto-dialectic dispatches. Set to `0` to disable all dispatches (kill-switch). Non-integer and negative values silently fall back to default. **The dispatch moment moved (2026-09-09):** `shouldDispatchAutoDialectic()` is still the decision function this key feeds, but session-end Phase 3.6.7's own auto-trigger nudge is gone — retired as a standalone close-time prompt, and its recording wrapper (with the `orchestrator.dialectic.nudge_decided` event) removed in #1288 — see § Persistence & Safety above "Nudge retirement". The session-start `maintenance-due` probe now calls it as one of six signals, so a due dialectic surfaces where the operator can act on it (session start), not where they are closing down. |
+| `dialectic.cadence` | integer | `5` | Number of sessions between auto-dialectic dispatches. Set to `0` to disable all dispatches (kill-switch). Non-integer and negative values silently fall back to default. **The dispatch moment moved (2026-09-09):** `shouldDispatchAutoDialectic()` is still the decision function this key feeds, but session-end Phase 3.6.7's own auto-trigger nudge is gone — retired as a standalone close-time prompt, and its recording wrapper (with the `orchestrator.dialectic.nudge_decided` event) removed in #1288 — see § Persistence & Safety above "Nudge retirement". The session-start `maintenance-due` probe now calls it as one of seven signals, so a due dialectic surfaces where the operator can act on it (session start), not where they are closing down. |
 | `dialectic.model` | string | `haiku` | Model tier for the critique call. Must be one of `haiku`, `sonnet`, `opus`. **Fail-fast**: unknown values cause parse-config.mjs to exit 1 at startup — NOT silently ignored. |
 | `dialectic.budget-tokens` | integer | `8000` | Input token budget per call. Output budget is fixed at 4000 (per #506). Non-integer and negative values fall back to default. |
 
@@ -1343,7 +1343,9 @@ Read by: `scripts/lib/config/evolve.mjs` (parser), `skills/evolve/SKILL.md` Step
 
 Opt-in configuration for the learning→conditional-rule reconciliation engine (Epic #693). When enabled, the reconciliation engine runs at session-end Phase 3.6.8 and proposes new `.claude/rules/` entries derived from accumulated learnings. The proposal is always operator-AUQ-gated — rules are **never** auto-applied. FA3 (#696) delivers proposals via `AskUserQuestion`; FA4 (#697) adds the guardrail config block documented here. When `enabled: false` (the default), Phase 3.6.8 is a silent no-op and the engine never runs.
 
-**The former `reconcile-nudge` session-start probe is SUBSUMED (2026-09-09), not replaced 1:1.** `reconcile-nudge-banner.mjs`'s `computeReconcileNudge()` function is unchanged and still the reconcile-specific signal — but it is no longer surfaced as its own standalone banner. `scripts/lib/maintenance-due-banner.mjs` now calls it wholesale as one of six ANDed maintenance signals (`reconcile: computeReconcileNudge().nudge === true`) behind the single session-start `maintenance-due` probe, alongside `evolve`, `sweep`, `dialectic`, `memory-cleanup` and `pending-sidecar`. The reconcile signal is therefore not lost — it is reported as `⚠ maintenance due: N of 6 (…) — run /session housekeeping.` rather than as its own line, with a 7-day cooldown after any housekeeping session (`HOUSEKEEPING_COOLDOWN_DAYS`) so a repo that just ran the loop stays silent instead of re-nagging.
+**The former `reconcile-nudge` session-start probe is SUBSUMED (2026-09-09), not replaced 1:1.** `reconcile-nudge-banner.mjs`'s `computeReconcileNudge()` function is unchanged and still the reconcile-specific signal — but it is no longer surfaced as its own standalone banner. `scripts/lib/maintenance-due-banner.mjs` now calls it wholesale as one of seven ANDed maintenance signals (`reconcile: computeReconcileNudge().nudge === true`) behind the single session-start `maintenance-due` probe, alongside `evolve`, `sweep`, `dialectic`, `memory-cleanup`, `pending-sidecar` and `generated-rules-expiring`. The reconcile signal is therefore not lost — it is reported as `⚠ maintenance due: N of 7 (…) — run /session housekeeping.` rather than as its own line, with a 7-day cooldown after any housekeeping session (`HOUSEKEEPING_COOLDOWN_DAYS`) so a repo that just ran the loop stays silent instead of re-nagging.
+
+**`generated-rules-expiring` (7th signal, 2026-09-16, #1372 follow-up).** Due when a machine-generated rule under `.claude/rules/` is expired or expires within `GENERATED_RULE_EXPIRY_HORIZON_DAYS` (7, a module constant — **no Session Config key**, same posture as every other threshold in this probe). Population and predicate come from `scripts/lib/instruction-budget-guard.mjs` (`listMachineGeneratedRules` / `daysUntilGeneratedRuleExpiry`), the same set its generated byte ceiling judges. The row names the files and their dates, because the repair is per-file: consolidate the content into a live thematic rule, move the `- learning-key:` / `- learning-id:` pairs with it, then delete. `rule-loader.mjs` filters an expired rule at READ time but nothing deletes it, so it keeps costing bytes and is still loaded verbatim by Claude Code (#1372). This alarm deliberately does NOT live in the test suite: an assertion against today's date turns `npm test` red on a calendar date with nothing committed, blocking unrelated work, and no test run can perform the consolidation.
 
 All fields live under a top-level `reconcile` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
 
@@ -1770,7 +1772,7 @@ Leave disabled (default) when:
 - The wave's deliverable is server-side / backend-only and persona evaluation would be noise.
 
 **Related skills and files:**
-- `commands/persona-panel.md` — standalone `/persona-panel` command for ad-hoc panel runs (not gated on `persona-gate-wave.enabled`).
+- `skills/persona-panel/SKILL.md` — standalone `/persona-panel` command for ad-hoc panel runs (not gated on `persona-gate-wave.enabled`).
 - `skills/persona-panel/SKILL.md` — full skill spec (catalog format, consolidation modes, sidecar shape).
 - `skills/wave-executor/wave-loop.md` § 3b — the wave-executor hook contract.
 - `agents/schemas/persona-panel-sidecar.schema.json` — sidecar JSON Schema enforced before write.

package/docs/session-config-template.md

@@ -690,14 +690,19 @@ special: "follow .claude/rules/parallel-sessions.md"
 
 # VCS & infrastructure
 vcs: gitlab
+gitlab-host: gitlab.example.com        # only if remote URL doesn't expose it
 mirror: github
 cross-repos: []
+pencil: path/to/design.pen             # design-code alignment input
 ecosystem-health: true
 health-endpoints: []
 issue-limit: 50
 stale-branch-days: 7
 stale-issue-days: 30
 
+# Auto-skill dispatch
+auto-skill-dispatch: false             # opt-in; phrase-match meta-skill — see skills/using-orchestrator/SKILL.md
+
 # Quality
 ssot-files: [STATE.md]
 ssot-freshness-days: 5
@@ -711,6 +716,12 @@ discovery-severity-threshold: low
 discovery-confidence-threshold: 60
 discovery-parallelism: 5
 
+# Issue budget — QUANTITY cap on issue creation (not a quality filter)
+issue-budget:
+  max-per-session: 12                  # non-exempt issues one session may create (0 = block all)
+  mode: strict                         # strict | warn | off
+  overflow: collect-issue              # collect-issue | vault-note
+
 # Persistence & safety
 memory-cleanup-threshold: 5
 memory-cleanup-soft-limit: 180
@@ -731,6 +742,10 @@ isolation: auto
 max-turns: auto
 auto-commit-per-wave: false            # opt-in: commit after each wave's Quality-Lite PASS (V3.6 plumbing)
 
+# Heavy-repo preflight & worktree hygiene (HR-003)
+heavy-repo: false                      # true clamps the dispatched agent count to agents-per-wave
+worktree-cleanup: default              # default | aggressive
+
 # Env-aware
 resource-awareness: true
 enable-host-banner: true
@@ -815,6 +830,29 @@ templates-first:
   enabled: true
   hosts: [github, gitlab]
 
+# Wave reviewers — opt-in inter-wave architecture/QA/PRD audit dispatch (#461 / #478)
+wave-reviewers:
+  enabled: false                       # opt-in; absent, false, or an empty reviewers array = no-op
+  reviewers: []                        # ["architect-reviewer", "qa-strategist", "analyst"]
+  mode: warn                           # warn | strict | off
+
+# Persona gate — opt-in persona-panel fan-out after a wave (#458)
+persona-gate-wave:
+  enabled: false                       # opt-in
+  after: quality                       # quality | impl-polish
+  threshold: all                       # all | any | <m>-of-<n>
+  personas: []                         # persona slugs the panel dispatches
+  dispatch-model: claude-opus-4-7
+  mode: off                            # off | warn | strict — enabled: true with mode: off never fires
+
+# Agentic test orchestrator (/test) — run profiles and artifact retention
+test:
+  enabled: false                       # opt-in
+  default-profile: smoke               # profile name looked up in profiles-path
+  profiles-path: .orchestrator/policy/test-profiles.json
+  mode: warn                           # warn | strict | off
+  retention-days: 30                   # days test-run artifacts are kept (0 = no cleanup)
+
 # Verification auto-fix loop (PRD gsd Pattern 4 / #521)
 verification-auto-fix:
   enabled: false

package/docs/telemetry.md

@@ -21,6 +21,21 @@ it is the locked v1 schema and consent precedence this plugin implements.
   [Relationship to `telemetry-claims.md`](#relationship-to-telemetry-claimsmd)
   below.
 
+## Your data stays in your repo
+
+Session Orchestrator runs locally, requires no account, and writes its records
+as append-only JSONL under `.orchestrator/metrics/` in *your* repository:
+sessions, learnings, events, subagent records. Those files are yours: readable,
+greppable, deletable. The optional anonymous usage telemetry described on the
+rest of this page is **off until you explicitly consent** and is a separate
+channel from those local records — turning telemetry on or off changes nothing
+about what is written locally, and deleting the local records sends nothing
+anywhere.
+
+Reported metrics describe *this* repository under its own conditions and will
+not transfer unchanged to yours
+([telemetry-claims.md](telemetry/telemetry-claims.md)).
+
 ## What we collect
 
 When telemetry is enabled and a batch is flushed, the payload is built from