session-orchestrator 3.22.0 → 3.24.0

package/CHANGELOG.md

@@ -7,6 +7,452 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.24.0] - 2026-09-02
+
+Five commits since v3.23.0 (4 `feat`, 1 `docs`; 152 files, +14,596/−942), no
+`BREAKING CHANGE:` footer and no `!` subject.
+
+One `docs` commit (`c3ab4801`) adds ADR-0013, naming the ownership-check-before-deregister
+ordering that closed Wave 4 of the previous session. One `feat` commit (`a019d5a4`, deep
+session, 5 waves, 37 agents + 3 reviewers + 3 panel) closes the GH#67 peer-filter class
+across every affected site, plus #1170, #1176, #1177, #1166, #1167, #1174, #1180 and #1175.
+One `feat` commit (`936dae8a`) closes a Fleet-Mining v2 instrument audit across 18 repos
+(1,587 learnings, 144k events, 347 telemetry records) with five repairs to the fleet's own
+measurement instruments (#1189, #1190, #1191, #1192, #1193).
+
+Two further `feat` commits (`2ccea0f2`, `3b352d78`) are Waves 2 and 3 of a new session (11
+agents each; Opus for guards/identity/protocol, Sonnet for consolidation/polish). The
+through-line: identity and scope boundaries are now drawn at the PROCESS, not the working
+copy — a peer session's manifest in the same checkout is `foreign`, a dispatched subagent's
+raw session id belongs to its coordinator, and four duplicated helper implementations
+collapse to one canonical each.
+
+### Added
+
+- **`orchestrator.reconcile.completed` (#1192).** Wrapper around `runReconcile` covering all
+  three return paths (empty corpus, normal, engine-error) with `trigger`
+  (`skill|session-end|phase-skip|unknown`), `targets` (allowlisted `repo-local|baseline`),
+  counters including measured zeros, `duration_ms`, and `aborted`+`reason` on the catch path.
+  Skipped with a stderr WARN when no `repoRoot` is passed, so test runs never write the fleet
+  ledger. First live record: `eligible 102 / proposals 10 / rejected 154 / capped 72 /
+  already_materialized 20`.
+- **`docs/audits/2026-09-02-fleet-instruments.md`** — the public scrubbed extract of the
+  Fleet-Mining v2 instrument audit: 18 repos, 1,587 learnings, 143,967 events, 347 telemetry
+  records (6 `anon_id`), 13 instrument verdicts and 12 orchestrator candidates (K1–K12).
+- **A new blocking validator catches dead script paths cited in skill/command/agent prose
+  (#1176).** `scripts/lib/validate/check-skill-script-paths.mjs` scans `skills/`, `commands/`
+  and `agents/` for `scripts/**.mjs` citations that neither exist nor carry a same-line/
+  line-above `<!-- path-check: planned #<iid> | historical | example -->` marker; fenced code
+  blocks are skipped as illustrative shape, not a claim. Measured 2026-09-02 @ `c3ab480`: 237
+  distinct citations, 7 dead, 4 of the 7 inside fences.
+- **`events.jsonl` records are now schema-versioned and validated before they are written
+  (#1177).** `emitEvent()` stamps every record `schema_version: 1` (never overwriting a
+  caller-supplied value) and runs `validateEventRecord()` BEFORE the append and BEFORE any
+  webhook POST — an invalid record throws `EventValidationError` and produces neither.
+  `scripts/emit-event.mjs` maps that to exit `1` (I/O failures keep exit `2`);
+  `scripts/lib/tmux-layout/telemetry.mjs` stamps + validates synchronously and drops invalid
+  lines. The read path stays lenient — the 33k+ pre-#1177 records without the field remain
+  valid.
+- **A canonical reader collapses `sessions.jsonl`'s append-only duplication (#1167).**
+  `scripts/lib/sessions-canonical.mjs` applies newest-wins per `session_id`, drops any record a
+  later `supersedes` pointer refutes, and narrowly collapses the systemic double-stub class
+  (two `abandoned` records sharing an exact `started_at`/`completed_at` pair, one synthetic).
+  The startup/CLI backfill path (`scripts/backfill-abandoned-sessions.mjs`) now also emits
+  `orchestrator.session.backfill_completed` per record — previously only the SessionEnd hook
+  did — and stamps `raw_session_id`; `hooks/on-session-end.mjs`'s backfill gained a second
+  UUID→semantic bridge via the `session.ended` event for sessions that lost the
+  lock-acquire race.
+- **A vault-scoped lock protects the shared live-status board's read-modify-write (#1180).**
+  `scripts/lib/vault-status/board-lock.mjs` wraps `sweepBoard()`'s merge in a cross-repo mutex
+  (mtime-based staleness — the vault dir can be synced cross-host, so a recorded pid isn't
+  probeable); fail-open on acquire timeout or fs-error (one stderr WARN, then runs unlocked)
+  since a board update is best-effort telemetry. `.gitignore` gained `state.lock` and
+  `rules.lock`.
+- **A GitLab Project Access Token recipe for the schema-drift CI job (#1175).**
+  `docs/ci-setup.md` documents Option A (Project Access Token, recommended) and Option B
+  (personal PAT) for `SCHEMA_DRIFT_TOKEN`. Activation is blocked on the documented
+  vendor-ahead drift tracked in #531: the token is provisioned but the CI/CD variable is not
+  yet set upstream.
+- **A `remote-hosts:` config block routes wave work to another machine over SSH (#1160).**
+  `scripts/lib/config/remote-hosts.mjs` adds the block (opt-in template + reference doc) and
+  an `ssh:<alias>` channel in `agent-mapping`; the wave-resource gate adds an `offload`
+  decision AFTER the HR-004 heavy-repo cap, gated on an injected readiness witness
+  (`remoteReady` map or async `probeFn`) — the gate never probes the network itself, so with
+  no witness the decision stays local. `dispatchRemote()`/`remoteDoctor()`/
+  `remoteReadyProbe()` wrap the host-side `offload` CLI (prompt travels on stdin, never argv;
+  exit codes 1–8 mapped to typed refusal reasons; an empty returned patch counts as failure,
+  not success). Emits `orchestrator.remote_dispatch.completed` on every attempt AND every
+  refusal (`ok:false`, `exit_code: null`) — the payload carries the configured alias, never a
+  hostname or IP. `skills/remote-offload/SKILL.md` documents the channel generically for any
+  consuming repo (skill count measured 48 → 49); wave-3 added the fourth wave-executor
+  dispatch branch (`ssh:<alias>` via `dispatchRemote()`) to `wave-loop.md` alongside the
+  existing three.
+- **A Peer-Scope-Union protocol lets two coordinator sessions in the same working copy share
+  scope without racing (#1195).** `skills/_shared/parallel-aware-auq.md` documents the
+  four-step handshake plus a message template; `skills/wave-executor/wave-loop.md` §
+  Scope Manifest 3.1a adds a `peer-session-<id>` record (rolled over each wave, cleared at
+  session-end) that is included in the disjoint check but excluded from the coordinator's own
+  file-scope union; a new branch in the `parallel-sessions.md` decision tree routes to it; and
+  `hooks/post-bash-write-verify.mjs` now partitions a peer's writes from genuine scope
+  violations instead of flagging both alike.
+- **Session-start now writes its own identity before anything can read it wrong (#1199).**
+  Phase 1.05 adds a self-report block (`session_id: null` before Phase 1.2 resolves it) so
+  downstream consumers see an explicit unresolved state instead of inferring one.
+- **`/evolve` and the auto-dialectic nudge now emit their own completion events (#1200).**
+  `orchestrator.evolve.completed` and `dialectic.completed` are emitted via `emit-event.mjs`
+  from inside the skill; `decideAndRecordAutoDialectic()` emits `dialectic.nudge_decided`
+  mechanically rather than leaving the decision only in skill prose, consumed by
+  `phase-3-6-tail.md`.
+
+### Changed
+
+- **BREAKING (behavior): `discovery-validator.enabled` defaults to `false` again (#1191).**
+  Reverts the #690 flip of 2026-06-25. Fleet measurement (2026-09-02, 18 repos): 6,946
+  `discovery_validator_violation` events had accumulated in repos that never declared the
+  block, and a scope-adjusted n=60 sample put real precision at 0/60 — the hook was scanning
+  the MAIN transcript on `SubagentStop`, not the subagent's own. It now reads the subagent
+  transcript (`agent_transcript_path` when the harness sends it, else
+  `<dir>/<base>/subagents/agent-<agent_id>.jsonl` — no fallback to the main transcript), and
+  the violation event now carries `agent_id`. Repos that relied on the silent default lose the
+  signal until they set `enabled: true` explicitly.
+- **Scope enforcement now treats every identity as process-local, including your own
+  (#1194).** `enforce-scope.mjs` reads session ids via a new `readProcessLocalSessionIds()`
+  instead of `readOwnSessionIds()` — a peer's manifest sitting in the SAME working copy now
+  classifies as `foreign`, not `own`. Two existing tests had asserted the inverted behaviour
+  and were rewritten with a named ceiling (a harness with no session id, e.g. bare
+  Codex/Cursor, resolves to `unknown` → enforce, never skip); `scope-collision-guard.md` and
+  `state-ownership.md` were updated to match.
+- **`memory.propose`'s lock check is now a raw→semantic lookup, not a trust boundary
+  (#1188).** The lock is consulted only to translate the caller's raw id into its semantic
+  session id, authorised by a process-local match against the RAW id — measured: a dispatched
+  subagent carries the COORDINATOR's raw UUID in `CLAUDE_CODE_SESSION_ID`, never its own.
+  `sessions-canonical.mjs` and the backfill path now distinguish silent `ENOENT` from loud
+  `EACCES`/`EISDIR` in two separate ledger readers instead of treating every read failure the
+  same.
+- **Four duplicated helper implementations collapse to one each.**
+  `scripts/lib/validate/markdown-fences.mjs` (#1181) replaces 4 line-start-only fence
+  scanners with one line-start-AND-end-anchored automaton shared by all 4 callers
+  (`validate-plugin` output byte-identical before/after, 203/0). `expandTilde` (#1182)
+  replaces 8 copies of home-directory expansion with the existing `common.mjs`
+  implementation — one of the deleted copies (`gitlab-portfolio/cli.mjs`) mis-expanded
+  `~user` (a different user's home, not the caller's). `hooks/_lib/subagent-paths.mjs`
+  (#1196) replaces 4 divergent sidecar-path derivations with one carrying the strictest rules
+  from any of them (agent-id length `{1,64}`, `'unknown'` rejected,
+  `agent_transcript_path` confined inside the transcript directory).
+  `hooks/_lib/atomic-json.mjs` (#1197) replaces 4 byte-identical copies with one whose
+  read-modify-write default only replaces a genuinely MISSING file (`ENOENT`) — an
+  unparsable or unreadable file is no longer silently overwritten with the default.
+- **A block-header matcher gained an indent+inline-value form, additively (#1185).**
+  `matchBlockHeaderDetailed` is now shared so `health-endpoints.mjs` no longer maintains its
+  own `HEADER_RE`.
+- **Five readers now go through the canonical `sessions.jsonl` collapse instead of counting
+  raw lines (#1186).** `telemetry/sync.mjs` and `build-live-signals.mjs` (wave 2), plus
+  `site-numbers.mjs` and `vault-mirror.mjs --kind session` (wave 3), now read
+  newest-per-`session_id`; on this repo the session count measured 289 lines → 278 sessions
+  (11 duplicate lines collapsed). Two tests pinning the old raw-line count were removed as no
+  longer testing real behaviour.
+- **Wave-completion refusals are now named events, not silent skips (#1201).**
+  `KNOWN_TRIGGERS` plus three explicit wrapper functions (`runReconcileFromSkill`/
+  `AtSessionEnd`/`FromPhaseSkip`) replace an implicit trigger string — an unrecognised
+  trigger now throws instead of silently defaulting. `emitFinalWaveCompleted` emits
+  `orchestrator.wave.final_refused` for all six refusal paths instead of leaving them
+  unrecorded — closing the same class of instrument gap named in
+  `.claude/rules/host-resources.md` § HR-105.
+
+### Fixed
+
+- **`orchestrator.agent.stopped` carried `agent: ""` in 86.7% of fleet records (#1190).**
+  89,991 of 103,763 historical records carried an empty `agent` because
+  `input?.agent_type ?? 'unknown'` never fires on an empty string — the harness's actual
+  shape. `agent` is now omitted when empty (never `'unknown'`, never a fabricated `0`/`false`).
+  Seven optional sidecar-derived fields were added — `agent_id`, `transcript_found`,
+  `tool_use_id`, `agent_type_meta`, `duration_ms` + `duration_source` (`meta-birthtime`), and
+  `status` (`done|partial|blocked|failed|no-tests-needed`, from the last line-anchored
+  `STATUS:` marker in the final 64 KiB of the agent transcript) — each independently omitted
+  when unmeasured, each wrapped in its own try/catch, with a charset guard on `agent_id`
+  before path interpolation. `CURRENT_SCHEMA_VERSION` is unchanged (additive). Measured
+  `status` coverage: 61.7% (71 done / 3 partial / 46 absent) over 120 completed sidecars.
+- **`commands[]` was empty in every usage ping (#1189).** `classifyInvocationName` routes
+  plugin-prefixed command names (`session-orchestrator:session`) into `commands[]` under the
+  bare name — the prefix is required, so a bare foreign name never becomes one of our
+  commands — and `.command`-field names are prefixed before classification, since that field
+  is itself the "this is one of ours" provenance signal a bare `.skill` arrival lacks.
+- **The final `orchestrator.wave.completed` of every session was never emitted (#1193).**
+  Fleet-wide: 1,018 `started` vs. 722 `completed`, a gap of exactly 296 — one per wave run.
+  `hooks/on-session-end.mjs` now emits it at SessionEnd, idempotent via a
+  `last_wave_completed` high-water mark written monotonically by both emitters, gated on
+  ownership of `current-session.json` via the RAW stdin session id (not the resolved one), and
+  skipped on `reason: clear`. `hooks/post-tool-batch-wave-signal.mjs` gained the same
+  raw-stdin-id ownership check, so it can no longer write wave keys into a peer session's
+  record either.
+- **`orchestrator.session.stopped.duration_ms` was a literal `0` in 8,127 of 8,127 fleet
+  records.** The harness never sends `start_ms`, so the old expression fell back to a
+  fabricated zero — indistinguishable from a real instant turn. It is now derived from an
+  OWNED `.orchestrator/session.lock` (`duration_source: 'session-lock'`, session-elapsed
+  measured at turn end) or omitted entirely, never `0`.
+- **`resolveSession()`'s ownership predicate was self-fulfilling** when the stdin `session_id`
+  was absent or non-UUID: it fell back to the recorded id and then compared the fallback
+  against itself. Fixed at the root (`rawStdinId !== null && rawStdinId === recordedId`) in
+  `hooks/on-session-end.mjs` for `duration_ms`, `semantic_session_id` and the new wave-completed
+  emit, plus the sibling site `resolveSessionId()` in `hooks/on-stop.mjs`.
+- **A live local `session.lock` no longer hides a same-working-copy registry peer (GH#67).**
+  Registry-sourced entries in `scripts/lib/session-discovery.mjs` / `peer-discovery.mjs` now
+  carry additive `registryOnly` / `lockSuperseded` / `lockOwnerId` annotations instead of
+  being filtered out — `lockSuperseded: true` is a HINT (the lock is advisory, so the entry
+  may still be a live session that lost the acquire race), never a verdict. Only
+  PROMOTION_OFFER decisions downgrade such a peer to advisory; peer-count and display
+  consumers keep it. Lock-sourced sessions carry none of the three fields, so their shape
+  stays byte-identical to pre-GH#67.
+- **Worktree-promotion teardown is now mechanical, not skill prose (#1170).**
+  `enterWorktree()` takes an optional `rawSessionId`; when given, it calls `leaveSourceRoot()`
+  on the OLD root after the destination provably exists and records the outcome on
+  `result.left`. Before #1170, four promotion call sites relied on coordinator prose to
+  release the source root — measured zero `deregisterSelf`/`release(` call sites across the
+  affected skill docs, so the abandoned registry entry advertised a phantom peer for up to an
+  hour.
+- **`memory.propose` filed wave-N+1 proposals into the wave-N quota bucket (#1166).**
+  `scripts/memory-propose.mjs` now resolves the RUNNING wave from `<state-dir>/wave-scope.json`
+  first (when present and unbound or bound to this session), falling back to `STATE.md
+  current-wave + 1` only when no usable manifest exists — `current-wave` itself always
+  records the JUST-COMPLETED wave.
+- **`health-endpoints` silently dropped the wizard's own nested-block output (#1174).** The
+  key was read off the flat KV map via `_coerceList`, which bails to `null` on any `{` and
+  cannot see a nested YAML block at all. `scripts/lib/config/health-endpoints.mjs` now parses
+  it content-scoped, accepting inline object arrays, the nested block form (top-level or
+  under `ecosystem-health:`), and a bare URL list; `ecosystem-health`'s own valueless
+  block-header form is now read as a fallback when the scalar key is absent.
+- **`emitEvent()`'s automatic session/semantic-session fill now requires a process-local
+  witness (#1177).** `CLAUDE_CODE_SESSION_ID` (or the hook-input session id) must exactly
+  equal the lock's raw `session_id` before `session_id`/`semantic_session_id` are
+  auto-filled — STATE.md is never treated as a witness. `wave` is filled the same way, only
+  from a `wave-scope.json` manifest bound to this same session, and is coerced to an integer.
+  See `docs/events-schema.md` § Correlation keys.
+- **The memory banner's "sessions ever" stat now counts distinct sessions, not JSONL lines
+  (#1167).** `sessions.jsonl` is append-only, so one physical session can occupy two lines;
+  on this repo the stat drops from 286 lines to 275 sessions. Five readers now go through
+  the canonical collapse: cold-start detection, the memory banner, harness-audit Category 1,
+  evolve's autopilot-effectiveness/verdict, and autopilot's id-set guard.
+- **`check-skill-script-paths` no longer goes blind past an unbalanced code fence (#1176).**
+  An unclosed/unbalanced fence now reports as its own `unbalanced-fence` finding instead of
+  silently absorbing the rest of the file as "inside a fence"; a fence opened inside a
+  blockquote is now recognised as a fence too.
+- **`sessions-canonical.mjs`'s `supersedes` collapse now requires an attestable join key
+  (#1167).** A `supersedes` pointer on an abandoned record is honoured only when it can be
+  matched to the record it claims to supersede; rule ordering was fixed so a superseded
+  record's synthetic double-stub twin is collapsed too. A new `keepUnidentified` option lets
+  callers retain records the canonicalizer could not confidently classify instead of
+  dropping them.
+- **`memory.propose` no longer trusts an unbound `wave-scope.json` (#1177).** A manifest
+  without a `semantic_session` binding is a peer's or a stale artefact, not this session's
+  own — it is now ignored with a stderr note instead of adopted; an unreadable/malformed
+  manifest also WARNs on stderr before falling back to `current-wave + 1`, rather than
+  failing silently.
+- **The vault-status board lock's stale-override is now surfaced, not silent (#1180).**
+  `onLockOutcome` reports a `staleOverride` reason when the lock was force-acquired past a
+  stale holder, and `sweepBoard()`'s board event now records it too — distinguishing "the
+  mutex worked as designed" from "a slow host looked like a crash".
+- **`check-hooks-emit-event-guard` and `check-validator-registration` both went live in
+  `validate-plugin` (#1183, #1184).** `check-hooks-emit-event-guard.mjs` (#1183) parses hooks
+  via `@babel/parser` (AST, not regex) to catch a hook that mutates state without emitting a
+  corresponding event; 5 pre-existing sites are grandfathered into an explicit WARN baseline
+  with a reason and stale-detection instead of silently passing. `check-validator-registration.mjs`
+  (#1184) confirms every validator module is actually wired into `validate-plugin.mjs`
+  (measured 33 of 33 wired, using comment-stripped source so a commented-out registration
+  doesn't count as live).
+- **`check-skill-script-paths`'s new `--strict-sh` mode found its own premise refuted
+  (#1187).** Extending the dead-path scan to shell-script citations, only 1 of 27 `.sh`
+  references sits inside the tool's own scan directories (`skills/`, `commands/`, `agents/`)
+  — the other 26 are in `docs/`, alongside 7 dead `.mjs` citations inside `docs/adr/` the same
+  run surfaced. Shipped as a WARN-only opt-in flag; the `docs/` sweep is a follow-up.
+- **The discovery-validator's dedupe key, gate-summary skip, and masking order all landed
+  together (#1198).** A dedupe key (`session_id`, `agent_id`, `sha256(claim)`) collapses
+  repeated flags of the identical claim; gate-summary recap lines (the coordinator's own
+  restatement of a subagent's findings, not a fresh claim) are now skipped entirely; claim
+  masking now runs before every pattern is checked, not a subset. Measured against the
+  flagged corpus: 186 of 400 flagged claims were false positives. Two claims from this
+  session's own discovery briefing were checked against the fix and refuted.
+- **A pre-push scratch-vs-publish check now reads the two arguments git already passes it.**
+  `.husky/pre-push` had never read `$1` (remote name/URL) or `$2` (remote URL) — confirmed by
+  `rg -n '\$1|\$2' .husky/pre-push` finding only a local function's own arguments — so every
+  push ran the full quality gate regardless of destination. It now skips the gate for a raw,
+  unconfigured scratch URL (e.g. the remote-offload sync target) while continuing to gate
+  real publish remotes; a named ceiling covers a real but unlisted third publish host, which
+  still reads as scratch.
+- **`check-untracked-test-deps` misclassified `.git` as an untracked file inside a linked
+  worktree.** In a normal checkout `.git` is a directory and was already excluded; in a
+  `git worktree add` checkout `.git` is a FILE containing `gitdir: <path>`, which satisfied
+  the same `isFile()` check the untracked-candidate branch uses. `.git` is now explicitly
+  exempted regardless of which shape it takes — measured 62 of 62 tests passing across the 5
+  affected test files inside a linked worktree checkout.
+
+## [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

package/README.md

@@ -1,9 +1,9 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.22.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.24.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)
+[![Tests](https://img.shields.io/badge/tests-15%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
 Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on **Claude Code, Codex CLI, Cursor, and [Pi](docs/pi-setup.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,11 +72,11 @@ 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`, …)
+- **49 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))
+- **15,000+ vitest tests** run on every commit ([telemetry methodology](docs/telemetry/telemetry-claims.md))
 
 Full component inventory: [`docs/components.md`](docs/components.md).
 
@@ -127,22 +129,25 @@ 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.22.0)
+## Recent highlights (v3.24.0)
 
-Every release is additive and backward-compatible. Highlights of the v3.22.0 line:
+Every release is additive and backward-compatible. Highlights of the v3.24.0 line: parallel-session identity moves from repo-scoped to process-local, remote work gets a declared host channel, and four duplicated-copy classes collapse to one module each:
 
-- **The warning that fired on 99.0% of all session starts (#1089)** — measured over **1,477 session-start events across 18 repos**, against 4,884 stop events with zero OOM markers. Three independent measurement errors, not one threshold among them: `os.freemem()` on Darwin reports only `Pages free` (median **0.4 GB** on hosts with 24–128 GB installed), a threshold named for *sessions* was compared against a *process* count (measured ratio **6.0:1** — same number, right denominator: 93.6% → **4.2%**), and one noisy axis could cap a wave alone. The verdict had reached the ledger 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**. A warning that fires on almost everything changes nothing except how fast you learn to ignore it.
-- **The questions this tool asks its operator had never been measured (#1107)** — `scripts/auq-audit.mjs` now scores every choice block against eight criteria and two hard hurdles, all thresholds from one registry. The census found **three populations where every prior count had seen one**: 40 Claude Code blocks, 10 Codex prose lists, and 17 nobody had counted. Baseline **21 of 72 (29%)**, after the pass **72 of 72**. The dominant cause was structural rather than editorial — `header` caps at 12 codepoints and truncates silently, **26 of 42 exceeded it**, and one NFD-composed header measured 12 visible characters as 14 and destroyed its own question.
-- **A probe that sized the wrong set and never asked git** — `checkStaleArtifacts` announced "37 files (11 MB)" while computing the megabytes over the entire directory instead of the 37 it names; they weigh **0.68 MB**, a factor of ~18. Separately it proposed pruning seven **tracked, runtime-read** source files, including the policy file a hook reads on every Bash call. 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, the lock, and issue-budget each held a different one) and `findPeers` reported the session's own presence as a foreign peer. The companion issue-budget fix removed a data-loss path where an identity-less invocation 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 publish during a 12-second propagation poll: published, not tagged, not pushed, reported as "failed, retryable". Each post-receipt step now gets exactly one attempt and the rest is collected as reconciliation. Leak detection decides on an extracted path, not a regex over `npm notice` prose — `contest` is not `tests`.
-- **Six waves ran with zero scope injection, and it looked exactly like a clean run (#1083)** — the scope declaration has two shapes; a coordinator that writes only the aggregate one degrades the chain to signal-free ALLOW. `scripts/materialize-wave-scope.mjs` is now the canonical writer of both.
+- **Parallel-session identity moves from repo-scoped to process-local (#1194 / #1188)** — `enforce-scope` now reads only process-local session ids (`readProcessLocalSessionIds`), so a peer's manifest in the same working copy is treated as foreign, not as your own; `memory-propose` authorizes off a process-local match of the raw session id rather than trusting the lock file alone. A peer's declared scope also gets its own place in the wave manifest now, as a `peer-session-<id>` record instead of a silent gap (#1195).
+- **Remote-offload: declare hosts, route heavy roles to a ready host instead of halving the wave (#1160)** — a `remote-hosts:` config block, an `ssh:<alias>` dispatch channel, and an offload decision wired into the resource gate right after the HR-004 cap (readiness is injected, never measured inside the gate itself). `skills/remote-offload/SKILL.md` is now the generic entry point, with adapters around the `offload` CLI.
+- **Four copy-classes collapsed to one module each (#1181 / #1182 / #1196 / #1197)** — atomic-JSON handling, subagent sidecar-path derivation, `expandHome`, and markdown-fence parsing each had 4–8 divergent copies; consolidating `atomic-json.mjs` also closed a data-loss path where a read-modify-write default silently replaced an unparsable or unreadable file.
+- **Refusals are now events, not silence (#1200 / #1201)** — `emitFinalWaveCompleted` writes `orchestrator.wave.final_refused` for six refusal paths, evolve and dialectic completions emit their own events, and reconcile's trigger set now lives in code (`KNOWN_TRIGGERS`) instead of being asserted in prose.
+- **Canonical session counting, fleet-wide (#1186)** — `site-numbers` and `vault-mirror --kind session` now count the same way everywhere: 289 raw lines in this repo's own ledger collapsed to 278 real sessions once double-counts were removed.
+- **Discovery-validator false positives cut — 186 of 400 measured hits were the harness's own gate-summary lines (#1198)** — a dedupe key and a gate-summary skip removed the noise; two brief claims about the masking order were also measured and refuted along the way.
+- **Three new mechanical guards land in `validate-plugin` (#1183 / #1184 / #1187)** — `emitEvent` try/catch coverage, validator-registration parity (every check actually wired in), and dead `.sh` citations in docs.
+- **The pre-push gate distinguishes a publish push from a scratch push; linked-worktree gates run green (15,829/0 on the remote host)** — a `.git` file (not a directory) in a linked worktree was previously misread as an untracked candidate, flagging 13 tracked files as missing.
+- **The AUQ clarity guard's delivery is proven live, not asserted (#1122)** — `check-auq-clarity` is wired into `validate-plugin` and blocks on the two hard hurdles at a measured 0% false-positive rate; its own wiring closes with a fake-regression proof, not a claim.
 
-Previous line (v3.21.0): guard mechanics, the public site, and cross-session messaging — which turned out to be one strand: a fact maintained in two places, and a guard that is green without biting.
+Previous line (v3.23.0): three external bug reports fixed end-to-end (Codex session-id versions, missing `/close` fields, plugin-root resolution), the worktree-promotion process boundary, and three measurement fixes (host-registry numbering, the mode-selector's mis-shaped read, two regained Semgrep rules).
 
 Full version history: [CHANGELOG.md](CHANGELOG.md).
 
@@ -165,10 +170,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: