@bongos/core 1.19.679 → 1.19.681

package/scripts/gds/git-merge-regen.js

@@ -16,6 +16,13 @@
 //     mergeMainIntoBranch self-heal so the heal runs even where the driver isn't
 //     installed per-clone.
 //
+// THE DRIVER ONLY FIRES ON A CONFLICT. A merge that lands CLEAN still leaves the
+// generated docs describing the pre-merge tree — new symbols, a new session log and a
+// new skill all arrive without conflicting. Three things close that: ship.js (at ship
+// time), the server's conflict-resolve.js step 7b (for a PR it resolves), and
+// `.husky/post-merge` (task 1001431) for the bare local `git merge` / `git pull` that
+// neither of those covers.
+//
 // SAFETY: it regenerates the GENERATED content and 3-way-merges the hand-written
 // parts of nested docs; it succeeds ONLY if no conflict markers remain. A genuine
 // hand-written conflict falls through to a normal git conflict — it never invents a
@@ -61,7 +68,13 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 // branches that both touch hall/status/landing copy regenerate them differently
 // and conflict on ordinary text; they join the whole-file group for the same
 // reason session-log-index.md did.
+// task 1001431: the ROOT CLAUDE.md joined too. It is mostly hand-written, but §13 carries
+// the bounded BEGIN/END GENERATED SESSION-LOG SNIPPET block (ADR 0062 §8) — so two sessions
+// that each add a session-log file regenerate that block differently and ALWAYS conflict
+// there, and nothing healed it: the driver did not know the file, and `merge=union` would be
+// wrong for prose. Same shape as docs/file-map.md (3-way-merge the prose, re-render the block).
 const REGENERABLE = new Set([
+  'CLAUDE.md',
   'docs/repo-map.md',
   'docs/file-map.md',
   'docs/session-log-index.md',
@@ -124,6 +137,22 @@ function regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {})
     return { content: CI.renderReport(CI.buildRegistry()), ok: true };
   }
 
+  // The ROOT CLAUDE.md (task 1001431): hand-written prose carrying ONE generated block, the
+  // §13 session-log snippet. 3-way-merge the prose, then re-render the snippet from the
+  // session-log files on disk. Must be handled BEFORE the nested-CLAUDE.md fallthrough below,
+  // which derives a directory by stripping `/CLAUDE.md` — for the root path that strips
+  // nothing and would ask gen-repo-map for a symbol block for a directory named "CLAUDE.md".
+  // It also needs none of the code-symbol model, so it sits with the other pre-buildModel rules.
+  //   Same provisionality caveat as the whole-file rules above: collectEntries() scans the
+  // working tree, which during a merge is still ours, so the block this writes describes our
+  // side. That is what makes the merge COMPLETE; the post-merge regeneration (conflict-resolve
+  // step 7b / ship-preflight-steps' resolveInWorktree) is what makes it CORRECT.
+  if (relpath === 'CLAUDE.md') {
+    const merged = threeWayMerge(base, ours, theirs);
+    const out = SI.injectSnippet(merged, SI.renderSnippet(SI.collectEntries()));
+    return { content: out, ok: !hasMarkers(out) };
+  }
+
   const model = G.buildModel();
 
   // docs/repo-map.md is fully generated — ignore all three sides, rebuild it.

package/scripts/gds/upgrade.js

@@ -521,7 +521,20 @@ function healDocAssets({ coreRoot }, run = spawnSync, fsImpl = fs) {
   return { ok: failed.length === 0, ran, failed, missing };
 }
 
