session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/orphan-reaper.mjs

@@ -0,0 +1,316 @@
+/**
+ * orphan-reaper.mjs — Teil B of Epic #1425: the NET under the process-group kill.
+ *
+ * Teil A (`process-group.mjs`) prevents orphans at the source. This module finds
+ * the ones that happen anyway — a session that crashed, a harness SIGKILL, a
+ * leak from a foreign repo on the same host — and reaps them.
+ *
+ * The 2026-09-20 incident this exists for: four orphaned `tsgo --noEmit`
+ * processes, two at PPID 1, 86-588% CPU and up to 8.0 GB RSS each; the Mac at
+ * 13% free memory, load 67.4. The existing detector
+ * (`countZombieProcesses`, `resource-probe/parsers.mjs`) would have counted ZERO:
+ * its `ps` carries no `ppid` and no `rss`, its name filter knows only
+ * `claude`/`node`, and it defines a zombie as IDLE (`cpu <= 1.0`) — the exact
+ * opposite of a runaway.
+ *
+ * ## Shape: pure decision, impure execution
+ *
+ *   ps text → `parsePsSnapshot` → `decideReapCandidates` (PURE)
+ *           → targeted ps + identity re-check BEFORE EVERY SIGNAL
+ *           → `deps.killProcessGroup` → wait → re-measure (IMPURE)
+ *
+ * ## Layout (#1437)
+ *
+ * This file is the stable entry: the public re-exports below plus the CLI the
+ * trigger hooks spawn. The implementation lives in `orphan-reaper/`:
+ *
+ *   defaults.mjs       `REAPER_DEFAULTS` + the repo-path join (node:path only)
+ *   scan-throttle.mjs  B4 throttle marker — the trigger hooks import THIS
+ *   ps-snapshot.mjs    the binding `ps` format, its parser and runners
+ *   reaper-decide.mjs  the PURE candidate decision and its identity checks
+ *   reaper-audit.mjs   B5 audit record, writer, bounded reader, pruner, HR-101 rate
+ *   scan.mjs           `runOrphanScan` + its `resolveDeps` adapter
+ *
+ * Explicit named re-exports, never `export *`: a star barrel hides which module
+ * a name comes from, and the import census reads it as no reference at all.
+ */
+
+import { isMainModule } from './is-main-module.mjs';
+import { REAPER_DEFAULTS } from './orphan-reaper/defaults.mjs';
+import { runOrphanScan } from './orphan-reaper/scan.mjs';
+
+export { REAPER_DEFAULTS } from './orphan-reaper/defaults.mjs';
+export {
+  SCAN_MARKER_RELPATH,
+  scanMarkerPath,
+  shouldScanNow,
+  touchScanMarker,
+} from './orphan-reaper/scan-throttle.mjs';
+export {
+  PS_ARGS,
+  parsePsSnapshot,
+  parsePsSnapshotDetailed,
+  psPidArgs,
+} from './orphan-reaper/ps-snapshot.mjs';
+export {
+  READ_ONLY_COMMAND_PATTERNS,
+  decideReapCandidates,
+  isReadOnlyCommand,
+  verifyGroupMemberIdentity,
+} from './orphan-reaper/reaper-decide.mjs';
+export {
+  FALSE_ALARM_SUSPECT_RATE,
+  REAPER_AUDIT_RELPATH,
+  auditPath,
+  falseAlarmRate,
+} from './orphan-reaper/reaper-audit.mjs';
+export { REAPER_SCAN_EVENT, resolveDeps, runOrphanScan } from './orphan-reaper/scan.mjs';
+
+// ---------------------------------------------------------------------------
+// CLI (#1432 B4 follow-up)
+// ---------------------------------------------------------------------------
+//
+// The two trigger hooks (`hooks/on-stop.mjs`,
+// `hooks/post-tool-batch-wave-signal.mjs`) spawn the scan as a DETACHED child.
+// Before this tail existed they had to hand `node` an `--input-type=module -e
+// <program>` string that dynamically imported this module — a program the
+// hooks carried as source text, in two byte-identical copies. This entry point
+// replaces it with a plain argv call, so the hooks spawn `node
+// scripts/lib/orphan-reaper.mjs --repo-root <p> --mode <m> …` and the child's
+// contract lives HERE, in one place, next to the function it drives.
+
+/**
+ * Parse the CLI argv — PURE, and exported so the flag contract is testable
+ * without starting a process (the argv form is what the two hooks build, so a
+ * typo in it fails silently as a dead detached child).
+ *
+ * Never throws: an unknown flag, a missing value and a non-numeric value all
+ * land in `errors`, which the tail maps to exit 2. Returning the errors rather
+ * than throwing keeps this usable from a test and from the tail alike.
+ *
+ * @param {string[]} [argv]  `process.argv.slice(2)`
+ * @returns {{help: boolean, json: boolean, repoRoot: string|null, mode: 'report'|'kill',
+ *   dryRun: boolean, minAgeSeconds: number, killGraceMs: number, verifyWaitMs: number,
+ *   falseAlarmWindow: number, errors: string[]}}
+ */
+export function parseReaperCliArgs(argv = []) {
+  const args = Array.isArray(argv) ? argv : [];
+  /** @type {string[]} */
+  const errors = [];
+  const out = {
+    help: false,
+    json: false,
+    repoRoot: null,
+    mode: /** @type {'report'|'kill'} */ ('report'),
+    dryRun: true,
+    minAgeSeconds: REAPER_DEFAULTS.minAgeSeconds,
+    killGraceMs: REAPER_DEFAULTS.killGraceMs,
+    verifyWaitMs: REAPER_DEFAULTS.verifyWaitMs,
+    falseAlarmWindow: REAPER_DEFAULTS.falseAlarmWindow,
+    errors,
+  };
+
+  /**
+   * Consume the value of `--flag <value>`; records an error when it is absent.
+   * @param {string} flag @param {number} i @returns {string|null}
+   */
+  const valueAt = (flag, i) => {
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+      errors.push(`missing value for ${flag}`);
+      return null;
+    }
+    return value;
+  };
+
+  /**
+   * A count of seconds/milliseconds: finite and non-negative. A `NaN` here
+   * would reach `runOrphanScan` as a threshold that compares false against
+   * everything — a silently disarmed gate, which is why it is an error and
+   * never a fallback to the default.
+   * @param {string} flag @param {string} raw @returns {number|null}
+   */
+  const numberFrom = (flag, raw) => {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0) {
+      errors.push(`${flag} expects a non-negative number, got ${JSON.stringify(raw)}`);
+      return null;
+    }
+    return n;
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    switch (arg) {
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      case '--json':
+        out.json = true;
+        break;
+      case '--repo-root': {
+        const value = valueAt(arg, i);
+        if (value !== null) { out.repoRoot = value; i += 1; }
+        break;
+      }
+      case '--mode': {
+        const value = valueAt(arg, i);
+        if (value === null) break;
+        i += 1;
+        if (value !== 'report' && value !== 'kill') {
+          errors.push(`--mode expects report|kill, got ${JSON.stringify(value)}`);
+          break;
+        }
+        out.mode = value;
+        break;
+      }
+      case '--min-age-seconds':
+      case '--kill-grace-ms':
+      case '--verify-wait-ms': {
+        const value = valueAt(arg, i);
+        if (value === null) break;
+        i += 1;
+        const n = numberFrom(arg, value);
+        if (n === null) break;
+        if (arg === '--min-age-seconds') out.minAgeSeconds = n;
+        else if (arg === '--kill-grace-ms') out.killGraceMs = n;
+        else out.verifyWaitMs = n;
+        break;
+      }
+      case '--false-alarm-window': {
+        const value = valueAt(arg, i);
+        if (value === null) break;
+        i += 1;
+        const n = numberFrom(arg, value);
+        if (n === null) break;
+        // A window of 0 is not "no window" — `falseAlarmRate` reads it as "every
+        // firing ever recorded", which is the opposite of the rolling window the
+        // key names. The config parser clamps at 1; the CLI refuses instead, so
+        // a hand-run diagnosis never measures a different population than the
+        // hook does.
+        if (n < 1) {
+          errors.push(`${arg} expects a number >= 1, got ${JSON.stringify(value)}`);
+          break;
+        }
+        out.falseAlarmWindow = n;
+        break;
+      }
+      default:
+        errors.push(`unknown argument: ${arg}`);
+    }
+  }
+
+  // `kill` is the ONLY value that disarms the dry run — same direction as
+  // `runOrphanScan`'s own `dryRun = true` default: a caller that mistypes the
+  // mode scans and reports, it does not signal. (A rejected `--mode` value
+  // already left `mode` at `report`, so this stays `true` there too.)
+  out.dryRun = out.mode !== 'kill';
+  return out;
+}
+
+/** `--help` text. Exit codes documented here are the ones the tail returns. */
+const REAPER_HELP_TEXT = `orphan-reaper.mjs — scan for orphaned read-only gate processes (#1425 Teil B)
+
+USAGE
+  node scripts/lib/orphan-reaper.mjs [options]
+
+DESCRIPTION
+  Runs ONE orphan scan: ps -> decide -> (with --mode kill) re-verify identity
+  against a fresh snapshot -> kill the process group -> audit. Candidates are a
+  CONJUNCTION: recorded in this repo's gate-process ledger, PPID 1, older than
+  --min-age-seconds, a read-only gate command, and an identity that still
+  verifies. Spawned detached by hooks/on-stop.mjs and
+  hooks/post-tool-batch-wave-signal.mjs; runnable by hand for diagnosis.
+
+OPTIONS
+  --repo-root <path>        Repo whose ledger, audit and marker are used
+                            (default: cwd).
+  --mode report|kill        report = dry run, signals nothing (default);
+                            kill = send the SIGTERM/SIGKILL ladder.
+  --min-age-seconds <n>     Minimum elapsed time before a process is reapable
+                            (default: ${REAPER_DEFAULTS.minAgeSeconds}).
+  --kill-grace-ms <n>       Grace between SIGTERM and SIGKILL
+                            (default: ${REAPER_DEFAULTS.killGraceMs}).
+  --verify-wait-ms <n>      Wait before re-measuring the effect
+                            (default: ${REAPER_DEFAULTS.verifyWaitMs}).
+  --false-alarm-window <n>  Rolling window of audit DECISIONS the HR-101
+                            false-alarm rate is judged over; >= 1
+                            (default: ${REAPER_DEFAULTS.falseAlarmWindow}).
+  --json                    Emit the full scan result as one JSON object.
+  --help, -h                Show this help and exit.
+
+EXIT CODES
+  0  the scan ran (0 candidates is a normal, successful scan)
+  2  usage error, or a degraded scan that measured nothing (\`skipped\`)
+`;
+
+/**
+ * CLI body: one scan, one line (or one JSON object) of output.
+ *
+ * A degraded scan — `skipped: 'ps-failed' | 'ledger-unreadable' | …` — exits 2,
+ * not 0: it measured NOTHING, and an exit 0 there is exactly the "missing
+ * measurement looks like a zero" shape this module refuses everywhere else.
+ * The detached hook child ignores the code; a human or a CI caller does not.
+ *
+ * @param {string[]} argv  `process.argv.slice(2)`
+ * @returns {Promise<number>} process exit code
+ */
+async function mainCli(argv) {
+  const cli = parseReaperCliArgs(argv);
+
+  if (cli.help) {
+    process.stdout.write(REAPER_HELP_TEXT);
+    return 0;
+  }
+  if (cli.errors.length > 0) {
+    for (const message of cli.errors) process.stderr.write(`orphan-reaper: ${message}\n`);
+    process.stderr.write('Run with --help for usage.\n');
+    return 2;
+  }
+
+  const repoRoot = cli.repoRoot ?? process.cwd();
+  let result;
+  try {
+    result = await runOrphanScan({
+      repoRoot,
+      dryRun: cli.dryRun,
+      minAgeSeconds: cli.minAgeSeconds,
+      killGraceMs: cli.killGraceMs,
+      verifyWaitMs: cli.verifyWaitMs,
+      falseAlarmWindow: cli.falseAlarmWindow,
+    });
+  } catch (err) {
+    // runOrphanScan carries a NO-THROW contract; this catch exists so a broken
+    // contract surfaces as a tool error instead of an unhandled rejection.
+    process.stderr.write(`orphan-reaper: scan failed — ${err?.message ?? String(err)}\n`);
+    return 2;
+  }
+
+  if (cli.json) {
+    process.stdout.write(`${JSON.stringify({ repoRoot, mode: cli.mode, ...result })}\n`);
+  } else {
+    process.stdout.write(
+      `orphan-reaper: scanned=${result.scanned} candidates=${result.candidates.length} `
+      + `reported=${result.reported.length} unattributed=${result.unattributed} `
+      + `peer_liveness=${result.peerLiveness ?? 'none'} killed=${result.killed.length} `
+      + `malformed=${result.malformed} mode=${cli.mode}`
+      + `${result.skipped ? ` skipped=${result.skipped}` : ''}\n`,
+    );
+  }
+  return result.skipped ? 2 : 0;
+}
+
+// Entry guard: a bare `import()` of this module must do NOTHING — tests and
+// any caller of the re-exports above import it. Written
+// in the one symlink-safe form `scripts/lib/validate/check-entry-guard.mjs`
+// and `check-hook-entry-guards.mjs` accept.
+//
+// `process.exitCode` rather than `process.exit()`: `--json` carries the whole
+// result, whose `rejected` array materialises every PPID-1 row not in the
+// ledger — measured 2026-09-22 on this host, 40.224 bytes for 834 processes,
+// the same order as the 64 KiB pipe buffer above which `process.exit()`
+// DISCARDS the pending write and turns a full result into a truncated one.
+if (isMainModule(import.meta.url)) {
+  process.exitCode = await mainCli(process.argv.slice(2));
+}

