session-orchestrator 3.21.0 → 3.22.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": "3.21.0"
+    "version": "3.22.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": "3.21.0",
+  "version": "3.22.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": "3.21.0+codex.20260819195349",
+  "version": "3.22.0+codex.20260822193811",
   "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/rules/000-session-orchestrator.mdc

@@ -33,10 +33,11 @@ You have Session Orchestrator capabilities. This plugin provides structured sess
 **No AskUserQuestion tool**: Present choices as numbered Markdown lists:
 ```
 Choose one:
-1. Option A — description
-2. Option B — description
+1. Option A (Recommended) — what it does, and why it is the safe default here.
+2. Option B — when B applies instead, and what it costs.
 Reply with the number of your choice.
 ```
+Two rules the example above follows. `(Recommended)` goes on option 1, in the label — an operator skims labels, so a recommendation hidden in the description is a recommendation he never sees. And every option names a reason, a cost, or a consequence: a recommendation without one is a claim he can only believe or ignore.
 
 **No TaskCreate/Update**: Use plain-text checklists to track progress:
 ```

package/.cursor/rules/040-discovery.mdc

@@ -186,9 +186,9 @@ Options:
 1. [title] — [file_path]:[line] ([severity])
 
 Options:
-1. Accept all (Recommended) — create issues for all
-2. Review individually
-3. Dismiss all
+1. Accept all (Recommended) — one issue per finding. Fastest, and you can still close any of them later.
+2. Review individually — decide finding by finding. Costs about a minute per item.
+3. Dismiss all — no issues created, and the findings are gone when this session ends.
 ```
 
 ### Step 4: Batch Confirmation
@@ -196,9 +196,9 @@ Options:
 ```
 Ready to create [N] issues? ([X] critical, [Y] high, [Z] medium, [W] low)
 
-1. Create all [N] issues (Recommended)
-2. Review list first
-3. Cancel
+1. Create all [N] issues (Recommended) — the list is already filtered, so nothing here is noise. You can close any of them later.
+2. Review list first — read the titles before anything is written. Costs one extra step.
+3. Cancel — nothing is written, and this run's findings are not kept.
 ```
 
 ## Phase 5: Issue Creation

package/.cursor/rules/050-plan.mdc

@@ -29,9 +29,9 @@ If no mode specified, ask via numbered list:
 ```
 Which planning mode?
 
-1. new (Recommended) — Project kickoff (full PRD, repo setup, issue creation)
-2. feature — Feature PRD (compact scope, acceptance criteria, issues)
-3. retro — Retrospective (metrics analysis, reflection, improvement actions)
+1. new (Recommended) — Project kickoff: full PRD, repo setup, issue creation. Fits a repo that has no PRD yet.
+2. feature — One feature: compact scope, acceptance criteria, issues. Cheaper, but assumes the project context already exists.
+3. retro — Retrospective on finished work: metrics, reflection, improvement actions. Defines no new scope.
 ```
 
 ## Phase 2: Q&A Engine (Shared Core)
@@ -154,9 +154,9 @@ If any criterion fails, revise and re-review. Maximum **3 iterations**. After 3
 The PRD reviewer flagged these remaining issues:
 [list]
 
-1. Accept as-is (Recommended) — issues are minor, proceed
-2. Manual edit — I'll edit the PRD myself before continuing
-3. Re-run review — try one more revision round
+1. Accept as-is (Recommended) — the flagged issues are minor, so the PRD is usable now. You can still edit it later.
+2. Manual edit — you edit the PRD yourself before continuing. Costs a round-trip.
+3. Re-run review — one more revision round. Costs another review pass and may surface nothing new.
 ```
 
 Then present the saved PRD path and ask for final approval:
@@ -164,8 +164,8 @@ Then present the saved PRD path and ask for final approval:
 ```
 PRD saved to [path]. Ready for your review.
 
