session-orchestrator 3.22.0 → 3.24.0

package/hooks/post-subagent-discovery-validator.mjs

@@ -11,9 +11,13 @@
  *   1. shouldRunHook('post-subagent-discovery-validator') gate — exit 0 when disabled.
  *   2. Read JSON payload from stdin; require hook_event_name === 'SubagentStop'.
  *   3. Read `discovery-validator.enabled` from CLAUDE.md/AGENTS.md Session Config.
- *      Default OFF — exit 0 immediately unless explicitly enabled.
- *   4. Read `input.transcript_path` (whole-session JSONL of assistant/user records),
- *      scan the TAIL (last ~8 `type:"assistant"` records), concat text blocks.
+ *      Default OFF (opt-in) — exit 0 immediately unless explicitly enabled.
+ *   4. Resolve the STOPPING SUBAGENT's OWN transcript (never the parent):
+ *      `input.agent_transcript_path` when the harness sends it, else
+ *      `<dir(transcript_path)>/<base>/subagents/agent-<agent_id>.jsonl`. Scan its
+ *      TAIL (last ~8 `type:"assistant"` records), concat text blocks. When no
+ *      `agent_id` is derivable (or the file is absent) the hook exits 0 and
+ *      records NOTHING — see the scope note below.
  *   5. Regex-scan the concatenated text for 8 claim patterns — 6 quantifier-
  *      triggered distributional claims, the #908 bare-cardinal repo-state
  *      fact ("14 commits", "92 learnings", "5 dirty files", "412 lines"), and
@@ -27,8 +31,32 @@
  *      date, `HEAD`, "as of", "measured at"). Undated-but-verified claims are
  *      counted and reported in the warn text — they are NOT violations in v1.
  *
- * Why read the transcript: the SubagentStop stdin payload has NO output_text
- * field. The agent's text lives in `input.transcript_path`.
+ * Why read a transcript at all: the SubagentStop stdin payload has NO
+ * output_text field — the agent's text only exists on disk.
+ *
+ * WHICH transcript (#1191, the root cause behind the fleet false-positive
+ * flood): `input.transcript_path` is the PARENT/MAIN session transcript, not
+ * the subagent's. Scanning it flagged the COORDINATOR's own prose — wave plans,
+ * TL;DRs, complexity scores. Measured 2026-09-02 on a seeded random sample of
+ * 60 violations: 100% coordinator text, scope-adjusted precision 0%, and
+ * `agent` was `"unknown"` in 90.8% of 1,541 vault events. The hook therefore
+ * reads `<transcriptDir>/<session>/subagents/agent-<agent_id>.jsonl` (the same
+ * layout `hooks/subagent-telemetry.mjs` and `scripts/lib/wave-transcript-tail.mjs`
+ * read) and NEVER falls back to the parent path: a scan of the wrong transcript
+ * is worse than no scan.
+ *
+ * Output channels — THREE writes, TWO different recipients:
+ *   - `discovery_validator_violation` in .orchestrator/metrics/events.jsonl,
+ *     and the stderr WARN → the COORDINATOR's only copy of the finding. PSA-006
+ *     makes REJECTING the unverified claim his duty, so these two are the
+ *     channels that carry the rule's enforcement path.
+ *   - stdout `hookSpecificOutput.additionalContext` → the STOPPING SUBAGENT
+ *     (which continues and may self-correct), NOT the coordinator — a hook is
+ *     structurally unable to address him. See the measured delivery note at the
+ *     hookSpecificOutput write below for the shipped-binary evidence.
+ *   All three are pinned together by the "all three channels fire" test in
+ *   tests/hooks/post-subagent-discovery-validator.test.mjs — do not collapse
+ *   the coordinator-visible pair into additionalContext.
  *
  * Exit codes: 0 always (informational, never blocking).
  */
@@ -42,6 +70,7 @@ import { promises as fs } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
+import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 import { appendJsonl } from '../scripts/lib/common.mjs';
 import { eventsFilePath } from '../scripts/lib/events.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