-function restartService({ service, restartCmd }, run = spawnSync) {
+// Restart the instance service so the newly-installed core becomes the one being SERVED.
+// Escalation is the whole difficulty here (task 1002884). A provisioned instance runs under a
+// `User=` systemd unit, and the unattended sweep that restarts it has no TTY — so a bare
+// `systemctl restart` from the owning (non-root) user returns "Interactive authentication
+// required" and exits 1. We retry once through `sudo -n`, the same idiom dev.js and dev-lib.js
+// already use for privileged systemctl; `-n` fails fast rather than blocking on a password
+// prompt, so the retry costs nothing when it isn't permitted. An operator who prefers polkit
+// over sudo can install the rule in docs/recipes/instance-service-restart.md instead — either
+// path makes this return ok.
+// `--restart-cmd` is NOT escalated: an explicit command is the operator's own contract.
+// Trust boundary: `service` comes from `--service` or the subscription roster — operator-supplied
+// config, never request input — and the escalation reaches only as far as the host's own sudoers
+// or polkit scoping allows. Do not wire a caller that derives `service` from anything untrusted.
+function restartService({ service, restartCmd }, run = spawnSync, deps = {}) {
   if (restartCmd) {
     const parts = restartCmd.split(/\s+/);
     const r = run(parts[0], parts.slice(1), { stdio: 'inherit' });
@@ -529,7 +542,14 @@ function restartService({ service, restartCmd }, run = spawnSync) {
   }
   if (service) {
     const r = run('systemctl', ['restart', service], { stdio: 'inherit' });
-    return { ok: !!r && !r.error && r.status === 0, code: r && r.status };
+    if (r && !r.error && r.status === 0) return { ok: true, code: 0 };
+    const isRoot = deps.isRoot !== undefined
+      ? !!deps.isRoot
+      : (typeof process.getuid === 'function' && process.getuid() === 0);
+    if (isRoot) return { ok: false, code: r && r.status };
+    const s = run('sudo', ['-n', 'systemctl', 'restart', service], { stdio: 'inherit' });
+    const ok = !!s && !s.error && s.status === 0;
+    return { ok, code: ok ? 0 : (s && s.status), triedSudo: true, directCode: r && r.status };
   }
   return { ok: null, skipped: true };
 }
@@ -622,6 +642,68 @@ async function pollHealth(healthUrl, deps = {}) {
   }
 }
 
+// ---- served-version verification (task 1002884) -----------------------------
+// The gap this closes: after a restart, `readInstalledCoreVersion` reads node_modules on DISK
+// and `pollHealth` proves only that *something* answers the port. Neither can tell "the new core
+// is up" from "the old core never went down" — so when a restart silently failed on
+// cloudbongos.com (2026-08-11), the health poll hit the STILL-RUNNING old process, got 200, and
+// the bump reported "✓ upgrade complete" while live kept serving the previous core.
+// `/version` reports the LIVE process's coreVersion (serve-internal.js, since 1.17.2), which is
+// the one signal that distinguishes the two.
+
+// Default the version endpoint to /version on the same origin as the health URL. Deriving rather
+// than demanding a second flag is deliberate: every existing call site passes only --health-url,
+// and a check that has to be opted into is off exactly where it is needed. Returns null when the
+// health URL isn't parseable as one.
+function deriveVersionUrl(healthUrl) {
+  try {
+    const u = new URL(healthUrl);
+    u.pathname = '/version';
+    u.search = '';
+    u.hash = '';
+    return u.toString();
+  } catch { return null; }
+}
+
+// Poll the version endpoint until it yields a parseable coreVersion or the budget elapses. Runs
+// AFTER the health poll, so the service is already answering and the budget is short — this is
+// re-reading a live endpoint, not waiting for a boot. A body without a usable coreVersion is
+// "unreadable", NOT a mismatch: the caller must be able to tell "it says the wrong version"
+// (a real failure) from "it wouldn't tell me" (unconfirmed), because only the first is proof.
+async function pollServedVersion(versionUrl, deps = {}) {
+  const fetchImpl = deps.fetch || fetch;
+  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = deps.now || Date.now;
+  // Default to the health budget when a caller (or a test) has already narrowed it, else 15s.
+  const budgetMs = deps.versionBudgetMs != null
+    ? deps.versionBudgetMs
+    : (deps.healthBudgetMs != null ? deps.healthBudgetMs : 15_000);
+  // A hard attempt cap alongside the clock: `now` is injectable, and a frozen or non-advancing
+  // clock would otherwise spin this loop forever instead of giving up.
+  const maxAttempts = deps.versionMaxAttempts != null ? deps.versionMaxAttempts : 12;
+  const deadline = now() + budgetMs;
+  let attempt = 0;
+  let last = { ok: false, error: 'not attempted' };
+  for (;;) {
+    attempt++;
+    try {
+      const res = await fetchImpl(versionUrl, { signal: AbortSignal.timeout(5_000) });
+      if (!res || !res.ok) last = { ok: false, error: `status ${res && res.status}` };
+      else if (typeof res.json !== 'function') last = { ok: false, error: 'response carried no JSON body' };
+      else {
+        const body = await res.json();
+        const version = body && typeof body.coreVersion === 'string' ? body.coreVersion : null;
+        if (version) return { ok: true, version, attempts: attempt };
+        last = { ok: false, error: 'no coreVersion in the response body' };
+      }
+    } catch (e) {
+      last = { ok: false, error: e.message };
+    }
+    if (now() >= deadline || attempt >= maxAttempts) return { ...last, attempts: attempt, timedOut: true };
+    await sleep(Math.min(2_000, 500 * attempt));
+  }
+}
+
 // ---- integrity-pin verification (task 1002216 / audit H8, finding F1) --------
 // The packager (package-core.js) computes tree_sha256 = canonicalTreeHash over the
 // redacted core files (+ the two synthesized files) and records it, the per-file
@@ -738,7 +820,9 @@ async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts },
   else err(`  ! reinstall of previous core failed (${inst.reason || 'exit ' + inst.code}) — the instance may need manual repair`);
 
   // 3. restart back onto the previous core.
