session-orchestrator 3.23.0 → 3.24.0

package/docs/session-config-reference.md

@@ -98,7 +98,7 @@ agent-mapping: { impl: cursor:composer-2.5, test: cursor:cursor-grok-4.6-high, s
 
 **Where the rest of the contract lives** — deliberately not here, so one place owns it:
 
-- **Model selection** (which model for which role, and why): the account-switch routing SSOT, ADR-002 / `tools/routing/routing.yaml`. Working defaults are `composer-2.5` for foreign impl and `cursor-grok-4.6-high` for review / test-writing / judgment roles.
+- **Model selection** (which model for which role, and why): the operator's model-routing SSOT (ADR-002). Working defaults are `composer-2.5` for foreign impl and `cursor-grok-4.6-high` for review / test-writing / judgment roles.
 - **Dispatch contract** (detached worktree, the `never_foreign` role lock, the filesystem-measured verdict, the MANDATORY Claude semantic diff-review before merge-back, wall-clock timeout instead of `maxTurns`, and the `orchestrator.foreign_dispatch.completed` event that replaces the hook-chain telemetry a foreign run cannot emit): `skills/wave-executor/wave-loop.md` § Third branch: foreign-model dispatch.
 
 ## VCS & Infrastructure
@@ -111,8 +111,34 @@ agent-mapping: { impl: cursor:composer-2.5, test: cursor:cursor-grok-4.6-high, s
 | `cross-repos` | list | none | Related repositories under `~/Projects/`. The orchestrator checks their git state and critical issues during session start. |
 | `cross-repo.projects` | list | `[]` | Repos to process when running cross-repo maintenance scripts (`run-migrate-v2-cross-repo.mjs`, `vault-integration-watcher.mjs`, `promote-vault-strict.mjs`). Each entry is a path (absolute, `~`-prefixed, or bare name resolved under `~/Projects/`). When this list is empty or absent, those scripts emit a one-line notice and exit 0 — they never error on an empty list. Example: `[~/Projects/my-app, ~/Projects/another-app]`. |
 | `pencil` | string | none | Path to a `.pen` design file (relative to project root). Enables design-code alignment reviews after Impl-Core and Impl-Polish waves. |
-| `ecosystem-health` | boolean | `false` | Enable service health checks at session start. Requires `health-endpoints` to be configured. |
-| `health-endpoints` | list | none | Service URLs to check health. Each entry is an object with `name` and `url` fields. |
+| `ecosystem-health` | boolean | `false` | Enable service health checks at session start. Requires `health-endpoints` to be configured. Accepts the SCALAR form (`ecosystem-health: true`) read off the flat key/value map, or a BLOCK form (`ecosystem-health:` with no value, followed by an indented body — the wizard's output) read via `_parseEcosystemHealthBlockEnabled()`; the scalar wins when both are present (#1174). |
+| `health-endpoints` | list | none | Service URLs to check health. Each entry is an object with `name` and `url` fields. Parsed by `scripts/lib/config/health-endpoints.mjs`, which accepts THREE forms (#1174) — see below. |
+
+**`health-endpoints` accepted forms.** Before #1174 the parser read this key off the flat KV map,
+which bails to `null` the instant a value contains `{` and cannot see a nested YAML block at all;
+the wizard's own output (Form B) silently failed to parse. All three forms below are parsed
+content-scoped, independent of the flat KV map:
+
+```yaml
+# Form A — inline object array
+health-endpoints: [{name: "API", url: "https://a/health"}, {name: "W", url: "http://w:8080/z"}]
+
+# Form B — nested block (top-level, or one level under `ecosystem-health:`); the wizard's output.
+# Block items may also be inline objects, `- { name: API, url: … }` (the form this file's own
+# example above uses).
+health-endpoints:
+  - name: API
+    url: https://api.example.com/health
+
+# Form C — bare bracket list of URLs; each URL becomes its own name ({ name: <url>, url: <url> })
+health-endpoints: [https://a/health, https://b/health]
+```
+
+The `name=url` shorthand (Form D) is **not** supported — an entry containing `=` is treated
+verbatim as a Form-C URL, never split on `=`. A malformed entry (missing `name` or `url`, an
+unmatched brace) resolves to `null` for the whole key and prints exactly one
+`config: health-endpoints:` WARN to stderr — it never throws, so a broken config key cannot take
+down session-start.
 | `issue-limit` | integer | `50` | Maximum issues to fetch when querying VCS during session start. |
 | `stale-branch-days` | integer | `7` | Days of inactivity before a branch is flagged as stale. |
 | `stale-issue-days` | integer | `30` | Days without progress before an issue is flagged for triage. |
@@ -385,18 +411,18 @@ state-md-lock:
 
 ## Discovery-Validator (PSA-006 Enforcement, #567)
 
-Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") appearing in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only — exit 0 always, never blocks the agent; a blocking hard-gate is reserved for a future iteration. Default ON (flip risk is near-zero; the hook only ever generates telemetry).
+Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") appearing in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only — exit 0 always, never blocks the agent; a blocking hard-gate is reserved for a future iteration. Default OFF (opt-in) — the #690 flip to ON was reverted 2026-09-02 (#1191) after fleet measurement showed 6,946 violation events accumulating in 18 repos that never declared the block.
 
 All fields live under a top-level `discovery-validator` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
 
 ```yaml
 discovery-validator:
-  enabled: true                        # on by default; log+warn-only, exit-0-always — set false to silence
+  enabled: true                        # off by default; opt in per repo — log+warn-only, exit-0-always
 ```
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `discovery-validator.enabled` | boolean | `true` | Master toggle. When `false`, the `SubagentStop` hook is bypassed entirely — no transcript scanning, no `discovery_validator_violation` events. Note: when the `discovery-validator:` block is present but omits the `enabled:` line, the parser conservatively resolves to `false` (only a literal `true` flips it) — the `true` default applies when the block is absent entirely. Always set `enabled` explicitly when adding this block. |
+| `discovery-validator.enabled` | boolean | `false` | Master toggle. When `false` (or when the block is absent), the `SubagentStop` hook is bypassed entirely — no transcript scanning, no `discovery_validator_violation` events. Note: when the `discovery-validator:` block is present but omits the `enabled:` line, the parser conservatively resolves to `false` — only a literal `true` enables the hook. Always set `enabled` explicitly when adding this block. |
 
 **Used by:** `hooks/post-subagent-discovery-validator.mjs`, `scripts/lib/config/discovery-validator.mjs` (`_parseDiscoveryValidator`). See `.claude/rules/parallel-sessions.md` § PSA-006.
 
@@ -1190,6 +1216,38 @@ Read by: `scripts/lib/config/custom-phases.mjs` (parser), `skills/session-end/SK
 - `archive-closed-prds` (#782, Epic #774) — `node scripts/archive-closed-prds.mjs --apply` — archives `docs/prd/` PRDs (defaults).
 - `archive-closed-plans` (#786) — `… --apply --prd-dir docs/plans --vault-subdir 01-projects/session-orchestrator/plans` — archives `docs/plans/` executable-plan artefacts of closed features/Epics. The plan's tracking `#NNN` (inline in the plan's `Source:` header, see `skills/write-executable-plan/`) is the anchor this phase reads; a plan with no `#NNN` is never archived (fail-closed `no-epic-ref`).
 
+## Remote Hosts (#1160)
+
+Opt-in declaration of ssh-reachable hosts a heavy wave role may be OFFLOADED to instead of shrinking the wave under local resource pressure. This key only DECLARES: it never probes a host, never dispatches, and never changes a wave by itself. Absent/empty ⇒ `[]` ⇒ every wave stays local, exactly as before.
+
+**Parser gotcha:** like every other block-shaped Session Config key, the `remote-hosts:` key-line itself MUST NOT carry an inline comment — see § Parser Gotcha: No-Inline-Comment Block Headers (top of this file). A trailing `# comment` on that exact line means the parser never enters the block and `remote-hosts` silently resolves to `[]`.
+
+```yaml
+remote-hosts:
+  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+    roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
+    repo-path: ~/Projects/Alice     # optional; SAFE path; default null
+    claude-path: ~/.local/bin/claude   # optional; SAFE path; default null
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `remote-hosts` | list | `[]` | The declared hosts, in preference order — the gate takes the FIRST host that accepts the role and is witnessed ready. |
+| `alias` | string | — (required) | ssh destination as configured on this host. Must match `^[A-Za-z0-9._-]+$`; it reaches argv as `-H <alias>`. A record missing or failing this is dropped with a stderr WARN. |
+| `roles-allowed` | string[] | `[test, ui, perf]` | The `agent-mapping` roles this host accepts. Entries outside `test` / `ui` / `perf` are filtered with a WARN; a record whose list is empty after filtering is dropped. `impl`, `db`, `security`, `compliance` and `docs` work never leaves the local host. |
+| `repo-path` | string \| null | `null` | Checkout location on the remote host. SAFE-path validated (`^[A-Za-z0-9._~/-]+$`); an unsafe value drops the whole record with a WARN. |
+| `claude-path` | string \| null | `null` | `claude` binary location on the remote host. Same validation as `repo-path`. |
+
+**Two enums, never conflated.** `roles-allowed` holds `agent-mapping` roles (`test`, `ui`, `perf`) — NOT wave roles (`Impl-Core`, `Quality`, …). The wave→role translation is `OFFLOADABLE_WAVE_ROLES` in `scripts/lib/wave-resource-gate.mjs`; a wave role absent from that map is local-only by default.
+
+**Placement contract.** The gate applies its offload arm only after the HR-004 heavy-repo cap, and only when the resource verdict was `reduce` or `coordinator-direct`. It does NOT probe the network: the coordinator supplies a readiness witness (`remoteReady: { m5: true }`, or an async `probeFn`). With no witness, no host counts as ready and the decision stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/foreign-dispatch.mjs`) is never offloaded regardless.
+
+**agent-mapping interaction.** A declared alias is what an `agent-mapping` value of the form `<role>: ssh:<alias>` validates against; naming an undeclared host throws at parse time, naming the `ssh` channel with no target throws as for any other channel.
+
+Read by: `scripts/lib/config/remote-hosts.mjs` (parser), `scripts/lib/config.mjs` (`ssh:` channel validation), `scripts/lib/wave-resource-gate.mjs` (placement).
+
+See `skills/remote-offload/SKILL.md` for the wave-executor-side decision rule, the three offload channels, and how a declared alias here is what an `agent-mapping` `ssh:<alias>` value validates against.
+
 ## Evolve Extra Sources (#638)
 
 Opt-in EXTRA learning sources for `/evolve`. A domain measurement (e.g. an eval-learn regression harness) runs OUT-OF-BAND and writes a sidecar JSON of regression flags; `/evolve` then READS each declared sidecar and emits a `domain-regression` learning candidate per flag that has persisted across ≥2 consecutive sessions. This is a strict **read-only consumption contract**: `/evolve` never runs the domain measurement — it only consumes the sidecar output. Absent/empty ⇒ `[]` ⇒ no extra sources are read; existing `/evolve` runs are unaffected.

package/docs/session-config-template.md

@@ -66,7 +66,7 @@ mirror: github                         # auto-push to mirror after every commit
 cross-repos: [related-repo-1]          # repos under ~/Projects/ to snapshot at session-start
 pencil: path/to/design.pen             # design-code alignment input
 ecosystem-health: true                 # toggle health-endpoint probes
-health-endpoints:
+health-endpoints:                      # nested block form — content-scoped parse, see reference doc (#1174)
   - { name: API, url: https://api.example.com/health }
 issue-limit: 50                        # max issues fetched at session-start
 stale-branch-days: 7                   # branch-age threshold for stale flag
@@ -381,6 +381,29 @@ Security: `command` and `review` reject shell metacharacters; records failing va
 
 Read by: `scripts/lib/config/custom-phases.mjs`, `skills/session-end/SKILL.md` Phase 2.5.
 
+## Remote Hosts (#1160)
+
+Opt-in declaration of ssh-reachable hosts that heavy wave roles may be OFFLOADED to instead of shrinking the wave under local resource pressure. Declaring a host does not enable anything by itself: the wave resource gate only routes a wave to a host when the wave role is offloadable AND the coordinator supplies a readiness witness. Absent/empty ⇒ `[]` ⇒ everything runs locally, exactly as before.
+
+```yaml
+remote-hosts:
+  - alias: m5                          # required, SAFE slug ([A-Za-z0-9._-]); reaches argv as `-H <alias>`
+    roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
+    repo-path: ~/Projects/Alice     # optional SAFE path (default: null)
+    claude-path: ~/.local/bin/claude   # optional SAFE path (default: null)
+```
+
+Field semantics:
+- **`alias`** — the ssh destination as configured on this host. Required; a record without it is dropped with a stderr WARN.
+- **`roles-allowed`** — the `agent-mapping` roles this host accepts. `test`, `ui` and `perf` only — impl, db, security, compliance and docs work never leaves the local host. Unknown entries are filtered with a WARN; a record left with an empty list is dropped.
+- **`repo-path` / `claude-path`** — where the checkout and the `claude` binary live on the remote host, when they differ from the defaults the dispatch adapter assumes.
+
+A declared alias is also what an `agent-mapping` value of the form `<role>: ssh:<alias>` is validated against — naming an undeclared host is a parse error, not a runtime surprise.
+
+The gate never probes the network. Without a readiness witness no host counts as ready and the decision stays local (fail toward local).
+
+Read by: `scripts/lib/config/remote-hosts.mjs`, `scripts/lib/wave-resource-gate.mjs`.
+
 ## Evolve Extra Sources (#638)
 
 Opt-in EXTRA learning sources for `/evolve`. A `domain-regression` measurement (e.g. an eval-learn harness) runs OUT-OF-BAND and writes a sidecar JSON; `/evolve` then READS each declared sidecar and emits a `domain-regression` learning candidate per persistent regression flag. `/evolve` NEVER runs the measurement itself — this is a strict read-only consumption contract. Absent/empty ⇒ `[]` ⇒ no extra sources are read.
@@ -431,11 +454,11 @@ Read by: `scripts/lib/config/reconcile.mjs` (parser), `skills/session-end/SKILL.
 
 ## Discovery-Validator (PSA-006 Enforcement)
 
-Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only (exit 0 always — never blocks an agent) — a blocking hard-gate is reserved for a future iteration. ON by default (flip risk is near-zero; generates real telemetry). Issue #567.
+Non-blocking `SubagentStop` hook that mechanically enforces PSA-006: distributional claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of") in a subagent's transcript tail must carry an adjacent fenced grep/rg/find transcript. When a claim lacks one, the hook records a `discovery_validator_violation` event in `.orchestrator/metrics/events.jsonl` and emits a stderr WARN. v1 is log + warn only (exit 0 always — never blocks an agent) — a blocking hard-gate is reserved for a future iteration. OFF by default (opt-in). Issue #567; #690 flip reverted 2026-09-02 after fleet measurement.
 
 ```yaml
 discovery-validator:
-  enabled: true                        # on by default; log+warn-only, exit-0-always — set false to silence
+  enabled: true                        # opt-in; hook is off unless this block sets it
 ```
 
 Read by: `scripts/lib/config/discovery-validator.mjs`, `hooks/post-subagent-discovery-validator.mjs`.
@@ -817,6 +840,13 @@ custom-phases:
     mode: hard                          # warn | hard | off (default: warn)
     review: docs/eval/last-run.md       # optional SAFE path read after the command (default: null)
 
+# Remote hosts — ssh-reachable offload targets for heavy roles (#1160)
+remote-hosts:
+  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+    roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
+    repo-path: ~/Projects/Alice     # optional SAFE path (default: null)
+    claude-path: ~/.local/bin/claude   # optional SAFE path (default: null)
+
 # Evolve extra-sources — opt-in EXTRA /evolve learning sources (#638)
 evolve:
   extra-sources:
@@ -836,7 +866,7 @@ reconcile:
 
 # Discovery-validator — PSA-006 enforcement (#567)
 discovery-validator:
-  enabled: true
+  enabled: true                  # opt-in; hook is off unless this block sets it
 
 # Dialectic-Deriver (#506)
 dialectic:

package/docs/telemetry/telemetry-claims.md

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

package/docs/telemetry.md

@@ -43,7 +43,36 @@ projection unit test enforces the drop of any non-whitelisted input field.
 | `session_type` | One of `housekeeping`, `feature`, `deep`, `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
 

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 };
+}

package/hooks/_lib/subagent-paths.mjs

@@ -0,0 +1,143 @@
+/**
+ * subagent-paths.mjs — consolidated subagent sidecar-path derivation (#1196).
+ *
+ * Four call sites independently derived the SAME shape — the stopping
+ * subagent's own `agent-<id>.jsonl` transcript + `agent-<id>.meta.json`
+ * sidecar, from the PARENT transcript path the harness sends on stdin — and
+ * diverged on strictness. Measured 2026-09-02 @ a019d5a4 (this consolidation):
+ *
+ * | copy (file:line)                                          | honours `agent_transcript_path` | id bound        | rejects `'unknown'` | containment check |
+ * |------------------------------------------------------------|:---:|:---:|:---:|:---:|
+ * | hooks/subagent-telemetry.mjs:513 `resolveSubagentTranscriptPath` | no  | unbounded (`+`) | yes (:517) | n/a (no override) |
+ * | hooks/on-stop.mjs:666 `resolveSidecarBase`                       | no  | `{1,64}` (:566) | **no** | n/a (no override) |
+ * | hooks/post-subagent-discovery-validator.mjs:538 `resolveAgentTranscriptPath` | yes (:539) | `{1,64}` (:547) | yes (:549) | **no** — `explicit` returned unchecked (:539) |
+ * | scripts/lib/wave-transcript-tail.mjs:610 `readAgentType`         | no  | **none** | no | n/a (no override) |
+ *
+ * `resolveSubagentSidecar()` below applies the STRICTEST rule found in ANY
+ * copy to every caller: the `{1,64}` bound, the `'unknown'` rejection (closes
+ * the on-stop.mjs / wave-transcript-tail.mjs gap), AND a path-containment
+ * check on the `agentTranscriptPath` override that NONE of the four copies
+ * performed — post-subagent-discovery-validator.mjs returned the harness
+ * override completely unvalidated. That containment check is a NEW rule this
+ * consolidation introduces, not a preserved behaviour.
+ *
+ * @module hooks/_lib/subagent-paths
+ */
+
+import path from 'node:path';
+
+/**
+ * Real agent ids are hex-ish tokens (e.g. `a60348a01ca982b4c`); anything else
+ * is rejected, not sanitised, so no payload value can traverse out of the
+ * `subagents/` directory. `{1,64}` is the strictest bound found across the
+ * four prior copies (hooks/subagent-telemetry.mjs used an unbounded `+`;
+ * scripts/lib/wave-transcript-tail.mjs applied no charset check at all).
+ */
+export const AGENT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * Validate a candidate agent id against the strictest rule of the four prior
+ * copies: the `{1,64}` charset+length bound, AND explicit rejection of the
+ * literal `'unknown'` — the no-usable-id fallback value that several callers
+ * (`firstNonEmptyString(..., 'unknown')`) substitute when the harness sends no
+ * id at all. `'unknown'` matches `AGENT_ID_RE` (it's plain lowercase letters),
+ * so a charset check alone does not catch it — hooks/on-stop.mjs's
+ * `resolveSidecarBase()` had exactly this gap (AGENT_ID_RE-only, no explicit
+ * `'unknown'` rejection) before this consolidation.
+ *
+ * @param {unknown} agentId
+ * @returns {agentId is string}
+ */
+export function isValidAgentId(agentId) {
+  return typeof agentId === 'string' && AGENT_ID_RE.test(agentId) && agentId !== 'unknown';
+}
+
+/**
+ * Resolve the sidecar pair (`.jsonl` transcript + `.meta.json`) for a stopping
+ * subagent (#949, #1190, #1191, #1196).
+ *
+ * Two paths to the same result:
+ *  - **Override.** `agentTranscriptPath` (the harness's `agent_transcript_path`,
+ *    honoured today only by hooks/post-subagent-discovery-validator.mjs:539)
+ *    wins when present — but ONLY when, after `path.resolve`, it sits inside
+ *    `dirname(transcriptPath)`. An override outside that tree is REJECTED
+ *    (returns null), never silently accepted and never falls through to
+ *    derivation — a bad override must not resolve to an unrelated agent's
+ *    sidecar.
+ *  - **Derivation.** `<dir>/<base>/subagents/agent-<agentId>` from the PARENT
+ *    transcript path — the shape all four prior copies agree on
+ *    (subagent-telemetry.mjs:513, on-stop.mjs:666,
+ *    post-subagent-discovery-validator.mjs:552-553, and the subagentsDir
+ *    scripts/lib/wave-transcript-tail.mjs's tailLoop() already builds by hand).
+ *
+ * Returns null — never a guessed or partial path — on ANY invalid input: an
+ * empty/non-string `transcriptPath`, an `agentId` failing `isValidAgentId()`
+ * (only checked in the derivation branch — the override branch does not need
+ * a valid agentId, matching all four prior copies' precedence), or an override
+ * that fails containment.
+ *
+ * NAMED CEILING (BV-004): the meta path is always derived as
+ * `transcript.replace(/\.jsonl$/i, '.meta.json')` (or `${transcript}.meta.json`
+ * when the transcript has no `.jsonl` suffix to replace — an override the
+ * harness contract says never happens; see the header comments of
+ * hooks/post-subagent-discovery-validator.mjs). REVISIT TRIGGER: if a real
+ * override without a `.jsonl` suffix is ever observed, this needs its own
+ * validation branch instead of the current always-well-formed assumption.
+ *
+ * NAMED CEILING (BV-004, LOW, qa review): the override's containment check
+ * (`path.relative(resolvedDir, resolvedOverride)` below) is LEXICAL, not
+ * filesystem-real — it runs on `path.resolve()`'d strings, never on
+ * `fs.realpathSync()`'d ones. A symlink SITTING INSIDE `dirname(transcriptPath)`
+ * whose TARGET points outside that tree therefore passes containment: the
+ * lexical path looks contained, the file it actually resolves to is not.
+ * Deliberately not fixed with a realpath call here — every current consumer
+ * of this override branch (hooks/post-subagent-discovery-validator.mjs) only
+ * READS the resulting sidecar files, and `agentTranscriptPath` is a value the
+ * HARNESS itself supplies on stdin, not one an untrusted external actor can
+ * inject — so the realpath syscalls would buy nothing against the live
+ * threat model. REVISIT TRIGGER: if `agentTranscriptPath` (or any future
+ * override this module accepts) is ever sourced from a producer this repo
+ * does NOT trust as much as the harness's own stdin payload, resolve both
+ * `resolvedOverride` and `resolvedDir` through `fs.realpathSync()` before the
+ * `path.relative()` comparison, so a symlink cannot smuggle the effective
+ * path outside the allowed tree.
+ *
+ * @param {object} args
+ * @param {string|undefined|null} args.transcriptPath — parent transcript path
+ *   (stdin `transcript_path`, or an equivalent parent-transcript path)
+ * @param {string|undefined|null} args.agentId
+ * @param {string|undefined|null} [args.agentTranscriptPath] — harness override
+ *   (`agent_transcript_path`); takes precedence over derivation when present
+ *   and contained under `dirname(transcriptPath)`
+ * @returns {{base: string, transcript: string, meta: string}|null}
+ */
+export function resolveSubagentSidecar({ transcriptPath, agentId, agentTranscriptPath = null }) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return null;
+
+  const dir = path.dirname(transcriptPath);
+  const base = path.basename(transcriptPath).replace(/\.jsonl$/i, '');
+  if (!base || base === '.' || base === '..') return null;
+
+  let transcript;
+  if (typeof agentTranscriptPath === 'string' && agentTranscriptPath.trim()) {
+    const resolvedOverride = path.resolve(agentTranscriptPath);
+    const resolvedDir = path.resolve(dir);
+    const rel = path.relative(resolvedDir, resolvedOverride);
+    const contained = rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    if (!contained) return null;
+    transcript = resolvedOverride;
+  } else {
+    if (!isValidAgentId(agentId)) return null;
+    transcript = path.join(dir, base, 'subagents', `agent-${agentId}.jsonl`);
+  }
+
+  const meta = /\.jsonl$/i.test(transcript)
+    ? transcript.replace(/\.jsonl$/i, '.meta.json')
+    : `${transcript}.meta.json`;
+
+  return {
+    base: transcript.replace(/\.jsonl$/i, ''),
+    transcript,
+    meta,
+  };
+}

package/hooks/cwd-change-restore.mjs

@@ -24,7 +24,6 @@
  * Exit codes: 0 always (informational, never blocking).
  */
 
-import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
@@ -32,6 +31,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 if (!shouldRunHook('cwd-change-restore')) process.exit(0);
 
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { atomicMutateJson } from './_lib/atomic-json.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -71,32 +71,6 @@ function readStdinJson() {
   });
 }
 
