session-orchestrator 5.3.0 → 5.4.0

package/docs/session-config-reference.md

@@ -356,6 +356,11 @@ slopcheck:
 | `max-turns` | integer or string | `auto` | Maximum agent turns before PARTIAL. Auto expands PER SESSION TYPE inside the resolved shape (`scripts/lib/session-shape.mjs` `MAX_TURNS_DEFAULT`, § Session Shapes above): housekeeping=8, feature=15, deep=25 (`maxTurnsDefault` in the shape JSON, applied to every wave). The `ultradeep` profile does **not** use one flat number — it sets `max-turns` PER WAVE: 40 for the Research+Code-Discovery wave, 25 for Impl-Core/Impl-Polish/Quality, 15 for Release/Finalization (the Synthesis-Gate wave is coordinator-direct and carries no `max-turns` at all). |
 | `auto-commit-per-wave` | boolean | `false` | Automatically commit each wave's work after the Quality-Lite gate passes. Checkpoint commits per wave reduce the risk of data loss from `git stash` collisions in parallel sessions (V3.3 RESCUE incident — see GitLab #214). When `false`, all work is committed at session-end via `/close`. Requires `persistence: true`; the flag is silently ignored when `persistence: false`. Trade-off: each wave produces an additional commit; git log shows N+1 commits instead of 1. Use `/simplify` or `git rebase -i --autosquash` before final close to squash if a clean history is desired. **Implementation note:** the procedural commit sequence (`scripts/lib/auto-commit.mjs`) is deferred to V3.6. Until then, setting this flag to `true` triggers a session-start warning that auto-commits are not yet active — the flag is a no-op but is validated so projects can opt in early. <!-- path-check: historical --> |
 
