session-orchestrator 5.0.0 → 5.1.0

package/docs/events-schema.md

@@ -103,6 +103,7 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.wave.started` / `.completed` | `hooks/post-tool-batch-wave-signal.mjs` · `hooks/on-session-end.mjs` (`emitFinalWaveCompleted`, `.completed` only) | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612); an explicit injected `wave_signal` still takes precedence. **Second `.completed` emitter (#1193):** the batch hook closes wave N-1 only at an N-1→N transition, so the LAST wave of every session never received a completion — measured fleet-wide 2026-09-02 as **296 gaps over 296 wave runs** (1018 started vs 722 completed), exactly one missing final completion per run. SessionEnd now emits it. **Payload of that record:** `wave_number` (the `current-session.json` `last_wave`), `reason: 'session-end'`, `emitted_by: 'on-session-end'`, plus `session_id` / `semantic_session_id` — **omitted when unattested**, never fabricated. **Idempotent** via the `last_wave_completed` high-water mark in `.orchestrator/current-session.json`, written by BOTH emitters and preserved across `/clear`+compact by `on-session-start.mjs`; `last_wave` absent or `0` emits nothing (an Express-Path or coordinator-direct session never batched, and zero waves is the correct reading, not a gap). **Two gates on the SessionEnd emitter, both load-bearing:** (a) OWNERSHIP — `current-session.json` is a single repo-global file describing whichever session most recently ran SessionStart, routinely a different still-live session in a shared working copy, so the emit reuses `resolveSession()`'s `isRecordedSession` predicate; when false it emits nothing AND writes nothing, since writing the marker into a peer's file would silence the peer's own SessionEnd and preserve this very gap on the wrong session. (b) REASON — `reason === 'clear'` **and `reason === 'resume'`** are SKIPPED: the SessionEnd matcher is empty, so `/clear` fires the hook mid-wave while the LOGICAL session continues, and `on-session-start.mjs` preserves `last_wave` / `last_wave_completed` across a resume of the SAME logical session exactly as it does across a clear — so both end the HARNESS session, not the logical one. Closing the live wave on either is premature, and the preserved marker would then suppress the real completion later. Resume is the MORE common of the two (fleet n = 1498 `session.ended`, 2026-09-02: 12 `resume` vs 9 `clear`). Deliberately SessionEnd-only (`on-stop.mjs` is not mirrored) so the closed-vs-abandoned split stays measurable. **Diff-size keys on the BATCH-HOOK emitter only (#980):** `files_changed` (integer) + `files_changed_source: 'worktree-vs-wave-start-sha'` (the only value emitted today; present iff `files_changed` is). Measurement: the DEDUPED union of `git diff --name-only <wave_start_sha>` and `git ls-files --others --exclude-standard`, run in the project dir at the N→N+1 transition, where `wave_start_sha` is the `git rev-parse HEAD` the batch hook persisted into `.orchestrator/current-session.json` when wave N was OPENED (same ownership gate as the wave keys; written as `null` when git is unreadable, so a previous wave's sha can never inflate the next count). Worktree-vs-sha rather than `<sha>..HEAD` because the coordinator commits at session close, not per wave — a commit-only diff reads 0 for every wave of a normal session. **Both keys are OPTIONAL and absent-is-not-zero:** any git failure, a 1.5 s timeout, or a missing `wave_start_sha` omits them, and `scripts/lib/convergence-monitor.mjs` reads an absent key as `null`, so the `shrinking_diff` signal simply does not fire (it never reads a fabricated 0). The `on-session-end.mjs` final-wave `.completed` carries NEITHER key by design — no wave-open transition runs there, so it has no start sha to measure against |
 | `orchestrator.wave.final_refused` | `hooks/on-session-end.mjs` (`emitFinalWaveCompleted` → `emitFinalRefused`, via `emitEvent(..., {repoRoot})` + `sessionAttribution(repoRoot)`, wrapped in its OWN try/catch — independent of the caller's outer catch — so a telemetry failure on one refusal can never surface as a teardown failure) | the SIBLING event to `orchestrator.wave.completed` above (#1201 Part B / Discovery D8) — fires exactly once per SessionEnd in which the final `.completed` was NOT emitted, one row per refusal. Deliberately a SEPARATE event name rather than `.completed` carrying `emitted:false`: existing consumers of `.completed` treat every row as a finished wave, and overloading it would silently corrupt that count. **Payload:** `reason` (always present, closed enum — verified against `emitFinalWaveCompleted`'s own call sites) `not-recorded` \| `clear` \| `resume` \| `unreadable` \| `session-id-mismatch` \| `no-wave` \| `already-completed` \| `exception`, `emitted_by: 'on-session-end'` (always), plus `session_id` / `semantic_session_id` — omitted when `null`, never fabricated. **Optional, absent-is-not-zero:** `wave_number` — present ONLY on the `already-completed` reason, the sole call site that passes a resolved `last_wave` through to `emitFinalRefused`; every other reason, INCLUDING `no-wave`, omits it (that path never resolved a wave number at all — the function's own JSDoc pins this: "only when `last_wave` was resolved to a positive number before the refusal (currently only `already-completed`)"). Six of the eight reasons were previously SILENT refusal paths with no trace anywhere (`.claude/rules/host-resources.md` § HR-105: "a refusal that writes nothing is unfalsifiable") |
 | `orchestrator.quality_gate.passed` / `.failed` | `scripts/run-quality-gate.mjs` (the gate CLI — live between waves) · `scripts/lib/quality-gate.mjs` (`emitGateEvent` inside `runQualityGateWithRetry`, reached ONLY under `verification-auto-fix.enabled: true` — default `false`, and `false` in this repo) | CLI: once per gate-CLI run. Library: once per `runQualityGateWithRetry` **call**, never per retry attempt (`attempts` carries that detail). The two paths never nest, so one run passes through exactly one emitter. **Payload (both):** `variant`, `exit_code`, plus `session_id` / `semantic_session_id` when `sessionAttribution()` finds a session lock (both omitted when it does not). CLI `variant` is the `--variant` value (`baseline`\|`incremental`\|`full-gate`\|`per-file`); the library pins `variant: 'auto-fix-loop'`. **CLI only:** `wave_number`. **Library only:** `attempts` (1…`maxRetries+1`) and `gate` (`lint`\|`typecheck`\|`test` — the fail-fast gate of the last attempt; omitted on the passing path). **Optional on both:** `counts: {passed, failed, total}`. **Absent is not zero — for both optional fields.** `counts` is admitted by the ONE shared policy `admitSuiteCounts()` (`scripts/lib/gates/gate-helpers.mjs`, #967 item 2), which returns `null` — never a zero triple — for an unmeasured or inconsistent input (test gate skipped/stubbed, fail-fast on lint or typecheck before the test step, no parseable `<N> passed` marker, or `passed + failed !== total`); both callers spread `...(counts ? { counts } : {})`, so the KEY is missing in those runs. A present `counts.failed: 0` therefore means "measured, zero failures", while an absent `counts` means "not measured" — reading a missing field as `0` mis-analyses the ledger in both directions. Same contract for `wave_number` (CLI, #966 step 1): resolved from the `.{pi,cursor,codex,claude}/wave-scope.json` sidecar, **omitted** — never `0` — when there is no sidecar or its `wave` is non-numeric/non-positive; a human running `npm run quality-gate` from a `git push` has no wave at all, so an invented wave 0 would have to be special-cased by every consumer. Note `total` is `passed + failed` and EXCLUDES skipped/todo (see `extractTestCounts`) |
+| `orchestrator.scope.coordinator_carveout_allowed` | `hooks/enforce-scope.mjs` (coordinator carveout, #245 / #1361) | exactly once per ALLOWED write BY THE COORDINATOR into one of the harness-owned in-repo files the carveout covers — `.claude/STATE.md` and its `.codex/` / `.cursor/` / `.pi/` siblings, plus the exact relative path of the live `wave-scope.json` the hook itself just read. Since #1361 a payload carrying `agent_id` is a dispatched subagent: it gets no carveout and falls through to Gate 7, where a manifest that does not grant the path is a DENY (a subagent permitted to write `wave-scope.json` could rewrite its own file scope and disarm every later gate of the wave; STATE.md is coordinator-owned per `skills/_shared/state-ownership.md`). **Payload:** `hook`, `manifest` (the manifest path), `wave`, `file_path` (the project-RELATIVE, forward-slash-normalized path — the carveout set is in-repo by construction, so no host-local absolute path enters the ledger) and `discriminator` (`'coordinator' \| 'malformed' \| 'absent'` — same enum and same meanings as `orchestrator.scope.memory_dir_allowed`: `'coordinator'` = `agent_type` present without `agent_id`; `'malformed'` = an `agent_id` key present but unusable (number, object, array, blank string), a fail-open that must stay rare; `'absent'` = no `agent_id` key at all, the harness's documented main-thread shape. `'subagent'` never appears here BECAUSE a subagent gets no carveout and so emits no allow) — exactly the five keys the `emitEvent` call passes, with `{ repoRoot: projectRoot }` as options. **Fail-safe:** awaited BEFORE `emitAllow()` (which calls `process.exit()` and would discard a pending append) and wrapped in its own `try {} catch {}`, so a telemetry failure can never flip the decision. Before #1361 this branch was a bare `emitAllow()` with no log and no event, so whether it ever fired was unfalsifiable after the fact (HR-105) | <!-- path-check: example -->
 | `orchestrator.scope.foreign_session_ignored` | `hooks/enforce-scope.mjs` (Gate 3b, #1123) · `hooks/enforce-commands.mjs` · `hooks/post-bash-write-verify.mjs` (both Gate 3b, #1153 P1) | exactly once per gated tool call while a FOREIGN-session `wave-scope.json` is live: the manifest's `session_id`/`semantic_session_id` provably name another session (legacy `session`/`semantic_session` still read, #1153 P2), so the hook stands down instead of enforcing. **Payload:** `hook`, `manifest` (path), `manifest_session` (string[]), `own_session` (string[]), `wave`; additionally `file_path` from `enforce-scope` (PreToolUse Edit/Write) and `command` from `enforce-commands` (PreToolUse Bash). `post-bash-write-verify` (PostToolUse Bash) carries neither — it reports on the working tree, not on one tool input. Legacy manifests without a session-binding field never emit this — they stay enforced |
 | `orchestrator.scope.memory_dir_allowed` | `hooks/enforce-scope.mjs` (Gate 5c, #1295) | exactly once per ALLOWED write BY THE COORDINATOR (#1352 — a payload carrying `agent_id` is a dispatched subagent, gets no carve-out and falls through to the normal gates) into THIS repo's harness auto-memory directory `~/.claude/projects/<encodeProjectDir(repoRoot)>/memory/` — the single out-of-repo carveout, evaluated only on the out-of-root branch (Gate 6) and only when a `wave-scope.json` manifest is live, so the in-repo gates are untouched. **Payload:** `hook`, `manifest` (the manifest path), `wave`, `file_path` (the REALPATH-resolved candidate) and, since #1352, `discriminator` (`'coordinator' \| 'malformed' \| 'absent'` — `'coordinator'` = `agent_type` present without `agent_id`; `'malformed'` = an `agent_id` key present but unusable (number, object, array, blank string), a fail-open that must stay rare; `'absent'` = no `agent_id` key at all, the harness's documented main-thread shape. `'subagent'` never appears here BECAUSE a subagent gets no carve-out and so emits no allow) — exactly the five keys the `emitEvent` call passes, with `{ repoRoot: projectRoot }` as options. **Fail-safe:** awaited BEFORE `emitAllow()` (which calls `process.exit()` and would discard a pending append) and wrapped in its own `try {} catch {}`, so a telemetry failure can never flip the decision. This row is the audit trail for the carveout: it is the only place an out-of-repo ALLOW becomes measurable after the fact |
 | `orchestrator.scope.unbound_manifest` | `scripts/wave-scope-binding.mjs` (#1153 P4) | wave-executor § Scope Manifest, when the binding step resolves to `{}` — `attributionForRecord()` found no `.orchestrator/session.lock`, or the lock's `session_id` did not match this process's own identity, so the manifest about to be written names NOBODY. **Payload:** `wave` (number\|string\|null), `role` (string\|null), `reason` (currently only `no-confirmed-session-attribution`). Exactly one per invocation, and only on the unbound path — a bound binding emits nothing. An unbound manifest is the FAIL-CLOSED direction (it enforces against every session in the checkout) and is therefore otherwise silent; this event is what makes it countable instead of indistinguishable from a coordinator who skipped the step |

package/docs/install.md

@@ -0,0 +1,112 @@
+# Install, Upgrade, Uninstall
+
+Everything the README's short install block leaves out: the full requirement
+matrix, the per-harness install commands with their caveats, how an upgrade is
+detected and performed, and exactly what remains in your repository after an
+uninstall.
+
+- [Requirements](#requirements)
+- [Install](#install)
+- [Upgrade](#upgrade)
+- [Uninstall](#uninstall)
+
+## Requirements
+
+| | |
+|---|---|
+| **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** ([codex-setup.md](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 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
+
+| Platform | Install |
+|---|---|
+| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry` (run both inside Claude Code). |
+| **Codex CLI** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs` |
+| **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` ; 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` |
+
+### Claude Code: install the Node dependencies once
+
+For Claude Code, also install the package's Node dependencies **once** and
+restart Claude Code. First locate the installed plugin:
+
+```bash
+claude plugin list --json
+```
+
+Find the enabled `session-orchestrator@kanevry` entry, then replace the
+placeholder below with its `installPath` value:
+
+```bash
+cd "/absolute/installPath/from/the/list" && npm install
+```
+
+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.
+
+Setup guides: [Codex](codex-setup.md) · [Cursor IDE](cursor-setup.md) ·
+[Pi](pi-setup.md). Per-IDE notes on which instruction file each harness reads:
+[instruction-file-resolution](../skills/_shared/instruction-file-resolution.md).
+
+## 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](codex-setup.md#refresh-and-explicit-cache-invalidation)
+for your marketplace source, then reload the skill picker or restart Codex.
+
+### How you learn that you are behind
+
+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".
+
+### Across a major version
+
+**[migration-v5.md](migration-v5.md)** covers the current release: the
+agent-status reader API changes and close-time discovery is enabled by default.
+If upgrading from before v4, also follow **[migration-v4.md](migration-v4.md)**
+for the removed skills, commands and scripts and their replacements.
+[migration-v3.md](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 ([codex-setup.md](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](../README.md#platform-support)) <!-- path-check: example -->
+- The `## Session Config` block you added to your instruction file
+- `.claude/rules/*.md` if you vendored the rule library via `/bootstrap --sync-rules`
+
+Deleting `.orchestrator/metrics/` deletes your session history. Telemetry
+requires explicit consent ([telemetry.md](telemetry.md)). 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.

