session-orchestrator 3.21.0 → 3.23.0

package/CHANGELOG.md

@@ -7,6 +7,275 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.23.0] - 2026-08-28
+
+Two commits today (1 `feat`, 1 `fix`; 64 files, +4,971/−184) close Waves 3 and 4 of the
+resumed session, plus eight items carried forward from Wave 2 (`36aa605`, 2026-08-26,
+never previously changelogged). No `BREAKING CHANGE:` footer and no `!` subject. The
+pattern repeats across both waves: a guard, sanitizer, or census that already existed but
+checked the wrong population or stopped short of the surface it needed to reach — a parity
+guard sampling five rule files by name instead of reading the directory, a sanitizer whose
+findings never reached stderr, a byte-count drifting 338 lines from the line it cited, a
+tracked directory hiding an untracked hook beside it.
+
+One `feat` commit (session-2, `30940cb`, 2026-08-28; 39 files, +2,475/−405) closes Wave 2
+with three GitHub-mirror fixes and a session-identity cluster at the process boundary. No
+`BREAKING CHANGE:` footer and no `!` subject. The through-line: identifiers the platforms
+mint (UUIDv7, semantic session ids) were rejected or dropped by readers built for UUIDv4
+only — every resume looked foreign — and call sites that needed a repo root passed
+`undefined` instead, so fail-open paths ran on every invocation.
+
+### Added
+
+- **Eight core rules ship as sanitized copies, with a report-only leak scanner (#1098).**
+  `rules/always-on/` holds sanitized copies of `ask-via-tool`, `build-value`,
+  `loop-and-monitor` and five more; `scanVendoringLeaks()` now reaches stderr as one line
+  per finding in both CLIs, folded into `validate-vendored-rules` with a rule-ID census.
+- **Session Config fails loud on an unparsable line (#1097).** `collectUnparsableLines`
+  gates warn/strict via one `htmlCommentSkipper` shared by extractor and classifier — a
+  commented-out `enforcement: strict` had been reading as live config.
+- **A read-only protection-audit CLI, with a runbook naming the order (#1079).** States
+  the required sequence; never flips a setting itself.
+- **The scope guard now emits `orchestrator.wave_dispatch.scope_checked` (#1092).** Closes
+  the ledger half that never recorded a signal-free ALLOW.
+- **`/journey-audit` — a user-facing product audit as a repeatable skill (#1161).** Skill,
+  command and manifest template; skill/command counts measured at 48/28.
+- **A Cursor `.mdc` parity guard that reads the directory, not a fixed list (#1093).**
+  Catches bare `PID=`/`${VAR}` IDs a name-sampling guard had missed; `priority::` swept
+  across all 5 files.
+- **The old root now formally leaves before the new one claims it, wired at all four
+  promotion sites (#1069).** `scripts/lib/session-transition.mjs` → `leaveSourceRoot()`:
+  `deregisterSelf()` → lock-release (reusing `on-session-end`'s ownership rules) →
+  `orchestrator.session.root_left` (carries `source_root_hash`/`source_root_basename`,
+  never an absolute path — the payload also travels over the optional webhook). Review
+  found the Phase-1.2.1 promotion site had been missing the call; it is now wired at
+  session-start Phase 0.5, Phase 1.2.1, and both `parallel-aware-*` docs. A real
+  `git worktree` two-root integration test goes phantom-peer red → green.
+
+### Fixed
+
+- **Six onboarding contradictions + a `cursor-install` TARGET guard (#1078).** First
+  production diff authored by a foreign model (composer-2.5) under mandatory Claude review.
+- **Amber is now a documented normal state (#1062).** `docs/ci-setup.md` names it instead
+  of leaving it an unexplained CI color.
+- **A tracked directory no longer hides an untracked hook beside it (#1158).**
+  `hooksPathIsTracked` now requires a GIT-tracked file directly under `core.hooksPath`.
+- **`probe-stale` collapses to one vocabulary term (#1159).** A record older than 7 days
+  is `probe-stale`, severity `warn`, never a live finding; the registry remap is gone.
+- **The scope-cap saw operators, not shell keywords (#1145).** `splitSegments` now splits
+  on keywords too, so `for t in a b c; do glab issue create; done` no longer slips a
+  compound-statement head past the cap.
+- **A missing `.claude/rules/` was misdiagnosed as a loop (#1132).** `err.code` now
+  separates silent `ENOENT`/`ENOTDIR` from loud `EACCES`; the repeat was caller fan-out.
+- **Two probes measured the wrong population (#1143/#1148).** One counted a whole file and
+  cited a line that had already drifted 338 lines from the finding; both scanners read the
+  filesystem instead of the git index, censoring 5 gitignored files as documentation.
+- **Generated rules now self-verify offline (#1101).** Each carries a sha256 seal over its
+  own Evidence block instead of a learning-key into a gitignored file; 23 rules sealed,
+  fresh-clone warnings 23 → 0.
+- **`reconcile.targets` had zero consumers (#1099).** Now wired through with a closed enum,
+  visible rejection of unknowns, and per-target path confinement.
+- **Orphaned wave-scope files survived re-materialization (#1103).** Reconciled by
+  ownership proof now, never a blind directory wipe — two parallel sessions can share one
+  wave-N directory (PSA-003).
+- **Two rival vendoring paths wrote the same rule file (#1060).** `rules/` is now sole SSOT
+  for PSA-001..007; `templates/_shared/rules/` is deleted.
+- **`parseSessionId` accepted only UUIDv4; Codex mints v7 (#66/#1091).**
+  `scripts/lib/session-id.mjs` now accepts RFC-9562 v1–8 (`UUID_RE`, additive `version`
+  field — see `### Removed` below for the alias this superseded). Every SessionStart had
+  minted a fresh v4; a
+  resumed/compacted thread read its own lock as a foreign session. `hooks/on-stop.mjs` and
+  `hooks/on-session-end.mjs` now apply the writer's acceptance rule, closing a lock-leak via
+  non-UUID stdin ids.
+- **phase-3-7a called `updateFrontmatterFieldsOnDisk(undefined, …)` (#65/#1036).**
+  `skills/session-end/phase-3-7a-recommendations.md` requires a repo root; every `/close`
+  took the fail-open path — 0 of 5 recommendation fields were ever written. The snippet now
+  binds `repoRoot` via `git rev-parse --show-toplevel`; the catch logs the cause.
+- **Codex MCP launch resolved to `/scripts/mcp-server.sh` from non-git cwd (#64).** Codex
+  copies a marketplace plugin to
+  `~/.codex/plugins/cache/<marketplace>/session-orchestrator/<version>/` and starts the MCP
+  child with no plugin-root env var. `.mcp.json` and `scripts/lib/plugin-root.mjs` gained a
+  plugin-cache scan tier (name-matched `package.json`, newest by mtime). Codex snapshots
+  `.mcp.json` at install time — existing installs need a reinstall.
+- **`scoring.mjs` read a flat `completion_rate` 0 of 281 records carry (#1071).** The value
+  lives under `effectiveness`, so the high-completion bonus was unreachable.
+  `resolveMemoryDir`/`buildLiveSignals` now take an explicit `repoRoot` instead of
+  `process.cwd()`.
+- **mission-status recovery aborted on the first non-canonical body line (#1104).**
+  `scripts/lib/state-md/mission-status.mjs` now skips per line, reports skipped lines
+  (`recoverFrontmatterMissionStatusDetailed`). `setMissionStatus` refuses ids outside the
+  grammar with a stderr WARN from the on-disk wrapper.
+- **`enterWorktree` failed with `already used by worktree` when the source branch was
+  checked out (#1067).** `scripts/lib/autopilot/worktree-pipeline.mjs` now creates
+  `so/<sessionId>` from that branch and returns `branch`/`promotedFrom`.
+- **Phase 4a auto-promoted-worktree cleanup was dead under the #1069 process boundary.**
+  Since the promoted worktree runs as a brand-new session with its own id,
+  `detectAutoPromotedWorktree()`'s basename match against the CURRENT session id could
+  never fire post-#1069. `enterWorktree()` now writes `.orchestrator/promoted-from.json`
+  (source-root hash + basename, source session id, branch) at creation time;
+  `detectAutoPromotedWorktree()` tries this marker FIRST (`source: 'marker'`), falling back
+  to the legacy basename match (`source: 'basename'`) for pre-marker worktrees.
+  `isWorktreeClean()` discounts exactly the marker's own untracked line so the marker never
+  reads as dirty by itself. Re-promoting onto an existing `so/<sessionId>` branch now reuses
+  it (`reusedBranch: true`) or reports a typed refusal, instead of failing outright. See
+  ADR-0013.
+- **`.mcp.json`'s bash bootstrap had silently drifted from `resolvePluginRoot()`'s tier
+  order.** The shell mirror now matches the same five env tiers in the same order, tests
+  `package.json`'s `name` field via `node -e JSON.parse(...)` instead of a substring `grep`
+  (which had matched `session-orchestrator-fork`), and ties the newest-by-mtime cache scan
+  to the same strict `-nt` comparison as the JS side. Two drift tests pin JS and shell
+  staying in sync.
+- **`ci-status-banner.mjs` escaped control bytes in the JSON preview but not in the
+  parse-error message.** `JSON.stringify()` alone is not enough — V8 quotes the raw
+  offending input inside `SyntaxError.message`, carrying control bytes straight to the
+  terminal. `escapeControlBytes()` now covers both the preview AND `err.message`;
+  `parseCliJson()` also gained a shape-gate against `null`/`[]`/a bare `"ok"` string, all of
+  which parse as valid JSON but are not the object/array shape callers expect.
+- **A refused mission-status write warned on only 1 of 5 call paths.**
+  `setMissionStatusDetailed()` now reports the refusal reason (e.g. `id-grammar`) to every
+  caller, and the on-disk wrapper emits the stderr WARN on all 5 paths instead of the one it
+  happened to cover before.
+- **`check-unwired-features` exempted itself from its own edge census via its allowlist
+  string, hiding a real orphan behind it.** The `SELF_REL` self-reference correctly
+  contributes zero edges by design, but the same code path was masking that
+  `scripts/lib/webhook-url.mjs` has zero callers repo-wide — genuinely unreachable, not a
+  false positive. Follow-up issue pending to wire it in or remove it.
+- **Three load-sensitive tests hardened with margin instead of being disabled.**
+  `tests/scripts/validate-plugin.test.mjs`'s child-process timeout moved from 30s to 120s (a
+  killed child returns `status: null`, which had read as a different failure than a real
+  one) plus a matching `hookTimeout` bump, and two further spawn-timeout assertions gained
+  the same discriminating margin between contention and a genuine failure.
+
+### Changed
+
+- **Host-registry census counts `semantic_session_id` (#1066).** `hooks/on-session-start.mjs`
+  falls back to `session_id` only when it is itself semantic. Before, only UUIDs were
+  projected — the n-increment discards them — so the registry contributed nothing to
+  numbering.
+- **Session end events carry `semantic_session_id`; backfill event + supersede (#1068).**
+  `orchestrator.session.ended` / `.stopped` carry `semantic_session_id` (omitted when
+  unknown). A new `orchestrator.session.backfill_completed` event records each backfill outcome. A
+  completed record may now supersede an `abandoned` stub (append-only, `supersedes` marker).
+  Readers preferring the newest record are a follow-up.
+- **`.semgrep.yml` regains two taint-mode rules (#1129).** `json-parse-untrusted-input` and
+  `prototype-pollution-object-assign` aimed at this repo's real trust boundary (hook stdin,
+  child-process stdout); 27 rules total. `unsafe-llm-output-rendering` stays excluded with a
+  measured reason (no DOM code).
+
+### Removed
+
+- **`UUID_V4_RE` removed** from `scripts/lib/session-id.mjs` — deprecated alias of
+  `UUID_RE` with zero importers repo-wide (measured @ 7daa3d2; hits in
+  `tests/telemetry/anon-id.test.mjs` and `server/ingest/validate.mjs` are unrelated local
+  constants of the same name). Use `UUID_RE`, any RFC 9562 version 1–8.
+
+### Notes
+
+Two of this session's diffs were authored by foreign models under the #1150 adapter —
+#1078 by composer-2.5, #1093 by grok-4.6 — each passing mandatory Claude review before
+landing. First production use of the foreign-dispatch path.
+
+## [3.22.0] - 2026-08-22
+
+Twenty commits (12 `fix`, 5 `docs`, 2 `feat`, 1 `chore`; 150 files, +17,312/−2,575), no
+`BREAKING CHANGE:` footer and no `!` subject. One strand runs through all of it:
+**an instrument that reported confidently and measured the wrong quantity.** Not a
+threshold set too tight, not a rule too strict — the wrong quantity, reported with the
+same certainty as the right one. The host-resource warning fired on **99.0% of 1,477
+measured session starts** and nobody could falsify it, because the two fields it was
+computed from were never persisted. A hygiene probe announced "37 files (11 MB)" while
+sizing the entire directory instead of the 37 — factor ~18 — and proposed deleting
+version-controlled source files, because it never asked git. And the questions this tool
+puts to its operator had never been measured at all: **21 of 72 passed** on first
+measurement, and the single dominant cause was a 12-codepoint header limit that silently
+truncated 30 of them.
+
+### Added
+
+- **The operator's questions are now measured before he reads them (#1107).** `scripts/auq-audit.mjs`
+  scores every `AskUserQuestion` block and every prose fallback list against eight criteria
+  (K1–K8) plus two hard hurdles, all thresholds sourced from one registry — no hard-coded
+  number in the scorer. The census found **three populations, not one**: 40 Claude Code blocks,
+  10 Codex prose lists, and 17 that every prior count had missed (9 `.cursor/rules/*.mdc` with
+  10 choice blocks, plus 6 runtime questions inside `.mjs`). Baseline **21 of 72 (29%)**, after
+  the pass **72 of 72**. The dominant cause was structural: `header` caps at 12 codepoints and
+  the tool truncates silently — **26 of 42 headers exceeded it**, and one NFD-composed header
+  measured 12 visible characters as 14, destroying the question. Population A — the operator's
+  own path — ran 62% failing against 0% for the Codex and Cursor forms, which carry no header
+  at all.
+- **A guard on the guard (#1122 groundwork).** The `AskUserQuestion` PreToolUse hook denies only
+  the two hard hurdles and reports the rest to stderr; `check-auq-clarity` is wired into
+  `validate-plugin` and blocks on H1/H2 with a measured 0% false-positive rate. Its own wiring is
+  proven by fake regression, not asserted.
+- **`/eli5`** — say the last answer again in plain words, same facts, in the order the operator
+  needs them.
+
+### Fixed
+
+- **The warning that fired on 99.0% of all session starts (#1089).** Measured over **1,477
+  `orchestrator.session.started` events across 18 repos**: `ram_free_gb < 2` fired on 84.0%,
+  `claude_processes >= 5` on 93.6%, any of the three on **99.0%** — against 4,884 stop events
+  with zero OOM markers. Three independent measurement errors, no threshold among them.
+  (a) `os.freemem()` on Darwin reports only `Pages free` — median **0.4 GB** on hosts with
+  24–128 GB — so memory is now judged on `memory_pressure_pct_free` and a better signal
+  *replaces* a worse one rather than suppressing it. (b) `concurrent-sessions-warn` is
+  denominated in sessions and was compared against a process count; measured ratio **6.0:1**.
+  Same threshold, right denominator: 93.6% → **4.2%**. (c) One noisy axis could cap a wave;
+  now two independent soft signals must agree. The verdict had reached `sessions.jsonl` for
+  **15 of 1,734 sessions (0.9%)**, which is why the false alarm survived four months while six
+  repos independently wrote it into their learnings store — one at confidence **1.0**.
+  Codified as `.claude/rules/host-resources.md` (HR-101..106).
+- **A standing condition is not a second opinion (#1089 follow-up).** The first live run of the
+  rebuilt verdict returned `warn | cap 2 | soft: ["cpu","zombies"]`. Zombie processes are idle
+  by definition — they cannot cause the load they are paired with — and are always present
+  (6, 13 and 9 in three readings minutes apart). They report; they never count toward the
+  two-signal rule.
+- **A probe that sized the wrong set and never asked git.** `checkStaleArtifacts` computed its
+  byte figure over the whole of `.orchestrator/` instead of the aged subset it names —
+  the 37 files weighed **0.68 MB against 11 MB reported**. Independently, it consulted git
+  nowhere and therefore proposed pruning seven tracked, runtime-read source files, among them
+  the policy file `pre-bash-templates-first.mjs` reads and the two steering documents
+  session-start loads. The git exclusion is fail-**silent**, not fail-open: falling back to
+  "nothing is tracked" *is* the defect it closes.
+- **Only the raw session ID releases a lock (#1085).** One session carried three identities —
+  STATE.md said `session-2`, the lock said `session-3`, issue-budget counted against a third
+  UUID — and `findPeers` reported the session's own presence as a foreign peer. The semantic
+  ID is now attribution metadata only; a release requires exact raw-ID equality, and a
+  semantic hint resolves to a raw ID only against a verified local binding. The companion fix
+  to issue-budget removed a data-loss path in which an identity-less invocation wrote its
+  fresh state into the shared counter and erased a live session's parked overflow.
+- **The npm receipt is the boundary — and a `throw` lay behind it (#1088).** `publish()` threw
+  *after* a successful `npm publish`, during a 12-second registry-propagation poll: published,
+  not tagged, not pushed, reported as "failed, retryable". Propagation now returns a typed
+  outcome, each post-receipt step gets exactly one attempt, and everything else is collected as
+  `post-publish-reconciliation`. Leak detection decides on an extracted path rather than a regex
+  over `npm notice` prose (`contest` ≠ `tests`), and `ensureGithubRelease` became tri-state so
+  an auth or network answer no longer reads as "no release exists".
+- **`--silent` leaked into the children, and the gate discarded its own diagnosis (a4f93cf).**
+- **The empty sidecar path skipped the collision gate with exit 0 (#1083).** A coordinator that
+  wrote only the aggregate form of the two-shape scope declaration ran **six waves and ~27
+  dispatches with zero `FILE-SCOPE` injection** — and the absence looked identical to a clean
+  run. `scripts/materialize-wave-scope.mjs` is now the canonical writer of both shapes.
+- **The GitLab target comes from the explicit path (#1065).** `glab repo view --output json`
+  materialised a full project response to read one field; on 2026-08-17 that response carried a
+  runner registration credential into a tool transcript. Project identity is now
+  `(host, URL-encoded namespace/project)` with traversal and double-encoding rejection, and the
+  same minimisation reached the vault-backfill path.
+- **The restore froze after its first run (#state-md).** Also: a `gitleaks` allowlist that grew
+  by one proper name per incident now matches on a word boundary instead.
+- **Four count claims where the checker could only see two (#docs-parity).** `docs/components.md`
+  claimed 46 skills and 26 commands against 47 and 27 on disk. The drift checker reported two —
+  its patterns are `^##`-anchored — while a census of the same two surfaces in the same file
+  found four; the two inside the Mermaid diagram were already self-contradictory before the fix.
+
+### Notes
+
+`.claude/rules/host-resources.md` is new and always-on. `.claude/rules/bash-harness-pitfalls.md`
+gained no rule text this line, but two measurement traps were recorded against it in the
+learnings store: `rg -rn` is not `grep -rn` (`-r` is `--replace` and silently substitutes every
+match), and zsh does not word-split an unquoted variable, so a multi-path `git log -- $paths`
+reports zero matches with exit 0 — both produce a plausible wrong number without erroring.
+
 ## [3.21.0] - 2026-08-19
 
 Twenty-one commits (12 `fix`, 4 `feat`, 4 `docs`, 1 `chore`; 209 files, +28,906/−2,893), no

package/README.md

@@ -1,7 +1,7 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.21.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.23.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 [![Tests](https://img.shields.io/badge/tests-12%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
@@ -52,6 +52,8 @@ That is the whole loop. `/plan` and `/evolve` extend it (see [Lifecycle](#lifecy
 
 ## Quick Start
 
+Run `/bootstrap` in your project repo first — it writes `.orchestrator/bootstrap.lock`, which session-start requires before `/session` will run.
+
 Add a `## Session Config` section to your project's `CLAUDE.md` (Claude Code and Cursor IDE) or `AGENTS.md` (Codex CLI and Pi) — see [instruction-file-resolution](skills/_shared/instruction-file-resolution.md) for which file each platform reads. The smallest valid config is seven fields:
 
 ```yaml
@@ -70,8 +72,8 @@ Everything else is opt-in. See [`docs/session-config-template.md`](docs/session-
 
 ## What you get
 
-- **45 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, audits, and more
-- **24 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …)
+- **48 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, audits, and more
+- **28 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …)
 - **15 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …)
 - **10 hook event types** enforcing scope, blocking destructive commands, gating templates-first, capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged on the other platforms ([Platform support](#platform-support))
 - **10,000+ vitest tests** run on every commit ([telemetry methodology](docs/telemetry/telemetry-claims.md))
@@ -127,22 +129,23 @@ The system is markdown-driven config plus a thin Node runtime — skills, comman
 - **Five typed waves, not one big batch.** Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a *simplification pass* on AI-generated code **before** tests are written — otherwise tests pin the AI patterns into place.
 - **Inter-wave reviews, not just end-of-session.** Catching regressions between waves — not only at the end — stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.
 - **State persists across crashes.** `STATE.md` records wave progress and deviations; the next `/session` offers to resume from the last completed wave.
-- **Hooks enforce, not just warn.** A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike (specifics in [Safety](#safety)). This hard enforcement is full on Claude Code; it degrades to experimental / post-hoc / bridged on Codex CLI, Cursor IDE, and Pi (see [Platform support](#platform-support)).
+- **Hooks enforce, not just warn.** A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike (specifics in [Safety](#safety)). This hard enforcement is full on Claude Code; Cursor and Pi reach it through payload bridges; Codex is still pending a real `apply_patch` adapter (see [Platform support](#platform-support)).
 - **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.
 - **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.
 
-## Recent highlights (v3.21.0)
+## Recent highlights (v3.23.0)
 
-Every release is additive and backward-compatible. Highlights of the v3.21.0 line:
+Every release is additive and backward-compatible. Highlights of the v3.23.0 line: the first shaped by three external bug reports on the public mirror (Kanevry#64, #65, #66), all three reproduced, fixed and live-verified:
 
-- **The site that proves its own numbers (#1043–#1046)** — the live page had served v3.19.0 against v3.20.0 in the repo for six days, all five legal paths were 404, and the `Measured` block — the honesty argument of the whole page — carried five wrong numbers. It is now generated: `scripts/site-numbers.mjs` reads **13 metrics** from the repo into `data-metric` spans, and its very first run caught three real errors, one of them the coordinator's own (`skills: page says 47, repo says 46`) and one a contract defect that would have shipped `vv3.20.0` at the next release. Deploy config moved from a dashboard into a versioned `vercel.json`. Rendered height fell to **52.4%** of the old page (10,350 → 5,428px), and mobile navigation — previously `display:none` with no hamburger — exists.
-- **The documented Claude Code install path was guaranteed broken** — `claude plugin dir` is not a subcommand; it exits 1, the fallback path does not exist, `cd` fails, `npm install` never runs, and every hook afterwards cannot find `zx`. Measured on Claude Code 2.1.235. That is the cause behind external issues #62/#63, whose reporters described the symptom — and **all four issues opened by people outside this repo are install or environment failures, not one a feature request**. The replacement was extracted from the shipped HTML, entity-decoded and executed verbatim.
-- **The scope guard shipped the instructions for its own disarmament (#1057)** — the stale-manifest denial ended on ``remove it with `rm -f <path>` ``, and that string travels in `permissionDecisionReason` into the context of the agent just denied. `rm -f` is not blocked (14 rules, only `rm-rf-destructive` bites), and with the manifest gone both allowedPaths **and** project-root containment fall. A parallel session in the same working copy received this suggestion for the live manifest of this one, and declined on an indicator rather than on knowledge.
-- **Two dead instruments, found by measuring rather than reading** — the v2 vault renderer's branch condition was **structurally false from its first commit** and matched **0 of 253** session records; the obvious fix would have been worse than the bug, because `agents` is polymorphic (210× a number, 14× an array over 599 wave objects) and a naive `??` would have written `[object Object]` into the vault. And `scanBacklog` read 50 of 89 open issues while reporting the window nowhere: `critical 0, high 10, stale 0` where the truth was `1 / 18 / 5`.
-- **Cross-session messaging is wired (Epic #1048, waves 1–2)** — a new always-on rule with CSM-001..005, and a peer-inform branch hung **below** the sibling check in the PSA decision tree so it can mask neither that branch nor the PSA-002 pause. The moat was never "peer sessions cannot talk to each other" — they demonstrably can — it is that they share one working copy, and what crosses the channel is information, never isolation.
-- **Guards that were green without biting** — the owner-leakage scanner did not read `.html` at all; admitting the class immediately found a live `U+00AD` breaking a word visibly on a legally required page. `harness-audit` category 6 awarded **2/2** outside a git repository. Six consecutive CI pipelines were red because a test depended on untracked ledger files: locally 23/23, on CI `23 tests | 23 skipped`. Each is now closed by a mechanism, and the review panel found further holes inside the fixes themselves — including one fail-open state inside the fix that was closing fail-open.
+- **Codex CLI mints UUIDv7 session ids; every reader accepted only v4 (#66 / #1091)** — each SessionStart minted a fresh v4, so a resumed or compacted thread read its own lock as a foreign session. `parseSessionId` now accepts RFC 9562 versions 1–8 and the stop/end hooks apply the writer's rule, so one id owns the lock from start through release. The `UUID_V4_RE` alias is gone: zero importers, and a name that said v4 while matching v1–8.
+- **Every `/close` wrote 0 of 5 recommendation fields (#65 / #1036)** — the documented Phase 3.7a call passed `undefined` where a repo root is required, and the fail-open catch hid it on every run. The snippet binds the root; the catch now names the cause. A second defect found while verifying the fix: backticks in a comment inside a `node -e "…"` string made bash execute `undefined` on each close.
+- **Codex copies a marketplace plugin and starts the MCP child with no plugin-root variable (#64)** — measured: the copy lives under `~/.codex/plugins/cache/<marketplace>/session-orchestrator/<version>/`, and from a non-git cwd the launcher resolved to `/scripts/mcp-server.sh`. `.mcp.json` and `plugin-root.mjs` gained a cache-scan tier with a name-matched `package.json`, and `.mcp.json` now mirrors the module's tier order under two drift tests. Existing installs need a reinstall — Codex snapshots `.mcp.json` at install time.
+- **Worktree-Auto-Promotion is a process boundary, not a live migration (#1069, ADR-0013)** — the source session deregisters and releases its lock before the new worktree's session acquires (`leaveSourceRoot()`), which removes the phantom peer that stayed visible for up to 60 minutes. Because the new session's id never equals the worktree suffix, Phase 4a cleanup keys on a promotion marker written at creation time; the review panel found that key dead before any user did.
+- **The host registry contributed nothing to session numbering (#1066)** — the census projected only raw UUIDs, which the n-increment discards. It now counts `semantic_session_id`, so two sessions on one host cannot mint the same label. The semantic id stays a best-effort label; ownership remains the raw id plus owner proof.
+- **The mode selector scored a field no record carries (#1071)** — `completion_rate` sits under `effectiveness` in all 281 ledger records; the flat read was always `undefined`, so the high-completion bonus was unreachable and the fixtures pinned a shape production never writes. Fixed with a nested-first read and a divisor test for the 99 records that carry no rate at all.
+- **Semgrep regained two rules a path filter had dropped (#1129)** — re-aimed at this repo's real trust boundary (hook stdin, child-process stdout), taint-mode; the first true positives were three unguarded `JSON.parse` calls on `glab`/`gh` output in the CI banner. A proposed spread-sink was refused with a measurement: object spread cannot pollute a prototype.
 
-Previous line (v3.20.0): the memory pipeline — 233 sessions of learnings that reached no agent (#1014), agent-authored text neutralised at the render point (#1015), and a learning store made durable after 11 of 13 provenance pointers resolved to nothing (#1017).
+Previous line (v3.22.0): instruments that confidently measured the wrong quantity — the 99%-firing resource warning, the AUQ audit, and the lock-release identity split.
 
 Full version history: [CHANGELOG.md](CHANGELOG.md).
 
@@ -165,10 +168,10 @@ The design goal is engineering quality: every wave exits verified, every unfinis
 
 | Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
 |---|---|---|---|---|
-| All 24 commands | Native slash commands | Native plugin commands | Rules-based (.mdc) | Prompt templates |
+| All 28 commands | Native slash commands | Native plugin commands | Native `.cursor/commands` slash commands | Prompt templates |
 | Parallel agents | Agent tool | Multi-agent roles | Sequential only | Sequential (parallel planned) |
 | Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | `.pi/STATE.md` |
-| Scope enforcement | PreToolUse hooks | Unavailable — pending a real `apply_patch` adapter | `afterFileEdit` (post-hoc) | `tool_call` bridge |
+| Scope enforcement | PreToolUse hooks | Unavailable — pending a real `apply_patch` adapter | `preToolUse` + `beforeShellExecution` via cursor-hook-bridge; `afterFileEdit` post-hoc | `tool_call` bridge |
 | AskUserQuestion | Native tool | Numbered-list fallback | Numbered-list fallback | Numbered-list fallback |
 | Quality gates | Full | Full | Full | Full |
 

package/agents/AGENTS.md

@@ -73,7 +73,7 @@ tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (bo
 **Body conventions** (from Anthropic's `plugins/plugin-dev/agents/*` reference set):
 - Sections: `**Your Core Responsibilities:**` → `**[X] Process:**` → `**Quality Standards:**` → `**Output Format:**` → `**Edge Cases:**`.
 - Length: 500–3000 words is the recommended range. Below 500 reads as under-specified; above 3000 reads as bloated.
-- Read-only reviewer agents: tools `Read, Grep, Glob, Bash` (no Edit/Write). Implementer agents: `Read, Edit, Write, Glob, Grep, Bash`.
+- Read-only reviewer agents: tools `Read, Grep, Glob, Bash` (no Edit/Write). Implementer agents: `Read, Edit, Write, Glob, Grep, Bash`. Agents on the escalation allowlist append `SendMessage` to either baseline — see § Escalation Channel (#1051) for the six that do and why the rest do not.
 
 ## Model Selection & Cost Routing (#768)
 
@@ -95,6 +95,25 @@ Every agent definition with `repo-write` sandbox-tier (i.e. `Edit`/`Write` prese
 
 This is deliberately more explicit than a bare "Do NOT commit" — the git index and stash are SHARED resources across concurrently-dispatched sibling agents in the same wave, and `git stash`/`git add`/`git mv`/`git rm` are index-mutating even when scoped to the agent's own files. `docs-writer.md` had NO git-write restriction at all until #724 closed the gap (its `repo-write` siblings at least carried a bare "Do NOT commit" line) — when adding a new repo-write agent, copy the ban line verbatim rather than re-deriving a weaker phrasing so this gap does not recur. See `.claude/rules/parallel-sessions.md` § PSA-007 for the full rationale and fleet evidence.
 
+## Escalation Channel (#1051)
+
+Six agents opt into `SendMessage` so a wave-blocking obstacle can reach the coordinator **while the wave is still running**, instead of surfacing only in the final report after the wave has ended. The allowlist is exactly:
+
+`code-implementer` · `db-specialist` · `ui-developer` · `test-writer` · `docs-writer` · `session-reviewer`
+
+**The Nicht-Liste is deliberate, not an oversight.** `analyst`, `qa-strategist`, `architect-reviewer`, `security-reviewer`, `ux-evaluator`, `eval-judge`, `skill-applied-judge` and `dialectic-deriver` do NOT get the tool. Their output is a judgment over a whole corpus — a finding at minute three is provisional, and the analysis is complete only at the end. An early message from one of them would carry an unfinished verdict the coordinator cannot act on without re-reading the final report anyway, so the channel would add interrupts without adding information. The six above are different: each one can hit a state where its *task* becomes unfulfillable (the file it must edit does not exist, the migration target is missing, the diff under review is absent) — an obstacle, not a verdict.
+
+**The contract every escalation-enabled agent carries** (see `.claude/rules/cross-session-messaging.md` CSM-001/004/005):
+
+- **One message, upward only.** Exactly ONE `SendMessage` to `main` per obstacle. Never to a sibling agent — agents send upward, they cannot discover sideways.
+- **Never wait for a reply.** Silence is neither refusal nor consent (CSM-004); the agent keeps working in its scope or ends `blocked`.
+- **Degrade silently.** Where `SendMessage` is unavailable (disabled telemetry, non-Anthropic provider, native Windows — CSM-005), the obstacle goes in the final report instead. No code path may assume delivery happened.
+- **Payload:** agent role, declared file scope, the obstacle. The send is noted in the agent's own report so the operator can see the hand-off.
+
+**Mandate for new agents** — same shape as the git-write ban convention above: when adding a repo-write agent that belongs on this allowlist, copy the escalation block verbatim from `code-implementer.md` (adjusting only the role name) rather than re-deriving a weaker phrasing. A paraphrase that drops "never wait for a reply" or "upward only" re-opens exactly the failure modes CSM-004 and CSM-001 exist to close.
+
+`SendMessage` does NOT lift an agent out of `read-only`: it is in `READ_ONLY_TOOLS` (`scripts/lib/validate/tier-inference.mjs`, #1049), so `session-reviewer` keeps `sandbox-tier: read-only` and every `sandbox-tier` in this directory is unchanged by the opt-in.
+
 ## Color Allocation Strategy (#443)
 
 `color` is an **operator side-channel**, not a cosmetic field. In a `/tmux-layout` or multi-pane session, the per-agent color lets the operator tell co-running agents apart at a glance. With only a 9-color palette (`blue | cyan | green | yellow | purple | orange | pink | red | magenta`) and more than 9 agents in this directory, some colors are **deliberately shared** — but never carelessly.
@@ -124,12 +143,12 @@ Agents MAY declare their sandbox permission tier. Valid values:
 
 | Value | Meaning | Typical tools |
 |---|---|---|
-| `read-only` | observes only; no file writes, no network | `Read, Grep, Glob, Bash` |
-| `repo-write` | may create or modify files | `Read, Edit, Write, Glob, Grep, Bash` |
+| `read-only` | observes only; no file writes, no network | `Read, Grep, Glob, Bash` (+ `Skill`, `SendMessage`, `ListAgents`) |
+| `repo-write` | may create or modify files | `Read, Edit, Write, Glob, Grep, Bash` (+ `Skill`, `SendMessage`, `ListAgents`) |
 | `network-allowed` | may make outbound network calls (future) | — |
 | `dangerous` | may run destructive shell commands (future) | — |
 
-Inference rule (backward-compat): agents without `sandbox-tier:` infer their tier from tools — `Edit` or `Write` present → `repo-write`; only `Read/Grep/Glob/Bash/Skill` → `read-only`. The validator emits **WARN**, not FAIL, when the field is absent, so existing agents continue to work during migration. Bash appears in all tiers — fine-grained Bash control is handled by `hooks/pre-bash-destructive-guard.mjs`, not by tier.
+Inference rule (backward-compat): agents without `sandbox-tier:` infer their tier from tools — `Edit` or `Write` present → `repo-write`; only `Read/Grep/Glob/Bash/Skill/SendMessage/ListAgents` → `read-only`. `SendMessage` and `ListAgents` are pure agent↔coordinator communication surfaces with no filesystem write path, so they do not lift an agent out of `read-only` (`scripts/lib/validate/tier-inference.mjs` `READ_ONLY_TOOLS`, #1049) — that is what lets `session-reviewer` opt into the escalation channel while staying `read-only`. The validator emits **WARN**, not FAIL, when the field is absent, so existing agents continue to work during migration. Bash appears in all tiers — fine-grained Bash control is handled by `hooks/pre-bash-destructive-guard.mjs`, not by tier.
 
 Example:
 

package/agents/code-implementer.md

@@ -3,7 +3,7 @@ name: code-implementer
 description: 'Use this agent for feature implementation, API development, refactoring, and general code changes. Handles backend logic, API routes, service layers, and cross-cutting concerns. <example>Context: Wave plan assigns a new API endpoint implementation. user: "Implement CRUD API for invoices" assistant: "I''ll dispatch the code-implementer agent to build the invoice API endpoints." <commentary>Feature implementation with multiple files is the code-implementer''s core strength.</commentary></example> <example>Context: Refactoring task in an implementation wave. user: "Extract shared validation logic into a utility module" assistant: "I''ll use the code-implementer to extract and refactor the validation logic." <commentary>Cross-file refactoring requires systematic reading, extraction, and verification.</commentary></example>'
 model: inherit
 color: green
-tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
+tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
 output-schema: schemas/code-implementer.schema.json
 ---
@@ -37,6 +37,7 @@ You are a focused implementation agent. You write production code, refactor exis
 - Do NOT add standalone or narrative documentation (README, CLAUDE.md, guides), and never write docs for code that does not exist yet — those surfaces are owned by docs-writer. Inline code-surface docs ARE yours: comments where logic is non-obvious, plus JSDoc/TSDoc on public functions you author (per `.claude/rules/development.md` § Documentation).
 - Do NOT introduce new runtime dependencies without explicit instruction. If a new dependency seems necessary, pause and report rather than installing.
 - Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
+- **Escalation channel (#1051, opt-in):** If you hit a WAVE-BLOCKING obstacle — one that makes your task unfulfillable, not a question you could answer by reading more code — send exactly ONE `SendMessage` to `main` carrying your agent role (`code-implementer`), your declared file scope, and the obstacle. Then keep working in your scope or end with `Status: blocked`. NEVER wait for a reply (CSM-004); never message a sibling agent (CSM-001 — upward only). Where `SendMessage` is unavailable, report the obstacle in your final report instead (CSM-005). Note the send in Blockers / Notes.
 - Do NOT touch unrelated files in the same directory just because they share a folder.
 - Before creating a NEW file, grep for existing files with a similar basename/purpose (`git ls-files | grep -i <basename>`) — if one exists, prefer extending it over creating a "cousin" duplicate (#730.3).
 - Do NOT use destructive operations (`rm -rf`, `git reset --hard`, `git clean`). Stick to Edit/Write — the git-write ban above (PSA-007) already covers `git reset`/`git clean`'s VCS-specific forms.

package/agents/db-specialist.md

@@ -3,7 +3,7 @@ name: db-specialist
 description: 'Use this agent for database work — schema design, migrations, queries, indexes, and database functions. Handles SQL, ORMs, and database architecture decisions. <example>Context: New feature requires database schema changes. user: "Create the migration for the invoice tables with proper indexes" assistant: "I''ll dispatch the db-specialist agent to design the schema and create the migration." <commentary>Schema design requires understanding normalization, indexing, and the existing data model.</commentary></example> <example>Context: Performance issue with database queries. user: "Optimize the slow invoice listing query" assistant: "I''ll use the db-specialist to analyze and optimize the query with proper indexing." <commentary>Query optimization requires understanding execution plans, indexes, and data access patterns.</commentary></example>'
 model: inherit
 color: purple
-tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
+tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
 output-schema: schemas/db-specialist.schema.json
 ---
@@ -36,6 +36,7 @@ You are a focused database agent. You design schemas, write migrations, optimize
 - Do NOT modify application code — only database-related files (`migrations/`, `schema.sql`, `prisma/`, RPC function definitions).
 - Do NOT run `DROP TABLE`, `TRUNCATE`, or `DELETE` without explicit user instruction.
 - Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
+- **Escalation channel (#1051, opt-in):** If you hit a WAVE-BLOCKING obstacle — one that makes your task unfulfillable, not a question you could answer by reading more code — send exactly ONE `SendMessage` to `main` carrying your agent role (`db-specialist`), your declared file scope, and the obstacle. Then keep working in your scope or end with `Status: blocked`. NEVER wait for a reply (CSM-004); never message a sibling agent (CSM-001 — upward only). Where `SendMessage` is unavailable, report the obstacle in your final report instead (CSM-005). Note the send in Blockers / Notes.
 
 ## Quality Standards
 

package/agents/docs-writer.md

@@ -3,7 +3,7 @@ name: docs-writer
 description: 'Use this agent when documentation needs to be generated or updated as part of a session — user-facing READMEs, dev-focused CLAUDE.md sections, or vault narratives (context.md, decisions.md, people.md). <example>Context: a feature session added a new CLI flag. user: "Update the README with the new --no-vault flag." assistant: "I''ll dispatch the docs-writer agent to scan the diff and update README plus the Dev CLAUDE.md section if warranted." <commentary>Scope touches user-facing docs — docs-writer decides audience split and cites the diff.</commentary></example>'
 model: inherit
 color: cyan
-tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
+tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
 output-schema: schemas/docs-writer.schema.json
 ---
@@ -52,6 +52,8 @@ General rule: edit only files explicitly listed in the session scope passed at d
 
 Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
 
+**Escalation channel (#1051, opt-in):** If you hit a WAVE-BLOCKING obstacle — one that makes your task unfulfillable, not a question you could answer by reading more code — send exactly ONE `SendMessage` to `main` carrying your agent role (`docs-writer`), your declared file scope, and the obstacle. Then keep working in your scope or end with `Status: blocked`. NEVER wait for a reply (CSM-004); never message a sibling agent (CSM-001 — upward only). Where `SendMessage` is unavailable, report the obstacle in your final report instead (CSM-005). Note the send in Blockers / Notes.
+
 ## Output Format
 
 Report back in this shape:

package/agents/eval-judge.md

@@ -1,6 +1,6 @@
 ---
 name: eval-judge
-description: Use this agent during the /eval Skill Phase 3 (Epic #803, issue #810) to judge — from a session-eval record's dimension evidence, kpis, and session_id — the record's instruction-adherence and report-quality per rubric-v1.md's Judge Dimensions section. Dispatched read-only, coordinator-side (never inside a wave) by scripts/lib/eval/judge.mjs::runEvalJudge with a bounded per-call budget. RETURNS one fenced json block of two advisory judge dimensions (instruction-adherence, report-quality); the coordinator merges them via mergeJudgeDimensions() and appends the record via appendEvalRecord(). Read-only by contract — never writes files. Advisory-only and always uncalibrated — never blended into the deterministic tally or any global score. <example>Context: /eval Phase 3 with eval.judge: haiku. user "Judge whether this session-eval record shows instruction adherence and honest report quality." assistant "Dispatching eval-judge to read the record slice and emit advisory instruction-adherence/report-quality judgments." <commentary>The judge overlays a cheap advisory signal onto the five deterministic dimensions — never a global score, never a gate.</commentary></example>
+description: "Use this agent during the /eval Skill Phase 3 (Epic #803, issue #810) to judge — from a session-eval record's dimension evidence, kpis, and session_id — the record's instruction-adherence and report-quality per rubric-v1.md's Judge Dimensions section. Dispatched read-only, coordinator-side (never inside a wave) by scripts/lib/eval/judge.mjs::runEvalJudge with a bounded per-call budget. RETURNS one fenced json block of two advisory judge dimensions (instruction-adherence, report-quality); the coordinator merges them via mergeJudgeDimensions() and appends the record via appendEvalRecord(). Read-only by contract — never writes files. Advisory-only and always uncalibrated — never blended into the deterministic tally or any global score. <example>Context: /eval Phase 3 with eval.judge: haiku. user \"Judge whether this session-eval record shows instruction adherence and honest report quality.\" assistant \"Dispatching eval-judge to read the record slice and emit advisory instruction-adherence/report-quality judgments.\" <commentary>The judge overlays a cheap advisory signal onto the five deterministic dimensions — never a global score, never a gate.</commentary></example>"
 model: haiku
 color: cyan
 tools: Read, Grep, Glob

package/agents/memory-proposal-collector.md

@@ -135,8 +135,8 @@ and `{{options}}` at render time.
 ```
 AskUserQuestion({
   questions: [{
-    header: "Memory — Confirm Proposals (Batch {{N}} of {{M}})",
-    question: "Select the learnings you want to store permanently. Unselected proposals will be archived as declined.",
+    header: "Memory",
+    question: "Batch {{N}} of {{M}} — which learnings should be stored permanently? Unselected ones are archived as declined.",
     options: [
       // one entry per proposal in this batch — see label format below
       { label: "{{label}}", description: "{{description}}" },
@@ -147,12 +147,14 @@ AskUserQuestion({
 })
 ```
 
-**When there is only one batch** (`M === 1`), omit the batch suffix:
+**When there is only one batch** (`M === 1`), omit the batch prefix from the question:
 
 ```
-header: "Memory — Confirm Proposals"
+question: "Which learnings should be stored permanently? Unselected ones are archived as declined."
 ```
 
+`header` stays `"Memory"` in both cases: the field is cut off after 12 characters, so anything longer never reaches the operator.
+
 ### Option label format
 
 Locked by D3 (Wave 1 decision):

package/agents/session-reviewer.md

@@ -3,7 +3,7 @@ name: session-reviewer
 description: 'Use this agent between waves or at session end to verify work quality against the session plan. Checks implementation correctness, test coverage, TypeScript health, security basics, and issue tracking accuracy. <example>Context: Impl-Core wave is complete, coordinator needs quality check before Impl-Polish. user: "Impl-Core wave done, review before continuing" assistant: "I''ll dispatch the session-reviewer to verify Impl-Core outputs." <commentary>Inter-wave quality gate ensures issues are caught early, not at session end.</commentary></example> <example>Context: Session end, verifying all work before committing. user: "/close" assistant: "Running session-reviewer to verify all session work before committing." <commentary>Final quality gate before any code is committed.</commentary></example>'
 model: inherit
 color: pink
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, SendMessage
 sandbox-tier: read-only
 output-schema: schemas/session-reviewer.schema.json
 ---
@@ -164,6 +164,12 @@ The same standard binds your own conduct: a defect in your OWN review process
 
 Evidence for both halves (2026-08-14 quality panel, 18 findings / 2 HIGH): each of the three reviewers refuted at least one coordinator claim. The architect's 10-entry CONFIRMED list and the QA strategist's 12-entry REFUTED list produced no findings at all, yet two REFUTED entries closed gaps the coordinator had explicitly suspected — re-work the next wave would otherwise have repeated. The security reviewer reproduced a HIGH that no test and no gate had surfaced (self-review and a green gate are not review), and disclosed a defect in his own probe with its full cleanup. A fix-agent refused a coordinator-specified `needleCount > 0` coupling by showing it would disable the fix in the zero-needle run — i.e. in exactly the leaking run.
 
+### Escalation channel (#1051, opt-in)
+
+If you hit a WAVE-BLOCKING obstacle — one that makes the review itself unfulfillable (the diff you were pointed at does not exist, the gate cannot run at all), not a defect you could report as a finding — send exactly ONE `SendMessage` to `main` carrying your agent role (`session-reviewer`), your declared review scope, and the obstacle. Then finish whatever review remains possible and report as usual. NEVER wait for a reply (CSM-004); never message a sibling agent (CSM-001 — upward only). Where `SendMessage` is unavailable, report the obstacle in your final report instead (CSM-005). Note the send in your report.
+
+A HIGH finding is not an escalation — findings travel in the findings list, and `stop-and-escalate` (RCR-007) is a classification you report, not a message you send. This channel exists only for the obstacle that stops the review from happening.
+
 ## Output Format
 
 ```

package/agents/test-writer.md

@@ -3,7 +3,7 @@ name: test-writer
 description: 'Use this agent to close NAMED test gaps and to consolidate redundant tests. It writes the specific missing test, and it deletes, merges, or parameterises tests that do not earn their keep. <example>Context: Quality wave named one concrete gap — the invoice service never exercises the declined-payment branch. user: "The invoice service has no test for a declined payment" assistant: "I''ll dispatch the test-writer to add that one error-path test and run the falsification check on it." <commentary>A named gap states a bug that would ship undetected; ''improve coverage'' names nothing and is not a dispatchable task.</commentary></example> <example>Context: The auth test file has 14 tests — 6 assert the same validation branch and 3 only pin prose strings. user: "Clean up the auth test file" assistant: "I''ll use the test-writer to merge the 6 duplicates into one parameterised test and delete the 3 prose-pinning tests — net test count falls 14 to 6 while catch-power rises, reported as test_delta.removed plus test_delta.consolidated." <commentary>Consolidation is a success outcome: fewer tests that each catch a distinct bug beat many that catch none, and a scope with no real gap legitimately ends with status no-tests-needed.</commentary></example>'
 model: inherit
 color: orange
-tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
+tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
 output-schema: schemas/test-writer.schema.json
 ---
@@ -40,6 +40,7 @@ You are a focused testing agent. You write tests — unit, integration, and edge
 - Do NOT write trivial tests. `expect(typeof add).toBe('function')` does not test behavior.
 - Do NOT add test utilities unless the same pattern appears 3+ times. Premature abstraction in tests obscures what's being tested.
 - Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
+- **Escalation channel (#1051, opt-in):** If you hit a WAVE-BLOCKING obstacle — one that makes your task unfulfillable, not a question you could answer by reading more code — send exactly ONE `SendMessage` to `main` carrying your agent role (`test-writer`), your declared file scope, and the obstacle. Then keep working in your scope or end with `Status: blocked`. NEVER wait for a reply (CSM-004); never message a sibling agent (CSM-001 — upward only). Where `SendMessage` is unavailable, report the obstacle in your final report instead (CSM-005). Note the send in Blockers / Notes.
 - Do NOT use computed values in assertions. Always use hardcoded literals.
 - Do NOT skip error paths. Every function with failure modes needs at least one error/edge case test alongside the happy path.
 - **Falsification check (mandatory)**: Before finishing, verify each test would FAIL if the core logic were removed. If it wouldn't, the test is worthless.

package/agents/ui-developer.md

@@ -3,7 +3,7 @@ name: ui-developer
 description: 'Use this agent for frontend implementation — UI components, pages, styling, accessibility, and responsive design. Handles React/Next.js components, CSS, and design system work. <example>Context: Implementation wave includes UI component work. user: "Build the invoice list page with filters and pagination" assistant: "I''ll dispatch the ui-developer agent to implement the invoice list UI." <commentary>Frontend page implementation with interactive components is the ui-developer''s specialty.</commentary></example> <example>Context: Accessibility improvements needed. user: "Fix WCAG violations in the dashboard components" assistant: "I''ll use the ui-developer to audit and fix the accessibility issues." <commentary>WCAG compliance requires understanding semantic HTML, ARIA attributes, and keyboard navigation.</commentary></example>'
 model: inherit
 color: magenta
-tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
+tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
 output-schema: schemas/ui-developer.schema.json
 ---
@@ -36,6 +36,7 @@ You are a focused frontend implementation agent. You build UI components, pages,
 - Do NOT write backend logic — server actions, API routes, DB queries are out of scope. Use client-only patterns + existing data-fetching layers (React Query, SWR, server components).
 - Do NOT use `dangerouslySetInnerHTML` without DOMPurify sanitization (XSS risk).
 - Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
+- **Escalation channel (#1051, opt-in):** If you hit a WAVE-BLOCKING obstacle — one that makes your task unfulfillable, not a question you could answer by reading more code — send exactly ONE `SendMessage` to `main` carrying your agent role (`ui-developer`), your declared file scope, and the obstacle. Then keep working in your scope or end with `Status: blocked`. NEVER wait for a reply (CSM-004); never message a sibling agent (CSM-001 — upward only). Where `SendMessage` is unavailable, report the obstacle in your final report instead (CSM-005). Note the send in Blockers / Notes.
 
 ## Quality Standards