+**Guard coverage (moved from CLAUDE.md Critical Gotchas, 2026-09-25).** **Destructive-Command Guard is active in main + subagent waves on harnesses with a compatible command hook.** On Claude Code, and through the supported Cursor and Pi bridges, `hooks/pre-bash-destructive-guard.mjs` applies `.orchestrator/policy/blocked-commands.json`:
+**12 of its 16 rules are `severity: block`, the other 4 only warn** (measured 2026-09-19: `jq '[.rules[].severity]|group_by(.)|map({(.[0]):length})|add' .orchestrator/policy/blocked-commands.json`).
+The 16th is `ledger-delete-protected` (#1401): `rm`/`mv`/`unlink` on `.orchestrator/metrics/**` — added after a wave agent deleted a rotated 53.896-line ledger archive that no rule covered, because `rm` existed only as the pattern `rm -rf` and the redirect denylist's `*.jsonl` did not match `events.jsonl.1`.
+On Codex, the destructive-command rules are instructions only because no compatible `PreToolUse` command handler is wired. Rule source of truth: [`.claude/rules/parallel-sessions.md`](../.claude/rules/parallel-sessions.md) (PSA-003). Per-session bypass via Session Config: `allow-destructive-ops: true` (intentional maintenance only).
+
 ### enforcement-gates: the five gate keys (#800/#915)
 
 `enforcement-gates` is surfaced to the hook layer as `gates` inside the wave's
@@ -775,7 +780,25 @@ vault-integration:
   vault-name:                # optional (#660) — per-project vault namespace override
 ```
 
-> **Host-local override (#653; extended #819).** `vault-dir` resolves host-locally with precedence: env-var (`SO_VAULT_DIR`) > `owner.yaml` `paths.vault-dir` > the committed default. `plan-baseline-path` resolves with an extra per-context tier in between: `SO_BASELINE_PATH` env > `owner.yaml` `baselines:` directory-prefix match against cwd > `owner.yaml` `paths.baseline-path` (legacy scalar) > the committed default. This keeps maintainer-specific absolute paths out of version control. Resolvers: `scripts/lib/config/host-paths.mjs` (both keys) and `scripts/lib/named-baseline-resolver.mjs` (the `baselines:` match tier).
+> **Host-local override (#653; extended #819, agents/vault#319, #1448).** `vault-dir` resolves host-locally with precedence: env-var (`SO_VAULT_DIR`) > `owner.yaml` `vault-dirs:` directory-prefix match against cwd > `owner.yaml` `paths.vault-dir` > the committed default. `plan-baseline-path` resolves the same way: `SO_BASELINE_PATH` env > `owner.yaml` `baselines:` directory-prefix match against cwd > `owner.yaml` `paths.baseline-path` (legacy scalar) > the committed default. The match tier exists because one host-wide `paths.vault-dir` otherwise redirects EVERY repo on the host into one vault, including a repo whose own vault lives elsewhere on that host. First match wins, so list the more specific prefix first:
+>
+> ```yaml
+> # ~/.config/session-orchestrator/owner.yaml
+> paths:
+>   vault-dir: ~/Projects/work/vault               # host-wide default
+> vault-dirs:
+>   - path: ~/Projects/private-world/vault         # used for any cwd under the prefix
+>     match: { path-prefix: ~/Projects/private-world/ }
+> ```
+>
+> A leading `~` is expanded to the home directory: `path-prefix` when matching, and the `path` / `paths.vault-dir` value the two owner.yaml tiers return (`match`, `owner`). The `env` and `committed` tiers pass through unexpanded; `scripts/vault-mirror.mjs` expands its `--vault-dir` at entry, so a `~/…` from any tier reaches the vault rather than `<cwd>/~/…`.
+>
+> The parsed config reports which tier won as `vault-integration.vault-dir-source` (`env`, `match`, `owner`, `committed`). This keeps maintainer-specific absolute paths out of version control. Resolvers: `scripts/lib/config.mjs` (`resolveVaultDir`, module-private), `scripts/lib/config/host-paths.mjs` (`resolveHostPath`, used for `plan-baseline-path`) and `scripts/lib/named-baseline-resolver.mjs` (the `baselines:` / `vault-dirs:` match tier).
+>
+> **Fake-repoRoot trap (moved from CLAUDE.md Critical Gotchas, 2026-09-25).** A throwaway invocation of a vault writer (`mirrorNarrative()`, `vault-mirror.mjs`, the board writer) with a synthetic `repoRoot` does **not** land in a sandbox — the fake repo path only fakes the SOURCE, never the DESTINATION. A reviewer in this repo walked into exactly that.
+> Export `SO_VAULT_DIR=<tmpdir>` before ANY manual invocation of vault-writing code. <!-- consistency:exempt:runtime-only -->
+>
+> **Host-local switch (#1448).** A host can switch the integration off or soften it without touching the committed file, e.g. a host with no vault clone, where `vault-mirror.mjs` would otherwise exit 2 (`missing-vault-dir`) and a `strict` repo would block `/close`. Precedence: env `SO_VAULT_INTEGRATION=off|warn|strict` > `owner.yaml` `vault-integration: { enabled: false }` or `vault-integration: { mode: off|warn|strict }` > the committed block. The host may only LOWER the committed level (`strict` → `warn` → `off`); `enabled: true` or a stronger mode is ignored, so a host can never mirror a repo that did not opt in. An invalid `owner.yaml` `vault-integration:` section is dropped on its own (the rest of `owner.yaml` stays in force). When the host lowered the level, `vault-integration.host-override` names the tier (`env:SO_VAULT_INTEGRATION` or `owner.yaml`), otherwise it is `null`; session-end then prints `vault-mirror: bewusst aus auf diesem Host (<tier>)` instead of failing.
 
 > **`SO_CONFIG_HOME` — the host-private config directory itself.** A sibling override, one layer below `owner.yaml`'s own contents rather than a key inside it: `scripts/lib/config/private-config-dir.mjs` (`resolvePrivateConfigDir()`) is THE resolver (#1223) for the directory holding `owner.yaml`, `host-private.json`, and the host-alias ledger (`SO_HOST_ALIASES_FILE`) — `scripts/lib/host-identity.mjs`'s `_privateDir()` delegates to it — with precedence env-var (`SO_CONFIG_HOME`, names the private dir ITSELF) > `XDG_CONFIG_HOME` (names its PARENT) > the homedir default `~/.config/session-orchestrator`. Both env vars are read with `.trim() || fallback`, not a bare `||` (`.claude/rules/development.md` § Error Handling env-var-fallback-whitespace trap).
 
@@ -784,7 +807,7 @@ vault-integration:
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `vault-integration.enabled` | boolean | `false` | If true, session-end and evolve skills invoke `vault-mirror.mjs` to sync learnings and sessions into the vault. When false (or missing), mirroring is skipped silently. |
-| `vault-integration.vault-dir` | string or null | `null` | Absolute path to the vault repository. Falls back to `$VAULT_DIR` env variable if not set. Required when `enabled` is true. |
+| `vault-integration.vault-dir` | string or null | `null` | Absolute path to the vault repository. Host-local tiers override it (see the note above). If it is still empty after them, only the bash snippet in session-end and evolve falls back to the `$VAULT_DIR` env variable. Required when `enabled` is true. |
 | `vault-integration.mode` | string | `warn` | Mirror error handling. `strict` blocks session close if the mirror exits non-zero. `warn` reports errors but does not block. `off` bypasses mirror invocation entirely (useful when transitioning). |
 | `vault-integration.vault-name` | string or null | `null` | Optional override for the per-project vault namespace segment (#660). When set (or via CLI `--vault-name`), vault writes go to `40-learnings/<vault-name>/` and `50-sessions/<vault-name>/`, sanitised to a kebab slug. When null/absent, the namespace is derived from the git origin via `deriveRepo()`. Owner-privacy leaks (personal home path / private slug / personal name) are redacted to `redacted-repo`. NOT a filesystem path → NOT host-path-resolved. **Coverage gap:** portfolio board rows are NOT yet namespace-aware — the override only reaches `40-learnings/`, `50-sessions/`, and the per-repo narrative mirror (`narrative-mirror.mjs`, #832 item 2); tracked separately in #832. Resolver: `scripts/lib/vault-mirror/namespace.mjs` (`resolveRepoNamespace`). |
 | `vault-integration.gitlab-groups` | string[] or null | `null` | List of GitLab group paths to scan for repos missing `.vault.yaml`. Consumed by `scripts/vault-backfill.mjs` (via `readVaultIntegrationConfig()`) and the `/plan retro` vault-backfill sub-mode (`skills/plan/mode-retro.md` Phase 1.6 Step 1). When null/unset, the backfill CLI exits with a "no groups configured" notice. |
@@ -1350,7 +1373,7 @@ remote-hosts:
 
 **Two enums, never conflated.** `roles-allowed` holds `agent-mapping` roles (`test`, `ui`, `perf`) — NOT wave roles (`Impl-Core`, `Quality`, …). The wave→role translation is `OFFLOADABLE_WAVE_ROLES` in `scripts/lib/wave-resource-gate.mjs`; a wave role absent from that map is local-only by default.
 
-**Placement contract.** The gate applies its offload arm only after the HR-004 heavy-repo cap, and only when the resource verdict was `reduce` or `coordinator-direct`. It does NOT probe the network: the coordinator supplies a readiness witness (`remoteReady: { m5: true }`, or an async `probeFn`). With no witness, no host counts as ready and the decision stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`) is never offloaded regardless.
+**Placement contract.** The gate applies its offload arm only after the HR-004 heavy-repo cap, and only when the resource verdict was `reduce` or `coordinator-direct` — or, with `offload-first: true`, on `proceed` as well (see § `offload-first` below). It does NOT probe the network: the coordinator supplies a readiness witness (`remoteReady: { m5: true }`, or an async `probeFn`). With no witness, no host counts as ready and the decision stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`) is never offloaded regardless.
 
 **agent-mapping interaction.** A declared alias is what an `agent-mapping` value of the form `<role>: ssh:<alias>` validates against; naming an undeclared host throws at parse time, naming the `ssh` channel with no target throws as for any other channel.
 
@@ -1358,6 +1381,32 @@ Read by: `scripts/lib/config/remote-hosts.mjs` (parser), `scripts/lib/config.mjs
 
 See `skills/remote-offload/SKILL.md` for the wave-executor-side decision rule, the three offload channels, and how a declared alias here is what an `agent-mapping` `ssh:<alias>` value validates against.
 
