session-orchestrator 3.16.0

package/scripts/lib/package-manager.mjs

@@ -0,0 +1,160 @@
+/**
+ * Package-manager detection for Node.js repos (issue #183).
+ *
+ * Consumed by bootstrap when generating .orchestrator/policy/quality-gates.json
+ * to pick sensible default test/typecheck/lint commands.
+ *
+ * Detection is synchronous. An explicit package.json packageManager field wins;
+ * otherwise, root lockfiles are considered when they are not explicitly ignored
+ * by the repo's root .gitignore.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PACKAGE_MANAGERS = new Set(['pnpm', 'yarn', 'bun', 'npm']);
+
+const LOCKFILES = [
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['yarn.lock', 'yarn'],
+  ['bun.lockb', 'bun'],
+  ['package-lock.json', 'npm'],
+];
+
+function packageManagerFromPackageJson(repoRoot) {
+  const path = join(repoRoot, 'package.json');
+  if (!existsSync(path)) return null;
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    const value = parsed.packageManager;
+    if (typeof value !== 'string') return null;
+
+    const name = value.split('@')[0];
+    return PACKAGE_MANAGERS.has(name) ? name : null;
+  } catch {
+    return null;
+  }
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function gitignorePatternMatchesRootFile(pattern, fileName) {
+  let normalized = pattern.trim();
+  if (!normalized || normalized.startsWith('#') || normalized.endsWith('/')) {
+    return false;
+  }
+
+  if (normalized.startsWith('/')) {
+    normalized = normalized.slice(1);
+  }
+
+  if (normalized.includes('/')) {
+    return normalized === fileName;
+  }
+
+  if (normalized.includes('*') || normalized.includes('?')) {
+    const source = normalized
+      .split('*')
+      .map((part) => part.split('?').map(escapeRegExp).join('.'))
+      .join('.*');
+    return new RegExp(`^${source}$`).test(fileName);
+  }
+
+  return normalized === fileName;
+}
+
+/**
+ * Returns true when `fileName` sits at the repo root AND is matched
+ * (non-negated) by a pattern in the repo's root `.gitignore`.
+ *
+ * Shared by sibling package-manager detectors (ecosystem-wizard's
+ * detectPackageManagerFromRoot, quality-gates-cache's computeDependencyHash)
+ * so a gitignored root lockfile is treated as absent everywhere, not just
+ * in detectPackageManager() below (issue #715 bug class).
+ *
+ * @param {string} repoRoot - absolute path to the repo root
+ * @param {string} fileName - root-level file name to test (e.g. "pnpm-lock.yaml")
+ * @returns {boolean}
+ */
+export function isIgnoredRootFile(repoRoot, fileName) {
+  const path = join(repoRoot, '.gitignore');
+  if (!existsSync(path)) return false;
+
+  let ignored = false;
+  try {
+    const lines = readFileSync(path, 'utf8').split(/\r?\n/);
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) continue;
+
+      const negated = line.startsWith('!');
+      const pattern = negated ? line.slice(1) : line;
+      if (gitignorePatternMatchesRootFile(pattern, fileName)) {
+        ignored = !negated;
+      }
+    }
+  } catch {
+    return false;
+  }
+
+  return ignored;
+}
+
+/**
+ * Detects the package manager used in the given repo.
+ *
+ * @param {string} repoRoot - absolute path to the repo root
+ * @returns {"pnpm"|"yarn"|"bun"|"npm"|null}
+ */
+export function detectPackageManager(repoRoot) {
+  const explicit = packageManagerFromPackageJson(repoRoot);
+  if (explicit) return explicit;
+
+  for (const [lockfile, packageManager] of LOCKFILES) {
+    if (
+      existsSync(join(repoRoot, lockfile)) &&
+      !isIgnoredRootFile(repoRoot, lockfile)
+    ) {
+      return packageManager;
+    }
+  }
+
+  return null;
+}
+
+const COMMANDS = {
+  pnpm: {
+    test: { command: 'pnpm test --run', required: true },
+    typecheck: { command: 'pnpm typecheck', required: true },
+    lint: { command: 'pnpm lint', required: true },
+  },
+  npm: {
+    test: { command: 'npm test', required: true },
+    typecheck: { command: 'npm run typecheck', required: true },
+    lint: { command: 'npm run lint', required: true },
+  },
+  yarn: {
+    test: { command: 'yarn test', required: true },
+    typecheck: { command: 'yarn typecheck', required: true },
+    lint: { command: 'yarn lint', required: true },
+  },
+  bun: {
+    test: { command: 'bun test', required: true },
+    typecheck: { command: 'bun run typecheck', required: true },
+    lint: { command: 'bun run lint', required: true },
+  },
+};
+
+/**
+ * Returns the default quality-gate commands for a package manager.
+ * Unknown / null → npm defaults (most portable).
+ *
+ * @param {"pnpm"|"yarn"|"bun"|"npm"|null|undefined} packageManager
+ * @returns {{test: {command: string, required: boolean}, typecheck: {command: string, required: boolean}, lint: {command: string, required: boolean}}}
+ */
+export function defaultQualityGateCommands(packageManager) {
+  return COMMANDS[packageManager] || COMMANDS.npm;
+}

