session-orchestrator 3.22.0 → 3.23.0

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.22.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.22.0)
+## Recent highlights (v3.23.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.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 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.
+- **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.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.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/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
 

package/commands/bootstrap.md

@@ -6,7 +6,7 @@ argument-hint: "[--upgrade <tier>]"
 
 # Bootstrap
 
-**TL;DR — for first-time users:** Run `/bootstrap` with no flags. The skill auto-detects the right tier (fast/standard/deep) from your repo, recommends one with a one-line reason, and asks **a single confirmation question**. Bestätigen → fertig. Keine weiteren Schritte.
+**TL;DR — for first-time users:** Run `/bootstrap` with no flags. The skill auto-detects the right tier (fast/standard/deep) from your repo, recommends one with a one-line reason, then walks a **fixed questionnaire** — tier/stack (1–2 prompts), owner persona (5), dispatcher autonomy (1); **7–9 prompts** on a first-run full bootstrap. Bestätigen → fertig. Keine weiteren Schritte.
 
 The flags below cover special cases (re-adopting an existing repo, upgrading a tier, syncing rules). If you don't recognize the case in the description, you don't need the flag.
 
@@ -22,7 +22,7 @@ This is the path 95 % of users want.
 
 | Invocation | Behavior |
 |------------|----------|
-| `/bootstrap` | Auto-detect tier (fast / standard / deep) from repo context. Present recommendation via `AskUserQuestion` with options to confirm or override. At most ONE question in the normal case. Then scaffold files + commit. |
+| `/bootstrap` | Auto-detect tier (fast / standard / deep) from repo context. Present recommendation via `AskUserQuestion` with options to confirm or override. Tier/stack: 1–2 questions; first-run full bootstrap adds owner interview (5, `owner-interview.mjs`) + dispatcher-autonomy capture (1). Then scaffold files + commit. |
 
 What the user sees:
 

package/commands/close.md

@@ -10,7 +10,9 @@ The user wants to end the current session.
 **Pre-check before invoking session-end:** Determine `<state-dir>` from the current platform (`.claude/`, `.codex/`, `.cursor/`, or `.pi/`). Check if `<state-dir>/STATE.md` exists and read its `status` field. Three exit conditions:
 
 1. **STATE.md does not exist:** Read Session Config to check `persistence`. If `persistence: false`, inform the user: "Session completed (persistence is off — STATE.md was never created). Use `/session` to start a new session." If `persistence: true` (or Session Config unavailable), inform the user: "No active session found. Use `/session` to start a session first." Either way, stop.
-2. **STATE.md exists and `status: completed`:** Inform the user: "Previous session was already finalized by session-end. Start a new session with `/session`, or inspect `<state-dir>/STATE.md` to review the prior close. (Note: if this is unexpected after an Express Path session, `commands/go.md` should have auto-invoked /close — check that STATE.md `## Deviations` contains an `Express path:` entry.)" and stop.
+2. **STATE.md exists and `status: completed`:** `status: completed` alone is NOT proof that session-end's Phase 3.7 writer ever ran (#429) — the field can be set by hand, or by any path that stops short of that write. Before treating the prior close as final, read STATE.md frontmatter's `session` field (the semantic session id, e.g. `main-2026-05-27-session-1`; see `skills/_shared/state-ownership.md`) and check whether `.orchestrator/metrics/sessions.jsonl` contains a record whose `session_id` equals it (`grep -c` for the literal id, or parse each line as JSON and compare `session_id`).
+   - **A matching record exists:** Inform the user: "Previous session was already finalized by session-end. Start a new session with `/session`, or inspect `<state-dir>/STATE.md` to review the prior close. (Note: if this is unexpected after an Express Path session, `commands/go.md` should have auto-invoked /close — check that STATE.md `## Deviations` contains an `Express path:` entry.)" and stop.
+   - **No `session` field is present in STATE.md frontmatter, OR no matching record exists:** Warn the user: "STATE.md completed ohne Ledger-Record — session-end wurde vorher nie ausgeführt (#429)." Do NOT stop — proceed to invoke the session-end skill exactly as in exit condition 3, so the missing record gets written this time. (The SessionEnd hook's `backfillCompletedFromStateMd` — `scripts/lib/session-close-backfill.mjs` — independently self-heals this same gap on a later session's teardown; this Pre-Check branch covers the case where /close is re-run before that hook has had a chance to fire.)
 3. **STATE.md exists and `status: active` or `status: paused`:** Proceed to invoke the session-end skill.
 
 For any other `status` value (e.g., `idle`), warn the user: "Unexpected session status `<value>`. Inspect `<state-dir>/STATE.md` and use `/session` to reset if needed." and stop.