+### `offload-first` (#1465)
+
+Opt-in switch that makes placement the FIRST choice for an offloadable wave role, not only the answer to local pressure. Scalar key, so a trailing `# comment` on its line is fine (the block-header gotcha above does not apply).
+
+```yaml
+offload-first: false   # true = offloadable roles go to a witnessed-ready remote host even on `proceed`
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `offload-first` | boolean | `false` | When `true`, the gate's offload arm fires on a `proceed` verdict too, not only on `reduce` / `coordinator-direct`. `false` (or absent) changes nothing. |
+
+**Behaviour with `offload-first: true`.**
+
+- Only roles in `OFFLOADABLE_WAVE_ROLES` (`scripts/lib/wave-resource-gate.mjs`) move: wave roles `quality` / `test` → `test`, `ui` → `ui`, `perf` → `perf`. The table is NOT extended by this switch — build, lint and audit work is covered by the Quality wave's `test` role. `impl-core`, `security-review`, `migration`, `release`, `secrets`, `incident` and `refactor-crosscut` never leave the local host.
+- The target is the FIRST declared `remote-hosts` entry whose `roles-allowed` carries the mapped role AND that is witnessed ready (`remoteReady: { m5: true }` or an async `probeFn`). The gate still never probes the network itself, so the witness is mandatory for the switch to have any effect: without one, nothing offloads even with the switch on.
+- The HR-004 heavy-repo cap still binds the offloaded agent count.
+- No ready host for the role → the verdict is unchanged (`proceed`, or the `reduce`/`coordinator-direct` the resource rules computed) and `reasons` carries `offload-first: no ready host for '<role>' — staying local`.
+- Switch on but no `remote-hosts` declared → the verdict is unchanged and `reasons` carries `offload-first: true but no remote-hosts declared — staying local`. `validateSessionConfig()` (`scripts/lib/config-schema.mjs`) additionally emits a warn-level cross-field finding `offload-first-cross-field` for that combination; it never flips `ok`.
+- `resource-awareness: false` remains a FULL opt-out (no probe, no HR-004 cap, no placement), as documented in § Environment Awareness — the switch does not change that.
+- On the `probe failed (ignored)` path placement DOES apply when the switch is on, because placement needs no measurement; the `probe failed (ignored)` reason is kept.
+
+**Committed-only.** There is no host-local precedence (env > `owner.yaml` > committed) for this key: the existing `resolveDispatcherAutonomy` resolver is enum-specific and `owner.yaml` freezes its allowed sections, so reusing it would need a schema change for a need nobody has raised yet (BV-001) — the value in the committed Session Config is the value that applies.
+
+Read by: `scripts/lib/config.mjs` (parser), `scripts/lib/config-schema.mjs` (cross-field warning), `scripts/lib/wave-resource-gate.mjs` (placement).
+
 ## Evolve Extra Sources (#638)
 
 Opt-in EXTRA learning sources for `/evolve`. A domain measurement (e.g. an eval-learn regression harness) runs OUT-OF-BAND and writes a sidecar JSON of regression flags; `/evolve` then READS each declared sidecar and emits a `domain-regression` learning candidate per flag that has persisted across ≥2 consecutive sessions. This is a strict **read-only consumption contract**: `/evolve` never runs the domain measurement — it only consumes the sidecar output. Absent/empty ⇒ `[]` ⇒ no extra sources are read; existing `/evolve` runs are unaffected.
@@ -1572,7 +1621,7 @@ reaper:
 | `reaper.mode` | `report` \| `kill` | `report` | `report` runs the scan in dry-run (decide + audit, no signal); `kill` arms the signal path (PRD Stufe 2, after calibration). An unrecognised value falls back to `report` — never to `kill`. |
 | `reaper.min-age-seconds` | integer (≥ 0) | `300` | DevWatchdog's hard limit for `tsgo`; the 2026-09-20 orphans were 7–17 min old, well above it. Self-healing clamp: a value below `min-scan-interval-seconds` is widened to it, because a process younger than one scan period can be born and reaped between two scans. |
 | `reaper.min-scan-interval-seconds` | integer (≥ 1) | `30` | DevWatchdog's normal scan cadence. The throttle that keeps a `PostToolBatch` storm from taxing every tool call. |
-| `reaper.kill-grace-ms` | integer (≥ 0) | `10000` | `DEFAULT_KILL_GRACE_MS` from `dispatch-common.mjs:61` — repo convention, not newly invented. SIGTERM → grace → SIGKILL. |
+| `reaper.kill-grace-ms` | integer (≥ 0) | `10000` | `DEFAULT_KILL_GRACE_MS` from `process-group.mjs:52` — repo convention, not newly invented. SIGTERM → grace → SIGKILL. |
 | `reaper.verify-wait-ms` | integer (≥ 0) | `500` | Wait before reading the effect back. Without it the 2026-09-20 check falsely reported "still alive" measuring immediately after `kill -9` (PRD B6: a sent signal proves nothing). |
 | `reaper.max-hook-latency-ms` | integer (≥ 1) | `50` | Ceiling the TRIGGER may delay a hook by — the config read, the marker `stat` and the detached spawn, measured with `performance.now()` in `maybeTriggerOrphanScan()`. Overrunning it writes ONE stderr WARN line and nothing else: no event (a `PostToolBatch`-class hook emitting per fire is the always-on signal HR-101 calls a broken instrument) and no abort (the child is already detached by then). The scan itself is not covered — that is the point of spawning detached. |
 | `reaper.false-alarm-window` | integer (≥ 1) | `50` | Rolling window of audit decisions the HR-101 10 % false-alarm rate is judged over — a window in DECISIONS, not calendar time, so the rate has a population on quiet hosts too. Reaches the scan as `--false-alarm-window` on the detached child's argv and becomes `runOrphanScan`'s `falseAlarmWindow`; the CLI refuses `0`, which `falseAlarmRate()` would read as “every firing ever recorded” rather than as a window. |
@@ -1834,7 +1883,7 @@ persona-gate-wave:
   after: quality               # quality | impl-polish — wave name after which to fire
   threshold: "all"             # "M-of-N" | "all" | "N-of-N" — passed to parseThreshold
   personas: []                 # list of persona names from .claude/personas/; empty = all catalog
-  dispatch-model: claude-opus-4-7   # alias or full model ID — default 'claude-opus-4-7'
+  dispatch-model: opus              # alias or full model ID — default 'opus'
   mode: off                    # off | warn | strict
 ```
 