@@ -213,6 +242,27 @@ const CARDINAL_RATIO_PATTERN = new RegExp(
 /** Inline-code spans are masked before the cardinal pattern runs. */
 const INLINE_CODE_RE = /`[^`\n]*`/g;
 
+/**
+ * Gate-summary / STATUS-report lines are the HARNESS's own completion output —
+ * tool evidence, not an unverified assertion about the codebase — yet carried
+ * no exemption of their own: they were caught only incidentally, by whichever
+ * individual claim pattern happened not to fire on that exact phrasing. GitLab
+ * #1198 (Discovery D8, 2026-09-02): a 400-event sample of
+ * `discovery_validator_violation` records showed 186/400 (46.5%) firing on
+ * this exact class — the single largest false-positive source measured to
+ * date. Skipped at the LINE level, before ANY pattern runs, rather than by
+ * narrowing `CARDINAL_NOUN`: narrowing the noun set would ALSO silence a true
+ * "N files" claim appearing outside a gate-summary line, which is not this
+ * bug's fix.
+ *
+ * Four alternatives cover the measured shapes: an N-passed/M-failed count
+ * ("14904 passed / 0 failed"), a `STATUS:` report line (`skills/wave-executor`
+ * agent-report convention), a "Full Gate" heading, and a `Gate: <verdict>`
+ * summary line (English "typecheck" or German "grün"/"rot").
+ */
+const GATE_SUMMARY_LINE_RE =
+  /\b\d+\s+passed\s*\/\s*\d+\s+failed\b|^\s*STATUS:\s*(?:done|partial|failed)\b|\bFull Gate\b|\bGate:\s*(?:typecheck|grün|rot)\b/i;
+
 /**
  * Commands that count as a MEASUREMENT inside a fenced block. `grep|rg|find`
  * (the #567 set) only covers text search; the #908 facts are measured with
@@ -450,9 +500,18 @@ function findViolations(text) {
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    let matched = CLAIM_PATTERNS.some((re) => re.test(line));
+    // #1198 FIX 2: gate-summary/STATUS lines are tool OUTPUT, not a claim —
+    // skipped before any pattern runs (see GATE_SUMMARY_LINE_RE header).
+    if (GATE_SUMMARY_LINE_RE.test(line)) continue;
+
+    // #1198 FIX 3 (masking-order bug): mask inline-code spans ONCE, then test
+    // BOTH the six CLAIM_PATTERNS and the cardinal/ratio patterns against the
+    // masked text. Previously only the cardinal branch masked — a claim
+    // quoted entirely inside backticks (evidence/example text, not an
+    // assertion) still tripped CLAIM_PATTERNS via the raw, unmasked line.
+    const masked = line.replace(INLINE_CODE_RE, ' ');
+    let matched = CLAIM_PATTERNS.some((re) => re.test(masked));
     if (!matched && !fencedLines.has(i)) {
-      const masked = line.replace(INLINE_CODE_RE, ' ');
       matched = CARDINAL_PATTERN.test(masked) || CARDINAL_RATIO_PATTERN.test(masked);
     }
     if (!matched) continue;
@@ -490,6 +549,58 @@ function firstNonEmptyString(input, keys, fallback) {
   return fallback;
 }
 
+/**
+ * Resolve the STOPPING SUBAGENT's own sidecar pair (#1191, #1196).
+ *
+ * Thin wrapper over the consolidated derivation —
+ * `hooks/_lib/subagent-paths.mjs` `resolveSubagentSidecar()` — which now ALSO
+ * containment-checks the `agent_transcript_path` override this file used to
+ * return unvalidated (see that module's header divergence table). Returns
+ * null when the derivation is impossible — the caller must then scan
+ * NOTHING. Falling back to `input.transcript_path` is the defect this
+ * function exists to remove: that path is the coordinator's transcript.
+ *
+ * @param {object} input — SubagentStop stdin payload
+ * @param {string|null} agentId
+ * @returns {{base: string, transcript: string, meta: string}|null}
+ */
+function resolveAgentTranscriptPath(input, agentId) {
+  const agentTranscriptPath = firstNonEmptyString(input, ['agent_transcript_path'], null);
+  return resolveSubagentSidecar({ transcriptPath: input.transcript_path, agentId, agentTranscriptPath });
+}
+
+/**
+ * Agent types carry a plugin qualifier, so the COLON is part of the real shape:
+ * `session-orchestrator:code-implementer` (37 chars, measured on-disk in a real
+ * sidecar meta.json 2026-09-02). Same constant as `AGENT_TYPE_META_RE` in
+ * hooks/on-stop.mjs — kept local because the two hooks share no module.
+ */
+const AGENT_TYPE_META_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+/**
+ * Read the agent TYPE from the sidecar `agent-<id>.meta.json` the harness writes
+ * next to the subagent transcript. Used only when the stdin payload omits
+ * `agent_type` — the reason `agent` read `"unknown"` on ~91% of events.
+ *
+ * @param {string} metaPath — `resolveSubagentSidecar(...).meta`
+ * @returns {Promise<string|null>}
+ */
+async function readAgentTypeFromMeta(metaPath) {
+  try {
+    const meta = JSON.parse(await fs.readFile(metaPath, 'utf8'));
+    const t = meta?.agentType;
+    if (typeof t !== 'string' || !t.trim()) return null;
+    // Clamped with the same shape hooks/on-stop.mjs applies to `agentType`
+    // (colon included — `session-orchestrator:code-implementer` is the real
+    // shape). This value reaches BOTH the ledger event and the model-visible
+    // `additionalContext` string, so a mismatch is OMITTED rather than
+    // truncated: the caller then falls back to the honest `'unknown'`.
+    return AGENT_TYPE_META_RE.test(t.trim()) ? t.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Sanitize a user/runtime-provided string for use in a tmp sentinel filename.
  *
@@ -511,23 +622,38 @@ function projectRootHash(projectRoot) {
 }
 
 /**
- * Build the dedup sentinel path for real project/session/agent contexts.
+ * Build the dedup sentinel path for real project/session/agent/claim contexts.
  * Missing fallback IDs intentionally return null so unrelated hooks/tests do
  * not collide on a global "unknown" key.
  *
+ * #1198 FIX 1: the key used to be `(projectRoot, sessionId, agent_type)` —
+ * `agent_type` is a CLASS ("discovery"), not an individual agent, so two
+ * DIFFERENT real subagents of the same type running in the same session
+ * collided on the same sentinel: the second agent's own `additionalContext`
+ * feedback was silently suppressed even though it never received a copy of
+ * the first agent's warning. Keying on `agentId` (the harness's per-process
+ * `agent_id`/`subagent_id`) instead removes that cross-agent collision. The
+ * claim-text hash is ADDITIVE: it lets a genuinely SECOND, DISTINCT claim
+ * from the same real agent still surface its own suppression check, rather
+ * than being silenced merely because that agent already triggered once for a
+ * different claim.
+ *
  * @param {object} opts
  * @param {string} opts.projectRoot
  * @param {string|null} opts.sessionId
- * @param {string|null} opts.agent
+ * @param {string|null} opts.agentId
+ * @param {string|null} opts.claimText
  * @returns {string|null}
  */
-function dedupSentinelPath({ projectRoot, sessionId, agent }) {
+function dedupSentinelPath({ projectRoot, sessionId, agentId, claimText }) {
   if (typeof sessionId !== 'string' || !sessionId.trim()) return null;
-  if (typeof agent !== 'string' || !agent.trim()) return null;
+  if (typeof agentId !== 'string' || !agentId.trim()) return null;
+  if (typeof claimText !== 'string' || !claimText.trim()) return null;
 
+  const claimHash = createHash('sha256').update(claimText).digest('hex').slice(0, 16);
   return path.join(
     tmpdir(),
-    `psa006-${projectRootHash(projectRoot)}-${safeSentinelComponent(sessionId)}-${safeSentinelComponent(agent)}.lock`
+    `psa006-${projectRootHash(projectRoot)}-${safeSentinelComponent(sessionId)}-${safeSentinelComponent(agentId)}-${claimHash}.lock`
   );
 }
 
@@ -542,11 +668,19 @@ async function main() {
 
   if (!(await isEnabled())) return;
 
-  const text = await readTranscriptTail(input.transcript_path);
+  // #1191: scan the SUBAGENT's own transcript, never the parent. No agent_id
+  // (or no derivable path) → scan nothing and record nothing.
+  const agentId = firstNonEmptyString(input, ['agent_id', 'subagent_id'], null);
+  const sidecar = resolveAgentTranscriptPath(input, agentId);
+  if (sidecar === null) return;
+
+  const text = await readTranscriptTail(sidecar.transcript);
   const { violations, undatedVerified } = findViolations(text);
   if (violations.length === 0) return;
 
-  const agentForDedup = firstNonEmptyString(input, ['agent_type'], null);
+  const agentForDedup =
+    firstNonEmptyString(input, ['agent_type', 'subagent_type'], null) ??
+    (await readAgentTypeFromMeta(sidecar.meta));
   const agent = agentForDedup ?? 'unknown';
   // session_id precedence: parent_session_id first, mirroring the sibling hook
   // hooks/subagent-telemetry.mjs (firstNonEmptyString(['parent_session_id',
@@ -554,10 +688,18 @@ async function main() {
   // parent_session_id` order disagreed with telemetry and could log the wrong id.
   const sessionId = firstNonEmptyString(input, ['parent_session_id', 'session_id'], null);
 
