session-orchestrator 4.0.0 → 4.0.1

package/.codex-plugin/skills/test-runner/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: test-runner
+description: 'Use this skill when orchestrating agentic end-to-end tests. Resolves target + profile, dispatches the right driver(s) (playwright for web today, peekaboo for macOS (issue #381)), invokes the ux-evaluator agent (opus, read-only) against driver artifacts, reconciles findings with the open issue tracker via scripts/lib/test-runner/issue-reconcile.mjs, and writes report.md + JSONL roll-up. Wraps upstream tools (no forks). Hard-gates Playwright MCP for browser drive (4× token cost vs CLI per Microsoft''s own benchmark).'
+metadata:
+  user-invocable: 'false'
+  tags: test, orchestrator, e2e, ux
+  model: sonnet
+  model-preference: sonnet
+  model-preference-codex: gpt-5.4
+  model-preference-cursor: claude-sonnet-4-6
+---
+
+<!-- Generated by scripts/generate-codex-skills.mjs; do not edit. -->
+
+# test-runner
+
+Read [`skills/test-runner/SKILL.md`](../../../skills/test-runner/SKILL.md) in full before taking any action, then follow its complete workflow.
+The linked document is authoritative, including its prechecks, argument rules, and stop conditions.
+
+Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/tmux-layout/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: tmux-layout
+description: 'Use this skill when the operator wants a prepared tmux visualization layout for the session''s side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator''s original terminal. Trigger phrases: "tmux layout", "split panes for ci watch", "visualize session side-channels", "show me state-md tail and ci".'
+metadata:
+  model: inherit
+  color: cyan
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<!-- Generated by scripts/generate-codex-skills.mjs; do not edit. -->
+
+# tmux-layout
+
+Read [`skills/tmux-layout/SKILL.md`](../../../skills/tmux-layout/SKILL.md) in full before taking any action, then follow its complete workflow.
+The linked document is authoritative, including its prechecks, argument rules, and stop conditions.
+
+Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/using-orchestrator/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: using-orchestrator
+description: 'Use this skill when dispatching implicit slash-command intent from the user''s first message. Inspects the user''s first message for implicit slash-command intent and dispatches to the highest-confidence matching entry-point skill via the Skill tool. Only active when `auto-skill-dispatch: true` in Session Config. Silent no-op otherwise.'
+metadata:
+  user-invocable: 'false'
+  tags: dispatch, meta, routing, auto-skill
+  model: haiku
+---
+
+<!-- Generated by scripts/generate-codex-skills.mjs; do not edit. -->
+
+# using-orchestrator
+
+Read [`skills/using-orchestrator/SKILL.md`](../../../skills/using-orchestrator/SKILL.md) in full before taking any action, then follow its complete workflow.
+The linked document is authoritative, including its prechecks, argument rules, and stop conditions.
+
+Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/vault-mirror/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: vault-mirror
+description: 'Use when you need to populate the Meta-Vault with machine-generated notes derived from session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when `vault-integration.enabled=true` and `vault-integration.mode != "off"`. Idempotent: re-runs safely; skips hand-authored notes. Triggers: "mirror to vault", "sync session notes to vault", "write learning notes to vault", "vault-mirror failed at session close". <example>Context: session-end is finalizing, vault-integration.mode is "warn". user: "/close" assistant: "Running vault-mirror to write 50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped."</example>'
+metadata:
+  model: haiku
+---
+
+<!-- Generated by scripts/generate-codex-skills.mjs; do not edit. -->
+
+# vault-mirror
+
+Read [`skills/vault-mirror/SKILL.md`](../../../skills/vault-mirror/SKILL.md) in full before taking any action, then follow its complete workflow.
+The linked document is authoritative, including its prechecks, argument rules, and stop conditions.
+
+Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/vault-sync/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: vault-sync
+description: 'Use when you need to validate the Meta-Vault''s Markdown frontmatter and wiki-link integrity before closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes: `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: "vault validation failed at session close", "fix vault frontmatter errors", "check vault wiki-links", "why is session-end blocked by vault-sync". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true, vault-sync.mode="hard". user: "/close" assistant: "vault-sync found 2 frontmatter errors in vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close."</example>'
+metadata:
+  model: haiku
+---
+
+<!-- Generated by scripts/generate-codex-skills.mjs; do not edit. -->
+
+# vault-sync
+
+Read [`skills/vault-sync/SKILL.md`](../../../skills/vault-sync/SKILL.md) in full before taking any action, then follow its complete workflow.
+The linked document is authoritative, including its prechecks, argument rules, and stop conditions.
+
+Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/wave-executor/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: wave-executor
+description: Use this skill when executing the agreed session plan in waves with role-based execution and parallel subagents. Handles inter-wave quality checks, plan adaptation, and progress tracking. Core orchestration engine for feature and deep sessions. Triggered by /go command.
+metadata:
+  user-invocable: 'false'
+  tags: orchestration, execution, agents, waves
+  model: inherit
+  model-preference: opus
+  model-preference-codex: gpt-5.4-mini
+  model-preference-cursor: claude-sonnet-4-6
+---
+
+<!-- Generated by scripts/generate-codex-skills.mjs; do not edit. -->
+
+# wave-executor
+
+Read [`skills/wave-executor/SKILL.md`](../../../skills/wave-executor/SKILL.md) in full before taking any action, then follow its complete workflow.
+The linked document is authoritative, including its prechecks, argument rules, and stop conditions.
+
+Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/write-executable-plan/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: write-executable-plan
+description: Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects "TBD", "TODO", "add error handling", "similar to Task N".
+metadata:
+  model: inherit
+  color: green
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Write
+---
+
+<!-- Generated by scripts/generate-codex-skills.mjs; do not edit. -->
+
+# write-executable-plan
+
+Read [`skills/write-executable-plan/SKILL.md`](../../../skills/write-executable-plan/SKILL.md) in full before taking any action, then follow its complete workflow.
+The linked document is authoritative, including its prechecks, argument rules, and stop conditions.
+
+Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+Regenerate with `node scripts/generate-codex-skills.mjs`.

