session-orchestrator 3.24.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:
@@ -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**

package/docs/vault-docs-architecture.md

@@ -1,12 +1,19 @@
 # Vault & Docs Architecture — Umbrella Narrative
 
 **Audience:** Plugin contributors (Dev). New contributors who need to understand
-how the four documentation skills, one orchestrator skill, one agent, and two
-discovery probes fit together — what fires when, who owns which file, and how
+how the three documentation skills, one orchestrator skill, one agent, two
+vault-status writers, and two discovery probes fit together — what fires when, who owns which file, and how
 to recover when something breaks.
 
 **Status:** Living document. Tracks Epic #229 (Vault & Docs Orchestration).
 
+**Last verified:** 2026-09-06 at `e4674109`. The vault-file layout below was
+re-measured against the code that writes it — `scripts/lib/vault-status/narrative-mirror.mjs`
+(`resolveNarrativePath`) and `scripts/lib/vault-status/board-writer.mjs` (`resolveBoardPath`) —
+after the pre-#673/#674/#675 layout in this file was found stale by the 2026-09-06
+360°-Audit (`docs/audits/2026-09-06-360-audit/w1/d6-docs-drift.md`). The `daily` skill
+rows are gone with the skill itself (§ 5A of that audit).
+
 ---
 
 ## 1. Purpose
@@ -48,6 +55,8 @@ Data flow within a single `/session feature → /go → /close` cycle:
                                 ↓
 ┌──────────────────────────────────────────────────────────────────┐
 │  session-start                                                   │
+│   Phase 1.7  vault-status board  (opt-in)                        │
+│     └─ this repo → in-progress in _active-sessions.md            │
 │   Phase 2.5  docs-orchestrator (opt-in)                          │
 │     └─ audience detection → docs-tasks block in STATE.md         │
 │        Source: skills/session-start/phase-2-5-docs-planning.md   │
@@ -78,6 +87,8 @@ Data flow within a single `/session feature → /go → /close` cycle:
 │   Phase 2.3  vault-staleness     (opt-in: stale projects)        │
 │   Phase 3.2  docs-verify         (per-task ok/partial/gap)       │
 │   Phase 3.7  vault-mirror        (sessions.jsonl → 50-sessions/) │