-  // Project/session/agent deduplication: only emit additionalContext once for
-  // repeated real contexts. Missing session IDs never create/read a sentinel,
-  // so fallback traffic still surfaces warnings and cannot collide globally.
-  const sentinel = dedupSentinelPath({ projectRoot: SO_PROJECT_DIR, sessionId, agent: agentForDedup });
+  // Project/session/agent/claim deduplication: only emit additionalContext
+  // once for repeated real contexts. Missing session IDs never create/read a
+  // sentinel, so fallback traffic still surfaces warnings and cannot collide
+  // globally. Keyed on agentId (not agent TYPE, #1198 FIX 1) plus the first
+  // violation's claim text so distinct real agents and distinct claims never
+  // share a sentinel.
+  const sentinel = dedupSentinelPath({
+    projectRoot: SO_PROJECT_DIR,
+    sessionId,
+    agentId,
+    claimText: violations[0],
+  });
 
   const filePath = eventsFilePath();
   for (const claim of violations) {
@@ -565,6 +707,7 @@ async function main() {
       event: 'discovery_validator_violation',
       timestamp: new Date().toISOString(),
       agent,
+      ...(agentId !== null ? { agent_id: agentId } : {}),
       ...(sessionId !== null ? { session_id: sessionId } : {}),
       claim_text: claim,
     });