package/commands/go.md

@@ -10,7 +10,7 @@ The user has approved the session plan. Begin execution immediately.
 
 ## Express Path Detection
 
-Before invoking the wave-executor, check the conversation context for the Express Path activation banner emitted by session-plan or session-start Phase 8.5:
+Before invoking the wave-executor, check the conversation context for the Express Path activation banner — printed by `node scripts/express-path.mjs` in session-start Phase 8.5, and carried through session-plan's Short-Circuit (#1146):
 
 ```
 Express path activated — <N> tasks, coordinator-direct, no inter-wave checks.

package/commands/journey-audit.md

@@ -0,0 +1,43 @@
+---
+description: Outside-in product audit as a deep session — 7 read-only roles check what the site promises against what the code does, what a user experiences, what arrives by mail, and what the data says is used. Writes a dossier; needs a per-repo journey-manifest.
+argument-hint: "[manifest-path]"
+---
+
+# Journey Audit
+
+Invokes the `journey-audit` skill (`skills/journey-audit/SKILL.md`). Dispatches roles R1–R7 against
+the repo's journey manifest, re-verifies every P0 claim in the coordinator thread, and writes
+`docs/audits/YYYY-MM-DD-user-journey-audit.md`.
+
+Complements `/discovery` rather than replacing it: discovery checks code quality inside-out,
+journey-audit checks product truth outside-in.
+
+## Argument Validation
+
+The optional argument is a path to the manifest, overriding the default
+`.orchestrator/journey-manifest.md`. Use it for a second manifest (e.g. a staging variant) or when
+the repo keeps it elsewhere.
+
+- `/journey-audit` — uses `.orchestrator/journey-manifest.md`
+- `/journey-audit .orchestrator/journey-manifest.staging.md` — uses that file instead
+
+If the argument names a file that does not exist, say so and stop — do NOT silently fall back to
+the default path, because auditing the wrong manifest produces findings that look valid and are not.
+
+## Behavior
+
+1. **Gates** — bootstrap gate, then the manifest HARD-GATE: no manifest → refuse and point at
+   `templates/_shared/journey-manifest.md`; no filled `## SAFETY` block → run without R5 and say so.
+2. **Peer-session check** — announce the audit before dispatching (`.claude/rules/parallel-sessions.md`).
+3. **Wave** — R1–R7 in parallel, all read-only except R5, each fed from the manifest.
+4. **Coordinator re-verification** — every P0 re-checked with the coordinator's own command before
+   it enters the dossier. This step is not optional and not delegable.
+5. **Dossier + closing AUQ** — fixed section order, then fix-wave packages (multiSelect) and an
+   optional issue batch via `skills/gitlab-ops/SKILL.md` label taxonomy.
+
+## Related
+
+- `skills/journey-audit/SKILL.md` — the skill, in full
+- `templates/_shared/journey-manifest.md` — the per-repo manifest template (SAFETY block gates R5)
+- `docs/prd/2026-08-28-journey-audit-skill.md` — the PRD, incl. the first-run evidence
+- `commands/discovery.md` — the inside-out counterpart

package/docs/USER-GUIDE.md