package/scripts/lib/owner-yaml.mjs

@@ -36,6 +36,16 @@
  *   dispatcher:             (optional; host-local cross-repo dispatcher autonomy override — #679)
  *     autonomy: string      ('' = no override; resolver enum off | advisory | autonomous-gated;
  *                            precedence env SO_DISPATCHER_AUTONOMY > this > committed > off)
+ *   vault-integration:      (optional; host-local switch for the vault-integration gate — SO#1448)
+ *     enabled: boolean      (false = off on this host; true is ignored — the host may not enable)
+ *     mode: 'off' | 'warn' | 'strict'  (applied only when weaker than the committed mode;
+ *                            precedence env SO_VAULT_INTEGRATION > this > committed.
+ *                            An invalid value drops ONLY this section, see loadOwnerConfig)
+ *   vault-dirs:             (optional list; per-directory vault-dir — agents/vault#319)
+ *     - path: string                       (the vault directory)
+ *       match: { path-prefix: string }     (required; cwd directory prefix, first match wins)
+ *       name: string                       (optional label, defaults to path)
+ *                            precedence env SO_VAULT_DIR > this > paths.vault-dir > committed
  *
  * ── Exports ───────────────────────────────────────────────────────────────────
  *
@@ -44,7 +54,8 @@
  *   validateOwnerSections(obj) — pure validation, no I/O; bucketed per section (#820)
  *   validateOwnerConfig(obj)   — pure validation, no I/O; thin wrapper over validateOwnerSections
  *   loadOwnerConfig({path?})   — reads file; per-section tolerance for OPTIONAL
- *                                sections (paths/dispatcher/vaults/baselines) — #820
+ *                                sections (paths/dispatcher/vault-integration/vaults/
+ *                                baselines/vault-dirs) — #820
  *   writeOwnerConfig(config, {path?}) — validates, writes YAML, creates dir
  *   getDefaults()              — returns sensible default config object
  *
@@ -202,9 +213,12 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  * sections — currently `scripts/lib/owner-config-banner.mjs`, which derived the
  * #1244 "survived a whole-file discard" set from a hand-mirrored local copy.
  * Frozen so a consumer cannot mutate the shared array.
+ *
+ * `vault-integration` has no `getDefaults()` entry: absent means "no host
+ * override", so a dropped section simply leaves the committed gate in force.
  */
 export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
-  Object.freeze(['paths', 'dispatcher'])
+  Object.freeze(['paths', 'dispatcher', 'vault-integration'])
 );
 
 /**
@@ -213,7 +227,10 @@ export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
  * `parseNamedVaults`/`parseBaselines` — that already drops bad entries with
  * its own WARN). Surfaced here only via `sectionWarnings`, never dropped.
  */
-const OPTIONAL_LIST_SECTIONS = /** @type {const} */ (['vaults', 'baselines']);
+const OPTIONAL_LIST_SECTIONS = /** @type {const} */ (['vaults', 'baselines', 'vault-dirs']);
+
+/** Host-settable vault-integration modes (mirrors VAULT_MODE_VALUES in config-schema.mjs). */
+const VALID_VAULT_INTEGRATION_MODES = ['off', 'warn', 'strict'];
 
 /** Canonical validation-order — MUST match the pre-#820 inline validation order. */
 const SECTION_ORDER = /** @type {const} */ ([
@@ -421,6 +438,35 @@ export function validateOwnerSections(obj) {
     sections.dispatcher = { valid: errors.length === 0, errors };
   }
 
+  // ── vault-integration (optional; host-local gate switch — SO#1448) ──────────
+  // STRICT enum validation, unlike `dispatcher`: a typo like `mode: of` must not
+  // fall through to the committed `strict` silently while the operator believes
+  // the host is off. An invalid section is dropped (and reported) on its own —
+  // `paths` and every other section survive (#820 per-section tolerance).
+  {
+    const errors = [];
+    const vi = obj['vault-integration'];
+    if (vi !== undefined && vi !== null) {
+      if (!isPlainObject(vi)) {
+        errors.push('vault-integration must be an object when present');
+      } else {
+        if (vi.enabled !== undefined && vi.enabled !== null && typeof vi.enabled !== 'boolean') {
+          errors.push(`vault-integration.enabled must be a boolean, got: ${typeof vi.enabled}`);
+        }
+        if (
+          vi.mode !== undefined &&
+          vi.mode !== null &&
+          !VALID_VAULT_INTEGRATION_MODES.includes(vi.mode)
+        ) {
+          errors.push(
+            `vault-integration.mode must be one of ${VALID_VAULT_INTEGRATION_MODES.join(', ')}, got: ${JSON.stringify(vi.mode)}`,
+          );
+        }
+      }
+    }
+    sections['vault-integration'] = { valid: errors.length === 0, errors };
+  }
+
   // ── vaults (optional; N named vaults for walk-up resolution — #700) ──────────
   // Drop-and-WARN on malformed entries is handled by parseNamedVaults() in
   // named-vault-resolver.mjs. Here we only validate the container shape to
@@ -512,6 +558,47 @@ export function validateOwnerSections(obj) {
     sections.baselines = { valid: errors.length === 0, errors };
   }
 
+  // ── vault-dirs (optional; per-directory vault-dir — agents/vault#319) ────────
+  // Same entry shape as baselines: (and parsed by the same parseBaselines() with
+  // section 'vault-dirs'), except `name` is optional. List section: surfaced via
+  // sectionWarnings, never dropped — the resolver drops bad entries itself.
+  {
+    const errors = [];
+    const vaultDirs = obj['vault-dirs'];
+    if (vaultDirs !== undefined && vaultDirs !== null) {
+      if (!Array.isArray(vaultDirs)) {
+        errors.push('vault-dirs must be an array when present');
+      } else {
+        for (let i = 0; i < vaultDirs.length; i++) {
+          const entry = vaultDirs[i];
+          if (!isPlainObject(entry)) {
+            errors.push(`vault-dirs[${i}] must be an object`);
+            continue;
+          }
+          if (typeof entry.path !== 'string' || entry.path.trim() === '') {
+            errors.push(`vault-dirs[${i}].path must be a non-empty string`);
+          }
+          if (
+            entry.name !== undefined &&
+            entry.name !== null &&
+            (typeof entry.name !== 'string' || entry.name.trim() === '')
+          ) {
+            errors.push(`vault-dirs[${i}].name must be a non-empty string when present`);
+          }
+          if (!isPlainObject(entry.match)) {
+            errors.push(`vault-dirs[${i}].match must be an object`);
+          } else if (
+            typeof entry.match['path-prefix'] !== 'string' ||
+            entry.match['path-prefix'].trim() === ''
+          ) {
+            errors.push(`vault-dirs[${i}].match.path-prefix must be a non-empty string`);
+          }
+        }
+      }
+    }
+    sections['vault-dirs'] = { valid: errors.length === 0, errors };
+  }
+
   const errors = SECTION_ORDER.flatMap((name) => sections[name].errors);
   return { sections, errors };
 }
@@ -540,10 +627,10 @@ export function validateOwnerConfig(obj) {
  * Per-section tolerance (#820): an invalid REQUIRED section (owner, tone,
  * efficiency, hardware-sharing) still discards the whole file (legacy
  * behaviour, unchanged). An invalid OPTIONAL object section (paths,
- * dispatcher) is instead replaced by its default value — the rest of the
+ * dispatcher, vault-integration) is instead replaced by its default value — the rest of the
  * file survives, `source` becomes `'partial'`, and the drop is reported via
  * `droppedSections` + a stderr WARN. OPTIONAL list sections (vaults,
- * baselines) are passed through UNTOUCHED even when strict-invalid — their
+ * baselines, vault-dirs) are passed through UNTOUCHED even when strict-invalid — their
  * consumers already run a lenient parse-at-point-of-use pass — and are
  * surfaced only via `sectionWarnings` (never dropped, never counted towards
  * `'partial'`).
@@ -658,6 +745,14 @@ export function loadOwnerConfig(opts = {}) {
         discardDropped.push({ section: name, errors: sec.errors });
       }
     }
+    // `vault-dirs:` (agents/vault#319) survives the discard too, raw — exactly as
+    // on the required-valid branch below; parseBaselines() drops bad entries at
+    // point-of-use. Dropping it would hand a repo under a declared prefix the
+    // host-wide `paths.vault-dir` (which DOES survive above): the silent vault
+    // override #319 exists to prevent, triggered by an unrelated `tone:` typo.
+    if (parsed['vault-dirs'] !== undefined && parsed['vault-dirs'] !== null) {
+      discardConfig['vault-dirs'] = parsed['vault-dirs'];
+    }
     const discardResult = { config: discardConfig, source: 'defaults', errors: allErrors };
     if (discardDropped.length > 0) discardResult.droppedSections = discardDropped;
     return discardResult;
@@ -673,7 +768,10 @@ export function loadOwnerConfig(opts = {}) {
   for (const name of OPTIONAL_OBJECT_SECTIONS) {
     const sec = sections[name];
     if (sec && !sec.valid) {
-      config[name] = defaults[name];
+      // A section without a default (vault-integration) is removed, not set to
+      // `undefined`: js-yaml's dump rejects undefined values on a write-back.
+      if (defaults[name] === undefined) delete config[name];
+      else config[name] = defaults[name];
       droppedSections.push({ section: name, errors: sec.errors });
       const firstError = sec.errors[0] ?? 'invalid section';
       console.warn(

package/scripts/lib/peer-cards/merger.mjs

@@ -49,7 +49,7 @@ const SENTINEL_BEGIN_RE = new RegExp(`<!--\\s*BEGIN\\s+MANAGED:\\s*(${SECTION_NA
 
 /**
  * @typedef {Object} Conflict
- * @property {'duplicate-section' | 'orphan-begin'} type
+ * @property {'duplicate-section' | 'orphan-begin' | 'unmapped-preamble' | 'multi-heading-region'} type
  * @property {string} [name] — section name (for duplicate-section and orphan-begin)
  */
 
@@ -317,8 +317,14 @@ function escapeRegex(s) {
 // the two, so `/evolve dialectic --apply` could not complete (#1310, correcting
 // #1303 point 3 — the signatures line up, the seam did not).
 //
-// The mapping is DERIVED, not invented: every managed region in the live cards
-// wraps exactly one `## ` heading, so the heading IS the section unit. Existing
+// The mapping is DERIVED, not invented: a managed region wrapping exactly one
+// `## ` heading makes that heading the section unit. A region wrapping SEVERAL
+// headings cannot be addressed per heading without splitting the region (a
+// storage-format change), so it is fail-closed (#1380): `deriveManagedUpdates`
+// never targets it, and every proposed heading that lives inside it is skipped
+// — neither replaced (which would delete its sibling headings' hand text) nor
+// appended (which would duplicate the heading) — and reported as a
+// `multi-heading-region` conflict by `mergeDerivedBody`. Existing
 // names are read back out of the card rather than re-slugified, because the live
 // names are NOT a pure function of their headings — measured 2026-09-11 in
 // `.orchestrator/peers/AGENT.md`: "Guard and protocol-migration discipline" →
@@ -359,6 +365,9 @@ function slugifyHeading(heading) {
  *  • Text BEFORE the first `## ` heading → returned as `preamble`. It is NOT
  *    written into any section (it has no sentinel to own it); `mergeDerivedBody`
  *    surfaces it as an `unmapped-preamble` conflict so a caller cannot miss it.
+ *  • Heading that lives inside an existing managed region wrapping MORE than one
+ *    `## ` heading → SKIPPED (not in `managedUpdates`, not in `mapping`) and
+ *    listed in `skippedRegions`; that region is never a target (#1380).
  *  • Content under `###`+ headings stays inside its parent `##` section.
  *  • A proposed body that already carries BEGIN/END sentinels keeps them inside
  *    the section content — it is the deriver's job not to emit them (see
@@ -370,7 +379,8 @@ function slugifyHeading(heading) {
  * @param {string} [existingBody] — the on-disk body, for existing-name lookup
  * @returns {{ managedUpdates: Record<string,string>,
  *             mapping: Array<{heading: string, section: string, origin: 'existing'|'new'}>,
- *             preamble: string }}
+ *             preamble: string,
+ *             skippedRegions: Array<{region: string, headings: string[], skipped: string[]}> }}
  */
 export function deriveManagedUpdates(proposedBody, existingBody = '') {
   if (typeof proposedBody !== 'string') {
@@ -383,13 +393,25 @@ export function deriveManagedUpdates(proposedBody, existingBody = '') {
   // heading-key → existing section name, read out of the live card
   const existingByHeading = new Map();
   const existingNames = new Set();
+  // Fail-closed bookkeeping for regions wrapping more than one `## ` heading (#1380).
+  /** @type {Map<string, {region: string, headings: string[], skipped: string[]}>} */
+  const multiHeading = new Map();
+  const multiHeadingByKey = new Map();
   if (existingBody.length > 0) {
     for (const s of parseSections(existingBody).sections) {
       if (s.type !== 'managed') continue;
       existingNames.add(s.name);
-      const h = s.content.match(/^##[ \t]+(.+?)[ \t]*$/m);
-      if (h && !existingByHeading.has(headingKey(h[1]))) {
-        existingByHeading.set(headingKey(h[1]), s.name);
+      H2_RE.lastIndex = 0;
+      const regionHeads = [...s.content.matchAll(H2_RE)].map(h => h[1]);
+      if (regionHeads.length > 1) {
+        const entry = multiHeading.get(s.name) ?? { region: s.name, headings: [], skipped: [] };
+        entry.headings.push(...regionHeads);
+        multiHeading.set(s.name, entry);
+        for (const h of regionHeads) multiHeadingByKey.set(headingKey(h), entry);
+        continue;
+      }
+      if (regionHeads.length === 1 && !existingByHeading.has(headingKey(regionHeads[0]))) {
+        existingByHeading.set(headingKey(regionHeads[0]), s.name);
       }
     }
   }
@@ -409,6 +431,12 @@ export function deriveManagedUpdates(proposedBody, existingBody = '') {
     const end = i + 1 < heads.length ? heads[i + 1].index : proposedBody.length;
     const content = proposedBody.slice(start, end).trim();
 
+    const blocked = multiHeadingByKey.get(headingKey(heading));
+    if (blocked !== undefined) {
+      blocked.skipped.push(heading);
+      continue;
+    }
+
     const existing = existingByHeading.get(headingKey(heading));
     let section;
     let origin;
@@ -419,7 +447,9 @@ export function deriveManagedUpdates(proposedBody, existingBody = '') {
       const base = slugifyHeading(heading);
       let candidate = base;
       let n = 2;
-      while (used.has(candidate)) {
+      // A multi-heading region is never a target — not even via a slug that
+      // happens to equal its name.
+      while (used.has(candidate) || multiHeading.has(candidate)) {
         candidate = `${base}-${n++}`;
       }
       section = candidate;
@@ -431,7 +461,8 @@ export function deriveManagedUpdates(proposedBody, existingBody = '') {
     mapping.push({ heading, section, origin });
   }
 
-  return { managedUpdates, mapping, preamble };
+  const skippedRegions = [...multiHeading.values()].filter(e => e.skipped.length > 0);
+  return { managedUpdates, mapping, preamble, skippedRegions };
 }
 
 /**
@@ -439,13 +470,20 @@ export function deriveManagedUpdates(proposedBody, existingBody = '') {
  * This is the function `/evolve dialectic --apply` calls; `mergePeerCard` stays
  * the section-map primitive its existing callers already use.
  *
+ * A managed region wrapping several `## ` headings is left byte-unchanged; each
+ * skipped proposed heading surfaces as a
+ * `{ type: 'multi-heading-region', region, headings, skipped }` conflict (#1380).
+ *
  * @param {string} existingBody
  * @param {string} proposedBody
  * @returns {MergeResult & { mapping: Array<{heading: string, section: string, origin: 'existing'|'new'}>, preamble: string }}
  */
 export function mergeDerivedBody(existingBody, proposedBody) {
-  const { managedUpdates, mapping, preamble } = deriveManagedUpdates(proposedBody, existingBody);
+  const { managedUpdates, mapping, preamble, skippedRegions } = deriveManagedUpdates(proposedBody, existingBody);
   const result = mergePeerCard(existingBody, managedUpdates);
+  for (const { region, headings, skipped } of skippedRegions) {
+    result.conflicts.push({ type: 'multi-heading-region', region, headings, skipped });
+  }
   if (preamble.length > 0) {
     result.conflicts.push({ type: 'unmapped-preamble', content: preamble });
   }