session-orchestrator 4.0.0 → 4.1.0

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.1.0",
   "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,217 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-09-08
+
+### Added
+
+- The owner-privacy scanner accepts `--include-untracked` to check new files before staging while respecting Git ignore rules. Tracked-only remains the default (#1267).
+
+### Fixed
+
+- Privacy scanning includes MDX and preserves filenames containing Unicode or newlines. Failure output includes the scanned-file count, and the pre-commit regression verifies that an unavailable confidential-name policy blocks the commit (#1267, #1269).
+- Native Codex `CODEX_THREAD_ID` now participates in process-confirmed session ownership and event attribution. Explicit harness selection prevents inherited IDs from proving ownership; ambiguous IDs remain unconfirmed. Test workers isolate the invoking harness's identity (#1274).
+- GitHub release recovery prints commands with the exact repository and tag, retains failed-create notes for retry, and inspects uncertain release state before any creation (#1095).
+- CI audit detection examines executable GitHub steps and GitLab jobs, recognizes package-manager options and supported wrappers, and excludes metadata, comments, unused templates and help-only invocations. Local GitLab references, inheritance and `spec:inputs` headers are supported; external includes and dynamic conditions remain outside this heuristic (#1040).
+- Vault session notes render lifecycle agent counts, preserve measured zero, and label counts known only as completed or planned (#1276).
+- Guide copy buttons stay beside their command blocks, including multiline snippets and narrow screens (#1275).
+- Full-repository validation runs once before Vitest workers start, and its result is shared by the existing smoke assertions. This avoids four competing scans during coverage while retaining mandatory validation and failure propagation (#1278).
+- Coverage verification now requires generated reports and compares structured measurements with the canonical Vitest thresholds before writing its verified marker. Missing artifacts and low coverage previously passed through shell conditions that did not stop the CI job (#1279).
+
+### Changed
+
+- README, English/German landing pages, guide and machine-readable summaries now agree on installation prerequisites, active plugin-cache selection, Codex command skills, Pi package management, platform-specific enforcement and update-cache behavior (#1275).
+- Refreshed distribution evidence and submission drafts, corrected stable repository steering, and recorded the product-quality review with Chrome and backlog evidence (#824, #1080).
+- Release instructions now place the fully green preflight after commit, both remote pushes and exact-commit CI, matching the executable gate's requirements (#1277).
+
+## [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 +1189,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