session-orchestrator 3.23.0 → 3.24.0

package/hooks/on-stop.mjs

@@ -16,15 +16,32 @@
  * JSONL format (`.orchestrator/metrics/events.jsonl`) — emitted via the canonical
  * `emitEvent()` so the JSONL record and the optional Clank webhook always carry the
  * SAME dotted event name (was: bare `stop`/`subagent_stop` in JSONL vs dotted in webhook):
- *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.session.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>}
- *                (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.)
- *   SubagentStop: {"timestamp":<ISO>,"event":"orchestrator.agent.stopped","agent":"<name>"}
+ *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.session.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>,"duration_source":"session-lock"}
+ *                (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.
+ *                 `duration_ms` + `duration_source` are omitted TOGETHER when no OWNED
+ *                 session.lock is readable — never a fabricated 0, see K5 below.)
+ *   SubagentStop: {"timestamp":<ISO>,"event":"orchestrator.agent.stopped","agent":"<name>","agent_id":"...",
+ *                  "agent_type_meta":"...","tool_use_id":"...","transcript_found":true,
+ *                  "duration_ms":<int>,"duration_source":"meta-birthtime","status":"done"}
+ *                (#1190 — every key after `event` is OPTIONAL and OMITTED when the
+ *                 measurement could not be made; `agent` too. See docs/events-schema.md.)
  */
 
 import path from 'node:path';
-import { promises as fs, statSync, writeFileSync } from 'node:fs';
+import {
+  promises as fs,
+  closeSync,
+  existsSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { AGENT_ID_RE, resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
 if (!shouldRunHook('on-stop')) process.exit(0);
 
@@ -32,7 +49,7 @@ import { emitEvent } from '../scripts/lib/events.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
-import { updateHeartbeat } from '../scripts/lib/session-lock.mjs';
+import { readLock, updateHeartbeat } from '../scripts/lib/session-lock.mjs';
 
 // ---------------------------------------------------------------------------
 // stdin reading (inline — no io.mjs because Stop hooks exit 0 always, never deny)
@@ -247,7 +264,8 @@ async function readWaveNumber(projectRoot) {
  */
 async function resolveSessionId(input, projectRoot) {
   const fromStdin = input?.session_id ?? input?.sessionId ?? null;
-  let sessionId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+  const rawStdinId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+  let sessionId = rawStdinId;
 
   let recordedId = null;
   let semanticSessionId = null;
@@ -265,15 +283,84 @@ async function resolveSessionId(input, projectRoot) {
     }
   } catch { /* missing or unparseable is fine */ }
 
+  // Actor-identity fallback ONLY — `sessionId` drives the registry heartbeat and
+  // the lock heartbeat, both of which need an id even when stdin carried none.
   if (sessionId === null) sessionId = recordedId;
 
-  const isRecordedSession = sessionId !== null && sessionId === recordedId;
+  // W4a review F-A, second site of the same defect (census: exactly 2, both in
+  // hooks/, `grep -rn "= recordedId;" hooks/ scripts/` 2026-09-02). Comparing
+  // the RESOLVED id against `recordedId` is self-fulfilling: the line above may
+  // have just copied one into the other, so an id-less or non-UUID turn-end
+  // always read as "I am the recorded session" and inherited a live PEER's
+  // semantic identity — the exact #863 defect (c) contamination this gate
+  // exists to refuse. Decided on the RAW stdin UUID instead.
+  const isRecordedSession = rawStdinId !== null && rawStdinId === recordedId;
   return {
     sessionId,
     semanticSessionId: isRecordedSession ? semanticSessionId : null,
   };
 }
 
+/**
+ * Resolve an elapsed span for this Stop event — and WHICH span depends on the
+ * source, which is why `duration_source` ships beside the number (W4a F-C).
+ *
+ *   `session-lock`   — SESSION-elapsed, measured at this turn's end. Stop fires
+ *                      once per TURN, and `started_at` is stamped once per
+ *                      SESSION, so this number GROWS MONOTONICALLY across the
+ *                      turns of one session: the last Stop of a 3-hour session
+ *                      reports ~3 hours, not the length of its final turn.
+ *   `stdin-start-ms` — TURN-elapsed, the only first-party measurement of the
+ *                      turn itself. Measured today: the harness never sends it,
+ *                      so this source has never appeared in the fleet stream.
+ *
+ * Consumers must therefore not aggregate the two: summing `session-lock` spans
+ * over a session double-counts, where summing `stdin-start-ms` spans would not.
+ *
+ * OWNERSHIP-GATED, on the raw stdin `session_id` only. A lock in this working
+ * copy may name a PEER session (two windows share one checkout routinely), and
+ * a working-copy artefact is not a process-local identity witness — so the
+ * lock's `session_id` must match the id the STOPPING session was handed on
+ * stdin. `resolveSessionId()`'s resolved id is deliberately NOT used here: it
+ * falls back to `current-session.json`, which is exactly the foreign-identity
+ * inheritance this guard exists to refuse.
+ *
+ * Returns an object to SPREAD into the payload: `{}` when nothing is
+ * attestable, so `duration_ms` and `duration_source` are omitted together
+ * rather than written as a fabricated 0 (K5).
+ *
+ * `start_ms` is honoured first when the harness ever starts sending it — it is
+ * the only first-party measurement of the turn itself; measured today it is
+ * never present.
+ *
+ * @param {object|null} input parsed stdin payload
+ * @param {string} projectRoot
+ * @returns {{duration_ms?: number, duration_source?: string}}
+ */
+function resolveStopDuration(input, projectRoot) {
+  if (typeof input?.start_ms === 'number' && Number.isFinite(input.start_ms)) {
+    const ms = Date.now() - input.start_ms;
+    if (Number.isFinite(ms) && ms >= 0) {
+      return { duration_ms: Math.round(ms), duration_source: 'stdin-start-ms' };
+    }
+  }
+
+  const stdinId = input?.session_id ?? input?.sessionId ?? null;
+  if (typeof stdinId !== 'string' || stdinId.length === 0) return {};
+
+  try {
+    const lock = readLock({ repoRoot: projectRoot });
+    if (lock === null || lock.session_id !== stdinId) return {};
+    const startedAt = Date.parse(lock.started_at);
+    if (Number.isNaN(startedAt)) return {};
+    const ms = Date.now() - startedAt;
+    if (!Number.isFinite(ms) || ms < 0) return {};
+    return { duration_ms: Math.round(ms), duration_source: 'session-lock' };
+  } catch {
+    return {}; // best-effort — an unreadable lock measures nothing
+  }
+}
+
 /**
  * Handle a Stop event. Reads wave from scope file + git info, appends JSONL.
  * @param {object|null} input
@@ -350,9 +437,15 @@ async function handleStop(input) {
     } catch { /* best-effort */ }
   }
 
