session-orchestrator 3.23.0 → 3.24.0

package/scripts/vault-mirror.mjs

@@ -63,6 +63,7 @@ import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
 import { resolveCanonicalSuffixes } from './lib/named-vault-resolver.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
+import { canonicalizeSessions } from './lib/sessions-canonical.mjs';
 
 // ── Canonical-vault helpers (#600 D2 / #607 D2) ────────────────────────────────
 // These are module-level (above the CLI bootstrap) so the module is import-safe
@@ -489,24 +490,24 @@ async function main() {
     qualityMinConfidence,
   };
 
-  for (const line of lines) {
-    lineNum++;
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    runState.total++;
-
-    let entry;
-    try {
-      entry = JSON.parse(trimmed);
-    } catch (err) {
-      process.stderr.write(`vault-mirror: malformed JSON on line ${lineNum}: ${err.message}\n`);
-      // Close the run out BEFORE exiting: `process.exit` runs no `finally`, so
-      // without this the abort is the one outcome that leaves no run record —
-      // exactly the shape reserved for a broken emitter.
-      await finishRun('malformed-json');
-      process.exit(1);
-    }
-
+  /**
+   * Dispatch one already-parsed entry to its processor and account for the
+   * result. Extracted (#1186c) so the `--kind session` path below can call it
+   * AFTER a whole-file dedup pass instead of once per raw line; every branch
+   * is byte-identical to the pre-#1186c per-line loop body.
+   * @param {unknown} entry — parsed JSONL value (usually an object; a bare
+   *   `null`/primitive line is a real shape this must keep handling, see the
+   *   #1186c session branch below for why it is never filtered out here).
+   * @param {number} entryLineNum — 1-based JSONL line number, or (for the
+   *   `--kind session` dedup path) the line of the record that WON the
+   *   collapse. `_lineNum` is read ONLY for telemetry (process.mjs
+   *   `emitEntryAction` → `line:` on the per-entry ledger event), never to
+   *   derive content — process.mjs itself tolerates a non-finite value by
+   *   suppressing just that one ledger record, but every call site here
+   *   always supplies a real line number.
+   * @returns {Promise<void>}
+   */
+  async function dispatchEntry(entry, entryLineNum) {
     try {
       // Both processors return the `action` string they emitted (every one of
       // their exit paths is an `emitAction` call), so the tally needs no second
@@ -514,8 +515,8 @@ async function main() {
       // stale the first time a branch is added.
       const action =
         kind === 'learning'
-          ? await processLearning(entry, lineNum, ctx)
-          : await processSession(entry, lineNum, ctx);
+          ? await processLearning(entry, entryLineNum, ctx)
+          : await processSession(entry, entryLineNum, ctx);
       tally(action);
     } catch (err) {
       // Validation errors (missing required fields) → per-entry skip, not a global failure
@@ -530,13 +531,13 @@ async function main() {
         await emitMirrorEvent({
           action: 'skipped-invalid',
           kind,
-          line: lineNum,
+          line: entryLineNum,
           recordId: entryId,
           skipClass: 'validation',
           reason: err.message,
           dryRun,
         });
-        continue;
+        return;
       }
       // #718: discriminate genuine filesystem/system errors (which must still
       // abort the whole run — a partially-written vault is worse than a loud
@@ -552,7 +553,7 @@ async function main() {
         (typeof err.code === 'string' && err.code.length > 0) || Boolean(err.syscall);
       if (!isSystemError) {
         process.stderr.write(
-          `vault-mirror: mapper crash on line ${lineNum} (${err.message}) — record skipped\n`,
+          `vault-mirror: mapper crash on line ${entryLineNum} (${err.message}) — record skipped\n`,
         );
         const entryId = entry?.id ?? entry?.session_id ?? null;
         process.stdout.write(
@@ -569,21 +570,105 @@ async function main() {
         await emitMirrorEvent({
           action: 'skipped-invalid',
           kind,
-          line: lineNum,
+          line: entryLineNum,
           recordId: entryId,
           skipClass: 'mapper-crash',
           reason: err.message,
           dryRun,
         });
-        continue;
+        return;
       }
       // Unexpected filesystem errors → fatal
-      process.stderr.write(`vault-mirror: filesystem error on line ${lineNum}: ${err.message}\n`);
+      process.stderr.write(`vault-mirror: filesystem error on line ${entryLineNum}: ${err.message}\n`);
       await finishRun('filesystem-error');
       process.exit(2);
     }
   }
 
+  // #1186c: for `--kind session`, every parsed entry is buffered here instead
+  // of dispatched inline — the dedup pass below needs the WHOLE file before it
+  // can tell which of several same-`session_id` lines is the winner. `--kind
+  // learning` is unaffected: it still dispatches per line, inline, immediately
+  // below (a malformed line further down the file must not undo an already-
+  // dispatched learning — pinned by the existing `total: 2, created: 1` abort
+  // test in tests/unit/vault-mirror.test.mjs).
+  const sessionEntries = [];
+  const sessionLineNums = [];
+
+  for (const line of lines) {
+    lineNum++;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    runState.total++;
+
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch (err) {
+      process.stderr.write(`vault-mirror: malformed JSON on line ${lineNum}: ${err.message}\n`);
+      // Close the run out BEFORE exiting: `process.exit` runs no `finally`, so
+      // without this the abort is the one outcome that leaves no run record —
+      // exactly the shape reserved for a broken emitter.
+      await finishRun('malformed-json');
+      process.exit(1);
+    }
+
+    if (kind === 'session') {
+      sessionEntries.push(entry);
+      sessionLineNums.push(lineNum);
+      continue;
+    }
+
+    await dispatchEntry(entry, lineNum);
+  }
+
+  if (kind === 'session') {
+    // Only an OBJECT entry carrying a non-empty `session_id` is eligible for
+    // the dedup collapse — the same predicate canonicalizeSessions itself uses
+    // internally (sessions-canonical.mjs `isRecordObject` + `isNonEmptyString`,
+    // not exported, so re-stated here rather than reached into). Everything
+    // else — a bare `null`/primitive JSONL line, or a legacy record with no
+    // `session_id` field — is dispatched EXACTLY as before: unaffected, in
+    // original file order, through the SAME validation/mapper-crash paths
+    // process.mjs already has for those shapes. Two regression-guard tests in
+    // tests/unit/vault-mirror.test.mjs depend on this (a bare `null` line and a
+    // legacy `session`-keyed record both still reach processSession() and its
+    // existing error handling, never silently vanish into the collapse).
+    const isIdentifiable = (e) =>
+      e !== null &&
+      typeof e === 'object' &&
+      !Array.isArray(e) &&
+      typeof e.session_id === 'string' &&
+      e.session_id.length > 0;
+    const identifiable = sessionEntries.filter(isIdentifiable);
+    // canonicalizeSessions never clones — the survivors are the SAME object
+    // references as in `sessionEntries`, so reference identity below is exact,
+    // never a guess (scripts/lib/sessions-canonical.mjs header, "RULE ORDER").
+    const survivors = new Set(canonicalizeSessions(identifiable));
+
+    for (let i = 0; i < sessionEntries.length; i++) {
+      const entry = sessionEntries[i];
+      if (isIdentifiable(entry) && !survivors.has(entry)) {
+        // A losing duplicate: an earlier line whose `session_id` a LATER line
+        // in this same batch supersedes or overwrites (crash-recovery
+        // re-append, #1068 stub/supersede pair). No dispatch, no stdout line,
+        // no tally for it — the winning occurrence (dispatched below, at its
+        // own position) already produces the ONE note this physical session
+        // gets. BV-004 ceiling: `runState.total` still counts this raw line,
+        // so `created+updated+skipped+failed` no longer partitions `total`
+        // for a `--kind session` run that collapsed at least one duplicate —
+        // no test pins that invariant for session kind (only for `learning`,
+        // where duplicates are not collapsed), and a partially-written vault
+        // from a batch that could not be fully deduped is the worse failure
+        // mode. Revisit with a dedicated telemetry action if an operator ever
+        // needs to name WHICH lines were collapsed, not just how many notes
+        // were written.
+        continue;
+      }
+      await dispatchEntry(entry, sessionLineNums[i]);
+    }
+  }
+
   // ── Run close-out (#1147) ───────────────────────────────────────────────────
   //
   // The happy tail. Both roll-ups live in `finishRun` above, which every abort

package/skills/_shared/parallel-aware-auq.md

@@ -101,10 +101,39 @@ The two slots are `parallelPeer.mode` and `parallelPeer.pid`; `<ageHours>` is th
 
 ### Outcome handling
 
-- **Worktree anlegen + starten** → invoke `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. The helper creates a sibling worktree at `<basePath>/<repo-name>-<sessionId>/`, runs idempotency + boundary checks, and logs a WARN line to stderr on fresh creation. When `<branch>` is already checked out by another worktree — the normal case, since Phase 0.5 passes the current HEAD — the worktree lands on a fresh `so/<sessionId>` branch created at `<branch>` and the helper returns `{ branch: 'so/<sessionId>', promotedFrom: '<branch>' }` (#1067); the new worktree's STATE.md `branch` MUST record `so/<sessionId>` and note `promoted from <branch>@<repoRoot>`. Once the worktree exists, and BEFORE exiting the preamble flow, call `leaveSourceRoot({ repoRoot, sessionId: <the raw physical session_id owning this root's lock/registry entry>, semanticSessionId, reason: 'worktree-promotion' })` from `scripts/lib/session-transition.mjs`. **Read that `sessionId` from this root's `.orchestrator/session.lock` via `readLock({ repoRoot })` — never the semantic label, and never `current-session.json`, which may describe a peer session (#863); a wrong id aborts the teardown with `ok: false, reason: 'lock-session-mismatch:<owner>'` and removes nothing.** In detail: the promotion is a PROCESS BOUNDARY, not a live migration (#1069) — the old root is deregistered and its `session.lock` released BEFORE the new worktree's own Phase 1.2 acquires, so the two roots never both own a live claim at once. The call never throws; on `{ ok: false }` emit a stderr WARN `parallel-aware: leaveSourceRoot: <reason>` and continue (the destination worktree already exists — aborting here would leave the two-live-roots state the call prevents). Then exit the current preamble flow — the new worktree's own session-start runs from scratch (Phase 1 onwards). On failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit a stderr warning `parallel-aware: enterWorktree failed: <error>; falling back to Manuell` and proceed via the Manuell path.
+- **Worktree anlegen + starten** → invoke `enterWorktree({ basePath, sessionId, branch, repoRoot, rawSessionId, reason: 'worktree-promotion' })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. The helper creates a sibling worktree at `<basePath>/<repo-name>-<sessionId>/`, runs idempotency + boundary checks, and logs a WARN line to stderr on fresh creation. When `<branch>` is already checked out by another worktree — the normal case, since Phase 0.5 passes the current HEAD — the worktree lands on a fresh `so/<sessionId>` branch created at `<branch>` and the helper returns `{ branch: 'so/<sessionId>', promotedFrom: '<branch>' }` (#1067); the new worktree's STATE.md `branch` MUST record `so/<sessionId>` and note `promoted from <branch>@<repoRoot>`. Since #1170, `enterWorktree` releases the source root ITSELF once the destination worktree provably exists — it calls `leaveSourceRoot({ repoRoot, sessionId: rawSessionId, semanticSessionId: sessionId, reason })` from `scripts/lib/session-transition.mjs` internally, on BOTH success exits, so this AUQ handler makes no separate `leaveSourceRoot` call. `rawSessionId` — **read from this root's `.orchestrator/session.lock` via `readLock({ repoRoot })`, never the semantic label, and never `current-session.json`, which may describe a peer session (#863)** — is the RAW physical `session_id` owning this root's lock/registry entry; a wrong id aborts the teardown with `left.ok: false, reason: 'lock-session-mismatch:<owner>'` and removes nothing. In detail: the promotion is a PROCESS BOUNDARY, not a live migration (#1069) — the old root is deregistered and its `session.lock` released BEFORE the new worktree's own Phase 1.2 acquires, so the two roots never both own a live claim at once. `enterWorktree`'s return value carries the outcome as `left: { ok, steps, reason? }`; `leaveSourceRoot()` never throws, so on `left.ok !== true` `enterWorktree` itself emits the stderr WARN `enterWorktree: leaveSourceRoot: <reason>` and the promotion continues regardless (the destination worktree already exists — aborting here would leave the two-live-roots state the call prevents). Then exit the current preamble flow — the new worktree's own session-start runs from scratch (Phase 1 onwards). On failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit a stderr warning `parallel-aware: enterWorktree failed: <error>; falling back to Manuell` and proceed via the Manuell path.
 - **Manuell** → append a Deviation via `appendDeviationOnDisk()`:
   `Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>, mode=<peer.mode>, pid=<peer.pid>. PSA-001/PSA-002/PSA-004 discipline applies.`
-  Continue Phase-0.
+  Continue Phase-0 — and run the **Peer-Scope-Union** protocol below before the first write.
+
+### Peer-Scope-Union (Manuell only, #1195)
+
+In-place beside a peer is survivable when the two scopes are DECLARED to each other rather than discovered by collision. Measured 2026-09-02 in a consumer repo: a 4-subagent session ran beside a deep session (wave 4, `enforcement: strict`) in ONE checkout, no worktree, zero collisions — the peer's paths were carried in the deep session's `allowedPaths` union (19 → 41, `--assert-subset` green) across a wave rollover.
+
+Four steps, in order. Steps 1 and 2 are the protocol; 3 and 4 are what keeps it honest.
+
+1. **Declare the COMPLETE path list.** The arriving session sends the peer every path it will write — including the ones a script produces (fixtures, snapshots, result files, temp helpers), not only the ones it plans to edit by hand. A path omitted here is a path the peer's guard reports as a violation. In the same message it adopts the peer's resource rules.
+2. **The peer unions.** The receiving coordinator adds those paths to its `allowedPaths` as ONE record `peer-session-<id>` in the wave's scope manifest, re-asserts subset/disjointness, and re-materializes them on every wave rollover (`skills/wave-executor/wave-loop.md` § Scope Manifest).
+3. **Probe with ONE real write.** Before dispatching any agent, make one small PLANNED Edit from the declared list. A denial here costs one edit; the same denial found after a fan-out costs the wave.
+4. **Announce before committing.** The arriving session sends its final file list, the peer sequences its own push behind it, and the SHAs come back. The git index is shared (PSA-007) — sequencing it is the only thing that makes two sessions in one checkout committable.
+
+Message template for step 1 (`SendMessage`, first line self-contained per `.claude/rules/cross-session-messaging.md`):
+
+```
+Scope-union request: I will write exactly these paths in <repo> — please add them to your allowedPaths.
+
+Paths (complete, incl. files my scripts write):
+- <path>
+- <path>
+
+Resource rules I adopt from you: no build, no dev-server ports, no service stop/restart,
+commit only via `git commit --only <my files>` after announcing, no push, no tag.
+
+I will probe with ONE planned edit before dispatching, announce my final file list before
+committing, and send you the SHAs afterwards.
+```
+
+Delivery is never guaranteed (CSM-004): an unanswered request establishes nothing. Without a confirmed union, do not write beside the peer — take the worktree instead.
 - **Abbrechen** → exit Phase-0 immediately. No file writes.
 
 ## Always-OK Pass-Through (no AUQ)

package/skills/_shared/parallel-aware-preamble.md

@@ -134,14 +134,23 @@ async function runParallelAwarePreamble({ repoRoot, callerMode, callerSessionId
     return { outcome: 'EXCLUSIVE_BLOCKED', callerClass, blockingSession: exclusiveActive, active: classifiedActive };
   }
 
+  // GH#67: a registry-sourced peer whose lock is SUPERSEDED (a LIVE lock at
+  // this repoRoot is owned by a DIFFERENT raw session_id) is likely a
+  // finished-but-still-fresh task on a platform without SessionEnd. It stays
+  // visible in `active` (never a filter — the lock is advisory, #1085
+  // contract), but it is not eligible to trigger the Promotion AUQ. Split it
+  // out as advisory before the parallelPeer lookup.
+  const supersededPeers = classifiedActive.filter((e) => e.lockSuperseded === true);
+  const promotionEligible = classifiedActive.filter((e) => e.lockSuperseded !== true);
+
   const parallelPeer = callerClass === 'parallel-ok'
-    ? classifiedActive.find((e) => e._class === 'parallel-ok' && e.sessionId !== callerSessionId)
+    ? promotionEligible.find((e) => e._class === 'parallel-ok' && e.sessionId !== callerSessionId)
     : null;
   if (parallelPeer) {
     return { outcome: 'PROMOTION_OFFER', callerClass, parallelPeer, active: classifiedActive };
   }
 
-  return { outcome: 'PASS_THROUGH', callerClass, active: classifiedActive };
+  return { outcome: 'PASS_THROUGH', callerClass, active: classifiedActive, advisory: supersededPeers };
 }
 ```
 
@@ -153,7 +162,9 @@ The skill consuming the preamble translates the outcome:
 |---------|--------|
 | `PASS_THROUGH` | Continue immediately. No AUQ. Pre-P1.3 behavior. |
 | `EXCLUSIVE_BLOCKED` | Fire Exclusive-Conflict AUQ from `parallel-aware-auq.md`. Block until user response. On "Abbrechen": exit cleanly. On "Andere Session beenden": surface to user (preamble does NOT kill other session). On "Warten": pause Phase 0; re-run preamble on user retry. |
-| `PROMOTION_OFFER` | Fire Promotion AUQ from `parallel-aware-auq.md`. On "Worktree anlegen": call enterWorktree() from worktree-pipeline.mjs, then — BEFORE exiting Phase 0 — `leaveSourceRoot({ repoRoot, sessionId, semanticSessionId, reason: 'worktree-promotion' })` from `session-transition.mjs` (see parallel-aware-auq.md outcome-handling). `sessionId` is the RAW physical `session_id` from this root's `.orchestrator/session.lock` (`readLock({ repoRoot })`), never the semantic label and never `current-session.json` (may describe a peer, #863). The promotion is a process boundary, not a live migration (#1069): the old root is deregistered and its lock released BEFORE the new worktree's own Phase 1.2 acquires — never both roots owning at once. It never throws; on `{ ok: false }` emit a stderr WARN `parallel-aware: leaveSourceRoot: <reason>` and continue. On "Manuell": append Deviation (`Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>`) and continue. On "Abbrechen": exit. |
+| `PROMOTION_OFFER` | Fire Promotion AUQ from `parallel-aware-auq.md`. On "Worktree anlegen": call `enterWorktree({ ..., rawSessionId, reason: 'worktree-promotion' })` from worktree-pipeline.mjs (see parallel-aware-auq.md outcome-handling) — since #1170 this ONE call also releases the source root: it calls `leaveSourceRoot({ repoRoot, sessionId: rawSessionId, semanticSessionId, reason })` from `session-transition.mjs` internally, on BOTH success exits, so no separate call is made here. `rawSessionId` is the RAW physical `session_id` from this root's `.orchestrator/session.lock` (`readLock({ repoRoot })`), never the semantic label and never `current-session.json` (may describe a peer, #863). The promotion is a process boundary, not a live migration (#1069): the old root is deregistered and its lock released BEFORE the new worktree's own Phase 1.2 acquires — never both roots owning at once. The return value's `left` field carries the outcome; `leaveSourceRoot()` never throws, so on `left.ok !== true` `enterWorktree` itself emits the stderr WARN `enterWorktree: leaveSourceRoot: <reason>` and the promotion continues regardless. On "Manuell": append Deviation (`Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>`) and continue. On "Abbrechen": exit. |
+
+**Superseded-lock advisory (GH#67).** A `discovered` peer with `lockSuperseded: true` never fires the Promotion AUQ — it is downgraded to the `advisory` array on the `PASS_THROUGH` result instead (see the `runParallelAwarePreamble` reference above), because a live lock at this repoRoot is owned by a different raw session_id and the entry is likely a finished-but-still-fresh task on a platform without SessionEnd, not a live collision (#1085 advisory-lock contract — the entry is never filtered, only downgraded). The consuming skill prints ONE advisory line per entry: `parallel-aware: registry entry <sessionId> (last heartbeat <N> min ago) is superseded by this root's live lock <lockOwnerId> — likely a finished task on a platform without SessionEnd (GH#67); still counted for PSA-001 awareness`, then continues. `lockSuperseded: false` with `lockOwnerId: null` means "no live lock here" — distinct from "own lock". The same session id remains PSA-002-relevant if it also shows up in STATE.md (`source: 'state-md'`, handled unchanged by Phase 1.2.1/Phase 1b below).
 
 ## Phase 1b Peer-Guard (defense-in-depth)
 
@@ -169,7 +180,9 @@ The guard is a SOFT-GATE — operator can override, but the warning is mandatory
 findPeers(repoRoot, { mySessionId }) → peer = peers.find((p) => p.source === 'state-md') →
   peer === null  →  safe to write STATE.md; continue Phase 1b normally.
   peer !== null  →  fire Promotion AUQ (parallel-aware-auq.md "Promotion" block).
-                    On "Worktree anlegen": enterWorktree() → leaveSourceRoot(this root)
+                    On "Worktree anlegen": enterWorktree(..., rawSessionId) — releases
+                                           the source root internally (#1170; no
+                                           separate leaveSourceRoot call needed)
                                            → continue in sibling (process boundary,
                                              old root released before the new acquire).
                     On "Manuell": appendDeviationOnDisk() + continue in-place.

package/skills/_shared/state-ownership.md

@@ -147,7 +147,7 @@ This is the wave-plan-time analog of PSA-007 (subagents never race the shared gi
 
 The rule above deconflicts writers *inside one wave*. The same working copy is also shared across SESSIONS, and `<state-dir>/wave-scope.json` is the one control artefact that constrains writes rather than describing them. It lives in the working copy, not in the session — so before #1123 a manifest written by session A governed session B's every Edit. Measured 2026-08-22 (#1082): a Discovery wave's `allowedPaths: []` — prescribed for every Discovery wave — denied all writes of an unrelated parallel session, with a deny reason that could only tell it to fix a wave plan it does not own.
 
-**The manifest is SESSION-BOUND since #1123.** The coordinator that writes it names itself in two optional fields, `session` (raw `session_id`) and `semantic_session`, both from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`) — see `skills/wave-executor/wave-loop.md` § Scope Manifest 1. `hooks/enforce-scope.mjs` Gate 3b classifies the manifest with `readOwnSessionIds()` + `classifyManifestSession()` (`scripts/lib/session-identity/own-session.mjs`):
+**The manifest is SESSION-BOUND since #1123.** The coordinator that writes it names itself in two optional fields, `session` (raw `session_id`) and `semantic_session`, both from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`) — see `skills/wave-executor/wave-loop.md` § Scope Manifest 1. `hooks/enforce-scope.mjs` Gate 3b classifies the manifest with `readProcessLocalSessionIds()` + `classifyManifestSession()` (`scripts/lib/session-identity/own-session.mjs`) — process-local tiers only (hook payload, `CLAUDE_CODE_SESSION_ID`), never the repo-global `session.lock`, which is shared by every session in the checkout and made a peer's manifest read `own` (#1194):
 
 - **`foreign`** (ids present, none of them ours) → the gate ALLOWS the write and emits one `orchestrator.scope.foreign_session_ignored` event. A foreign manifest is somebody else's wave plan; it never had authority here, and the event keeps the skip counted rather than silent.
 - **`own`** → enforce, unchanged.

package/skills/contract-version-bump/SKILL.md

@@ -131,7 +131,7 @@ schema, so nobody double-checks the actual runtime behavior, and invalid data pa
 undetected.
 
 Reference case: `maxLength: 63` was the natural way to express S3 bucket-name limits. The
-downstream validator (`aiat-poc-infra/scripts/estate/validate-estate-yaml.sh`) is a hand-written
+downstream validator (`aiat-poc-infra/scripts/estate/validate-estate-yaml.sh`) <!-- path-check: historical --> is a hand-written
 JSON-Schema mini-interpreter that does not implement `maxLength` — it would have parsed the
 schema, not recognized the keyword, and silently done nothing, so a 200-character bucket name
 would still validate green. Decision: extend the consumer (option 1) rather than relying only on

package/skills/ecosystem-health/SKILL.md

@@ -24,7 +24,10 @@ For harness < 2.1.105 (no monitor support), the skill's manual probes documented
 
 This skill reads from the project's `## Session Config` section in the platform instruction file:
 
-- **`health-endpoints`** — list of `{name, url}` objects for service health checks
+- **`health-endpoints`** — list of `{name, url}` objects for service health checks. Parsed
+  content-scoped by `scripts/lib/config/health-endpoints.mjs` (#1174), which accepts the nested
+  block form this wizard writes (below), an inline object array, and a bare list of URLs — see
+  `docs/session-config-reference.md` § VCS & Infrastructure for the full form table.
 - **`cross-repos`** — list of related repositories for critical issue scanning
 
 Both fields are optional. The skill degrades gracefully when either is missing. On Codex this means `AGENTS.md`; on Claude/Cursor it means `CLAUDE.md`.

package/skills/ecosystem-health/wizard.md

@@ -128,6 +128,11 @@ ecosystem-health:
 the block is NOT overwritten. The wizard prints "Skipped (already present)" and
 exits 0. Re-run to edit: remove the existing block first, then re-run.
 
+This nested `health-endpoints:` block (an indented list under a valueless header) is now parsed
+content-scoped by `scripts/lib/config/health-endpoints.mjs` (#1174) — before that fix the flat
+key/value reader bailed to `null` the moment it saw the `{`/nested-list shape this wizard writes,
+so the block above wrote successfully but the ecosystem-health skill silently never saw it.
+
 ### 4b — `.orchestrator/policy/ecosystem.json`
 
 ```json

package/skills/evolve/SKILL.md

@@ -34,6 +34,8 @@ Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills
 
 ## Phase 1: Config & Data Loading
 
+**Telemetry start marker (#1200):** note the current wall-clock time before Step 1.1 runs (e.g. `date +%s%3N`, or the coordinator's own turn-start instant). Every `orchestrator.evolve.completed` emit in Phase 1 / Phase 3 below reports `duration_ms` (placeholder `DURATION_MS`) as the elapsed milliseconds since this marker — same in-memory-value convention as `CT`/`AC`/`ASK`/`DROP` in `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
+
 ### 1.1 Read Session Config
 
 Read and parse Session Config per `skills/_shared/config-reading.md`. Store result as `$CONFIG`.
@@ -44,6 +46,13 @@ Extract `persistence` from `$CONFIG`. If `persistence` is `false`, abort with me
 
 > "Learnings require persistence to be enabled in Session Config. Add `persistence: true` to your Session Config block (CLAUDE.md for Claude Code, AGENTS.md for Codex CLI)."
 
+**Telemetry on abort (#1200):** before stopping, emit the abort form of the run-completion event:
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({aborted: 'persistence-disabled', reason: 'Learnings require persistence to be enabled in Session Config.'.slice(0,300), duration_ms: DURATION_MS}))")"
+```
+
 ### 1.3 Determine Mode
 
 Read mode from `$ARGUMENTS`:
@@ -91,7 +100,12 @@ Extract learnings from session history.
 - Read all entries from `.orchestrator/metrics/sessions.jsonl` (or `<state-dir>/metrics/sessions.jsonl` if the v2 path does not exist — see Phase 1.4 fallback)
 - Parse each JSONL line as JSON
 - Sort by `completed_at` descending (most recent first)
-- If no sessions found, abort: "No session data available. Complete at least one session before running evolve."
+- If no sessions found, abort: "No session data available. Complete at least one session before running evolve." **Telemetry on abort (#1200):** before stopping, emit:
+
+  ```bash
+  node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+    "$(node -e "process.stdout.write(JSON.stringify({aborted: 'no-session-data', reason: 'No session data available. Complete at least one session before running evolve.'.slice(0,300), duration_ms: DURATION_MS}))")"
+  ```
 
 ### Step 3.1b: Read Extra Sources (#638)
 
@@ -380,6 +394,13 @@ For confirmed learnings, use atomic rewrite strategy:
 
 Report: "Saved N new learnings, updated M existing. Total active: K."
 
+**Telemetry (#1200):** emit the run-completion event as the last action of this step, using the counts already computed above — `N` (Step 3.5(4) new-learnings count) → `appended`, `M` (Step 3.5(2) reinforced-existing count) → `boosted`, `$PRUNE.archived` (the sweep CLI's returned total, Step 3.5(5)) → `pruned`. `promoted` is always `0` from THIS call site: promotion to `public` scope is the separate `npm run share:hw-learnings -- --promote` CLI, never invoked by `/evolve analyze` itself — see `docs/events-schema.md`. All four counters are ALWAYS present, including as `0`:
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({appended: N, boosted: M, pruned: PRUNED, promoted: 0, duration_ms: DURATION_MS}))")"
+```
+
 ### Step 3.6: C2 Auto-Repair Feeder (opt-in — #647)
 
 > **Default OFF (advisory-only).** With no `skill-evolution:` block in Session Config, this step surfaces repair candidates as ADVICE only — it applies nothing and opens no MR. This mirrors the opt-in precedent of `slopcheck` (#520) and `verification-auto-fix` (#521): the engine is dark unless explicitly enabled.
@@ -542,6 +563,8 @@ N active learnings (M high confidence, K expiring soon)
 
 Single-pass LLM derivation of USER.md + AGENT.md (peer cards from #503) updates from current learnings + sessions + steering files. Dry-run-default per #506 EARS contract.
 
+**Telemetry start marker (#1200):** note the current wall-clock time at Phase 6 entry (`DURATION_MS` in the Step 6.4/6.5 emits below is the elapsed milliseconds since this marker) — same placeholder convention as `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
+
 ### Step 6.0: Argument Parsing
 
 Parse `$ARGUMENTS` for trailing flags after the `dialectic` keyword:
@@ -603,6 +626,13 @@ const result = await runDialecticDeriver({
 - If `--apply`: call `mergePeerCard(existingBody, managedUpdates)` from `scripts/lib/peer-cards/merger.mjs` for each card target, then `writePeerCard(repoRoot, 'user', mergedUserCard)` and `writePeerCard(repoRoot, 'agent', mergedAgentCard)` from `scripts/lib/peer-cards/writer.mjs`. Update the `updated:` frontmatter.
 - Report: `Dialectic-derived: M deltas to USER.md, N deltas to AGENT.md. Dry-run | Applied. Tokens: in=<X> out=<Y>.`
 
+**Telemetry (#1200):** immediately after the report line above, emit the success form (`mode` mirrors which branch ran):
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.dialectic.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({mode: 'MODE', user_deltas: M, agent_deltas: N, tokens_in: X, tokens_out: Y, duration_ms: DURATION_MS}))")"
+```
+
 ### Step 6.5: Error Handling
 - `status: 'unknown-model'` → fail with clear error (already thrown by validateModel)
 - `status: 'budget-exceeded'` → emit `{status:'budget-exceeded', used:N, budget:M}`, do NOT truncate
@@ -610,6 +640,13 @@ const result = await runDialecticDeriver({
 - `status: 'empty-input'` → exit clean with message "dialectic: skipped (no input)"
 - subagent crash → log ⚠, exit cleanly (do NOT write to `.orchestrator/dialectic-pending.md`)
 
+**Telemetry (#1200):** for EACH outcome above, before exiting, emit `orchestrator.dialectic.completed` in its abort form — `SLUG` is `unknown-model` \| `budget-exceeded` \| `would-empty-card` \| `empty-input` \| `subagent-crash` respectively (the subagent-crash case has no `runDialecticDeriver` status of its own; use the literal slug `subagent-crash`):
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.dialectic.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({aborted: 'SLUG', duration_ms: DURATION_MS}))")"
+```
+
 Cross-reference: PRD #506 AC1-AC4 + EARS gates. Vault Integration: dialectic does NOT mirror to vault (#506 scope — peer cards are repo-local by design; vault mirror is for cross-repo sessions/learnings).
 
 ---

package/skills/journey-audit/SKILL.md

@@ -20,11 +20,12 @@ tools: Read, Grep, Glob, Bash, Write, Task
 
 ## Purpose
 
-The most expensive defects of the first run (EventDrop `main-2026-08-28-a6`: a core feature with no
-entry point anywhere in the UI, burned free quota, a plan gate that could be bypassed, a
-claim-vs-code contradiction, EUR copy in a USD context) are **invisible to every code-centric
-check**. They are not bugs in a function; they are gaps between five surfaces — marketing copy,
-code constants, live UI, outbound mail, real usage data — that no single surface can reveal.
+The most expensive defects of a consumer product's first run (session id redacted) — a core
+feature with no entry point anywhere in the UI, burned free quota, a plan gate that could be
+bypassed, a claim-vs-code contradiction, EUR copy in a USD context — are **invisible to every
+code-centric check**. They are not bugs in a function; they are gaps between five surfaces —
+marketing copy, code constants, live UI, outbound mail, real usage data — that no single
+surface can reveal.
 
 This skill dispatches seven roles that each own one surface, then makes the coordinator personally
 re-verify every P0 before it is written down. The re-verification is the value, not the fan-out:

package/skills/reconcile/SKILL.md

@@ -156,9 +156,9 @@ himself.
 ### 2.3 Invoke `runReconcile`
 
 ```javascript
-import { runReconcile } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
+import { runReconcileFromSkill } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
 
-const { proposals, rejected, summary, error } = await runReconcile({
+const { proposals, rejected, summary, error } = await runReconcileFromSkill({
   repoRoot,             // absolute path from git rev-parse --show-toplevel
   ruleExpiryDays: RULE_EXPIRY_DAYS,   // empty → undefined → engine per-type TTL
   minRuleDays: MIN_RULE_DAYS,         // default 7 — floors a near-dead expires-at
@@ -166,6 +166,9 @@ const { proposals, rejected, summary, error } = await runReconcile({
   maxProposalsPerRun: MAX_PROPOSALS_PER_RUN, // default 10 — volume brake (issue #900 D)
   now: new Date(),
   dryRun: DRY_RUN,     // true → engine touches no disk (no idempotency sidecar write)
+  // trigger is pinned to 'skill' IN CODE by runReconcileFromSkill (#1201 Part A) —
+  // this prose block no longer sets it.
+  targets,             // from resolveEffectiveTargets above; recorded when non-empty, omitted otherwise
 });
 
 // The engine does NOT apply a confidence floor — it proposes every eligible

package/skills/remote-offload/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: remote-offload
+user-invocable: false
+tags: [reference, remote, offload, wave-executor, resource-gate]
+model: haiku
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+description: Use when local resource pressure would shrink or coordinator-direct a wave, a wave plan carries heavy build/test/audit roles (test, ui, perf), or the operator says offload, remote host, or auslagern — reference for routing that wave role to a declared SSH-reachable host instead of reducing agent count
+---
+
+# Remote Offload — routing a wave role to a declared host instead of shrinking it
+
+Repo-side half of #1160: `remote-hosts:` declares hosts, `wave-resource-gate.mjs` places work on them, `remote-dispatch.mjs` runs it. The host-side `offload` CLI (a separate baseline repo owns its SSOT) is invoked as a subprocess; this skill covers what the repo itself knows about it.
+
+## Quick reference
+
+| Task | Command |
+|---|---|
+| Host readiness | `offload doctor -H <alias> --brief` |
+| Gate (typecheck/lint/test) | `offload gate <repo> -H <alias>` |
+| Run a command | `offload run <repo> -H <alias> -- <cmd...>` |
+| Read-only analysis | `offload claude <repo> -H <alias> --model <name> < prompt.txt` |
+| Implementation + patch | `offload claude <repo> -H <alias> --write --patch <path> < prompt.txt` |
+| Remove finished jobs | `offload clean -H <alias> --older-than <hours>` |
+
+Exit codes (`offload --help`, measured 2026-09-02): `0` ok · `1` usage/config · `2` host unreachable/not ready · `3` remote command failed · `4` sync failed · `5` timeout · `6` empty diff on a `--write` run · `7` account quota exhausted (429) · `8` write lock held. Same map as `OFFLOAD_EXIT_REASONS` in `scripts/lib/wave-executor/remote-dispatch.mjs`.
+
+## 1. Decision rule — offload vs reduce
+
+The gate decides, not the coordinator. `applyOffloadDecision()` in `scripts/lib/wave-resource-gate.mjs` only fires when the resource verdict is already `reduce` or `coordinator-direct`, and only AFTER the HR-004 heavy-repo cap — a capped wave that offloads still respects the cap. It never probes the network; the coordinator supplies a readiness WITNESS:
+
+- `opts.remoteReady` — `{ [alias]: boolean }`, built from the SessionStart banner line `Offload <alias>: ready=yes …`, or
+- `opts.probeFn` — an async `(alias) => boolean` fallback, consulted only for aliases `remoteReady` doesn't answer for (backed by `remoteDoctor()`, i.e. `offload doctor -H <alias> --brief` parsed by `parseDoctorLine()`).
+
+With neither supplied, no host counts as ready and the wave 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`: `impl-core`, `security-review`, `migration`, `release`, `secrets`) is never offloaded regardless of readiness.
+
+## 2. What is declared where
+
+`remote-hosts:` in Session Config (`docs/session-config-reference.md` § Remote Hosts) declares the hosts, in preference order — the gate takes the FIRST host whose `roles-allowed` accepts the wave role and is witnessed ready:
+
+```yaml
+remote-hosts:
+  - alias: <ssh-alias>                 # required, SAFE slug; reaches argv as `-H <alias>`
+    roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
+    repo-path: ~/path/on/host          # optional; SAFE path; default null
+    claude-path: ~/.local/bin/claude   # optional; SAFE path; default null
+```
+
+Two enums meet here and must not be conflated: `roles-allowed` holds `agent-mapping` roles (`test`/`ui`/`perf`), not wave roles (`Impl-Core`/`Quality`/…). The translation table is `OFFLOADABLE_WAVE_ROLES` in `wave-resource-gate.mjs` (`quality`→`test`, `test`→`test`, `ui`→`ui`, `perf`→`perf`; a wave role absent from that map stays local by default).
+
+An `agent-mapping` entry of the form `<role>: ssh:<alias>` routes that wave role to Claude running ON the declared host instead of shrinking the wave; the alias must already exist under `remote-hosts`, or the config parse throws.
+
+## 3. Three channels of work
+
+| Channel | Command | Verdict rule |
+|---|---|---|
+| Gate / arbitrary command | `offload gate` / `offload run` | Exit code decides — use the table above, never the prose in the run's own output |
+| Implementation, patch back | `offload claude --write --patch <file>` via `dispatchRemote()` | Empty patch (exit `6`) is a FAILURE regardless of what the run reports; the coordinator READS the patch, then applies it with its own `git apply` — the remote job never touches the repo the coordinator commits from |
+| Read-only analysis | `offload claude` (no `--write`) | No patch is produced; treat the transcript as advisory input, same skepticism as any reviewer output (`receiving-review.md`) |
+
+`dispatchRemote()` (`scripts/lib/wave-executor/remote-dispatch.mjs`) is the wave-executor caller for the second and third channels; it emits `orchestrator.remote_dispatch.completed` once per call (`docs/events-schema.md`) — the only ledger record a remote dispatch produces, since a Bash-spawned `offload` child fires no `SubagentStop` hook. Payload: `host`, `role`, `run_id`, `ok`, `exit_code`, `duration_ms`, `patch_files`, `patch_bytes`, `reason` (present on every refusal and every failure class — absence means success). Deliberately excluded from the payload: prompt text, patch body, `patch_path`.
+
+## 4. Rules
+
+- **Supervised, not blind.** Read the gate log or the patch before treating it as a result — completed and correct are not the same claim.
+- **Prompt travels on stdin, never argv** (`offload --help`: "prompts travel by file (mode 600), never argv"; argv is visible to every process on the host).
+- **The patch is READ, then applied by the coordinator** — never inside the offloaded job.
+- **`never_foreign` roles are never offloaded** — checked first in `dispatchRemote()`, before any spawn or side effect.
+- **One `--job` per concurrent run.** A job holds ONE set of run artefacts; two parallel runs sharing a job collided until per-run ids were introduced.
+- **Rate-limit (exit `7`) carries the reset time in the message** — do not retry blind.
+- **Secrets never in output** (SEC-008) — `offload` does not print credentials, and the module deliberately excludes prompt text and patch body from telemetry.
+- **Never "clean up" another checkout on the host.** `offload clean` only removes the offload tool's OWN finished job worktrees, never a host's other active checkouts.
+
+## 5. Host readiness checklist
+
+- SSH alias configured with key auth (no password/interactive prompt on connect).
+- `tmux` available on the host (for an interactive `offload session`).
+- Claude authenticated ON the host — never copy OAuth credentials between machines (refresh-token rotation invalidates the source copy); log in fresh with `/login` there instead.
+- Repo cloned on the host with headless git credentials configured (no interactive auth prompt on push/pull).
+- Node version matching this repo's `.nvmrc`.
+- Toolchain parity with the local checkout (same package manager, same lockfile).
+
+## 6. Pitfalls measured in this repo
+
+- **The pre-push quality gate used to fire on the sync push.** `.husky/pre-push` (#C10) detects a SCRATCH push — an unconfigured remote URL, e.g. the offload tool's own SSH sync target — and skips the gate for it; publish remotes (`origin`, `github`) stay gated regardless. The offload tool has since been fixed upstream to push with `--no-verify` itself, so this repo-side detection is defense-in-depth, not the primary fix.
+- **The host installer must follow this repo's committed lockfile.** `package-lock.json` is tracked here (npm-canonical — `.claude/rules/development.md` § Package Management); install with `npm ci`, never a different package manager's install command, or the host checkout's `node_modules` layout diverges from CI's.
+- **A linked worktree makes `.git` a file, not a directory.** 13 tracked files used to be flagged as "not in repository" in an unmodified worktree at the same layout, because the file form of `.git` was read as an untracked candidate rather than the repository marker — wave 3 fixed `scripts/lib/validate/check-untracked-test-deps.mjs` to treat a `.git` FILE as the repository marker in a linked worktree; the remote gate then ran 15,829/0.
+- **Keychain-route auth shares the host account's usage window with that account's other interactive sessions**, not a dedicated quota — a token-slot profile (`--via slot`) avoids the sharing where a fixed quota matters.

package/skills/session-end/phase-3-6-tail.md

@@ -246,14 +246,15 @@ After learnings are written (Phase 3.6) and the auto-dream decision is made (Pha
 
 1. Read `dialectic.cadence` (default 5), `dialectic.model` (default haiku), `dialectic.budget-tokens` (default 8000) from `$CONFIG`.
 
-2. Invoke `shouldDispatchAutoDialectic` from `scripts/lib/auto-dialectic.mjs`:
+2. Invoke `decideAndRecordAutoDialectic` from `scripts/lib/auto-dialectic.mjs`:
    ```javascript
-   import { shouldDispatchAutoDialectic } from '${PLUGIN_ROOT}/scripts/lib/auto-dialectic.mjs';
-   const decision = await shouldDispatchAutoDialectic({
+   import { decideAndRecordAutoDialectic } from '${PLUGIN_ROOT}/scripts/lib/auto-dialectic.mjs';
+   const decision = await decideAndRecordAutoDialectic({
      repoRoot: process.cwd(),
      cadence: config.dialectic?.cadence ?? 5,
    });
    ```
+   Same return shape as `shouldDispatchAutoDialectic` (`{trigger, reason, signals}`) — `decideAndRecordAutoDialectic` calls it internally and additionally emits the mechanical `orchestrator.dialectic.nudge_decided` telemetry record on all four return paths (#1200 part c), so the nudge decision is observable without depending on this prose actually reaching step 5/7.
 
 3. If `decision.trigger === false`: log `auto-dialectic: not triggered (${decision.reason})` and continue. Emit no nudge. Do NOT update `.orchestrator/dialectic-last-run`.
 
@@ -291,17 +292,19 @@ After the auto-dialectic nudge decision is made (Phase 3.6.7), and when the reco
 
 1. Read Session Config: `reconcile.enabled` (default `false`), `reconcile['rule-expiry-days']` (default `null` — falls back to per-type TTL in the engine), `reconcile['confidence-floor']` (default `0.5`), `reconcile['min-rule-days']` (default `7` — floor window (days) applied to a proposed rule's `expires-at` so a near-dead or already-elapsed natural expiry never produces a born-dead rule, issue #741.1), `reconcile['min-insight-chars']` (default `24` — opt-in minimum insight length gating the eligibility placeholder-insight check, issue #741.2), `reconcile['max-proposals-per-run']` (default `10` — volume brake, issue #900 D; the engine sorts eligible learnings by confidence DESC and proposes at most this many per run). If `reconcile.enabled` is not `true`, log `reconcile: disabled (reconcile.enabled=false)` and skip all remaining steps.
 
-2. Invoke `runReconcile` from `scripts/lib/reconcile/engine.mjs`:
+2. Invoke `runReconcileAtSessionEnd` from `scripts/lib/reconcile/engine.mjs`:
 
    ```javascript
-   import { runReconcile } from '${PLUGIN_ROOT}/scripts/lib/reconcile/engine.mjs';
-   const { proposals, rejected, summary, error } = await runReconcile({
+   import { runReconcileAtSessionEnd } from '${PLUGIN_ROOT}/scripts/lib/reconcile/engine.mjs';
+   const { proposals, rejected, summary, error } = await runReconcileAtSessionEnd({
      repoRoot: process.cwd(),
      ruleExpiryDays: config.reconcile['rule-expiry-days'] ?? undefined,
      minRuleDays: config.reconcile['min-rule-days'] ?? undefined,
      minInsightChars: config.reconcile['min-insight-chars'] ?? undefined,
      maxProposalsPerRun: config.reconcile['max-proposals-per-run'] ?? undefined,
      now: new Date(),
+     // trigger is pinned to 'session-end' IN CODE by runReconcileAtSessionEnd
+     // (#1201 Part A) — this prose block no longer sets it.
    });
    ```