session-orchestrator 3.24.0 → 4.0.0

package/commands/session.md

@@ -1,6 +1,6 @@
 ---
-description: Start a development session (housekeeping, feature, deep)
-argument-hint: "[housekeeping|feature|deep]"
+description: Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)
+argument-hint: "[housekeeping|feature|deep|ultradeep]"
 ---
 
 # Session Start
@@ -9,7 +9,22 @@ You are beginning a new development session. The user has invoked `/session` wit
 
 **Default rationale (measured, not assumed):** `deep` is the default because it is what operators actually run — 77.3 % of 489 recorded sessions across 5 repos, and 115 of 228 (50.4 %) in this repo's own `.orchestrator/metrics/sessions.jsonl`. The former `feature` default made the majority case the one that had to be typed out every time. A `deep` default costs a downgrade keystroke in the minority case; a `feature` default cost an upgrade keystroke in the majority case.
 
-**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit `$ARGUMENTS` value ALWAYS wins over the default — `/session housekeeping` and `/session feature` behave exactly as before. If `$ARGUMENTS` is not empty and does not match any valid type, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep." Then fall back to `deep`.
+**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit `$ARGUMENTS` value ALWAYS wins over the default — `/session housekeeping` and `/session feature` behave exactly as before. `ultradeep` is additionally accepted as an ARGUMENT ALIAS (see below); it is not a fourth type. If `$ARGUMENTS` is not empty and does not match any valid type or the alias, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep (alias: ultradeep)." Then fall back to `deep`.
+
+### Argument alias: `ultradeep` (PRD `docs/prd/2026-09-06-ultradeep-session-profile.md`)
+
+`/session ultradeep` is an alias, NOT a fourth `session_type`. Resolve it to TWO STATE.md frontmatter values and then continue exactly as a `deep` session would:
+
+```yaml
+session-type: deep          # what every downstream consumer sees
+session-profile: ultradeep  # the only place the alias survives
+```
+
+- **`session-type` NEVER becomes `ultradeep`.** The value is a closed set in `scripts/lib/session-schema/constants.mjs` (`VALID_SESSION_TYPES`) and in `scripts/lib/wave-sizing.mjs`; a fourth member would degrade silently in two places (`scripts/lib/telemetry/schema.mjs` maps an unknown type to `"other"`, `scripts/lib/session-close-backfill.mjs` labels it `housekeeping`). The alias exists so that no closed set has to change.
+- **`session-profile` is optional and absent by default.** A plain `/session deep` writes NO `session-profile` key. Absent means "no profile" — never write an empty string, `none`, or `null` to mean absence. Read/write helpers: `readSessionProfile` / `setSessionProfile` in `scripts/lib/state-md.mjs`.
+- **What the profile changes** is the WAVE SHAPE, not the session type: 7 waves with a coordinator-direct Synthesis-Gate at wave 2. See `skills/session-plan/SKILL.md` § Role-to-Wave Mapping and `skills/wave-executor/SKILL.md` § Ultradeep Profile.
+- **Precondition.** The profile needs 7 waves. If Session Config sets `waves` below 7, do NOT silently plan 5 waves under an ultradeep label — name the conflict to the user and let them raise `waves` or drop the alias.
+- **Budgets are deliberately not implemented yet** (PRD § 7): no `ultradeep.max-*` key is read anywhere. Do not invent one; the PRD defers thresholds until three runs have been measured.
 
 > **Not read from Session Config.** There is deliberately no `session-type:` (or equivalent) key in the `## Session Config` block — `scripts/lib/config.mjs` `parseSessionConfig()` does not emit one, so any such key in a repo's CLAUDE.md (or its Codex CLI equivalent AGENTS.md) is inert prose. The `session-type:` scalar that IS live lives in STATE.md frontmatter (read by `scripts/print-applicable-rules.mjs` for rule mode-gating) and is written per session, not configured per repo. Do not reintroduce a Session Config key here without wiring it into the parser first.
 

package/docs/README.md