-  // duration_ms: if input provides a start time we compute from it, else 0
-  const durationMs =
-    typeof input?.start_ms === 'number' ? Date.now() - input.start_ms : 0;
+  // K5 — `duration_ms` was literally 0 in 8.127 of 8.127 fleet
+  // `orchestrator.session.stopped` records (measured 2026-09-02): the old
+  // expression fell back to a hard 0 because the harness never sends
+  // `start_ms`. A fabricated 0 is the exact failure class
+  // `scripts/lib/telemetry/subagents-schema.mjs:20-35` documents — it reads as
+  // a MEASURED zero-length session and is indistinguishable from one. So the
+  // span now comes from the session.lock's `started_at`, and BOTH keys are
+  // omitted when it cannot be measured.
+  const duration = resolveStopDuration(input, projectRoot);
 
   // Single emission path: emitEvent writes the canonical {timestamp, event, ...payload}
   // JSONL record AND fires the optional Clank webhook with the SAME event name — no
@@ -361,14 +454,19 @@ async function handleStop(input) {
   // turn-end outcome is joinable by identity from events.jsonl alone. Omitted
   // (never `""`/`null`) when unattested: an unresolved identity stays visibly
   // unresolved rather than becoming a guessed id.
-  await emitEvent('orchestrator.session.stopped', {
-    ...(sessionId !== null ? { session_id: sessionId } : {}),
-    ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
-    wave,
-    ...(branch !== null ? { branch } : {}),
-    ...(commit !== null ? { commit } : {}),
-    duration_ms: durationMs,
-  });
+  // #1183 — a malformed record throws EventValidationError BEFORE any side
+  // effect (scripts/lib/events.mjs); this hook must never abort on that, so
+  // the emit is wrapped rather than left to propagate.
+  try {
+    await emitEvent('orchestrator.session.stopped', {
+      ...(sessionId !== null ? { session_id: sessionId } : {}),
+      ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+      wave,
+      ...(branch !== null ? { branch } : {}),
+      ...(commit !== null ? { commit } : {}),
+      ...duration,
+    });
+  } catch { /* telemetry never blocks the hook (#1183) */ }
 }
 
 /**
@@ -380,11 +478,242 @@ async function handleStop(input) {
  * @returns {Promise<string|null>} additionalContext or null
  */
 async function handleSubagentStop(input) {
-  const agent = input?.agent_type ?? 'unknown';
-  await emitEvent('orchestrator.agent.stopped', { agent });
+  /** @type {Record<string, unknown>} */
+  const payload = {};
+
+  // `agent` — the #1190 headline fix. The harness sends the EMPTY STRING, which
+  // `?? 'unknown'` never caught: 89.991 of 103.763 fleet records (86,7%,
+  // measured 2026-09-02) carry `agent: ""`. Trim, and emit the key ONLY when a
+  // real value remains — an unmeasured type stays visibly unmeasured rather
+  // than becoming `""` or a guessed `'unknown'`.
+  //
+  // Clamped with the SAME regex as `agent_type_meta` below (Q1-LOW-F3): this is
+  // the identical value class from a different source, it lands in the ledger
+  // and travels the optional Clank webhook, and it was the only unclamped
+  // string in this payload. A mismatch OMITS the key — never a truncation,
+  // which would look like a measured (but wrong) agent type.
+  const rawAgent = firstNonEmptyString(input, ['agent_type', 'subagent_type']);
+  const agent = rawAgent !== null && AGENT_TYPE_META_RE.test(rawAgent) ? rawAgent : null;
+  if (agent !== null) payload.agent = agent;
+
+  // `agent_id` — reader shape copied from hooks/subagent-telemetry.mjs (both
+  // naming conventions the harness may use). Charset-guarded before it is ever
+  // interpolated into a path (same precedent, resolveSubagentTranscriptPath)
+  // AND before it is emitted: an unbounded, unvalidated id (`../../etc/passwd`,
+  // or a 10 KB blob) would otherwise land verbatim in the ledger and travel
+  // over the optional Clank webhook unredacted. A rejected id is OMITTED — the
+  // same omission contract every other field in this payload uses — never
+  // sanitised into a different id that looks measured.
+  const rawAgentId = firstNonEmptyString(input, ['agent_id', 'subagent_id']);
+  const agentId = rawAgentId !== null && AGENT_ID_RE.test(rawAgentId) ? rawAgentId : null;
+  if (agentId !== null) payload.agent_id = agentId;
+
+  // Sidecar-derived fields. Every derivation is individually wrapped: a failure
+  // omits its own field and nothing else, and this function must never throw —
+  // a throw here would skip the emit and lose the record that already works.
+  // Consolidated derivation (#1196): hooks/_lib/subagent-paths.mjs now also
+  // rejects the literal 'unknown' agentId — this file's own AGENT_ID_RE-only
+  // check (above, for the emitted `agent_id` field) never did.
+  const sidecar = resolveSubagentSidecar({ transcriptPath: input?.transcript_path, agentId });
+  if (sidecar !== null) {
+    const transcriptPath = sidecar.transcript;
+    const metaPath = sidecar.meta;
+
+    let transcriptFound = false;
+    try {
+      transcriptFound = existsSync(transcriptPath);
+      payload.transcript_found = transcriptFound;
+    } catch { /* probe failed — omit rather than assert `false` */ }
+
+    try {
+      // One small read, one parse, two fields. `description` is operator prose
+      // and is deliberately NOT carried: this payload also travels over the
+      // optional Clank webhook unredacted.
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+      // Both fields are CHARSET+LENGTH CLAMPED before they enter the payload,
+      // for the same reason `agent_id` above is: this record is appended to the
+      // ledger AND travels over the optional Clank webhook UNREDACTED, and
+      // meta.json is written by the harness, not by us. An oversized or
+      // structured value would land verbatim in both. A rejected value is
+      // OMITTED, never truncated into a shorter value that still looks measured.
+      if (typeof meta?.toolUseId === 'string' && TOOL_USE_ID_RE.test(meta.toolUseId.trim())) {
+        payload.tool_use_id = meta.toolUseId.trim();
+      }
+      // A SECOND witness for the type — never merged into `agent`, so the
+      // empty-`agent_type` rate stays measurable.
+      if (typeof meta?.agentType === 'string' && AGENT_TYPE_META_RE.test(meta.agentType.trim())) {
+        payload.agent_type_meta = meta.agentType.trim();
+      }
+    } catch { /* absent or corrupt sidecar meta — omit both fields */ }
+
+    try {
+      // meta.json carries no spawn timestamp; the harness writes the file AT
+      // spawn, so its birthtime IS the spawn moment. `duration_source` puts
+      // that provenance in the record instead of implying a measured span.
+      const span = spanFromBirthtime(Date.now(), statSync(metaPath).birthtimeMs);
+      if (span !== null) {
+        payload.duration_ms = span;
+        payload.duration_source = 'meta-birthtime';
+      }
+    } catch { /* stat failed — omit both keys (never a fabricated 0) */ }
+
+    if (transcriptFound) {
+      const status = readStatusFromTranscriptTail(transcriptPath);
+      if (status !== null) payload.status = status;
+    }
+  }
+
+  // #1183 — a malformed record throws EventValidationError BEFORE any side
+  // effect (scripts/lib/events.mjs); this hook must never abort on that, so
+  // the emit is wrapped rather than left to propagate.
+  try {
+    await emitEvent('orchestrator.agent.stopped', payload);
+  } catch { /* telemetry never blocks the hook (#1183) */ }
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// SubagentStop payload derivations (#1190)
+// ---------------------------------------------------------------------------
+
+/**
+ * Harness tool-use ids, measured on-disk 2026-09-02 in a real sidecar meta.json:
+ * `toolu_01Xj6qZ3ApsVfomhByNftmxj` (25 chars, alphanumeric + one underscore).
+ */
+const TOOL_USE_ID_RE = /^[A-Za-z0-9_.-]{1,64}$/;
+
+/**
+ * Agent types carry a plugin qualifier, so the COLON is part of the real shape —
+ * measured in the same file: `session-orchestrator:code-implementer` (37 chars).
+ * A `tool_use_id`-identical charset would have rejected every plugin-qualified
+ * agent type in this repo, i.e. silently removed the field it clamps.
+ */
+const AGENT_TYPE_META_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+/**
+ * Upper bound on a `meta-birthtime` span, in ms. NAMED CEILING (BV-004): 7 days.
+ *
+ * No subagent runs for a week — the longest recorded here is minutes — so a
+ * span above this is not a long agent, it is a birthtime the filesystem did not
+ * supply. Node documents `birthtimeMs` as unavailable on filesystems that do
+ * not record it (overlayfs and some CI images among them), where it surfaces as
+ * 0 / 1970-01-01; the old `>= 0` lower bound accepted that verbatim and would
+ * ship a ~55-YEAR span stamped `duration_source: 'meta-birthtime'` — a
+ * fabricated measurement of exactly the class K5 removed.
+ *
+ * REVISIT TRIGGER: if a legitimately long-running agent class ever appears
+ * (a background agent measured in hours-to-days), raise this — but raise it to
+ * a measured bound, never remove it.
+ */
+const META_BIRTHTIME_MAX_SPAN_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Span between a birthtime and now, or `null` when the birthtime is not a
+ * usable measurement.
+ *
+ * Rejects a non-positive `birthtimeMs` (the "filesystem records no birthtime"
+ * signal) and any span outside `(0, META_BIRTHTIME_MAX_SPAN_MS)`. `null` means
+ * "omit both keys" at the call site — never a fabricated number.
+ *
+ * Pure, and separate from the call site so the two out-of-band cases are
+ * testable without a filesystem that can forge a birthtime.
+ *
+ * @param {number} nowMs
+ * @param {number} birthtimeMs
+ * @returns {number|null} rounded span in ms, or null
+ */
+function spanFromBirthtime(nowMs, birthtimeMs) {
+  if (!Number.isFinite(birthtimeMs) || birthtimeMs <= 0) return null;
+  const span = nowMs - birthtimeMs;
+  if (!Number.isFinite(span) || span < 0 || span > META_BIRTHTIME_MAX_SPAN_MS) return null;
+  return Math.round(span);
+}
+
+/** Tail window for the STATUS scan — sidecars measured at 113–528 KB. */
+const STATUS_TAIL_BYTES = 64 * 1024;
+
+/**
+ * STATUS literals an agent reports at the START of a line (optionally bold).
+ *
+ * LINE-ANCHORED on purpose — the rationale and the measurement are at
+ * `scripts/lib/wave-transcript-tail.mjs:105-112`: a free-floating
+ * `/STATUS: partial/` fires on any agent that merely QUOTES the marker
+ * (2 of 2 live hits in that measurement were quotations, 0 were reports).
+ * NOT imported from that module because the two alternations are DIFFERENT
+ * literal sets, not two copies of one: the tailer's `STATUS_RE` matches only
+ * `partial|blocked|failed` (it classifies a single `status-partial` attention
+ * pattern), while this hook records the agent's SELF-REPORTED status and must
+ * therefore also match `done` and `no-tests-needed`. Importing its constant
+ * would silently drop the two success literals. (Import cost is NOT the reason —
+ * measured 2026-09-02 as equal.)
+ */
+const AGENT_STATUS_RE = /^[ \t*_]*STATUS:\s*(done|partial|blocked|failed|no-tests-needed)\b/im;
+
+/**
+ * Pick the first non-empty trimmed string among `keys` on `input`.
+ * @param {object|null|undefined} input
+ * @param {string[]} keys
+ * @returns {string|null}
+ */
+function firstNonEmptyString(input, keys) {
+  for (const k of keys) {
+    const v = input?.[k];
+    if (typeof v === 'string' && v.trim()) return v.trim();
+  }
+  return null;
+}
+
+/**
+ * Read the LAST `STATUS_TAIL_BYTES` of an agent transcript and return the most
+ * recent line-anchored STATUS literal, or null when none is present.
+ *
+ * Never reads the whole file: measured sidecar sizes are 113–528 KB and this
+ * hook fires on every SubagentStop. Absence means NOT FOUND, never success —
+ * measured 2026-09-02, only 1 of 4 live sidecars carried a STATUS token in its
+ * last 64 KiB, so the miss is the common path.
+ *
+ * @param {string} transcriptPath
+ * @returns {string|null}
+ */
+function readStatusFromTranscriptTail(transcriptPath) {
+  let fd = null;
+  try {
+    fd = openSync(transcriptPath, 'r');
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, STATUS_TAIL_BYTES);
+    const start = size - length;
+    const buf = Buffer.alloc(length);
+    const read = readSync(fd, buf, 0, length, start);
+    let lines = buf.subarray(0, read).toString('utf8').split('\n');
+    // Drop the leading partial line when the window did not start at byte 0.
+    if (start > 0) lines = lines.slice(1);
+
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch { continue; }
+      const content = rec?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (let j = content.length - 1; j >= 0; j -= 1) {
+        const block = content[j];
+        if (typeof block?.text !== 'string') continue;
+        const m = AGENT_STATUS_RE.exec(block.text);
+        if (m) return m[1].toLowerCase();
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------

package/hooks/post-bash-write-verify.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 /**
  * post-bash-write-verify.mjs — PostToolUse hook (matcher `Bash`): report
- * working-tree changes a Bash call made OUTSIDE the wave's `allowedPaths`.
+ * working-tree changes a Bash call made OUTSIDE the wave's `allowedPaths` —
+ * except a path a PEER session declared through a `peer-session-*` record in
+ * the wave's aggregate scope sidecar (#1195), which is named as a peer write.
  *
  * ## Why this hook exists (#915, follow-up to #906 / #800)
  *
@@ -160,7 +162,7 @@ import { findScopeFile, pathMatchesPattern } from '../scripts/lib/hardening.mjs'
 // tests/hooks/post-bash-write-verify.test.mjs, which imports the named export —
 // is unchanged. Two byte-identical copies of a clock is exactly the one-fact-two-
 // copies class this repo keeps paying for.
-import { sessionAgeMs } from '../scripts/lib/scope-gate.mjs';
+import { sessionAgeMs, PEER_RECORD_PREFIX, isPeerRecordId } from '../scripts/lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -322,6 +324,90 @@ export function isInScope(relPath, allowedPaths) {
   return allowedPaths.some((p) => typeof p === 'string' && pathMatchesPattern(relPath, p));
 }
 
+/**
+ * Re-exported for readers of this hook: the prefix that marks an
+ * aggregate-sidecar record as a PEER SESSION's declared scope rather than one
+ * of this wave's own agents (#1195). The DEFINITION lives in
+ * `scripts/lib/scope-gate.mjs`, next to `unionFileScopes`, which must exclude
+ * exactly these records from `allowedPaths` for the peer branch below to be
+ * reachable at all.
+ */
+export { PEER_RECORD_PREFIX };
+
+/**
+ * The peer-session records of a wave's aggregate scope sidecar.
+ *
+ * Shape, as written by `scripts/materialize-wave-scope.mjs`
+ * (`<state-dir>/filescopes/wave-<N>.scopes.json`): ONE JSON array of
+ * `{ id, files }` records — the per-agent files under
+ * `<state-dir>/filescopes/wave-<N>/<id>.json` are path STRINGS and are a
+ * different artefact (see `docs/scope-collision-guard.md` § 2.2). Only records
+ * whose `id` starts with `peer-session-` are returned: those are paths a peer
+ * session announced and this session's coordinator carried into the manifest
+ * union (`skills/wave-executor/wave-loop.md` § Scope Manifest).
+ *
+ * Absent, unreadable or malformed sidecar ⇒ `[]`, which restores the exact
+ * pre-#1195 behaviour. Never throws.
+ *
+ * @param {string} stateDir absolute path of the harness state dir (the
+ *   directory holding `wave-scope.json`)
+ * @param {unknown} wave the manifest's `wave` field
+ * @returns {Array<{ id: string, files: string[] }>}
+ */
+export function readPeerScopeRecords(stateDir, wave) {
+  if (typeof stateDir !== 'string' || stateDir === '') return [];
+  if (typeof wave !== 'number' || !Number.isInteger(wave) || wave <= 0) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(
+      readFileSync(path.join(stateDir, 'filescopes', `wave-${wave}.scopes.json`), 'utf8'),
+    );
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .filter(
+      (r) => r && typeof r === 'object'
+        && isPeerRecordId(r.id)
+        && Array.isArray(r.files),
+    )
+    .map((r) => ({ id: r.id, files: r.files.filter((f) => typeof f === 'string') }));
+}
+
+/**
+ * Which peer record — if any — declared this path?
+ *
+ * Same matcher as `isInScope`, so a peer's declaration is read exactly the way
+ * the wave's own `allowedPaths` are.
+ *
+ * @param {string} relPath
+ * @param {Array<{ id: string, files: string[] }>} peerRecords
+ * @returns {string|null} the peer record id, or null
+ */
+export function peerRecordFor(relPath, peerRecords) {
+  if (!Array.isArray(peerRecords)) return null;
+  for (const record of peerRecords) {
+    if (record.files.some((p) => pathMatchesPattern(relPath, p))) return record.id;
+  }
+  return null;
+}
+
+/**
+ * Render the peer-write notice (#1195) — deliberately a NOTICE and not part of
+ * the violation report: a peer record is EXCLUDED from the union that computes
+ * `allowedPaths` (`unionFileScopes`, `scripts/lib/scope-gate.mjs`), so a peer
+ * path is outside `allowedPaths` and reaches this branch; naming it as a
+ * violation would re-file an agreed peer write as an alarm.
+ *
+ * @param {string} relPath
+ * @param {string} peerId the `peer-session-<id>` record id
+ * @returns {string}
+ */
+export function formatPeerWriteNotice(relPath, peerId) {
+  return `bash-write-verify: ${relPath} inside ${peerId} scope — peer write, not a violation`;
+}
+
 /**
  * Stable signature of the wave's scope. A change means a new wave, which must
  * re-baseline silently rather than blame the next Bash call for the previous
@@ -915,8 +1001,22 @@ async function main() {
   // first run is named, not silently trusted. Computed before the G4/G5 gate
   // above so the gate cannot swallow it.
   if (missingSnapshotNotice) messages.push(missingSnapshotNotice);
-  if (report.length > 0) {
-    messages.push(formatMessage(report, allowedPaths.length));
+  // #1195 — a path a PEER session declared (a `peer-session-*` record in this
+  // wave's aggregate sidecar) is outside `allowedPaths` because `--union`
+  // EXCLUDES peer records when computing it (`unionFileScopes`,
+  // `scripts/lib/scope-gate.mjs`) — that exclusion is what keeps this branch
+  // reachable. Such a write is agreed, not a bypass. Split it out of the violation report and
+  // name it, so the peer's file is countable without being an alarm. Sidecar
+  // absent ⇒ `peerRecords` is empty ⇒ every path stays a violation, unchanged.
+  const peerRecords = readPeerScopeRecords(path.dirname(scopePath), scope.wave);
+  const violations = [];
+  for (const relPath of report) {
+    const peerId = peerRecordFor(relPath, peerRecords);
+    if (peerId) messages.push(formatPeerWriteNotice(relPath, peerId));
+    else violations.push(relPath);
+  }
+  if (violations.length > 0) {
+    messages.push(formatMessage(violations, allowedPaths.length));
     warn = true;
   }
   if (messages.length === 0) return; // silence is the common case (0.91 % fire rate)