package/docs/session-config-template.md

@@ -690,14 +690,19 @@ special: "follow .claude/rules/parallel-sessions.md"
 
 # VCS & infrastructure
 vcs: gitlab
+gitlab-host: gitlab.example.com        # only if remote URL doesn't expose it
 mirror: github
 cross-repos: []
+pencil: path/to/design.pen             # design-code alignment input
 ecosystem-health: true
 health-endpoints: []
 issue-limit: 50
 stale-branch-days: 7
 stale-issue-days: 30
 
+# Auto-skill dispatch
+auto-skill-dispatch: false             # opt-in; phrase-match meta-skill — see skills/using-orchestrator/SKILL.md
+
 # Quality
 ssot-files: [STATE.md]
 ssot-freshness-days: 5
@@ -711,6 +716,12 @@ discovery-severity-threshold: low
 discovery-confidence-threshold: 60
 discovery-parallelism: 5
 
+# Issue budget — QUANTITY cap on issue creation (not a quality filter)
+issue-budget:
+  max-per-session: 12                  # non-exempt issues one session may create (0 = block all)
+  mode: strict                         # strict | warn | off
+  overflow: collect-issue              # collect-issue | vault-note
+
 # Persistence & safety
 memory-cleanup-threshold: 5
 memory-cleanup-soft-limit: 180
