session-orchestrator 5.3.0 → 5.5.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`, exported; `scripts/vault-backfill.mjs` resolves its stub root through it, #1094), `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,10 +807,10 @@ 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. |
+| `vault-integration.gitlab-groups` | string[] or null | `null` | List of GitLab group paths to scan for repos missing `.vault.yaml`. Parsed by `_parseVaultIntegration` (`scripts/lib/config/vault-integration.mjs`) and consumed by `scripts/vault-backfill.mjs`. Accepts a comma string, `[a, b]`, or a YAML block list; in the inline-object form more than one group needs `[a, b]`; an empty list is `null`. YAML semantics: `null`, `~` and an empty value mean unset (as a list element too, where they are dropped), and each element loses one pair of matching quotes — `["a"]` is the group `a`, and only a quoted `"null"` element is a group named `null`. Also consumed by the `/plan retro` vault-backfill sub-mode (`skills/plan/mode-retro.md` Phase 1.6 Step 1). When null/unset and neither `--groups` nor `--yes` is passed, the backfill CLI exits 1 with `no GitLab groups specified — pass --groups <CSV> or set vault-integration.gitlab-groups in CLAUDE.md`. |
 
 ### Environment override: `VAULT_MIRROR_CANONICAL_SUFFIX`
 
@@ -843,7 +866,7 @@ Opt-out configuration for the agent-writable memory tool. During a wave, an agen
 
 This is a Hermes-style memory-write API **without** Hermes' overwrites-manual-edits critique: the operator confirmation is mandatory and there is no silent overwrite path. Three safety layers keep the surface conservative:
 
-1. **Quota per wave** — `quota-per-wave` (default `5`) caps how many proposals any single agent may queue within one wave. Excess proposals exit `1` and the call-site logs the rejection.
+1. **Quota per wave** — `quota-per-wave` (default `5`) caps how many proposals ONE WAVE may queue, all of its agents together — not each agent: the store counts a wave's records by `wave_id` only (`scripts/lib/memory-proposals/store.mjs`). In a wave of N agents the 6th proposal of the wave exits `1` regardless of which agent sends it, so one agent that proposes five times uses up the quota for every sibling. Excess proposals exit `1` and the call-site logs the rejection.
 2. **Confidence floor** — `confidence-floor` (default `0.5`) rejects low-confidence proposals before they reach the operator (exit `2`). Tuned so a learning is only proposed when the agent is at least 50% sure of the insight.
 3. **AUQ confirm-or-discard** — the session-end phase never auto-persists. Every proposal is `AskUserQuestion`-gated; the operator can accept, reject, or edit before commit.
 
@@ -853,14 +876,14 @@ All fields live under the top-level `memory` object in your Session Config host
 memory:
   proposals:
     enabled: true                # default true; opt-out master toggle for the memory.propose feature
