session-orchestrator 3.22.0 → 3.23.0

package/docs/cursor-setup.md

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

package/docs/events-schema.md

@@ -58,8 +58,10 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.session.started` | `hooks/on-session-start.mjs` | SessionStart |
 | `orchestrator.session.ended` | `hooks/on-session-end.mjs` | SessionEnd |
 | `orchestrator.session.stopped` | `hooks/on-stop.mjs` | Stop |
+| `orchestrator.session.backfill_completed` | `hooks/on-session-end.mjs` (`emitBackfillOutcome`) | SessionEnd, once per backfill call (#1068 AC2 — the backfill outcome is canonically queryable, the side-log is no longer the only result source). Payload: `kind` (`abandoned`\|`state-md-completed`), `action` (the backfill result action, e.g. `appended`\|`superseded`\|`skipped-already-recorded`\|`unknown`), plus `session_id`, `semantic_session_id`, `record_id`, `supersedes`, `reason` — each OMITTED when unknown, never `null` |
+| `orchestrator.session.root_left` | `scripts/lib/session-transition.mjs` (`leaveSourceRoot`) | a session left a repo root for good — the process-boundary teardown of Worktree-Auto-Promotion (#1069), emitted into the OLD root's stream after `deregisterSelf()` + `release()`, whether or not either found anything. NOT emitted when the teardown ABORTED (invalid args, a lock owned by another session, an unparseable lock): the event asserts a root was left, and on those branches none was. Payload: `session_id`, `semantic_session_id` (OMITTED when unknown, never `null`), `from_root_hash` (`repoPathHash()` of the abandoned root — the SAME hash the session registry keys its entries by, so a departure joins to the entry it removed), `from_root_basename` (matching the registry's `repo_name`), `reason` (e.g. `worktree-promotion`). **Never the absolute root:** this payload also travels over the optional Clank webhook with no redaction, and an absolute root on a developer host is `/Users/<operator>/…` — same rule as `board_written` / `mirror_completed` and `relativeWorktreePath` in `worktree-pipeline.mjs`. Its absence beside a live-looking registry entry is the phantom-peer signature the event exists to make visible |
 | `orchestrator.session.lock.acquired` | `hooks/_lib/lock-bootstrap.mjs` | SessionStart |
-| `orchestrator.session.lock.released` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) | after a `release()` that matched ownership (#952). Payload: `session_id`, `caller` (`on-session-end`\|`worktree-pipeline`), `outcome` (`deleted`\|`already-gone`), `verified`; hook-side additionally `lock_session_id`, `semantic_session_id`, `end_reason` (the SessionEnd reason — deliberately NOT `reason`, which the sibling `release_failed` uses for the failure reason); pipeline-side additionally `worktree_path`, `issue_iid`. `outcome: 'already-gone'` means the lock had ALREADY vanished between `readLock()` and `release()` — the forensically interesting case, since a successful release previously left no trace at all and a missing lock was therefore indistinguishable from a lock someone else deleted (#914 residual 3) |
+| `orchestrator.session.lock.released` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) · `scripts/lib/session-transition.mjs` (`leaveSourceRoot`) | after a `release()` that matched ownership (#952). Payload: `session_id`, `caller` (`on-session-end`\|`worktree-pipeline`\|`session-transition`), `outcome` (`deleted`\|`already-gone`), `verified`; hook-side additionally `lock_session_id`, `semantic_session_id`, `end_reason` (the SessionEnd reason — deliberately NOT `reason`, which the sibling `release_failed` uses for the failure reason); pipeline-side additionally `worktree_path`, `issue_iid`. The `session-transition` caller emits only this event and no `release_failed` sibling — a failed release there is reported to its caller as `{ ok: false, reason: 'lock-<reason>' }`, which the promotion prose must WARN on, so the stream is not the only witness. `outcome: 'already-gone'` means the lock had ALREADY vanished between `readLock()` and `release()` — the forensically interesting case, since a successful release previously left no trace at all and a missing lock was therefore indistinguishable from a lock someone else deleted (#914 residual 3) |
 | `orchestrator.session.lock.release_failed` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) | ownership matched but `release()` did NOT delete the lock (#724). Payload: `session_id`, `reason` (`fs-error`\|`session-mismatch`\|`not-deleted`\|`threw`), `caller`; pipeline-side additionally `worktree_path`, `issue_iid` |
 | `orchestrator.session.lock.reconcile_attempted` | `hooks/_lib/lock-reconcile.mjs` | SessionEnd, when NEITHER ownership check matched the recorded lock (#748). Payload: `session_id`, `action` (`reaped`\|`skipped`\|`unknown`), `reason` (e.g. `own-host-pid-alive`) |
 | `orchestrator.session.lock.reaped` | `scripts/lib/lock-reaper.mjs` | a dead lease was reaped. Payload: `session_id`, `semantic_session_id`, `host`, `pid`, `age_hours`, `reap_mode`, `current_session` |
@@ -67,19 +69,89 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.memory.propose_invoked` | `hooks/pre-bash-memory-propose-audit.mjs` | PreToolUse(Bash) |
 | `orchestrator.wave.started` / `.completed` | `hooks/post-tool-batch-wave-signal.mjs` | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612); an explicit injected `wave_signal` still takes precedence |
 | `orchestrator.quality_gate.passed` / `.failed` | `scripts/run-quality-gate.mjs` (the gate CLI — live between waves) · `scripts/lib/quality-gate.mjs` (`emitGateEvent` inside `runQualityGateWithRetry`, reached ONLY under `verification-auto-fix.enabled: true` — default `false`, and `false` in this repo) | CLI: once per gate-CLI run. Library: once per `runQualityGateWithRetry` **call**, never per retry attempt (`attempts` carries that detail). The two paths never nest, so one run passes through exactly one emitter. **Payload (both):** `variant`, `exit_code`, plus `session_id` / `semantic_session_id` when `sessionAttribution()` finds a session lock (both omitted when it does not). CLI `variant` is the `--variant` value (`baseline`\|`incremental`\|`full-gate`\|`per-file`); the library pins `variant: 'auto-fix-loop'`. **CLI only:** `wave_number`. **Library only:** `attempts` (1…`maxRetries+1`) and `gate` (`lint`\|`typecheck`\|`test` — the fail-fast gate of the last attempt; omitted on the passing path). **Optional on both:** `counts: {passed, failed, total}`. **Absent is not zero — for both optional fields.** `counts` is admitted by the ONE shared policy `admitSuiteCounts()` (`scripts/lib/gates/gate-helpers.mjs`, #967 item 2), which returns `null` — never a zero triple — for an unmeasured or inconsistent input (test gate skipped/stubbed, fail-fast on lint or typecheck before the test step, no parseable `<N> passed` marker, or `passed + failed !== total`); both callers spread `...(counts ? { counts } : {})`, so the KEY is missing in those runs. A present `counts.failed: 0` therefore means "measured, zero failures", while an absent `counts` means "not measured" — reading a missing field as `0` mis-analyses the ledger in both directions. Same contract for `wave_number` (CLI, #966 step 1): resolved from the `.{pi,cursor,codex,claude}/wave-scope.json` sidecar, **omitted** — never `0` — when there is no sidecar or its `wave` is non-numeric/non-positive; a human running `npm run quality-gate` from a `git push` has no wave at all, so an invented wave 0 would have to be special-cased by every consumer. Note `total` is `passed + failed` and EXCLUDES skipped/todo (see `extractTestCounts`) |
+| `orchestrator.scope.foreign_session_ignored` | `hooks/enforce-scope.mjs` (Gate 3b, #1123) | PreToolUse Edit/Write — exactly once per gated tool call while a FOREIGN-session `wave-scope.json` is live: the manifest's `session`/`semantic_session` provably name another session, so the hook allows instead of enforcing. **Payload:** `hook`, `manifest` (path), `manifest_session` (string[]), `own_session` (string[]), `wave`, `file_path`. Legacy manifests without a `session` field never emit this — they stay enforced |
 | `orchestrator.grounding.injected` | `scripts/compute-grounding-injection.sh` (via `scripts/emit-event.mjs`) | grounding injection, when `PERSISTENCE=true` |
 | `orchestrator.handover.gated` | `skills/session-end/SKILL.md` Phase 1.65 (skill-prose, via `scripts/emit-event.mjs`) | Handover-Alignment-Gate outcome (#773). Payload: `candidates_total`, `auto_carry`, `asked`, `dropped`, `questions_asked`, `questions_answered`, `questions_deferred`, `path` (`fast_path`\|`triage`\|`weiterarbeiten`\|`fail_open`). Emitted exactly once per close — including the fail-open skip and the "Weiterarbeiten" abort — so never-measured paths become observable |
+| `orchestrator.vault.board_written` | `scripts/lib/vault-status/board-writer.mjs` (`emitBoardEvent`; name const `BOARD_EVENT`) | exactly ONE record per `mirrorBoard()` call, and therefore per `sweepBoard()` call — the sweep never double-emits. Call sites: the `mirrorBoard` wrapper through which all six inner return points funnel, and `sweepBoard`'s two paths (happy + enumeration-failure fallback). **Payload:** `action` (always — including every no-op: the five `skipped-vault-disabled` guards at `:803/:812/:817/:821/:829`, plus `skipped-handwritten`, `skipped-noop`, `skipped-write-failed`, `dry-run`, `written`), `caller` (always, `mirrorBoard`\|`sweepBoard`). **Optional, absent-is-not-zero:** `path_tail` (the BASENAME only — never the full path: under `01-projects/` the parent directory is the private project slug, and this payload also travels over the optional Clank webhook with no redaction), `rows`, `repos_swept`, `duration_ms`, plus `session_id` / `semantic_session_id` via `sessionAttribution(repoRoot)` (#1147 — the SAME root the record is pinned to, so attribution can never name a different tree than the ledger line; both keys omitted, never fabricated, when no `session.lock` is readable) — the numeric three admitted via `Number.isFinite(...)` / `typeof === 'string'`, NOT truthiness, so a measured `repos_swept: 0` survives while an unmeasured field is omitted. The enumeration-failure fallback deliberately omits `repos_swept`. **A throw from the inner function emits nothing** — `action` is mandatory and a throw has no action the code knows; inventing one would put a fictional state in the ledger (#1073) |
+| `orchestrator.vault.narrative_mirrored` | `scripts/lib/vault-status/narrative-mirror.mjs` (`emitNarrativeEvent`; name const `NARRATIVE_EVENT`) | one record per `mirrorNarrative()` call, from the thin wrapper — every outcome plus the throw path (`action: 'error'`, then re-throws). The old body became `runNarrativeMirror()`, so an early return added later is telemetered by construction. Covered: `skipped-vault-disabled` ×4, `skipped-invalid-path`, `skipped-no-statemd`, `written`, `skipped-noop`, `skipped-handwritten`, `dry-run`. **Payload:** `action` (always); optional `path_tail` (BASENAME only, same reason as `board_written`), `chars`, `session_id`, `semantic_session_id` (via `sessionAttribution`), `error_code` (throw path only — the error MESSAGE is deliberately not recorded, it can quote a path or STATE.md prose). **Named gap with a revisit trigger:** when `repoRoot` is absent, NOTHING is emitted — `emitEvent` would fall back to `SO_PROJECT_DIR` and the two rootless unit tests would append synthetic records to this repo's real ledger on every suite run. This deliberately diverges from `board-writer.mjs`, which emits there (#1073) |
+| `orchestrator.vault.mirror_completed` | `scripts/lib/vault-mirror/telemetry.mjs` (`emitMirrorEvent`; name const `MIRROR_EVENT`), called from `scripts/lib/vault-mirror/process.mjs` (`emitAction`, reached from all **18** of its call sites — census `grep -n 'emitEntryAction' scripts/lib/vault-mirror/process.mjs`, 2026-08-23) and from the two `skipped-invalid` branches in `scripts/vault-mirror.mjs` | **ONE record per JSONL entry processed, EXCEPT `skipped-noop`** (#1151: noop dominates a steady-state run; its count survives in the run-event's `skipped` total + `action_breakdown`) — `created`, `updated`, every other `skipped-*`, and both invalid paths. Until #1147 it was **failure-only**: only the two `skipped-invalid` branches emitted, which is why this repo's ledger held **0** records of it against 1272 `orchestrator.secret_masker.applied` from the same CLI (measured 2026-08-23). A healthy run was therefore indistinguishable from a broken emitter — the gap the sibling `orchestrator.vault.mirror_run_completed` row below closes. **Payload:** `action` (the SAME string the entry wrote to stdout), `kind`, `line` (1-based JSONL line — the only locator when a record has no id). **Optional, absent-is-not-zero:** `record_id` (the record's `id` / `session_id`), `path` (**vault-RELATIVE**, never absolute: this payload also travels over the optional Clank webhook with no redaction — omitted on `skipped-invalid` and on the pre-path quality skips, which are reached before a target path exists), `skip_class` (`validation` | `mapper-crash`, invalid branches only — mirrors the stdout `reason` verbatim so the failure class stays groupable without string-matching), `reason` (the renderer's message on the invalid branches, or the existing `meta.reason` string on a quality skip — `confidence:X < min:Y` / `narrative:N < min:M` / `status:…` — REUSED from the stdout payload rather than recomputed; clamped to 300 chars), `dry_run`, `session_id` / `semantic_session_id`. `record_id` / `path` / `skip_class` / `reason` treat **`null` as not-measured** and are omitted: a `record_id: null` would read as "measured, empty id" rather than "this record had none". **Attribution is read at `SO_PROJECT_DIR`, explicitly** — `readLock()` defaults to `process.cwd()`, so a bare `sessionAttribution()` would attribute the record to whatever tree the process happens to run in while the ledger line lands under `CLAUDE_PROJECT_DIR`. Same root for both halves or neither. The ledger destination stays the 2-arg `emitEvent` default so every event of one run shares it: this CLI has no repo-root flag, and deriving one from `--source` would split a single run's telemetry across two ledgers |
+| `orchestrator.vault.mirror_run_completed` | `scripts/lib/vault-mirror/telemetry.mjs` (`emitMirrorRunEvent`; name const `MIRROR_RUN_EVENT`), called from `finishRun()` in `scripts/vault-mirror.mjs` — the ONE close-out function every exit routes through (the happy tail, the malformed-JSON abort, the filesystem-error abort, and the top-level `main().catch`), latched so it can only fire once | exactly ONE record per CLI run, **unconditionally** — beside the `orchestrator.secret_masker.applied` emit and BEFORE the `--strict-schema` abort, so a failing run still reports its denominator. **This event is the denominator the per-entry row above lacks:** a healthy run over an empty source emits zero per-entry records, and so does a run whose emitter is broken — from the ledger the two are identical (`.claude/rules/host-resources.md` § HR-105). **Payload:** `kind`, `total` (non-blank JSONL entries attempted), `created`, `updated`, `skipped` (every non-failure `skipped-*` class), `failed` (`skipped-invalid` — validation error or mapper crash; split out because those are the entries whose session silently ends up WITHOUT a vault note), `dry_run`. **These five counters are ALWAYS present, including as `0`** — this is the one place a written zero is the payload rather than a violation of "absent is not zero", because each was measured over the whole run; `total: 0` is a measured empty run and the record's ABSENCE is the broken-emitter signal. `created + updated + skipped + failed === total` for any run that does not abort (pinned by a test). **Optional, and the discriminator that keeps the counters honest:** `aborted` (`malformed-json` | `filesystem-error` | `unexpected-error` | `missing-vault-dir` | `vault-not-canonical` | `missing-source` (#1151: the three pre-loop exit-2 aborts now close the run out through finishRun())) — present ONLY when the run exited before its tail, absent means "ran to the end" and never "unknown". Its presence says the five counters are PARTIAL (every line after the abort was never attempted), so the classes stop partitioning `total` and that gap must be read as an abort, not as producer/consumer drift. Until it existed, the two `process.exit` calls inside the entry loop and the `main().catch` jumped straight over this emit: the runs an operator most wants counted were the ones that vanished from the ledger, in the exact shape ("no record") the paragraph above reserves for a broken emitter. **Optional:** `action_breakdown` (per-`action` counts, keyed by the same strings the entries wrote to stdout — enumerates only actions that OCCURRED, so a missing key there means zero occurrences; the always-present `total` makes that reading unambiguous, and the key itself is omitted when nothing was processed), plus `session_id` / `semantic_session_id` via the same `SO_PROJECT_DIR`-pinned `sessionAttribution` as the per-entry event |
+| `orchestrator.secret_masker.applied` | `scripts/vault-mirror.mjs` (beside the vault-mirror run) | once per vault-mirror run, unconditionally. Payload carries `channel: 'vault-mirror'`. **Undocumented until 2026-08-23, at which point it had over a thousand records** — and that omission actively misled: a census grepping event NAMES for `board\|mirror` returns 0 and reads as "the mirror emits nothing", while run-level presence was in fact already observable through THIS event's payload. Grep the `channel`, not the name |
+| `orchestrator.probes.completed` | `scripts/lib/session-start-probes.mjs` (`runSessionStartProbes`), called from `hooks/on-session-start.mjs` | once per SessionStart, after the Phase-4 measurement probes run. **This event is the whole point of #1073:** the 18 module-backed probes had **zero** mechanical callers across `hooks/`, npm scripts, CI and husky — their only caller was prose in `skills/session-start/SKILL.md` — and across the 336 session starts recorded up to 2026-08-23 there was **no banner event at all**, so whether they ever ran was unfalsifiable (`.claude/rules/host-resources.md` § HR-105). **Payload:** `total`, `ran`, `warned`, `skipped`, `errored`, `timed_out`, `duration_ms`, and `probes` — one `{id, outcome, reason?}` per probe — `reason` travels whenever one was recorded, because `module-absent` (a permanently dead entry) must be distinguishable from `network-probe-opt-in` (the intended default); `outcome` ∈ `ran-clean`\|`ran-warn`\|`ran-alert`\|`skipped`\|`timeout`\|`error`. Two invariants are asserted by tests: `total === probes.length` and `ran + skipped + errored + timed_out === total`. **The count is 18, not the 19 Phase 4 appears to list:** four Phase-4 items are prose-only measurements with no module and no entry function (SSOT freshness, quality baseline, Pencil design status, plugin freshness) — 22 measurements, 18 wireable probes. **Network probes (`ci-status`, `mirror-issues`) are excluded by default** and appear as `outcome: 'skipped', reason: 'network-probe-opt-in'` — never omitted, because omitting them would rebuild the defect one layer down. Opt in with `SO_PROBES_INCLUDE_NETWORK=1`. The grounds are measured, not assumed: `hooks/hooks.json` gives the WHOLE SessionStart hook `timeout: 5` seconds while each network probe carries its own 8 s CLI timeout, so one slow network probe alone exceeds the hook's entire budget and takes the started-event and the banner down with it; warm-and-authenticated best case measured 520 ms / 498 ms, paid on every start of every repo. **Budget:** `PROBE_BUDGET_MS = 2000`; measured median against this repo **968 ms** (5 runs, 855–1104), 130–229 ms in a fresh tmp repo. Revisit trigger: median past HALF the budget, or any single probe past the budget → move the slow probes off the hook's critical path, do NOT raise the number. **Named ceiling:** the deadline is enforced at await points, so it is hard for async/network probes and advisory for the two that shell out synchronously (`project-hygiene`, `tests-src-ratio`). Escape hatch: `SO_DISABLE_STARTUP_PROBES=1`. **Deliberately NOT gated on `enable-host-banner: false`** — that preference governs DISPLAY; gating the RUN on it would rebuild exactly the unfalsifiable blind spot this event removes |
+| `orchestrator.express_path.evaluated` | `scripts/lib/express-path.mjs` (`evaluateExpressPath`, emit in `_emitEvaluated`; name const `EXPRESS_PATH_EVENT`) | once per Phase-8.5 evaluation — **on refusal as well as activation**. Until #1119 this was unrecordable twice over: `scripts/lib/config.mjs` discarded the `express-path` key **even when the block was present** (synthetic probe: 88 keys emitted, none of them this one), and the decision lived only in `skills/session-start/phase-8-5-express-path.md` prose, so it fired only when a coordinator read that prose. Ledger evidence, measured 2026-08-23 @ `34321bc` (a count, so read it as history, not as state): **0** express events at that point, against 22 of the last 30 sessions running with no wave at all — every one of them `housekeeping`, the exact population the path targets. **Payload:** `activated` (always, boolean), `reasons` (always — the BLOCKING codes on refusal, the satisfied ones on activation; nothing short-circuits, so a refusal names every blocker and a reader can tell whether trimming the issue list alone would have helped). **Optional, absent-is-not-zero:** `enabled`, `session_type`, `task_count`, `parallel_agents_required`, plus `session_id`/`semantic_session_id` via `sessionAttribution`. An unmeasured `sessionType` or `taskCount` fails CLOSED (`reasons: ['session-type-unknown','task-count-unknown']`) — defaulting unknown scope to 0 would activate a gate-skipping path on data nobody supplied. **Four inputs, not three:** activation condition 3 carries two clauses (`≤ 3 issues` AND no parallel agents), which both condition matrices list as a non-activating row. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling through to `SO_PROJECT_DIR` — that is the wave-1 incident of this session (a probe with an unexported var wrote a synthetic record into the real fleet ledger) made structurally impossible; a regression test reproduces it. `events.mjs` is imported lazily so `config.mjs`'s 48-file import graph does not gain `platform.mjs`, which runs filesystem walk-ups at module load |
+| `orchestrator.foreign_dispatch.completed` | `scripts/lib/wave-executor/foreign-dispatch.mjs` (`dispatchForeign`, via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`) | once per foreign-model dispatch (#1150) — the replacement for `SubagentStop` telemetry, which cannot fire for a Bash-spawned `cursor-agent` child (no hook in the chain sees it). **Payload:** `model`, `role`, `ok`, `exit_code`, `timed_out`, `duration_s`, `changed_files` (count, tracked-modified ∪ untracked-new — `git diff` alone is blind to new files), `reason` (present on every refusal — `never-foreign-role`, `empty-diff`, `channel-unavailable`, `unsafe-*` — and on the failure classes of a completed run, so no failure class is reasonless), `hook_tampering` (tri-state: `true` = the child repointed/rewrote the shared `.git` hooks path, invalidates the run regardless of `ok`; `false` = fingerprint matched; absent/`null` = not measured, never read as clean), plus `session_id`/`semantic_session_id` via `sessionAttribution` (omitted, never fabricated, without a readable `session.lock`). Emitted on refusals too (`ok:false`), so a blocked dispatch is a record, not a silence |
+| `orchestrator.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 |
 
 Non-orchestrator names still present in the stream: `tmux-layout.{invoked,completed,degraded}`
-(tmux-layout skill) and `stagnation_detected`. (`grounding_injected` was migrated to
-the dotted `orchestrator.grounding.injected` in #611 — see the catalog above.)
+(tmux-layout skill) and `stagnation_detected`. The latter keeps its legacy bare name
+deliberately — it predates the `orchestrator.` convention, and renaming it in the same change
+that wired its first producer would have stacked a breaking stream change on top of a behaviour
+change (#1114). (`grounding_injected` WAS migrated, to the dotted
+`orchestrator.grounding.injected` in #611 — see the catalog above.)
+
+### `stagnation_detected` — two producers, one schema (#1114)
+
+| Producer | `source` | Trigger |
+|---|---|---|
+| Coordinator prose, `skills/wave-executor/wave-loop.md` § "Review Agent Outputs" | `"coordinator"` | post-wave review, per agent, when a stagnation pattern fires. Routed through `scripts/emit-event.mjs` / `emitEvent()` like every other event — the hand-rolled `>>` append it used to prescribe is gone |
+| `scripts/lib/wave-transcript-tail.mjs`, run as the `wave-transcript-tail` monitor (`monitors/monitors.json`, `when: on-skill-invoke:wave-executor`) | `"tail"` | live, while the wave runs: tails the own session's subagent transcripts and matches three executable regexes |
+
+**Payload:** `session` (the **SEMANTIC** session id — the value that matches
+`sessions.jsonl.session_id`, e.g. `main-2026-08-24-session-1`, measured 2026-08-25; this is the
+join key `skills/session-end/metrics-collection.md` filters on, `.session == $sid` where `$sid` is
+`$SESSION_ID`. A raw UUID here would join to nothing. The `session_id` / `semantic_session_id` pair
+that `sessionAttribution()` contributes is additive provenance beside it, and is OMITTED rather
+than fabricated when no `session.lock` is readable — so `session` is the field consumers rely on),
+`wave`, `agent`,
+`pattern`, `source`, `file` (project-relative path, or `null` when not applicable), `occurrences`.
+`pattern` ∈ `pagination-spiral` | `turn-key-repetition` | `error-echo` | `psa007-git-write` |
+`status-partial` — the first two are coordinator-only, the last two tail-only, and `error-echo` is
+produced by BOTH, so `source` is the only thing that tells those two records apart. `source` ∈
+`coordinator` | `tail` and is **additive**: a consumer that does not read it behaves unchanged.
+**Optional, absent-is-not-zero:** `error_class` (`edit-format-friction` | `scope-denied` |
+`command-blocked` | `other`) is present on `error-echo` ONLY and omitted for every other pattern —
+an absent field means "no class applies", never `"other"`. **`occurrences` is an
+AGGREGATION-WINDOW counter, not a fixed value.** Monitor output is rate-limited, so a key emits
+once when it reaches its threshold (`3` for `error-echo` and the two coordinator threshold
+patterns, `1` for the single-shot `psa007-git-write` / `status-partial`) and then RE-EMITS only
+every further `RE_EMIT_EVERY = 10` hits, carrying the running total. A single-shot detector that
+fires 21 times therefore produces `occurrences` `1`, `11`, `21` — three records, pinned by the
+`toEqual([1, 11, 21])` assertion in `tests/lib/wave-transcript-tail.test.mjs`. Read a value above the threshold as "this many hits
+so far in this window", never as "this many new hits". `agent_id` (tail-produced
+records only, additive): the per-dispatch agent id from the transcript filename — needed because
+`agent` carries the agent TYPE and a wave routinely runs several agents of one type (measured
+2026-08-25: 2 `Explore` in one wave), so restart-dedup keyed on type alone would suppress a
+sibling's genuine first finding. Coordinator-produced records omit it.
+
+**Measured before wiring — read as history, not as state.** 0 records in this repo's 30 785-line
+ledger (`grep -c '"stagnation_detected"' .orchestrator/metrics/events.jsonl` → 0, exit 1;
+2026-08-25 @ `ebce189`), and 0 across 97 816 event lines in 19 repos (asserted, source W1/D3
+2026-08-25 — re-measure before citing it further). That zero is the denominator the wiring is
+judged against (`.claude/rules/host-resources.md` § HR-105: a class at 0% is either genuinely rare
+or silently broken, and the two look identical from outside). Until #1114 the event had no
+producer at all — its only mechanical reference across `scripts/ hooks/ commands/` was a READER,
+`scripts/compute-grounding-injection.sh:88`, which filters on `error_class` + `file` and degrades
+correctly on records carrying neither. If the ledger still reads 0 after the tailer has observed
+five waves, that is a finding about the repo, not about the emitter.
+
+**Dated caveat — records written before `FIXTURE_CONTEXT_RE` are not reproducible.** The
+`psa007-git-write` record emitted 2026-08-25 ~05:01 was a false positive: a sibling agent seeding a
+test fixture in a `mktemp -d` scratch repo, whose index is not the shared one PSA-007 protects.
+`isGitWrite()` gained the fixture-context exclusion (`scripts/lib/wave-transcript-tail.mjs`) after
+that record was written, so replaying the same transcript against today's detector yields no hit.
+Read pre-exclusion `psa007-git-write` records as artefacts of the older detector — the ledger line
+stands as history and is not retracted, but it is not evidence about current behaviour. The same
+five 2026-08-25 04:59–05:01 records also carry the RAW session uuid in `session` (a bare
+`06461b1a-…` where the semantic `main-2026-08-25-session-N` belongs), which is the pre-fix shape —
+they join to no `sessions.jsonl` row and will not appear in a per-session roll-up.
 
 ## Consumers
 
 - `scripts/lib/convergence-monitor.mjs` — tails events.jsonl; reads `event_type ?? event`.
 - `scripts/lib/tmux-layout/telemetry-stats.mjs` — filters `event.startsWith('tmux-layout.')`.
 - `scripts/lib/events-rotation.mjs` — size-based archival.
-- `skills/session-end/metrics-collection.md` — jq roll-ups (incl. `orchestrator.grounding.injected`).
+- `skills/session-end/metrics-collection.md` — jq roll-ups (incl. `orchestrator.grounding.injected` and `stagnation_detected` → `stagnation_events`).
+- `scripts/compute-grounding-injection.sh` — filters `stagnation_detected` on `error_class` + `file` to build each agent's edit-friction history; ignores records carrying neither (which is every `psa007-git-write` / `status-partial` record).
 
 Renaming an existing event name is a breaking change to the stream + these
 consumers — verify with `grep` (PSA-006) and update consumers in lockstep.

package/docs/github-mirror-protection.md

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

package/docs/pi-setup.md

@@ -18,6 +18,8 @@ pi install npm:session-orchestrator
 
 This is the primary install path — the package is published to npm (since v3.16.0, 2026-07-19) and carries the `pi-package` keyword for the [Pi packages gallery](https://pi.dev/packages) index; no local checkout required. The dev-fallback options below remain available for working against a local checkout.
 
+The short git form documented for Pi packages (`pi install git:github.com/user/repo`) is **unverified against this repo as of 2026-08-28** — the `pi` CLI was not installed on the verifying host (`which pi` → not found), so no install attempt could be made. The npm form above remains the only measured, documented install path; do not elevate the `git:` short form to this guide or to README until it has been run against this repo and the result dated.
+
 ### Option 2: Project-local registration (dev fallback)
 
 ```bash

package/docs/rule-authoring.md

@@ -118,7 +118,9 @@ Before `syncRules()` writes a source file into a consumer repo's `.claude/rules/
 | `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. |
 | `foreign-glob` | warn | A glob segment carrying a PascalCase, product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope. |
 
-Error-severity violations skip the write for that file (recorded in `syncRules()`'s `errors[]`); warn-severity violations do not block the write and are recorded additively in `warnings[]`. The standalone CLI (`node scripts/lib/validate-vendored-rules.mjs --dir <rulesDir> [--target-root <repo>] [--require-provenance] [--json] [--mode hard|warn]`) exits `0` (no errors, or errors under `--mode warn`), `1` (errors present under `--mode hard`), or `2` (invocation error).
+Error-severity violations skip the write for that file (recorded in `syncRules()`'s `errors[]`); warn-severity violations do not block the write and are recorded additively in `warnings[]`. Since #1098 the envelope also carries `sanitizer[]` — `{file, line, kind, text}` records from `scanVendoringLeaks()` for plugin-internal citations that resolve to a real file under the plugin root (`scripts/…`, `hooks/…`, `skills/…`, `docs/…`, `tests/…`) and for `See Also` references that name no entry in `rules/_index.md`. The sanitizer is report-only: it never rewrites content and never contributes to `errors[]`, so a finding changes neither the write decision nor the exit code — a human decides whether the citation is a leak. `rules-sync.mjs`'s CLI additionally prints each finding to **stderr** as `rules-sync: sanitizer <kind> <file>:<line> — <text>`, so the report reaches an operator who never parses the JSON envelope.
+
+`scanVendoringLeaks()` itself lives in `scripts/lib/validate-vendored-rules.mjs` (it has the validator's shape — judge one rule file, return findings); `rules-sync.mjs` re-exports it for importers that predate the move. The standalone CLI (`node scripts/lib/validate-vendored-rules.mjs --dir <rulesDir> [--target-root <repo>] [--plugin-root <dir>] [--require-provenance] [--json] [--mode hard|warn]`) exits `0` (no errors, or errors under `--mode warn`), `1` (errors present under `--mode hard`), or `2` (invocation error). Passing `--plugin-root <dir>` turns on the same sanitizer scan there: findings appear under a `sanitizer` key in `--json` mode and as `validate-vendored-rules: sanitizer <kind> <file>:<line> — <text>` stderr lines otherwise. The `unresolvable-see-also` half needs `<pluginRoot>/rules/_index.md` to be readable; when it is not, only the `repo-local-path` check runs. Report-only there too — `sanitizer[]` never moves the exit code.
 
 ### Archetype-scoped manifest tags (issue #722 Epic A Wave 3)
 

package/docs/scope-collision-guard.md

@@ -37,6 +37,31 @@ Steps 1, 2, 3, 4 and the `--assert-subset` assertion all read the *same* file, a
 
 The coordinator's **own** planned direct edits belong in `coordinator.json` in the identical form. They are not dispatches, so the hook can never see them (§ 6); the CLI check is the only gate that covers them.
 
+### 2.3 The manifest names its writer (#1123)
+
+`wave-scope.json` is written into the WORKING COPY, not into the session — so until #1123 one session's manifest governed every session sharing that checkout. Measured 2026-08-22 (#1082): a Discovery wave's `allowedPaths: []` — which `wave-loop.md` prescribes for *every* Discovery wave — denied every write of an unrelated parallel session, with a deny reason that could only tell it to fix a wave plan it does not own.
+
+Two OPTIONAL manifest fields close that: `session` (the raw `session_id`) and its human-readable twin `semantic_session`. Both come from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`, reads `.orchestrator/session.lock` once) in the same coordinator step that writes the rest of the manifest — `skills/wave-executor/wave-loop.md` § Scope Manifest 1.
+
+The reader is `hooks/enforce-scope.mjs` **Gate 3b**, between the manifest parse (G3) and the path-guard gate (G4). It resolves identity via `readOwnSessionIds(projectRoot, { hookInput: input })` and classifies via `classifyManifestSession(scope, ownIds)`, both from [`scripts/lib/session-identity/own-session.mjs`](../scripts/lib/session-identity/own-session.mjs):
+
+| Manifest state | `classifyManifestSession` verdict | Gate 3b disposition |
+|---|---|---|
+| no `session` / `semantic_session` (legacy, pre-#1123) | `unknown` | ENFORCE — falls through unchanged |
+| an id present and matching one of our own | `own` | ENFORCE — falls through unchanged |
+| ids present, none matching, own identity resolvable | `foreign` | **ALLOW** + one `orchestrator.scope.foreign_session_ignored` event |
+| ids present, own identity unresolvable (empty id set) | `unknown` | ENFORCE |
+
+Five properties are choices, not omissions — and every one of them points the fail-**closed** way, the deliberate inverse of § 4.1's posture for the dispatch hook:
+
+- **Only what is PROVABLY foreign is foreign.** `readOwnSessionIds()` returns the **UNION** of three sources — hook input (`session_id`/`sessionId`/`parent_session_id`) ∪ `CLAUDE_CODE_SESSION_ID` ∪ `session.lock` (`session_id`/`semantic_session_id`) — and an EMPTY set when none yields an id, which can only produce `unknown`. A gate that guessed would turn "cannot tell" into a silent enforcement-off on every harness exporting no session id. Every value is trimmed on the way in, so a whitespace-only env var cannot enter as a phantom id that matches nothing (`.claude/rules/development.md` § env-var whitespace trap).
+- **Union, not first-tier-wins.** Any id the process can legitimately claim names this session; only an id in NO source is somebody else's. Gating the sources made the READER's identity a strict subset of the WRITER's — the manifest's `session` comes from `sessionAttribution()` = the same repo-global lock — and three divergences all produced the same silent failure, the OWN manifest read `foreign` and the write gate switched itself off for the whole wave, logging an event indistinguishable from correct behaviour: (a) a nested harness where payload `session_id` ≠ `CLAUDE_CODE_SESSION_ID` (measured in `hooks/pre-bash-issue-budget.mjs` `resolveSessionId`); (b) a sub-agent invocation, whose own id is the subagent's while the manifest names the coordinator; (c) a session that lost the lock race and therefore wrote a PEER's id into its own manifest (see the writer guard below). The union only ADDS ids the process actually carries, so the security direction is unchanged: a manifest whose id appears in no source still classifies `foreign`. Its cost is named and points fail-**closed** — a peer-owned lock makes us enforce a peer's wave plan, which is a visible deny rather than a silent enforcement-off.
+- **The writer verifies the binding names itself.** Because the lock is repo-global, `skills/wave-executor/wave-loop.md` § Scope Manifest 1 requires the coordinator to compare `sessionAttribution()`'s ids against its own session (STATE.md `session`) and to OMIT the `session`/`semantic_session` keys when they diverge — unbound = ENFORCE. The reader's union covers the case anyway; the writer guard keeps the manifest readable as an audit record instead of publishing a foreign name.
+- **Gate 3b runs after the parse, never on the raw bytes.** A corrupt manifest yields `{}`, hence no ids, hence `unknown` — and keeps failing closed. A gate that peeked at the bytes first would let a truncated manifest disarm the guard.
+- **The empty string is a validator ERROR, not a third flavour of absent.** `validateSession()` → `validateOptionalSessionId()` in `scripts/validate-wave-scope.mjs` rejects `"session": ""` with *"an empty id attributes to nothing; omit the key entirely to declare the manifest unbound"*. An empty id satisfies a truthiness check while matching nobody, so every reader would classify the manifest FOREIGN where the writer meant UNBOUND — opposite dispositions, not a cosmetic ambiguity. An ABSENT key only WARNS, because the § 3.3 pre-union skeleton is itself an unbound manifest and so is every manifest written before #1123.
+
+The event is what keeps the skip countable rather than silent: `orchestrator.scope.foreign_session_ignored` carries `hook`, `manifest`, `manifest_session`, `own_session`, `wave` and `file_path`. It is deliberately an event and not an `emitWarn` — the branch is hit on *every* Edit of the non-owning session, so a stderr line per write would be noise the operator learns to ignore.
+
 ## 3. The collision algorithm
 
 `findScopeCollisions(agentScopes, { knownFiles })` compares every cross-agent entry pair through `classifyEntryCollision()`, in three binding stages:
@@ -104,6 +129,24 @@ Two structural rules keep this matrix honest, both recorded in the hook header:
 - `decide()` is a **pure function returning a verdict**; the module emits exactly once, at the end. `emitWarn`/`emitDeny` call `process.exit(0)` and never return, so a warn emitted from inside the checking flow would terminate the process before a later collision could be denied — and would skip the lock's release `finally`.
 - Row 9's discriminator is **not** `ok !== true`. `ok` means *disjoint*, so `ok === false` is the normal result of a real collision; "not evaluable" is `ok === false` with BOTH result arrays empty. Reading `ok` as evaluability would turn every genuine collision into a warn, i.e. an allow — the exact fail-open the hook exists to prevent.
 
+### 4.2 Observability — one record per dispatch decision (#1092)
+
+Every dispatch that reaches a verdict also appends one `orchestrator.wave_dispatch.scope_checked` record to `<projectDir>/.orchestrator/metrics/events.jsonl` (payload contract: [`docs/events-schema.md`](events-schema.md)). It is built inside `decide()` as `verdict.telemetry` and emitted by `main()` — awaited **before** the terminal `emitAllow`/`emitDeny`/`emitWarn`, each of which calls `process.exit()` and would discard a pending append — inside a `try/catch`, so a failed write can never change the verdict or the exit code.
+
+Why it exists: the in-ledger `scopeSignals` counter (§ 4.1, rows 5/6) is a **wave tally**. It answers "how many dispatches of this wave carried a scope", never "which agent was dispatched unscoped" — and a wave in which the injection step was skipped entirely still produces a plausible-looking tally. The per-dispatch record makes the individual dispatch falsifiable (`.claude/rules/host-resources.md` § HR-105).
+
+**What the event proves:** the hook SAW — or did not see — a `FILE-SCOPE` declaration in the prompt the coordinator handed to the dispatch tool, which declaration shape parsed it (`shape`), whether any path survived (`injected`, `declared_path_count`), and which matrix row decided (`ledger_result`, `collision_count`). That is the **send** side, measured at the PreToolUse boundary.
+
+**What it does not prove:** that the block reached the agent's context, or that the model read it. Those are **receive**-side facts, and this hook observes the tool payload, not the assembled prompt. A record reading `injected: true` is therefore evidence about the coordinator's dispatch, never about the agent's obedience — reading it as the latter rebuilds exactly the false confidence § 2.2 warns about. The counterpart signal on the receive side remains the agent's own behaviour (`enforce-scope` at write time) and the W5 verification pass.
+
+**Payload discipline.** Counts and closed enums only, plus `agent_id` (the coordinator's own dispatch description, clamped) and the optional session attribution: no prompt body, no declared path, no glob. Issue #1092's acceptance criterion 3 is the rule, and the reason is concrete — this record also travels over the optional Clank Event-Bus webhook with no redaction, and paths under `01-projects/` carry private project slugs.
+
+**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.
+
+Until then the issue's remaining acceptance criteria — a scope-file **digest** proven to have reached the prompt assembler, and an omitted/malformed injection turning an end-to-end probe red while materializer, disjointness, union and subset checks stay green — are not satisfiable by any mechanism inside this repo, because no observable boundary carries the final prompt.
+
 ## 5. The liveness probe
 
 A ledger with no notion of completion denies the wrong thing. Measured over 38 archived transcripts of this repo (346 `Agent` dispatch blocks; hook header, 2026-08-14): 0 of 4 same-batch overlaps and **2 of 2 cross-dispatch overlaps** would have been denied — and both cross-dispatch pairs were legitimate **sequential repair passes** (a dispatch and its later fix). Because a deny deliberately does not persist the ledger, the re-dispatch would have met the same stale record: a permanent block.
@@ -129,6 +172,9 @@ Complete list of what this guard does **not** see, or sees only approximately:
 6. **Glob ∩ glob without witnesses.** Stage 3a needs tracked files; with git unavailable (row 8) or for files not yet on disk, only stage 3b's prefix fallback carries the load — and it requires at least one recursive entry, so two non-recursive globs that intersect only in an unborn file are not detected.
 7. **Only collisions involving the current dispatch are actionable.** A pair among already-dispatched agents was either denied at its own dispatch or predates the guard; re-denying it would block an innocent third agent.
 8. **Lock loss reopens the race.** On lock timeout the cycle runs unlocked (row 14) — two dispatches starting together can then read the same ledger state and one record is lost. That is the pre-lock behaviour, chosen over denying on a lock-file problem.
+9. **The session binding is self-declared** (§ 2.3). `session` is a plain field in a file any process in this working copy can write, so writing a foreign id into it turns the write gate off for that manifest. Named rather than hidden: it is the SAME power `enforcement: "off"` already grants in the same file, so Gate 3b adds no new authority — the manifest is the coordinator's own artefact either way.
+10. **Only the WRITE gate is session-bound.** The dispatch ledger of § 4 takes its session component from the harness's own `input.session_id` (`waveKeyOf(projectDir, sessionId, …)`), and reads only `wave` and `role` out of `wave-scope.json` — the `session` field is not consulted there at all. So a peer session's manifest cannot bind this session's writes since #1123, but the two hooks reach that property by different routes, and a change to one does not carry to the other.
+11. **A peer-owned lock costs enforcement precision, deliberately.** `readOwnSessionIds()` unions the `session.lock` ids in (§ 2.3), and the lock is repo-global — so while a peer holds it, that peer's manifest classifies `own` here and its `allowedPaths` bind this session's writes: the #1082 shape, but now as a visible deny naming a wave plan we do not own. The alternative (gating the lock behind the payload) fails the other way and silently, because the manifest's own `session` is written from that same lock. Bounded by the writer guard in `skills/wave-executor/wave-loop.md` § Scope Manifest 1 (omit rather than write a foreign id) and by `session.lock` heartbeat-liveness. Revisit if a manifest ever carries the writer's PROCESS identity alongside the lock-derived one, which would let the reader distinguish the two cases instead of unioning them.
 
 ## 7. Debugging
 
@@ -138,7 +184,7 @@ Complete list of what this guard does **not** see, or sees only approximately:
 - The other agent has finished, but the ledger still binds it → the transcript carried no evidence (§ 5) and you are inside the TTL window. Delete `.orchestrator/wave-dispatch-scopes.json`; the next dispatch rebuilds it.
 - The `waveKey` names an older wave → the `<session>|w?|?` fallback (limit 5). Check that `<state-dir>/wave-scope.json` exists and is readable, then delete the ledger.
 
-**A dispatch was NOT denied and should have been.** Work down the allow rows: is `FILE-SCOPE` present in the prompt with a fenced block right after it (rows 5/6)? Is the hook armed at all (`GUARD INACTIVE` on stderr = row 2)? Did a `systemMessage` warning appear (rows 7/9)? Cross-check the same scopes through the CLI, which does not depend on prose:
+**A dispatch was NOT denied and should have been.** Start at the ledger line, which now says which row fired without re-running anything: `jq -c 'select(.event=="orchestrator.wave_dispatch.scope_checked")' .orchestrator/metrics/events.jsonl | tail` — `injected:false` with `signal:"marker-absent"` is row 5 (no declaration in the prompt at all, i.e. the injection step, not the guard), `signal:"unparseable"` is row 6 (a declaration the parser could not use), `ledger_result:"allow-finished"` is row 10a (the collision was real but its partner had finished), and NO record at all for a dispatch you watched happen means the hook never ran or crashed before deciding (§ 4.2). Then work down the allow rows: is `FILE-SCOPE` present in the prompt with a fenced block right after it (rows 5/6)? Is the hook armed at all (`GUARD INACTIVE` on stderr = row 2)? Did a `systemMessage` warning appear (rows 7/9)? Cross-check the same scopes through the CLI, which does not depend on prose:
 
 ```bash
 node scripts/validate-wave-scope.mjs --assert-disjoint "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
@@ -163,5 +209,6 @@ Re-measure before citing any of these downstream. A count re-briefed later is a
 
 - `skills/wave-executor/wave-loop.md` § Scope Manifest — the coordinator runbook (steps 3.1–3.3) and § Pre-Dispatch: File-Scope Injection (the prompt block shape).
 - `.claude/rules/parallel-sessions.md` § Decision Tree (why a file in two declared scopes is never a benign sibling signal), § PSA-006 (measurement discipline).
-- `hooks/enforce-scope.mjs` — the write-time gate, fail-**closed**; the deliberate inversion of this hook's posture.
+- `hooks/enforce-scope.mjs` — the write-time gate, fail-**closed**; the deliberate inversion of this hook's posture. Its Gate 3b is the reader of the § 2.3 session binding; `scripts/lib/session-identity/own-session.mjs` holds the identity half.
+- `skills/_shared/state-ownership.md` § `wave-scope.json` Session Binding — the same contract from the ownership side (which shared working-copy artefact belongs to which session).
 - [`docs/adr/0011-guard-degradation-semantics.md`](adr/0011-guard-degradation-semantics.md) — the exit-0 hook protocol (#906) and why a truncated stdout envelope reads as no-decision, i.e. as ALLOW.