@@ -731,6 +742,10 @@ isolation: auto
 max-turns: auto
 auto-commit-per-wave: false            # opt-in: commit after each wave's Quality-Lite PASS (V3.6 plumbing)
 
+# Heavy-repo preflight & worktree hygiene (HR-003)
+heavy-repo: false                      # true clamps the dispatched agent count to agents-per-wave
+worktree-cleanup: default              # default | aggressive
+
 # Env-aware
 resource-awareness: true
 enable-host-banner: true
@@ -815,6 +830,29 @@ templates-first:
   enabled: true
   hosts: [github, gitlab]
 
+# Wave reviewers — opt-in inter-wave architecture/QA/PRD audit dispatch (#461 / #478)
+wave-reviewers:
+  enabled: false                       # opt-in; absent, false, or an empty reviewers array = no-op
+  reviewers: []                        # ["architect-reviewer", "qa-strategist", "analyst"]
+  mode: warn                           # warn | strict | off
+
+# Persona gate — opt-in persona-panel fan-out after a wave (#458)
+persona-gate-wave:
+  enabled: false                       # opt-in
+  after: quality                       # quality | impl-polish
+  threshold: all                       # all | any | <m>-of-<n>
+  personas: []                         # persona slugs the panel dispatches
+  dispatch-model: claude-opus-4-7
+  mode: off                            # off | warn | strict — enabled: true with mode: off never fires
+
+# Agentic test orchestrator (/test) — run profiles and artifact retention
+test:
+  enabled: false                       # opt-in
+  default-profile: smoke               # profile name looked up in profiles-path
+  profiles-path: .orchestrator/policy/test-profiles.json
+  mode: warn                           # warn | strict | off
+  retention-days: 30                   # days test-run artifacts are kept (0 = no cleanup)
+
 # Verification auto-fix loop (PRD gsd Pattern 4 / #521)
 verification-auto-fix:
   enabled: false

