session-orchestrator 5.2.0 → 5.3.0

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 });
   }

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

@@ -104,11 +104,11 @@ async function readOneCard(absPath, now) {
     };
   }
 
-  const parsed = parseStateMd(content);
+  const parsed = parseStateMd(foldMultilineLists(content));
   if (parsed === null) {
     return {
       frontmatter: null,
-      body: content,
+      body: stripFrontmatterBlock(content),
       stalenessDays: Infinity,
       isStale: true,
       validation: { ok: false, errors: ['no frontmatter or malformed YAML'] },
@@ -123,3 +123,79 @@ async function readOneCard(absPath, now) {
 
   return { frontmatter, body, stalenessDays, isStale, validation };
 }
+
+// `---\n<frontmatter>\n---\n` at the very start — same shape `parseStateMd` matches.
+const FRONTMATTER_BLOCK_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/;
+
+/**
+ * Fold multi-line list values of top-level frontmatter keys into the one-line
+ * flow form (`key: [a, b]`) that `parseStateMd` understands. Two shapes (#1380):
+ *   • a multi-line flow list — `key:\n  [\n    "a",\n    "b",\n  ]` — which is how
+ *     Prettier reformats the one-line list `writer.mjs` emits;
+ *   • a block list — `key:\n  - a\n  - b` — as a hand edit would write it.
+ * Done here, not in the shared STATE.md parser: its mutators rely on `null` for
+ * shapes it does not understand. A block list whose items are mappings
+ * (`- name: x`) is left untouched — that is the parser's own block-seq form.
+ * Content outside the frontmatter block is never modified.
+ *
+ * @param {string} content — full file content
+ * @returns {string}
+ */
+function foldMultilineLists(content) {
+  const m = FRONTMATTER_BLOCK_RE.exec(content);
+  if (!m) return content;
+  const lines = m[1].split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const key = /^([\w-]+):\s*$/.exec(lines[i]);
+    const next = lines[i + 1];
+    if (!key || next === undefined || !/^\s+\S/.test(next)) {
+      out.push(lines[i]);
+      continue;
+    }
+    if (next.trim().startsWith('[')) {
+      let j = i + 1;
+      const parts = [];
+      while (j < lines.length && /^\s+\S/.test(lines[j])) {
+        parts.push(lines[j].trim());
+        if (lines[j].trim().endsWith(']')) break;
+        j++;
+      }
+      if (j < lines.length && lines[j].trim().endsWith(']')) {
+        const inner = parts.join(' ').slice(1, -1).trim().replace(/,\s*$/, '');
+        out.push(`${key[1]}: [${inner.replace(/\s*,\s*/g, ', ')}]`);
+        i = j;
+        continue;
+      }
+    } else {
+      let j = i + 1;
+      const items = [];
+      while (j < lines.length && /^\s+-\s+\S/.test(lines[j])) {
+        items.push(lines[j].trim().slice(1).trim());
+        j++;
+      }
+      const endsBlock = j >= lines.length || !/^\s/.test(lines[j]);
+      if (items.length > 0 && endsBlock && !items.some((it) => /^[\w-]+:(\s|$)/.test(it))) {
+        out.push(`${key[1]}: [${items.join(', ')}]`);
+        i = j - 1;
+        continue;
+      }
+    }
+    out.push(lines[i]);
+  }
+  return `---\n${out.join('\n')}\n---${m[2]}${content.slice(m[0].length)}`;
+}
+
+/**
+ * Remove a leading `---…---` frontmatter block so an unparseable one never reaches
+ * a body consumer (the dialectic deriver payload) as if it were markdown (#1380).
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function stripFrontmatterBlock(content) {
+  const m = FRONTMATTER_BLOCK_RE.exec(content);
+  if (!m) return content;
+  const rest = content.slice(m[0].length);
+  return rest.startsWith('\n') ? rest.slice(1) : rest;
+}