@@ -1844,7 +1893,7 @@ persona-gate-wave:
 | `persona-gate-wave.after` | string (`quality` \| `impl-polish`) | `quality` | The wave role after which the hook fires. The hook runs once per session, immediately after the named wave's STATE.md update. |
 | `persona-gate-wave.threshold` | string | `"all"` | Voting threshold passed to `parseThreshold()` from `scripts/lib/persona-panel/threshold.mjs`. Accepts `"all"`, `"any"`, or `"M-of-N"` where `1 ≤ M ≤ N ≤ 20`. Example: `"6-of-6"` requires every persona to vote PASS; `"4-of-6"` allows two dissenters. |
 | `persona-gate-wave.personas` | string[] | `[]` | Roster of persona names to dispatch. Each entry must match `^[a-z0-9-]{1,64}$` and refer to a persona file under `.claude/personas/<name>.md`. When the list is empty (default), every persona in the catalog is dispatched. |
-| `persona-gate-wave.dispatch-model` | string | `claude-opus-4-7` | Model used for each persona agent dispatch. Accepts the same shape as agent frontmatter `model:` — one of `inherit` \| `sonnet` \| `opus` \| `haiku`, or a full model ID like `claude-opus-4-7`. |
+| `persona-gate-wave.dispatch-model` | string | `opus` | Model used for each persona agent dispatch. Accepts the same shape as agent frontmatter `model:` — one of `inherit` \| `sonnet` \| `opus` \| `haiku` \| `fable`, or a full model ID like `claude-opus-5-5`. Default is the alias `opus`, which tracks the current Opus; pin a full ID only for a named reproducibility need. |
 | `persona-gate-wave.mode` | string (`off` \| `warn` \| `strict`) | `off` | Behaviour on consolidator result. `off` skips dispatch entirely even when `enabled: true` (silent no-op). `warn` consolidates and logs findings under a `Persona-gate:` bullet in the wave progress update without blocking. `strict` consolidates and on any non-PROCEED verdict prompts the operator via `AskUserQuestion` to proceed-as-is, revise remaining waves, or abort. |
 
 **Validation:**

package/docs/session-config-template.md

@@ -410,6 +410,14 @@ The gate never probes the network. Without a readiness witness no host counts as
 
 Read by: `scripts/lib/config/remote-hosts.mjs`, `scripts/lib/wave-resource-gate.mjs`.
 