package/scripts/lib/path-utils.mjs

@@ -0,0 +1,217 @@
+/**
+ * path-utils.mjs — Path-traversal-safe helpers for cross-platform use.
+ *
+ * SECURITY-CRITICAL: Backs enforce-scope.mjs (CWE-23 protection).
+ *
+ * Most functions are pure (no filesystem I/O). The exception is
+ * validatePathInsideProject, which performs a two-phase lexical + realpath
+ * guard and calls realpathSync on Phase 2. All other exported helpers remain
+ * pure and do not follow symlinks.
+ *
+ * Part of v3.0.0 migration (Epic #124, issue #130).
+ */
+
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Documented attack patterns covered by isPathInside.
+ * Exported for test self-check (Wave 4) and audit documentation.
+ */
+export const CWE_23_ATTACK_PATTERNS = [
+  'relative-escape',         // ../
+  'deep-relative-escape',    // ../../
+  'absolute-escape',         // /etc/passwd when parent is /home/user
+  'prefix-match-confusion',  // /home/userx vs /home/user (not a descendant)
+  'windows-drive-escape',    // C:\..\Windows
+  'case-mismatch',           // Windows Foo vs foo (locale-aware)
+  'cross-drive',             // C:\ vs D:\
+  'unc-path',                // \\server\share (Windows — unconditionally rejected)
+  'null-byte-injection',     // embedded \x00 (rejected via input guard)
+];
+
+function _assertNonEmptyString(value, fnName, argName) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${fnName}: ${argName} must be a non-empty string`);
+  }
+  if (value.includes('\x00')) {
+    throw new TypeError(`${fnName}: ${argName} must not contain null bytes`);
+  }
+}
+
+function _normalizeForCompare(p) {
+  // Locale-stable lowercasing on Windows to match filesystem case-insensitivity.
+  // toLocaleLowerCase('en-US') avoids Turkish-I style divergence from toLowerCase().
+  return IS_WINDOWS ? p.toLocaleLowerCase('en-US') : p;
+}
+
+/**
+ * Returns true if child is strictly inside parent (descendant, not equal).
+ *
+ * Rejects: relative/absolute escapes, UNC paths on Windows, null bytes, empty inputs.
+ * Case-insensitive on Windows (locale-stable).
+ *
+ * @param {string} child — path to test
+ * @param {string} parent — containing path
+ * @returns {boolean}
+ * @throws {TypeError} on invalid input (empty, null-byte, non-string)
+ */
+export function isPathInside(child, parent) {
+  _assertNonEmptyString(child, 'isPathInside', 'child');
+  _assertNonEmptyString(parent, 'isPathInside', 'parent');
+
+  // Unconditionally reject UNC paths on Windows as child input.
+  if (IS_WINDOWS && (child.startsWith('\\\\') || child.startsWith('//'))) {
+    return false;
+  }
+
+  const resolvedParent = path.resolve(parent);
+  const resolvedChild = path.resolve(child);
+  const pa = _normalizeForCompare(resolvedParent);
+  const ch = _normalizeForCompare(resolvedChild);
+  const rel = path.relative(pa, ch);
+
+  // Descendant iff: non-empty relative path, no leading '..', and not absolute.
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/**
+ * Returns relative path from root to fullPath.
+ *
+ * Return contract:
+ *   - `'.'`        → fullPath IS root (same directory)
+ *   - `'<rel>'`    → fullPath is strictly inside root
+ *   - `null`       → fullPath is outside root
+ *
+ * Callers MUST distinguish `null` from `'.'` — do not use falsy checks.
+ *
+ * @param {string} root
+ * @param {string} fullPath
+ * @returns {string|null}
+ */
+export function relativeFromRoot(root, fullPath) {
+  _assertNonEmptyString(root, 'relativeFromRoot', 'root');
+  _assertNonEmptyString(fullPath, 'relativeFromRoot', 'fullPath');
+
+  const resolvedRoot = path.resolve(root);
+  const resolvedFull = path.resolve(fullPath);
+
+  if (_normalizeForCompare(resolvedRoot) === _normalizeForCompare(resolvedFull)) {
+    return '.';
+  }
+  if (!isPathInside(fullPath, root)) {
+    return null;
+  }
+  return path.relative(resolvedRoot, resolvedFull);
+}
+
+/**
+ * Lowercase on Windows (locale-stable), passthrough on POSIX.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function normalizeCase(p) {
+  _assertNonEmptyString(p, 'normalizeCase', 'p');
+  return _normalizeForCompare(p);
+}
+
+/**
+ * Returns true if two paths reside on the same drive.
+ * On POSIX, always returns true (single-root filesystem).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameDrive(a, b) {
+  _assertNonEmptyString(a, 'sameDrive', 'a');
+  _assertNonEmptyString(b, 'sameDrive', 'b');
+  if (!IS_WINDOWS) return true;
+  const rootA = path.parse(path.resolve(a)).root.toLowerCase();
+  const rootB = path.parse(path.resolve(b)).root.toLowerCase();
+  return rootA === rootB;
+}
+
+/**
+ * Two-phase path-traversal + symlink-escape guard.
+ * Phase 1: lexical isPathInside check (rejects ../ traversal).
+ * Phase 2: realpath resolution + isPathInside (rejects symlink escape).
+ * ENOENT in Phase 2 is swallowed — lexical check is sufficient when path does not yet exist.
+ *
+ * @param {string} input - User-supplied path (relative or absolute)
+ * @param {string} root - Trusted parent directory (absolute)
+ * @param {object} [opts] - Optional behaviour modifiers.
+ * @param {boolean} [opts.canonicalizeRoot=false] - When true and `root` exists on
+ *   disk, canonicalize it via `realpathSync` BEFORE the Phase 1 lexical check.
+ *   This is the documented workaround for macOS tmpdirs where `/var/...` is a
+ *   symlink to `/private/var/...` — without canonicalization the Phase 2
+ *   realpath check would reject legitimate descendants because the realpath
+ *   namespace differs from the lexical namespace.
+ *   DEFAULT IS `false` — the legacy two-phase behaviour is byte-identical when
+ *   the option is omitted or set to anything other than `true`.
+ *
+ *   ASYMMETRIC OPT-IN (#548 A3) — current callers split as follows:
+ *     - opt-in (`canonicalizeRoot: true`):
+ *         memory-proposals/sink.mjs × 3, memory-proposals/store.mjs × 1
+ *       These run against `mkdtempSync` paths in tests on macOS and require
+ *       the workaround to function on `/var → /private/var`.
+ *     - default (`canonicalizeRoot` omitted): run-migrate-v2-cross-repo.mjs,
+ *         promote-vault-strict.mjs × 2, vault-integration-watcher.mjs,
+ *         config/test.mjs, playwright-driver/runner.mjs, profiles/schema.mjs,
+ *         persona-panel/catalog-loader.mjs × 2, gitlab-portfolio/cli.mjs.
+ *   Flipping the default to `true` is a behaviour change for the 10 default
+ *   callers (root would be realpath-resolved before the lexical compare); it
+ *   is tracked separately and intentionally NOT done here. New callers should
+ *   pass `{ canonicalizeRoot: true }` when they operate against tmpdir roots.
+ * @returns {{ok: true, realPath: string|undefined, lexicalPath: string} | {ok: false, reason: 'lexical'|'symlink'|'input', error?: string}}
+ */
+export function validatePathInsideProject(input, root, opts = {}) {
+  // 1. Input validation
+  if (typeof input !== 'string' || input.length === 0) {
+    return { ok: false, reason: 'input', error: 'input must be a non-empty string' };
+  }
+  if (input.includes('\0')) {
+    return { ok: false, reason: 'input', error: 'input contains null byte' };
+  }
+  // 1b. Optional root canonicalization (#544 M3 — opt-in for callers that
+  // operate against mkdtempSync paths on macOS). Strictly gated on
+  // opts.canonicalizeRoot === true so unconditional callers see byte-identical
+  // legacy behaviour.
+  //
+  // #548 A5-ENOENT: the previous `existsSync(root) && realpathSync(root)`
+  // pattern was a TOCTOU race — root could be deleted between the existsSync
+  // check and the realpathSync call. Drop the precheck and rely on the
+  // try/catch alone, narrowed to the two expected error codes (ENOENT for
+  // racy tmp-dir teardown, EACCES for unreadable paths). Other errors
+  // surface so genuine filesystem faults are not silently swallowed.
+  let effectiveRoot = root;
+  if (opts && opts.canonicalizeRoot === true) {
+    try {
+      effectiveRoot = realpathSync(root);
+    } catch (err) {
+      if (err && err.code !== 'ENOENT' && err.code !== 'EACCES') throw err;
+      // Best-effort: fall back to lexical root if realpath fails with the
+      // expected codes. ENOENT/EACCES are normal during tmp-dir tests and
+      // racy filesystem operations.
+    }
+  }
+  // 2. Phase 1: lexical
+  const lexicalPath = path.resolve(effectiveRoot, input);
+  if (!isPathInside(lexicalPath, effectiveRoot)) {
+    return { ok: false, reason: 'lexical' };
+  }
+  // 3. Phase 2: realpath (ENOENT swallowed; other errors propagate — SEC-Q2-LOW-1)
+  try {
+    const realPath = realpathSync(lexicalPath);
+    if (!isPathInside(realPath, effectiveRoot)) {
+      return { ok: false, reason: 'symlink' };
+    }
+    return { ok: true, realPath, lexicalPath };
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') throw err;
+    return { ok: true, realPath: undefined, lexicalPath };
+  }
+}

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

@@ -0,0 +1,310 @@
+/**
+ * merger.mjs — Sentinel-region three-way merge for peer cards (USER.md / AGENT.md)
+ * for issue #503 (Wave 2 I8).
+ *
+ * Consumers:
+ *   - /evolve --dialectic pass (future #506)
+ *
+ * Design notes
+ * ────────────
+ *  • SENTINEL-REGION MERGE (Strategy A per #503 D3). Managed regions are delimited by
+ *    HTML comment sentinels:
+ *        <!-- BEGIN MANAGED: <section-name> -->
+ *        ...AI-replaceable content...
+ *        <!-- END MANAGED: <section-name> -->
+ *    Content outside sentinels is hand-owned and preserved verbatim. Content inside
+ *    sentinels is AI-replaceable.
+ *  • Pure functions — no fs imports, no IO, deterministic. Same input → same output.
+ *  • Conflict-surfacing — duplicate section names and orphan BEGIN sentinels become
+ *    `conflicts[]` entries. The caller decides UX (warn vs prompt vs reject).
+ *  • Idempotent — `mergePeerCard(body, {})` returns body byte-equivalent (modulo the
+ *    serialize round-trip; the sentinel comments are re-emitted in the same form).
+ *
+ * Section-name grammar: `[A-Za-z0-9_-]+` (word characters + hyphen).
+ */
+
+const SECTION_NAME = '[\\w-]+';
+const SENTINEL_BEGIN_RE = new RegExp(`<!--\\s*BEGIN\\s+MANAGED:\\s*(${SECTION_NAME})\\s*-->`, 'g');
+
+/**
+ * @typedef {Object} HandSection
+ * @property {'hand'} type
+ * @property {string} content — verbatim text between/around sentinels (may be empty)
+ * @property {number} startIdx — absolute char offset in original body
+ * @property {number} endIdx — absolute char offset (exclusive)
+ */
+
+/**
+ * @typedef {Object} ManagedSection
+ * @property {'managed'} type
+ * @property {string} name — section name from the BEGIN sentinel
+ * @property {string} content — inner content (excludes the sentinel comments themselves)
+ * @property {number} startIdx — offset of the BEGIN sentinel; -1 for sections appended via merge
+ * @property {number} endIdx — offset just past the END sentinel; -1 for appended sections
+ */
+
+/**
+ * @typedef {HandSection | ManagedSection} Section
+ */
+
+/**
+ * @typedef {Object} Conflict
+ * @property {'duplicate-section' | 'orphan-begin'} type
+ * @property {string} [name] — section name (for duplicate-section and orphan-begin)
+ */
+
+/**
+ * Parse a peer-card body into hand-owned and AI-managed sections.
+ *
+ * Behaviour
+ * ─────────
+ *  • Text before the first BEGIN sentinel becomes a `hand` section.
+ *  • Each well-formed BEGIN..END pair becomes a `managed` section. The `content` field
+ *    excludes the sentinel comments themselves (so re-serialising wraps them back on).
+ *  • An orphan BEGIN (no matching END) collapses the BEGIN sentinel and all remaining
+ *    text into a single `hand` section — defensive: we never silently drop user text.
+ *    Caller should detect this via the absence of the expected managed section in the
+ *    parse result, OR via the `mergePeerCard` `conflicts[]` (which checks structure).
+ *  • Trailing text after the last END becomes a `hand` section.
+ *
+ * @param {string} body
+ * @returns {{ sections: Section[] }}
+ */
+function parseSections(body) {
+  if (typeof body !== 'string') {
+    throw new Error(`parseSections: body must be string (got ${typeof body}).`);
+  }
+
+  const sections = [];
+  const text = body;
+  let cursor = 0;
+
+  // Reset regex state (global regex carries lastIndex across calls)
+  SENTINEL_BEGIN_RE.lastIndex = 0;
+  const beginMatches = [...text.matchAll(SENTINEL_BEGIN_RE)];
+
+  for (const beginMatch of beginMatches) {
+    const sectionName = beginMatch[1];
+    const beginStart = beginMatch.index;
+
+    // If a previous orphan-BEGIN already consumed to EOF, skip remaining matches
+    if (beginStart < cursor) continue;
+
+    const beginEnd = beginStart + beginMatch[0].length;
+
+    // Hand region BEFORE this BEGIN
+    if (cursor < beginStart) {
+      sections.push({
+        type: 'hand',
+        content: text.slice(cursor, beginStart),
+        startIdx: cursor,
+        endIdx: beginStart,
+      });
+    }
+
+    // Find matching END (constructed per-section so names match exactly)
+    const endRegex = new RegExp(`<!--\\s*END\\s+MANAGED:\\s*${escapeRegex(sectionName)}\\s*-->`);
+    const endRest = text.slice(beginEnd);
+    const endMatch = endRest.match(endRegex);
+
+    if (!endMatch) {
+      // Orphan BEGIN — defensive: treat the BEGIN sentinel + rest of file as hand
+      sections.push({
+        type: 'hand',
+        content: text.slice(beginStart),
+        startIdx: beginStart,
+        endIdx: text.length,
+      });
+      cursor = text.length;
+      break;
+    }
+
+    const endStart = beginEnd + endMatch.index;
+    const endEnd = endStart + endMatch[0].length;
+
+    sections.push({
+      type: 'managed',
+      name: sectionName,
+      content: text.slice(beginEnd, endStart),
+      startIdx: beginStart,
+      endIdx: endEnd,
+    });
+    cursor = endEnd;
+  }
+
+  // Trailing hand region
+  if (cursor < text.length) {
+    sections.push({
+      type: 'hand',
+      content: text.slice(cursor),
+      startIdx: cursor,
+      endIdx: text.length,
+    });
+  }
+
+  return { sections };
+}
+
+/**
+ * Serialize sections back to a body string, wrapping managed regions in sentinels.
+ *
+ * @param {Section[]} sections
+ * @returns {string}
+ */
+function serializeSections(sections) {
+  if (!Array.isArray(sections)) {
+    throw new Error(`serializeSections: sections must be array (got ${typeof sections}).`);
+  }
+
+  let out = '';
+  for (const s of sections) {
+    if (s.type === 'hand') {
+      out += s.content;
+    } else if (s.type === 'managed') {
+      out += `<!-- BEGIN MANAGED: ${s.name} -->`;
+      out += s.content;
+      out += `<!-- END MANAGED: ${s.name} -->`;
+    } else {
+      throw new Error(`serializeSections: unknown section type: ${JSON.stringify(s)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * @typedef {Object} MergeResult
+ * @property {string} body — the merged body
+ * @property {Conflict[]} conflicts — duplicate-section / orphan-begin issues for caller review
+ * @property {{ preserved: number, replaced: number, appended: number }} stats
+ */
+
+/**
+ * Merge a dialectic-derived update into an existing peer-card body.
+ *
+ * Semantics
+ * ─────────
+ *  • Hand-owned sections (outside sentinels): PRESERVED verbatim.
+ *  • Managed sections matching `managedUpdates` keys: REPLACED with new content.
+ *  • Managed sections in `managedUpdates` not in existing: APPENDED at end.
+ *  • Managed sections in existing not in `managedUpdates`: KEPT (no auto-delete).
+ *  • Idempotency: `mergePeerCard(body, {})` returns a body byte-equivalent to `body`
+ *    (round-trip through parse/serialize, which preserves sentinel form).
+ *
+ * Conflicts
+ * ─────────
+ *  • `duplicate-section` — same managed section name appears more than once in the
+ *    existing body. We replace ALL occurrences with the update content (or keep all
+ *    as-is if no update) but surface the conflict so the caller can resolve.
+ *  • `orphan-begin` — BEGIN without matching END. Detected by re-parsing the merged
+ *    body and comparing sentinel structure.
+ *
+ * @param {string} existingBody — the on-disk body (with sentinels)
+ * @param {Record<string, string>} managedUpdates — `{ <section-name>: <new-content> }`
+ * @returns {MergeResult}
+ */
+export function mergePeerCard(existingBody, managedUpdates) {
+  if (typeof existingBody !== 'string') {
+    throw new Error(`mergePeerCard: existingBody must be string (got ${typeof existingBody}).`);
+  }
+  if (!managedUpdates || typeof managedUpdates !== 'object' || Array.isArray(managedUpdates)) {
+    throw new Error('mergePeerCard: managedUpdates must be a plain object.');
+  }
+
+  // Validate update keys against section-name grammar
+  for (const name of Object.keys(managedUpdates)) {
+    if (!/^[\w-]+$/.test(name)) {
+      throw new Error(`mergePeerCard: invalid section name "${name}" (allowed: [A-Za-z0-9_-]+).`);
+    }
+    if (typeof managedUpdates[name] !== 'string') {
+      throw new Error(`mergePeerCard: managedUpdates["${name}"] must be a string.`);
+    }
+  }
+
+  const { sections } = parseSections(existingBody);
+  const conflicts = [];
+  const stats = { preserved: 0, replaced: 0, appended: 0 };
+
+  // Detect orphan-begin: a BEGIN sentinel was found but no matching END (the parser
+  // collapsed it into a hand section). We re-scan the original text for BEGIN names
+  // whose presence in the parsed managed sections is missing — those are orphans.
+  const parsedManagedNames = new Set();
+  const seenForDuplicate = new Set();
+  for (const s of sections) {
+    if (s.type === 'managed') {
+      parsedManagedNames.add(s.name);
+      if (seenForDuplicate.has(s.name)) {
+        conflicts.push({ type: 'duplicate-section', name: s.name });
+      } else {
+        seenForDuplicate.add(s.name);
+      }
+    }
+  }
+
+  SENTINEL_BEGIN_RE.lastIndex = 0;
+  const allBeginNames = [...existingBody.matchAll(SENTINEL_BEGIN_RE)].map(m => m[1]);
+  const reportedOrphans = new Set();
+  for (const name of allBeginNames) {
+    if (!parsedManagedNames.has(name) && !reportedOrphans.has(name)) {
+      conflicts.push({ type: 'orphan-begin', name });
+      reportedOrphans.add(name);
+    }
+  }
+
+  // Apply updates: replace managed sections whose names match, preserve others
+  const updatedSections = sections.map(s => {
+    if (s.type === 'hand') {
+      stats.preserved++;
+      return s;
+    }
+    // s.type === 'managed'
+    if (Object.prototype.hasOwnProperty.call(managedUpdates, s.name)) {
+      stats.replaced++;
+      return { ...s, content: wrapManagedContent(managedUpdates[s.name]) };
+    }
+    // Managed section not in updates — keep as-is
+    return s;
+  });
+
+  // Append new managed sections from updates that didn't exist in original
+  for (const name of Object.keys(managedUpdates)) {
+    if (!parsedManagedNames.has(name)) {
+      stats.appended++;
+      updatedSections.push({
+        type: 'managed',
+        name,
+        content: wrapManagedContent(managedUpdates[name]),
+        startIdx: -1,
+        endIdx: -1,
+      });
+    }
+  }
+
+  return {
+    body: serializeSections(updatedSections),
+    conflicts,
+    stats,
+  };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Normalise managed content so the serialised form always reads:
+ *   <!-- BEGIN MANAGED: x -->\n<content>\n<!-- END MANAGED: x -->
+ * Trimming + adding newlines keeps managed regions visually distinct from sentinels.
+ * @param {string} raw
+ * @returns {string}
+ */
+function wrapManagedContent(raw) {
+  return '\n' + raw.trim() + '\n';
+}
+
+/**
+ * Escape regex metacharacters in a section name. The grammar `[\w-]+` excludes most
+ * metacharacters, but defence-in-depth is cheap here.
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}