session-orchestrator 3.20.0 → 3.22.0

package/docs/scope-collision-guard.md

@@ -0,0 +1,167 @@
+# 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).
+> 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
+
+`assertFileScopeSubset()` (#796) checks each agent's scope **⊆** the wave's `allowedPaths` union, and `wave-scope-commit-guard` checks writes against that same union. A file claimed by two agents is a subset **twice over**, and the union grants it exactly once — so a double assignment is structurally invisible to both. It surfaced only afterwards, from an agent's own PSA-002 report (`findScopeCollisions()` header: `tests/scripts/sweep-expired-learnings-cli.test.mjs` handed to two agents of one wave). Per `.claude/rules/parallel-sessions.md` § Decision Tree, a file inside two declared scopes of one dispatch round is never a benign sibling signal — it is a deconfliction gap.
+
+Two things follow, and both are the point of #1020:
+
+- `allowedPaths` is **computed** from the per-agent declarations (`unionFileScopes()`), not transcribed by hand.
+- Disjointness is asserted on the **declarations**, before the union exists.
+
+## 2. The chain, in order
+
+| # | Step | Artefact | Mechanism |
+|---|------|----------|-----------|
+| 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` |
+
+`<state-dir>` is the first of `.pi` / `.cursor` / `.codex` / `.claude` that carries a `wave-scope.json` — the same precedence `findScopeFile()` and the hook's `waveKeyOf()` use.
+
+### 2.1 Why `--union` runs last
+
+A union computed over colliding scopes **launders the defect into the artefact meant to prevent it**: `allowedPaths` then grants the contested file, and every later gate — `--assert-subset`, `enforce-scope` Gate 7, the commit guard — sees a perfectly legal write. `validate()` in `validate-wave-scope.mjs` enforces the order in code: `--assert-subset` → `--assert-disjoint` → `--union`, and `--union` returns early because it is a QUERY MODE that replaces the manifest echo on stdout.
+
+The same ordering argument applies one level up: step 2 runs on the **declared** scopes, before step 3 expands test siblings. See § 6 for the limit that buys.
+
+### 2.2 Why the scope files are not temp files
+
+Steps 1, 2, 3, 4 and the `--assert-subset` assertion all read the *same* file, addressed by wave and agent id. A `$TMPDIR` copy is the one failure in this chain that **costs no error**: the injector finds nothing, no `FILE-SCOPE` block reaches the prompt, `extractScopeFromPrompt()` returns `[]`, and the hook allows the dispatch exactly as it did before #1020 — signal-free (matrix rows 5/6 below). The scope files are control state like `wave-scope.json` itself, never a wave territory; writing them legitimately trips `bash-write-verify` once per wave rollover, and widening `allowedPaths` to silence that would grant agents write access to the deconfliction record.
+
+The coordinator's **own** planned direct edits belong in `coordinator.json` in the identical form. They are not dispatches, so the hook can never see them (§ 6); the CLI check is the only gate that covers them.
+
+## 3. The collision algorithm
+
+`findScopeCollisions(agentScopes, { knownFiles })` compares every cross-agent entry pair through `classifyEntryCollision()`, in three binding stages:
+
+1. **Exact string equality** → kind `concrete`. The commonest real case, and the only stage that works for a file that **does not exist yet**.
+2. **Concrete vs glob** via `pathMatchesPattern(concrete, glob)` → kind `concrete`. Exact and I/O-free. Two *distinct concrete* paths are disjoint and return immediately.
+3. **Glob ∩ glob**, in two sub-stages:
+   - **3a — witness:** expand both entries against `KNOWN = knownFiles ∪ {every concrete entry of every agent}`; a non-empty intersection is `glob-expanded`. The second half of that union matters — a file the wave is about to *create* is not in `git ls-files`, but a concrete claim by one agent can still witness another's glob.
+   - **3b — prefix fallback:** for the intersection that exists only in files not yet on disk. Requires literal-prefix containment in either direction, at least one **recursive** entry (`**`, or a trailing `/`, which `pathMatchesPattern` matches by `startsWith` at any depth), and compatible literal suffixes. The suffix filter is a necessary condition, so it adds no false negative while removing `scripts/**/*.ts` vs `scripts/**/*.mjs`.
+
+`knownFiles` is **injected, never discovered**: `scope-gate.mjs` is hook-safe (pure, sync, no I/O, no spawn) because `enforce-scope.mjs` reaches it on a hot path, and under the exit-0/stdout-JSON protocol a throw there reads as "no decision" = ALLOW. The CLI spawns `git ls-files` in `knownRepoFiles()`; the hook does the same in `listTrackedFiles()`, both resolving `git rev-parse --show-toplevel` first so a session started in a subdirectory produces repo-relative paths on both sides.
+
+Duplicate agent ids are reported separately (`duplicateIds`), not as a self-collision. A record with no usable id runs as `<unnamed#i>` rather than being dropped — an unreviewed scope is exactly the one that collides.
+
+### 3.1 Why `pathMatchesPattern` alone cannot do stage 3
+
+The matcher is **directed**: argument 2 is compiled into a regex, argument 1 is tested as a literal string. Measured in this working tree on 2026-08-14:
+
+```
+$ node --input-type=module -e "import { pathMatchesPattern } from './scripts/lib/scope-gate.mjs';
+  console.log(pathMatchesPattern('scripts/**/*.mjs','scripts/lib/*.mjs'));
+  console.log(pathMatchesPattern('scripts/lib/x.mjs','scripts/**/*.mjs'),
+              pathMatchesPattern('scripts/lib/x.mjs','scripts/lib/*.mjs'));"
+false
+true true
+```
+
+Both globs match `scripts/lib/x.mjs`, yet the direct comparison says `false`. For `assertFileScopeSubset()` that inexactness is *safe*: its glob branch reduces to verbatim presence plus literal-prefix coverage and therefore **over-approximates coverage**, which at worst accepts a union it could not fully prove. For a **collision** check the sign flips — the same over-approximation becomes a **false negative**, i.e. a missed collision, i.e. the incident. That is why the two exact stages decide first and stage 3 is reached only for pairs neither can settle.
+
+## 4. The hook
+
+`hooks/pre-task-scope-disjoint.mjs` is a `PreToolUse` hook on matcher **`Agent`** (registered in `hooks/hooks.json`). It blocks a wave from handing the same file to two agents at the moment of dispatch, before either has written a byte.
+
+It cannot compare a batch of siblings directly — the header records why, measured against 12 archived transcripts of this repo (147 dispatch `tool_use` blocks, 51 batches, measured 2026-08-14): the dispatch tool is named `Agent` and not `Task`; the payload carries **no** structured file scope (`files` / `file_scope` / `scope` → 441 probes, zero hits), so the scope exists only as prose inside `prompt`; and the not-yet-dispatched siblings of a batch are not visible in the transcript at dispatch time. What remains is a **ledger**: each dispatch records its scope under a wave key, and the next dispatch is checked against everything already recorded.
+
+- **Ledger:** `.orchestrator/wave-dispatch-scopes.json` (gitignored), keyed `<session-id>|w<wave>|<role>` from `<state-dir>/wave-scope.json`.
+- **Lock:** `.orchestrator/wave-dispatch-scopes.lock` — the read-modify-write cycle runs under `withFileLock()` (the primitive behind the PSA-005 STATE.md lock). `writeJsonAtomicSync` makes the write atomic, never the *cycle*.
+- **Scope extraction:** `extractScopeFromPrompt()` finds a scope marker line and takes the FIRST fenced block after it, accepting only lines that survive a deliberately strict `looksLikeRepoPath()`. `normalizeScopeEntry()` then folds `./`, `//` and `/./` spellings together, and `promoteDirEntries()` rewrites `scripts/lib` → `scripts/lib/` **on evidence** (not a tracked file itself, at least one tracked file beneath it) — both because two spellings of one path previously compared as disjoint.
+- **DENY** fires on exactly one condition: a collision involving THIS dispatch with a prior agent of the same wave that is **still in flight** (§ 5). The reason names the agent pair, the collision kind and the evidence paths; the suggestion is "give the file exactly ONE owner, or wait for the named agent(s) and re-dispatch", plus the ledger path to delete if the state is stale. The ledger is deliberately **not** persisted on a deny — the dispatch did not happen, so recording it would make the retry-after-fix look like a duplicate.
+
+### 4.1 Error-class matrix — deliberately fail-**open**
+
+The blast radius is asymmetric. A false positive on the dispatch path blocks every agent of the session — the guard becomes a session outage, and nothing downstream catches a dispatch that never happened. A false negative is a double assignment that three later gates still catch (`validate-wave-scope.mjs`, `enforce-scope.mjs` at write time, the W5 verification pass). Fail-closed is right for a WRITE guard (`enforce-scope.mjs` is), and wrong here. Each row is a choice, not an oversight:
+
+| # | Condition | Decision |
+|---|-----------|----------|
+| 1 | disabled via profile/env | exit 0, silent |
+| 2 | repo module failed to load | ALLOW + `GUARD INACTIVE` banner on stderr |
+| 3 | stdin empty / not JSON | ALLOW |
+| 4 | `tool_name` is not `Agent` | ALLOW |
+| 5 | prompt carries no scope marker | ALLOW |
+| 6 | scope block present but unparseable | ALLOW |
+| 7 | ledger unreadable / corrupt | WARN + ALLOW + **self-heal** (the verdict carries a fresh ledger) |
+| 8 | `git ls-files` failed | ALLOW, degraded (stage 3a loses witnesses; concrete collisions still found) |
+| 9 | `findScopeCollisions` not evaluable | WARN + ALLOW |
+| 10 | same agent id re-dispatched | ALLOW, ledger record replaced (a retry must not self-lock) |
+| 10a | collision, but every colliding prior agent has FINISHED | ALLOW + prune those records |
+| 11 | collision with a prior agent still IN FLIGHT | **DENY** |
+| 12 | unexpected throw in `main()` | ALLOW + stderr |
+| 13 | liveness probe throws / no evidence at all | treated as IN FLIGHT (bounded by the TTL, § 5) |
+| 14 | ledger lock not acquirable within its budget | run the cycle UNLOCKED (degraded), never deny |
+
+Two structural rules keep this matrix honest, both recorded in the hook header:
+
+- `decide()` is a **pure function returning a verdict**; the module emits exactly once, at the end. `emitWarn`/`emitDeny` call `process.exit(0)` and never return, so a warn emitted from inside the checking flow would terminate the process before a later collision could be denied — and would skip the lock's release `finally`.
+- Row 9's discriminator is **not** `ok !== true`. `ok` means *disjoint*, so `ok === false` is the normal result of a real collision; "not evaluable" is `ok === false` with BOTH result arrays empty. Reading `ok` as evaluability would turn every genuine collision into a warn, i.e. an allow — the exact fail-open the hook exists to prevent.
+
+## 5. The liveness probe
+
+A ledger with no notion of completion denies the wrong thing. Measured over 38 archived transcripts of this repo (346 `Agent` dispatch blocks; hook header, 2026-08-14): 0 of 4 same-batch overlaps and **2 of 2 cross-dispatch overlaps** would have been denied — and both cross-dispatch pairs were legitimate **sequential repair passes** (a dispatch and its later fix). Because a deny deliberately does not persist the ledger, the re-dispatch would have met the same stale record: a permanent block.
+
+The discriminator is therefore neither time nor the agent's name, but whether the recorded agent is **still in flight**. Two transcript shapes carry that:
+
+- **Synchronous dispatch** — the `tool_result` for the dispatch's `tool_use` id arrives when the agent is done (measured: five `Agent` rows within 0.44 s, their results 5–11 minutes later). At the fifth agent's `PreToolUse` none of the first four has a result → all in flight → a real same-batch overlap still denies.
+- **Asynchronous dispatch** — the `tool_result` arrives in ~0.2 s and reads `Async agent launched successfully`. **That text is a launch receipt, not a completion.** Treating it as one would let every real background-batch collision through. The completion arrives later as a `<task-notification>` record carrying `<tool-use-id>` and `<status>completed</status>` (measured: launch 14:14:26.768 → notification 14:24:39.360).
+
+`buildTranscriptIndex()` reads all three record shapes and counts a description as finished only when **every** one of its dispatch ids is finished. Cost containment: the transcript is read **only once a collision has already been found** — i.e. only on the path that is about to deny; the no-collision path pays nothing. Transcripts above 256 MiB are treated as *no evidence*, never as a completion.
+
+**Blind fallback and its named ceiling (BV-004).** With no transcript, or none carrying a record of that agent, liveness falls back to the ledger entry's own age with `IN_FLIGHT_TTL_MS = 30 min`. The ceiling is derived: the largest **measured** same-batch dispatch spread is 95.7 s, so 30 min is ~19× headroom against the false-ALLOW direction, while both measured sequential repair gaps (36 min, 49 min) sit above it. **Revisit trigger:** a same-batch spread above ~5 min appearing in `.orchestrator/metrics/`, or a harness change that stops writing `transcript_path` — either invalidates the headroom the number rests on.
+
+## 6. Named limits
+
+Complete list of what this guard does **not** see, or sees only approximately:
+
+1. **The blind TTL window.** Without transcript evidence the only liveness signal is the 30-minute TTL above. Inside that window a finished agent still blocks (false deny, recoverable by deleting the ledger); outside it a running agent no longer blocks (false allow). Revisit trigger as stated in § 5.
+2. **Test-sibling collisions.** Disjointness is asserted on the **declared** scopes (step 2), before `expandTestSiblings()` runs (step 3). Two agents whose production files share a basename receive the *same* emitted sibling glob (`tests/**/{basename}*.test.mjs`), which a declared-scope check cannot see. Revisit if a wave is ever scoped by basename family instead of by directory.
+3. **Prose extraction fails only toward ALLOW.** The hook's only channel is the `FILE-SCOPE` prose block. A missing marker, a missing fence, a decorated path that fails `looksLikeRepoPath()` — all resolve to allow (rows 5/6). Measured: 42 of 147 archived prompts (28.6 %) carried a scope marker at all, so denying the non-extractable case would have denied ~7 dispatches in 10. The CLI check (step 2) is the gate that does not depend on prose.
+4. **Coordinator-direct edits are invisible to the hook.** They are not dispatches, so no ledger entry exists for them. They participate in the CLI check via `coordinator.json` only — and 2 of the 5 divergences that motivated #1020 were coordinator-direct edits.
+5. **The wave-key fallback.** With no readable `wave-scope.json`, `waveKeyOf()` degrades to `<session>|w?|?` and the ledger spans the whole session, so a wave-3 dispatch is compared against wave-1 records. Bounded, not eliminated, by the liveness probe: a prior record binds only while its agent is in flight.
+6. **Glob ∩ glob without witnesses.** Stage 3a needs tracked files; with git unavailable (row 8) or for files not yet on disk, only stage 3b's prefix fallback carries the load — and it requires at least one recursive entry, so two non-recursive globs that intersect only in an unborn file are not detected.
+7. **Only collisions involving the current dispatch are actionable.** A pair among already-dispatched agents was either denied at its own dispatch or predates the guard; re-denying it would block an innocent third agent.
+8. **Lock loss reopens the race.** On lock timeout the cycle runs unlocked (row 14) — two dispatches starting together can then read the same ledger state and one record is lost. That is the pre-lock behaviour, chosen over denying on a lock-file problem.
+
+## 7. Debugging
+
+**A dispatch was denied and you do not believe it.** Read `.orchestrator/wave-dispatch-scopes.json`: it carries `waveKey`, `updated`, and one `{id, desc, files, at}` record per already-dispatched agent. The deny reason names the other agent — find its record and compare its `files` to the ones in your prompt's `FILE-SCOPE` block. Three outcomes:
+
+- The other agent is genuinely running and the overlap is real → fix the ownership in the session plan (one file, one agent), rewrite the affected `filescopes/wave-<N>/*.json`, re-assert, re-dispatch.
+- The other agent has finished, but the ledger still binds it → the transcript carried no evidence (§ 5) and you are inside the TTL window. Delete `.orchestrator/wave-dispatch-scopes.json`; the next dispatch rebuilds it.
+- The `waveKey` names an older wave → the `<session>|w?|?` fallback (limit 5). Check that `<state-dir>/wave-scope.json` exists and is readable, then delete the ledger.
+
+**A dispatch was NOT denied and should have been.** Work down the allow rows: is `FILE-SCOPE` present in the prompt with a fenced block right after it (rows 5/6)? Is the hook armed at all (`GUARD INACTIVE` on stderr = row 2)? Did a `systemMessage` warning appear (rows 7/9)? Cross-check the same scopes through the CLI, which does not depend on prose:
+
+```bash
+node scripts/validate-wave-scope.mjs --assert-disjoint "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
+```
+
+Exit 1 prints one `ERROR:` line per collision (`agents "A" and "B" both claim [...]`) and one per duplicate id. Exit 0 — nothing on stderr, the manifest echoed back on stdout — means the declared scopes really are disjoint and the hook was right to allow; the divergence is then in the prompt, not in the plan.
+
+**Reset.** Delete `.orchestrator/wave-dispatch-scopes.json` (and `.orchestrator/wave-dispatch-scopes.lock` if a dead holder is suspected). Both are gitignored, both are rebuilt on the next dispatch, and neither is shared with any other mechanism. After the final wave, `<state-dir>/filescopes/` is deleted along with `wave-scope.json` — a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified.
+
+**Disable.** The hook honours the repo's profile gate (`shouldRunHook('pre-task-scope-disjoint')`, row 1) — a silent exit 0, no decision at all.
+
+## 8. Provenance of the numbers
+
+Every figure above is quoted from a measurement recorded next to the code that carries it, with its date:
+
+- Transcript-shape figures (147 dispatch blocks / 12 transcripts / 51 batches / 441 zero-hit probes / 28.6 % marker coverage; 346 blocks / 38 transcripts for liveness; the 95.7 s, 36 min and 49 min spreads; the 0.44 s and 10-minute observations) — header of `hooks/pre-task-scope-disjoint.mjs`, measured 2026-08-14 against this project's archived transcripts.
+- The directedness transcript in § 3.1 — run in this working tree on 2026-08-14; the command is printed with it.
+
+Re-measure before citing any of these downstream. A count re-briefed later is a claim about the past (`.claude/rules/parallel-sessions.md` § PSA-006).
+
+## See Also
+
+- `skills/wave-executor/wave-loop.md` § Scope Manifest — the coordinator runbook (steps 3.1–3.3) and § Pre-Dispatch: File-Scope Injection (the prompt block shape).
+- `.claude/rules/parallel-sessions.md` § Decision Tree (why a file in two declared scopes is never a benign sibling signal), § PSA-006 (measurement discipline).
+- `hooks/enforce-scope.mjs` — the write-time gate, fail-**closed**; the deliberate inversion of this hook's posture.
+- [`docs/adr/0011-guard-degradation-semantics.md`](adr/0011-guard-degradation-semantics.md) — the exit-0 hook protocol (#906) and why a truncated stdout envelope reads as no-decision, i.e. as ALLOW.

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/enforce-scope.mjs

@@ -20,6 +20,12 @@
  *   G7  relative path matches an allowedPaths pattern
  *   G8  (all passed) → allow
  *
+ * Empty-allowedPaths reasoning (#1057): the VERDICT for an empty allowlist is
+ * unchanged (deny-all, the #256 contract), but the deny REASON is now classified
+ * — Discovery's read-only contract, an unreadable manifest, a crashed session's
+ * leftover, an incomplete `--union`, or undecidable. See
+ * `scripts/lib/scope-gate.mjs` § Empty-`allowedPaths` classification.
+ *
  * Exit codes:  0 = allow   2 = deny
  *
  * SECURITY notes (inline refs):
@@ -88,6 +94,10 @@ let findScopeFile;
 let pathMatchesPattern;
 let suggestForScopeViolation;
 let readJson;
+// #1057 — empty-`allowedPaths` classification + the session clock it needs.
+let classifyEmptyScope;
+let suggestForEmptyScope;
+let sessionStartedAtMs;
 
 const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -137,6 +147,13 @@ async function bootstrap() {
       platform: { specifier: lib('platform.mjs') },
       hardening: { specifier: lib('hardening.mjs') },
       common: { specifier: lib('common.mjs') },
+      // #1057. Bound DIRECTLY rather than through the `hardening.mjs` barrel:
+      // that barrel re-exports an explicit, frozen symbol list shared by six
+      // hooks, and widening it for one hook's need would drag three symbols
+      // into five unrelated import surfaces. `hardening` already imports
+      // `scope-gate` transitively, so this adds no new failure mode — a broken
+      // scope-gate already banners GUARD INACTIVE through that edge.
+      scopeGate: { specifier: lib('scope-gate.mjs') },
     },
     {
       hookName: HOOK_NAME,
@@ -151,6 +168,7 @@ async function bootstrap() {
   ({ resolveProjectDir } = modules.platform);
   ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
   ({ readJson } = modules.common);
+  ({ classifyEmptyScope, suggestForEmptyScope, sessionStartedAtMs } = modules.scopeGate);
 }
 
 async function main() {
@@ -183,15 +201,31 @@ async function main() {
   if (!scopePath) return emitAllow();
 
   // SECURITY-REQ-08: read scope file once; pass parsed object to all subsequent checks
+  //
+  // #1057: `parseOk` records WHETHER that read produced a usable scope RECORD.
+  // Both fold-to-`{}` / fold-to-`[]` paths (corrupt JSON #794 GAP-5, malformed
+  // shapes #558) already deny and CONTINUE to deny — the flag exists so the deny
+  // REASON can say "the manifest is broken" instead of "update the session plan
+  // and restart the wave", which is the one instruction that cannot help here.
   let scope;
+  let parseOk = true;
   try {
     scope = await readJson(scopePath);
+    if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) {
+      parseOk = false;
+      scope = {};
+    }
   } catch {
+    parseOk = false;
     scope = {};
   }
 
   const enforcement = scope.enforcement ?? 'strict';
   const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+  // A PRESENT-but-non-array `allowedPaths` (#558: null / string / object) is a
+  // MALFORMED record, not an empty grant — same class as unparseable JSON, so it
+  // earns the same reason. Absent is different and stays `parseOk`.
+  if (scope.allowedPaths !== undefined && !Array.isArray(scope.allowedPaths)) parseOk = false;
   const gatesEnabled = scope.gates?.['path-guard'] !== false;
 
   // Gate 4: path-guard gate explicitly disabled
@@ -200,6 +234,48 @@ async function main() {
   // Gate 5: enforcement is turned off
   if (enforcement === 'off') return emitAllow();
 
+  // -------------------------------------------------------------------------
+  // #1057 — WHY is the allowlist empty?
+  //
+  // FIVE repo states produce `allowedPaths.length === 0` and the DENY IS RIGHT
+  // IN ALL FIVE; only the instruction differs (Discovery's read-only contract,
+  // a corrupt manifest, a crashed session's leftover, an incomplete `--union`,
+  // or genuinely undecidable). This block is therefore VERDICT-NEUTRAL: it
+  // selects a sentence, never a decision — `suggest()` below is the only
+  // consumer, and its `'unknown'` branch is byte-identical to the pre-#1057 text.
+  //
+  // Computed AFTER the early-exit gates (a disabled or `off` wave pays no
+  // fs.stat) and BEFORE the first deny site, so all three deny sites share one
+  // explanation instead of drifting apart.
+  // -------------------------------------------------------------------------
+  const emptyScopeReason =
+    allowedPaths.length === 0
+      ? classifyEmptyScope({
+          role: scope.role,
+          parseOk,
+          scopeMtimeMs: await mtimeMsOf(scopePath),
+          sessionStartMs: sessionStartedAtMs(projectRoot),
+        })
+      : null;
+  const scopeRelRaw = relativeFromRoot(projectRoot, scopePath);
+  const scopeHint = (scopeRelRaw ?? scopePath).split(path.sep).join('/');
+
+  /**
+   * The suggestion half of every deny below.
+   *
+   * With a NON-empty allowlist this is byte-identical to the pre-#1057 call.
+   * With an empty one it routes through the classifier — whose `'unknown'`
+   * branch delegates back to `suggestForScopeViolation(target, '')`, i.e. the
+   * same sentence as before. Strictly an addition.
+   *
+   * @param {string} target
+   * @returns {string}
+   */
+  const suggest = (target) =>
+    emptyScopeReason === null
+      ? suggestForScopeViolation(target, allowedPaths.join(', '))
+      : suggestForEmptyScope(target, emptyScopeReason, { role: scope.role, scopePath: scopeHint });
+
   // SECURITY-REQ-06: resolve relative file_path against projectRoot, not process.cwd()
   const absPathInput = path.isAbsolute(filePath)
     ? filePath
@@ -264,7 +340,7 @@ async function main() {
   // Gate 6: path must be inside the project root
   if (!isPathInside(resolvedPath, projectRoot)) {
     const reason = `Scope violation: path outside project root`;
-    const suggestion = suggestForScopeViolation(filePath, allowedPaths.join(', '));
+    const suggestion = suggest(filePath);
     return enforcement === 'strict'
       ? emitDeny(reason, suggestion)
       : emitWarn(`${reason} — ${suggestion}`);
@@ -276,7 +352,7 @@ async function main() {
   // SECURITY-REQ-04: null return means outside root — deny rather than pass null to pathMatchesPattern
   if (relPath === null) {
     const reason = `Scope violation: '${filePath}' outside project root`;
-    const suggestion = suggestForScopeViolation(filePath, allowedPaths.join(', '));
+    const suggestion = suggest(filePath);
     return enforcement === 'strict'
       ? emitDeny(reason, suggestion)
       : emitWarn(`${reason} — ${suggestion}`);
@@ -297,7 +373,7 @@ async function main() {
 
   if (!matched) {
     const reason = `Scope violation: '${normalizedRel}' not in allowed paths [${allowedPaths.join(', ')}]`;
-    const suggestion = suggestForScopeViolation(normalizedRel, allowedPaths.join(', '));
+    const suggestion = suggest(normalizedRel);
     return enforcement === 'strict'
       ? emitDeny(reason, suggestion)
       : emitWarn(`${reason} — ${suggestion}`);
@@ -307,6 +383,30 @@ async function main() {
   return emitAllow();
 }
 
+/**
+ * `mtimeMs` of a file, or `null` when it cannot be stat'ed.
+ *
+ * The PROVENANCE half of the #1057 staleness comparison. It is fed into a
+ * SUBTRACTION against this session's start time — deliberately NOT compared to a
+ * TTL: an absolute age cap blinds the check in exactly the regime it exists for
+ * (a legitimate long deep session ages into the blind spot with nothing having
+ * gone wrong). Same argument `hooks/post-bash-write-verify.mjs` makes for
+ * `sessionAgeMs` under "Why the minimum, and why NOT a staleness cap".
+ *
+ * Never throws — an unstat-able manifest simply yields an undecidable clock, and
+ * {@link classifyEmptyScope} degrades to `'unknown'`, never to an allow.
+ *
+ * @param {string} file
+ * @returns {Promise<number|null>}
+ */
+async function mtimeMsOf(file) {
+  try {
+    return (await fs.stat(file)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
 const COORDINATOR_CARVEOUT_PATHS = Object.freeze([
   '.claude/STATE.md',
   '.codex/STATE.md',

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.20.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
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.20.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
           },
           {
@@ -95,6 +95,26 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-task-scope-disjoint.mjs\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-auq-clarity.mjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "PostToolUse": [