+`offload-first` (#1465) makes placement the first choice instead of the answer to pressure: with `true`, an offloadable role (`test` / `ui` / `perf`) goes to the first witnessed-ready declared host even when the gate verdict is `proceed`. It needs both a `remote-hosts` entry and a readiness witness to act; without them the wave stays local and the gate names the reason.
+
+```yaml
+offload-first: false                   # true = offloadable roles go to a witnessed-ready remote host even on `proceed`
+```
+
+Read by: `scripts/lib/config.mjs`, `scripts/lib/config-schema.mjs`, `scripts/lib/wave-resource-gate.mjs`.
+
 ## Evolve Extra Sources (#638)
 
 Opt-in EXTRA learning sources for `/evolve`. A `domain-regression` measurement (e.g. an eval-learn harness) runs OUT-OF-BAND and writes a sidecar JSON; `/evolve` then READS each declared sidecar and emits a `domain-regression` learning candidate per persistent regression flag. `/evolve` NEVER runs the measurement itself — this is a strict read-only consumption contract. Absent/empty ⇒ `[]` ⇒ no extra sources are read.
@@ -856,7 +864,7 @@ persona-gate-wave:
   after: quality                       # quality | impl-polish
   threshold: all                       # all | any | <m>-of-<n>
   personas: []                         # persona slugs the panel dispatches
-  dispatch-model: claude-opus-4-7
+  dispatch-model: opus                 # alias or full model ID — default 'opus'
   mode: off                            # off | warn | strict — enabled: true with mode: off never fires
 
 # Agentic test orchestrator (/test) — run profiles and artifact retention
@@ -886,6 +894,7 @@ remote-hosts:
     roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
     repo-path: ~/Projects/Alice     # optional SAFE path (default: null)
     claude-path: ~/.local/bin/claude   # optional SAFE path (default: null)
+offload-first: false                   # #1465: true = offloadable roles go to a witnessed-ready remote host even on `proceed`
 
 # Evolve extra-sources — opt-in EXTRA /evolve learning sources (#638)
 evolve:
@@ -1015,7 +1024,7 @@ reaper:
   mode: report                   # report (decide + audit only) | kill (send signals — PRD Stufe 2)
   min-age-seconds: 300           # DevWatchdog's hard limit for tsgo; the 2026-09-20 orphans were 7–17 min old
   min-scan-interval-seconds: 30  # throttle; keeps a PostToolBatch storm from taxing every tool call
-  kill-grace-ms: 10000           # DEFAULT_KILL_GRACE_MS from dispatch-common.mjs:61 — repo convention
+  kill-grace-ms: 10000           # DEFAULT_KILL_GRACE_MS from process-group.mjs:52 — repo convention
   verify-wait-ms: 500            # wait before reading the effect back (a sent signal proves nothing)
   max-hook-latency-ms: 50        # ceiling a scan may delay a hook by
   false-alarm-window: 50         # rolling window of audit decisions the HR-101 10 % rate is judged over

package/hooks/_lib/hook-import-set.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-09-22T06:04:50.134Z",
-  "head": "132e3ae1b222cc3a5e52e2a1e67e9688832f2c20",
+  "generated_at": "2026-10-01T17:18:47.118Z",
+  "head": "ffc5929f12df0b5fd7c75d9708a3aa1a5dc6fa45",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -61,6 +61,7 @@
         "pre-bash-sessions-ledger-guard.mjs",
         "pre-bash-staging-fence.mjs",
         "pre-bash-templates-first.mjs",
+        "pre-edit-sessions-ledger-guard.mjs",
         "pre-task-scope-disjoint.mjs",
         "skill-invocation-telemetry.mjs",
         "subagent-telemetry.mjs"
@@ -239,6 +240,12 @@
         "pre-bash-templates-first.mjs"
       ]
     },