-    quota-per-wave: 5            # max proposals an agent may queue per wave (exit 1 on overflow)
+    quota-per-wave: 5            # max proposals per wave, all agents together (exit 1 on overflow)
     confidence-floor: 0.5        # proposals below this confidence are rejected (exit 2)
 ```
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `memory.proposals.enabled` | boolean | `true` | Master toggle for the entire memory-proposals feature. When `false`, the `memory.propose` CLI exits `3` (rejected-wrong-context) for every call and session-end Phase 3.6.3 is skipped. When `true`, agents may queue proposals during waves and the coordinator surfaces them at session-end. PRD F2.1 / issue #501. |
-| `memory.proposals.quota-per-wave` | integer | `5` | Maximum number of proposals one wave-executor agent can queue per wave. The 6th proposal from the same agent in the same wave exits `1` (quota-exceeded). Bounds: integer ≥ 0. Set to `0` to disable proposals from agents without disabling the feature entirely (operator can still propose). |
+| `memory.proposals.quota-per-wave` | integer | `5` | Maximum number of proposals a wave can queue, counted across ALL of its agents (the store counts records by `wave_id` only). The 6th proposal of a wave exits `1` (quota-exceeded) whichever agent sends it — in a wave of N agents, the first five proposals of the wave win. Bounds: integer ≥ 0. Set to `0` to disable proposals from agents without disabling the feature entirely (operator can still propose). |
 | `memory.proposals.confidence-floor` | float | `0.5` | Minimum confidence (0.0..1.0) required for a proposal to be queued. Proposals with `--confidence < confidence-floor` exit `2` (rejected-low-confidence) before reaching the operator. Bounds: `0.0 ≤ value ≤ 1.0`. Set to `0.0` to accept any confidence (operator filters at AUQ time). |
 
 ### Agent CLI invocation
@@ -900,7 +923,7 @@ A successful dry-run exits `0` with stdout status `dry-run-ok` (see updated exit
 |-----------|-----------------|---------|--------------|
 | `0` | `queued` | Queued | Proposal accepted into the per-wave staging directory; awaits operator confirmation at session-end Phase 3.6.3. |
 | `0` | `dry-run-ok` | Validated, not written | `--dry-run` was passed and the proposal (argv + schema) validated successfully. No write to `proposals.jsonl` occurs; the wrong-context gates are bypassed under this flag (#741.3). |
-| `1` | `quota-exceeded` | Rejected — quota exceeded | This agent has already queued `quota-per-wave` proposals in this wave. Subsequent calls from the same agent fail until the next wave. Not applicable under `--dry-run` (gate bypassed). |
+| `1` | `quota-exceeded` | Rejected — quota exceeded | This wave has already queued `quota-per-wave` proposals, from any of its agents. Every further call in this wave fails, whichever agent makes it, until the next wave. Not applicable under `--dry-run` (gate bypassed). |
 | `2` | `rejected-low-confidence` | Rejected — low confidence | `--confidence` argument is below `confidence-floor`. Tighten the insight or raise the confidence (operator can still tune the floor). |
 | `3` | `rejected-wrong-context` | Rejected — wrong context | Feature disabled (`enabled: false`), STATE.md not active, or `SO_WAVE_AGENT != "1"` (call originated outside a wave-executor agent context). Not applicable under `--dry-run` (gate bypassed). |
 | `4` | `error` | Arg error | Missing or malformed flag — invalid `--type`, empty `--subject`, non-numeric `--confidence`. The CLI prints a one-line usage message on stderr. |
@@ -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,12 +1621,12 @@ 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. |
 
-**Used by:** `hooks/post-tool-batch-wave-signal.mjs`, `hooks/on-stop.mjs` (both via `maybeTriggerOrphanScan()`), `scripts/lib/orphan-reaper.mjs`, `scripts/lib/config/reaper.mjs` (`_parseReaper`). PRD `docs/prd/2026-09-20-prozessgruppen-kill-und-waisen-waechter.md`, Epic #1425, issue #1432.
+**Used by:** `hooks/post-tool-batch-wave-signal.mjs`, `hooks/on-stop.mjs` (both via `maybeTriggerOrphanScan()` from `scripts/lib/orphan-reaper/trigger.mjs`), `scripts/lib/orphan-reaper.mjs`, `scripts/lib/config/reaper.mjs` (`_parseReaper`). PRD `docs/prd/2026-09-20-prozessgruppen-kill-und-waisen-waechter.md`, Epic #1425, issue #1432.
 
 ## Gate Timeout — Path B (#1425 A3)
 
@@ -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/docs/vault-docs-architecture.md

@@ -169,10 +169,14 @@ entirely. Source: `docs/session-config-reference.md` § Docs Orchestrator.
 The `docs-writer` agent operates under a **hallucination ban**: every
 substantive paragraph must trace to one of the canonical four sources, or
 carry an inline `<!-- REVIEW: source needed -->` marker. The four sources are
-defined once and reused everywhere:
-
-1. **diff** — `git diff $SESSION_START_REF..HEAD`
-2. **git-log** — `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"`
+defined once — in `skills/docs-orchestrator/SKILL.md` — and reused everywhere.
+Diffs take `"$SESSION_RANGE"`, ONE complete range (the pinned SHA's
+`<sha>..HEAD`, else the resolved `<base>...HEAD` from the accessor in
+`skills/session-end/plan-verification.md`); only the log keeps the two-dot
+`$SESSION_START_REF..HEAD`. An empty range or ref is a skip, never "no changes":
+
+1. **diff** — `git diff "$SESSION_RANGE"`
+2. **git-log** — `git log "$SESSION_START_REF..HEAD" --format="%H %s%n%b"`
 3. **session-memory** — `~/.claude/projects/<project>/memory/session-*.md` and
    `.orchestrator/` outputs
 4. **affected-files** — files in the wave-scope `allowedPaths` block

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-03T07:30:53.188Z",
+  "head": "0cfbaa2c4fad16d825b94b8000ca8aea3dc9af68",
   "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": [
@@ -301,6 +308,7 @@
     {
       "file": "scripts/lib/command-blocker.mjs",
       "reachable_from": [
+        "on-stop.mjs",
         "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-validate.mjs",
@@ -308,7 +316,8 @@
         "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "pre-bash-staging-fence.mjs",
-        "pre-bash-templates-first.mjs"
+        "pre-bash-templates-first.mjs",
+        "pre-task-scope-disjoint.mjs"
       ]
     },
     {
@@ -320,7 +329,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"
       ]
@@ -835,8 +843,7 @@
       "file": "scripts/lib/env-check.mjs",
       "reachable_from": [
         "post-bash-write-verify.mjs",
-        "post-edit-validate.mjs",
-        "pre-bash-memory-propose-audit.mjs"
+        "post-edit-validate.mjs"
       ]
     },
     {
@@ -947,6 +954,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": [
@@ -963,8 +976,7 @@
       "file": "scripts/lib/hardening.mjs",
       "reachable_from": [
         "post-bash-write-verify.mjs",
-        "post-edit-validate.mjs",
-        "pre-bash-memory-propose-audit.mjs"
+        "post-edit-validate.mjs"
       ]
     },
     {
@@ -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,21 @@
       ]
     },
     {
-      "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"
+      ]
+    },
+    {
+      "file": "scripts/lib/orphan-reaper/trigger.mjs",
       "reachable_from": [
         "on-stop.mjs",
         "post-tool-batch-wave-signal.mjs"
@@ -1242,13 +1270,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 +1285,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"
       ]
     },
     {
@@ -1284,10 +1303,12 @@
     {
       "file": "scripts/lib/scope-gate.mjs",
       "reachable_from": [
+        "on-stop.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-validate.mjs",
         "post-tool-batch-wave-signal.mjs",
-        "pre-bash-memory-propose-audit.mjs"
+        "pre-bash-memory-propose-audit.mjs",
+        "pre-task-scope-disjoint.mjs"
       ]
     },
     {
@@ -1387,8 +1408,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 +1663,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": [