session-orchestrator 3.24.0 → 4.0.1

package/docs/scope-collision-guard.md

@@ -41,13 +41,13 @@ The coordinator's **own** planned direct edits belong in `coordinator.json` in t
 
 `wave-scope.json` is written into the WORKING COPY, not into the session — so until #1123 one session's manifest governed every session sharing that checkout. Measured 2026-08-22 (#1082): a Discovery wave's `allowedPaths: []` — which `wave-loop.md` prescribes for *every* Discovery wave — denied every write of an unrelated parallel session, with a deny reason that could only tell it to fix a wave plan it does not own.
 
-Two OPTIONAL manifest fields close that: `session` (the raw `session_id`) and its human-readable twin `semantic_session`. Both come from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`, reads `.orchestrator/session.lock` once) in the same coordinator step that writes the rest of the manifest — `skills/wave-executor/wave-loop.md` § Scope Manifest 1.
+Two OPTIONAL manifest fields close that: `session_id` (the raw harness session id) and its human-readable twin `semantic_session_id` — the same spelling `.orchestrator/session.lock` and `current-session.json` use (renamed from `session` / `semantic_session` in #1153 P2; readers accept the legacy pair until the next minor release, see `MANIFEST_SESSION_KEYS` in `scripts/lib/session-identity/own-session.mjs`). Both come from ONE `attributionForRecord(repoRoot)` call (`scripts/lib/events.mjs`) in the same coordinator step that writes the rest of the manifest — `skills/wave-executor/wave-loop.md` § Scope Manifest 1. Unlike a raw lock read, `attributionForRecord()` reads `.orchestrator/session.lock` and then confirms the lock's raw `session_id` against `readProcessLocalSessionIds()` before returning anything — a mismatch (or no process-local id at all) yields `{}`, never a peer's ids (#1207).
 
 The reader is `hooks/enforce-scope.mjs` **Gate 3b**, between the manifest parse (G3) and the path-guard gate (G4). It resolves identity via `new Set(readProcessLocalSessionIds({ hookInput: input }))` and classifies via `classifyManifestSession(scope, ownIds)`, both from [`scripts/lib/session-identity/own-session.mjs`](../scripts/lib/session-identity/own-session.mjs):
 
 | Manifest state | `classifyManifestSession` verdict | Gate 3b disposition |
 |---|---|---|
-| no `session` / `semantic_session` (legacy, pre-#1123) | `unknown` | ENFORCE — falls through unchanged |
+| no `session_id` / `semantic_session_id` (and no legacy `session` / `semantic_session`; pre-#1123) | `unknown` | ENFORCE — falls through unchanged |
 | an id present and matching one of our own | `own` | ENFORCE — falls through unchanged |
 | ids present, none matching, own identity resolvable | `foreign` | **ALLOW** + one `orchestrator.scope.foreign_session_ignored` event |
 | ids present, own identity unresolvable (empty id set) | `unknown` | ENFORCE |
@@ -56,7 +56,7 @@ Five properties are choices, not omissions — and every one of them points the
 
 - **Only what is PROVABLY foreign is foreign.** `readProcessLocalSessionIds()` returns the ids that are PROCESS-LOCAL — hook input (`session_id`/`sessionId`/`parent_session_id`) and `CLAUDE_CODE_SESSION_ID` — and an EMPTY set when neither yields an id, which can only produce `unknown`. The repo-global `session.lock` is deliberately NOT a tier here (#1194): it is ONE file shared by every session in the checkout, so unioning it let a peer's manifest match a peer-written lock id, classify `own`, and have Gate 7 deny the second session's legitimate writes — the exact lockout G3b exists to end. A better signal REPLACES a worse one (`.claude/rules/host-resources.md` § HR-102). A gate that guessed would turn "cannot tell" into a silent enforcement-off on every harness exporting no session id. Every value is trimmed on the way in, so a whitespace-only env var cannot enter as a phantom id that matches nothing (`.claude/rules/development.md` § env-var whitespace trap).
 - **Union across the process-local tiers, not first-tier-wins.** Both process-local tiers are read and merged; only an id in NEITHER is somebody else's. Gating them against each other made the READER's identity a strict subset of the WRITER's — the manifest's `session` comes from `sessionAttribution()` = the same repo-global lock — and two divergences inside these tiers produce the same silent failure, the OWN manifest read `foreign` and the write gate switched itself off for the whole wave, logging an event indistinguishable from correct behaviour: (a) a nested harness where payload `session_id` ≠ `CLAUDE_CODE_SESSION_ID` (measured in `hooks/pre-bash-issue-budget.mjs` `resolveSessionId`); (b) a sub-agent invocation, whose own id is the subagent's while the manifest names the coordinator. A third divergence — a session that lost the lock race and wrote a PEER's id into its own manifest — is NO longer covered here since #1194 dropped the lock tier; it is the accepted cost in limit 11, and its defense is the writer guard. The merge only ADDS ids the process actually carries, so the security direction is unchanged: a manifest whose id appears in neither tier still classifies `foreign`. Its cost is named in limit 11 below.
-- **The writer verifies the binding names itself.** Because the lock is repo-global, `skills/wave-executor/wave-loop.md` § Scope Manifest 1 requires the coordinator to compare `sessionAttribution()`'s ids against its own session (STATE.md `session`) and to OMIT the `session`/`semantic_session` keys when they diverge — unbound = ENFORCE. The reader's union covers the case anyway; the writer guard keeps the manifest readable as an audit record instead of publishing a foreign name.
+- **The writer's binding check is mechanical, not a prose comparison (#1207).** Because the lock is repo-global, `skills/wave-executor/wave-loop.md` § Scope Manifest 1 calls `attributionForRecord(repoRoot)`, which confirms the lock's raw `session_id` against `readProcessLocalSessionIds()` internally and returns `{}` on any mismatch or absent process-local id — the coordinator writes whatever comes back, with no further comparison to perform. STATE.md is deliberately not part of this check: it is a shared working-copy artefact written by whichever session holds the lock, so under a peer-owned lock STATE.md's `session` field would agree with the lock about the same peer and "confirm" exactly the wrong id. OMIT the `session_id`/`semantic_session_id` keys whenever `attributionForRecord()` returns `{}` — unbound = ENFORCE. The reader's union covers the case anyway; the writer guard keeps the manifest readable as an audit record instead of publishing a foreign name.
 - **Gate 3b runs after the parse, never on the raw bytes.** A corrupt manifest yields `{}`, hence no ids, hence `unknown` — and keeps failing closed. A gate that peeked at the bytes first would let a truncated manifest disarm the guard.
 - **The empty string is a validator ERROR, not a third flavour of absent.** `validateSession()` → `validateOptionalSessionId()` in `scripts/validate-wave-scope.mjs` rejects `"session": ""` with *"an empty id attributes to nothing; omit the key entirely to declare the manifest unbound"*. An empty id satisfies a truthiness check while matching nobody, so every reader would classify the manifest FOREIGN where the writer meant UNBOUND — opposite dispositions, not a cosmetic ambiguity. An ABSENT key only WARNS, because the § 3.3 pre-union skeleton is itself an unbound manifest and so is every manifest written before #1123.
 
@@ -89,7 +89,7 @@ false
 true true
 ```
 