+    {
+      "file": "hooks/pre-edit-sessions-ledger-guard.mjs",
+      "reachable_from": [
+        "pre-edit-sessions-ledger-guard.mjs"
+      ]
+    },
     {
       "file": "hooks/pre-task-scope-disjoint.mjs",
       "reachable_from": [
@@ -320,7 +327,6 @@
         "post-bash-issue-budget-refund.mjs",
         "post-edit-validate.mjs",
         "post-subagent-discovery-validator.mjs",
-        "post-tool-batch-wave-signal.mjs",
         "pre-bash-issue-budget.mjs",
         "pre-bash-templates-first.mjs"
       ]
@@ -947,6 +953,12 @@
         "skill-invocation-telemetry.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/fleet-protocol.mjs",
+      "reachable_from": [
+        "on-session-start.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/frontend-detect/detect.mjs",
       "reachable_from": [
@@ -1016,6 +1028,7 @@
         "pre-bash-sessions-ledger-guard.mjs",
         "pre-bash-staging-fence.mjs",
         "pre-bash-templates-first.mjs",
+        "pre-edit-sessions-ledger-guard.mjs",
         "pre-task-scope-disjoint.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1045,6 +1058,7 @@
         "pre-bash-sessions-ledger-guard.mjs",
         "pre-bash-staging-fence.mjs",
         "pre-bash-templates-first.mjs",
+        "pre-edit-sessions-ledger-guard.mjs",
         "pre-task-scope-disjoint.mjs",
         "skill-invocation-telemetry.mjs",
         "subagent-telemetry.mjs"
@@ -1145,7 +1159,14 @@
       ]
     },
     {
-      "file": "scripts/lib/orphan-reaper.mjs",
+      "file": "scripts/lib/orphan-reaper/defaults.mjs",
+      "reachable_from": [
+        "on-stop.mjs",
+        "post-tool-batch-wave-signal.mjs"
+      ]
+    },
+    {
+      "file": "scripts/lib/orphan-reaper/scan-throttle.mjs",
       "reachable_from": [
         "on-stop.mjs",
         "post-tool-batch-wave-signal.mjs"
@@ -1242,13 +1263,6 @@
         "on-session-start.mjs"
       ]
     },
-    {
-      "file": "scripts/lib/process-group.mjs",
-      "reachable_from": [
-        "on-stop.mjs",
-        "post-tool-batch-wave-signal.mjs"
-      ]
-    },
     {
       "file": "scripts/lib/resource-probe.mjs",
       "reachable_from": [
@@ -1264,9 +1278,7 @@
     {
       "file": "scripts/lib/resource-probe/parsers.mjs",
       "reachable_from": [
-        "on-session-start.mjs",
-        "on-stop.mjs",
-        "post-tool-batch-wave-signal.mjs"
+        "on-session-start.mjs"
       ]
     },
     {
@@ -1387,8 +1399,7 @@
       "reachable_from": [
         "on-session-end.mjs",
         "on-session-start.mjs",
-        "on-stop.mjs",
-        "post-tool-batch-wave-signal.mjs"
+        "on-stop.mjs"
       ]
     },
     {
@@ -1643,13 +1654,6 @@
         "pre-bash-staging-fence.mjs"
       ]
     },
-    {
-      "file": "scripts/lib/wave-executor/dispatch-common.mjs",
-      "reachable_from": [
-        "on-stop.mjs",
-        "post-tool-batch-wave-signal.mjs"
-      ]
-    },
     {
       "file": "scripts/lib/wave-sizing.mjs",
       "reachable_from": [

package/hooks/hooks-codex.json

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

package/hooks/hooks-cursor.json

@@ -83,6 +83,11 @@
             "type": "command",
             "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/config-protection.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-edit-sessions-ledger-guard.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/hooks/hooks-pi.json

@@ -38,6 +38,11 @@
             "type": "command",
             "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/config-protection.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/pre-edit-sessions-ledger-guard.mjs\"",
+            "timeout": 5
           }
         ]
       },

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.3.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.4.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -53,6 +53,11 @@
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/config-protection.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-edit-sessions-ledger-guard.mjs\"",
+            "timeout": 5
           }
         ]
       },

package/hooks/on-session-start.mjs

@@ -38,6 +38,7 @@ import path from 'node:path';
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
+import { readNavigatorLease } from '../scripts/lib/fleet-protocol.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
 import { getPlatform, resolveProjectDir } from '../scripts/lib/platform.mjs';
@@ -98,6 +99,38 @@ const bannerLines = [];
  */
 let pendingAdditionalContext = null;
 
+/** Byte budget of the navigator line (#1462, PRD 4.5 row "Bannerzeile B6"). */
+const NAVIGATOR_BANNER_MAX_BYTES = 120;
+
+/**
+ * Render the one-line navigator status (#1462, fleet protocol v1). The verdict
+ * comes from `readNavigatorLease()`: only a VALID lease is "aktiv"; a missing or
+ * expired one is "nicht nachweisbar" (ADR-004: absence is no proof of a free
+ * seat), an unreadable one says so instead of guessing. A long id is cut from
+ * the label — never from the fixed text — so the whole line stays ≤ 120 bytes.
+ * Same wording on every harness (Codex runs this hook too).
+ */
+export function navigatorBannerLine(verdict) {
+  if (verdict?.state === 'active') {
+    const lease = verdict.lease ?? {};
+    const prefix = '🧭 Navigator aktiv: ';
+    const suffix = ', Check-in nach ~/.config/navigator/checkin/';
+    const room = NAVIGATOR_BANNER_MAX_BYTES - Buffer.byteLength(prefix + suffix, 'utf8');
+    // Defence in depth: the lease reader already refuses control bytes in these
+    // two fields; a newline / ANSI / bidi byte must still never reach systemMessage.
+    let shown = String(lease.adresse ?? lease.session_id ?? 'unknown')
+      .replace(/[\p{Cc}\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/gu, '?');
+    if (Buffer.byteLength(shown, 'utf8') > room) {
+      const chars = [...shown];
+      while (chars.length > 0 && Buffer.byteLength(`${chars.join('')}…`, 'utf8') > room) chars.pop();
+      shown = `${chars.join('')}…`;
+    }
+    return `${prefix}${shown}${suffix}`;
+  }
+  if (verdict?.state === 'unreadable') return '🧭 Navigator: Lease unlesbar, Status nicht nachweisbar';
+  return '🧭 Navigator: keiner nachweisbar (keine gültige Lease)';
+}
+
 /**
  * Queue one or more banner lines for the single end-of-hook flush.
  * @param {string|null|undefined} line — multi-line strings are pushed verbatim
@@ -762,6 +795,13 @@ async function main() {
   // Resolve current branch; fall back to "unknown" when detached HEAD or no git.
   const branch = (await gitOutput(['branch', '--show-current'], projectRoot)) ?? 'unknown';
 
+  // #1443 — the commit this session started on, the fallback source for
+  // `session_start_ref` (STATE.md's `session-start-ref` had no writer). Kept
+  // only when it is a full object name; no repo, an unborn HEAD or a missing
+  // git leaves it null and the payload key is OMITTED, never fabricated.
+  const rawHeadSha = await gitOutput(['rev-parse', 'HEAD'], projectRoot);
+  const headSha = rawHeadSha && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(rawHeadSha) ? rawHeadSha : null;
+
   // v3.1.0 env-aware banner (opt-out via enable-host-banner: false in Session Config).
   // The ask-via-tool nudge rides the same opt-out flag — both are coordinator
   // reminders shown at session start; users who silence one expect silence.
@@ -987,6 +1027,18 @@ async function main() {
     pushBanner('   (registry view: repo/branch/wave. Liveness (busy/idle) is model-side — not available in this hook.)');
   }
 
+  // #1462 — Navigator line (fleet protocol v1). Exactly one line, read from the
+  // lease file only (`~/.config/navigator/leases/navigator.json`, override
+  // NAVIGATOR_CONFIG_DIR); registry `role` and ListAgents are hints, never proof.
+  // Gated like the peer lines above: no host banner → no navigator line. A read
+  // failure must never block the hook — the helper is fail-closed itself, the
+  // try/catch only guards against the unexpected.
+  if (bannerData) {
+    try {
+      pushBanner(navigatorBannerLine(await readNavigatorLease()));
+    } catch { /* swallow — hook must remain non-blocking */ }
+  }
+
   // Epic #583 W3-P3 — Mechanical peer-detection banner (independent of the
   // v3.1.0 registry-driven detectPeers() output). discoverActiveSessions()
   // reads every worktree's session.lock and the host registry; this is the