@@ -36,7 +36,7 @@ Session Orchestrator is a Claude Code and Codex plugin that brings structured, w
 
 #### Claude Code
 
-Claude Code installs plugins through slash commands inside a running session. There is no `claude plugin` shell CLI — run these commands in the Claude Code prompt:
+Claude Code also has a `claude plugin` shell CLI (`claude plugin --help` lists subcommands). For end-user installation, use the slash commands inside a running session — run these in the Claude Code prompt:
 
 **From GitHub (recommended for end users):**
 
@@ -992,7 +992,7 @@ Enforcement levels (configured via `enforcement`):
 
 ### Prerequisites
 
-Scope and command enforcement hooks require `jq` to be installed. If `jq` is not available, hooks degrade gracefully — all operations are allowed with a warning to stderr. Install `jq` for enforcement to be active:
+The enforcement hooks (`hooks/enforce-scope.mjs`, `hooks/enforce-commands.mjs`) do not call `requireJq()` — they run without `jq`. `jq` is required by `scripts/validate-plugin.mjs` and by the wave-scope shell snippets in `skills/wave-executor/` (e.g. deriving `blockedCommands` and reading Session Config). Install `jq` when you run those tools or snippets:
 
 - **macOS**: `brew install jq`
 - **Ubuntu/Debian**: `sudo apt-get install jq`

package/docs/ci-setup.md

@@ -14,6 +14,20 @@ project-level Job Token allowlists are explicitly configured — an admin action
 in the foreign project that cannot be scripted from here. The fix is a deploy
 token or PAT stored as the masked CI variable `SCHEMA_DRIFT_TOKEN`.
 