-Both globs match `scripts/lib/x.mjs`, yet the direct comparison says `false`. For `assertFileScopeSubset()` that inexactness is *safe*: its glob branch reduces to verbatim presence plus literal-prefix coverage and therefore **over-approximates coverage**, which at worst accepts a union it could not fully prove. For a **collision** check the sign flips — the same over-approximation becomes a **false negative**, i.e. a missed collision, i.e. the incident. That is why the two exact stages decide first and stage 3 is reached only for pairs neither can settle.
+Both globs match `scripts/lib/x.mjs`, yet the direct comparison says `false`. For `assertFileScopeSubset()` that inexactness is *safe*: its glob branch reduces to verbatim presence plus literal-prefix coverage and therefore **over-approximates coverage**, which at worst accepts a union it could not fully prove. For a **collision** check the sign flips — the same over-approximation becomes a **false negative**, i.e. a missed collision, i.e. the incident. That is why the two exact stages decide first and stage 3 is reached only for pairs neither can settle. <!-- path-check: example -->
 
 ## 4. The hook
 
@@ -174,7 +174,7 @@ Complete list of what this guard does **not** see, or sees only approximately:
 8. **Lock loss reopens the race.** On lock timeout the cycle runs unlocked (row 14) — two dispatches starting together can then read the same ledger state and one record is lost. That is the pre-lock behaviour, chosen over denying on a lock-file problem.
 9. **The session binding is self-declared** (§ 2.3). `session` is a plain field in a file any process in this working copy can write, so writing a foreign id into it turns the write gate off for that manifest. Named rather than hidden: it is the SAME power `enforcement: "off"` already grants in the same file, so Gate 3b adds no new authority — the manifest is the coordinator's own artefact either way.
 10. **Only the WRITE gate is session-bound.** The dispatch ledger of § 4 takes its session component from the harness's own `input.session_id` (`waveKeyOf(projectDir, sessionId, …)`), and reads only `wave` and `role` out of `wave-scope.json` — the `session` field is not consulted there at all. So a peer session's manifest cannot bind this session's writes since #1123, but the two hooks reach that property by different routes, and a change to one does not carry to the other.
