session-orchestrator 4.0.1 → 4.1.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "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.",
-    "version": "4.0.1"
+    "version": "4.1.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "4.0.1",
+  "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",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "4.0.1+codex.20260907191442",
+  "version": "4.1.0+codex.20260908074427",
   "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.",
   "keywords": [
     "session",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "4.0.1",
+  "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"

package/CHANGELOG.md

@@ -7,6 +7,29 @@ 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

package/README.md

@@ -1,11 +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.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 [![Tests](https://img.shields.io/badge/tests-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.
+Plan, run and verify coding sessions with **Claude Code, Codex CLI, Cursor IDE, or [Pi](docs/pi-setup.md)**. Session Orchestrator reads your repository and issues, proposes a plan, coordinates work in waves, and records what passed and what remains. Free, MIT-licensed, and community-maintained.
+
+[Website](https://session-orchestrator.com) · [User guide](docs/USER-GUIDE.md) · [Platform support](#platform-support) · [Changelog](CHANGELOG.md)
 
 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)).
 
@@ -16,7 +18,7 @@ The same workflows are available on all four harnesses; Codex exposes commands a
 | **Node.js** | **24 or later** (`node --version`) — `package.json` `engines.node` is `>=24.0.0`. The plugin is ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/). |
 | **A coding agent** | Claude Code, Codex CLI, Cursor IDE, or Pi. This is a workflow layer *on top of* one of them, not a replacement. |
 | **Harness version** | Codex CLI **0.144.4 or later** ([docs/codex-setup.md](docs/codex-setup.md)). No minimum is pinned for Claude Code, Cursor, or Pi — if `/plugin` (or the Cursor/Pi installer) runs, the plugin loads. |
-| **OS** | macOS and Linux are first-class and run in CI (`ubuntu-latest`, `macos-latest`). Windows is **not** covered by CI and has not been tested natively — treat it as best-effort. The Node core is portable (paths via `path.join`, tmp via `os.tmpdir()`), but `hooks/hooks.json` invokes hook commands via `sh` (see line 14) and the optional MCP server (`scripts/mcp-server.sh`) is a Bash script that needs `jq` on `PATH` — both need WSL or Git Bash on Windows. |
+| **OS** | macOS and Linux are tested in CI. Windows is untested and best-effort; shell hooks and the optional Bash/`jq` MCP server need WSL or Git Bash. |
 | **Git** | A git repository. Session-orchestrator reads git state at every session start and commits at close. |
 
 ## Install
@@ -28,42 +30,21 @@ The same workflows are available on all four harnesses; Codex exposes commands a
 | **Cursor IDE** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/cursor-install.mjs /path/to/your/project` |
 | **Pi** | `pi install npm:session-orchestrator` — or dev-fallback: `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` |
 
-For Claude Code, also install Node dependencies **once** (hooks import `zx`) and restart Claude Code:
+For Claude Code, also install the package's Node dependencies **once** and restart Claude Code. First locate the installed plugin:
 
 ```bash
-# Claude Code has no `plugin dir` subcommand, so resolve the install path from the cache.
-SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
-cd "$SO_DIR" && npm install
+claude plugin list --json
 ```
 
-If `SO_DIR` comes back empty, the plugin is not installed from a marketplace — check `/plugin list` inside Claude Code first.
-
-Setup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md) · [Pi](docs/pi-setup.md). Per-IDE notes on `CLAUDE.md` vs `AGENTS.md`: [instruction-file-resolution](skills/_shared/instruction-file-resolution.md).
-
-## Upgrade
+Find the enabled `session-orchestrator@kanevry` entry, then replace the placeholder below with its `installPath` value:
 
-```text
-/plugin update session-orchestrator@kanevry     # Claude Code
+```bash
+cd "/absolute/installPath/from/the/list" && npm install
 ```
 
-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".
-
-Upgrading across a major version: **[docs/migration-v4.md](docs/migration-v4.md)** is the current one — v4.0.0 removes five skills, three commands and eight top-level scripts, each on a measured 90-day two-signal rule rather than a judgement call, and it names what replaces every removed invocation. [docs/migration-v3.md](docs/migration-v3.md) documents the older v2 → v3 path and the shape both guides follow (what changes · prerequisites · per-platform steps · what stays · known issues · rollback).
+If that entry is missing or disabled, resolve it through `/plugin` first. Use the path reported for that entry; another cached version or a nested dependency is not the installed plugin.
 
-## Uninstall
-
-Remove the plugin through your harness's own plugin manager — `/plugin` in Claude Code (marketplace entry `session-orchestrator@kanevry`), `codex plugin remove` on Codex CLI ([docs/codex-setup.md](docs/codex-setup.md)). On Cursor and Pi, delete the files the installer wrote into your project.
-
-**What stays behind in your repo** — none of it is removed by uninstalling, and all of it is plain text you can delete by hand:
-
-- `.orchestrator/` — `bootstrap.lock`, `metrics/` (your session and learning JSONL records), `policy/`, `steering/`, `runtime/`, `peers/`, `session.lock`
-- `STATE.md` under your harness's state directory (`.claude/STATE.md` on Claude Code — see [Platform support](#platform-support))
-- The `## Session Config` block you added to `CLAUDE.md` / `AGENTS.md`
-- `.claude/rules/*.md` if you vendored the rule library via `/bootstrap --sync-rules`
-
-Deleting `.orchestrator/metrics/` deletes your session history. Nothing is sent anywhere without your explicit consent (see [Data & telemetry](#safety--data--telemetry)) — the one exception is the session-start update check (`scripts/lib/plugin-update-banner.mjs`): a single anonymous `GET` to the npm registry, at most once per day per repo, comparing your installed version against the latest release. Set `SO_DISABLE_UPDATE_CHECK=1` (or `DO_NOT_TRACK=1`) to turn it off. Beyond that, there is nothing else to revoke.
+Setup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md) · [Pi](docs/pi-setup.md). Per-IDE notes on `CLAUDE.md` vs `AGENTS.md`: [instruction-file-resolution](skills/_shared/instruction-file-resolution.md).
 
 ## Quick Start
 
@@ -117,6 +98,31 @@ $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.
 
+## Upgrade
+
+```text
+/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 Cursor and the Pi clone fallback, upgrade with `git pull` in your clone followed by the same install script you originally ran. Manage npm-installed Pi packages through Pi's package manager. 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".
+
+Upgrading across a major version: **[docs/migration-v4.md](docs/migration-v4.md)** is the current one — v4.0.0 removes five skills, three commands and eight top-level scripts, each on a measured 90-day two-signal rule rather than a judgement call, and it names what replaces every removed invocation. [docs/migration-v3.md](docs/migration-v3.md) documents the older v2 → v3 path and the shape both guides follow (what changes · prerequisites · per-platform steps · what stays · known issues · rollback).
+
+## Uninstall
+
+Remove the plugin through your harness's own plugin manager — `/plugin` in Claude Code (marketplace entry `session-orchestrator@kanevry`), `codex plugin remove` on Codex CLI ([docs/codex-setup.md](docs/codex-setup.md)), or Pi's package manager for an npm-installed Pi package. On Cursor and the Pi clone fallback, delete the files the installer wrote into your project.
+
+**What stays behind in your repo** — none of it is removed by uninstalling, and all of it is plain text you can delete by hand:
+
+- `.orchestrator/` — `bootstrap.lock`, `metrics/` (your session and learning JSONL records), `policy/`, `steering/`, `runtime/`, `peers/`, `session.lock`
+- `STATE.md` under your harness's state directory (`.claude/STATE.md` on Claude Code — see [Platform support](#platform-support))
+- The `## Session Config` block you added to `CLAUDE.md` / `AGENTS.md`
+- `.claude/rules/*.md` if you vendored the rule library via `/bootstrap --sync-rules`
+
+Deleting `.orchestrator/metrics/` deletes your session history. Telemetry requires explicit consent (see [Data & telemetry](#safety--data--telemetry)). The session-start update check (`scripts/lib/plugin-update-banner.mjs`) makes an anonymous `GET` to the npm registry to compare your installed version against the latest release. Successful results are cached for 24 hours per repo; failed checks can retry at the next session start. Set `SO_DISABLE_UPDATE_CHECK=1` (or `DO_NOT_TRACK=1`) to turn it off.
+
 ## Lifecycle and waves
 
 ![Session Orchestrator wave lifecycle: /bootstrap once per repo, then /session, then /go running five typed waves — Discovery, G1, Impl-Core, G2, Impl-Polish, G3, Quality, G4 Full Gate, Finalization — followed by /close](assets/wave-lifecycle.svg)
@@ -177,8 +183,8 @@ Counts measured on 2026-09-07 with the command in brackets:
 - **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`)
-- **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`)
+- **26 rule files** and **18 ADRs** carrying the reasoning behind the mechanisms (`ls .claude/rules/*.md | wc -l`, `ls docs/adr/*.md | wc -l`)
+- **667 vitest test files** covered by the full quality gate and CI — 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.** `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).
 
@@ -189,24 +195,22 @@ Full component inventory: [`docs/components.md`](docs/components.md). Version hi
 - **Typed waves, not one big batch.** Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a *simplification pass* on AI-generated code **before** tests are written — otherwise tests pin the AI patterns into place.
 - **Inter-wave reviews, not just end-of-session.** Catching regressions between waves stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.
 - **State persists across crashes.** `STATE.md` records wave progress and deviations; the next `/session` offers to resume from the last completed wave.
-- **Hooks enforce, not just warn.** A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike ([Safety](#safety--data--telemetry)).
-- **Parallel *operator* sessions are treated as a hazard.** Two humans — or two of your own sessions — in the same working copy share one git index, one filesystem, one `STATE.md`. A heartbeat session lock, peer-scope manifests, and the PSA rule set in [`.claude/rules/parallel-sessions.md`](.claude/rules/parallel-sessions.md) exist for exactly that axis.
+- **Hook enforcement has a defined platform boundary.** Claude Code hooks block covered destructive commands; writes outside declared paths warn in `warn` mode and block in `strict` mode. Cursor and Pi bridge supported events. Codex currently has no scope-enforcement adapter ([Platform support](#platform-support)).
+- **Parallel *operator* sessions are treated as a hazard.** Two humans — or two of your own sessions — in the same working copy share one git index, one filesystem, one `STATE.md`. A heartbeat session lock, peer-scope manifests, and the PSA rule set in [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) exist for exactly that axis.
 - **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.
 - **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.
 
 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.1)
+## Recent highlights (v4.1.0)
 
-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:
+Highlights of the v4.1.0 line:
 
-- **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.
+- **Privacy and session ownership.** The privacy scanner covers MDX and can include untracked files with `--include-untracked`. Native Codex task IDs now confirm session ownership; ambiguous inherited IDs remain unconfirmed.
+- **CI and release recovery.** Coverage verification now requires valid reports and measured thresholds. Audit detection checks executable workflow commands; GitHub release recovery retains the exact repository, tag and retry notes.
+- **Clearer onboarding.** README, English/German pages and the guide agree on installation and platform capabilities. Guide Copy buttons stay beside their command blocks, including on narrow screens.
 
-Full list, with the evidence for each claim: [CHANGELOG.md](CHANGELOG.md).
+If upgrading from before 4.0, read [the v4 migration guide](docs/migration-v4.md). Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
 
 ## Platform support
 
@@ -225,13 +229,13 @@ All platforms share the same skills, commands, and scripts; hooks use platform-s
 
 **Your data stays in your repo.** Session Orchestrator runs locally, requires no account, and writes its records as append-only JSONL under `.orchestrator/metrics/` in *your* repository — sessions, learnings, events, subagent records. Those files are yours: readable, greppable, deletable. Optional anonymous usage telemetry is **off until you explicitly consent** and is separate from the local records ([docs/telemetry.md](docs/telemetry.md) says exactly what it would collect and how to turn it off). Reported metrics describe *this* repository under its own conditions and will not transfer unchanged to yours ([details](docs/telemetry/telemetry-claims.md)).
 
-**Destructive-command guard.** `hooks/pre-bash-destructive-guard.mjs` enforces `.orchestrator/policy/blocked-commands.json` — 14 rules, of which 10 block outright (`git reset --hard`, `rm -rf`, `git push --force`, and more) and 4 warn — in the main session *and* in subagent waves. Bypass per session only for intentional maintenance:
+**Destructive-command guard.** On Claude Code, `hooks/pre-bash-destructive-guard.mjs` enforces `.orchestrator/policy/blocked-commands.json` — 14 rules, of which 10 block outright (`git reset --hard`, `rm -rf`, `git push --force`, and more) and 4 warn — in the main session *and* in subagent waves. Other harnesses depend on their event adapters; see [Platform support](#platform-support). Bypass per session only for intentional maintenance:
 
 ```yaml
 allow-destructive-ops: true
 ```
 
-The rule source of truth is [`.claude/rules/parallel-sessions.md`](.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.
+The rule source of truth is [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.
 
 **Import probe.** `hooks/post-edit-import-probe.mjs` (PostToolUse on `Edit`/`Write`/`MultiEdit`) guards the other direction: a hook-reachable helper saved in a broken intermediate state makes *every* Bash/Edit/Write call fail with "Internal hook error — request blocked", host-wide, for every session sharing the working copy. Right after such a file is saved the probe runs ESLint `no-undef` on it (plus a child-process `import()` for `scripts/lib/**`) and reports the blast radius; it never blocks and always exits 0. It only fires for files listed in the committed allowlist [`hooks/_lib/hook-import-set.json`](hooks/_lib/hook-import-set.json), regenerated by `node scripts/generate-hook-import-set.mjs`. Kill switch: `SO_DISABLED_HOOKS=post-edit-import-probe`.
 
@@ -255,9 +259,9 @@ npm run typecheck # node --check on every .mjs file
 
 `.npmrc` ships with `ignore-scripts=true` (supply-chain defence), so Husky git hooks don't auto-wire on install — run `npx husky` once after cloning. `git commit` then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.
 
-Two directories share the name *rules* and play opposite roles: [`rules/`](rules/README.md) is the **deliverable rule library** shipped *out* to consumer repos via `/bootstrap --sync-rules`, while [`.claude/rules/`](.claude/rules/) is this repo's own always-on rule set.
+Two directories share the name *rules* and play opposite roles: [`rules/`](rules/README.md) is the **deliverable rule library** shipped *out* to consumer repos via `/bootstrap --sync-rules`, while [`.claude/rules/`](https://github.com/Kanevry/session-orchestrator/tree/main/.claude/rules/) is this repo's own rule set with always-on and path-scoped entries.
 
-Contributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [sub-agent authoring spec](docs/agent-authoring.md).
+Contributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md) · [sub-agent authoring spec](docs/agent-authoring.md).
 
 ## Support & scope
 
@@ -278,12 +282,12 @@ What it is **not**:
 - [User Guide](docs/USER-GUIDE.md) — installation, config reference, workflow walkthrough, FAQ
 - [Components & Reference](docs/components.md) — full skill/command/agent/hook inventory, repository anatomy, comparisons
 - [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) — contributor guide, layering, hook anatomy, testing
-- [Migration guide](docs/migration-v3.md) — upgrade path, known issues, rollback
+- [Migration to v4](docs/migration-v4.md) — upgrade path, removed surfaces and replacements
 - [Telemetry](docs/telemetry.md) · [Telemetry claims](docs/telemetry/telemetry-claims.md) — what is collected, how metrics are measured, why they may not transfer
-- [Example Configs](docs/examples/) — Session Config examples for Next.js, Express, Swift
+- [Example Configs](https://github.com/Kanevry/session-orchestrator/tree/main/docs/examples/) — Session Config examples for Next.js, Express, Swift
 - [CHANGELOG.md](CHANGELOG.md) — version history
 
-We follow [Conventional Commits](https://www.conventionalcommits.org/) — see [CONTRIBUTING.md](CONTRIBUTING.md).
+We follow [Conventional Commits](https://www.conventionalcommits.org/) — see [CONTRIBUTING.md](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md).
 
 ## Learn the method behind it
 

package/commands/release.md

@@ -29,14 +29,14 @@ The same reading shows the other half: the GitHub releases for 3.15/3.18/3.19/3.
 1. **Preconditions.** Working tree clean, on `main`, and `origin/main` **and** `github/main` both level with `HEAD`. The mirror is checked because the site deploy hangs off `github`, not `origin`.
 2. **Set the version.** `node scripts/release.mjs --set-version X.Y.Z` — rewrites every version surface, syncs `package-lock.json`, re-stamps the measured census on the site.
 3. **Write the editorial half.** The dated `## [X.Y.Z] - YYYY-MM-DD` CHANGELOG entry, `[Unreleased]` folded, README highlights. The script does not write these; `--check` enforces them.
-4. **Preflight.** `node scripts/release.mjs --check --json` — every row green. This runs *after* step 2, never before: `--check` derives its target from `package.json`, so on the pre-bump version the registry- and tag-collision rows are red by construction.
-5. **Gate, commit, push.** Full quality gate, then commit and push to **both** remotes.
-6. **CI green — on the commit that will be published, on BOTH platforms.** Not on its predecessor: a green pipeline from before step 5's commit is evidence about a different tree. And not on GitLab alone — `--check` carries two CI rows, `ci-green-on-head` (GitLab, via `origin`) and `ci-green-on-head-github` (the mirror). The GitLab pipeline is Linux-only; the **macOS** matrix leg exists solely in `.github/workflows/test.yml`, i.e. on the operator's own platform. The github row self-disables (`skipped — no github remote`) in a checkout without a mirror, and fails on `unknown`/`degraded` exactly like the GitLab one — "could not read the mirror" is not "the mirror is green".
+4. **Gate, commit, push.** Full quality gate, then commit and push to **both** remotes.
+5. **CI green — on the commit that will be published, on BOTH platforms.** Not on its predecessor: a green pipeline from before step 4's commit is evidence about a different tree. And not on GitLab alone — `--check` carries two CI rows, `ci-green-on-head` (GitLab, via `origin`) and `ci-green-on-head-github` (the mirror). The GitLab pipeline is Linux-only; the **macOS** matrix leg exists solely in `.github/workflows/test.yml`, i.e. on the operator's own platform. The github row self-disables (`skipped — no github remote`) in a checkout without a mirror, and fails on `unknown`/`degraded` exactly like the GitLab one — "could not read the mirror" is not "the mirror is green".
+6. **Preflight.** `node scripts/release.mjs --check --json` — every row green. Run this after the release commit is pushed and its CI succeeds: the preflight requires a clean working tree, exact HEAD parity on both remotes and green CI on that commit. It derives its target from `package.json`, so checking the pre-bump version instead produces registry- and tag-collision failures.
 7. **Publish.** `node scripts/release.mjs --publish` — **give it ≥600 s of wall clock, or run it in the background.** The script sets no spawn timeout on purpose (a kill mid-`npm publish` or mid-push is the very failure the receipt boundary exists to avoid), and the tail is slow by construction: each of the two `git push` remotes re-runs the husky pre-push full gate, plus up to 120 s of live-site polling. A 3-minute default command timeout kills it mid-tail.
 
    The target-confirmed npm receipt is the irreversible boundary. Before that receipt, any failure aborts normally. After it, never rerun `--publish`: registry propagation timeout/query/wait failures are reconciliation while the script still tags, pushes `main` + tag to both remotes, handles the GitHub release, and polls the live site. If tag/push fails after the receipt, the dependent GitHub-release and site steps are skipped and the script returns structured reconciliation guidance instead. Add the GitHub release for the new tag (`gh release create`) as part of this step, not "later" — "later" is what produced the three-second backfill above.
 
-Steps 2–7 are one continuous act. A release left parked between step 5 and step 7 is exactly the `3.18.0` state: every surface says released, the registry disagrees.
+Steps 2–7 are one continuous act. A release left parked between step 4 and step 7 is exactly the `3.18.0` state: every surface says released, the registry disagrees.
 
 ## Abort criteria
 

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.0.1 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v4.1.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.0.1 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v4.1.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "4.0.1",
+  "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.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",

package/scripts/ci/assert-coverage-green.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Repository CI only: requires the checkout's Vitest config and dev dependencies.
+// Test-result JSON does not prove coverage. Check the structured coverage summary
+// against the same global percentage thresholds Vitest uses before writing a marker.
+// The caller removes both reports and the marker before starting the current run.
+
+import { readFileSync } from 'node:fs';
+import config from '../../vitest.config.mjs';
+
+const metrics = ['lines', 'functions', 'statements', 'branches'];
+const [summaryPath = 'coverage/coverage-summary.json', xmlPath = 'coverage/cobertura-coverage.xml'] = process.argv.slice(2);
+
+function requireValid(condition, reason) {
+  if (!condition) throw new Error(reason);
+}
+
+// Check completeness of the XML emitted by the configured Istanbul reporter.
+// This is an artifact check, not a DTD/schema evaluator; never fetch the DOCTYPE.
+function checkCobertura(xml, total) {
+  const stack = [];
+  let root;
+  let hasClassLine = false;
+  const parts = xml.match(/<[^>]*>|[^<]+/g) ?? [];
+  requireValid(parts.join('') === xml, 'malformed Cobertura artifact');
+  for (const part of parts) {
+    if (/^<\?xml\s[^<>]*\?>$|^<!DOCTYPE coverage SYSTEM "[^"<>]*">$/.test(part)) {
+      requireValid(!root, 'unexpected Cobertura declaration');
+      continue;
+    }
+    if (!part.startsWith('<')) {
+      requireValid(!part.trim() || stack.at(-1) === 'source', 'unexpected Cobertura content');
+      continue;
+    }
+    const tag = part.match(/^<(\/?)([A-Za-z][\w.-]*)((?:\s+[\w:-]+="[^"<>]*")*)\s*(\/?)>$/);
+    requireValid(tag, 'malformed Cobertura tag');
+    const [, closing, name, attributes, selfClosing] = tag;
+    if (closing) {
+      requireValid(!attributes && !selfClosing && stack.pop() === name, 'unbalanced Cobertura tags');
+    } else {
+      const entries = [...attributes.matchAll(/([\w:-]+)="([^"]*)"/g)].map((match) => [match[1], match[2]]);
+      requireValid(new Set(entries.map(([key]) => key)).size === entries.length, 'duplicate Cobertura attributes');
+      const values = Object.fromEntries(entries);
+      if (stack.length === 0) {
+        requireValid(!root && name === 'coverage' && !selfClosing, 'invalid Cobertura root');
+        root = values;
+      }
+      const path = [...stack, name].join('/');
+      if (path === 'coverage/packages/package/classes/class') {
+        requireValid(typeof values.filename === 'string' && values.filename.trim(), 'Cobertura class is missing a filename');
+      }
+      if (path === 'coverage/packages/package/classes/class/lines/line') {
+        requireValid(/^\d+$/.test(values.number) && Number(values.number) > 0
+          && /^\d+$/.test(values.hits), 'invalid Cobertura line record');
+        hasClassLine = true;
+      }
+      if (!selfClosing) stack.push(name);
+    }
+  }
+  requireValid(root && stack.length === 0, 'empty or incomplete Cobertura artifact');
+  requireValid(total.lines.total === 0 || hasClassLine, 'Cobertura artifact contains no class line records');
+  for (const [attribute, expected] of Object.entries({
+    'lines-valid': total.lines.total,
+    'lines-covered': total.lines.covered,
+    'line-rate': total.lines.pct / 100,
+    'branches-valid': total.branches.total,
+    'branches-covered': total.branches.covered,
+    'branch-rate': total.branches.pct / 100,
+  })) {
+    requireValid(root[attribute] !== undefined && root[attribute] !== ''
+      && Number(root[attribute]) === expected, `Cobertura ${attribute} disagrees with coverage summary`);
+  }
+}
+
+try {
+  const thresholds = config.test?.coverage?.thresholds;
+  requireValid(thresholds && Object.keys(thresholds).every((key) => metrics.includes(key)),
+    'unsupported coverage thresholds: expected global percentage thresholds');
+  const { total } = JSON.parse(readFileSync(summaryPath, 'utf8'));
+  requireValid(total && typeof total === 'object', 'missing coverage totals');
+  for (const metric of metrics) {
+    const threshold = thresholds[metric];
+    requireValid(Number.isFinite(threshold) && threshold >= 0 && threshold <= 100,
+      `missing or invalid configured ${metric} threshold`);
+    const data = total[metric];
+    requireValid(data && ['total', 'covered', 'skipped'].every((key) => Number.isSafeInteger(data[key]) && data[key] >= 0)
+      && data.total > 0 && data.covered <= data.total && data.skipped <= data.total
+      && Number.isFinite(data.pct) && data.pct >= 0 && data.pct <= 100,
+    `missing or invalid ${metric} coverage data`);
+    // Istanbul truncates percentages to two decimals; compare the reported
+    // percentage (Vitest's threshold input) only after checking its counters.
+    const percentage = Math.floor((100000 * data.covered / data.total) / 10) / 100;
+    requireValid(data.pct === percentage, `inconsistent ${metric} coverage percentage`);
+    requireValid(data.pct >= threshold, `${metric} coverage ${data.pct}% is below configured ${threshold}%`);
+  }
+  checkCobertura(readFileSync(xmlPath, 'utf8'), total);
+  console.log(`[ci] coverage verified: ${metrics.map((metric) => `${metric}=${total[metric].pct}%`).join(' ')}`);
+} catch (error) {
+  console.error(`[ci] coverage NOT VERIFIED: ${error.message}`);
+  process.exitCode = 1;
+}

package/scripts/lib/events.mjs

@@ -27,8 +27,8 @@
  *   3. **Never a peer's id (#1123).** A shared working copy means
  *      `session.lock` can name a PEER session that won the acquire race. The
  *      lock alone therefore does not prove ownership; the fill happens only
- *      when a PROCESS-LOCAL id (`CLAUDE_CODE_SESSION_ID`, or a hook payload's
- *      `session_id`) equals the lock's raw `session_id`. STATE.md is NOT a
+ *      when a confirmed native PROCESS-LOCAL id (`CLAUDE_CODE_SESSION_ID` or
+ *      `CODEX_THREAD_ID`) equals the lock's raw `session_id`. STATE.md is NOT a
  *      witness here (#1177 FX1): it is a shared working-copy file written by
  *      the lock holder, so under a peer-owned lock both agreed about the peer
  *      and the union stamped the peer's ids. See {@link attributionForRecord}.
@@ -124,7 +124,7 @@ const STATE_DIR_CANDIDATES = ['.claude', '.codex', '.cursor', '.pi'];
  * when one exists it decides alone.**
  *
  *   - No lock (CI, a bare script) → `{}`. Nothing to attribute to.
- *   - No process-local id (`CLAUDE_CODE_SESSION_ID` absent) → `{}`. Ownership is
+ *   - No confirmed process-local id (absent or ambiguous native env) → `{}`. Ownership is
  *     UNPROVEN, and an unproven attribution is exactly the peer-id write #1123
  *     forbids; an absent key costs a correlation, a wrong key costs a false one.
  *   - A process-local id that equals the lock's raw `session_id` → fill BOTH

package/scripts/lib/project-hygiene.mjs

@@ -44,6 +44,8 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import yaml from 'js-yaml';
+import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './command-blocker.mjs';
 
 /** Commits past the newest tag before release hygiene is worth mentioning. */
 export const DEFAULT_RELEASE_DRIFT_COMMITS = 50;
@@ -408,8 +410,8 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
 /**
  * H4 — CI configuration hygiene.
  *
- * Measured 5/6. Reports only what is decidable by presence, never by parsing
- * pipeline semantics. The dependency-audit gap is the load-bearing one: three
+ * Measured 5/6. Checks locally declared executable commands without evaluating
+ * pipeline conditions or external includes. The dependency-audit gap is the load-bearing one: three
  * of the tested repos carried known-vulnerable dependencies that no pipeline
  * would ever surface.
  *
@@ -438,19 +440,21 @@ export function checkCiConfig(repoRoot) {
     return findings;
   }
 
-  let ciText = '';
-  if (hasGitlab) ciText += safeRead(gitlabCi);
+  const ciConfigs = [];
+  if (hasGitlab) ciConfigs.push({ text: safeRead(gitlabCi), platform: 'gitlab' });
   if (hasGithub) {
     try {
       for (const f of readdirSync(ghWorkflows)) {
-        if (f.endsWith('.yml') || f.endsWith('.yaml')) ciText += safeRead(join(ghWorkflows, f));
+        if (f.endsWith('.yml') || f.endsWith('.yaml')) {
+          ciConfigs.push({ text: safeRead(join(ghWorkflows, f)), platform: 'github' });
+        }
       }
     } catch {
       /* unreadable workflows dir — fall through with what we have */
     }
   }
 
-  if (ciText && !/\b(npm|pnpm|yarn) audit\b|pip-audit|cargo audit|osv-scanner|dependency.?check/i.test(ciText)) {
+  if (ciConfigs.some(({ text }) => text) && !ciConfigs.some(hasAuditStep)) {
     findings.push({
       check: 'ci-audit-job',
       fixable: true,
@@ -461,6 +465,178 @@ export function checkCiConfig(repoRoot) {
   return findings;
 }
 
+const GITLAB_COMMAND_FIELDS = ['script', 'before_script', 'after_script'];
+const GITLAB_GLOBAL_FIELDS = new Set([
+  'stages', 'types', 'variables', 'default', 'include', 'workflow',
+  'image', 'services', 'cache', 'before_script', 'after_script', 'spec',
+]);
+const GITLAB_REFERENCE = Symbol('gitlab-reference');
+const GITLAB_SCHEMA = yaml.DEFAULT_SCHEMA.extend([
+  new yaml.Type('!reference', {
+    kind: 'sequence',
+    construct: (path) => ({ [GITLAB_REFERENCE]: path }),
+  }),
+]);
+const AUDIT_VALUE_FLAGS = new Set([
+  '--filter', '-F', '--dir', '-C', '--prefix', '--cwd', '--registry',
+  '--userconfig', '--globalconfig', '--workspace', '-w', '--cache', '--pm-on-fail',
+]);
+const AUDIT_BOOLEAN_FLAGS = new Set([
+  '-r', '--recursive', '-s', '--silent', '-g', '--global', '--workspaces', '--offline',
+]);
+
+/** Inspect executable job/step locations, never arbitrary keys named run/script. */
+function hasAuditStep({ text, platform }) {
+  let config;
+  try {
+    if (platform === 'gitlab') {
+      const documents = yaml.loadAll(text, undefined, { schema: GITLAB_SCHEMA });
+      if (documents.length === 1) {
+        [config] = documents;
+      } else if (documents.length === 2 && isConfigMap(documents[0])
+        && Object.keys(documents[0]).length === 1 && isConfigMap(documents[0].spec)) {
+        // GitLab permits a spec header followed by --- and the job document.
+        // Header input defaults are data; unrelated multi-document YAML is ambiguous.
+        [, config] = documents;
+      } else {
+        return false;
+      }
+    } else {
+      config = yaml.load(text);
+    }
+  } catch {
+    return false;
+  }
+  if (!isConfigMap(config)) return false;
+  if (platform === 'github') {
+    if (!isConfigMap(config.jobs)) return false;
+    return Object.values(config.jobs).some((job) => isConfigMap(job)
+      && job.if !== false && Array.isArray(job.steps)
+      && job.steps.some((step) => isConfigMap(step) && step.if !== false
+        && typeof step.run === 'string' && hasAuditCommand(step.run)));
+  }
+
+  return Object.keys(config).some((name) => {
+    if (name.startsWith('.') || GITLAB_GLOBAL_FIELDS.has(name)) return false;
+    const job = resolveGitlabJob(config, name);
+    if (!job?.script || job.when === 'never') return false;
+    return GITLAB_COMMAND_FIELDS.some((field) => {
+      let commands = job[field];
+      if (!Object.hasOwn(job, field) && field !== 'script') {
+        const inherit = job.inherit?.default;
+        if (inherit === false || (Array.isArray(inherit) && !inherit.includes(field))) return false;
+        commands = Object.hasOwn(config.default ?? {}, field) ? config.default[field] : config[field];
+      }
+      return hasGitlabAuditCommands(commands, config);
+    });
+  });
+}
+
+function isConfigMap(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && !Object.hasOwn(value, GITLAB_REFERENCE);
+}
+
+/** Local extends uses later-parent/child replacement for command arrays. */
+function resolveGitlabJob(config, name, seen = new Set()) {
+  if (typeof name !== 'string' || !Object.hasOwn(config, name)
+    || !isConfigMap(config[name]) || seen.has(name)) return null;
+  seen.add(name);
+  const job = config[name];
+  let merged = {};
+  const parents = Array.isArray(job.extends) ? job.extends : [job.extends];
+  for (const parent of parents.filter((entry) => entry !== undefined)) {
+    const inherited = resolveGitlabJob(config, parent, seen);
+    // An unresolved later parent may override earlier commands. Only fields
+    // supplied by later local parents or the job itself remain evidence.
+    merged = inherited ? mergeGitlabJob(merged, inherited) : {};
+  }
+  seen.delete(name);
+  return mergeGitlabJob(merged, job);
+}
+
+function mergeGitlabJob(parent, child) {
+  const merged = { ...parent, ...child };
+  // Command fields replace wholesale; inherit is a map, so its default flag
+  // survives a child that overrides only inherit.variables.
+  if (isConfigMap(parent.inherit) && isConfigMap(child.inherit)) {
+    merged.inherit = { ...parent.inherit, ...child.inherit };
+  }
+  return merged;
+}
+
+/** Resolve only command strings/arrays and local !reference paths, with cycle guards. */
+function hasGitlabAuditCommands(commands, config) {
+  const seen = new WeakSet();
+  function visit(value) {
+    if (typeof value === 'string') return hasAuditCommand(value);
+    if (!value || typeof value !== 'object' || seen.has(value)) return false;
+    seen.add(value);
+    let found = false;
+    if (Array.isArray(value)) {
+      found = value.some(visit);
+    } else if (Array.isArray(value[GITLAB_REFERENCE])) {
+      let target = config;
+      for (const key of value[GITLAB_REFERENCE]) {
+        target = target && typeof target === 'object' && Object.hasOwn(target, key) ? target[key] : undefined;
+      }
+      found = visit(target);
+    }
+    seen.delete(value);
+    return found;
+  }
+  return visit(commands);
+}
+
+/**
+ * Bounded command recognition: wrappers and options may precede the audit
+ * subcommand, but another verb (install/run/echo) ends the search. Unknown
+ * value-taking flags and commands hidden in external includes are not resolved.
+ */
+function hasAuditCommand(command) {
+  return splitChainSegments(tokenizeCommand(command)).some((segment) => hasAuditSegment(segment));
+}
+
+function hasAuditSegment(segment, depth = 0) {
+  const resolved = resolveSegmentVerb(segment);
+  if (resolved.alt) return false;
+  let { verb, index } = resolved;
+  if (resolved.payloads.length > 0) {
+    if (depth >= 3 || resolved.payloads.length !== 1) return false;
+    const tokens = tokenizeCommand(resolved.payloads[0]);
+    const parts = splitChainSegments(tokens);
+    // env -S splits argv; it does not execute shell operators. Restrict this
+    // reuse of the shared tokenizer to one plain command with no redirects.
+    if (parts.length !== 1 || parts[0].length !== tokens.length
+      || tokens.some((token) => token.redirect)) return false;
+    const trailingArgs = index < 0 ? [] : segment.slice(index);
+    return hasAuditSegment([...tokens, ...trailingArgs], depth + 1);
+  }
+  if (verb === 'corepack' || verb === 'npx') {
+    index++;
+    while (['-y', '--yes', '--no-install', '--'].includes(segment[index]?.text)) index++;
+    verb = segment[index]?.text;
+  }
+  if (segment.slice(index + 1).some((token) => ['-h', '--help', '--version'].includes(token.text))) return false;
+  if (/^(?:pip-audit|osv-scanner|dependency-check(?:\.sh)?)$/.test(verb ?? '')) return true;
+  if (!/^(?:npm|pnpm|yarn|bun)(?:@[\w.+-]+)?$/.test(verb ?? '') && verb !== 'cargo') return false;
+  let i = index + 1;
+  while (segment[i]?.text.startsWith('-')) {
+    const flag = segment[i].text;
+    if (flag === '--') { i++; break; }
+    if (AUDIT_VALUE_FLAGS.has(flag)) {
+      if (!segment[i + 1] || segment[i + 1].redirect) return false;
+      i += 2;
+    } else if (AUDIT_BOOLEAN_FLAGS.has(flag) || /^--[\w-]+=/.test(flag)) {
+      i++;
+    } else {
+      return false;
+    }
+  }
+  if (/^yarn(?:@|$)/.test(verb) && segment[i]?.text === 'npm') i++;
+  return segment[i]?.text === 'audit';
+}
+
 /** @param {string} p @returns {string} */
 function safeRead(p) {
   try {

package/scripts/lib/session-identity/own-session.mjs

@@ -80,8 +80,8 @@ function readLockIds(repoRoot) {
  *      handled right now (`session_id` / `sessionId`, plus `parent_session_id`
  *      for a sub-agent invocation, whose coordinator is equally us). The only
  *      tier that is per-INVOCATION rather than per-working-copy.
- *   2. `CLAUDE_CODE_SESSION_ID` — process-scoped, absent on harnesses that
- *      export no session env var.
+ *   2. The native process-scoped id (`CLAUDE_CODE_SESSION_ID` or
+ *      `CODEX_THREAD_ID`), selected by {@link readProcessLocalSessionIds}.
  *   3. `session.lock` `session_id` / `semantic_session_id` — repo-GLOBAL, and
  *      the identity the WRITER of a manifest uses: `wave-scope.json`'s
  *      `session` field comes from `sessionAttribution()`, which reads this same
@@ -138,20 +138,12 @@ function readLockIds(repoRoot) {
  *   never as a mismatch.
  */
 export function readOwnSessionIds(repoRoot, { hookInput = null } = {}) {
-  const ids = new Set();
+  const ids = new Set(readProcessLocalSessionIds({ hookInput }));
   const add = (value) => {
     const trimmed = typeof value === 'string' ? value.trim() : '';
     if (trimmed) ids.add(trimmed);
   };
 
-  // Source 1 — the harness's statement about THIS invocation.
-  if (hookInput && typeof hookInput === 'object') {
-    for (const key of ['session_id', 'sessionId', 'parent_session_id']) add(hookInput[key]);
-  }
-
-  // Source 2 — process-scoped env var.
-  add(process.env.CLAUDE_CODE_SESSION_ID);
-
   // Source 3 — repo-global lock file (the manifest writer's own identity).
   try {
     const lock = readLockIds(repoRoot);
@@ -190,6 +182,14 @@ export function readOwnSessionIds(repoRoot, { hookInput = null } = {}) {
  * rather than unioning is the fix — a better signal REPLACES a worse one
  * (`.claude/rules/host-resources.md` § HR-102).
  *
+ * Native env identity (#1274): an explicit SO_PLATFORM selects ONLY its own
+ * variable (claude → CLAUDE_CODE_SESSION_ID, codex → CODEX_THREAD_ID). Cursor
+ * and Pi have no native env source here. Without a valid explicit selection,
+ * a single non-empty native id, or two equal ids, is usable; conflicting ids
+ * are ambiguous and contribute nothing. This prevents an inherited parent
+ * harness's id from confirming a peer lock. Hook invocation/parent ids remain
+ * valid independently. No filesystem/platform detection is an identity proof.
+ *
  * Never throws.
  *
  * @param {{ env?: object, hookInput?: object|null }} [opts]
@@ -211,8 +211,19 @@ export function readProcessLocalSessionIds({ env = process.env, hookInput = null
   if (hookInput && typeof hookInput === 'object') {
     for (const key of ['session_id', 'sessionId', 'parent_session_id']) add(hookInput[key]);
   }
-  // Tier 2 — process-scoped env var.
-  add(env?.CLAUDE_CODE_SESSION_ID);
+  // Tier 2 — select a native process id without importing the platform module
+  // into this hook-safe leaf or using shared repository markers as evidence.
+  const trim = (value) => typeof value === 'string' ? value.trim() : '';
+  const platform = trim(env?.SO_PLATFORM);
+  const claudeId = trim(env?.CLAUDE_CODE_SESSION_ID);
+  const codexId = trim(env?.CODEX_THREAD_ID);
+  if (platform === 'claude') add(claudeId);
+  else if (platform === 'codex') add(codexId);
+  else if (platform !== 'cursor' && platform !== 'pi') {
+    // Invalid/absent SO_PLATFORM is not an explicit choice (platform.mjs uses
+    // the same trimmed allowlist). Disagreement must never become a union.
+    if (!claudeId || !codexId || claudeId === codexId) add(claudeId || codexId);
+  }
 
   return ids;
 }

package/scripts/lib/validate/check-owner-leakage.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /**
  * check-owner-leakage.mjs — Scan tracked files for owner-privacy leakage patterns.
+ * Add --include-untracked to also scan new files that Git does not ignore.
  *
  * Implements the #462 audit trail durable CI guard (#471).
  * Canonicalization-before-matching refactor (issue #661): the historical
@@ -19,7 +20,7 @@
  * toward over-matching: this is a security guard, a false-positive is cheap, a
  * false-negative ships a leak to the public mirror.
  *
- * Usage: check-owner-leakage.mjs <plugin-root>
+ * Usage: check-owner-leakage.mjs <plugin-root> [--include-untracked]
  *
  * Forbidden patterns (canonical rules CP1–CP10):
  *   CP1  personal home path `/Users/bernhardg…` — matched on the CANONICAL form,
@@ -128,8 +129,9 @@ const isMain =
 
 // CLI: single positional arg required (only enforced when run directly).
 const pluginRoot = argv[2];
+const includeUntracked = argv.slice(3).includes('--include-untracked');
 if (isMain && !pluginRoot) {
-  console.error('Usage: check-owner-leakage.mjs <plugin-root>');
+  console.error('Usage: check-owner-leakage.mjs <plugin-root> [--include-untracked]');
   process.exit(1);
 }
 
@@ -789,9 +791,10 @@ function rawConfidentialNamesKeyState(ownerYamlPath) {
  * exists to block. The operator knows their own path; the CLASS of failure is what
  * this line has to convey.
  *
+ * @param {{ loadHostPaths?: typeof import('../config/host-paths.mjs').loadHostPaths }} [opts]
  * @returns {Promise<{ patterns: RegExp[], disabledReason?: string, inertWarn?: string }>}
  */
-async function getConfidentialNamePatterns() {
+export async function getConfidentialNamePatterns({ loadHostPaths } = {}) {
   let helpers;
   try {
     helpers = {
@@ -833,7 +836,7 @@ async function getConfidentialNamePatterns() {
   }
 
   try {
-    const { loadHostPaths, resolveHostPath } = helpers.hostPaths;
+    const { resolveHostPath } = helpers.hostPaths;
     const { inspectConfidentialNames } = helpers.confidentialNames;
     const { resolveOwnerYamlPath } = helpers.ownerYaml;
 
@@ -841,7 +844,7 @@ async function getConfidentialNamePatterns() {
     // health (source / reason / droppedSections) straight through, so the
     // env>owner.yaml>default precedence and the load's diagnosis come from the
     // same read — no second loadOwnerConfig() call to recover what was discarded.
-    const hostCtx = loadHostPaths();
+    const hostCtx = (loadHostPaths ?? helpers.hostPaths.loadHostPaths)();
 
     // FAIL-CLOSED on an unknowable load (LOW-2). `loadHostPaths` has its own
     // defensive catch that swallows a THROWING owner loader and returns
@@ -987,6 +990,7 @@ async function getConfidentialNamePatterns() {
 // adding: all 7 tracked `.jsonl` files pass (1525 -> 1532 scanned, 0 findings).
 const TEXT_EXTS = new Set([
   '.md',
+  '.mdx',
   '.mjs',
   '.js',
   '.ts',
@@ -1021,9 +1025,14 @@ function isTextFile(filePath) {
 
 function getTrackedFiles() {
   try {
-    const output = execFileSync('git', ['ls-files'], { cwd: pluginRoot, encoding: 'utf8' });
+    // NUL delimiters preserve Unicode, spaces and newlines without Git's quoted
+    // filename encoding. --exclude-standard applies only to untracked entries;
+    // tracked files remain visible even if an ignore rule now matches them.
+    const args = ['ls-files', '-z', '--cached'];
+    if (includeUntracked) args.push('--others', '--exclude-standard');
+    const output = execFileSync('git', args, { cwd: pluginRoot, encoding: 'utf8' });
     return output
-      .split('\n')
+      .split('\0')
       .filter(Boolean)
       .map((f) => join(pluginRoot, f));
   } catch {
@@ -1402,7 +1411,7 @@ if (violations.length === 0) {
 }
 
 console.log('');
-console.log(`Results: ${passed} passed, ${failed} failed`);
+console.log(`Results: ${passed} passed, ${failed} failed (${scanFiles.length} scanned files)`);
 process.exit(failed === 0 ? 0 : 1);
 }
 

package/scripts/lib/vault-mirror/render-sessions.mjs

@@ -473,12 +473,19 @@ export function generateSessionNote(entry, options = {}) {
   // that "repaired" that one too would be inventing a measurement.
   const waveRows = waves
     .map((w) => {
+      // #1276: lifecycle-only records omit every older count alias. Started
+      // measures participation; completed/planned-only counts retain their
+      // labels so a plan or a completion count never claims dispatch coverage.
+      const completedAgents = waveCount(w.agent_count_completed);
+      const plannedAgents = waveCount(w.agent_count_planned);
       const agentsCell =
         waveCount(w.agent_count) ??
         waveCount(w.agents) ??
         waveCount(w.agents_dispatched) ??
         waveCount(w.dispatched) ??
-        MISSING_CELL;
+        waveCount(w.agent_count_started) ??
+        (completedAgents === undefined ? undefined : `${completedAgents} completed`) ??
+        (plannedAgents === undefined ? MISSING_CELL : `${plannedAgents} planned`);
       const filesCell = waveCount(w.files_changed) ?? waveCount(w.files) ?? MISSING_CELL;
       const qualityCell =
         w.quality ?? w.quality_check ?? w.status ?? w.result ?? w.outcome ?? MISSING_CELL;

package/scripts/release.mjs

@@ -1520,10 +1520,15 @@ export function printPublishOutcome(outcome, target, io = {}) {
     log(`  ${outcome.release.detail}.`);
   } else {
     error(`\nRECONCILIATION: ${outcome.release.detail}`);
-    if (outcome.release.state === 'create-failed') {
-      error(`  Recover with: gh release create ${outcome.tag} --verify-tag --title ${outcome.tag} --notes-file <changelog excerpt>`);
+    const recovery = outcome.release.recovery;
+    if (recovery?.inspect) {
+      error(`  Inspect with: ${renderRecoveryCommand(recovery.inspect)}`);
+      if (outcome.release.state === 'create-failed' && recovery.create) {
+        error(`  Recover with: ${renderRecoveryCommand(recovery.create)}`);
+        error('  The notes file is retained for recovery; remove it after the release is reconciled.');
+      }
     } else {
-      error('  Inspect `gh release view` and its authentication/network state before attempting any create.');
+      error('  Resolve the GitHub repository identity before inspecting or creating the release.');
     }
   }
 
@@ -1553,6 +1558,11 @@ export function printPublishOutcome(outcome, target, io = {}) {
   return 0;
 }
 
+/** Render argv for a POSIX shell without interpreting paths as shell code. */
+function renderRecoveryCommand(argv) {
+  return argv.map((arg) => /^[\w./:@=+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`).join(' ');
+}
+
 /**
  * Create the GitHub release for `v<target>`, or confirm the existing one.
  *
@@ -1582,18 +1592,23 @@ export function printPublishOutcome(outcome, target, io = {}) {
  * @param {string} repoRoot
  * @param {string} target
  * @param {{runImpl?: Function, repoSpec?: string}} [deps] — injection seam for tests
- * @returns {{ok: boolean, created: boolean, tag: string, state: 'exists'|'created'|'unknown'|'create-failed', detail: string, argv?: string[]}}
+ * @returns {{ok: boolean, created: boolean, tag: string, state: 'exists'|'created'|'unknown'|'create-failed', detail: string, argv?: string[], recovery?: {inspect: string[], create?: string[]}}}
  */
 export function ensureGithubRelease(repoRoot, target, deps = {}) {
   const runImpl = deps.runImpl ?? run;
   const tag = `v${target}`;
-  const spec = deps.repoSpec ?? resolveRepoSpec({ repoRoot, vcs: 'github' });
-  // resolveRepoSpec returns undefined when it cannot auto-detect; its contract
-  // is that callers OMIT the flag rather than pass `-R undefined`.
-  const repoFlag = spec ? ['--repo', spec] : [];
+  let recovery;
 
   try {
-    const existing = runImpl('gh', ['release', 'view', tag, ...repoFlag], { cwd: repoRoot });
+    const spec = deps.repoSpec ?? resolveRepoSpec({ repoRoot, vcs: 'github' });
+    if (typeof spec !== 'string' || !spec.trim()) {
+      return { ok: false, created: false, tag, state: 'unknown', detail: 'GitHub repository identity could not be resolved' };
+    }
+    // Recovery must carry the same resolved identity as the real invocation.
+    // An absent identity cannot safely fall back to the caller's ambient repo.
+    const repoFlag = ['--repo', spec];
+    recovery = { inspect: ['gh', 'release', 'view', tag, ...repoFlag] };
+    const existing = runImpl(recovery.inspect[0], recovery.inspect.slice(1), { cwd: repoRoot });
     const viewOutput = `${existing.stdout || ''}\n${existing.stderr || ''}`.trim();
     if (existing.status === 0 && viewOutput) {
       return { ok: true, created: false, tag, state: 'exists', detail: `GitHub release ${tag} already exists — no-op` };
@@ -1607,6 +1622,7 @@ export function ensureGithubRelease(repoRoot, target, deps = {}) {
         created: false,
         tag,
         state: 'unknown',
+        recovery,
         detail: `could not determine whether GitHub release ${tag} exists (gh release view exited ${existing.status}: ${viewOutput.slice(0, 300) || 'empty output'})`,
       };
     }
@@ -1614,26 +1630,31 @@ export function ensureGithubRelease(repoRoot, target, deps = {}) {
     const notesDir = mkdtempSync(join(tmpdir(), 'release-ghnotes-'));
     const notesFile = join(notesDir, 'notes.md');
     let argv;
+    let retainNotes = false;
     try {
       writeFileSync(notesFile, `${changelogExcerpt(repoRoot, target)}\n`);
       argv = ['release', 'create', tag, ...repoFlag, '--verify-tag', '--title', tag, '--notes-file', notesFile];
       const created = runImpl('gh', argv, { cwd: repoRoot });
       if (created.status !== 0) {
+        // A recovery argv pointing to a file deleted by finally is unusable.
+        // Preserve only this failed-create excerpt; successful runs still clean up.
+        retainNotes = true;
         return {
           ok: false,
           created: false,
           tag,
           state: 'create-failed',
           argv,
+          recovery: { ...recovery, create: ['gh', ...argv] },
           detail: `gh release create exited ${created.status}: ${(created.stderr || created.stdout || '').trim().slice(0, 300)}`,
         };
       }
       return { ok: true, created: true, tag, state: 'created', argv, detail: `GitHub release ${tag} created (--verify-tag)` };
     } finally {
-      rmSync(notesDir, { recursive: true, force: true });
+      if (!retainNotes) rmSync(notesDir, { recursive: true, force: true });
     }
   } catch (err) {
-    return { ok: false, created: false, tag, state: 'unknown', detail: `gh could not be run: ${err.message}` };
+    return { ok: false, created: false, tag, state: 'unknown', ...(recovery ? { recovery } : {}), detail: `gh could not be run: ${err.message}` };
   }
 }