@@ -98,6 +98,10 @@ Two things worth knowing about this split:
 | `docs/plans/` | Active work document | `/write-executable-plan` artifacts for in-progress work. May not exist when nothing is mid-plan. |
 | `docs/_private/`, `docs/specs/` | Local-only (gitignored) | Operator scratch space; never tracked, out of scope for this classification. |
 
+### Superseded design notes
+
+Because `docs/specs/` is gitignored, a correction written INTO a spec can never be committed — so the correction lives here instead. `docs/specs/2026-05-26-parallel-aware-sessions-design.md` (parallel-aware sessions) specifies PID-based lock liveness (`stale-pid-dead`). That is **superseded**: liveness is heartbeat-age based since #1137 (`isLockLive`; `acquire()` knows only `stale-heartbeat`), and the recorded PID is consulted nowhere since #1151 — it was the PID of the short-lived subprocess that wrote the lock, dead within a second. Read the local spec only with that correction applied.
+
 ## See Also
 
 - `docs/prd/2026-07-08-docs-public-split.md` — the epic that established this split (S1–S8, issues #775–#782).

package/{agents/AGENTS.md → docs/agent-authoring.md}

@@ -1,37 +1,30 @@
----
-name: agents-authoring-spec
-description: NOT A DISPATCHABLE AGENT — never select this. It is the authoring specification that the agent definitions in this directory must follow, loaded as a nested instruction file. Claude Code's plugin loader registers every agents/*.md as an agent by directory convention, and the manifest's `agents` key is additive-only, so it cannot exclude a path. Without this frontmatter the file registered as an unnamed agent with FULL tool access; the minimal `tools` line below is what bounds that. If you need agent-authoring rules, read this file — do not dispatch it.
-tools: Read
----
+<!-- Moved in v4.0.0 from `agents/AGENTS.md` (audit 2026-09-06 § 5A). It never was an agent: Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it — only pseudo-frontmatter (`name: agents-authoring-spec`, `tools: Read`) kept the false registration bounded. Living under `docs/` removes the registration instead of bounding it. -->
 
-# `agents/` — Sub-Agent Authoring Conventions
+# Sub-Agent Authoring Conventions (`agents/**`)
 
-> Nested instruction file for the `agents/` subtree. Claude Code / Cursor IDE
-> and Codex CLI both load this additively when working on files in this
-> directory (root `CLAUDE.md` for the big picture, this file for local
-> conventions). Resolution rule:
+> Authoring spec for the sub-agent definitions in `agents/`. Read it together
+> with the root `CLAUDE.md` (big picture) and, when working under `agents/`,
+> whatever nested instruction file that subtree carries. Resolution rule:
 > [`../skills/_shared/instruction-file-resolution.md`](../skills/_shared/instruction-file-resolution.md).
 >
-> This is **not** an agent definition — it is the authoring spec the agent
-> `*.md` definitions in this directory must follow. The plugin validator
-> (`scripts/lib/validate/check-agents.mjs`) excludes `AGENTS.md` / `CLAUDE.md`
-> from agent-frontmatter validation by name, and `measureDescriptionSurface`
-> excludes them from its walked corpus (#878).
->
-> **Claude Code's plugin loader makes no such exception.** It registers every
-> `agents/*.md` as a dispatchable agent by directory convention, and the
-> manifest's `agents` key is documented as *additive* ("in addition to those in
-> the `agents/` directory"), so it cannot exclude a path. With no frontmatter
-> this file therefore registered as an agent named `AGENTS` with **full tool
-> access**. The frontmatter above is the containment: it names the file for what
-> it is, states in the `description` that it must never be dispatched, and caps
-> `tools` at `Read`. Do not remove it — and if you add another non-agent doc to
-> this directory, give it the same treatment.
+> **This spec lives in `docs/`, not in `agents/`, on purpose.** Claude Code's
+> plugin loader registers every `agents/*.md` as a dispatchable agent by
+> directory convention, and the manifest's `agents` key is documented as
+> *additive* ("in addition to those in the `agents/` directory"), so it cannot
+> exclude a path. As `agents/AGENTS.md` this file was therefore a registered
+> agent — first an unnamed one with **full tool access**, later a contained one
+> whose pseudo-frontmatter capped `tools` at `Read`. Moving it out of the
+> directory removes the registration rather than bounding it. The same applies
+> to any future non-agent doc: put it under `docs/`, never in `agents/`.
+> (`scripts/lib/validate/check-agents.mjs` still excludes `AGENTS.md` /
+> `CLAUDE.md` by name, and `measureDescriptionSurface` still excludes them from
+> its walked corpus (#878) — both now vacuous for this file, and the safety net
+> for anyone who reintroduces one.)
 >
 > Sibling spec: for `.claude/rules/*.md` frontmatter (conditional loading via
 > globs/mode/host-class/expiry, plus the never-always-on invariant for
 > auto-generated rules), see the canonical authoring spec
-> [`docs/rule-authoring.md`](../docs/rule-authoring.md).
+> [`docs/rule-authoring.md`](./rule-authoring.md).
 
 ## Local Validation Commands
 

package/docs/baseline.md

@@ -0,0 +1,67 @@
+# The projects-baseline Relationship
+
+**One line:** `projects-baseline` is a **private, optional** companion repository that
+holds the operator's canonical rule and schema corpus. session-orchestrator reads
+from it when it is present and degrades to a documented fallback when it is not.
+Nothing in this plugin requires it, and no public consumer needs to obtain it.
+
+## What it is
+
+A separate git repository (not vendored, not a submodule, not on npm) carrying:
+
+- `packages/zod-schemas/src/vault-frontmatter.ts` — the canonical Zod schema for
+  Obsidian vault note frontmatter.
+- `templates/shared/.vault.yaml.template` — the canonical `.vault.yaml` template.
+- A `.claude/rules/` corpus. Measured: **26 rule files, all using `paths:`
+  frontmatter, 0 using `globs:`** (`scripts/lib/rule-loader.mjs` module doc;
+  restated in `scripts/lib/validate/check-rules.mjs`). That corpus is the reason
+  `paths:` exists as a same-shape alias for `globs:` at all (#795) — the fleet's
+  rules are read **from the baseline**, not from this plugin, so the plugin had to
+  learn the baseline's frontmatter convention rather than the other way round.
+
+## How the plugin finds it
+
+Never by a hardcoded path. Resolution is host-local, most specific first:
+
+1. `SO_BASELINE_PATH` environment variable
+2. `owner.yaml` `paths.baseline-path` (`~/.config/session-orchestrator/owner.yaml`,
+   host-local, never committed — see `docs/owner-config-schema.md`)
+3. a sibling checkout at `<repoRoot>/../projects-baseline`
+4. `~/Projects/projects-baseline` (legacy default)
+
+Tiers 1–2 go through `resolveHostPath('baseline-path', …)` in
+`scripts/lib/config/host-paths.mjs`. `scripts/lib/vault-backfill/template.mjs`
+additionally honours `PROJECTS_BASELINE_DIR` above all four, for back-compat.
+
+## The four hard-runtime touchpoints, and what each degrades to
+
+| Touchpoint | Reads / writes | Without a baseline |
+|---|---|---|
+| `scripts/lib/frontmatter-guard.mjs` | the canonical vault-frontmatter Zod schema | `readVaultSchema()` → `null`; `generateFrontmatterSnippet()` falls back to an in-module enum set mirroring `skills/vault-sync/validator.mjs` and warns ONCE on stderr; `computeSchemaHash()` → `null` (never the empty-string hash) |
+| `scripts/lib/vault-backfill/template.mjs` | `.vault.yaml.template` | `loadTemplate()` calls `dieFn(2, …)` with a message naming `owner.yaml paths.baseline-path`, `SO_BASELINE_PATH`, `PROJECTS_BASELINE_DIR`, and the sibling-checkout convention. Only `scripts/vault-backfill.mjs` is affected; nothing else aborts |
+| `scripts/sync-vault-schema.mjs` | `--check` drift guard against the canonical schema | exits 2 (missing file). It is a maintenance script, never on a session path |
+| `scripts/lib/reconcile/writer.mjs` + `scripts/lib/session-end/phase-skip.mjs` | writes rule proposals into the baseline (`reconcile.targets` containing `baseline`) | `baselineRoot` absent ⇒ the `baseline` target is a **no-op**; `repo-local` (the default target) is unaffected |
+
+`scripts/promote-vault-strict.mjs` also uses a baseline template and already ships
+an explicit `--no-baseline` opt-out.
+
+## The public fallback
+
+A repository bootstrapped without the baseline is a normal, supported outcome —
+`skills/bootstrap/public-fallback.md` owns that path. `bootstrap.lock` records
+which source produced the scaffold in its `source:` field:
+
+- `claude-init` — `claude init` ran successfully (Claude Code fast path)
+- `plugin-template` — the plugin's own template was copied (every other case)
+- `projects-baseline` — the private baseline was present and used
+
+The first two are the **public** values. A consumer repo that shows either is
+fully bootstrapped; the baseline adds the operator's private corpus on top, it
+does not gate the scaffold.
+
+## See also
+
+- `docs/owner-config-schema.md` — `owner.yaml` schema, including `paths.baseline-path`
+- `docs/rule-authoring.md` — `paths:` / `globs:` frontmatter
+- `skills/bootstrap/public-fallback.md` — the no-baseline bootstrap path
+- `skills/frontmatter-guard/SKILL.md` — the schema-source resolution table

package/docs/ci-setup.md

@@ -14,62 +14,78 @@ 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:
+> **Armed (2026-09-03, #1175): the hard gate is live.** #531 landed upstream
+> — `infrastructure/projects-baseline` commit `cb9ec97` adds `peer-card`,
+> `board`, and `source-repo` to the canonical schema (the issue's AC named
+> only `peer-card`; the close comment widened scope to all three values
+> already vendored ahead here). That closed the vendored-schema divergence
+> which had blocked activation since 2026-09-02; `skills/vault-sync/
+> validator.mjs` was regenerated and `node scripts/sync-vault-schema.mjs
+> --check` now exits 0. The Project Access Token was re-minted (id 53, see
+> § Activation status below), the masked `SCHEMA_DRIFT_TOKEN` CI variable is
+> set on this project, and `SCHEMA_DRIFT_OPTIONAL` is `"false"` at both
+> sites in `.gitlab-ci.yml` — a missing or expired token now hard-fails the
+> pipeline (exit 4) instead of printing the amber `NOT VERIFIED` line that
+> was the accepted state under the prior (2026-08-28, #1062) decision. Both
+> directions were proven before the flip — see below. Revisit trigger for
+> the token itself: expiry (2027-09-01) or a scope/rotation need — see
+> § Rotation / re-arm sequence.
+
+### Activation status (token re-minted 2026-09-03, id 53)
+
+The Project Access Token was revoked on 2026-09-02 once a control run had
+answered the question it was minted for — an unused credential is a
+liability per SEC-005's secrets-lifecycle discipline. That control run had
+also surfaced the real reason activation was still blocked:
+`skills/vault-sync/validator.mjs`'s `vaultNoteTypeSchema` enum carried
+`peer-card` and `board`, and `vaultFrontmatterSchema` carried
+`source-repo: z.string().optional()`, none of which the canonical
+`infrastructure/projects-baseline` source had yet — the documented
+vendor-ahead state (`scripts/sync-vault-schema.mjs` header, "Vendor-ahead
+state (2026-05-23, #503, I5)"), tracked as upstream-sync-debt in issue #531
+(#503 itself was already closed).
+
+**#531 landed upstream** as commit `cb9ec97`: `vaultNoteTypeSchema` gained
+`peer-card` and `board`; `vaultFrontmatterSchema` gained `source-repo:
+z.string().optional()`. With the canonical source caught up,
+`node scripts/sync-vault-schema.mjs --check` exits 0 — no drift.
+
+**Token, re-minted:**
 
 - **Name:** `session-orchestrator-ci-schema-drift`
 - **Project:** `infrastructure/projects-baseline` (id 52) — the TARGET repo,
   not this one
+- **Token id:** 53
 - **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.
+The masked `SCHEMA_DRIFT_TOKEN` CI variable is set on this project (id 74),
+**not** Protected — same reasoning as Option A step 3 below.
+
+**Proof pipelines, both directions, run before the flip:**
+
+- **GREEN** — pipeline 8358 @ `dc9522dd` (branch
+  `proof/1175-schema-drift-green`): job `schema-drift-check` #84625 ran with
+  the token, cloned the baseline, and printed `RESULT: IN-SYNC (exit 0)`;
+  `pipeline-gate` succeeded.
+- **RED** — pipelines 8355–8357 @ `bca78dae` (branch
+  `proof/1175-schema-drift-red`, a deliberately bogus enum value injected
+  into the vendored copy): `sync-vault-schema.mjs` reported drift, the job
+  failed with exit 1 — outside `allow_failure.exit_codes: [3]` — and
+  `pipeline-gate` never ran.
+
+With both proofs recorded, `SCHEMA_DRIFT_OPTIONAL` is `"false"` at both
+sites in `.gitlab-ci.yml` — `schema-drift-check` and `pipeline-gate`.
+`tests/ci/schema-drift-check.test.mjs` pins the committed value on both
+jobs, so a half-revert or a template refresh flipping one site back to
+`"true"` fails the suite locally, not silently in a pipeline.
+
+**Rotation / re-arm sequence** (token expiry or replacement):
+
+0. **Re-mint the token.** 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
@@ -92,10 +108,12 @@ the canonical enum gains both values.
    `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.
+3. `SCHEMA_DRIFT_OPTIONAL` stays `"false"` at **both** sites —
+   `schema-drift-check` and `pipeline-gate`. A rotation replaces only the
+   credential, never the flag; if the flag was ever reverted for an
+   emergency, flip it back to `"false"` at both sites in one commit —
+   `tests/ci/schema-drift-check.test.mjs` pins the committed value on both
+   jobs, so a half-flip fails the suite locally.
 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
@@ -134,11 +152,12 @@ let alone diff a schema against it. Issue #933.
 
 ```yaml
 variables:
-  SCHEMA_DRIFT_OPTIONAL: "true"
+  SCHEMA_DRIFT_OPTIONAL: "false"
 ```
 
-It is the review-visible declaration that "no token" is *currently* an accepted
-state. The behaviour matrix:
+It is the review-visible declaration that "no token" is *no longer* an
+accepted state — armed 2026-09-03 (#1175, see § Activation status above).
+The behaviour matrix:
 
 | `SCHEMA_DRIFT_TOKEN` | `SCHEMA_DRIFT_OPTIONAL` | Exit | State | Pipeline effect |
 |---|---|---|---|---|
@@ -169,14 +188,41 @@ 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`
+**This is what the armed state looks like.** `SCHEMA_DRIFT_OPTIONAL` is
+`"false"` in `.gitlab-ci.yml` at **both** places: the `schema-drift-check`
 job and `pipeline-gate`. One flag, two enforcement points;
-`tests/ci/schema-drift-check.test.mjs` asserts the mirroring, so a half-flip
-fails the suite locally rather than silently leaving one point advisory. The
-flip is what converts a missing token from a tolerated warning into a hard red,
-and it is the whole point of the flag: the opt-out is a line in a reviewed file,
-not the accidental side effect of an unset CI variable.
+`tests/ci/schema-drift-check.test.mjs` asserts the mirroring AND pins the
+literal `"false"` value on both jobs, so a half-flip — or a full revert —
+fails the suite locally rather than silently leaving one point advisory. A
+missing or expired token now hard-fails the pipeline (exit 4) instead of the
+tolerated amber warning — that is the whole point of the flag: the opt-out is
+a line in a reviewed file, not the accidental side effect of an unset CI
+variable.
+
+**To switch it back to amber temporarily** (a token rotation window, or
+taking the check offline for an emergency): set `SCHEMA_DRIFT_OPTIONAL` to
+`"true"` at **both** sites, in one commit — the same mirrored-pair discipline
+applies in reverse, and the same test catches a half-revert. Re-arm by
+flipping both sites back to `"false"` once the reason for the amber window is
+resolved; see § Rotation / re-arm sequence above for the token side of that
+operation.
+
+**Fork / external-contributor MR caveat.** `.gate-rules` (`.gitlab-ci.yml:74`)
+includes `if: $CI_PIPELINE_SOURCE == "merge_request_event"`, so a merge
+request pipeline runs `schema-drift-check` regardless of who opened it — but
+GitLab does not pass the target project's masked CI/CD variables to a
+pipeline running a **forked** project's code, by design, so that an untrusted
+fork cannot exfiltrate a secret. A fork/contributor MR therefore cannot read
+`SCHEMA_DRIFT_TOKEN` even though the variable is set and unprotected on this
+project, and with `SCHEMA_DRIFT_OPTIONAL: "false"` that reads as a genuinely
+missing token: exit **4** (`MISCONFIGURED`), a hard pipeline failure — not the
+amber `SKIPPED` a same-project branch would get. The accepted mitigation is
+either of: a maintainer re-runs the pipeline from within this project (e.g.
+pushing the same commit to a branch here, where the variable IS available),
+or a maintainer temporarily sets `SCHEMA_DRIFT_OPTIONAL: "true"` on that one
+MR/branch for the duration of review. Do not weaken the committed default in
+`.gitlab-ci.yml` for this — it stays `"false"` at both sites per the armed
+state above.
 
 > **Before you flip it, run ONE pipeline with the token present while
 > `SCHEMA_DRIFT_OPTIONAL` is still `"true"`, and check the job's DURATION.**

package/docs/codex-setup.md

@@ -11,6 +11,8 @@ Guide for using Session Orchestrator with OpenAI Codex through Codex's public pl
 
 ## Installation
 
+**Recommended:** the short remote form (`codex plugin marketplace add <owner>/<repo>`) needs no local clone — see "Short-Form Marketplace Add" below. The steps below are the maintainer/local-clone path used by `scripts/codex-install.mjs`.
+
 Clone the repository, install its runtime dependencies, and run the installer from the plugin root:
 
 ```bash
@@ -30,7 +32,7 @@ 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)
+### Short-Form Marketplace Add (Recommended — Verified 2026-09-04, codex-cli 0.144.4)
 
 `codex plugin marketplace add --help` documents a short remote form:
 
@@ -38,33 +40,22 @@ It operates only through public Codex plugin commands; hook trust remains untouc
 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):
+This is the recommended install path — no local clone needed. Confirmed end-to-end on codex-cli **0.144.4** (2026-09-04), against this repo's unchanged flat layout (`.codex-plugin/plugin.json` + `.claude-plugin/marketplace.json` at repo root, no `plugins/<name>/`):
 
 ```
-$ codex plugin marketplace add Kanevry/session-orchestrator --json
-{
-  "marketplaceName": "kanevry",
-  "installedRoot": ".../.tmp/marketplaces/kanevry",
-  "alreadyAdded": false
-}
+$ codex plugin add session-orchestrator@kanevry --json
+{"pluginId":"session-orchestrator@kanevry","version":"3.22.1+codex.20260825125233","installedPath":"~/.codex/plugins/cache/kanevry/session-orchestrator/<version>","authPolicy":"ON_INSTALL"}
 $ 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.
+`codex plugin list --available --json --marketplace kanevry` confirms `installed: true, enabled: true` for the same layout — no `plugins/<name>/` restructuring was needed.
 
-**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
-```
+**Historical note:** on codex-cli 0.141.0 (2026-08-28), the identical `plugin add` command failed against this same layout with `Error: plugin session-orchestrator was not found in marketplace kanevry`; upgrading to 0.144.4+ resolves it.
 
-`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.
+### Switching Marketplace Sources
 
-**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.
+`codex plugin marketplace add owner/repo` silently **replaces** an already-registered marketplace of the same declared name — the name comes from `marketplace.json`'s `name` field, not the `owner/repo` argument — with a fresh git clone under `~/.codex/.tmp/marketplaces/<name>`. Re-adding the original local path afterward then fails with `marketplace '<name>' is already added from a different source; remove it before adding this source`. To switch sources deliberately, run `codex plugin marketplace remove <name>` first.
 
 ## Understand the Three States
 
@@ -76,7 +67,16 @@ Codex reports three distinct states that must not be conflated:
 
 ## Refresh and Explicit Cache Invalidation
 
-After pulling changes, rerun the installer:
+**If you installed via the short remote form** (`codex plugin marketplace add owner/repo`), the refresh is a marketplace upgrade, not a re-install. Measured 2026-09-06 on codex-cli 0.144.4 — `codex plugin marketplace upgrade --help`: *"Refresh configured Git marketplace snapshots. Omit MARKETPLACE_NAME to upgrade all configured Git marketplaces."*
+
+```bash
+codex plugin marketplace upgrade kanevry   # or omit the name to refresh all
+codex plugin add session-orchestrator@kanevry
+```
+
+`upgrade` re-fetches the Git snapshot; `plugin add` then re-installs the bundle from that refreshed snapshot. There is no local clone in this path, so "re-run the installer" does not apply to it.
+
+**If you installed from a local clone** (the maintainer path), rerun the installer after pulling:
 
 ```bash
 git pull
@@ -126,7 +126,51 @@ The plugin bundle includes the Codex role definitions under `.codex-plugin/agent
 
 The Codex hook command uses Codex's native `${PLUGIN_ROOT}` expansion. The wrapper also exports `CODEX_PLUGIN_ROOT="${PLUGIN_ROOT}"` for shared compatibility code and sets `SO_PLATFORM=codex` so Codex wins when multiple harness variables are present.
 
-Claude-only events (`SessionEnd`, `PostToolUseFailure`, `PostToolBatch`, and `CwdChanged`) are intentionally absent because Codex 0.144.4 does not expose them as supported project events. Claude Edit/Write payload handlers are also absent: Codex emits canonical `apply_patch` data, while those handlers currently expect Claude's Edit/Write payload shape. They will remain unwired until a real `apply_patch` adapter exists; pretending the payloads are compatible would create false enforcement. The same applies to the Bash-payload handlers, including `post-bash-write-verify.mjs` (#942): they gate on Claude's `tool_name === 'Bash'`, which no Codex bridge delivers, so wiring them today would be a silent no-op (the #919-P2 class). These per-event gaps are tracked as documented asymmetries in `scripts/lib/validate/check-hooks-symmetry.mjs` (Check 6, `handlerAsymmetries`) — an UNDOCUMENTED one-platform-only handler now fails validation.
+### What Codex actually exposes (measured 2026-09-06, codex-cli 0.144.4)
+
+The Codex runtime knows **ten** hook events. This is read out of the shipped binary, which embeds one JSON-Schema pair per event, not quoted from release notes:
+
+```
+$ strings -a "$(npm root -g)/@openai/codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin/bin/codex" \
+    | grep '"title": "'
+  "title": "post-tool-use.command.input" / ".output"
+  "title": "permission-request.command.input" / ".output"
+  "title": "post-compact.command.input" / ".output"
+  "title": "pre-tool-use.command.input" / ".output"
+  "title": "pre-compact.command.input" / ".output"
+  "title": "session-start.command.input" / ".output"
+  "title": "subagent-start.command.input" / ".output"
+  "title": "subagent-stop.command.input" / ".output"
+  "title": "user-prompt-submit.command.input" / ".output"
+  "title": "stop.command.input" / ".output"
+```
+
+| Event | 0.144.4 | Wired here |
+|---|---|---|
+| `SessionStart` | yes | yes — banner + `on-session-start.mjs` |
+| `PostToolUse` | yes | yes — `loop-guard.mjs` |
+| `SubagentStop`, `Stop` | yes | yes — `on-stop.mjs` |
+| `PreToolUse`, `SubagentStart` | yes | declared, **empty** (see below) |
+| `UserPromptSubmit`, `PermissionRequest`, `PreCompact`, `PostCompact` | yes | no — this repo has no handler for them |
+| `SessionEnd`, `Interrupt` | **no — event does not exist** | n/a |
+| `PostToolUseFailure`, `PostToolBatch`, `CwdChanged` | no — Claude-only | n/a |
+
+**`SessionEnd` is not "Claude-only", it is absent**, and that distinction is load-bearing: the manifest deserializer rejects unknown keys (`unexpected map key` in the same binary), so adding one does not skip a hook — it can reject the whole manifest and take every already-working hook with it. `Interrupt` arrives in 0.150.0+ and async handlers (`"async": true`) in 0.148+; both are **documented upstream but unverified here**, because this host runs 0.144.4. Re-measure against the shipped binary before widening the set — the machine-readable copy is `CODEX_NATIVE_EVENTS` in `scripts/lib/codex/plugin-contract.mjs`.
+
+For the day `SessionEnd` does land: upstream caps it (and `Interrupt`) at a **1 s default / 3 s maximum** timeout, where every other event gets 600 s. `hooks/on-session-end.mjs` measures ~221 ms median, so it fits — but only just, and only while it stays that fast.
+
+### Why our PreToolUse guards stay unwired — the reason, corrected
+
+Earlier revisions of this page said the handlers were unwired because "no Codex bridge delivers `tool_name`". **That was measuring the wrong thing** — it grepped our own adapter code rather than the Codex payload contract. There is no bridge because none is needed:
+
+- `pre-tool-use.command.input` REQUIRES `tool_name` and `tool_input`, alongside `cwd`, `hook_event_name`, `model`, `permission_mode`, `session_id`, `tool_use_id`, `transcript_path`, `turn_id`.
+- The deny envelope is `hookSpecificOutput.{hookEventName, permissionDecision, permissionDecisionReason}` — byte-identical to what `emitDeny()` already writes, and Codex enforces exactly that shape (its own error text: *"PreToolUse hook returned permissionDecision:deny without a non-empty permissionDecisionReason"*). Codex additionally rejects `permissionDecision: "allow"` and `"ask"`; our allow path is a bare `exit 0` with no stdout, so it is compatible.
+
+The real blocker is the **tool-name vocabulary**. Codex has no `Bash`, `Edit`, `Write` or `MultiEdit` tool — `strings -a <codex> | grep -c '"Bash"'` returns `0`; its tools are `shell`, `exec_command`, `unified_exec`, `apply_patch`, `update_plan`, `view_image`. Every PreToolUse guard in `hooks/` opens with an equality gate on a Claude tool name and returns `emitAllow()` otherwise, so wiring `pre-bash-destructive-guard.mjs` or `enforce-scope.mjs` today produces a hook that runs, matches nothing, and allows everything — **false enforcement, which is worse than a registered gap** (#919-P2 class).
+
+Consequence to state plainly: **PSA-003 (destructive-command guard) and the file-scope guard are behavioural only on Codex today.** The repair is a tool-name map (`shell`/`exec_command`/`unified_exec` → `Bash`) for the Bash guards, plus an `apply_patch` payload adapter for the Edit/Write matchers specifically. Only the second half needs the adapter.
+
+These per-event gaps are tracked as documented asymmetries in `scripts/lib/validate/check-hooks-symmetry.mjs` (Check 6, `handlerAsymmetries`) — an UNDOCUMENTED one-platform-only handler fails validation.
 
 An empty `PreToolUse` or `SubagentStart` array means the event belongs to the validated Codex surface but currently has no payload-compatible handler. It does not mean installation or hook trust failed.