@@ -1126,6 +1178,7 @@ async function main() {
     // makes the supersession rate measurable instead of inferred (HR-105).
     peers_superseded: mechanicalPeersSuperseded,
   };
+  if (headSha) payload.head_sha = headSha;
 
   // #1091 — record the native SessionStart source so "does the same raw
   // session_id repeat under source=resume?" becomes answerable from

package/hooks/on-stop.mjs

@@ -883,7 +883,9 @@ export async function maybeTriggerOrphanScan({
     // Cheapest gate first: disabled means no stat, no spawn, no module load.
     if (cfg.enabled !== true) return { spawned: false, reason: 'disabled' };
 
-    const reaper = await import('../scripts/lib/orphan-reaper.mjs');
+    // The throttle module only — the scan's ledger, `ps` and kill-ladder code
+    // load in the detached child, never on this hook path (#1437).
+    const reaper = await import('../scripts/lib/orphan-reaper/scan-throttle.mjs');
     const markerPath = reaper.scanMarkerPath(root);
     const nowMs = typeof now === 'number' ? now : Date.now();
 

package/hooks/post-tool-batch-wave-signal.mjs

@@ -416,7 +416,9 @@ export async function maybeTriggerOrphanScan({
     // Cheapest gate first: disabled means no stat, no spawn, no module load.
     if (cfg.enabled !== true) return { spawned: false, reason: 'disabled' };
 
-    const reaper = await import('../scripts/lib/orphan-reaper.mjs');
+    // The throttle module only — the scan's ledger, `ps` and kill-ladder code
+    // load in the detached child, never on this hook path (#1437).
+    const reaper = await import('../scripts/lib/orphan-reaper/scan-throttle.mjs');
     const markerPath = reaper.scanMarkerPath(root);
     const nowMs = typeof now === 'number' ? now : Date.now();
 

package/hooks/pre-bash-memory-propose-audit.mjs

@@ -24,8 +24,9 @@
 
 import { readStdin, emitAllow } from '../scripts/lib/io.mjs';
 import crypto from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { findScopeFile } from '../scripts/lib/hardening.mjs';
@@ -86,7 +87,8 @@ const KNOWN_FLAGS = Object.freeze([
  *
  * WHY THE HASH IS HERE (#1415, 2026-09-21): until today this hook wrote a
  * merely flag-redacted `argv_truncated` (512 chars of command text) into
- * `orchestrator.memory.propose_invoked` — a TRACKED `events.jsonl` line and,
+ * `orchestrator.memory.propose_invoked` — an `events.jsonl` line (gitignored
+ * here via `.gitignore:57`; consumer repos may track it) and,
  * with the webhook configured, a network payload. Redaction covered only the
  * five `--insight/--subject/--evidence/--content/--reason` values and said so
  * in its own caveat: `$VAR`, `$(cat secret)` and any value written elsewhere
@@ -123,6 +125,53 @@ function flagsPresent(command) {
   );
 }
 
+/**
+ * The working directory as a value that carries no absolute host path (#1439).
+ *
+ * Relative to `projectDir` (`.` when equal); a directory OUTSIDE the project is
+ * written as `sha256:<12 hex>` of its resolved path instead — still groupable,
+ * never the path itself. Until 2026-09-25 this was `process.cwd()` verbatim,
+ * i.e. `/Users/<name>/…` in an events.jsonl line (gitignored here via
+ * `.gitignore:57`; consumer repos may track it) and, with the webhook
+ * configured, in a network payload. No production reader consumes `cwd`.
+ *
+ * Both sides are realpath-resolved before comparing: on macOS the tmp dir is
+ * `/var/…` while `process.cwd()` reports `/private/var/…`, and a naive
+ * `path.relative` then calls the project dir itself `../../../private/var/…`.
+ * A path that cannot be resolved falls back to `path.resolve` — never throws.
+ *
+ * A project dir that is no project boundary — the filesystem root, the home
+ * dir, or an ancestor of it (`/Users`) — also gets the hash form: relative to
+ * `/` the cwd reads `Users/<name>/…`, i.e. the username in a webhook-bound
+ * event, the very leak the relative form exists to prevent. The ancestor test
+ * is path-segment-wise (`path.relative`), so `/Users/al` is NOT an ancestor of
+ * `/Users/alice` the way a string prefix would claim.
+ *
+ * @param {string} cwd
+ * @param {string} projectDir
+ * @returns {string}
+ */
+function relativeCwd(cwd, projectDir) {
+  const real = (p) => {
+    try { return realpathSync(p); } catch { return path.resolve(p); }
+  };
+  // `..`-prefixed (above the base) or absolute (another Windows drive).
+  const escapes = (rel) =>
+    rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel);
+  const realCwd = real(cwd);
+  const realProject = real(projectDir);
+  const rel = path.relative(realProject, realCwd);
+  if (rel === '') return '.';
+  // Same sha256 recipe as `command_hash`, cut to 12 hex.
+  const hashed = `sha256:${hashCommand(realCwd).slice(0, 12)}`;
+  if (escapes(rel)) return hashed;
+  if (path.dirname(realProject) === realProject) return hashed; // filesystem root
+  let home = null;
+  try { home = real(os.homedir()); } catch { /* no home dir: root check above still holds */ }
+  if (home !== null && !escapes(path.relative(realProject, home))) return hashed;
+  return rel;
+}
+
 /**
  * Resolve the session_id from the hook stdin payload, with fallback to the
  * persisted file written by on-session-start.mjs. Returns null when neither
@@ -219,7 +268,7 @@ async function main() {
       command_hash: commandHash,
       flags_present: flags,
       argv_length: command.length,
-      cwd: process.cwd(),
+      cwd: relativeCwd(process.cwd(), projectDir),
       exit_code: null,
     });
   } catch { /* telemetry never blocks the hook (#1183) */ }

package/hooks/pre-bash-sessions-ledger-guard.mjs

@@ -268,8 +268,9 @@
  *     hides its payload from this matcher by construction.
  *   - `sponge`, `install`, `rsync`, `awk > file` and other less common write
  *     verbs (a redirect inside an `awk` program string is quoted data here).
- *   - The Write/Edit tools — a different PreToolUse matcher entirely
- *     (`hooks/enforce-scope.mjs` territory), not this hook's surface.
+ *   - The Write/Edit/MultiEdit tools — a different PreToolUse matcher entirely,
+ *     guarded by `hooks/pre-edit-sessions-ledger-guard.mjs` (#1443), not this
+ *     hook's surface.
  *   - The #385 repair-apply subshell/backtick deny (`unwrapSubshellLayers`)
  *     only unwraps a command that IS, in its entirety, one wrapped run —
  *     `x=$(node scripts/repair-invalid-sessions.mjs --apply)` (the wrapper is
@@ -1521,11 +1522,36 @@ async function main() {
     ? `${target.slice(0, TARGET_ECHO_MAX)}… (${target.length} chars)`
     : target;
 
+  // #1442 — a repair-apply VARIANT (extra flag, wrapper, env prefix) reached
+  // here because it is not the exact sanctioned string. Text only, no matching
+  // change: name the one command that IS allowed, and say why the most common
+  // re-spelling cannot work — this hook reads SO_DISABLED_HOOKS from its OWN
+  // process env (hooks/_lib/profile-gate.mjs), never from the command text, and
+  // a leading `VAR=val` token also breaks the exact match above.
+  if (target.startsWith(REPAIR_APPLY_MARKER)) {
+    emitDeny(
+      [
+        `Direct write to the sessions ledger blocked: '${shown}'`,
+        `The sanctioned repair invocation is allowed ONLY as the exact bare command:`,
+        `  ${REPAIR_APPLY_CANONICAL_COMMAND}`,
+        `Any variant — an extra flag, a wrapper, an env prefix — is denied.`,
+        `A SO_DISABLED_HOOKS=… prefix INSIDE the command has no effect: this hook reads`,
+        `it from the environment of the whole session, never from the command text.`,
+        `Override (intentional maintenance only, operator-side — e.g. started with \`!\`):`,
+        `SO_DISABLED_HOOKS=pre-bash-sessions-ledger-guard as the environment of the session`,
+        `See: GitLab #958, #1442, skills/session-end/session-metrics-write.md`,
+      ].join('\n'),
+    );
+    return;
+  }
+
   emitDeny(
     [
       `Direct write to the sessions ledger blocked: '${shown}'`,
       `The ledger is append-only through its validating writer:`,
       `  node scripts/emit-session.mjs --entry '<json>'    (or pipe the JSON on stdin)`,
+      `After the writer succeeds, verify the record (read-only; does not repair):`,
+      `  node scripts/check-sessions-integrity.mjs --session-id '<semantic-id>'`,
       `Hand-composing a record and appending it — with a shell redirect, or from`,
       `inside an interpreter (node -e / python -c) — skips schema validation. That is`,
       `exactly how the malformed records in GitLab #958 and #1408 landed.`,