session-orchestrator 3.23.0 → 4.0.0

package/docs/session-config-reference.md

@@ -61,6 +61,8 @@ Bypass via `SO_SKIP_CONFIG_VALIDATION=1`. Missing fields can be patched into an
 
 **Stale-citation note:** an older code comment on the `custom-phases:` key in this repo's own `CLAUDE.md` cites a per-key regex (`/^custom-phases:\s*$/`) as the mechanism. That citation predates the #830 generalisation — `custom-phases.mjs` (like all 37 consumers) now delegates to the shared `matchBlockHeader(line, 'custom-phases')`, which is strictly MORE tolerant than the old per-key regex (it additionally accepts the dash-bullet and bold-bullet renderings). The no-inline-comment failure mode is unchanged; only the underlying mechanism moved from a bespoke regex to the shared helper. Treat any remaining per-key regex citation in prose (including in this file, prior to this section's introduction) as documentation of the OLD mechanism — the general contract above is current.
 
+**A second, orthogonal gotcha shares this section: a multi-line `<!-- … -->` comment (#1162).** Every block-shaped parser now strips commented-out lines before matching, via `scripts/lib/config/block-preprocess.mjs` — so a block commented out to disable it can no longer be read as live config, and a bold-bullet sub-key rendering (`- **enabled:** true`) is normalised before parsing instead of silently missing its regex. The one failure mode that still exists is an **unterminated** `<!--` — a stray opener with no matching `-->` anywhere in the rest of the document. `scripts/parse-config.mjs` detects this ONCE per session (not once per parser) and prints a single stderr WARN: `⚠ <file>: unterminated <!-- at line N — comment stripping disabled for the whole document`. The fail-closed direction differs by consumer: a block PARSER gets its lines back UNFILTERED (nothing may silently vanish), while the two destructive-bypass scanners (`allow-config-weakening`, `allow-destructive-ops`) treat an unterminated comment as the bypass being **NOT ARMED** — an ambiguous document must never grant an opt-in it cannot read cleanly.
+
 ## Policy Files
 
 Some sub-configs live in dedicated policy files under `.orchestrator/policy/`:
@@ -74,12 +76,46 @@ Some sub-configs live in dedicated policy files under `.orchestrator/policy/`:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `agents-per-wave` | integer or integer with overrides | `6` | Maximum parallel subagents per wave. Supports session-type overrides: `6 (deep: 18)` outputs `{"default": 6, "deep": 18}`. Plain integers remain plain. The override key names a session type but does **not** create one: there is no `session-type:` Session Config key — `parseSessionConfig()` emits none, so writing one into a repo's `## Session Config` block is inert prose. The session type comes from the `/session` argument (default `deep`, see `commands/session.md`) and is persisted to STATE.md frontmatter as `session-type:`, which is the only live read (`scripts/print-applicable-rules.mjs` rule mode-gating). |
+| `agents-per-wave` | integer or integer with overrides | `6` | Maximum parallel subagents per wave. Supports session-type overrides: `6 (deep: 18)` outputs `{"default": 6, "deep": 18}`. The override key set is OPEN — `_coerceInteger` (`scripts/lib/config/coercers.mjs`) parses whatever keys the parentheses contain, so `6 (deep: 18, ultradeep: 18)` outputs `{"default": 6, "deep": 18, "ultradeep": 18}` with no code change (see § Session Profile below). Plain integers remain plain. The override key names a session type but does **not** create one: there is no `session-type:` Session Config key — `parseSessionConfig()` emits none, so writing one into a repo's `## Session Config` block is inert prose. The session type comes from the `/session` argument (default `deep`, see `commands/session.md`) and is persisted to STATE.md frontmatter as `session-type:`, which is the only live read (`scripts/print-applicable-rules.mjs` rule mode-gating). |
 | `agent-mapping` | object | null | Optional mapping of role keys to agent names for explicit agent binding. Keys: `impl`, `test`, `db`, `ui`, `security`, `compliance`, `docs`, `perf`. Example: `{ impl: code-editor, test: test-specialist }`. Overrides auto-discovery when present. Values may carry a channel prefix — see § `agent-mapping` values below. |
 | `waves` | integer | `5` | Number of execution waves for feature and deep sessions. |
 | `recent-commits` | integer | `20` | Number of recent commits to display during session start git analysis. |
 | `special` | string | none | Repo-specific instructions. Freeform text that the orchestrator reads and follows during sessions. |
 
+### Session Profile — `session-profile` (NOT a Session Config key)
+
+`session-profile` names a WAVE-SHAPE variant on top of an unchanged `session-type`. It is listed here because it is easy to look for in the wrong place: **it is not a Session Config key and `parseSessionConfig()` does not emit one.** Writing `session-profile:` into a repo's `## Session Config` block is inert prose, exactly like `session-type:` (see the `agents-per-wave` row above).
+
+| Aspect | Value |
+|---|---|
+| Where it lives | STATE.md frontmatter (`session-profile: ultradeep`), written per session |
+| Who writes it | The `/session ultradeep` argument alias — `commands/session.md` |
+| Read/write API | `readSessionProfile` / `setSessionProfile` / `SESSION_PROFILE_FIELD` in `scripts/lib/state-md.mjs` |
+| Absent means | No profile. Never an empty string, never `none` — `readSessionProfile` returns `null` |
+| Session record | Optional `session_profile` field (`scripts/lib/session-schema/constants.mjs` `OPTIONAL_FIELDS`); records without it validate unchanged |
+| Defined values | `ultradeep` (7 waves, coordinator-direct Synthesis-Gate at wave 2) — spec: `docs/prd/2026-09-06-ultradeep-session-profile.md` |
+
+`session-type` NEVER becomes `ultradeep`: that value is a closed set in `scripts/lib/session-schema/constants.mjs`, `scripts/lib/wave-sizing.mjs` and `scripts/lib/session-close-backfill.mjs`, and an unknown member degrades SILENTLY there (telemetry maps it to `"other"`, the close-backfill labels it `housekeeping`). The profile field exists so no closed set has to change.
+
+**Sizing an ultradeep session** uses the open override key set:
+
+```yaml
+agents-per-wave: 6 (deep: 18, ultradeep: 18)
+waves: 5                # must be >= 7 for the ultradeep wave shape
+```
+
+Verified against the parser (2026-09-06, `scripts/lib/config/coercers.mjs`):
+
+```
+$ node -e "import('./scripts/lib/config/coercers.mjs').then(m => console.log(JSON.stringify(
+    m._coerceInteger(new Map([['agents-per-wave','6 (deep: 18, ultradeep: 18)']]), 'agents-per-wave', 6))))"
+{"default":6,"deep":18,"ultradeep":18}
+```
+
+Two consumers resolve that object to `.default` rather than to a mode key — `scripts/lib/resource-probe/evaluate.mjs` and `scripts/lib/wave-resource-gate.mjs` (see `heavy-repo` in § Environment Awareness) — so an `ultradeep: 18` override does NOT raise the resource gate's cap.
+
+**Budgets are deliberately absent.** The PRD's `ultradeep.max-agents-total` / `max-wall-clock-hours` / `max-output-tokens` / `on-breach` block (§ 7) is NOT implemented and no key of that name is read anywhere. It stays deferred until three ultradeep runs have been measured, per `.claude/rules/host-resources.md` HR-105 — a threshold whose firing rate nothing records is unfalsifiable. Do not add one ahead of the measurement.
+
 ### `agent-mapping` values — channel prefixes (#1150)
 
 A mapping value has three forms, distinguished by the colon:
@@ -98,7 +134,7 @@ agent-mapping: { impl: cursor:composer-2.5, test: cursor:cursor-grok-4.6-high, s
 
 **Where the rest of the contract lives** — deliberately not here, so one place owns it:
 
-- **Model selection** (which model for which role, and why): the account-switch routing SSOT, ADR-002 / `tools/routing/routing.yaml`. Working defaults are `composer-2.5` for foreign impl and `cursor-grok-4.6-high` for review / test-writing / judgment roles.
+- **Model selection** (which model for which role, and why): the operator's model-routing SSOT (ADR-002). Working defaults are `composer-2.5` for foreign impl and `cursor-grok-4.6-high` for review / test-writing / judgment roles.
 - **Dispatch contract** (detached worktree, the `never_foreign` role lock, the filesystem-measured verdict, the MANDATORY Claude semantic diff-review before merge-back, wall-clock timeout instead of `maxTurns`, and the `orchestrator.foreign_dispatch.completed` event that replaces the hook-chain telemetry a foreign run cannot emit): `skills/wave-executor/wave-loop.md` § Third branch: foreign-model dispatch.
 
 ## VCS & Infrastructure
@@ -111,8 +147,34 @@ agent-mapping: { impl: cursor:composer-2.5, test: cursor:cursor-grok-4.6-high, s
 | `cross-repos` | list | none | Related repositories under `~/Projects/`. The orchestrator checks their git state and critical issues during session start. |
 | `cross-repo.projects` | list | `[]` | Repos to process when running cross-repo maintenance scripts (`run-migrate-v2-cross-repo.mjs`, `vault-integration-watcher.mjs`, `promote-vault-strict.mjs`). Each entry is a path (absolute, `~`-prefixed, or bare name resolved under `~/Projects/`). When this list is empty or absent, those scripts emit a one-line notice and exit 0 — they never error on an empty list. Example: `[~/Projects/my-app, ~/Projects/another-app]`. |
 | `pencil` | string | none | Path to a `.pen` design file (relative to project root). Enables design-code alignment reviews after Impl-Core and Impl-Polish waves. |
-| `ecosystem-health` | boolean | `false` | Enable service health checks at session start. Requires `health-endpoints` to be configured. |
-| `health-endpoints` | list | none | Service URLs to check health. Each entry is an object with `name` and `url` fields. |
+| `ecosystem-health` | boolean | `false` | Enable service health checks at session start. Requires `health-endpoints` to be configured. Accepts the SCALAR form (`ecosystem-health: true`) read off the flat key/value map, or a BLOCK form (`ecosystem-health:` with no value, followed by an indented body — the wizard's output) read via `_parseEcosystemHealthBlockEnabled()`; the scalar wins when both are present (#1174). |
+| `health-endpoints` | list | none | Service URLs to check health. Each entry is an object with `name` and `url` fields. Parsed by `scripts/lib/config/health-endpoints.mjs`, which accepts THREE forms (#1174) — see below. |
+
+**`health-endpoints` accepted forms.** Before #1174 the parser read this key off the flat KV map,
+which bails to `null` the instant a value contains `{` and cannot see a nested YAML block at all;
+the wizard's own output (Form B) silently failed to parse. All three forms below are parsed
+content-scoped, independent of the flat KV map:
+
+```yaml
+# Form A — inline object array
+health-endpoints: [{name: "API", url: "https://a/health"}, {name: "W", url: "http://w:8080/z"}]
+
+# Form B — nested block (top-level, or one level under `ecosystem-health:`); the wizard's output.
+# Block items may also be inline objects, `- { name: API, url: … }` (the form this file's own
+# example above uses).
+health-endpoints:
+  - name: API
+    url: https://api.example.com/health
+
+# Form C — bare bracket list of URLs; each URL becomes its own name ({ name: <url>, url: <url> })
+health-endpoints: [https://a/health, https://b/health]
+```
+
+The `name=url` shorthand (Form D) is **not** supported — an entry containing `=` is treated
+verbatim as a Form-C URL, never split on `=`. A malformed entry (missing `name` or `url`, an
+unmatched brace) resolves to `null` for the whole key and prints exactly one
+`config: health-endpoints:` WARN to stderr — it never throws, so a broken config key cannot take
+down session-start.
 | `issue-limit` | integer | `50` | Maximum issues to fetch when querying VCS during session start. |
 | `stale-branch-days` | integer | `7` | Days of inactivity before a branch is flagged as stale. |
 | `stale-issue-days` | integer | `30` | Days without progress before an issue is flagged for triage. |
@@ -255,7 +317,7 @@ slopcheck:
 | `grounding-injection-max-files` | integer | `3` | Max files with recent `edit-format-friction` stagnation history to inject as line-numbered GROUNDING blocks into each agent's prompt before dispatch (wave-executor pre-dispatch step). Per-agent scope; selects top N by recency. `0` disables the feature. Gated on `persistence: true`. (#85) |
 | `isolation` | string | `auto` | Agent isolation mode: `worktree`, `none`, or `auto`. `auto` resolves per-wave via the graduated default (#194): ≤2 agents → `none`, 3–4 agents on feature/deep → `worktree`, ≥5 agents → `worktree`, housekeeping 3–4 → `none`. Explicit `worktree` or `none` overrides the graduation. See [isolation graduation](#isolation-graduation) below. |
 | `max-turns` | integer or string | `auto` | Maximum agent turns before PARTIAL. Auto: housekeeping=8, feature=15, deep=25. |
-| `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. |
+| `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 --> |
 
 ### enforcement-gates: the five gate keys (#800/#915)
 
@@ -385,18 +447,18 @@ state-md-lock:
 
 ## Discovery-Validator (PSA-006 Enforcement, #567)
 
-Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") appearing in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only — exit 0 always, never blocks the agent; a blocking hard-gate is reserved for a future iteration. Default ON (flip risk is near-zero; the hook only ever generates telemetry).
+Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") appearing in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only — exit 0 always, never blocks the agent; a blocking hard-gate is reserved for a future iteration. Default OFF (opt-in) — the #690 flip to ON was reverted 2026-09-02 (#1191) after fleet measurement showed 6,946 violation events accumulating in 18 repos that never declared the block.
 
 All fields live under a top-level `discovery-validator` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
 
 ```yaml
 discovery-validator:
-  enabled: true                        # on by default; log+warn-only, exit-0-always — set false to silence
+  enabled: true                        # off by default; opt in per repo — log+warn-only, exit-0-always
 ```
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `discovery-validator.enabled` | boolean | `true` | Master toggle. When `false`, the `SubagentStop` hook is bypassed entirely — no transcript scanning, no `discovery_validator_violation` events. Note: when the `discovery-validator:` block is present but omits the `enabled:` line, the parser conservatively resolves to `false` (only a literal `true` flips it) — the `true` default applies when the block is absent entirely. Always set `enabled` explicitly when adding this block. |
+| `discovery-validator.enabled` | boolean | `false` | Master toggle. When `false` (or when the block is absent), the `SubagentStop` hook is bypassed entirely — no transcript scanning, no `discovery_validator_violation` events. Note: when the `discovery-validator:` block is present but omits the `enabled:` line, the parser conservatively resolves to `false` — only a literal `true` enables the hook. Always set `enabled` explicitly when adding this block. |
 
 **Used by:** `hooks/post-subagent-discovery-validator.mjs`, `scripts/lib/config/discovery-validator.mjs` (`_parseDiscoveryValidator`). See `.claude/rules/parallel-sessions.md` § PSA-006.
 
@@ -678,6 +740,8 @@ vault-integration:
 
 > **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).
 
+> **`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/host-identity.mjs` `_privateDir()` resolves the directory holding `owner.yaml`, `host-private.json`, and the host-alias ledger (`SO_HOST_ALIASES_FILE`, see `host-identity.mjs`) with precedence env-var (`SO_CONFIG_HOME`, names the private dir ITSELF) > `XDG_CONFIG_HOME` (names its PARENT — `owner-config-loader.mjs` uses the same variable the same way) > 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).
+
 > **Parser accepts three key-line renderings (#823).** The `vault-integration:` key line is recognized in plain form (`vault-integration:`), dash-bullet form (`- vault-integration:`), and bold-bullet form (`- **vault-integration:**`) — each paired with either the inline-object shape (`{ enabled: true, ... }` on the same line) or the indented block shape shown above. Parser: `scripts/lib/config/vault-integration.mjs` (`_parseVaultIntegration`).
 
 | Field | Type | Default | Description |
@@ -818,7 +882,7 @@ Memory proposals are one of five Epic #498 Phase 2 features that share the same
 
 Together: F2.1 captures fresh insight mid-flight, F2.2 consolidates old insight at scale, F2.3 surfaces it at the start, F2.4/F2.5 distill it into the durable peer-card profiles.
 
-**Used by:** `scripts/lib/memory-proposals/{schema,store,collector,sink}.mjs`, `scripts/memory-propose.mjs`, `agents/memory-proposal-collector.md`, `hooks/pre-bash-memory-propose-audit.mjs`, `skills/session-end/SKILL.md` Phase 3.6.3.
+**Used by:** `scripts/lib/memory-proposals/{schema,store,collector,sink}.mjs`, `scripts/memory-propose.mjs`, `docs/memory-proposal-flow.md`, `hooks/pre-bash-memory-propose-audit.mjs`, `skills/session-end/SKILL.md` Phase 3.6.3.
 
 **Cross-reference:** issue #501, PRD F2.1 in the Learning-Memory Modernization PRD; issue #741.3 (`--dry-run` flag + `dry-run-ok` status). Sibling features: `memory.banner` (above, F2.3 / #505), `dialectic.cadence` (F2.5 / #506), Auto-Dream (F2.2 / #502, surfaced via `memory-cleanup-soft-limit`).
 
@@ -1190,6 +1254,38 @@ Read by: `scripts/lib/config/custom-phases.mjs` (parser), `skills/session-end/SK
 - `archive-closed-prds` (#782, Epic #774) — `node scripts/archive-closed-prds.mjs --apply` — archives `docs/prd/` PRDs (defaults).
 - `archive-closed-plans` (#786) — `… --apply --prd-dir docs/plans --vault-subdir 01-projects/session-orchestrator/plans` — archives `docs/plans/` executable-plan artefacts of closed features/Epics. The plan's tracking `#NNN` (inline in the plan's `Source:` header, see `skills/write-executable-plan/`) is the anchor this phase reads; a plan with no `#NNN` is never archived (fail-closed `no-epic-ref`).
 
+## Remote Hosts (#1160)
+
+Opt-in declaration of ssh-reachable hosts a heavy wave role may be OFFLOADED to instead of shrinking the wave under local resource pressure. This key only DECLARES: it never probes a host, never dispatches, and never changes a wave by itself. Absent/empty ⇒ `[]` ⇒ every wave stays local, exactly as before.
+
+**Parser gotcha:** like every other block-shaped Session Config key, the `remote-hosts:` key-line itself MUST NOT carry an inline comment — see § Parser Gotcha: No-Inline-Comment Block Headers (top of this file). A trailing `# comment` on that exact line means the parser never enters the block and `remote-hosts` silently resolves to `[]`.
+
+```yaml
+remote-hosts:
+  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+    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
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `remote-hosts` | list | `[]` | The declared hosts, in preference order — the gate takes the FIRST host that accepts the role and is witnessed ready. |
+| `alias` | string | — (required) | ssh destination as configured on this host. Must match `^[A-Za-z0-9._-]+$`; it reaches argv as `-H <alias>`. A record missing or failing this is dropped with a stderr WARN. |
+| `roles-allowed` | string[] | `[test, ui, perf]` | The `agent-mapping` roles this host accepts. Entries outside `test` / `ui` / `perf` are filtered with a WARN; a record whose list is empty after filtering is dropped. `impl`, `db`, `security`, `compliance` and `docs` work never leaves the local host. |
+| `repo-path` | string \| null | `null` | Checkout location on the remote host. SAFE-path validated (`^[A-Za-z0-9._~/-]+$`); an unsafe value drops the whole record with a WARN. |
+| `claude-path` | string \| null | `null` | `claude` binary location on the remote host. Same validation as `repo-path`. |
+
+**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.
+
+**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.
+
+Read by: `scripts/lib/config/remote-hosts.mjs` (parser), `scripts/lib/config.mjs` (`ssh:` channel validation), `scripts/lib/wave-resource-gate.mjs` (placement).
+
+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.
+
 ## 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.
@@ -1484,43 +1580,7 @@ SO_DISABLED_HOOKS=enforce-scope,enforce-commands claude ...
 
 Each hook handler imports `shouldRunHook` from `hooks/_lib/profile-gate.mjs` at the top level and calls `process.exit(0)` immediately when gated off. The exit is silent (no stdout, no stderr), so Claude Code sees an allow as if the hook had never run.
 
-## Webhooks (#228)
-
-Opt-in webhook notifications delivered by `scripts/lib/webhook-url.mjs`. The helper centralizes URL resolution so no personal-domain default ever silently fires — callers must supply a URL explicitly.
-
-### Resolution order
-
-For every supported kind the resolver checks sources in this order; the first non-empty string wins:
-
-1. **Environment variable** `SO_WEBHOOK_<KIND>_URL` — uppercase kind, hyphens → underscores  
-   e.g. `SO_WEBHOOK_SLACK_URL`, `SO_WEBHOOK_GITLAB_PIPELINE_STATUS_URL`
-2. **Session Config** `webhooks.<kind>.url`
-3. **Error** — `WebhookConfigError` is thrown. No silent personal-domain fallback.
-
-### Supported kinds
-
-| Kind | Env variable | Config key |
-|------|-------------|------------|
-| `slack` | `SO_WEBHOOK_SLACK_URL` | `webhooks.slack.url` |
-| `discord` | `SO_WEBHOOK_DISCORD_URL` | `webhooks.discord.url` |
-| `generic` | `SO_WEBHOOK_GENERIC_URL` | `webhooks.generic.url` |
-| `gitlab-pipeline-status` | `SO_WEBHOOK_GITLAB_PIPELINE_STATUS_URL` | `webhooks.gitlab-pipeline-status.url` |
-
-### Session Config example
-
-```yaml
-webhooks:
-  slack:
-    url: https://hooks.slack.com/services/REDACTED/REDACTED/REDACTED
-  discord:
-    url: https://discord.com/api/webhooks/REDACTED/REDACTED
-  generic:
-    url: https://example.com/hooks/session-events
-  gitlab-pipeline-status:
-    url: https://gitlab.example.com/hooks/pipeline
-```
-
-### Clank Event Bus (events.mjs / on-stop.mjs)
+## Clank Event Bus (events.mjs / on-stop.mjs)
 
 The internal Clank Event Bus webhook is controlled by two environment variables:
 
@@ -1589,24 +1649,23 @@ Set `express-path.enabled: false` when:
 - `skills/session-plan/SKILL.md` — Express Path Short-Circuit section (1-wave plan emission)
 - GitLab issue `#214` (foundation and codification)
 
-## Autopilot Multi-Story (#431)
-
-Opt-in configuration for `autopilot --multi-story` (`scripts/autopilot-multi.mjs`). Controls how parallel story pipelines are isolated when N stories run concurrently. Projects that do not use `--multi-story` leave this block unset and are unaffected.
+## Autopilot Multi-Story (#431) — removed
 
-All fields live under a top-level `autopilot` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
-
-```yaml
-autopilot:
-  bg-isolation: worktree   # worktree | none (default: worktree)
-```
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `autopilot.bg-isolation` | `worktree` \| `none` | `worktree` | Isolation mode for concurrent story pipelines. `worktree` (default): each story creates its own git worktree — safe for parallel writes, costs disk space and EnterWorktree latency. `none`: no worktrees; sub-sessions spawn directly in the main working tree — faster for monorepos with heavy build state but requires explicit file-scope deconfliction (see below). |
+The `autopilot` block and its single field `autopilot.bg-isolation` are **gone**, not
+deprecated. Their only reader was `scripts/autopilot-multi.mjs`, retired together with <!-- path-check: historical -->
+`commands/autopilot-multi.md` by the 2026-09-06 360°-Audit (§ 5A: 0 telemetry, 0 fleet
+invocations in 90 days, no runtime consumer).
 
-**`bg-isolation: none` hard-error guard:** when `bg-isolation: none` AND `--max-stories > 1`, `autopilot-multi` requires `--deconflict-paths=<glob>` on the CLI to confirm that per-story file ownership is planned. Omitting the flag exits with code 1. This enforces the parallel-session discipline defined in `.claude/rules/parallel-sessions.md` PSA-001/002/003 — two agents editing the same file in the main tree simultaneously will corrupt each other's work.
+Verified 2026-09-06 at `e4674109`:
+`rg -n "bg-isolation|bgIsolation|deconflict-paths" scripts hooks tests` returns nothing;
+`scripts/parse-config.mjs` never parsed an `autopilot` key at all; `scripts/autopilot.mjs`
+has no `--multi-story` mode. Documenting the field as functional would therefore have been
+the exact failure the audit found elsewhere — a key an operator can set and no code can
+read. <!-- path-check: historical -->
 
-**Feature introduced by:** GitLab issue #431 (CC 2.1.143 `worktree.bgIsolation` changelog adoption). Implementation: `scripts/autopilot-multi.mjs` reads `config?.autopilot?.['bg-isolation']` via `scripts/parse-config.mjs`. Documentation: `skills/autopilot/SKILL.md` § Configuration.
+**If your Session Config still carries an `autopilot:` block, delete it.** It is inert: no
+parser reads it, so removing it changes no behaviour. Single-story `/autopilot` is
+unaffected and takes no Session Config block.
 
 ## Wave Reviewers
 

package/docs/session-config-template.md

@@ -57,6 +57,10 @@ special: "any repo-specific instructions"   # freeform — orchestrator reads +
 
 Read by: `skills/session-start/SKILL.md` (Phase 4.5), `skills/session-plan/SKILL.md`, `skills/wave-executor/wave-loop.md`.
 
+**The override key set is open.** `_coerceInteger` (`scripts/lib/config/coercers.mjs`) parses whatever keys stand inside the parentheses, so `agents-per-wave: 6 (deep: 18, ultradeep: 18)` is valid today with no code change — it yields `{"default": 6, "deep": 18, "ultradeep": 18}`.
+
+**`session-profile` is NOT a Session Config key — do not add one here.** The wave-shape profile (`ultradeep`) lives in STATE.md frontmatter, written per session by the `/session ultradeep` argument alias, and is absent by default. `parseSessionConfig()` emits no such key, so writing one into a repo's `## Session Config` block is inert prose — the same trap as `session-type:`. Full contract: [`session-config-reference.md` § Session Profile](./session-config-reference.md). The PRD's `ultradeep.max-*` budget block is deliberately NOT implemented and no key of that name is read anywhere (deferred until measured, HR-105).
+
 ## VCS & Infrastructure
 
 ```yaml
@@ -66,7 +70,7 @@ mirror: github                         # auto-push to mirror after every commit
 cross-repos: [related-repo-1]          # repos under ~/Projects/ to snapshot at session-start
 pencil: path/to/design.pen             # design-code alignment input
 ecosystem-health: true                 # toggle health-endpoint probes
-health-endpoints:
+health-endpoints:                      # nested block form — content-scoped parse, see reference doc (#1174)
   - { name: API, url: https://api.example.com/health }
 issue-limit: 50                        # max issues fetched at session-start
 stale-branch-days: 7                   # branch-age threshold for stale flag
@@ -274,7 +278,7 @@ memory:
 
 Agents invoke via `SO_WAVE_AGENT=1 node scripts/memory-propose.mjs …`. The `SO_WAVE_AGENT=1` env-var is set automatically by the wave-executor boilerplate; direct CLI calls without it exit `3` (`rejected-wrong-context`).
 
-Read by: `scripts/lib/memory-proposals/{schema,store,collector,sink}.mjs`, `scripts/memory-propose.mjs`, `agents/memory-proposal-collector.md`, `hooks/pre-bash-memory-propose-audit.mjs`, `skills/session-end/SKILL.md` Phase 3.6.3.
+Read by: `scripts/lib/memory-proposals/{schema,store,collector,sink}.mjs`, `scripts/memory-propose.mjs`, `docs/memory-proposal-flow.md`, `hooks/pre-bash-memory-propose-audit.mjs`, `skills/session-end/SKILL.md` Phase 3.6.3.
 
 ## Auto-Dream Proposal Filter (#566)
 
@@ -381,6 +385,29 @@ Security: `command` and `review` reject shell metacharacters; records failing va
 
 Read by: `scripts/lib/config/custom-phases.mjs`, `skills/session-end/SKILL.md` Phase 2.5.
 
+## Remote Hosts (#1160)
+
+Opt-in declaration of ssh-reachable hosts that heavy wave roles may be OFFLOADED to instead of shrinking the wave under local resource pressure. Declaring a host does not enable anything by itself: the wave resource gate only routes a wave to a host when the wave role is offloadable AND the coordinator supplies a readiness witness. Absent/empty ⇒ `[]` ⇒ everything runs locally, exactly as before.
+
+```yaml
+remote-hosts:
+  - alias: m5                          # required, SAFE slug ([A-Za-z0-9._-]); reaches argv as `-H <alias>`
+    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)
+```
+
+Field semantics:
+- **`alias`** — the ssh destination as configured on this host. Required; a record without it is dropped with a stderr WARN.
+- **`roles-allowed`** — the `agent-mapping` roles this host accepts. `test`, `ui` and `perf` only — impl, db, security, compliance and docs work never leaves the local host. Unknown entries are filtered with a WARN; a record left with an empty list is dropped.
+- **`repo-path` / `claude-path`** — where the checkout and the `claude` binary live on the remote host, when they differ from the defaults the dispatch adapter assumes.
+
+A declared alias is also what an `agent-mapping` value of the form `<role>: ssh:<alias>` is validated against — naming an undeclared host is a parse error, not a runtime surprise.
+
+The gate never probes the network. Without a readiness witness no host counts as ready and the decision stays local (fail toward local).
+
+Read by: `scripts/lib/config/remote-hosts.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.
@@ -431,11 +458,11 @@ Read by: `scripts/lib/config/reconcile.mjs` (parser), `skills/session-end/SKILL.
 
 ## Discovery-Validator (PSA-006 Enforcement)
 
-Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only (exit 0 always — never blocks an agent) — a blocking hard-gate is reserved for a future iteration. ON by default (flip risk is near-zero; generates real telemetry). Issue #567.
+Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only (exit 0 always — never blocks an agent) — a blocking hard-gate is reserved for a future iteration. OFF by default (opt-in). Issue #567; #690 flip reverted 2026-09-02 after fleet measurement.
 
 ```yaml
 discovery-validator:
-  enabled: true                        # on by default; log+warn-only, exit-0-always — set false to silence
+  enabled: true                        # opt-in; hook is off unless this block sets it
 ```
 
 Read by: `scripts/lib/config/discovery-validator.mjs`, `hooks/post-subagent-discovery-validator.mjs`.
@@ -589,26 +616,6 @@ express-path:
 
 Read by: `skills/session-start/phase-8-5-express-path.md`, `skills/session-plan/SKILL.md` (express-path short-circuit).
 
-## Webhooks
-
-Opt-in webhook notifications. The `scripts/lib/webhook-url.mjs` resolver checks env first (`SO_WEBHOOK_<KIND>_URL`), then this Session Config block. **No personal-domain default** — callers must supply a URL or the resolver throws.
-
-```yaml
-webhooks:
-  slack:
-    url: https://hooks.slack.com/services/REDACTED/REDACTED/REDACTED
-  discord:
-    url: https://discord.com/api/webhooks/REDACTED/REDACTED
-  generic:
-    url: https://example.com/hooks/session-events
-  gitlab-pipeline-status:
-    url: https://gitlab.example.com/hooks/pipeline
-```
-
-Measured: `scripts/lib/webhook-url.mjs` (`resolveWebhookUrl`) is the only reader of this `webhooks:` block, and it currently has **zero callers repo-wide** (`grep -rn "webhook-url" scripts/ hooks/` outside itself and one exemption comment in `check-unwired-features.mjs`) — the block is unreachable at HEAD; follow-up issue pending.
-
-What actually fires a webhook today is a **separate** mechanism: `scripts/lib/events.mjs`'s `emitEvent()` reads `CLANK_EVENT_SECRET` + `CLANK_EVENT_URL` directly from the environment (never from this Session Config block) and, when both are set, fire-and-forget POSTs every emitted event to the internal Clank Event Bus. Every hook that calls `emitEvent()` — which is most of `hooks/` — participates in that path; none of them reads `webhooks:` here.
-
 ## Hook Runtime Profile (env-only, not config)
 
 `SO_HOOK_PROFILE` and `SO_DISABLED_HOOKS` are environment variables, **not Session Config fields**. They control hook execution at runtime without editing `hooks.json`.
@@ -659,7 +666,7 @@ That's enough for `/session feature` → `/go` → `/close` to work end-to-end.
 
 ## Full opt-in baseline (copy-paste)
 
-Everything turned on for a project that wants the full feature surface (vault, docs, drift checks, env-aware sizing, webhooks). Trim to taste:
+Everything turned on for a project that wants the full feature surface (vault, docs, drift checks, env-aware sizing). Trim to taste:
 
 ```yaml
 ## Session Config
@@ -817,6 +824,13 @@ custom-phases:
     mode: hard                          # warn | hard | off (default: warn)
     review: docs/eval/last-run.md       # optional SAFE path read after the command (default: null)
 
+# Remote hosts — ssh-reachable offload targets for heavy roles (#1160)
+remote-hosts:
+  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+    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)
+
 # Evolve extra-sources — opt-in EXTRA /evolve learning sources (#638)
 evolve:
   extra-sources:
@@ -836,7 +850,7 @@ reconcile:
 
 # Discovery-validator — PSA-006 enforcement (#567)
 discovery-validator:
-  enabled: true
+  enabled: true                  # opt-in; hook is off unless this block sets it
 
 # Dialectic-Deriver (#506)
 dialectic:
@@ -939,13 +953,6 @@ config-protection:
   mode: warn               # warn | strict (strict blocks loosening, exit 2)
 allow-config-weakening: false   # per-session bypass (mirrors allow-destructive-ops)
 
-# Webhooks (URLs are required when used — no defaults)
-# webhooks:
-#   slack:
-#     url: https://hooks.slack.com/services/...
-#   gitlab-pipeline-status:
-#     url: https://gitlab.example.com/hooks/pipeline
-
 # Agent mapping
 agent-mapping:
   impl: code-implementer

package/docs/telemetry/telemetry-claims.md

@@ -58,29 +58,30 @@ the measurement recipe — see [Reproduce it yourself](#reproduce-it-yourself).
 
 ---
 
-## In-repo test suite — the "10,000+ tests" badge
+## In-repo test suite — the "15,000+ tests" badge
 
 Distinct from the private-corpus figures above, the README **Tests** badge and the
-"10,000+ vitest tests run on every commit" line count **this repository's own test
+"15,000+ vitest tests run on every commit" line count **this repository's own test
 suite** — a **public, CI-verifiable** number, not a maintainer-reported aggregate.
 
 | Claim | What it counts | How measured | As-of |
 | --- | --- | --- | --- |
-| 10,000+ vitest tests | executed test cases across `tests/**/*.test.mjs` | `npm test` prints the exact runtime total; the static floor is countable without running the suite (below) | 2026-06 |
+| 15,000+ vitest tests | executed test cases across `tests/**/*.test.mjs` | `npm test` prints the exact runtime total; the static floor is countable without running the suite (below) | 2026-09 |
 
 Both numbers reproduce in a fresh checkout:
 
 ```bash
-find tests -name '*.test.mjs' | wc -l                    # test files            -> 475
-grep -rohE '\b(it|test)\(' tests | wc -l                 # static test defs      -> ~9,871
-grep -rohE '\b(it|test|describe)\.each\b' tests | wc -l   # parameterized blocks  -> 93
+find tests -name '*.test.mjs' | wc -l                    # test files            -> 637
+grep -rohE '\b(it|test)\(' tests | wc -l                 # static test defs      -> ~13,361
+grep -rohE '\b(it|test|describe)\.each\b' tests | wc -l   # parameterized blocks  -> 440
 ```
 
-The static `it(` / `test(` count (~9,871 across 475 files) is a **floor**: the 93
+The static `it(` / `test(` count (~13,361 across 637 files) is a **floor**: the 440
 `it.each` / `test.each` parameterized blocks each expand to multiple executed cases
-at runtime, so the **case count vitest reports on `npm test` is 10,000+**. Unlike the
-private-corpus figures above, this one is fully auditable — run `npm test` in this
-checkout and read vitest's summary line.
+at runtime, so the **case count vitest reports on `npm test` is 15,000+** (measured
+15,869/0 on the local Full Gate at HEAD, 2026-09-02). Unlike the private-corpus
+figures above, this one is fully auditable — run `npm test` in this checkout and
+read vitest's summary line.
 
 ## Methodology