-1. Approve PRD (Recommended) — proceed to issue creation
-2. Request changes — describe what to change
+1. Approve PRD (Recommended) — proceed to issue creation. You can still edit the PRD afterwards; the issues link to it rather than copy it.
+2. Request changes — describe what to change. Costs one more revision round.
 ```
 
 ## Phase 5: Issue Creation

package/CHANGELOG.md

@@ -7,6 +7,107 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.22.0] - 2026-08-22
+
+Twenty commits (12 `fix`, 5 `docs`, 2 `feat`, 1 `chore`; 150 files, +17,312/−2,575), no
+`BREAKING CHANGE:` footer and no `!` subject. One strand runs through all of it:
+**an instrument that reported confidently and measured the wrong quantity.** Not a
+threshold set too tight, not a rule too strict — the wrong quantity, reported with the
+same certainty as the right one. The host-resource warning fired on **99.0% of 1,477
+measured session starts** and nobody could falsify it, because the two fields it was
+computed from were never persisted. A hygiene probe announced "37 files (11 MB)" while
+sizing the entire directory instead of the 37 — factor ~18 — and proposed deleting
+version-controlled source files, because it never asked git. And the questions this tool
+puts to its operator had never been measured at all: **21 of 72 passed** on first
+measurement, and the single dominant cause was a 12-codepoint header limit that silently
+truncated 30 of them.
+
+### Added
+
+- **The operator's questions are now measured before he reads them (#1107).** `scripts/auq-audit.mjs`
+  scores every `AskUserQuestion` block and every prose fallback list against eight criteria
+  (K1–K8) plus two hard hurdles, all thresholds sourced from one registry — no hard-coded
+  number in the scorer. The census found **three populations, not one**: 40 Claude Code blocks,
+  10 Codex prose lists, and 17 that every prior count had missed (9 `.cursor/rules/*.mdc` with
+  10 choice blocks, plus 6 runtime questions inside `.mjs`). Baseline **21 of 72 (29%)**, after
+  the pass **72 of 72**. The dominant cause was structural: `header` caps at 12 codepoints and
+  the tool truncates silently — **26 of 42 headers exceeded it**, and one NFD-composed header
+  measured 12 visible characters as 14, destroying the question. Population A — the operator's
+  own path — ran 62% failing against 0% for the Codex and Cursor forms, which carry no header
+  at all.
+- **A guard on the guard (#1122 groundwork).** The `AskUserQuestion` PreToolUse hook denies only
+  the two hard hurdles and reports the rest to stderr; `check-auq-clarity` is wired into
+  `validate-plugin` and blocks on H1/H2 with a measured 0% false-positive rate. Its own wiring is
+  proven by fake regression, not asserted.
+- **`/eli5`** — say the last answer again in plain words, same facts, in the order the operator
+  needs them.
+
+### Fixed
+
+- **The warning that fired on 99.0% of all session starts (#1089).** Measured over **1,477
+  `orchestrator.session.started` events across 18 repos**: `ram_free_gb < 2` fired on 84.0%,
+  `claude_processes >= 5` on 93.6%, any of the three on **99.0%** — against 4,884 stop events
+  with zero OOM markers. Three independent measurement errors, no threshold among them.
+  (a) `os.freemem()` on Darwin reports only `Pages free` — median **0.4 GB** on hosts with
+  24–128 GB — so memory is now judged on `memory_pressure_pct_free` and a better signal
+  *replaces* a worse one rather than suppressing it. (b) `concurrent-sessions-warn` is
+  denominated in sessions and was compared against a process count; measured ratio **6.0:1**.
+  Same threshold, right denominator: 93.6% → **4.2%**. (c) One noisy axis could cap a wave;
+  now two independent soft signals must agree. The verdict had reached `sessions.jsonl` for
+  **15 of 1,734 sessions (0.9%)**, which is why the false alarm survived four months while six
+  repos independently wrote it into their learnings store — one at confidence **1.0**.
+  Codified as `.claude/rules/host-resources.md` (HR-101..106).
+- **A standing condition is not a second opinion (#1089 follow-up).** The first live run of the
+  rebuilt verdict returned `warn | cap 2 | soft: ["cpu","zombies"]`. Zombie processes are idle
+  by definition — they cannot cause the load they are paired with — and are always present
+  (6, 13 and 9 in three readings minutes apart). They report; they never count toward the
+  two-signal rule.
+- **A probe that sized the wrong set and never asked git.** `checkStaleArtifacts` computed its
+  byte figure over the whole of `.orchestrator/` instead of the aged subset it names —
+  the 37 files weighed **0.68 MB against 11 MB reported**. Independently, it consulted git
+  nowhere and therefore proposed pruning seven tracked, runtime-read source files, among them
+  the policy file `pre-bash-templates-first.mjs` reads and the two steering documents
+  session-start loads. The git exclusion is fail-**silent**, not fail-open: falling back to
+  "nothing is tracked" *is* the defect it closes.
+- **Only the raw session ID releases a lock (#1085).** One session carried three identities —
+  STATE.md said `session-2`, the lock said `session-3`, issue-budget counted against a third
+  UUID — and `findPeers` reported the session's own presence as a foreign peer. The semantic
+  ID is now attribution metadata only; a release requires exact raw-ID equality, and a
+  semantic hint resolves to a raw ID only against a verified local binding. The companion fix
+  to issue-budget removed a data-loss path in which an identity-less invocation wrote its
+  fresh state into the shared counter and erased a live session's parked overflow.
+- **The npm receipt is the boundary — and a `throw` lay behind it (#1088).** `publish()` threw
+  *after* a successful `npm publish`, during a 12-second registry-propagation poll: published,
+  not tagged, not pushed, reported as "failed, retryable". Propagation now returns a typed
+  outcome, each post-receipt step gets exactly one attempt, and everything else is collected as
+  `post-publish-reconciliation`. Leak detection decides on an extracted path rather than a regex
+  over `npm notice` prose (`contest` ≠ `tests`), and `ensureGithubRelease` became tri-state so
+  an auth or network answer no longer reads as "no release exists".
+- **`--silent` leaked into the children, and the gate discarded its own diagnosis (a4f93cf).**
+- **The empty sidecar path skipped the collision gate with exit 0 (#1083).** A coordinator that
+  wrote only the aggregate form of the two-shape scope declaration ran **six waves and ~27
+  dispatches with zero `FILE-SCOPE` injection** — and the absence looked identical to a clean
+  run. `scripts/materialize-wave-scope.mjs` is now the canonical writer of both shapes.
+- **The GitLab target comes from the explicit path (#1065).** `glab repo view --output json`
+  materialised a full project response to read one field; on 2026-08-17 that response carried a
+  runner registration credential into a tool transcript. Project identity is now
+  `(host, URL-encoded namespace/project)` with traversal and double-encoding rejection, and the
+  same minimisation reached the vault-backfill path.
+- **The restore froze after its first run (#state-md).** Also: a `gitleaks` allowlist that grew
+  by one proper name per incident now matches on a word boundary instead.
+- **Four count claims where the checker could only see two (#docs-parity).** `docs/components.md`
+  claimed 46 skills and 26 commands against 47 and 27 on disk. The drift checker reported two —
+  its patterns are `^##`-anchored — while a census of the same two surfaces in the same file
+  found four; the two inside the Mermaid diagram were already self-contradictory before the fix.
+
+### Notes
+
+`.claude/rules/host-resources.md` is new and always-on. `.claude/rules/bash-harness-pitfalls.md`
+gained no rule text this line, but two measurement traps were recorded against it in the
+learnings store: `rg -rn` is not `grep -rn` (`-r` is `--replace` and silently substitutes every
+match), and zsh does not word-split an unquoted variable, so a multi-path `git log -- $paths`
+reports zero matches with exit 0 — both produce a plausible wrong number without erroring.
+
 ## [3.21.0] - 2026-08-19
 
 Twenty-one commits (12 `fix`, 4 `feat`, 4 `docs`, 1 `chore`; 209 files, +28,906/−2,893), no

package/README.md

@@ -1,7 +1,7 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.21.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.22.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-12%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
@@ -131,18 +131,18 @@ The system is markdown-driven config plus a thin Node runtime — skills, comman
 - **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.
 
-## Recent highlights (v3.21.0)
+## Recent highlights (v3.22.0)
 
-Every release is additive and backward-compatible. Highlights of the v3.21.0 line:
+Every release is additive and backward-compatible. Highlights of the v3.22.0 line:
 
-- **The site that proves its own numbers (#1043–#1046)** — the live page had served v3.19.0 against v3.20.0 in the repo for six days, all five legal paths were 404, and the `Measured` block — the honesty argument of the whole page — carried five wrong numbers. It is now generated: `scripts/site-numbers.mjs` reads **13 metrics** from the repo into `data-metric` spans, and its very first run caught three real errors, one of them the coordinator's own (`skills: page says 47, repo says 46`) and one a contract defect that would have shipped `vv3.20.0` at the next release. Deploy config moved from a dashboard into a versioned `vercel.json`. Rendered height fell to **52.4%** of the old page (10,350 → 5,428px), and mobile navigation — previously `display:none` with no hamburger — exists.
-- **The documented Claude Code install path was guaranteed broken** — `claude plugin dir` is not a subcommand; it exits 1, the fallback path does not exist, `cd` fails, `npm install` never runs, and every hook afterwards cannot find `zx`. Measured on Claude Code 2.1.235. That is the cause behind external issues #62/#63, whose reporters described the symptom — and **all four issues opened by people outside this repo are install or environment failures, not one a feature request**. The replacement was extracted from the shipped HTML, entity-decoded and executed verbatim.
-- **The scope guard shipped the instructions for its own disarmament (#1057)** — the stale-manifest denial ended on ``remove it with `rm -f <path>` ``, and that string travels in `permissionDecisionReason` into the context of the agent just denied. `rm -f` is not blocked (14 rules, only `rm-rf-destructive` bites), and with the manifest gone both allowedPaths **and** project-root containment fall. A parallel session in the same working copy received this suggestion for the live manifest of this one, and declined on an indicator rather than on knowledge.
-- **Two dead instruments, found by measuring rather than reading** — the v2 vault renderer's branch condition was **structurally false from its first commit** and matched **0 of 253** session records; the obvious fix would have been worse than the bug, because `agents` is polymorphic (210× a number, 14× an array over 599 wave objects) and a naive `??` would have written `[object Object]` into the vault. And `scanBacklog` read 50 of 89 open issues while reporting the window nowhere: `critical 0, high 10, stale 0` where the truth was `1 / 18 / 5`.
-- **Cross-session messaging is wired (Epic #1048, waves 1–2)** — a new always-on rule with CSM-001..005, and a peer-inform branch hung **below** the sibling check in the PSA decision tree so it can mask neither that branch nor the PSA-002 pause. The moat was never "peer sessions cannot talk to each other" — they demonstrably can — it is that they share one working copy, and what crosses the channel is information, never isolation.
-- **Guards that were green without biting** — the owner-leakage scanner did not read `.html` at all; admitting the class immediately found a live `U+00AD` breaking a word visibly on a legally required page. `harness-audit` category 6 awarded **2/2** outside a git repository. Six consecutive CI pipelines were red because a test depended on untracked ledger files: locally 23/23, on CI `23 tests | 23 skipped`. Each is now closed by a mechanism, and the review panel found further holes inside the fixes themselves — including one fail-open state inside the fix that was closing fail-open.
+- **The warning that fired on 99.0% of all session starts (#1089)** — measured over **1,477 session-start events across 18 repos**, against 4,884 stop events with zero OOM markers. Three independent measurement errors, not one threshold among them: `os.freemem()` on Darwin reports only `Pages free` (median **0.4 GB** on hosts with 24–128 GB installed), a threshold named for *sessions* was compared against a *process* count (measured ratio **6.0:1** — same number, right denominator: 93.6% → **4.2%**), and one noisy axis could cap a wave alone. The verdict had reached the ledger for **15 of 1,734 sessions (0.9%)**, which is why the false alarm survived four months while six repos independently wrote it into their learnings store — one at confidence **1.0**. A warning that fires on almost everything changes nothing except how fast you learn to ignore it.
+- **The questions this tool asks its operator had never been measured (#1107)** — `scripts/auq-audit.mjs` now scores every choice block against eight criteria and two hard hurdles, all thresholds from one registry. The census found **three populations where every prior count had seen one**: 40 Claude Code blocks, 10 Codex prose lists, and 17 nobody had counted. Baseline **21 of 72 (29%)**, after the pass **72 of 72**. The dominant cause was structural rather than editorial — `header` caps at 12 codepoints and truncates silently, **26 of 42 exceeded it**, and one NFD-composed header measured 12 visible characters as 14 and destroyed its own question.
+- **A probe that sized the wrong set and never asked git** — `checkStaleArtifacts` announced "37 files (11 MB)" while computing the megabytes over the entire directory instead of the 37 it names; they weigh **0.68 MB**, a factor of ~18. Separately it proposed pruning seven **tracked, runtime-read** source files, including the policy file a hook reads on every Bash call. The git exclusion is fail-**silent**, not fail-open: falling back to "nothing is tracked" *is* the defect it closes.
+- **Only the raw session ID releases a lock (#1085)** — one session carried three identities (STATE.md, the lock, and issue-budget each held a different one) and `findPeers` reported the session's own presence as a foreign peer. The companion issue-budget fix removed a data-loss path where an identity-less invocation erased a live session's parked overflow.
+- **The npm receipt is the boundary, and a `throw` lay behind it (#1088)** — `publish()` threw *after* a successful publish during a 12-second propagation poll: published, not tagged, not pushed, reported as "failed, retryable". Each post-receipt step now gets exactly one attempt and the rest is collected as reconciliation. Leak detection decides on an extracted path, not a regex over `npm notice` prose — `contest` is not `tests`.
+- **Six waves ran with zero scope injection, and it looked exactly like a clean run (#1083)** — the scope declaration has two shapes; a coordinator that writes only the aggregate one degrades the chain to signal-free ALLOW. `scripts/materialize-wave-scope.mjs` is now the canonical writer of both.
 
-Previous line (v3.20.0): the memory pipeline — 233 sessions of learnings that reached no agent (#1014), agent-authored text neutralised at the render point (#1015), and a learning store made durable after 11 of 13 provenance pointers resolved to nothing (#1017).
+Previous line (v3.21.0): guard mechanics, the public site, and cross-session messaging — which turned out to be one strand: a fact maintained in two places, and a guard that is green without biting.
 
 Full version history: [CHANGELOG.md](CHANGELOG.md).
 

package/agents/memory-proposal-collector.md

@@ -135,8 +135,8 @@ and `{{options}}` at render time.
 ```
 AskUserQuestion({
   questions: [{
-    header: "Memory — Confirm Proposals (Batch {{N}} of {{M}})",
-    question: "Select the learnings you want to store permanently. Unselected proposals will be archived as declined.",
+    header: "Memory",
+    question: "Batch {{N}} of {{M}} — which learnings should be stored permanently? Unselected ones are archived as declined.",
     options: [
       // one entry per proposal in this batch — see label format below
       { label: "{{label}}", description: "{{description}}" },
@@ -147,12 +147,14 @@ AskUserQuestion({
 })
 ```
 
-**When there is only one batch** (`M === 1`), omit the batch suffix:
+**When there is only one batch** (`M === 1`), omit the batch prefix from the question:
 
 ```
-header: "Memory — Confirm Proposals"
+question: "Which learnings should be stored permanently? Unselected ones are archived as declined."
 ```
 
+`header` stays `"Memory"` in both cases: the field is cut off after 12 characters, so anything longer never reaches the operator.
+
 ### Option label format
 
 Locked by D3 (Wave 1 decision):

package/commands/eli5.md

@@ -0,0 +1,33 @@
+---
+description: Say the last answer again in plain words — same facts, in the order the operator needs them. Optional topic argument.
+argument-hint: "[topic]"
+---
+
+# eli5
+
+Invokes the `eli5` skill (`skills/eli5/SKILL.md`). Restates my last substantial output — or the named topic — for someone who knows this project but did not watch the last ten minutes of it.
+
+## Argument Validation
+
+The optional argument is a topic, in prose. If absent, the target is my own last substantial output in this conversation; if there is none yet, say so rather than picking a topic for him.
+
+Examples:
+- `/eli5` — restate what I just said
+- `/eli5 warum ist der Regel-Korpus voll?` — explain that, grounded in what this session measured
+
+## Behavior
+
+1. **Resolve the target** — last output, or `$ARGUMENTS`.
+2. **Ground it** — prefer what this session already measured over recall, and name where it came from. Never measured here → say so.
+3. **Restate** — consequence first (*must I act, and what if I don't?*), then the facts in the order he needs them.
+4. **Check before sending** — every greppable token from the original still present; every noun the system does not contain gone.
+
+## The limit that outranks the command
+
+**Simplifying removes words, never facts.** A dropped path, number, error code, identifier, or instruction to act is data loss, not simplification — `skills/session-start/soul.md` § "Never traded for brevity" outranks brevity here as everywhere. And no invented pictures: say what happens, never what it is "like".
+
+## Related
+
+- `skills/eli5/SKILL.md` — the skill, in full
+- `.claude/rules/ask-via-tool.md` § AUQ-006 — plain words, real things
+- `skills/session-start/soul.md` § Register — the canonical register statement

package/commands/release.md

@@ -32,13 +32,13 @@ The same reading shows the other half: the GitHub releases for 3.15/3.18/3.19/3.
 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.** Not on its predecessor. A green pipeline from before step 5's commit is evidence about a different tree.
-7. **Publish.** `node scripts/release.mjs --publish` — publishes, verifies the registry, tags **after** the verified publish, pushes `main` + tag to both remotes, then polls the live site. 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.
+7. **Publish.** `node scripts/release.mjs --publish` — 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.
 
 ## Abort criteria
 
-Stop and report. Do not work around, do not "fix it after the publish" — an npm publish is not revocable.
+**Before a target-confirmed npm publish receipt:** stop and report. Do not work around, do not "fix it after the publish" — an npm publish is not revocable.
 
 | Signal | Why it stops the release |
 |---|---|
@@ -51,7 +51,9 @@ Stop and report. Do not work around, do not "fix it after the publish" — an np
 
 ## After
 
-`--publish` prints the remaining manual items (token rotation, async gallery indexing). Rotate the npm token — write tokens are short-lived by policy, and a token that transited a log or a chat is burned.
+`--publish` reports either **Release complete** or **Post-publish reconciliation required**. The latter means npm accepted the target release but registry propagation, tag/push, GitHub-release handling, or the live-site check still needs repair; a tag/push failure explicitly skips its dependent GitHub-release and site steps. **Do not rerun `--publish`**: reconcile the listed state directly, because a second publish cannot replace the immutable version. Exit `1` means a preflight/check failure or post-publish reconciliation is required; exit `2` remains a system/usage failure before the receipt.
+
+After a complete release, `--publish` prints the remaining manual items (token rotation, async gallery indexing). Rotate the npm token — write tokens are short-lived by policy, and a token that transited a log or a chat is burned.
 
 ## See Also
 

package/commands/test.md

@@ -59,9 +59,9 @@ Present the user with a structured choice via `AskUserQuestion`:
 AskUserQuestion({
   questions: [{
     question: "Which test profile should be run?",
-    header: "Test Command: profile selection",
+    header: "Profil",
     options: [
-      { label: "smoke (Recommended)", description: "Quick sanity pass — key flows, axe critical/serious, console errors." },
+      { label: "smoke (Recommended)", description: "Quick sanity pass — key flows, axe critical/serious, console errors. The fastest of the four; run it first." },
       { label: "full", description: "All checks at full depth — slower, used before release." },
       { label: "a11y", description: "Accessibility-focused pass — axe-core exhaustive scan." },
       { label: "onboarding", description: "Onboarding step-count + Liquid Glass conformance checks." }

package/docs/components.md

@@ -7,8 +7,8 @@ Detailed component inventory and architecture reference for Session Orchestrator
 ```mermaid
 flowchart LR
     USER([Operator]) -->|invokes /session| COORD[Coordinator]
-    COORD -->|reads| SK[Skills<br/>46 user-facing]
-    COORD -->|invokes| CMD[Commands<br/>25 slash-cmds]
+    COORD -->|reads| SK[Skills<br/>47 user-facing]
+    COORD -->|invokes| CMD[Commands<br/>27 slash-cmds]
     COORD -->|dispatches| AG[Agents<br/>15 typed sub-agents]
     AG -.->|parallel waves| W1[code-implementer]
     AG -.-> W2[test-writer]
@@ -18,7 +18,7 @@ flowchart LR
     COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
 ```
 
-## Skills (46 user-facing)
+## Skills (47 user-facing)
 
 - **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
 - **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`, `contract-version-bump`
@@ -29,11 +29,12 @@ flowchart LR
 - **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `spinout`, `npm-publish`
 - **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`
 - **Content review:** `persona-panel`
+- **Operator ergonomics:** `eli5` (plain-language restatement of the last answer)
 - **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))
 
-## Commands (25)
+## Commands (27)
 
-`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/contract-version-bump`.
+`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/contract-version-bump`, `/eli5`.
 
 ## Agents (15 typed sub-agents)
 

package/docs/scope-collision-guard.md

@@ -1,7 +1,7 @@
 # Scope-Collision Guard — Pre-Dispatch File-Scope Deconfliction
 
 > Reference for the mechanism that stops a wave from handing the SAME file to two agents (issue #1020).
-> Four moving parts: the per-agent scope files, `scripts/validate-wave-scope.mjs` (`--assert-disjoint` / `--union`), `findScopeCollisions()` + `unionFileScopes()` in [`scripts/lib/scope-gate.mjs`](../scripts/lib/scope-gate.mjs), and the `PreToolUse` hook [`hooks/pre-task-scope-disjoint.mjs`](../hooks/pre-task-scope-disjoint.mjs).
+> Five moving parts: `scripts/materialize-wave-scope.mjs` (the canonical declaration writer), the per-agent scope files, `scripts/validate-wave-scope.mjs` (`--assert-disjoint` / `--union`), `findScopeCollisions()` + `unionFileScopes()` in [`scripts/lib/scope-gate.mjs`](../scripts/lib/scope-gate.mjs), and the `PreToolUse` hook [`hooks/pre-task-scope-disjoint.mjs`](../hooks/pre-task-scope-disjoint.mjs).
 > The coordinator-side **runbook** is `skills/wave-executor/wave-loop.md` § Scope Manifest 3.1–3.3 — this document does not restate it. What lives here instead: how the mechanism works, how it fails, what it deliberately does not see, and how to debug it.
 
 ## 1. What the pre-existing gates could not see
@@ -17,8 +17,8 @@ Two things follow, and both are the point of #1020:
 
 | # | Step | Artefact | Mechanism |
 |---|------|----------|-----------|
-| 1 | Declare | `<state-dir>/filescopes/wave-<N>/<agent-id>.json` (one per agent, plus `coordinator.json`) | written verbatim from the session plan |
-| 2 | Assert disjointness | the sidecar array `[{id, files}, …]` | `validate-wave-scope.mjs --assert-disjoint` → `findScopeCollisions()` |
+| 1 | Materialize declarations | `<state-dir>/filescopes/wave-<N>/<agent-id>.json` (one per agent, plus `coordinator.json`) and `<state-dir>/filescopes/wave-<N>.scopes.json` | one canonical `[{id, files}, …]` stdin array → `materialize-wave-scope.mjs` |
+| 2 | Assert disjointness | the materialized sidecar array `[{id, files}, …]` | `validate-wave-scope.mjs --assert-disjoint` → `findScopeCollisions()` |
 | 3 | Compute the union | stdout of `--union` → `allowedPaths` | `expandTestSiblings(unionFileScopes(scopes), { role })` |
 | 4 | Inject | `FILE-SCOPE — exactly these:` + a fenced block in each agent prompt | the per-agent file from step 1 |
 | 5 | Dispatch | `.orchestrator/wave-dispatch-scopes.json` (ledger) | `hooks/pre-task-scope-disjoint.mjs`, `PreToolUse` matcher `Agent` |

package/docs/session-config-reference.md

@@ -423,7 +423,7 @@ Introduced by Epic #157 / issue #166. Lets session-start sense the host (RAM, CP
 |-------|------|---------|-------------|
 | `resource-awareness` | boolean | `true` | Master toggle for the env-aware runtime. When `false`, skips Phase 4.5 adaptive wave sizing and the host banner. |
 | `enable-host-banner` | boolean | `true` | Whether `hooks/on-session-start.mjs` emits the host + resource banner at the top of every session. Set `false` to silence. |
-| `resource-thresholds` | object | see below | Numeric thresholds that drive Phase 4.5 adaptive rules. Unset sub-keys fall back to defaults. Sub-keys: `ram-free-min-gb`, `ram-free-critical-gb`, `cpu-load-max-pct`, `concurrent-sessions-warn`, `ssh-no-docker`, `zombie-threshold-min`. |
+| `resource-thresholds` | object | see below | Numeric thresholds that drive Phase 4.5 adaptive rules. Unset sub-keys fall back to the single canonical default set (`DEFAULT_RESOURCE_THRESHOLDS` in `scripts/lib/resource-probe/evaluate.mjs`). Sub-keys: `ram-free-min-gb`, `ram-free-critical-gb`, `cpu-load-max-pct`, `concurrent-sessions-warn`, `ssh-no-docker`, `zombie-threshold-min`. |
 
 ### resource-thresholds
 
@@ -431,17 +431,40 @@ Sub-key defaults:
 
 ```yaml
 resource-thresholds:
-  ram-free-min-gb: 4            # below this, cap agents-per-wave at 2
-  ram-free-critical-gb: 2       # below this, recommend coordinator-direct
-  cpu-load-max-pct: 80          # sustained above this, cap agents-per-wave at 2
-  concurrent-sessions-warn: 5   # warn when host has this many Claude sessions
+  ram-free-min-gb: 4            # soft memory signal (see precedence below)
+  ram-free-critical-gb: 2       # hard memory signal → coordinator-direct
+  cpu-load-max-pct: 90          # soft CPU signal, judged on min(1m, 5m)
+  concurrent-sessions-warn: 5   # soft signal at this many live peer SESSIONS
   ssh-no-docker: true           # when session is over SSH, steer the plan away from Docker-based tests
   zombie-threshold-min: 30      # age (minutes) above which an idle Claude/Node process is a zombie candidate
 ```
 
-**`zombie-threshold-min`** (default: `30`): When set, the resource probe runs a secondary `ps` pass that counts Claude and Node processes older than this many minutes **and** with CPU% ≤ 1%. These are "zombie candidates" — stale sessions or orphaned workers that still hold RAM. The probe exposes them via `zombie_processes_count` in the snapshot. The evaluator escalates the verdict to at least `warn` when `zombie_processes_count >= 1` **and** `claude_processes_count > 0` (i.e., there are active Claude processes alongside the zombies). The reason string surfaces the threshold and count so the session-start banner gives actionable context. Set to `0` to disable zombie detection entirely (the field is omitted from the default snapshot when absent from config).
-
-Rationale: originated from the 2026-04-19 incident where 8 parallel Claude sessions on one Mac caused a hard freeze. The adaptive rules cap concurrent agent load when the host is under pressure, before a wave ever spawns subagents. See Epic #157 and Sub-Epic #158.
+**No single threshold caps a wave (#1089).** A cap requires either one *hard*
+signal (→ `critical`, coordinator-direct) or **two independent soft signals**
+agreeing (→ `warn`, cap 2). One soft signal alone is reported and acted on by
+nobody. Rationale and the measured firing rates are in
+[`.claude/rules/host-resources.md`](../.claude/rules/host-resources.md); the full
+rule table is in `skills/session-start/phase-4-5-resource-health.md`.
+
+**What the memory thresholds are compared against** is chosen by precedence, not
+by configuration: `memory_pressure_pct_free` (macOS, hard `<15%` / soft `<30%`)
+outranks `ram_available_gb`, which outranks `ram_free_gb`. The two GB-denominated
+keys above therefore apply to *available* RAM on macOS and to `os.freemem()` on
+Linux/Windows, where it is accurate. They are never compared against Darwin's
+`Pages free`, whose median across 1477 measured session starts was **0.4 GB** on
+hosts with 24-128 GB installed — gating on it fired `ram-free-critical-gb` on
+84.0% of all starts.
+
+**`concurrent-sessions-warn` counts SESSIONS, not processes.** The live count
+comes from the session registry (`detectPeers()` — self excluded,
+heartbeat-fresh). Until #1089 it was compared against `claude_processes_count`, a
+measured 6x unit error (median processes:sessions = 6.0) that fired the threshold
+on 93.6% of starts instead of 4.2%. When the registry is unreadable the probe
+falls back to the process count rescaled by that same factor.
+
+**`zombie-threshold-min`** (default: `30`): When set, the resource probe runs a secondary `ps` pass that counts Claude and Node processes older than this many minutes **and** with CPU% ≤ 1%. These are "zombie candidates" — stale sessions or orphaned workers that still hold RAM. The probe exposes them via `zombie_processes_count` in the snapshot. Since #1089 this is a *soft* signal: it is reported when `zombie_processes_count >= 1` **and** there is a live peer/process context, but on its own it caps nothing — sweeping stale sessions is housekeeping advice, not a reason to shrink a wave. The reason string surfaces the threshold and count so the session-start banner gives actionable context. Set to `0` to disable zombie detection entirely (the field is omitted from the default snapshot when absent from config).
+
+Rationale: originated from the 2026-04-19 incident where 8 parallel Claude sessions on one Mac caused a hard freeze. That hazard is real and the rules still escalate for it — what #1089 changed is that they now recognise it, instead of reporting it on 99.0% of session starts where it was not happening. See Epic #157, Sub-Epic #158, and `.claude/rules/host-resources.md`.
 
 ### isolation graduation
 

package/hooks/_lib/lock-bootstrap.mjs

@@ -15,8 +15,8 @@
  *
  * Schema v2 (Epic #583 D4 #587):
  *   {
- *     session_id:           string,  // semantic OR UUID — whatever resolveSessionId returned
- *     semantic_session_id:  string,  // ALWAYS the semantic form (closes D4)
+ *     session_id:           string,  // native raw identity OR generated UUID; sole live lock/registry ownership key
+ *     semantic_session_id:  string,  // attribution/history label only; never ownership
  *     started_at:           ISO,
  *     last_heartbeat:       ISO,     // basis for liveness; replaces PID-liveness checks
  *     mode:                 string,  // "deep"|"feature"|"housekeeping"|"session"|...
@@ -47,10 +47,12 @@ import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
  *
  * @param {object} opts
  * @param {string} opts.repoRoot — absolute path to the repository root.
- * @param {string} opts.sessionId — the resolved session id (semantic OR UUID).
- * @param {string} [opts.semanticSessionId] — the semantic form, ALWAYS surfaced
- *   even when sessionId is a UUID (closes D4 issue #587). When omitted, the
- *   field is populated by mirroring sessionId.
+ * @param {string} opts.sessionId — the physical raw session id from the native
+ *   harness, or a generated UUID when no trustworthy raw id exists. This is the
+ *   only live lock/registry ownership key.
+ * @param {string} [opts.semanticSessionId] — the semantic attribution/history
+ *   label, surfaced separately and never used for ownership. When omitted, the
+ *   field is populated by mirroring sessionId for backward-compatible display only.
  * @param {string} opts.mode — session mode (e.g. "deep", "feature").
  * @param {number} [opts.ttlHours=4] — lock TTL in hours.
  * @param {Function} [opts._acquireImpl] — DI for tests (defaults to importing acquire from session-lock.mjs).
@@ -88,9 +90,10 @@ export async function bootstrapLock({
 
   // Step 1: try to acquire. If a fresh acquire succeeds, we are done.
   // If a stale-PID-dead/-alive lock exists, force-overwrite it (the prior
-  // session has died; we own the worktree now).
-  // If the existing lock has the same sessionId, force-overwrite so the
-  // last_heartbeat gets refreshed.
+  // session has died; the current raw owner can take the worktree).
+  // Only an exact match of the existing physical raw sessionId permits the
+  // same-session force-refresh. semantic_session_id, STATE.md `session`, and
+  // an owner proof never make a different raw id the same owner.
   let acquireResult;
   try {
     // quiet: true suppresses the unknown-mode stderr WARN in acquire() (#592 MED-2).
@@ -169,9 +172,10 @@ export async function bootstrapLock({
     // last_heartbeat is the basis for liveness — set to started_at on bootstrap
     // so an immediate liveness check (< ttl_hours from now) succeeds.
     last_heartbeat: startedAt,
-    // semantic_session_id is ALWAYS the semantic form, even when session_id is
-    // a UUID-v4 (closes D4 #587). Fallback to mirroring session_id if no
-    // semantic was provided.
+    // semantic_session_id is an attribution/history label, normally semantic
+    // even when the physical session_id is a UUID-v4. Fall back to mirroring
+    // session_id only for backward-compatible display when no label was provided;
+    // it never changes the raw ownership key.
     semantic_session_id:
       typeof semanticSessionId === 'string' && semanticSessionId.length > 0
         ? semanticSessionId
@@ -190,7 +194,9 @@ export async function bootstrapLock({
   // Step 2b (#987 Part 1): persist the durable ownership proof at lock
   // genesis. `enriched` is byte-identical to the on-disk lock at this point
   // (the v2 overlay never touches pid/host/started_at), so the proof written
-  // here will verify via isLockOwnedByProof() against any later re-read.
+  // here will verify via isLockOwnedByProof() against any later re-read. The
+  // proof is supplementary evidence only: it never bridges a raw-id mismatch
+  // through semantic_session_id or STATE.md `session` equality.
   // This single call covers BOTH the plain-acquire and the forceAcquire
   // branch — both flow through the enriched write above. Best-effort like
   // the surrounding breadcrumb writes: writeOwnerProof() is no-throw by

package/hooks/hooks-codex.json

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