+> **Current decision (2026-08-28, #1062): amber is the accepted normal state.**
+> `glab variable list` on this project returns zero CI variables — no
+> `SCHEMA_DRIFT_TOKEN` is set — so every pipeline runs the job to exit 3
+> (`NOT VERIFIED`) and `pipeline-gate` prints the amber line. This is a
+> deliberate operator choice, not a defect: the job is correctly fail-loud
+> (exit taxonomy below), the vendored schema is compared manually at each
+> baseline refresh (#1100), and no token is rotated for a check that runs
+> against a private project of our own. Session-start's CI banner keeps
+> reporting the soft failure on purpose (`allow_failure` jobs are invisible
+> at pipeline level, which is what that banner exists to surface). Revisit
+> trigger: the first time a vendored-schema drift ships unnoticed, or when
+> the baseline gains a public mirror — then set the token (Option A below)
+> and flip `SCHEMA_DRIFT_OPTIONAL` at both sites.
+
 ### Required CI variable
 
 | Variable | Type | Mask | Protect | Value |

package/docs/codex-setup.md

@@ -30,6 +30,42 @@ codex plugin list --available --json
 
 It operates only through public Codex plugin commands; hook trust remains untouched.
 
+### Short-Form Marketplace Add (Verified 2026-08-28, codex-cli 0.141.0)
+
+`codex plugin marketplace add --help` documents a short remote form:
+
+```
+codex plugin marketplace add owner/repo --ref main
+```
+
+Tested against this repo in a scoped throwaway `CODEX_HOME` (2026-08-28, codex-cli 0.141.0):
+
+```
+$ codex plugin marketplace add Kanevry/session-orchestrator --json
+{
+  "marketplaceName": "kanevry",
+  "installedRoot": ".../.tmp/marketplaces/kanevry",
+  "alreadyAdded": false
+}
+$ echo $?
+0
+```
+
+This succeeds and clones the repo via git — no `--ref`/`owner/repo` string is needed beyond the short form; the resulting marketplace name (`kanevry`) is read from `.claude-plugin/marketplace.json`'s `name` field, not from the `owner/repo` argument.
+
+**However**, the subsequent install step fails identically for both this short remote form *and* the long-form local install documented above (`codex plugin marketplace add "$PWD"`, same as `scripts/codex-install.mjs` runs):
+
+```
+$ codex plugin add session-orchestrator@kanevry --json
+Error: plugin `session-orchestrator` was not found in marketplace `kanevry`
+$ echo $?
+1
+```
+
+`codex plugin list --available --json --marketplace kanevry` returns `{"installed": [], "available": []}` for both forms — the marketplace is configured, but no plugin is discoverable inside it, contradicting item 1 under "Understand the Three States" below. A synthetic marketplace root mirroring this repo's exact layout (`.codex-plugin/plugin.json` directly at root, no `.claude-plugin/marketplace.json`) reproduces the same empty discovery; by contrast, a directory scanned via a `<root>/plugins/<name>/.codex-plugin/plugin.json` layout (the shape `codex plugin marketplace add --help`'s `--sparse plugins/foo` example implies, and the shape this host's own pre-existing `local` marketplace uses via `~/plugins/session-orchestrator`) resolves correctly. This suggests codex's own plugin-discovery convention expects a `plugins/<name>/` marketplace layout that this repo's flat root does not provide, though `.claude-plugin/marketplace.json` (Claude Code's schema) is independently accepted as "a supported manifest" at the `marketplace add` step, without resolving to a discoverable Codex plugin at `list` time.
+
+**Caveat that limits this finding:** this host's installed codex-cli is **0.141.0**, older than the "0.144.4 or newer" prerequisite this guide states above. This failure was not re-verified against 0.144.4+, so it may be specific to running below the documented minimum rather than a defect in this repo's layout on a supported version. Until re-verified on 0.144.4+, treat both the short remote form and the long-form local install (`node scripts/codex-install.mjs`) as **unconfirmed end-to-end on this host** — the `marketplace add` step succeeds either way, but `plugin add` does not, on 0.141.0. Do not elevate either form to a README-level recommended command until a `plugin add` success is measured and dated.
+
 ## Understand the Three States
 
 Codex reports three distinct states that must not be conflated:
@@ -115,9 +151,12 @@ After installation and hook review, start a fresh task. Session Orchestrator exp
 | Config file | `CLAUDE.md` | `AGENTS.md` |
 | Task tracking | TaskCreate/TaskUpdate | Text-based checklists |
 | Hook root | `$CLAUDE_PLUGIN_ROOT` | native `${PLUGIN_ROOT}` plus `CODEX_PLUGIN_ROOT` compatibility export |
+| MCP server root | `$CLAUDE_PLUGIN_ROOT`, injected into the server process | resolved by `.mcp.json` itself — Codex expands no root variable inside `mcpServers.args` and injects none into the MCP child's environment |
 
 Both platforms share session history and learnings through `.orchestrator/metrics/`.
 
+`CODEX_PLUGIN_ROOT` is **session-orchestrator's own compatibility export, not a variable Codex provides.** The hook wrapper in `hooks/hooks-codex.json` assigns it from Codex's native `${PLUGIN_ROOT}` so that shared code (`scripts/lib/plugin-root.mjs`) can read one name on every harness. Nothing outside a hook command string sets it — in particular an MCP server started by Codex inherits neither `CODEX_PLUGIN_ROOT` nor `PLUGIN_ROOT`. That is why `.mcp.json` resolves the plugin root on its own instead of relying on a harness-provided variable: it tries `CLAUDE_PLUGIN_ROOT`, `CODEX_PLUGIN_ROOT`, `PLUGIN_ROOT`, then `git rev-parse --show-toplevel`, then asks Node to resolve the installed `session-orchestrator` package (which reaches `resolvePluginRoot()` and with it the `CURSOR_RULES_DIR` / `PI_PLUGIN_ROOT` roots too), and as the last tier scans the client plugin caches (`${CODEX_HOME:-$HOME/.codex}` and `$HOME/.claude` under `plugins/cache/*/session-orchestrator/*`, accepted only when the copy's `package.json` names `session-orchestrator`; newest by mtime wins). The tier order is documented once, in `scripts/lib/plugin-root.mjs` § TIER ORDER, and `.mcp.json` mirrors it. Each candidate must actually contain `scripts/mcp-server.sh` before it is used.
+
 ## Platform Limitations
 
 Claude Code dispatches role-specialized agents with dedicated definitions. Codex maps implementation work through its configured roles, so task prompts carry specialization that is not represented by a dedicated role. A project can add more specific TOML definitions under `.codex/agents/` when needed.
@@ -140,3 +179,28 @@ codex plugin list --available --json
 - **Other pre-public plugin/config/cache/hook-state residue is suspected:** this state is unsupported. Do not modify private Codex files. File an issue with `codex --version`, `codex plugin list --available --json`, and `codex plugin marketplace list --json` output so the public recovery path can be diagnosed.
 - **Agent dispatch fails:** verify Codex multi-agent support and inspect the bundled or project-level role TOMLs.
 - **Hooks report that Node is unavailable:** expose Node 24+ on the Codex hook PATH or set `SO_NODE_BIN` to the absolute Node executable.
+- **`MCP startup failed: handshaking with MCP server failed: connection closed: initialize response`:** the MCP entrypoint could not locate the plugin, or could not run. Read the server's **stderr** — since GH#64 it names itself. Two diagnostics exist:
+  - `session-orchestrator: cannot locate the plugin root` — no plugin-root variable was set, the working directory was outside any git checkout, no cached copy of the plugin was found, and Node could not resolve an installed `session-orchestrator` package. Fix: reinstall the plugin so a cached copy exists (see *Where the plugin actually lives* below), or add `CODEX_PLUGIN_ROOT` (or `CLAUDE_PLUGIN_ROOT`) pointing at the plugin directory to that server's `env` block. Do not expect Codex to supply the variable — see the note under *Key Differences* above.
+  - `session-orchestrator: 'jq' not found in PATH` — the plugin was found but `jq` is missing. Fix: install `jq` and restart Codex. (Before GH#64 this case wrote a JSON-RPC error to *stdout* with `id: null`, which is not a valid `initialize` response either, so a missing `jq` and a missing plugin were indistinguishable from the client side.)
+- **The MCP tools answer `Error: not inside a git repository`:** expected, not a failure. The handshake succeeded; `session_config` and `session_metrics` read the *project* you are working in, so they need Codex's working directory to be inside a git repository. Start Codex from the project, or `cd` into it.
+- **"another session holds the lock" right after `resume`/`compact` in Codex:** the session lock appears to be self-collision across a resume/compact boundary rather than a real second session. Cause: before v3.23.0 (unreleased at time of writing), `parseSessionId()`'s UUID matcher was pinned to version nibble `4` (Claude Code's format), so every native session id Codex CLI mints — UUIDv7 — failed to parse; `hooks/on-session-start.mjs` fell through to a freshly generated `randomUUID()` on each `SessionStart`, and the new mint then collided with the lock the previous mint still held (Kanevry#66 / #1091). Fixed in v3.23.0 by widening `UUID_RE` in `scripts/lib/session-id.mjs` to accept any RFC 9562 UUID version 1–8, not only `4`. Check: `node -e "import('./scripts/lib/session-id.mjs').then(m=>console.log(m.parseSessionId('017f22e2-79b0-7cc3-98c4-dc0c0c07398f')))"` must print `format: 'uuid'` and `version: 7` (verified 2026-08-28 @ 30940cb — it does).
+
+### Where the plugin actually lives (measured 2026-08-28, codex-cli 0.141.0)
+
+Three facts explain why launching Codex from `$HOME` used to kill the MCP server before `initialize` (GH Kanevry/session-orchestrator#64), and none of them is guessable from the docs:
+
+1. **Codex copies the plugin; it does not run it from your clone.** A marketplace install lands at `<CODEX_HOME>/plugins/cache/<marketplace>/<plugin>/<version>/` — measured here as `~/.codex/plugins/cache/local/session-orchestrator/3.22.0+codex.20260822193811/`, a full self-contained tree with its own `.mcp.json`, `package.json` and `scripts/mcp-server.sh`. Claude Code uses the same shape under `~/.claude/plugins/cache/`.
+2. **The MCP child gets no plugin-root variable and no working directory of its own.** Probing a registered MCP server launched from `/tmp` showed `PWD=/private/tmp` (the launch directory, verbatim) and `CLAUDE_PLUGIN_ROOT`, `CODEX_PLUGIN_ROOT`, `PLUGIN_ROOT` and `CODEX_HOME` **all unset**; `codex mcp list` prints `Env: -` and `Cwd: -` for the entry. `HOME` *is* set. So from `$HOME` — not a git repository — every locator the entrypoint had was blind, and `$(git rev-parse --show-toplevel)` collapsed the path to `/scripts/mcp-server.sh`.
+3. **Codex does not expand `${...}` in the registered command, and the registration is a snapshot.** `codex mcp list` shows the launch string verbatim, `${CLAUDE_PLUGIN_ROOT:-…}` and all — bash expands it, not Codex. It comes from the *cached* `.mcp.json`, taken at install time: a fix committed to this repo reaches an existing install only after a reinstall.
+
+The entrypoint therefore scans those cache roots itself, matching on `package.json` `"name": "session-orchestrator"` rather than on the directory name, and preferring the most recently installed copy. A directory that merely *sits* under a `session-orchestrator/` marketplace folder is rejected.
+
+**If your install predates this fix, reinstall — the fix cannot reach a cached copy on its own:**
+
+```bash
+codex plugin marketplace add Kanevry/session-orchestrator
+codex mcp list | grep session-orchestrator   # the launch string should mention plugins/cache
+```
+
+The 0.144.4 minimum-version caveat above still stands: everything in this section was measured on **0.141.0**, below the documented minimum, and has not been re-verified on 0.144.4+ or on the reporter's 0.149.0-alpha.4.3.
+

package/docs/components.md

@@ -7,8 +7,8 @@ Detailed component inventory and architecture reference for Session Orchestrator
 ```mermaid
 flowchart LR
     USER([Operator]) -->|invokes /session| COORD[Coordinator]
-    COORD -->|reads| SK[Skills<br/>47 user-facing]
-    COORD -->|invokes| CMD[Commands<br/>27 slash-cmds]
+    COORD -->|reads| SK[Skills<br/>48 user-facing]
+    COORD -->|invokes| CMD[Commands<br/>28 slash-cmds]
     COORD -->|dispatches| AG[Agents<br/>15 typed sub-agents]
     AG -.->|parallel waves| W1[code-implementer]
     AG -.-> W2[test-writer]
@@ -18,11 +18,11 @@ flowchart LR
     COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
 ```
 
-## Skills (47 user-facing)
+## Skills (48 user-facing)
 
 - **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
 - **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`, `contract-version-bump`
-- **Planning & discovery:** `plan`, `discovery`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`, `grill`
+- **Planning & discovery:** `plan`, `discovery`, `journey-audit`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`, `grill`
 - **Architecture:** `architecture`, `domain-model`, `ubiquitous-language`
 - **Cross-session:** `evolve`, `convergence-monitoring`, `memory-cleanup`, `reconcile`, `sunset-review`, `eval`
 - **Vault & docs:** `vault-sync`, `vault-mirror`, `daily`, `docs-orchestrator`
@@ -32,9 +32,9 @@ flowchart LR
 - **Operator ergonomics:** `eli5` (plain-language restatement of the last answer)
 - **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))
 
-## Commands (27)
+## Commands (28)
 
-`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/contract-version-bump`, `/eli5`.
+`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/contract-version-bump`, `/eli5`, `/journey-audit`.
 
 ## Agents (15 typed sub-agents)