-11. **A session that published a peer's id reads its OWN manifest as `foreign` (#1194).** Dropping the lock tier (§ 2.3) moved the cost to the other side of the trade, deliberately: a session that lost the `bootstrapLock()` race got the peer's id from `sessionAttribution()`, and if it writes that id into its own manifest, Gate 3b now classifies the manifest `foreign` and its own write guard stands down. The defense is on the WRITER, not the reader — `skills/wave-executor/wave-loop.md` § Scope Manifest, "Verify the binding names YOU before you write it": compare both ids against your own session and OMIT the keys when they diverge, because unbound = ENFORCE. CEILING (BV-004): on a harness that exports no session env var and puts no `session_id` in the hook payload (Codex CLI, Cursor today) both tiers are empty, so G3b is permanently `unknown` = enforce = pre-#1123 behaviour there. Revisit when Codex/Cursor hook payloads carry a session id.
+11. **A session that published a peer's id reads its OWN manifest as `foreign` (#1194) — the writer's defense is now mechanical (#1207).** Dropping the lock tier (§ 2.3) moved the cost to the other side of the trade: with a raw `sessionAttribution()` read, a session that lost the `bootstrapLock()` race could get the peer's id and write it into its own manifest, and Gate 3b would then classify the manifest `foreign`, standing its own write guard down. Since #1207 the writer calls `attributionForRecord(repoRoot)` instead — `skills/wave-executor/wave-loop.md` § Scope Manifest 1 — which confirms the lock's raw `session_id` against `readProcessLocalSessionIds()` before returning anything and yields `{}` on any mismatch, so the coordinator performs no manual comparison and STATE.md plays no part in it (a shared working-copy artefact written by whichever session holds the lock, not a process-local witness). A filled binding is therefore provably this session's own; unbound (`{}`) = ENFORCE. CEILING (BV-004): on a harness that exports no session env var and puts no `session_id` in the hook payload (Codex CLI, Cursor today) both tiers are empty, so G3b is permanently `unknown` = enforce = pre-#1123 behaviour there. Revisit when Codex/Cursor hook payloads carry a session id.
 
 ## 7. Debugging
 

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:
@@ -281,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)
 
@@ -704,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 |
@@ -844,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`).
 
@@ -1240,7 +1278,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/foreign-dispatch.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`. 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.
 
@@ -1542,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:
 
@@ -1647,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.
-
-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)
-```
+## Autopilot Multi-Story (#431) — removed
 
-| 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
@@ -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)
 
@@ -612,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`.
@@ -682,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
@@ -969,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.md