-/**
- * Atomic read-modify-write of a JSON file via temp + rename.
- * Reads the existing file (or starts with `defaultValue` when absent),
- * applies `mutate`, writes to a tmp file, then renames over the original.
- * Atomic on POSIX (same-filesystem rename). Best-effort on Windows.
- *
- * @param {string} filePath
- * @param {object} defaultValue — used when the file does not exist or is unparseable
- * @param {function(object): object} mutate — synchronous pure transformer
- */
-async function atomicMutateJson(filePath, defaultValue, mutate) {
-  let current = defaultValue;
-  try {
-    const raw = await readFile(filePath, 'utf8');
-    current = JSON.parse(raw);
-  } catch {
-    // File absent or unparseable — start from defaultValue.
-  }
-
-  const updated = mutate(current);
-  const tmp = `${filePath}.tmp-cwd-${process.pid}-${Date.now()}`;
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(tmp, JSON.stringify(updated, null, 2) + '\n', 'utf8');
-  await rename(tmp, filePath);
-}
-
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -117,14 +91,20 @@ async function main() {
 
   const sessionFile = path.join(SO_PROJECT_DIR, '.orchestrator', 'current-session.json');
 
-  await atomicMutateJson(sessionFile, {}, (current) => {
+  const result = await atomicMutateJson(sessionFile, {}, (current) => {
     const existing = Array.isArray(current.cwd_changes)
       ? current.cwd_changes
       : [];
     // Append the new record and cap at MAX_ENTRIES (keep most-recent).
     const updated = [...existing, record].slice(-MAX_ENTRIES);
     return { ...current, cwd_changes: updated };
-  });
+  }, 'cwd');
+  // Nothing else depends on this write — a non-ENOENT read/parse failure
+  // just means the record is dropped this turn. Diagnostic only (stderr),
+  // matches the hook's own "never blocking" contract.
+  if (!result.ok) {
+    console.error(`cwd-change-restore: atomicMutateJson skipped write (${result.reason})`);
+  }
 }
 
 // Exit 0 always — informational hook must never block Claude.