package/docs/telemetry.md

@@ -21,6 +21,21 @@ it is the locked v1 schema and consent precedence this plugin implements.
   [Relationship to `telemetry-claims.md`](#relationship-to-telemetry-claimsmd)
   below.
 
+## 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. The optional anonymous usage telemetry described on the
+rest of this page is **off until you explicitly consent** and is a separate
+channel from those local records — turning telemetry on or off changes nothing
+about what is written locally, and deleting the local records sends nothing
+anywhere.
+
+Reported metrics describe *this* repository under its own conditions and will
+not transfer unchanged to yours
+([telemetry-claims.md](telemetry/telemetry-claims.md)).
+
 ## What we collect
 
 When telemetry is enabled and a batch is flushed, the payload is built from

package/hooks/enforce-scope.mjs

@@ -529,7 +529,48 @@ async function main() {
   // Coordinator carveout (#245): exact-path allowlist for harness-owned files.
   // STATE.md and wave-scope.json are written by the coordinator between waves;
   // per-wave allowedPaths lists should not need to enumerate harness infrastructure.
-  if (isCoordinatorCarveout(normalizedRel, projectRoot, scopePath)) {
+  //
+  // CALLER DISCRIMINATION (#1361) — the carve-out is the COORDINATOR's, exactly
+  // as Gate 5c's is (#1352), and for a sharper reason: the two files it covers
+  // are the harness's own control surfaces. STATE.md is coordinator-owned by
+  // contract (`skills/_shared/state-ownership.md`), and `wave-scope.json` IS the
+  // manifest every later gate of this wave reads — a subagent permitted to write
+  // it can rewrite its own file scope and disarm the guard for the rest of the
+  // wave. A `'subagent'` therefore falls through to Gate 7, where a manifest that
+  // does not grant the path is a DENY.
+  //
+  // ALLOW-CENSUS (RCR-007, the precondition for forbidding what is allowed
+  // today): 1069 transcripts across 46 sessions of this repo carried 4385
+  // subagent writes; 0 targeted a carve-out path (2026-09-13 @ `5501f700`). The
+  // fix takes nothing away from any observed legitimate writer.
+  //
+  // FAIL-OPEN on ambiguity, same as Gate 5c and for the same reason: the other
+  // three classifications keep the ALLOW, because fail-closed would deny the
+  // coordinator's own `/close` STATE.md writes. The classification is emitted so
+  // that fail-open stays COUNTABLE (HR-105) — before #1361 this branch called
+  // `emitAllow()` (`process.exit(0)`, no log, no event), so whether it ever fired
+  // was unfalsifiable after the fact.
+  const carveoutCaller = classifyCaller(input);
+  if (carveoutCaller !== 'subagent' && isCoordinatorCarveout(normalizedRel, projectRoot, scopePath)) {
+    // One event per decision point, awaited before emitAllow() — emitAllow()
+    // calls process.exit(), which would discard a pending append.
+    try {
+      const { emitEvent } = await import('../scripts/lib/events.mjs');
+      await emitEvent(
+        'orchestrator.scope.coordinator_carveout_allowed',
+        {
+          hook: HOOK_NAME,
+          manifest: scopePath,
+          wave: scope.wave,
+          // Repo-RELATIVE by choice: the carve-out set is in-repo by
+          // construction, so the relative form carries the whole decision
+          // without putting a host-local absolute path into the ledger.
+          file_path: normalizedRel,
+          discriminator: carveoutCaller,
+        },
+        { repoRoot: projectRoot },
+      );
+    } catch { /* observability is best-effort — never blocks the decision */ }
     return emitAllow();
   }
 

package/hooks/hooks-codex.json

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "session-orchestrator",
-  "version": "5.0.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.",
+  "version": "5.1.0",
+  "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
   "keywords": [

package/scripts/lib/command-blocker.mjs

@@ -1663,18 +1663,90 @@ export function redirectRuleMatches(rule, command, opts = {}) {
   const denylist = Array.isArray(rule['target-denylist']) ? rule['target-denylist'] : [];
   if (denylist.length === 0) return false;
   const modes = new Set(Array.isArray(rule.modes) && rule.modes.length > 0 ? rule.modes : ['truncate']);
-  const regexes = denylist.map(redirectGlobToRegExp);
+
+  // #1362 — TWO denylist classes, deliberately kept apart:
+  //
+  //   REPO-RELATIVE (every pre-#1362 entry): judged against
+  //   `repoRelativeRedirectTarget`, which returns `null` for anything outside
+  //   the root. Behaviour is byte-identical to before, and that null is what
+  //   keeps a relative entry from ever reaching an out-of-repo path.
+  //
+  //   HOME-ANCHORED (`~/…`, new): judged against the EXPANDED ABSOLUTE target,
+  //   never relativized. Needed because the artefacts worth denying are not all
+  //   inside the repo — the harness auto-memory directory
+  //   (`~/.claude/projects/<encodeProjectDir(root)>/memory/`) is auto-injected
+  //   as trusted project context into every later session yet lives outside
+  //   `git diff`, CI review and the secret scanners. Measured 2026-09-13: with
+  //   only the repo-relative class, NO glob spelling could match it, because
+  //   `relativizeAgainstRoot` discards out-of-repo targets by design.
+  //
+  // The split is one-directional on purpose: a home-anchored entry cannot widen
+  // an existing repo-relative rule, and a repo-relative entry still cannot
+  // escape the root. An unexpandable `~` (no usable `home`) matches NOTHING —
+  // fail-closed for the new class, since an unexpanded `~` names no file.
+  const relRegexes = [];
+  const absRegexes = [];
+  for (const pattern of denylist) {
+    const text = String(pattern);
+    if (text === '~' || text.startsWith('~/')) {
+      const expanded = expandLeadingHome(text, home);
+      if (expanded === text) continue; // no usable home → no match, never a guess
+      absRegexes.push(redirectGlobToRegExp(foldAbsoluteTarget(expanded)));
+    } else {
+      relRegexes.push(redirectGlobToRegExp(text));
+    }
+  }
+  if (relRegexes.length === 0 && absRegexes.length === 0) return false;
 
   for (const entry of extractRedirectTargets(command)) {
     if (entry.unresolved) continue;
     if (!modes.has(entry.mode)) continue;
-    const target = repoRelativeRedirectTarget(entry.target, repoRoot, home);
-    if (target === null) continue;
-    if (regexes.some((re) => re.test(target))) return true;
+
+    if (absRegexes.length > 0) {
+      // A RELATIVE target is repo-root-relative here, exactly as the repo-relative
+      // class already treats it (#994 R1) — otherwise `> ../../.claude/projects/
+      // <enc>/memory/MEMORY.md` from the repo root names the very file the `~`
+      // spelling blocks, and only the spelling would be denied (measured
+      // 2026-09-13: relative `>`/`>>` ALLOW vs tilde/absolute BLOCK on one and
+      // the same resolved path). This resolves TARGETS, never ENTRIES: a
+      // repo-relative denylist entry keeps going through
+      // `repoRelativeRedirectTarget` below and still cannot reach out of the root.
+      const expandedTarget = expandLeadingHome(entry.target, home);
+      const absTarget = path.isAbsolute(expandedTarget)
+        ? expandedTarget
+        : repoRoot && path.isAbsolute(repoRoot)
+          ? path.resolve(repoRoot, expandedTarget)
+          : null;
+      if (absTarget !== null) {
+        const folded = foldAbsoluteTarget(absTarget);
+        if (absRegexes.some((re) => re.test(folded))) return true;
+      }
+    }
+
+    if (relRegexes.length > 0) {
+      const target = repoRelativeRedirectTarget(entry.target, repoRoot, home);
+      if (target !== null && relRegexes.some((re) => re.test(target))) return true;
+    }
   }
   return false;
 }
 
+/**
+ * Normalize an ABSOLUTE path for home-anchored denylist comparison (#1362):
+ * same alias-collapse and case-fold `relativizeAgainstRoot` applies before its
+ * containment test, so the two classes agree on what `/private/tmp` and a
+ * case-insensitive volume mean. Applied to BOTH sides (pattern and target), so
+ * the folding can never make a pattern match more than its literal spelling.
+ *
+ * @param {string} abs
+ * @returns {string}
+ */
+function foldAbsoluteTarget(abs) {
+  return stripPathAliases(path.posix.normalize(String(abs).replace(/\\/g, '/'))).toLocaleLowerCase(
+    'en-US',
+  );
+}
+
 /**
  * Test whether a command string contains a blocked pattern with shell-aware
  * boundaries AND a quoted-payload guard (#641).

package/scripts/lib/playwright-driver/runner.mjs

@@ -9,7 +9,8 @@
  * Exit codes:
  *   0 — all tests passed
  *   1 — at least one test failed (Playwright exit 1)
- *   2 — framework error, timeout, spawn failure, or invalid profile
+ *   2 — framework error, timeout, spawn failure, invalid profile, or the target
+ *       repo has no local Playwright install (preflight, #1359)
  *
  * CLI args (all also accepted via env vars as fallback):
  *   --run-dir <path>   absolute path to artifact dir  (env: RUN_DIR)
@@ -79,6 +80,43 @@ function checkAxeCore(targetPath, fsImpl) {
   return { present, skipped: false };
 }
 
+// ---------------------------------------------------------------------------
+// Playwright local-install preflight (#1359)
+// ---------------------------------------------------------------------------
+
+/** Packages that provide the `playwright test` runner, in preference order. */
+const PLAYWRIGHT_PACKAGES = ['@playwright/test', 'playwright'];
+
+/**
+ * Check whether the target repo can resolve the Playwright test runner from its
+ * OWN node_modules (walking up, so a monorepo hoist counts).
+ *
+ * Why a resolution probe and not `npx --no-install`: `--no-install` would change
+ * the spawn for every user — including the majority whose target repo has the
+ * devDependency — and its failure surfaces as npm's own message on a generic
+ * non-zero exit, which this runner would then map to exit 2 with no indication
+ * of what is missing. The probe is explicit, runs before any process starts, and
+ * leaves the spawned command byte-identical.
+ *
+ * @param {string} targetPath absolute path to the target repo
+ * @param {{ existsSync: Function }} fsImpl
+ * @returns {boolean} true when the runner binary resolves from the target
+ */
+function checkPlaywrightInstalled(targetPath, fsImpl) {
+  let dir = targetPath;
+  // Bounded by the filesystem root: path.dirname('/') === '/'.
+  for (;;) {
+    for (const pkg of PLAYWRIGHT_PACKAGES) {
+      const manifest = path.join(dir, 'node_modules', ...pkg.split('/'), 'package.json');
+      if (fsImpl.existsSync(manifest)) return true;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Main run() function
 // ---------------------------------------------------------------------------
@@ -212,6 +250,28 @@ export default async function run(opts = {}) {
     process.exit(0);
   }
 
+  // -------------------------------------------------------------------------
+  // Preflight: Playwright must resolve locally in the target repo (#1359)
+  // -------------------------------------------------------------------------
+
+  // `npx` resolves against the TARGET repo. Without a local install it falls
+  // back to downloading the package from the registry mid-run — a silent,
+  // unpinned network install inside what is supposed to be a test run. Abort
+  // first with an actionable message instead. Runs AFTER the dry-run exit
+  // above, so `--dry-run` still prints the resolved command on any machine.
+  if (!checkPlaywrightInstalled(targetPath, fsImpl)) {
+    console.error(
+      `runner: Playwright is not installed in the target repo (${targetPath}).`,
+    );
+    console.error(
+      'runner: this driver runs the target repo\'s OWN Playwright — it never falls back to a global install.',
+    );
+    console.error(
+      `runner: install it there first — \`npm install --save-dev @playwright/test\` in ${targetPath}, then \`npx playwright install chromium\`.`,
+    );
+    process.exit(2);
+  }
+
   // -------------------------------------------------------------------------
   // Create artifact directories
   // -------------------------------------------------------------------------