@@ -39,8 +39,11 @@ projection unit test enforces the drop of any non-whitelisted input field.
 | `arch` | CPU architecture (e.g. `arm64`, `x64`). |
 | `node_major` | Major Node.js version in use. |
 | `ci` | Boolean — whether the run was detected as a CI environment. |
-| `fleet` | Boolean — whether this send came from an operator's own fleet-mode host (`owner.yaml` opt-in), as opposed to an external install. |
-| `session_type` | One of `housekeeping`, `feature`, `deep`, `other`. |
+| `fleet` | Boolean — **DEPRECATED since 2026-09-06, removal 2027-03-06.** Identical in value to `fleet_self_declared` for the whole deprecation generation; kept so the server's existing `fleet` column stays comparable across the rename. |
+| `fleet_self_declared` | Boolean, optional — the client's own claim that this send came from an operator host. **Self-declared, and the name says so on purpose:** the authoritative classification is server-side (see below). Derived from the *resolved consent state* (`enabled-fleet` from an `owner.yaml` opt-in, or `enabled-env` from `SO_TELEMETRY=1`), no longer from a raw `owner.yaml` read. |
+| `session_profile` | Optional — the STATE.md frontmatter `session-profile`, and **whitelisted profile names only** (today exactly `ultradeep`). Anything else — a value your repo invented, a client name, a typo — is **omitted from the ping entirely**: never sent verbatim, and never flattened to `other` either. A SECOND axis beside `session_type`, never a substitute for it: an ultradeep session is `session_type: "deep"` PLUS `session_profile: "ultradeep"`. **Absent when no profile is set or the profile is not on the whitelist** (the key is omitted, never `null`), including on derived pings, which never invent one. The whitelist is enforced twice — client-side before the send, and again server-side, which rejects a record carrying an unlisted profile rather than storing it. |
+| `session_record` | Optional — WHICH source the session facts in this ping came from: `ledger` (a matching `sessions.jsonl` record), `derived` (reconstructed from `events.jsonl`), `absent` (neither). When `absent`, `session_type` is `unknown` and `duration_bucket` is **not a measurement**. |
+| `session_type` | One of `housekeeping`, `feature`, `deep`, `other`, `unknown`. `other` means MEASURED but not one of the three modes; `unknown` means NOT MEASURED. Before 2026-09-06 both collapsed to `other`. |
 | `duration_bucket` | One of `<15m`, `15-60m`, `1-3h`, `>3h` — a coarse bucket, never an exact duration. |
 | `skills[]` | Names of invoked skills, filtered against the shipped plugin roster — any name not in that roster becomes `"other"`. |
 | `commands[]` | Names of invoked slash-commands, same filtering rule as `skills[]`. |
@@ -79,7 +82,12 @@ towards anonymizing rather than towards attributing:
 This list is a hard invariant, not a deferral:
 
 - No repository names, no file paths, no git remotes.
-- No prompts, no session transcripts, no free-form text of any kind.
+- No prompts, no session transcripts, no free-form text of any kind. Every
+  field on the wire is either a number, a boolean, or a value from a closed
+  set this repository ships. The last free-text field, `session_profile`, was
+  closed on 2026-09-06: it now carries whitelisted profile names only, and an
+  unlisted value is dropped before the payload is built (and refused again by
+  the server, so it cannot be stored even if some other client sent it).
 - No command arguments — only whitelisted command/skill *names*, and only
   from the shipped roster (anything else is reduced to `"other"`).
 - No hostnames.