package/{plugin.json → .cursor-plugin/plugin.json}

@@ -1,7 +1,6 @@
 {
-  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "session-orchestrator",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer"
@@ -23,5 +22,9 @@
     "pi"
   ],
   "skills": "./skills/",
+  "rules": [],
+  "agents": [],
+  "commands": [],
+  "hooks": { "hooks": {} },
   "mcpServers": "./.mcp.json"
 }

package/CHANGELOG.md

@@ -7,6 +7,194 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.1] - 2026-09-07
+
+A PATCH release, two work streams. Codex CLI command entrypoints (closing Epic #1263 and
+sub-issues #1264/#1265/#1266) make every `commands/*.md` and `skills/*/SKILL.md` entry
+discoverable and selectable inside Codex. A 5-wave mechanical-fix session (7 Discovery + 12
+Impl-Core + 5 Impl-Polish + a 4-reviewer/Codex-gpt-6-astra Quality panel with 5 fixers) closes
+16 follow-up issues surfaced by the `4.0.0` 360° audit. The site redesign already staged in
+`[Unreleased]` (session-orchestrator.com relaunch, closing GitLab #1237 and #1080 points
+1/3/5/6/7) folds in unchanged below as `### Changed`.
+
+### Added
+
+- **Codex command workflows are now discoverable and selectable skills — 51 unique generated
+  entries (25 command-backed, 26 skill-backed), closing an 8-command discovery gap (`close`,
+  `go`, `harness-audit`, `portfolio`, `release`, `session`, `templates-ack`, `test`) and
+  resolving 17 same-name command/skill overlaps in the command's favor (`cf0876c3`, Refs
+  #1263/#1264/#1265/#1266).** `scripts/generate-codex-skills.mjs` builds `.codex-plugin/skills/`
+  as the union of `commands/` and `skills/` names; each generated entry links via a
+  package-relative path to its canonical `commands/<name>.md` or `skills/<name>/SKILL.md`, so it
+  resolves from the installed bundle, not only the source checkout. Command adapters read the
+  full canonical command before resolving any internal skill call directly, avoiding recursive
+  dispatch back to the public entry. Trailing prompt text passes through as `$ARGUMENTS` — no
+  shell expansion, no global substitution.
+- **`disable-model-invocation: true` now maps to `agents/openai.yaml`
+  `policy.allow_implicit_invocation: false`, so `go`, `close`, `bootstrap`, `brainstorm`, `plan`,
+  and `release` keep requiring explicit selection under Codex too (`cf0876c3`, Refs
+  #1263/#1264).** All other commands retain their source setting.
+- **`scripts/lib/validate/check-codex-skills.mjs` independently re-derives the expected Codex
+  surface from the emitted artifacts, not from the generator's own expected text, and is wired
+  into `scripts/validate-plugin.mjs` (`cf0876c3`, Refs #1263/#1265).** It checks source-name
+  coverage, manifest registration, frontmatter/metadata types, invocation-policy booleans, and
+  canonical-link targets; its CLI also re-runs `generate-codex-skills.mjs --check`.
+- **Native Codex `commands: []` now suppresses the installer's automatic `commands/` migration
+  (`ae16dfcb`, Refs #1263/#1265/#1266).** Without it, a real install on Codex 0.153.3 added nine
+  `source-command-*` aliases (including `source-command-close`) beside the generated entries,
+  with no invocation policy attached. `scripts/lib/codex/plugin-contract.mjs` now requires
+  `commands` to be an empty array when present.
+- **The root `plugin.json` (added in 4.0.0) is replaced by `.cursor-plugin/plugin.json`,
+  Cursor's native manifest format (`cf0876c3`, Refs #1263/#1264).** Read-only `plugin/read`
+  probes on Codex CLI 0.153.3 and desktop 0.153.4 found the root Agent Plugins manifest
+  overrides Codex's own declared skill path (fixing it to `./skills`) and root version —
+  silently defeating the generated `.codex-plugin/skills/` surface even though every adapter
+  unit test passed. `package.json` `files[]` and `scripts/release.mjs`'s version-surface table
+  are updated accordingly (`.cursor-plugin/` added, root `plugin.json` removed).
+- **Installed acceptance verified end to end (`3862505c`, `a244b870`, Refs #1263/#1266).**
+  Public `codex plugin add session-orchestrator@local --json` produced enabled version
+  `4.0.0+codex.20260907174300`; Codex desktop 0.153.4 returns exactly 51 unique enabled skills
+  via both `plugin/read` and `skills/list`, no migration aliases, and all six explicit-only
+  commands retain `allow_implicit_invocation: false`. Visible-picker selection is **not yet
+  confirmed** — Computer Use cannot drive the Codex desktop app — and remains open under #1266
+  (see Notes).
+- **Documented the Codex command entrypoints across `README.md`, `docs/codex-setup.md`,
+  `docs/components.md`, `docs/migration-v4.md`, and `docs/instruction-delivery.md` (`cf0876c3`,
+  Refs #1263/#1266).**
+
+### Changed
+
+- Public website redesigned (session-orchestrator.com): light-first design in the family look of the author's personal site (Bricolage Grotesque, Source Sans 3, IBM Plex Mono, all self-hosted; Archivo removed).
+- Two reading layers on the landing page: a plain-words layer for non-developers above a developer layer with install commands, the wave schedule, and the measured-claims table.
+- German landing page at `/de` with `hreflang` alternates (`en`, `de`, `x-default`), same section ids and census spans as the English page.
+- three.js hero (vendored `three@0.185.1`, two files: `three.module.min.js` + `three.core.min.js`), loaded via a lazy dynamic import skipped under `prefers-reduced-motion`, which renders the static `hero-fallback.svg` instead.
+- Six AI-generated illustrations (gpt-image-2), each captioned "AI-generated illustration (gpt-image-2)" in EN/DE.
+- FAQ section with `FAQPage` JSON-LD on both the EN and DE landing pages.
+- Author block linking to the personal site (root + `utm_source=session-orchestrator`), closing GitLab #1237.
+- `scripts/site-numbers.mjs` gained `npm-downloads-30d` and `github-stars`: fetched only under `--write` (5 s timeout, snapshot kept on failure), answered from the `site/_census.json` snapshot under `--check`; `SO_SITE_NUMBERS_OFFLINE=1` skips both metrics. Marker-bounded census blocks (`<!-- census:start -->` / `<!-- census:end -->`) added to `site/llms.txt` and `site/llms-full.txt` (GitLab #1080, points 1/3/5/6/7).
+- New tests: `tests/site/voice-gate.test.mjs` (em-dash, superlative, "we", emoji gate) and `tests/site/structure.test.mjs` (EN/DE parity, hreflang, asset presence, AI-illustration disclosure).
+- `vercel.json` cache headers for `/assets`, `/img`, `/vendor`; ESLint now ignores `site/vendor/**` (vendored three.js) and declares browser globals for `site/assets/**`.
+
+### Fixed
+
+- **`CHANGELOG.md`'s `[4.0.0]` entry and `docs/migration-v4.md` corrected two overclaims found
+  by post-tag review (`a4315993`).** `package.json` `files[]` admits the whole
+  `.orchestrator/policy/` directory, not a curated file list — the packlist test, not npm, is
+  what pins the shipped set to the tracked set. `pi-install.mjs --settings-only` actually
+  **rewrites** an existing Pi settings file (upsert), unlike `cursor-install.mjs`, which skips
+  existing destinations. Note for readers of the published `v4.0.0` tag: this correction lands
+  after that tag, so the tagged CHANGELOG text still carries the two overclaims — only `main`
+  and `4.0.1` have the corrected wording.
+- **`tests/scripts/site-numbers.test.mjs` fixtures run offline
+  (`SO_SITE_NUMBERS_OFFLINE=1`) (`4ea84d3e`).** Without it, the census-block tests fetched live
+  npm download counts and went red whenever the live count moved past the fixture snapshot
+  (measured in CI 2026-09-07: 1237 vs. 1165).
+- **`tests/lib/validate/check-auq-clarity.test.mjs` gets a 120 s hook timeout for its
+  `validate-plugin.mjs` spawn in `beforeAll` (`19b66e6e`).** GitLab pipelines 8790 and 8791
+  (2026-09-07) failed only here: the shared runner exceeded vitest's default 30 s `hookTimeout`
+  running the full validator (~12 s locally). Aligns with the sibling
+  `tests/scripts/validate-plugin.test.mjs`.
+
+#### 4.0.1 — mechanical-fix session (16 follow-up issues from the 4.0.0 audit)
+
+- **Reconcile-idempotency now has a contract and a regression test, not just a claim (#1242).**
+  Discovery found the acceptance criterion already held — tracked Provenance markers already
+  dedupe re-runs, a fresh-clone simulation regenerated 0 of 30 keys — so the delivered fix is a
+  contract doc (the scan is authoritative, the sidecar is a cache) plus a mutation-proven
+  fresh-clone consolidated-shape test, not new production code.
+- **`check-unwired-features.mjs`'s Category S4 no longer conflates "genuinely unreachable" with
+  "reachable only via coordinator dispatch" (#1239).** Discovery measured 52 raw S4 findings, 46
+  of them (88.5%) false positives — modules invoked only through a coordinator `Task`/skill
+  dispatch, never a static import. S4 now splits into 5 truly-unreachable findings and 46
+  coordinator-invoked findings reported as advisory rather than blocking, with `skills/`
+  recognised as a first-class reachability edge source; a same-wave fix-pass tightened the
+  coordinator-invoked match to token boundaries (a Codex-repro case where a bare substring match
+  over-matched) and dropped the advisory line's WARN severity per `host-resources.md` HR-101.
+  The check's exit code is unchanged.
+- **`inspectConfidentialNames()` is a new function; `loadConfidentialNames()` keeps its 4.0.0
+  `string[] | null` public contract (#1250).** This session's own Wave-2 refactor had changed
+  `loadConfidentialNames()`'s return shape to an object — a semver-breaking change the Wave-4
+  review panel and Codex gpt-6-astra both caught before the cut, not after. The fix reinstates
+  `loadConfidentialNames()` as a thin wrapper over the richer `inspectConfidentialNames()`. A new
+  `'all-dropped'` status (every entry in the confidential-names file invalid) now fails closed
+  instead of silently returning an empty list, and the loader's WARN on a missing/malformed file
+  is redacted to the file's basename — the same fix-pass had regressed the full path into
+  stderr, reopening the class of leak `check-owner-leakage.mjs` exists to prevent; found and
+  fixed inside this session's own review cycle, before release.
+- **`loadHostPaths()` no longer loads `owner.yaml` twice (#1251).** Health-check state now
+  passes through from the caller's single load instead of triggering a second read.
+- **Four small fixes under #1262: an env-configured standalone confidential-names copy now fails
+  closed instead of passing through silently (point 2); `docs/migration-v4.md` gained rollback
+  prose (point 3); `OPTIONAL_OBJECT_SECTIONS` is now an exported constant with a parity test,
+  replacing a duplicated mirror list (point 4); a stale comment on the full quality-gate path was
+  corrected (point 5).** Point 1 (a Codex-surface regeneration check) was dropped — Discovery
+  measured the existing set-equality pack test as the stronger pin, so no code change was needed.
+- **`VALID_SESSION_PROFILES` moved to a single source of truth in
+  `scripts/lib/session-schema/constants.mjs`, with `SHARED_LIST_BOUNDS`/`INGEST_LIST_BOUNDS`
+  parity enforced (#1252).** A re-export shim stayed at the old location for compatibility,
+  pinned by an identity test.
+- **Four git-fixture files and the two largest `rmSync` call sites now route through a shared
+  tmp-fixture helper instead of ad hoc cleanup; `listRepoFiles()` now swallows only
+  `ENOENT`/`ENOTDIR`, not every error (#1253).** This is a partial pass, not a sweep: 501 bare
+  **recursive** `rmSync` call sites remain unrouted (574 claimed → 524 measured → 501 after this
+  session) and are carried forward as #1268 with a Revisit-Trigger, not silently left
+  unmentioned.
+- **`check-skill-links.mjs` now scans `docs/` (previously skill/command files only), takes a
+  `dirs` option, and right-anchors its GitLab `-/issues` carve-out (#1258).** The carve-out was
+  previously unanchored and could match a URL fragment elsewhere in a line. Two dangling
+  documentation links were repaired, both pointing at content that had moved to the vault
+  archive.
+- **An unknown or valueless CLI flag on `generate-hook-import-set.mjs` now exits 2 with a usage
+  message instead of triggering the write (#1249).** `--out --check` no longer writes a file
+  literally named `--check` — the argv loop had read `--check` as `--out`'s value.
+- **A platform allowlist check now uses `Object.hasOwn()` (#1256).** Discovery's companion claim
+  in the same issue — that a related export was dead code — was checked against real call sites
+  and refuted; that half closes as "working as designed".
+- **Desktop notifications now carry a platform-aware label (#1254).** `detectPlatform()` drives
+  the OSC notify text so a Codex CLI session's notification reads differently from a Claude Code
+  session's.
+- **A new session-start probe, `telemetry-flush-health`, surfaces telemetry-sender problems that
+  were previously silent (#1255).** It tail-reads the last `orchestrator.telemetry.flush` event:
+  a `sandbox:*` refusal reason now renders as a WARN banner instead of nothing, and an
+  unreadable ledger renders explicitly as `ledger-unreadable` rather than falling through to
+  silence. The reason string is bounded to 120 characters with control characters stripped.
+- **The tests:src ratio census now resolves calls made through `fixtureGit`/`fixtureGitSpawn`
+  wrappers, including the `NO_BACKGROUND_WRITER` spread pattern, and strips comments before
+  reading a wrapped call's second positional argument (#1259).** Applicable call sites rose from
+  17 to 200 (measured 2026-09-07 on the release tree with
+  `node scripts/lib/validate/check-test-git-config-target.mjs .`) — the tokenizer previously
+  couldn't see wrapper calls at all — and the reporting floor was raised from 20 to 100 to match.
+- **Four tests now pin Node 24's `err.url` behaviour using a real spawned `node` child process,
+  not an in-process `vitest` failure (#1260).** An in-process `ERR_MODULE_NOT_FOUND` never
+  carries a `url` field, so the previous test could not observe the behaviour it claimed to pin.
+  The standalone single-file copy path is confirmed inert / fails closed for the same case.
+- **A Discovery premise was refuted before any code changed (#1257).** `vault-sync`'s
+  sub-package dependency pins looked accidental; they are intentional, because CI already
+  installs the sub-package separately. Documented in `skills/vault-sync/SKILL.md` §
+  Dependencies instead of "fixed".
+- **`release.mjs`'s drift sweep now judges version literals as whole tokens and skips comment
+  prose and lockfile dependency rows; its history allowlist admits nine files whose only literal
+  is prose history of the 4.0.0 major (`CLAUDE.md`, its generated twin `AGENTS.md`,
+  `CONTRIBUTING.md`, `NOTICE`, `.husky/pre-push`, `site/llms-full.txt`,
+  `skills/architecture/references/domain-model.md`, `skills/autopilot/SKILL.md`,
+  `templates/_shared/journey-manifest.md`).** Measured 2026-09-07 mid-release: `4.0.0` matched
+  inside `>=24.0.0` in package.json, 72 third-party rows in package-lock.json, and `// pre-4.0.0`
+  comments — none a version surface. The sweep's detail line now carries the total hit count
+  instead of truncating at five, which is how the last four files had stayed hidden.
+
+### Notes
+
+- **4.0.1 is a PATCH: no public export changed shape.** `loadConfidentialNames()` keeps its
+  `string[] | null` contract; the new exports (`inspectConfidentialNames`, `SHARED_LIST_BOUNDS`,
+  `INGEST_LIST_BOUNDS`, `OPTIONAL_OBJECT_SECTIONS`, `stripComments`, `wrapperHasCwd`,
+  `checkTelemetryFlushHealth`, `renderBanner`, `TAIL_BYTES`, and `VALID_SESSION_PROFILES` in
+  `constants.mjs`) are additive. Reviewed by a 4-reviewer panel plus Codex gpt-6-astra on the
+  packed tarball; 2 P1 + 3 P2 Codex findings were fixed before the cut, not after.
+- **Visible Codex picker confirmation (#1266) remains an operator step; not a release gate.**
+- **The telemetry ingest server was redeployed for this release (#1261).** Operational step, not
+  a code change — rollback tag `telemetry-ingest:1.0.0-pre401` kept in place; health confirmed
+  post-restart.
+
 ## [4.0.0] - 2026-09-06
 
 > **A MAJOR, because public surfaces are REMOVED** (see *Removed (BREAKING)* below).
@@ -978,7 +1166,8 @@ manual cleanup steps: [`docs/migration-v4.md`](docs/migration-v4.md).
   `npm pack --dry-run`, not a mock). The release leakage gate's `.orchestrator/`
   exclusion is narrowed to carve THIS directory back IN (`scripts/release.mjs`
   around line 319) — the operator's own `metrics/`, `debug/` artefacts and live
-  `*.lock` files stay excluded; only the tracked policy floor ships. **The
+  `*.lock` files stay excluded. `files[]` admits the directory, not a file list — what
+  keeps the shipped set equal to the TRACKED policy set is the packlist test below, not npm. **The
   Wave-4 review panel found this test asserted only a FLOOR (≥ 6 files) while
   `package.json`'s `files[]` admits the WHOLE `.orchestrator/policy/` directory
   and the carve-out above matched the path anywhere in the string, not just at

package/README.md

@@ -1,13 +1,13 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-4.0.1-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-vitest-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
 Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on **Claude Code, Codex CLI, Cursor IDE, and [Pi](docs/pi-setup.md)**, as a community plugin (MIT, community-maintained) for solo devs and small teams.
 
-The same skills and commands are available on all four harnesses; **enforcement depth differs** — scope enforcement is full on Claude Code, bridged on Cursor and Pi, and currently unavailable on Codex CLI (see [Platform support](#platform-support)).
+The same workflows are available on all four harnesses; Codex exposes commands as selectable skills. **Enforcement depth differs** — scope enforcement is full on Claude Code, bridged on Cursor and Pi, and currently unavailable on Codex CLI (see [Platform support](#platform-support)).
 
 ## Requirements
 
@@ -46,7 +46,7 @@ Setup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md)
 /plugin update session-orchestrator@kanevry     # Claude Code
 ```
 
-Restart the harness afterwards, and re-run `npm install` in the plugin directory when the release adds dependencies. On Codex CLI, Cursor, and Pi the upgrade is `git pull` in your clone followed by the same install script you originally ran.
+Restart the harness afterwards, and re-run `npm install` in the plugin directory when the release adds dependencies. On Cursor and Pi the upgrade is `git pull` in your clone followed by the same install script you originally ran. For Codex, follow the [refresh instructions](docs/codex-setup.md#refresh-and-explicit-cache-invalidation) for your marketplace source, then reload the skill picker or restart Codex.
 
 Session-start tells you when the running copy is behind: `scripts/lib/plugin-update-banner.mjs` compares the version of the code **that is actually loaded** against the published npm version and warns in the session-start banner (minor or major; patch-only updates stay silent). It fails silent — offline, a non-2xx response, or a malformed answer produces *no statement*, never a false "up to date".
 
@@ -67,6 +67,8 @@ Deleting `.orchestrator/metrics/` deletes your session history. Nothing is sent
 
 ## Quick Start
 
+In Codex, select the corresponding **Session Orchestrator** skill in the picker or use `$session-orchestrator:<command>`; the slash commands below name the shared workflows. For example, bootstrap with `$session-orchestrator:bootstrap`. See [Codex usage](docs/codex-setup.md#usage).
+
 **1. Bootstrap the repo once.** Run `/bootstrap` in your project — it scaffolds the minimum structure and writes `.orchestrator/bootstrap.lock`, which session-start requires before `/session` will run.
 
 **2. Declare a Session Config.** Add a `## Session Config` section to your project's `CLAUDE.md` (Claude Code, Cursor IDE) or `AGENTS.md` (Codex CLI, Pi) — see [instruction-file-resolution](skills/_shared/instruction-file-resolution.md) for which file each platform reads. The smallest valid config is seven fields:
@@ -105,7 +107,15 @@ Everything else is opt-in. Full template: [`docs/session-config-template.md`](do
 /close              # verify every item, commit cleanly, file carryover issues for the rest
 ```
 
-That is the whole loop. `/plan` and `/evolve` extend it, but you can start with just these three.
+In Codex, invoke the same loop through the generated command skills:
+
+```text
+$session-orchestrator:session feature
+$session-orchestrator:go
+$session-orchestrator:close
+```
+
+These entries preserve each command's full workflow and prechecks. Codex's native `/goal` is a separate feature. `/plan` and `/evolve` extend the loop, but you can start with just these three.
 
 ## Lifecycle and waves
 
@@ -161,16 +171,16 @@ The system is markdown-driven config plus a thin Node runtime — skills, comman
 
 ## What you get
 
-Counts measured on 2026-09-06 with the command in brackets:
+Counts measured on 2026-09-07 with the command in brackets:
 
 - **43 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, and audits (`ls -d skills/*/ | grep -v _shared | wc -l`)
 - **25 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …) (`ls commands/*.md | wc -l`)
 - **14 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …) (`ls agents/*.md | wc -l`)
 - **27 hook files across 10 event types**, enforcing scope, blocking destructive commands, gating templates-first, and capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged elsewhere ([Platform support](#platform-support)) (`ls hooks/*.mjs | wc -l`)
 - **26 always-on rule files** and **18 ADRs** carrying the reasoning behind the mechanisms (`ls .claude/rules/*.md | wc -l`, `ls docs/adr/*.md | wc -l`)
-- **661 vitest test files** run on every commit — 13,962 static `it()`/`test()` definitions at that measurement, and the runtime total is higher because of parameterised blocks ([methodology](docs/telemetry/telemetry-claims.md)) (`find tests -name '*.test.mjs' | wc -l`)
+- **667 vitest test files** run on every commit — 13,827 static `it()`/`test()` definitions at that measurement, and the runtime total is higher because of parameterised blocks ([methodology](docs/telemetry/telemetry-claims.md)) (`find tests -name '*.test.mjs' | wc -l`)
 
-**Portable across harnesses by construction.** The repo ships a root `AGENTS.md` generated byte-identical from `CLAUDE.md`, a root `plugin.json` following the [agent-plugins.org](https://agent-plugins.org) 1.0.0 schema, and a `.agents/skills/<name>/SKILL.md` mirror of all 43 skills carrying spec-legal frontmatter plus a pointer body. All three are generated by `scripts/generate-agents-skills.mjs` and drift-checked in `scripts/validate-plugin.mjs` — never hand-edited.
+**Portable across harnesses by construction.** `scripts/generate-agents-skills.mjs` generates root `AGENTS.md` byte-identical from `CLAUDE.md` and the `.agents/skills/<name>/SKILL.md` mirrors, with spec-legal frontmatter and pointers to canonical instructions. `scripts/generate-codex-skills.mjs` generates the Codex command entrypoints. Plugin validation checks both surfaces. Separate manifests under `.claude-plugin/`, `.codex-plugin/` and `.cursor-plugin/` register each harness's components; see [Codex manifest compatibility](docs/codex-setup.md#manifest-compatibility).
 
 Full component inventory: [`docs/components.md`](docs/components.md). Version history and per-release detail: [CHANGELOG.md](CHANGELOG.md).
 
@@ -186,17 +196,15 @@ Full component inventory: [`docs/components.md`](docs/components.md). Version hi
 
 How this compares to other orchestrators — with the parts that are measured and the parts that are not: [`docs/components.md` § Comparisons](docs/components.md#comparisons).
 
-## Recent highlights (v4.0.0)
+## Recent highlights (v4.0.1)
 
-v4.0.0 is the first release that REMOVES public surfaces, so read [docs/migration-v4.md](docs/migration-v4.md) before upgrading. Highlights of the v4.0.0 line: less surface, an instruction layer that loads on demand, and three instruments that were reporting numbers nobody could reproduce:
+4.0.1 is a patch on top of 4.0.0 — if you're upgrading from before 4.0, read [docs/migration-v4.md](docs/migration-v4.md) first; nothing below removes anything further. Highlights of the v4.0.1 line: Codex command entrypoints, a redesigned public site, and a review-hardened owner-privacy scanner — plus the sixteen follow-ups the 4.0.0 review left open:
 
-- **Five skills, three commands and eight top-level scripts are gone.** Removal followed a measured two-signal rule — 0 telemetry ∧ 0 fleet invocation over 90 days ∧ no runtime consumer — never a judgement call. Prose-invoked skills, which register 0 by construction, were exempt. `skills/domain-model/` was merged into `skills/architecture/` rather than dropped.
-- **`.claude/rules/` goes 61 → 26 files.** Forty-three machine-generated learning files were consolidated into eight thematic ones, each keeping its provenance markers so the reconcile engine still dedupes on them.
-- **The three largest instruction files are split, not shortened.** `session-start`, `session-end` and the wave loop keep every phase; the bodies move into per-phase files under `references/`, and the top-level file becomes an index that is heading-complete against the original. Nothing was summarised away.
-- **`ultradeep` is a profile over `deep`, not a fourth session type.** Seven waves with a blocking synthesis gate and a read-only review panel. Downstream tooling still sees `deep`, which is why it costs about eight touchpoints instead of forty-eight.
-- **A session-start banner now says when the plugin you are RUNNING is behind the one published** (minor or major; patch-only updates stay silent). This host had been running a copy five minors old for four weeks with no warning, because nothing anywhere compared installed against available.
-- **Two instruments were corrected rather than tuned.** Telemetry attributed the operator's own second machine to the external fleet, and the abandoned-session rate was an artefact of backfilled records. Both now report what they measure.
-- **A root `AGENTS.md`, a root `plugin.json` and a portable `.agents/skills/` mirror.** The repo now speaks the cross-harness instruction conventions it documents, generated and validated rather than hand-maintained.
+- **4.0.0 removed public surfaces and split the largest instruction files.** Five skills, three commands and eight top-level scripts were dropped on a measured two-signal rule (0 telemetry ∧ 0 fleet invocation over 90 days ∧ no runtime consumer, never a judgement call); `.claude/rules/` went 61 → 26 files; `session-start`, `session-end` and the wave loop keep every phase, with bodies moved into per-phase `references/` files. Full detail and upgrade steps: [docs/migration-v4.md](docs/migration-v4.md).
+- **Codex command workflows are now selectable skills.** `scripts/generate-codex-skills.mjs` generates 51 entries (25 command-backed, 26 skill-backed); `go`, `close`, and 6 others that were previously absent from the skill surface (`harness-audit`, `portfolio`, `release`, `session`, `templates-ack`, `test`) are now discoverable and invocable as `$session-orchestrator:<name>`. Native `commands: []` stops the installer from separately aliasing the source commands into policy-less duplicates. The intercepting standard root manifest moved to [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json) so it no longer shadows Codex's own manifest resolution (Refs #1263).
+- **Public website redesigned**, including a German `/de` landing page.
+- **Review-driven hardening.** The owner-privacy scanner (CP11) now fails CLOSED on a corrupted or env-configured-but-unresolvable confidential-names list instead of silently degrading to allow, and no longer prints the names-file path into logs; `check-unwired-features` splits 46 coordinator-invoked modules out of its actionable finding set (52 → 5 unreachable), so the report names what an operator can actually act on; a new session-start probe (`telemetry-flush-health`) surfaces when the sandbox refused a telemetry flush instead of that failure staying silent.
+- **Sixteen follow-ups from the 4.0.0 review closed, and the patch itself was reviewed before the cut.** A four-reviewer panel plus an external Codex gpt-6-astra pass over the packed npm tarball found two P1 and three P2 defects in this session's own changes — a names-file path printed into the scanner's failing output, a deep-import contract change, a flag swallowed as a value, a substring match that hid a real finding, a comment that counted as a target — all fixed before publishing. The residual list lives in GitLab #1268–#1273.
 
 Full list, with the evidence for each claim: [CHANGELOG.md](CHANGELOG.md).
 
@@ -204,7 +212,7 @@ Full list, with the evidence for each claim: [CHANGELOG.md](CHANGELOG.md).
 
 | Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
 |---|---|---|---|---|
-| All 25 commands | Native slash commands | Native plugin commands | Native `.cursor/commands` slash commands | Prompt templates |
+| All 25 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | 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 | `preToolUse` + `beforeShellExecution` via cursor-hook-bridge; `afterFileEdit` post-hoc | `tool_call` bridge |
@@ -283,7 +291,7 @@ This plugin is a methodology turned into code. The reasoning behind it — why e
 
 ## Links
 
-[Homepage](https://session-orchestrator.com) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy) · [npm](https://www.npmjs.com/package/session-orchestrator)
+[Homepage](https://session-orchestrator.com) (also at [/de](https://session-orchestrator.com/de) in German, with a plain-words layer above the developer detail) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy) · [npm](https://www.npmjs.com/package/session-orchestrator)
 
 ## License
 

package/docs/codex-setup.md

@@ -67,7 +67,7 @@ Codex reports three distinct states that must not be conflated:
 
 ## Refresh and Explicit Cache Invalidation
 
-**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."*
+**If you installed via the short remote form** (`codex plugin marketplace add owner/repo`), refresh the Git marketplace snapshot before updating the installed plugin. 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
@@ -86,6 +86,8 @@ node scripts/codex-install.mjs
 
 Every installer run executes `codex plugin marketplace add` and `codex plugin add`, even when the marketplace is already configured. The repeated `plugin add` refreshes Codex's installed bundle from the current clone instead of treating installation as a one-time copy.
 
+After either refresh path, confirm the installed version with `codex plugin list --available --json` and start a fresh task. Reopen the skill picker and search for `go` or `close`; if the updated entries are still missing, fully restart Codex. Editing the source clone or regenerating skills alone does not refresh the installed bundle.
+
 The tracked Codex manifest uses a version such as `3.14.0+codex.20260717175716`. The base must match `package.json`; the `+codex.<YYYYMMDDHHmmss>` UTC suffix is the repository's explicit invalidation marker. When a shipped bundle needs a new cache identity, maintainers commit a new timestamp in `.codex-plugin/plugin.json`. The installer validates that committed value and never mutates the tracked manifest.
 
 ## Configuration
@@ -176,14 +178,44 @@ An empty `PreToolUse` or `SubagentStart` array means the event belongs to the va
 
 ## Usage
 
-After installation and hook review, start a fresh task. Session Orchestrator exposes the shared skill surface, including:
+After installation or refresh, start a fresh task. In the desktop composer, open the skill picker, search for `go` or `close`, and select the matching **Session Orchestrator** entry. In Codex CLI or the IDE extension, use `/skills` or mention the namespaced skill directly in your prompt. [OpenAI skill invocation](https://learn.chatgpt.com/docs/build-skills)
+
+```text
+$session-orchestrator:session feature   # start a session (housekeeping, feature or deep)
+$session-orchestrator:go                # execute the agreed plan
+$session-orchestrator:close             # verify and close the session
+$session-orchestrator:plan feature      # plan a project or feature (new, feature or retro)
+$session-orchestrator:discovery         # run quality probes; optionally add a scope
+$session-orchestrator:evolve analyze    # manage learnings (analyze, review or list)
+```
+
+These are skill invocations in the Codex prompt, not shell commands. Invoking `go` reads the full canonical `commands/go.md`, including its Express Path and prechecks; invoking `close` reads `commands/close.md`, including its state and ledger checks before the session-end workflow. Codex's native `/goal` is a separate feature. Typing `/go` or `/close` alone is not a portable invocation contract; select the skill or use its explicit namespaced form.
+
+### Manifest Compatibility
+
+The plugin uses `.codex-plugin/plugin.json` for Codex and `.cursor-plugin/plugin.json` for Cursor. It does not ship a root Agent Plugins `plugin.json`: on Codex CLI 0.153.3 and desktop runtime 0.153.4, that standard manifest takes precedence, fixes skill discovery to conventional `skills/`, and supplies the root version. The Codex overlay can supply hooks, apps and interface metadata, but cannot override that skill path or version. This was verified with read-only `plugin/read` probes on 2026-09-07. [Codex manifest parser](https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/agent_plugin_manifest.rs)
+
+Moving the former root metadata to the native Cursor manifest lets Codex load its generated entrypoints and cache suffix. Cursor keeps the declared skills and MCP paths; the manifest explicitly disables discovery of extra rules, agents, commands and hooks. Its existing installer supplies the Cursor command and hook adapters. This follows the [Cursor manifest reference](https://cursor.com/docs/reference/plugins); native Cursor loading has not been runtime-tested as part of this change.
+
+### Generated Command Skills
+
+The Codex manifest registers one generated skill tree at `.codex-plugin/skills/`. It contains the union of names from `commands/` and `skills/`: when both contain the same name, the command takes precedence, giving the plugin one public entry for that name. OpenAI recommends converting reusable Markdown commands into skills. [OpenAI conversion guidance](https://developers.openai.com/plugins/guides/submit-claude-plugin)
 
-- `/session [housekeeping|feature|deep]` — start a session
-- `/go` — execute the agreed plan
-- `/close` — end the session with verification
-- `/plan [new|feature|retro]` — plan a project or feature
-- `/discovery [scope]` — run quality probes
-- `/evolve [analyze|review|list]` — manage learnings
+The manifest also declares top-level `"commands": []` to suppress the installer's automatic command migration. When that field was omitted, a public install with Codex 0.153.3 added nine `source-command-*` aliases alongside the generated entries, including `source-command-close`, without preserving invocation policy. The empty array selects no command sources; it does not register native slash commands. The generated skill tree remains the public invocation surface. [Codex 0.153.3 command-path parser](https://github.com/openai/codex/blob/rust-v0.153.3/codex-rs/core-plugins/src/manifest.rs#L203), [installer migration](https://github.com/openai/codex/blob/rust-v0.153.3/codex-rs/core-plugins/src/command_migration/plugin.rs)
+
+The generated files are adapters, not separate workflow bodies. Each links to its canonical command or skill using a package-relative path, so it also works from the installed bundle. Command adapters read the full command first and resolve internal skill calls directly to `skills/<name>/SKILL.md`, avoiding a recursive call to the public entry. Trailing prompt text supplies the command's `$ARGUMENTS` as data; the adapter does not shell-expand arguments or globally substitute them into command documents.
+
+Commands declaring `disable-model-invocation: true`, including `go` and `close`, receive `policy.allow_implicit_invocation: false` in `agents/openai.yaml`. This preserves explicit selection while disabling implicit skill invocation. Other commands retain their source setting. [OpenAI invocation policy](https://learn.chatgpt.com/docs/build-skills#optional-metadata)
+
+Maintainers edit the canonical files, then regenerate and check the Codex surface from the plugin root:
+
+```bash
+node scripts/generate-codex-skills.mjs
+node scripts/generate-codex-skills.mjs --check
+node scripts/validate-plugin.mjs
+```
+
+`--check` reports stale generated files without writing them. Plugin validation also checks manifest wiring, command coverage, canonical targets and invocation policy. Commit the generated output with its source change, then follow [Refresh and Explicit Cache Invalidation](#refresh-and-explicit-cache-invalidation) to update the installed copy.
 
 ## Key Differences from Claude Code
 
@@ -203,6 +235,8 @@ Both platforms share session history and learnings through `.orchestrator/metric
 
 ## Platform Limitations
 
+Repository skills under `.agents/skills/` and installed-plugin skills can both appear in the picker. The generated union prevents duplicate names within the plugin; it does not remove pre-existing entries from other discovery scopes. Select the installed command entry whose path is under `.codex-plugin/skills/` when a repository also offers a same-named internal skill.
+
 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.
 
 Hook enforcement is limited to the validated payload-compatible Codex subset described above. In particular, the absence of Claude-only events and Edit/Write handlers is deliberate rather than an installation workaround.
@@ -219,6 +253,7 @@ codex plugin list --available --json
 - **The target is missing, disabled, duplicated, or at the wrong version:** run `codex plugin marketplace list --json`, remove the exact target with `codex plugin remove session-orchestrator@kanevry` when present, and rerun `node scripts/codex-install.mjs` to reinstall and verify it.
 - **A `session-orchestrator@openai-curated` or `session-orchestrator@local` installation remains:** these are the only allowlisted legacy IDs. Remove the exact stale ID with `codex plugin remove session-orchestrator@openai-curated` or `codex plugin remove session-orchestrator@local`; unrelated plugins remain untouched.
 - **The `kanevry` marketplace points at another source:** confirm the conflict with `codex plugin marketplace list --json`, run `codex plugin marketplace remove kanevry`, then rerun the installer from the intended clone so it performs the public marketplace add and plugin add lifecycle.
+- **`go` or `close` is missing from the skill picker:** follow [the refresh steps](#refresh-and-explicit-cache-invalidation), verify the installed version, and restart Codex if reopening the picker does not load the new entries. Use the namespaced skill form from [Usage](#usage), rather than selecting the unrelated native Goal command.
 - **Plugin is installed and enabled but hooks do not fire:** start a fresh task or fully restart Codex, run `/hooks`, and review the trust state. Installation does not imply hook approval.
 - **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.
@@ -247,4 +282,3 @@ codex mcp list | grep session-orchestrator   # the launch string should mention
 ```
 
 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.
-