session-orchestrator 3.23.0 → 4.0.0

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

@@ -29,19 +29,55 @@
  *
  * 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.
+ *
+ * DIFF-SIZE MEASUREMENT (#980). The mechanical fallback below persists
+ * `wave_start_sha` (`git rev-parse HEAD`, best-effort) at every wave-OPEN
+ * transition and attaches `files_changed` + `files_changed_source:
+ * 'worktree-vs-wave-start-sha'` to the `orchestrator.wave.completed` it emits
+ * for the wave that sha opened. `files_changed` counts the DEDUPED union of
+ * `git diff --name-only <wave_start_sha>` (working tree vs the wave's start
+ * commit — the coordinator normally commits only at close, so uncommitted
+ * edits must count) and `git ls-files --others --exclude-standard` (untracked).
+ * Every git call is best-effort with a 1.5 s timeout; any failure, or a missing
+ * `wave_start_sha`, OMITS the key — the convergence-monitor reader treats an
+ * absent key as null and the `shrinking_diff` signal simply does not fire.
+ * `wave_start_sha` is written under the SAME ownership gate as the wave keys.
+ * OUT OF SCOPE: `hooks/on-session-end.mjs`'s final-wave `.completed` carries no
+ * `files_changed` — no wave-open transition runs there, so it has no start sha.
+ *
+ * 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 { execFileSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
 if (!shouldRunHook('post-tool-batch-wave-signal')) process.exit(0);
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } 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
@@ -74,32 +110,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,6 +145,54 @@ async function resolveSessionIdForHeartbeat(input, sessionFile) {
   return null;
 }
 
+/**
+ * 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
@@ -166,6 +224,87 @@ async function resolveWaveNumber(projectDir) {
   }
 }
 
+/**
+ * The only environment variables forwarded to the `git` children below.
+ * Everything else — `GIT_DIR`/`GIT_WORK_TREE`/`GIT_COMMON_DIR` above all — is
+ * dropped, so an ambient redirect cannot make these probes measure a FOREIGN
+ * repository while `cwd` points at this one (`GIT_DIR` outranks `cwd`; that is
+ * exactly the 2026-08-19 redirect incident class).
+ *
+ * Same 6-entry allowlist as `scripts/lib/git-config-drift.mjs:170` and
+ * `check-banner-parity.mjs:63`, COPIED rather than imported on purpose: this is
+ * a live hook, and importing a scripts/lib module for six strings would add an
+ * edge to the hook import graph (`hooks/_lib/hook-import-set.json`) for no
+ * behavioural gain — the constant is cheaper to copy than a shared module is to
+ * maintain (BV-001, the same call git-config-drift.mjs documents).
+ */
+const GIT_ENV_ALLOWLIST = Object.freeze(['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TZ']);
+
+/** @returns {Record<string,string>} the allowlisted subset of `process.env`. */
+function filteredGitEnv() {
+  /** @type {Record<string,string>} */
+  const out = {};
+  for (const key of GIT_ENV_ALLOWLIST) {
+    const value = process.env[key];
+    if (typeof value === 'string') out[key] = value;
+  }
+  return out;
+}
+
+/** Shared spawn options for the best-effort git probes below (#980). */
+const GIT_OPTS = (projectDir) => ({
+  cwd: projectDir,
+  encoding: 'utf8',
+  timeout: 1_500,
+  stdio: ['ignore', 'pipe', 'ignore'],
+  env: filteredGitEnv(),
+});
+
+/**
+ * `git rev-parse HEAD` in `projectDir`, best-effort (#980).
+ * Returns null on ANY failure — not a git repo, detached/empty HEAD, timeout,
+ * git absent. A null is persisted as null so a STALE sha from the previous wave
+ * can never be mistaken for this wave's start point.
+ *
+ * @param {string} projectDir
+ * @returns {string|null}
+ */
+function readHeadSha(projectDir) {
+  try {
+    const out = execFileSync('git', ['rev-parse', 'HEAD'], GIT_OPTS(projectDir)).trim();
+    return /^[0-9a-f]{40}$/i.test(out) ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count the files this wave touched: the DEDUPED union of the working tree's
+ * diff against `sha` and the untracked (non-ignored) files (#980).
+ *
+ * Working-tree-vs-sha rather than `sha..HEAD` on purpose: the coordinator
+ * commits at session close, not per wave, so a commit-only diff reads 0 for
+ * every wave of a normal session.
+ *
+ * @param {string} projectDir
+ * @param {unknown} sha  Persisted `wave_start_sha` (may be null/absent).
+ * @returns {number|null} null when unmeasurable — caller OMITS the key.
+ */
+function countFilesChangedSince(projectDir, sha) {
+  if (typeof sha !== 'string' || !/^[0-9a-f]{40}$/i.test(sha)) return null;
+  try {
+    const opts = GIT_OPTS(projectDir);
+    const tracked = execFileSync('git', ['diff', '--name-only', sha], opts);
+    const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], opts);
+    const paths = new Set(
+      `${tracked}\n${untracked}`.split('\n').map((l) => l.trim()).filter((l) => l.length > 0),
+    );
+    return paths.size;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -206,12 +345,18 @@ async function main() {
     ...(waveSignal !== null ? { wave_signal: waveSignal } : {}),
   };
 
-  const sessionFile = path.join(SO_PROJECT_DIR, '.orchestrator', 'current-session.json');
+  const sessionFile = path.join(getProjectDir(), '.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).
@@ -229,7 +374,7 @@ async function main() {
     const sessionId = await resolveSessionIdForHeartbeat(input, sessionFile);
     if (typeof sessionId === 'string' && sessionId.length > 0) {
       const { updateHeartbeat } = await import('../scripts/lib/session-lock.mjs');
-      updateHeartbeat({ repoRoot: SO_PROJECT_DIR, sessionId });
+      updateHeartbeat({ repoRoot: getProjectDir(), sessionId });
     }
   } catch { /* best effort — hook must remain non-blocking */ }
 
@@ -256,6 +401,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) {
     // ------------------------------------------------------------------
@@ -274,26 +445,55 @@ 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);
+      const wave = await resolveWaveNumber(getProjectDir());
       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;
+        let waveStartSha = null;
         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 */ }
+          // #980 — the sha persisted when THIS `last_wave` was opened.
+          if (typeof parsed.wave_start_sha === 'string') waveStartSha = parsed.wave_start_sha;
+          // #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) {
+            // #980 — measure the closing wave's diff size BEFORE the new wave's
+            // start sha is persisted below. Unmeasurable → both keys omitted.
+            const filesChanged = countFilesChangedSince(getProjectDir(), waveStartSha);
             await emitEvent('orchestrator.wave.completed', {
               wave_number: lastWave,
+              ...(filesChanged !== null
+                ? {
+                  files_changed: filesChanged,
+                  files_changed_source: 'worktree-vs-wave-start-sha',
+                }
+                : {}),
               ...(batchId !== null ? { batch_id: batchId } : {}),
               ...(batchSize !== null ? { batch_size: batchSize } : {}),
             });
@@ -305,11 +505,39 @@ 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)) {
+            // #980 — the OPEN half: stamp the sha this new wave starts from.
+            // Written as null (not omitted) when git is unreadable, so the
+            // PREVIOUS wave's sha can never linger and inflate the next count.
+            const startSha = readHeadSha(getProjectDir());
+            const markResult = await atomicMutateJson(sessionFile, {}, (current) => ({
+              ...current,
+              wave_start_sha: startSha,
+              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,14 +24,14 @@
  * 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';
 // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
 if (!shouldRunHook('post-tool-failure-corrective-context')) process.exit(0);
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } 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
 // ---------------------------------------------------------------------------
@@ -208,16 +179,22 @@ async function main() {
     exit_code: exitCode,
   };
 
-  const sessionFile = path.join(SO_PROJECT_DIR, '.orchestrator', 'current-session.json');
+  const sessionFile = path.join(getProjectDir(), '.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:

package/hooks/post-tooluse-frontend-slop.mjs

@@ -29,7 +29,7 @@ if (!shouldRunHook('frontend-slop-hook')) process.exit(0);
 
 import path from 'node:path';
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { detectFiles, SCANNABLE_EXTS } from '../scripts/lib/frontend-detect/detect.mjs';
 import { loadFrontendSlopHookConfig } from '../scripts/lib/config/frontend-slop-hook.mjs';
@@ -98,7 +98,7 @@ function resolveSessionId(input) {
  */
 function toRelPath(filePath) {
   try {
-    const rel = path.relative(SO_PROJECT_DIR, filePath);
+    const rel = path.relative(getProjectDir(), filePath);
     if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel;
   } catch { /* fall through */ }
   return path.basename(filePath);
@@ -147,7 +147,7 @@ async function main() {
   if (!SCANNABLE_EXTS.has(ext)) return;
 
   // Session Config gate — OPT-IN (default off).
-  const config = await loadFrontendSlopHookConfig({ repoRoot: SO_PROJECT_DIR });
+  const config = await loadFrontendSlopHookConfig({ repoRoot: getProjectDir() });
   if (config.enabled !== true) return;
 
   // Run the deterministic detector (fail-soft: unreadable files → []).

package/hooks/pre-bash-destructive-guard.mjs

@@ -95,6 +95,8 @@ let blocker = null;
 let readConfigFile;
 let loadEffectivePolicy;
 let isSessionConfigHeading;
+let preprocessBlockLinesNoDash;
+let findUnterminatedComment;
 let emitEvent;
 
 /**
@@ -164,6 +166,7 @@ async function bootstrap() {
       config: { specifier: lib('config.mjs') },
       blockedCommandsPolicy: { specifier: lib('blocked-commands-policy.mjs') },
       sectionExtractor: { specifier: lib('config', 'section-extractor.mjs') },
+      blockPreprocess: { specifier: lib('config', 'block-preprocess.mjs') },
       events: { specifier: lib('events.mjs') },
       blocker: {
         specifier: lib('command-blocker.mjs'),
@@ -192,6 +195,7 @@ async function bootstrap() {
   ({ readConfigFile } = modules.config);
   ({ loadEffectivePolicy } = modules.blockedCommandsPolicy);
   ({ isSessionConfigHeading } = modules.sectionExtractor);
+  ({ findUnterminatedComment, preprocessBlockLinesNoDash } = modules.blockPreprocess);
   ({ emitEvent } = modules.events);
   blocker = modules.blocker;
   degradedLabels = degraded;
@@ -760,19 +764,41 @@ async function main() {
     const mdContent = await readConfigFile(projectDir);
     // Look for "allow-destructive-ops: true" in the Session Config block.
     // Simple line-based scan: find lines under ## Session Config, stop at next ##.
-    const lines = mdContent.split(/\r?\n/);
-    let inConfig = false;
-    for (const line of lines) {
-      // SSOT predicate (#968) — never re-derive this comparison. A local copy
-      // that drifts LOOSER than the extractor silently disagrees with the
-      // runtime about where the config block starts.
-      if (isSessionConfigHeading(line)) { inConfig = true; continue; }
-      if (inConfig && /^## /.test(line)) break;
-      if (inConfig) {
-        const m = line.match(/^\s*(?:-\s+\*\*)?allow-destructive-ops(?::\*\*)?\s*:\s*(\S+)/);
-        if (m && m[1].toLowerCase() === 'true') {
-          process.stderr.write('ℹ destructive-guard bypassed\n');
-          return emitAllow();
+    // W4/F1b — HTML-comment stripping is MANDATORY here (same class as #1162a).
+    // With a raw `split(/\r?\n/)` a COMMENTED-OUT
+    // `<!--\nallow-destructive-ops: true\n-->` under `## Session Config` DISABLED
+    // the whole 14-rule guard for the session: commenting a key out is the most
+    // ordinary way to turn it off and must never turn it ON. `NoDash` (not the
+    // full `preprocessBlockLines`) on purpose — bold-subkey normalisation is not
+    // wanted; the regex below already tolerates `- **key:**` and stays as-is.
+    //
+    // UNTERMINATED `<!--` — the fail-closed direction INVERTS for a bypass scan.
+    // `stripHtmlCommentBlocks` returns the lines UNFILTERED when a comment is
+    // never closed (right for a block PARSER, nothing may silently vanish), which
+    // here would hand the commented-out bypass line back and re-arm the guard's
+    // own off switch. For this scan "I cannot tell where the comments end" must
+    // mean NOT ARMED: the bypass is opt-in, so refusing to grant it is the safe
+    // reading of an ambiguous document. Said out loud on stderr, because a
+    // silently-ignored bypass would look identical to a typo the operator meant.
+    if (findUnterminatedComment(mdContent.split(/\r?\n/)) !== null) {
+      process.stderr.write(
+        'ℹ destructive-guard: unterminated <!-- in CLAUDE.md — bypass ignored\n'
+      );
+    } else {
+      const lines = preprocessBlockLinesNoDash(mdContent);
+      let inConfig = false;
+      for (const line of lines) {
+        // SSOT predicate (#968) — never re-derive this comparison. A local copy
+        // that drifts LOOSER than the extractor silently disagrees with the
+        // runtime about where the config block starts.
+        if (isSessionConfigHeading(line)) { inConfig = true; continue; }
+        if (inConfig && /^## /.test(line)) break;
+        if (inConfig) {
+          const m = line.match(/^\s*(?:-\s+\*\*)?allow-destructive-ops(?::\*\*)?\s*:\s*(\S+)/);
+          if (m && m[1].toLowerCase() === 'true') {
+            process.stderr.write('ℹ destructive-guard bypassed\n');
+            return emitAllow();
+          }
         }
       }
     }

package/hooks/pre-bash-memory-propose-audit.mjs

@@ -185,13 +185,19 @@ async function main() {
 
   // G7 — emit canonical event via emitEvent (single emission path: schema + webhook,
   // replacing the local hand-rolled appendFileSync bypass).
-  await emitEvent('orchestrator.memory.propose_invoked', {
-    session_id: sessionId,
-    wave,
-    argv_truncated: argvRedacted.slice(0, 512),
-    cwd: process.cwd(),
-    exit_code: null,
-  });
+  // #1183 — a malformed record throws EventValidationError BEFORE any side
+  // effect (scripts/lib/events.mjs); this PreToolUse hook must never abort on
+  // that (it is deny-capable via emitAllow() below), so the emit is wrapped
+  // rather than left to propagate.
+  try {
+    await emitEvent('orchestrator.memory.propose_invoked', {
+      session_id: sessionId,
+      wave,
+      argv_truncated: argvRedacted.slice(0, 512),
+      cwd: process.cwd(),
+      exit_code: null,
+    });
+  } catch { /* telemetry never blocks the hook (#1183) */ }
 
   // Always allow — this is an observe-only audit hook
   return emitAllow();