@@ -180,6 +188,38 @@ the offline queue is non-empty or a session has completed since — the latter
 clause is what lets the fallback originate a ping instead of only retrying a
 failed one (#1138).
 
+## The other thing that leaves the host: the update check
+
+Telemetry is not the only outbound request this plugin can make, so the second
+one is documented here rather than somewhere an egress audit would miss it.
+
+On **SessionStart**, `hooks/on-session-start.mjs` calls the plugin-update banner
+(`scripts/lib/plugin-update-banner.mjs`), which asks npm whether a newer release
+exists:
+
+```
+GET https://registry.npmjs.org/session-orchestrator/latest
+```
+
+What it is, precisely:
+
+- **No payload and no identifier.** It is a plain `GET` of a constant, public
+  URL — no body, no query string, no `anon_id`, no headers this plugin adds.
+  npm sees a request for a public package's metadata, as `npm view` would.
+- **At most once per 24 h.** The answer is cached
+  (`plugin-latest.json`, `CACHE_TTL_MS = 24 h`); within the TTL no request is
+  made at all. The request has a short timeout and every failure is silent.
+- **Independent of telemetry consent.** It is not a ping and sends nothing about
+  you — but it is still traffic, so it honours the offline flags below.
+
+**Kill switches** (any one of them, set to anything other than empty / `0` /
+`false`, turns the whole check off — not merely the request; the SessionStart
+record then also omits `plugin_version_latest`):
+
+- `SO_DISABLE_UPDATE_CHECK` — this probe's own switch.
+- `DO_NOT_TRACK` — the standard flag, also honoured by the telemetry path.
+- `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`.
+
 ## Retention
 
 - **Raw records:** kept 24 months, then pruned. The retention window exists
@@ -190,6 +230,99 @@ failed one (#1138).
 - **Anonymous ID rotation:** every 90 days, independent of retention — a
   rotated ID cannot be linked back to the one it replaced.
 
+## When a ping is sent
+
+Two triggers, deliberately independent of each other:
+
+1. **SessionEnd** (`hooks/on-session-end.mjs`) — the mechanical close-time
+   flush.
+2. **SessionStart** (`backfillOnSessionStart` in
+   `scripts/backfill-abandoned-sessions.mjs`) — drains whatever the PREVIOUS
+   session left queued. Since 4.0.0 every queued record is re-projected and
+   `session_profile`-whitelisted at the transport boundary before it is sent,
+   and a batch the server rejects with HTTP 400/422 is EVICTED (breadcrumb
+   `reason: rejected-evicted`) instead of being re-queued forever — a poison
+   record can no longer block every later flush.
+
+Trigger 2 exists because trigger 1 fires only on a REGULAR close, and most
+sessions do not have one: measured 2026-09-06 over 90 fleet days, **429 clean
+closes against 2.016 distinct `session.started` ids = 21,3 %**. Roughly four
+sessions in five never reached the only code path that sends. SessionStart is
+the trigger that survives whatever killed the previous session — the same
+argument the abandoned-session backfill already makes for the ledger.
+
+The start-time flush is bounded (1,5 s POST budget), lazily imported, gated by
+the same consent check, and swallows every error: it can never delay or break a
+session start. A timeout is lossless — the batch lands in the offline queue.
+
+A ping no longer depends on `sessions.jsonl`. When the ledger has no matching
+record, `session_type` and `duration_bucket` are reconstructed from
+`events.jsonl` and the ping is stamped `session_record: "derived"`; when neither
+source has a type, it is `session_type: "unknown"` with `session_record:
+"absent"` — never a measured-looking `other`.
+
+### Sandbox guard
+
+The sender refuses to send when it is not running in a real operator session.
+This is not a nicety: on 2026-09-06 six agent sandboxes ran the SessionEnd hook
+from a repo checkout and sent **six real pings to the production ingest server**,
+minted against the operator's real `anon_id`, because `telemetry/paths.mjs`
+resolves `~/.config/session-orchestrator/` from `homedir()` and does not honour
+`SO_CONFIG_HOME` — faking the source never faked the destination.
+
+A send is refused (no network, no queue write, no anon-ID mint) when **any** of:
+
+- `SO_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK` is set;
+- `SO_CONFIG_HOME` / `XDG_CONFIG_HOME` points somewhere other than the directory
+  the telemetry state is actually read from (unless the caller redirected the
+  state path too — that redirect succeeded, which is the opposite of the leak);
+- `CLAUDE_PROJECT_DIR`, or the cwd, sits under the OS temp directory or `/tmp`.
+
+The guard also **fails closed**: if any of its own probes throws, the send is
+refused with `sandbox:probe-failed` rather than permitted. An environment the
+guard could not classify is treated as one it would have refused; nothing is
+lost, because the next session re-probes from scratch.
+
+If you invoke any telemetry writer by hand, export `SO_TELEMETRY_DISABLED=1`.
+
+## Server-side fleet attribution
+
+The `fleet` flag on the wire is **self-declared and was measurably wrong**.
+Until 2026-09-06 the client derived it as `ownerConfig?.telemetry?.enabled
+=== true` — a statement about a FILE, not about a person. The operator's
+second Mac has consent granted but no `telemetry:` block in `owner.yaml`,
+so it declared itself external: **394 of 490 server records (80,4 %)**
+counted the operator as an external user, and every week's
+`fleet_vs_external` was wrong by that margin.
+
+Two independent repairs, because the client alone cannot close this:
+
+1. **Client-side** — `fleet_self_declared` is derived from the resolved
+   consent state (`enabled-fleet` / `enabled-env`), so a host opted in via
+   `SO_TELEMETRY=1` is no longer mistaken for an external install. The name
+   states the limit: a sandbox, or a host whose `owner.yaml` is unreachable,
+   still declares `false` however honest it is.
+2. **Server-side (authoritative)** — set `SO_INGEST_FLEET_ANON_IDS` on the
+   ingest server to a comma-separated list of the operator's own `anon_id`
+   values. A matching record is **stored** as fleet regardless of what it
+   claims. The allowlist can only PROMOTE, never demote: a host that honestly
+   declares itself fleet stays fleet even if the operator forgot to list it.
+
+```
+SO_INGEST_FLEET_ANON_IDS=a3bb4907-…,c29cac99-…
+```
+
+The record survives verbatim in `raw_json`, including its own `fleet` /
+`fleet_self_declared` claim, so the client's declaration and the server's
+verdict remain separable forever and the disagreement rate stays measurable.
+`fleet_vs_external` in the weekly digest reads the stored column, i.e. the
+server verdict. **The allowlist applies at INSERT time**, so it cannot repair
+rows already written — a `fleet_vs_external` computed over a range that
+predates the change is known-wrong and re-running the digest will not fix it.
+
+Unset by default: with no `SO_INGEST_FLEET_ANON_IDS`, storage takes the
+client's word exactly as it did before.
+
 ## Schema evolution
 
 The schema is **additive-only** within a given `schema_version`: new
@@ -198,6 +331,27 @@ without a version bump. The server accepts both the current and the
 immediately previous `schema_version`, so a slightly-outdated client is
 never hard-broken by a server-side schema update.
 
+Unknown top-level fields are accepted by the server and preserved verbatim
+inside `raw_json`, so an additive field round-trips through a server that
+predates it — which is what makes a *rename* safe: emit both names for one
+generation, then drop the old one.
+
+**In flight now (added 2026-09-06, schema v1, additive):**
+
+| Field | Status | Removal |
+|---|---|---|
+| `fleet_self_declared` | new name for `fleet` | — |
+| `fleet` | deprecated alias, same value | **2027-03-06** |
+| `session_record` | new (`ledger` \| `derived` \| `absent`) | — |
+| `session_profile` | new (STATE.md `session-profile`, whitelisted names only; omitted when unset or unlisted) | — |
+
+Client-side the frozen whitelist is split in two: `USAGE_PING_FIELDS` (the
+REQUIRED v1 contract, which `tests/telemetry/parity.test.mjs` asserts the
+server independently requires field by field) and
+`USAGE_PING_OPTIONAL_FIELDS`. `projectUsagePing` projects the UNION, so the
+data-minimization tripwire still holds — a field must be on a reviewed list
+before it can reach the wire.
+
 ## Relationship to `telemetry-claims.md`
 
 This page describes the **opt-in, client-side usage-telemetry pipeline**