-  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run);
+  // `deps` is passed here for the same reason the forward path passes it: this restart runs
+  // AFTER a failure, so its sudo-escalation is the one that matters most and must be testable.
+  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run, deps);
   if (rs.skipped) log('  • restart: no --service/--restart-cmd — restart the instance service manually to load the reverted core.');
   else if (!rs.ok) err(`  ! restart after rollback failed (exit ${rs.code}) — restart the service manually.`);
   else log(`  ✓ restarted ${opts.service || 'service'} on the previous core`);
@@ -961,10 +1045,24 @@ async function runUpgrade(opts, deps = {}) {
   } else log('  • doc regen skipped (--skip-regen-docs)');
 
   // 6. restart.
-  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run);
+  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run, deps);
   if (rs.skipped) log(`  • restart: no --service/--restart-cmd — restart the instance service to load core ${targetVersion}.`);
-  else if (!rs.ok) err(`  ! restart command failed (exit ${rs.code}) — restart the service manually.`);
-  else log(`  ✓ restarted ${opts.service || 'service'}`);
+  else if (!rs.ok) {
+    // task 1002884: a failed restart is an upgrade FAILURE, not a warning. It used to fall
+    // through to the verification below — but the old process is still up, so the health poll
+    // passed against IT and the bump wrote a success row for a core that was never served.
+    // Failing here also keeps disk and process consistent: rollback puts the previous core back
+    // on disk, matching the one that is (still) running.
+    err(`  ✖ restart failed (exit ${rs.code})${rs.triedSudo ? ` — \`systemctl restart\` exited ${rs.directCode} and \`sudo -n systemctl restart\` could not escalate` : ''}`);
+    err('    The previous core is still the one being served. Grant the restart a non-interactive path');
+    err('    (sudoers NOPASSWD or a polkit rule — docs/recipes/instance-service-restart.md), then re-run.');
+    const error = `restart failed (exit ${rs.code}) — the instance is still running the previous core`;
+    if (rollbackOnFailure && snapshot) {
+      const rb = await doRollback('restart failed');
+      return { ok: false, error, fromVersion, toVersion: targetVersion, restartOk: false, rolledBack: true, rollback: rb };
+    }
+    return { ok: false, error, fromVersion, toVersion: targetVersion, restartOk: false };
+  } else log(`  ✓ restarted ${opts.service || 'service'}${rs.triedSudo ? ' (via sudo -n)' : ''}`);
 
   // 7. verify: installed version == target, optional /healthz, ledger row.
   const installed = readInstalledCoreVersion(instanceDir, fsImpl);
@@ -985,12 +1083,48 @@ async function runUpgrade(opts, deps = {}) {
     log('  • no managed restart + no --health-url — new core installed but not confirmed serving; restart the instance + health-check it to complete the bump.');
   }
 
+  // 7b. Confirm the SERVED process actually swapped (task 1002884). Everything above this point
+  //     can be true of an instance still running the OLD core: the pin moved, node_modules holds
+  //     the new version, and /healthz answers 200 — from the process that never went down. Only
+  //     the live coreVersion settles it.
+  //     A definite MISMATCH is a failure (same treatment as a failed health check). Being unable
+  //     to READ the endpoint is not: an instance may not expose it, and refusing every such bump
+  //     would be a worse regression than the false-pass. Passing --version-url explicitly asks
+  //     for proof, so there an unreadable endpoint IS a failure.
+  let servedOk = null;
+  let servedVersion = null;
+  const versionUrl = opts.versionUrl || (opts.healthUrl ? deriveVersionUrl(opts.healthUrl) : null);
+  if (opts.healthCheck === false) {
+    // --no-health-check is the documented opt-out from confirming the bump serves; it covers this.
+  } else if (versionUrl && healthOk !== false) {
+    const sv = await pollServedVersion(versionUrl, deps);
+    servedVersion = sv.version || null;
+    if (sv.ok && servedVersion === targetVersion) {
+      servedOk = true;
+      log(`  ✓ served core version: ${servedVersion} (${versionUrl})`);
+    } else if (sv.ok) {
+      servedOk = false;
+      err(`  ! served core version is ${servedVersion} but the target is ${targetVersion} (${versionUrl})`);
+      err('    The restart did not swap the running process — the old core is still being served.');
+    } else if (opts.versionUrl) {
+      servedOk = false;
+      err(`  ! could not read ${versionUrl} (${sv.error}) — --version-url was given, so this bump cannot be confirmed`);
+    } else {
+      err(`  ! could not read ${versionUrl} (${sv.error}) — this bump is NOT confirmed against the running process.`);
+      err('    Pass --version-url <url> if this instance serves its version elsewhere.');
+    }
+  }
+
   // A failed post-restart health check means the new core is serving broken — auto-revert (task
-  // 2149) instead of recording an "upgraded" row + leaving the instance down. The rollback writes
-  // its OWN rolled_back ledger row, so skip the normal insert below.
-  if (healthOk === false && rollbackOnFailure && snapshot) {
-    const rb = await doRollback('health check failed after restart');
-    return { ok: false, error: `health check failed after restart — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk: false, rolledBack: true, rollback: rb };
+  // 2149) instead of recording an "upgraded" row + leaving the instance down. A served-version
+  // mismatch means the new core is not serving AT ALL (task 1002884) and reverts the same way.
+  // The rollback writes its OWN rolled_back ledger row, so skip the normal insert below.
+  if ((healthOk === false || servedOk === false) && rollbackOnFailure && snapshot) {
+    const why = healthOk === false
+      ? 'health check failed after restart'
+      : `served core version did not change (still ${servedVersion || 'unconfirmed'}, expected ${targetVersion})`;
+    const rb = await doRollback(why);
+    return { ok: false, error: `${why} — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, rolledBack: true, rollback: rb };
   }
 
   const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: opts.note }, deps);
@@ -1010,9 +1144,9 @@ async function runUpgrade(opts, deps = {}) {
     dryRun: opts.dryRun,
   }, run, log, err);
 
-  const ok = versionOk && healthOk !== false;
+  const ok = versionOk && healthOk !== false && servedOk !== false;
   log(ok ? `\n✓ upgrade complete — core ${fromVersion || '(none)'} → ${targetVersion}` : `\n! upgrade finished with warnings — review above.`);
-  return { ok, fromVersion, toVersion: targetVersion, versionOk, healthOk, ledger: ledger.ok, pin };
+  return { ok, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, ledger: ledger.ok, pin };
 }
 
 function parseArgs(argv) {
@@ -1023,6 +1157,7 @@ function parseArgs(argv) {
     service: arg('--service', argv),
     restartCmd: arg('--restart-cmd', argv),
     healthUrl: arg('--health-url', argv),
+    versionUrl: arg('--version-url', argv), // task 1002884: read the LIVE process's coreVersion back; defaults to /version on the health URL's origin
     sourceCommit: arg('--source-commit', argv),
     note: arg('--note', argv),
     pinPath: arg('--pin-path', argv),
@@ -1058,7 +1193,8 @@ async function main(argv = process.argv.slice(2)) {
       '  --service <unit>     systemd unit to restart after applying',
       '  --restart-cmd <cmd>  explicit restart command (overrides --service)',
       '  --health-url <url>   poll after restart (~30s) until 2xx; a still-failing check fails the bump (auto-rollback). REQUIRED for a bump that restarts the service, unless --no-health-check.',
-      '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves)',
+      '  --version-url <url>  read the RUNNING process\'s coreVersion back after restart and require it to equal --to (default: /version on the --health-url origin). A health check alone cannot tell a new core from an old one that never went down.',
+      '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves); also skips the served-version read-back',
       '  --skip-migrate       do not run `npm run migrate`',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
@@ -1069,8 +1205,8 @@ async function main(argv = process.argv.slice(2)) {
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',
-      'Full bump: pre-flight → bump pin → npm install → verify integrity pin → migrate → materialize .claude → regen API docs+client → restart → verify.',
-      'On a failure after the pin moves (install/pin-verify/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
+      'Full bump: pre-flight → bump pin → npm install → verify integrity pin → migrate → materialize .claude → regen API docs+client → restart → verify (health + served coreVersion).',
+      'On a failure after the pin moves (install/pin-verify/migrate/restart/health/served-version), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
     ].join('\n') + '\n');
     return 0;
   }
@@ -1087,7 +1223,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
+  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth, deriveVersionUrl, pollServedVersion,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.679'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.681'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/conflict_resolve.mjs

@@ -554,6 +554,11 @@ test('1003546 every REGENERABLE artifact has a producer, and every producer is i
     ['docs/repo-map.md', 'scripts/gds/gen-repo-map.js'],
     ['docs/file-map.md', 'scripts/gds/gen-file-map.js'],
     ['docs/session-log-index.md', 'scripts/gds/gen-session-index.js'],
+    // task 1001431 — the ROOT CLAUDE.md joined REGENERABLE for its §13 snippet block.
+    // gen-session-index.js writes BOTH the (gitignored) whole index and that tracked
+    // snippet, and it is already in GENERATOR_SCRIPTS, so the server's post-merge
+    // regeneration covers the new entry with no change to the generator list.
+    ['CLAUDE.md', 'scripts/gds/gen-session-index.js'],
     [CI.REGISTRY_REL, 'scripts/gds/copy-inventory.js'],
     [CI.REPORT_REL, 'scripts/gds/copy-inventory.js'],
     ...G.NESTED_DIRS.map((d) => [`${d}/CLAUDE.md`, 'scripts/gds/gen-repo-map.js']),

package/tests/git_merge_regen.mjs

@@ -45,6 +45,7 @@ const repo = path.resolve(here, '..');
 const regen = require('../scripts/gds/git-merge-regen.js');
 const G = require('../scripts/gds/gen-repo-map.js');
 const CI = require('../scripts/gds/copy-inventory.js');
+const SI = require('../scripts/gds/gen-session-index.js'); // task 1001431 — the root CLAUDE.md's §13 snippet
 
 const MARKERS = /^(<{7}|={7}|>{7})/m;
 
@@ -120,10 +121,67 @@ function withBlockBody(src, body) {
 
 // ── 5) a non-generated path is never in scope ───────────────────────────────────
 {
-  assert.equal(regen.REGENERABLE.has('CLAUDE.md'), false, 'top-level CLAUDE.md is hand-written — never auto-healed');
   assert.equal(regen.REGENERABLE.has('scripts/gds/box.js'), false, 'source files are never auto-healed');
   const r = regen.regenerateResolved('scripts/gds/box.js', { base: 'a', ours: 'b', theirs: 'c' });
   assert.equal(r.content, null, 'a non-generated path resolves to null content');
+
+  // REVERSAL (task 1001431). This block used to assert the opposite —
+  //   REGENERABLE.has('CLAUDE.md') === false, 'top-level CLAUDE.md is hand-written'
+  // — and that was correct when it was written. ADR 0062 §8 then gave the root
+  // CLAUDE.md a generated §13 BEGIN/END SESSION-LOG SNIPPET block, which made the
+  // premise false without anything noticing: two sessions each adding a session-log
+  // file regenerate that block differently and conflict there on EVERY merge, and no
+  // layer healed it (not the driver, not ship.js, not the server resolver).
+  assert.equal(regen.REGENERABLE.has('CLAUDE.md'), true,
+    'the root CLAUDE.md carries a generated §13 snippet block and IS healed (task 1001431)');
+}
+
+// ── 5b) the root CLAUDE.md heals: prose 3-way-merged, snippet re-rendered ────────
+// It is the docs/file-map.md shape (hand-written prose + a generated block), NOT the
+// whole-file shape — so a conflict in the PROSE must still fall through to a human.
+{
+  const realRoot = fs.readFileSync(path.join(repo, 'CLAUDE.md'), 'utf8');
+  const freshSnippet = SI.renderSnippet(SI.collectEntries());
+
+  // A conflict confined to the generated block heals, and the block comes out equal to
+  // a fresh render regardless of what either side had in it.
+  const mangle = (tag) => SI.injectSnippet(realRoot, `${SI.BEGIN}\n- ${tag}\n${SI.END}`);
+  const healed = regen.regenerateResolved('CLAUDE.md', {
+    base: realRoot, ours: mangle('OURS entry'), theirs: mangle('THEIRS entry'),
+  });
+  assert.equal(healed.ok, true, 'a conflict inside the generated snippet must heal');
+  assert.ok(!MARKERS.test(healed.content), 'no conflict markers survive the heal');
+  assert.ok(healed.content.includes(freshSnippet), 'the snippet is re-rendered from the session-log files');
+  assert.ok(!healed.content.includes('OURS entry') && !healed.content.includes('THEIRS entry'),
+    'neither side\'s stale snippet content survives');
+
+  // Hand-written PROSE that genuinely diverges is NOT auto-resolved.
+  const firstNL = realRoot.indexOf('\n');
+  const proseConflict = regen.regenerateResolved('CLAUDE.md', {
+    base: realRoot,
+    ours: '# OURS heading' + realRoot.slice(firstNL),
+    theirs: '# THEIRS heading' + realRoot.slice(firstNL),
+  });
+  assert.equal(proseConflict.ok, false, 'a real prose conflict must fall through to a human');
+}
+
+// ── 5c) the .gitattributes pattern for the root CLAUDE.md is ROOT-ANCHORED ───────
+// `/CLAUDE.md` vs `CLAUDE.md` is the whole ballgame: a gitattributes pattern with no
+// slash matches at ANY depth, so the bare spelling would also capture the 22
+// modules/*/CLAUDE.md files and scripts/gds/CLAUDE.md — none of which are in
+// NESTED_DIRS, so the driver has no rule for them, exits 1, and FORCES a conflict git
+// would otherwise merge cleanly. Asserted through git itself, not by reading the file,
+// because the pattern semantics are git's and not ours to restate.
+{
+  const attr = (p) => {
+    const r = spawnSync('git', ['check-attr', 'merge', '--', p], { cwd: repo, encoding: 'utf8' });
+    return (r.stdout || '').trim();
+  };
+  assert.match(attr('CLAUDE.md'), /otb-regen$/, 'the root CLAUDE.md must get the driver');
+  for (const p of ['modules/economy/CLAUDE.md', 'scripts/gds/CLAUDE.md']) {
+    assert.doesNotMatch(attr(p), /otb-regen/,
+      `${p} is not regenerable — the root pattern must be anchored so it is not captured`);
+  }
 }
 
 // ── 6) END-TO-END: a real `git merge` invokes the driver and auto-resolves ──────
@@ -193,7 +251,11 @@ function withBlockBody(src, body) {
     .filter((line) => line && !line.startsWith('#'))
     .map((line) => line.split(/\s+/))
     .filter((tokens) => tokens.slice(1).includes('merge=otb-regen'))
-    .map((tokens) => tokens[0]);
+    // Strip a leading `/`: in a gitattributes pattern that is a ROOT ANCHOR, not part of
+    // the path (task 1001431 — `/CLAUDE.md` must not also match modules/*/CLAUDE.md). The
+    // driver receives git's %P, which never carries it, so REGENERABLE keys are unanchored
+    // and the two lists are compared as the PATH sets they are.
+    .map((tokens) => tokens[0].replace(/^\//, ''));
   assert.ok(otbRegenPaths.length > 0, 'expected at least one merge=otb-regen line in .gitattributes');
   for (const p of otbRegenPaths) {
     assert.ok(regen.REGENERABLE.has(p), `.gitattributes declares merge=otb-regen for ${p} but REGENERABLE (git-merge-regen.js) does not know it`);

package/tests/publish_branch_route.mjs

@@ -194,6 +194,63 @@ await t('enableAutoMerge: posts the graphql mutation; false on a graphql error',
   assert.equal(await gp.enableAutoMerge({ nodeId: null }, { token: 'TT', fetchImpl: okFetch }), false, 'no node id → false');
 });
 
+// ---- publishFailedDetail: the generic 500 names its cause (task 1001431) --
+await t('publishFailedDetail: threads the error code so publish_failed is never bare', async () => {
+  const D = buildTasksRouter.publishFailedDetail;
+
+  // The regression this closes: a code with no git_step/stderr used to produce {}, so the
+  // builder received `publish_failed` and nothing else — an expired App token and a
+  // GraphQL outage were indistinguishable.
+  assert.deepEqual(D({ code: 'APP_TOKEN_FAILED' }), { code: 'APP_TOKEN_FAILED' });
+  assert.deepEqual(D({ code: 'GRAPHQL_FAILED', detail: '[{"type":"FORBIDDEN"}]' }),
+    { code: 'GRAPHQL_FAILED', detail: '[{"type":"FORBIDDEN"}]' });
+
+  // Existing field names + meanings are unchanged — ship.js prints `reason`.
+  assert.deepEqual(
+    D({ code: 'GIT_FAILED', git_step: 'push', stderr: 'Permission denied', stderr_bytes: 17, exit_code: 128, timed_out: true }),
+    { code: 'GIT_FAILED', step: 'push', reason: 'Permission denied', reason_bytes: 17, git_exit_code: 128, timed_out: true }
+  );
+
+  // Absent fields stay absent rather than serializing as null/undefined keys.
+  assert.deepEqual(D({}), {});
+  assert.deepEqual(D(), {});
+  assert.equal('timed_out' in D({ timed_out: false }), false, 'a falsy timed_out is omitted, not sent as false');
+  assert.equal('git_exit_code' in D({ exit_code: 0 }), true, 'exit_code 0 is real and must survive');
+});
+
+// ---- enableAutoMergeDetailed: says WHY it could not arm (task 1001431) ----
+await t('enableAutoMergeDetailed: reports the GitHub message instead of a bare false', async () => {
+  const okFetch = async () => jsonRes(200, { data: { enablePullRequestAutoMerge: {} } });
+  assert.deepEqual(await gp.enableAutoMergeDetailed({ nodeId: 'N1' }, { token: 'TT', fetchImpl: okFetch }),
+    { ok: true, reason: null });
+
+  // The real-world case: a repository with allow_auto_merge OFF. GitHub answers with a
+  // plain GraphQL error, and its own message is the actionable one.
+  const offFetch = async () => jsonRes(200, { errors: [{ message: 'Auto-merge is not allowed for this repository' }] });
+  const off = await gp.enableAutoMergeDetailed({ nodeId: 'N1' }, { token: 'TT', fetchImpl: offFetch });
+  assert.equal(off.ok, false);
+  assert.match(off.reason, /Auto-merge is not allowed/, 'the repo-level cause reaches the caller');
+
+  const httpFetch = async () => jsonRes(502, {});
+  const http = await gp.enableAutoMergeDetailed({ nodeId: 'N1' }, { token: 'TT', fetchImpl: httpFetch });
+  assert.equal(http.ok, false);
+  assert.match(http.reason, /HTTP 502/, 'an HTTP failure is distinguishable from a rejection');
+
+  const thrown = await gp.enableAutoMergeDetailed({ nodeId: 'N1' }, {
+    token: 'TT', fetchImpl: async () => { throw new Error('socket hang up'); },
+  });
+  assert.equal(thrown.ok, false);
+  assert.match(thrown.reason, /socket hang up/);
+
+  assert.equal((await gp.enableAutoMergeDetailed({ nodeId: null }, { token: 'TT', fetchImpl: okFetch })).ok, false);
+  assert.match((await gp.enableAutoMergeDetailed({ nodeId: null }, { token: 'TT', fetchImpl: okFetch })).reason,
+    /no node id/, 'a missing node id is named, not silently false');
+
+  // The boolean façade keeps its exact contract for every existing caller.
+  assert.equal(await gp.enableAutoMerge({ nodeId: 'N1' }, { token: 'TT', fetchImpl: okFetch }), true);
+  assert.equal(await gp.enableAutoMerge({ nodeId: 'N1' }, { token: 'TT', fetchImpl: offFetch }), false);
+});
+
 // ---- getPublishStatus: the three states -----------------------------------
 await t('getPublishStatus: open PR → pending; merged + deploy success → success', async () => {
   const mergeSha = 'c'.repeat(40);