+│   Phase 3.7  narrative-mirror    (STATE.md → _session-narrative) │
+│   Phase 3.7c vault board         (this repo's row → closed)      │
 │        Source: skills/session-end/SKILL.md (phase markers)       │
 └──────────────────────────────────────────────────────────────────┘
                                 ↓
@@ -86,7 +97,10 @@ Data flow within a single `/session feature → /go → /close` cycle:
 │   01-projects/<slug>/  ← context.md / decisions.md / people.md   │
 │                          (docs-writer, Vault audience)           │
 │   01-projects/<slug>/  ← _overview.md (vault-mirror, no humans)  │
-│   03-daily/YYYY-MM-DD.md  (daily skill, idempotent)              │
+│   01-projects/<slug>/  ← _session-narrative.md                   │
+│                          (narrative-mirror, session-end 3.7)     │
+│   01-projects/_active-sessions.md                                │
+│                          (board-writer, start 1.7 / end 3.7c)    │
 │   40-learnings/<slug>.md  (vault-mirror, evolve hook)            │
 │   50-sessions/<id>.md     (vault-mirror, session-end Phase 3.7)  │
 └──────────────────────────────────────────────────────────────────┘
@@ -109,7 +123,8 @@ Data flow within a single `/session feature → /go → /close` cycle:
 | `vault-staleness` probes | `skills/discovery/probes-vault.md` + `skills/discovery/probes/vault-staleness.mjs` | `/discovery vault` (on-demand) and session-end Phase 2.3 (opt-in close-time gate) | `VAULT_DIR/01-projects/*/` `_overview.md` + narrative files | JSONL findings under `.orchestrator/metrics/vault-staleness.jsonl` and `vault-narrative-staleness.jsonl` | Vault/Ops (telemetry) |
 | `docs-orchestrator` | `skills/docs-orchestrator/SKILL.md` | session-start Phase 2.5, session-plan Step 1.5/1.8, session-end Phase 3.2 (all gated on `enabled: true`) | Session scope + Session Config audience list | `docs-tasks` block in STATE.md (write side); `### Documentation Coverage` block in final report (verify side) | All three (User / Dev / Vault) |
 | `docs-writer` agent | `agents/docs-writer.md` | Dispatched by `wave-executor` for each `Docs`-classified task | `diff`, `git-log`, `session-memory`, `affected-files` | Audience-targeted Markdown writes (Edit/Write); `[docs-orchestrator] Docs task complete` report line | All three (per task) |
-| `daily` | `skills/daily/SKILL.md` | User-invocable (`/daily`), idempotent | `VAULT_DIR/03-daily/`, `templates/daily.md.tpl` | `<vault>/03-daily/YYYY-MM-DD.md` (created or no-op) | Vault/Ops (PKM anchor) |
+| `narrative-mirror` | `scripts/lib/vault-status/narrative-mirror.mjs` (`mirrorNarrative`) | session-end Phase 3.7, gated on `vault-integration.enabled` | `.claude/STATE.md` narrative sections + the session record | `<vault>/01-projects/<repo-slug>/_session-narrative.md` (generator-marked) | Vault/Ops (durable per-repo narrative) |
+| `board-writer` | `scripts/lib/vault-status/board-writer.mjs` (`sweepBoard` / `mirrorBoard`) | session-start Phase 1.7 (`in-progress`) and session-end Phase 3.7c (`closed`), gated on `vault-integration.enabled` | live session registry + this repo's root | `<vault>/01-projects/_active-sessions.md` — one row per repo (generator-marked, idempotent, never touches `_overview.md`) | Vault/Ops (cross-repo occupancy board) |
 | `vault-mirror` | `skills/vault-mirror/SKILL.md` + `scripts/vault-mirror.mjs` | session-end Phase 3.7 (sessions); evolve Phase 3.5 (learnings) | `.orchestrator/metrics/sessions.jsonl`, `.orchestrator/metrics/learnings.jsonl` | `<vault>/50-sessions/<id>.md`, `<vault>/40-learnings/<slug>.md` (`_generator` marker `session-orchestrator-vault-mirror@1`) | Vault/Ops (telemetry → Markdown) |
 | `vault-backfill` CLI | `scripts/vault-backfill.mjs` | Manual, also surfaced via `/plan retro vault-backfill` sub-mode | `vault-integration.gitlab-groups` config + GitLab API | `.vault.yaml` per repo + Vault stub directories | Vault/Ops (one-shot migration) |
 
@@ -131,6 +146,15 @@ which audience. Never inline this table elsewhere — always cross-link.
   `<vault>/01-projects/<slug>/context.md`, `decisions.md`, `people.md`.
   Source: same.
 
+Those three are the **authored** half of a project folder and are the only vault
+files docs-writer may touch. The other four under `01-projects/` are **generated**
+and carry a `_` prefix plus a generator marker: `_overview.md` (vault-mirror),
+`_session-narrative.md` (narrative-mirror, #675), and — one level up, per vault
+rather than per project — `_active-sessions.md` (board-writer, #674). Editing a
+generated file by hand is not forbidden by a rule; it is simply overwritten on the
+next run. Source: the `resolveNarrativePath` / `resolveBoardPath` path builders in
+`scripts/lib/vault-status/`.
+
 The Session Config field `docs-orchestrator.audiences` accepts any subset of
 `[user, dev, vault]`; narrowing it (e.g., `[user, dev]` on a project without a
 Vault) suppresses Vault-targeted docs without disabling the orchestrator
@@ -169,7 +193,7 @@ silent REVIEW-marker-only output. Source:
 
 ## 6. Non-Overlap Discipline
 
-Three forbidden cross-writes are enforced by the architecture, not just by
+Four forbidden cross-writes are enforced by the architecture, not just by
 convention:
 
 - **`<vault>/01-projects/*/_overview.md` is owned by `vault-mirror`.** The
@@ -179,11 +203,24 @@ convention:
   `skills/docs-orchestrator/audience-mapping.md` § Non-Overlap (vault-mirror
   row) and `skills/vault-mirror/SKILL.md` § Idempotency (the `_generator`
   marker `session-orchestrator-vault-mirror@1` is the discriminator).
-- **`<vault>/03-daily/YYYY-MM-DD.md` is owned by `daily`.** Idempotent by
-  design — re-running `/daily` opens the existing note, never overwrites.
-  Source: `skills/daily/SKILL.md` § Idempotency Guarantee. A second writer
-  would corrupt the day's scratch notes. Source:
-  `skills/docs-orchestrator/audience-mapping.md` § Non-Overlap (daily row).
+- **`<vault>/01-projects/_active-sessions.md` and
+  `<vault>/01-projects/<slug>/_session-narrative.md` are owned by the two
+  vault-status writers.** Both are generator-marked and rewritten wholesale on
+  the next session-start / session-end, so a hand edit is silently lost rather
+  than merged. `board-writer` additionally holds a cross-repo mutex at
+  `<vault>/.orchestrator/board.lock` while writing
+  (`scripts/lib/vault-status/board-lock.mjs`, #1180 — deliberately not beside
+  the board) because the board is the one vault file several repos write
+  concurrently.
+- **`<vault>/03-daily/*` remains a forbidden path for `docs-writer`, but no
+  plugin component writes it any more.** The `daily` skill was retired on
+  2026-09-06 (360°-Audit § 5A) and `templates/daily.md.tpl` is gone with it;
+  measured the same day, `03-daily/` survives in code only inside
+  `scripts/lib/frontmatter-guard.mjs`'s vault-subdirectory *detector*, which
+  reads paths and writes none. The forbidden-path entries in
+  `skills/docs-orchestrator/audience-mapping.md` § Non-Overlap and
+  `agents/docs-writer.md` still name `daily` as the owner; that is stale
+  attribution for a path the operator's own PKM now owns, not a live contract.
 - **`CLAUDE.md` may be remediated by `docs-writer` (Dev audience), but
   `claude-md-drift-check` only diagnoses it.** The two skills must not run
   on `CLAUDE.md` in parallel within the same wave. Source:
@@ -201,6 +238,7 @@ Concrete answer to "when does each component fire":
 
 | Phase | Skill / Probe | Gating |
 |-------|---------------|--------|
+| `/session` start, Phase 1.7 | `board-writer` marks this repo `in-progress` on `_active-sessions.md` | `vault-integration.enabled: true` |
 | `/session` start, Phase 2.5 | `docs-orchestrator` audience detection | `docs-orchestrator.enabled: true` |
 | `/session` start, Phase 4.5 | resource-health probe | always (env-aware) |
 | session-plan Step 1.5/1.8 | `docs-writer` registered + Docs role classified | `docs-orchestrator.enabled: true` |
@@ -210,9 +248,10 @@ Concrete answer to "when does each component fire":
 | `/close` Phase 2.3 | `vault-staleness` + `vault-narrative-staleness` probes | `vault-staleness.enabled: true` |
 | `/close` Phase 3.2 | `docs-orchestrator` verification | `docs-orchestrator.enabled: true` AND `docs-tasks` block present |
 | `/close` Phase 3.7 | `vault-mirror` (sessions) | `vault-integration.enabled: true` AND `mode != off` |
+| `/close` Phase 3.7 | `narrative-mirror` → `_session-narrative.md` | `vault-integration.enabled: true`; `mode: strict` blocks the close on failure, otherwise WARN |
+| `/close` Phase 3.7c | `board-writer` transitions this repo's row to `closed` | `vault-integration.enabled: true`; non-blocking |
 | evolve Phase 3.5 | `vault-mirror` (learnings) | same as above |
 | `/discovery vault` | `vault-staleness` probes (on-demand) | `.vault.yaml` present OR `vault-integration.enabled: true` |
-| `/daily` | `daily` skill | user-invocable; no Session Config gate |
 
 Sources: `skills/session-end/SKILL.md` (Phase markers), `docs/session-config-reference.md`
 (per-skill enabled-flag semantics), `skills/discovery/probes-vault.md` (probe