@@ -594,12 +737,30 @@ async function main() {
   }
 
   if (alreadyWarned) {
-    // Events logged above; suppress additionalContext to prevent coordinator loop.
+    // Events logged above; suppress the repeat additionalContext for this
+    // already-warned real context. (Recipient is the stopping subagent, not the
+    // coordinator — see the delivery note at the hookSpecificOutput write below.)
     return;
   }
 
-  // v2.1.163+ additionalContext: feed the warning back to the coordinator turn
-  // so the finding is visible inline, not just in stderr + events.jsonl.
+  // v2.1.163+ additionalContext: surface the finding inline, not just in
+  // stderr + events.jsonl.
+  //
+  // The recipient is the SUBAGENT that just stopped — NOT the coordinator.
+  // Measured in the shipped binary (Claude Code 2.1.241, 2026-08-23): the
+  // SubagentStop hookSpecificOutput schema reads "additionalContext is
+  // non-error feedback delivered to the subagent; the subagent continues so it
+  // can act on it", and the emitter picks its target with
+  // `i.agentId ? "SubagentStop" : "Stop"`, yielding a `hook_additional_context`
+  // message into that agent's own loop. So this text lands in the transcript of
+  // the agent whose claims it is about, one moment after that agent is done.
+  //
+  // Worth knowing before "fixing" the path: PSA-006 asks the COORDINATOR to
+  // reject unverified distributional claims, and this channel never reaches
+  // him. His copy of the finding is events.jsonl + stderr, not this write.
+  // Whether he SHOULD receive it is a product question (#1116) — changing the
+  // route is not a comment edit.
+  //
   // Non-blocking — exit 0 always. Decision:"block" must never be set here.
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: {

package/hooks/post-tool-batch-wave-signal.mjs

@@ -29,10 +29,29 @@
  *
  * Exit codes: 0 always (informational, never blocking).
  *
+ * OWNERSHIP RULE for the wave keys (#1193 W4c Q1-MED). `.orchestrator/` is
+ * repo-global, so `current-session.json` describes whichever session most
+ * recently ran SessionStart — routinely a DIFFERENT, still-live session when
+ * two windows share this working copy. `last_wave` and `last_wave_completed`
+ * are therefore written ONLY when this batch's RAW stdin `session_id` equals
+ * the file's `session_id` (a file without one is legacy and allowed). Writing
+ * them unguarded was reproduced both ways with the real hook binaries: session
+ * A's batch stamped `last_wave_completed` into B's record, so B's own attested
+ * SessionEnd stayed silent (the #1193 gap preserved on B), and A's `last_wave`
+ * landed in B's record, so B's SessionEnd emitted `wave.completed` for A's wave
+ * under B's identity. `last_batch` stays UNGATED — it is a batch-resolution
+ * breadcrumb, not a claim about whose wave lifecycle this is.
+ *
+ * MONOTONICITY RULE (#1193 W4c Q3-MED-3). Three writers touch
+ * `last_wave_completed` (this hook's explicit branch, this hook's fallback,
+ * `hooks/on-session-end.mjs`). Every one of them writes through `maxWave()`,
+ * so the mark can only ever rise — an explicit `wave-complete{5}` arriving
+ * while `last_wave` is 4 must not be walked BACKWARDS to 4 by a later writer.
+ *
  * hooks.json wiring is managed separately (W3-C4 scope).
  */
 
-import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
@@ -41,6 +60,8 @@ if (!shouldRunHook('post-tool-batch-wave-signal')) process.exit(0);
 
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
+import { findScopeFile } from '../scripts/lib/scope-gate.mjs';
+import { atomicMutateJson } from './_lib/atomic-json.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -73,32 +94,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-ptb-${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);
-}
-
 /**
  * Resolve the session-id for the heartbeat refresh.
  * Precedence:
@@ -135,17 +130,73 @@ async function resolveSessionIdForHeartbeat(input, sessionFile) {
 }
 
 /**
- * Resolve the current wave number from .claude/wave-scope.json `.wave`.
+ * Monotone high-water helper — see the MONOTONICITY RULE in the module
+ * docblock. A non-integer `existing` (absent, `null`, or the string `'3'` a
+ * hand-edited file can carry) counts as ABSENT, never as a competing value.
+ *
+ * @param {unknown} existing
+ * @param {number} n
+ * @returns {number}
+ */
+function maxWave(existing, n) {
+  return Number.isInteger(existing) && existing > n ? existing : n;
+}
+
+/**
+ * Does THIS batch own `.orchestrator/current-session.json`?
+ * See the OWNERSHIP RULE in the module docblock for why the wave keys need it.
+ *
+ * Decided on the RAW stdin id only — deliberately NOT via
+ * `resolveSessionIdForHeartbeat()`, whose current-session.json fallback would
+ * make the compare self-fulfilling (the same F-A defect fixed in
+ * `hooks/on-session-end.mjs`: an assertion may never be derived from the value
+ * it asserts about). A file carrying no `session_id` is a legacy/pre-#587
+ * record with no owner to contend with → allowed.
+ *
+ * @param {object|null} input      Parsed stdin payload.
+ * @param {string} sessionFile     Absolute path to current-session.json.
+ * @returns {Promise<boolean>}
+ */
+async function ownsSessionFile(input, sessionFile) {
+  let rawStdinId = null;
+  if (typeof input?.session_id === 'string' && input.session_id.length > 0) {
+    rawStdinId = input.session_id;
+  } else if (typeof input?.sessionId === 'string' && input.sessionId.length > 0) {
+    rawStdinId = input.sessionId;
+  }
+
+  let recordedId = null;
+  try {
+    const parsed = JSON.parse(await readFile(sessionFile, 'utf8'));
+    if (typeof parsed?.session_id === 'string' && parsed.session_id.length > 0) {
+      recordedId = parsed.session_id;
+    }
+  } catch { /* absent or unparseable → no recorded owner */ }
+
+  if (recordedId === null) return true;
+  return rawStdinId !== null && rawStdinId === recordedId;
+}
+
+/**
+ * Resolve the current wave number from the wave-scope manifest's `.wave`.
  * Returns 0 when the file is absent or unparseable, mirroring the
  * pre-bash-memory-propose-audit.mjs G5 precedent ("wave defaults to 0 when
  * wave-scope.json absent"). The file is deleted mid-session at Quality phase
  * transitions and final cleanup, so absence is an expected, non-error state.
  *
+ * The manifest is located via `findScopeFile()` (#1082), the same precedence
+ * every other consumer uses — `.pi` > `.cursor` > `.codex` > `.claude`. The
+ * previous hard-coded `.claude/` path made this hook's whole wave-lifecycle
+ * fallback structurally dead on Codex CLI, Cursor and pi: the manifest exists,
+ * it just is not under `.claude/`, so every batch read 0 and no
+ * `orchestrator.wave.started`/`completed` event was ever emitted there.
+ *
  * @param {string} projectDir
  * @returns {Promise<number>}
  */
 async function resolveWaveNumber(projectDir) {
-  const waveFile = path.join(projectDir, '.claude', 'wave-scope.json');
+  const waveFile = findScopeFile(projectDir);
+  if (waveFile === null) return 0;
   try {
     const raw = await readFile(waveFile, 'utf8');
     const data = JSON.parse(raw);
@@ -199,10 +250,16 @@ async function main() {
 
   const sessionFile = path.join(SO_PROJECT_DIR, '.orchestrator', 'current-session.json');
 
-  await atomicMutateJson(sessionFile, {}, (current) => ({
+  const lastBatchResult = await atomicMutateJson(sessionFile, {}, (current) => ({
     ...current,
     last_batch: lastBatch,
-  }));
+  }), 'ptb');
+  // Non-ENOENT failure only drops this turn's last_batch signal — the
+  // heartbeat refresh and wave-lifecycle logic below are independent and
+  // must still run (a throw here would silently skip both).
+  if (!lastBatchResult.ok) {
+    console.error(`post-tool-batch-wave-signal: last_batch write skipped (${lastBatchResult.reason})`);
+  }
 
   // ----------------------------------------------------------------------
   // Heartbeat refresh (Epic #583 W3-P3, wires W2-I3 OQ2).
@@ -247,6 +304,32 @@ async function main() {
           ...(batchSize !== null ? { batch_size: batchSize } : {}),
         },
       );
+      // #1193 review F2 — this branch is a SECOND emitter of
+      // `wave.completed`, so it must feed the same high-water mark the other
+      // two read; otherwise SessionEnd (and the fallback below) would close the
+      // very wave this signal just closed. Only a numbered completion can be
+      // recorded — an unnumbered signal marks nothing.
+      //
+      // W4c Q2-F1 — this branch also advances `last_wave`. Without it an
+      // explicit `wave-complete{5}` left the marker AHEAD of `last_wave: 4`,
+      // and SessionEnd then read `4 !== 5`, emitted a duplicate completed(4)
+      // and walked the marker BACKWARDS to 4. Both keys go through maxWave().
+      // W4c Q1-MED — and neither is written into a PEER's record.
+      if (
+        waveSignal === 'wave-complete'
+        && typeof waveNumber === 'number'
+        && waveNumber > 0
+        && await ownsSessionFile(input, sessionFile)
+      ) {
+        const waveResult = await atomicMutateJson(sessionFile, {}, (current) => ({
+          ...current,
+          last_wave: maxWave(current?.last_wave, waveNumber),
+          last_wave_completed: maxWave(current?.last_wave_completed, waveNumber),
+        }), 'ptb');
+        if (!waveResult.ok) {
+          console.error(`post-tool-batch-wave-signal: last_wave write skipped (${waveResult.reason})`);
+        }
+      }
     } catch { /* best-effort — hook must remain non-blocking */ }
   } else if (waveSignal === null) {
     // ------------------------------------------------------------------
@@ -265,24 +348,41 @@ async function main() {
     // those windows — a drop to 0 (or any non-increase) is NOT a wave change
     // and is ignored, preventing spurious emissions on every batch.
     //
-    // Final-wave limitation: the LAST wave never receives a `completed` event
-    // here because there is no N+1 transition to trigger it. The coordinator
-    // emits the final orchestrator.wave.completed at session close.
+    // Final wave (#1193): no N+1 transition exists for the LAST wave, so its
+    // `completed` is emitted by `hooks/on-session-end.mjs` at SessionEnd, not
+    // here — and not by the coordinator, which never did (the prose claim this
+    // comment used to make was false from #612 until #1193, costing exactly one
+    // missing completion per wave run fleet-wide). The two emitters are made
+    // idempotent by the `last_wave_completed` high-water mark persisted below:
+    // when an N+1 transition already closed wave N, SessionEnd sees
+    // last_wave_completed === last_wave and stays silent.
     try {
       const wave = await resolveWaveNumber(SO_PROJECT_DIR);
       if (wave > 0) {
         // Read last_wave from the just-written session file (after the
         // last_batch RMW above, so we observe the latest persisted value).
         let lastWave = 0;
+        let lastWaveCompleted = 0;
         try {
           const raw = await readFile(sessionFile, 'utf8');
           const parsed = JSON.parse(raw);
           if (typeof parsed.last_wave === 'number') lastWave = parsed.last_wave;
-        } catch { /* absent/unparseable → lastWave stays 0 */ }
+          // #1193 review F2 — read in the SAME read as `last_wave`: a `/clear`
+          // mid-wave already emitted `completed(lastWave)` via SessionEnd, and
+          // `on-session-start.mjs` preserves that marker across the restart, so
+          // guarding on `wave > lastWave` alone would emit it a second time.
+          if (Number.isInteger(parsed.last_wave_completed)) {
+            lastWaveCompleted = parsed.last_wave_completed;
+          }
+        } catch { /* absent/unparseable → both stay 0 */ }
 
         if (wave > lastWave) {
-          // Close the prior wave first (only when there was one).
-          if (lastWave > 0) {
+          // Close the prior wave first — unless it was already closed. The
+          // compare is `>` and not `!==` (W4c Q3-MED-3): a marker AHEAD of
+          // `last_wave` (an explicit wave-complete for a higher wave) means the
+          // prior wave is already closed too, and a non-integer marker counts
+          // as absent rather than as "different".
+          if (lastWave > lastWaveCompleted) {
             await emitEvent('orchestrator.wave.completed', {
               wave_number: lastWave,
               ...(batchId !== null ? { batch_id: batchId } : {}),
@@ -296,11 +396,34 @@ async function main() {
             ...(batchId !== null ? { batch_id: batchId } : {}),
             ...(batchSize !== null ? { batch_size: batchSize } : {}),
           });
-          // Persist the high-water mark so the next batch does not re-emit.
-          await atomicMutateJson(sessionFile, {}, (current) => ({
-            ...current,
-            last_wave: wave,
-          }));
+          // Persist the high-water marks so the next batch does not re-emit,
+          // and so SessionEnd can tell whether the prior wave was already
+          // closed here (#1193). `last_wave_completed` is only advanced when a
+          // `completed` was actually emitted above (lastWave > 0).
+          // W4c Q1-MED — never stamp these into a PEER session's record. The
+          // events above are still emitted (they carry THIS session's
+          // attribution via emitEvent); only the shared-file claim is withheld.
+          // NAMED CEILING: for a non-owning session the marks therefore never
+          // advance, so this branch re-emits started{wave} once per batch until
+          // that session's own SessionStart takes over the file. Revisit if the
+          // ledger shows repeated started{N} for one wave in a shared checkout.
+          if (await ownsSessionFile(input, sessionFile)) {
+            const markResult = await atomicMutateJson(sessionFile, {}, (current) => ({
+              ...current,
+              last_wave: maxWave(current?.last_wave, wave),
+              ...(Math.max(lastWave, lastWaveCompleted) > 0
+                ? {
+                  last_wave_completed: maxWave(
+                    current?.last_wave_completed,
+                    Math.max(lastWave, lastWaveCompleted),
+                  ),
+                }
+                : {}),
+            }), 'ptb');
+            if (!markResult.ok) {
+              console.error(`post-tool-batch-wave-signal: last_wave mark skipped (${markResult.reason})`);
+            }
+          }
         }
       }
     } catch { /* best-effort — hook must remain non-blocking */ }

package/hooks/post-tool-failure-corrective-context.mjs

@@ -24,7 +24,6 @@
  * hooks.json wiring is managed separately (W3-C4 scope).
  */
 
-import { readFile, writeFile, mkdir, rename } 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('post-tool-failure-corrective-context')) process.exit(0);
 
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { atomicMutateJson } from './_lib/atomic-json.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -74,35 +74,6 @@ function readStdinJson() {
   });
 }
 
-/**
- * Atomic read-modify-write of a JSON file.
- * Reads the existing file (or starts with `defaultValue` when absent),
- * applies `mutate`, writes to a tmp file, renames over the original.
- *
- * @param {string} filePath
- * @param {object} defaultValue — used when the file does not exist
- * @param {function(object): object} mutate — 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-ptf-${process.pid}-${Date.now()}`;
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(tmp, JSON.stringify(updated, null, 2) + '\n', 'utf8');
-
-  // Rename is atomic on POSIX (same-filesystem). On Windows this is best-effort
-  // via the fs.rename syscall (may fail if target is locked — swallowed by
-  // the catch in main()).
-  await rename(tmp, filePath);
-}
-
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -210,14 +181,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.corrective_context)
       ? current.corrective_context
       : [];
     // Append the new note and cap at MAX_ENTRIES (keep most-recent).
     const updated = [...existing, note].slice(-MAX_ENTRIES);
     return { ...current, corrective_context: updated };
-  });
+  }, 'ptf');
+  // additionalContext below is derived from `note` in-memory, independent of
+  // whether the write landed — a non-ENOENT read/parse failure only means
+  // this turn's note is not persisted to current-session.json.
+  if (!result.ok) {
+    console.error(`post-tool-failure-corrective-context: atomicMutateJson skipped write (${result.reason})`);
+  }
 
   // Surface corrective context to Claude via additionalContext on the next turn.
   // PostToolUseFailure hookSpecificOutput shape per CC docs: