session-orchestrator 3.23.0 → 4.0.0

package/docs/telemetry.md

@@ -39,18 +39,55 @@ 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[]` | Same filtering rule as `skills[]`. |
+| `commands[]` | Names of invoked slash-commands, same filtering rule as `skills[]`. |
+
+### How a name lands in `skills[]` or `commands[]`
+
+Both buckets are fed from one local ledger of invocations
+(`.orchestrator/metrics/skill-invocations.jsonl`), so a single classification
+rule decides which bucket a name reaches — and it is deliberately biased
+towards anonymizing rather than towards attributing:
+
+- Shipped **skills** are recorded plugin-prefixed
+  (`session-orchestrator:session-end`); shipped **commands** are recorded bare
+  (`session`). The Skill tool surfaces a slash-command that has no backing
+  `skills/` directory under the *prefixed* form too, so a prefixed name whose
+  bare form is a shipped command is reported in `commands[]` under that bare
+  name.
+- A name is only ever reported as one of our commands when it carries the
+  plugin prefix. A **bare** name is never credited to a command, even when it
+  collides with one of our command names — a third-party or personal skill
+  invoked bare as `test` would otherwise be reported as our `/test` command.
+  Bare unknown names take the skills path and are reduced to `"other"`. The one
+  exception is a name arriving in the ledger's `.command` **field**: that field
+  is itself the "this is one of ours" provenance signal a bare `.skill` arrival
+  lacks, so `buildUsagePing` prefixes every `.command` value before
+  classification (`scripts/lib/telemetry/schema.mjs`). Without that step the
+  `.command` producer would be wired but dead — every record it writes would
+  silently become `"other"`.
+- On a spelling collision (`memory-cleanup` exists as both a skill and a
+  command) the skill roster wins, so exactly one bucket is credited. Counting
+  distinct surfaces across `skills[]` and `commands[]` therefore never
+  double-counts a single one.
 
 ## What we never collect
 
 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.
@@ -151,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
@@ -161,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
@@ -169,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

package/hooks/_lib/atomic-json.mjs

@@ -0,0 +1,111 @@
+/**
+ * atomic-json.mjs — shared atomic read-modify-write helper for JSON hook state.
+ *
+ * Extracted (issue #1197) from four byte-identical private copies of
+ * `atomicMutateJson` that had accumulated independently in
+ * `hooks/cwd-change-restore.mjs`, `hooks/on-session-end.mjs`,
+ * `hooks/post-tool-batch-wave-signal.mjs`, and
+ * `hooks/post-tool-failure-corrective-context.mjs` (measured 2026-09-02 @
+ * a019d5a4 via `rg -n "function atomicMutateJson" hooks/` — 4 hits, one per
+ * file, logic byte-identical modulo the per-file tmp-suffix and the
+ * `fs.`-namespace-vs-named-import style `on-session-end.mjs` uses).
+ *
+ * F-H fix (W3-reviewer finding, #1197): the pre-extraction copies treated
+ * EVERY read/parse failure as "file absent" and silently fell back to
+ * `defaultValue` — so an unparsable file, `EISDIR`, `EACCES`, or a file
+ * truncated mid-write by a concurrent writer was overwritten with
+ * `defaultValue`-derived content instead of being left alone. Only `ENOENT`
+ * (file genuinely does not exist yet) is a legitimate "start fresh" case;
+ * every other failure now aborts BEFORE the tmp-write/rename stage and
+ * reports `{ ok: false, reason }` — the original file is never touched.
+ *
+ * Return-object over throw (deliberate — see #1197 task note): all four
+ * callers already run under `main().catch(() => {}).finally(() =>
+ * process.exit(0))` — informational, never-deny hooks (verified 2026-09-02:
+ * none of the four match a deny/block pattern) — so a thrown error would be
+ * swallowed safely too. But in `post-tool-batch-wave-signal.mjs` a throw at
+ * the FIRST call site (line ~278, the `last_batch` write) would abort
+ * `main()` before it reaches the independent heartbeat-refresh block that
+ * follows — a real behavioural loss the thrown-error path would introduce
+ * silently. A result object lets every caller decide locally whether an RMW
+ * failure should short-circuit the rest of `main()` or just get logged and
+ * ignored, so no caller loses unrelated post-call behaviour by construction.
+ *
+ * NAMED CEILING (BV-004): tmp-file + rename makes each individual write
+ * atomic, but not the full read-modify-write — two concurrent callers can
+ * still interleave (both read the same `current`, both compute an update
+ * from it, the second rename wins and silently drops the first mutation).
+ * This module does not defend against that race. Revisit with a per-file
+ * lock (e.g. an flock-style sidecar or `session-lock.mjs`'s lease pattern)
+ * if `.orchestrator/current-session.json` writes start dropping fields
+ * under concurrent-session load — no such loss has been measured yet.
+ *
+ * @module hooks/_lib/atomic-json
+ */
+
+import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Atomic read-modify-write of a JSON file via temp-file + rename.
+ *
+ * Reads the existing file and parses it as JSON. When the file does not
+ * exist (`ENOENT`), starts from `defaultValue` — the only case in which
+ * "file absent" is legitimate. Any OTHER read or parse failure (directory
+ * at `filePath`, permission denied, truncated/corrupt JSON, …) aborts
+ * WITHOUT calling `mutate` and WITHOUT writing anything — the original file
+ * (if any) is left exactly as it was.
+ *
+ * On success, applies the synchronous `mutate` transformer, writes the
+ * result to a `${filePath}.tmp-<suffix>-<pid>-<ts>` sibling, then renames it
+ * over `filePath` (atomic on POSIX same-filesystem rename; best-effort on
+ * Windows). If the write/rename stage itself fails, the tmp file is
+ * best-effort unlinked so a failure never leaves an orphaned `.tmp-*`
+ * artifact behind.
+ *
+ * @param {string} filePath — absolute path to the JSON file.
+ * @param {object} defaultValue — starting value used ONLY when the file does
+ *   not exist yet (`ENOENT`). Never applied on top of an unreadable-but-
+ *   present file.
+ * @param {function(object): object} mutate — pure synchronous transformer;
+ *   receives the parsed current value (or `defaultValue`), returns the next
+ *   value to persist.
+ * @param {string} [tmpTag] — short tag folded into the tmp filename so
+ *   concurrent callers targeting the same `filePath` from different hooks
+ *   don't collide on the same tmp path (mirrors the per-caller suffixes the
+ *   four pre-extraction copies used: `-cwd-`, `-ose-`, `-ptb-`, `-ptf-`).
+ * @returns {Promise<{ ok: true, value: object } | { ok: false, reason: string }>}
+ */
+export async function atomicMutateJson(filePath, defaultValue, mutate, tmpTag = 'ajs') {
+  let current = defaultValue;
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    current = JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      // File genuinely does not exist yet — the only legitimate "fresh
+      // file" case. `current` already holds `defaultValue`.
+    } else {
+      // EISDIR, EACCES, a JSON.parse SyntaxError (unparsable/truncated
+      // content), or anything else — never silently treat as "absent".
+      // Abort before mutate/write; the original file is untouched.
+      return { ok: false, reason: (err && err.code) || 'parse-error' };
+    }
+  }
+
+  const updated = mutate(current);
+  const tmp = `${filePath}.tmp-${tmpTag}-${process.pid}-${Date.now()}`;
+  try {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(tmp, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+    await rename(tmp, filePath);
+  } catch (err) {
+    try {
+      await unlink(tmp);
+    } catch {
+      // tmp was never created, or is already gone — nothing to clean up.
+    }
+    return { ok: false, reason: (err && err.code) || 'write-error' };
+  }
+  return { ok: true, value: updated };
+}