session-orchestrator 3.22.0 → 3.24.0

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
 
@@ -92,7 +93,6 @@ Append a fenced ```json block at the end of your response per `agents/schemas/db
 ```
 
 Required: `status`, `task_id`, `files_changed`, `blockers`. Optional: `verdict`. **Emit `verdict` alongside `status` (status→verdict mapping: done→PROCEED, partial→PROCEED_WITH_FOLLOWUPS, blocked→BLOCKED). `status` is deprecated and will be removed in v4.0 (#472).** The coordinator parses the LAST fenced ```json block.
-```
 
 ## Edge Cases
 

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,11 +14,106 @@ 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.
+
+### Activation status (measured 2026-09-02)
+
+**Update, same day:** the token below was **revoked** — an unused credential is a
+liability per SEC-005's secrets-lifecycle discipline, and leaving a live,
+never-set-as-a-CI-variable token sitting in `infrastructure/projects-baseline`
+served no purpose once the control run below had already answered the
+question it was minted for. Re-minting it (same `glab api --method POST … --input -`
+recipe as Option A step 1) is now **Step 0** of the re-activation sequence
+below, not an assumed-still-valid token.
+
+A Project Access Token was provisioned today, scoped exactly as Option A
+below recommends:
+
+- **Name:** `session-orchestrator-ci-schema-drift`
+- **Project:** `infrastructure/projects-baseline` (id 52) — the TARGET repo,
+  not this one
+- **Scopes:** `read_repository`
+- **Access level:** Reporter (20)
+- **Expires:** 2027-09-01
+
+The masked `SCHEMA_DRIFT_TOKEN` CI variable on this project (id 74) was set
+with that token, then **removed again**. A control run with the token set
+confirmed the clone step authenticates correctly — but the drift check itself
+then failed for a real, already-known reason:
+`skills/vault-sync/validator.mjs`'s `vaultNoteTypeSchema` enum carries
+`peer-card` and `board`, and the canonical `infrastructure/projects-baseline`
+source does not have either yet. This is the documented vendor-ahead state
+(`scripts/sync-vault-schema.mjs` header, "Vendor-ahead state (2026-05-23,
+#503, I5)") and tracked as upstream-sync-debt in issue #531 (#503 itself is
+closed). With the variable set and `SCHEMA_DRIFT_OPTIONAL` still `"true"`,
+this exit-1 `DRIFT` is a **hard** failure — it is not in
+`allow_failure.exit_codes: [3]` — so leaving the variable set today would turn
+the next push red for a fact already tracked in #531, not for a new defect.
+The variable was removed rather than left set; activation stays blocked until
+the canonical enum gains both values.
+
+**Re-activation sequence once #531 lands upstream:**
+
+0. **Re-mint the token** — it was revoked (see § Activation status above). Run
+   the same `glab api --method POST … --input -` recipe as Option A step 1,
+   against the TARGET project (id 52), and copy the response's `token` field
+   immediately — it is shown exactly once.
+1. `read -rs TOKEN` at the prompt (no echo), then pipe it into `glab variable
+   set` rather than passing it as a `--value` argument — a value passed on the
+   command line is visible to any other process on the host via `ps`, while
+   stdin is not:
+
+   ```bash
+   read -rs TOKEN
+   printf '%s' "$TOKEN" | glab variable set SCHEMA_DRIFT_TOKEN \
+     -R infrastructure/session-orchestrator --masked
+   ```
+
+   **Not** `--protected`: `.gate-rules` (`.gitlab-ci.yml:74`) runs the job
+   on every branch and every MR pipeline, and a protected-only variable would
+   silently reproduce the exit-5 `UNAVAILABLE` failure on every unprotected
+   branch. (`glab variable set --help` documents stdin piping directly —
+   `cat file.txt | glab variable set SERVER_TOKEN` — but no `-`/dash value
+   for `--value`; the flag only accepts a literal string, so omitting it
+   entirely and piping the value is the only way to keep the token off argv.)
+2. Push an ordinary commit and read the `schema-drift-check` job log for
+   `RESULT: IN-SYNC` — and confirm the job DURATION is well over 20 seconds
+   (see the pipeline-6815 warning above). A fast "success" is the exit-3
+   soft-skip in disguise, not a real run.
+3. Flip `SCHEMA_DRIFT_OPTIONAL` to `"false"` at **both** sites —
+   `schema-drift-check` and `pipeline-gate` — in one commit.
+   `tests/ci/schema-drift-check.test.mjs` already asserts the two values are
+   equal, so no test edit is needed to enforce the flip.
+4. Local counter-probe before trusting the pipeline: clone
+   `infrastructure/projects-baseline` with the token, make a throwaway copy of
+   `packages/zod-schemas/src/vault-frontmatter.ts` with one field
+   deliberately edited, then run
+   `node scripts/sync-vault-schema.mjs --check --canonical <path-to-edited-copy>`
+   — expect exit 1 with a diff naming the edited field. That confirms the
+   check diffs real content rather than passing on a broken comparison.
+
+Per `.claude/rules/security.md` § SEC-005, this token's lifecycle belongs in
+`.claude/docs/SECRETS-INVENTORY.md` once one exists — that file is not present
+in this repo (measured 2026-09-02: no `.claude/docs/` directory tracked), so
+the inventory is not adopted here and this section remains the sole record.
+
 ### Required CI variable
 
 | Variable | Type | Mask | Protect | Value |
 |---|---|---|---|---|
-| `SCHEMA_DRIFT_TOKEN` | Variable | Yes | Optional | deploy token or PAT (see below) |
+| `SCHEMA_DRIFT_TOKEN` | Variable | Yes | No | Project Access Token or PAT — see Option A/B below |
 
 If `SCHEMA_DRIFT_TOKEN` is **not set**, the job prints a `NOT VERIFIED` notice
 and exits **3** — which `allow_failure.exit_codes` renders as an amber *warning*,
@@ -62,6 +157,18 @@ a schema diff that does not exist. Only 3 is listed in
 outcome also prints its own `[schema-drift] RESULT: <STATE>` line, so the job log
 answers "what happened" without the reader having to know this table.
 
+**Caveat — a second, narrower exit-3 collision (do not change the YAML for
+it).** `scripts/sync-vault-schema.mjs` has its own exit 3, for a different
+condition: malformed sentinel comments in `validator.mjs` (only one of
+`begin`/`end` present). If `--check` ever hit that branch, it would return
+exit 3 from the tool itself — and `allow_failure.exit_codes: [3]` reads the
+shell's final exit code, not which tool produced it, so a genuine tooling
+defect (broken sentinels) would render as the same amber "no token, declared
+optional" warning that the missing-token guard produces. This is a caveat to
+note, not a blocker: the sentinels are intact today, and the fix — if it is
+ever needed — is giving `sync-vault-schema.mjs`'s malformed-sentinel case a
+distinct exit code, not a change here.
+
 **After completing the token setup below, change `SCHEMA_DRIFT_OPTIONAL` to
 `"false"` in `.gitlab-ci.yml`** — in **both** places: the `schema-drift-check`
 job and `pipeline-gate`. One flag, two enforcement points;
@@ -84,35 +191,93 @@ not the accidental side effect of an unset CI variable.
 > exactly this failure — pipeline 6815 reported SUCCESS in 17 s having checked
 > nothing (issue #933).
 
-### Option A — Deploy Token (recommended, least-privilege)
-
-1. Open `infrastructure/projects-baseline` on your GitLab instance.
-2. Go to **Settings → Repository → Deploy tokens**.
-3. Click **Add token**:
-   - **Name:** `session-orchestrator-ci-schema-drift`
-   - **Expires at:** set a reminder (e.g. 1 year); rotate before expiry
-   - **Scopes:** check `read_repository` only
-4. Copy the generated token value (shown once).
-5. Open `session-orchestrator` on GitLab.
-6. Go to **Settings → CI/CD → Variables → Add variable**:
-   - **Key:** `SCHEMA_DRIFT_TOKEN`
-   - **Value:** paste the deploy token
-   - **Type:** Variable
-   - **Masked:** Yes
-   - **Protected:** Optional (enable if you only need it on protected branches)
-7. Save.
+### Option A — Project Access Token (recommended — works with the current clone URL)
+
+GitLab resolves a **deploy token** by its own fixed username
+(`gitlab+deploy-token-<n>`, or a custom username if one was set at creation).
+The job's clone step hardcodes the login as `oauth2:${SCHEMA_DRIFT_TOKEN}`
+(`.gitlab-ci.yml` ~:652) — `oauth2` is the username GitLab expects for a
+Personal or Project Access Token, not for a deploy token. A deploy token's
+value paired with that hardcoded username fails authentication at clone time
+and surfaces as exit 5 `UNAVAILABLE`, which reads as a network/credential
+problem rather than "wrong username" (see the demoted Deploy Token option
+below). Tokens with **PAT semantics** — GitLab accepts any username alongside
+the token value — authenticate correctly with this clone URL: a Personal
+Access Token, or, least-privilege, a **Project Access Token** scoped to the
+TARGET project (`infrastructure/projects-baseline`). A Project Access Token
+is preferred over a personal PAT for the same reason the deploy token used to
+be recommended: it belongs to the project, not a person, and survives staff
+changes.
+
+1. Create the token via API against the TARGET project (id 52) — GitLab has
+   no path to create a Project Access Token FOR a project from outside that
+   project's own Settings UI, so use `glab api`:
+
+   ```bash
+   glab api --hostname "$GITLAB_HOST" -X POST "projects/52/access_tokens" \
+     -H 'Content-Type: application/json' --input - <<'JSON'
+   {"name":"session-orchestrator-ci-schema-drift","scopes":["read_repository"],"access_level":20,"expires_at":"2027-09-01"}
+   JSON
+   ```
+
+   `--input -` plus the explicit `Content-Type: application/json` header is
+   required because the payload has a nested type (`scopes` is a JSON array),
+   which `glab api`'s `-f`/`-F` flag form cannot express. `access_level: 20`
+   is Reporter — the lowest access level that can read repository content.
+   `expires_at` is an operator choice, not a fixed value; the token created
+   for this document's own dry run (2026-09-02) was set 1 year out
+   (`2027-09-01`) — rotate before expiry.
+
+2. The response's `token` field holds the token value and is **shown exactly
+   once** — copy it immediately; GitLab will not display it again.
+
+3. Store it in `session-orchestrator` CI/CD variables as `SCHEMA_DRIFT_TOKEN`.
+   Prefer stdin over `--value` — a value passed as a command-line argument is
+   visible to other processes on the host (`ps`), while stdin is not:
+
+   ```bash
+   read -rs TOKEN
+   printf '%s' "$TOKEN" | glab variable set SCHEMA_DRIFT_TOKEN \
+     -R infrastructure/session-orchestrator --masked
+   ```
+
+   **Masked:** Yes. **Not** `--protected` — `.gate-rules` (`.gitlab-ci.yml:74`)
+   runs the job on every branch and every MR pipeline, so a protected-only
+   variable would silently be absent everywhere the job actually needs it.
 
 ### Option B — Personal Access Token (fallback)
 
-Use this if a deploy token is not available for the target project.
+The same PAT-semantics reasoning from Option A applies: a personal PAT
+authenticates under any username, so it works with the hardcoded `oauth2:`
+clone login. Use this only if you cannot create a Project Access Token on
+`infrastructure/projects-baseline` (e.g. you lack Owner/Maintainer there).
 
 1. Go to your GitLab profile → **Access Tokens**.
 2. Create a token with scope `read_repository` and a reasonable expiry.
 3. Store it in `session-orchestrator` CI/CD variables as `SCHEMA_DRIFT_TOKEN`
-   (Masked: Yes) — same steps 5–7 above.
-
-Note: a PAT is scoped to the creating user's access; prefer a deploy token so
-the CI credential survives staff changes.
+   (Masked: Yes, **not** Protected — see Option A step 3 above).
+
+A personal PAT is tied to the creating user's account and access; prefer the
+Project Access Token in Option A so the CI credential survives staff changes.
+
+### Deploy Token — does not work with the current clone URL
+
+This was the previously recommended option; it is demoted here because, as
+the job is written today, it does not authenticate. GitLab deploy tokens
+authenticate under their OWN username (`gitlab+deploy-token-<n>`, or a custom
+username set at creation) — never as `oauth2`. The job's clone step hardcodes
+`oauth2:${SCHEMA_DRIFT_TOKEN}` (`.gitlab-ci.yml` ~:652), so a deploy token's
+value paired with the wrong username fails authentication at clone time. This
+job reports that as exit 5 `UNAVAILABLE` — read as a network/credential-scope
+problem, when the actual cause is the username mismatch.
+
+To use a deploy token instead of Option A, `.gitlab-ci.yml`'s clone step would
+need to stop hardcoding `oauth2` — either read the deploy token's own username
+from a second CI variable and interpolate it into the clone URL, or create the
+deploy token with a custom username of `oauth2` if the GitLab instance allows
+choosing one. Neither change is made in this repo; that edit is out of this
+document's scope. Option A avoids needing it at all, by using a token whose
+username requirement (any username) already matches the hardcoded login.
 
 ### Verification path
 
@@ -148,8 +313,12 @@ Documenting it here for completeness:
   `infrastructure/session-orchestrator`.
 - Once the allowlist entry is saved, the job can use `CI_JOB_TOKEN` directly
   and `SCHEMA_DRIFT_TOKEN` is not needed.
-- Issue #279 chose the deploy-token path because it requires no admin action
-  in the foreign project and works immediately after variable creation.
+- Issue #279 chose the token-variable path over this allowlist because it
+  requires no admin action in the foreign project and works immediately after
+  variable creation. The original choice was a deploy token; as documented in
+  Option A above, a deploy token does not actually authenticate with this
+  job's hardcoded `oauth2:` clone login, so a Project Access Token (or PAT)
+  is the variant that delivers on that original reasoning.
 
 ## `pipeline-gate` — the fan-in job
 

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/<version>+codex.<stamp>/`, 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.
+