@bongos/core 1.19.680 → 1.19.681

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.680",
-  "core_contract": "1.19.680",
-  "source_commit": "e022c08bc3285327348cd482d38e0659e2ae8b3d",
+  "core_version": "1.19.681",
+  "core_contract": "1.19.681",
+  "source_commit": "e31ae913044e78d0b2b8202995eb551dad418a9e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T01:35:27.332Z",
+  "built_at": "2026-09-12T02:05:45.659Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 476,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2624,
-  "tree_sha256": "912d1481802f12085195156ce06ab53a39ca1e159441ebee3efe401ddbedf56d",
+  "tree_sha256": "f249c4df05688bdb744709b348940982241ccc686471029262564d9b79bdd140",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -322,7 +322,7 @@
     {
       "path": ".gitattributes",
       "mode": "0000644",
-      "sha256": "83c94b055dc619fdbf3bc1142fc5357810d901e4200644f1fb399e6939571c5f"
+      "sha256": "72bc38b553e34bc652f0b5b5b2ab24999b4b11c2d6fc3699489e157fd0127a11"
     },
     {
       "path": "CLAUDE.md",
@@ -387,7 +387,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "ba2f6ea9be911785f06761110363357fc1257fb53dadcb51def6194d1f60c9e7"
+      "sha256": "101095af6616b30d3338ec12394343f360d8a583ef3da84f0dce49edc80630cb"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1922,7 +1922,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "dbe27d28100bdbf007baefc90bfc93692b04fc8772019976292260617af175ac"
+      "sha256": "b09110e4eec5225c0594e4f7a3bd3e18878f751ee4697af87209568d69483c3a"
     },
     {
       "path": "docs/architecture.md",
@@ -2797,7 +2797,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "592be55bbe17442266b4478ca962fcc0bdc4cbd66718c6b4af13a1cca911cc3e"
+      "sha256": "244cffb195592c644ad06262ed1a0f610e7744fd62e634a35c5cddd954c9def6"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5732,7 +5732,7 @@
     {
       "path": "modules/lifecycle/github-push.js",
       "mode": "0000644",
-      "sha256": "d50b04376a9725bae0f8fe9c81166224eb47242655fec49f33f89b0f87b555f0"
+      "sha256": "1a84e2225c58969b7bc6c43643921278966c78a6049488deb6c39048982ae005"
     },
     {
       "path": "modules/lifecycle/goal-advisory.js",
@@ -5947,7 +5947,7 @@
     {
       "path": "modules/lifecycle/routes/tasks.js",
       "mode": "0000644",
-      "sha256": "366cb9c60952539ab8a946f8cf757754163b6cd6764a6430777b4529c86c6a75"
+      "sha256": "456b1d53d2349a499e1b07897dc6e16c72d26156a71347382c5a2508dc94d28d"
     },
     {
       "path": "modules/lifecycle/routes/version-route-authz.js",
@@ -7777,12 +7777,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "f0fd6366abe9523c64332de417406bfe0ab6f6872abc6e651debbe5f1941cad0"
+      "sha256": "fd92e4204b64289d8404adb924c9142b47c10b0a6c73d709583cbbad01cd6e0a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "60cff4653b02fd38c3c7fb8673cb423a57f8360955578a6a345ccaef9bf1ac9a"
+      "sha256": "242ae038fbdb23f8d375f04e794c87100df9df4c250b93942ca4eaed82017ca3"
     },
     {
       "path": "public-docs/index.html",
@@ -8332,7 +8332,7 @@
     {
       "path": "scripts/gds/git-merge-regen.js",
       "mode": "0000644",
-      "sha256": "f6f9c93faeb589d07105027655e42bd842d8d766119812b16bd534d58aa50816"
+      "sha256": "9896dc201aaa7186838fe4dcecf5226fdb0736b1b7094a98649e2f8fcbfc4d1a"
     },
     {
       "path": "scripts/gds/go-live.js",
@@ -9542,7 +9542,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "19014335bfaede6fba2e6ff79ba1fe746a2149345e25448b2ed0176bdb8a6649"
+      "sha256": "b06c931aa58a7997f7733e13d2850d290540647c4a7d243cc07d27c20d5b812e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10212,7 +10212,7 @@
     {
       "path": "tests/conflict_resolve.mjs",
       "mode": "0000644",
-      "sha256": "7ad7be450b9350e7888f075944888ddf2a0e2d57a23568f410a9ff17bd340dec"
+      "sha256": "e36410c3288ec8c38c22bd5fd285d7abc6e0cadc4433ce87028bb7f9c7d54806"
     },
     {
       "path": "tests/connections_api.mjs",
@@ -10642,7 +10642,7 @@
     {
       "path": "tests/git_merge_regen.mjs",
       "mode": "0000644",
-      "sha256": "c6cb1bda6809d8d384a9c35b376995af038d18c26b1b935cb5c0faebb163b72e"
+      "sha256": "52f02bc7f0da86b29d4b39da78a34f9677f7bdd93e24a4e5365ffb1af64fc413"
     },
     {
       "path": "tests/github_push_ancestry.mjs",
@@ -12192,7 +12192,7 @@
     {
       "path": "tests/publish_branch_route.mjs",
       "mode": "0000644",
-      "sha256": "485b2b965bcf44a515571de43851c42a32f278dcdd02510f0d3cd9f6ac53e61c"
+      "sha256": "f688f5da9bfc392ce203ee3b89dfa9ba23fd66ca4ebac603f6fb6faedb83b5c7"
     },
     {
       "path": "tests/publish_gate.mjs",

package/.gitattributes

@@ -18,6 +18,7 @@
 *.bash         text eol=lf
 .husky/pre-commit text eol=lf
 .husky/pre-push   text eol=lf
+.husky/post-merge text eol=lf
 
 # Node / Python sources: keep LF everywhere too. Node tolerates CRLF, but LF
 # keeps diffs clean and avoids surprises when these are sourced or piped.
@@ -57,8 +58,13 @@
 # publish-reconciler runs a temp-clone merge with this driver registered, so a PR
 # that conflicts only on these files lands without a human (GitHub's own auto-merge
 # can't run a custom driver, hence the server does the merge locally then pushes).
-# NB: the TOP-LEVEL CLAUDE.md is hand-written and deliberately NOT listed here —
-# only the nested CLAUDE.md docs that carry a generated block are. scripts/gds/CLAUDE.md
+# NB (task 1001431): the TOP-LEVEL CLAUDE.md IS listed now. It used to be excluded as
+# "hand-written", and that was true until ADR 0062 §8 gave its §13 a generated
+# BEGIN/END SESSION-LOG SNIPPET block — after which two sessions each adding a session-log
+# file conflicted there on every merge with nothing to heal it. It is the same shape as
+# docs/file-map.md (hand-written prose + a generated block), not the whole-file shape, so
+# the driver 3-way-merges the prose and re-renders only the snippet; a genuine conflict in
+# the prose still falls through to a normal git conflict. scripts/gds/CLAUDE.md
 # LEFT that set in task 1003548 (its ~40k-char block was 76% of a file loaded on every
 # visit to that directory; docs/repo-map.md still carries the full index), so its entry
 # came out with it — a path listed here whose generator no longer owns it would route a
@@ -72,6 +78,14 @@
 # appear in a merge and these two driver entries never fire. They are KEPT — harmless —
 # as a transition backstop for any in-flight branch that still carries a committed copy;
 # once none remain they can be dropped. The other four entries stay load-bearing.
+# The LEADING SLASH is load-bearing: a gitattributes pattern with no slash matches at ANY
+# depth, so a bare `CLAUDE.md` would also capture all 22 modules/*/CLAUDE.md and
+# scripts/gds/CLAUDE.md — files the driver does NOT know (they are not in NESTED_DIRS, so
+# REGENERABLE has no rule for them). The driver would then exit 1 on each and FORCE a
+# conflict git would otherwise have merged cleanly — the exact 'routed through a driver
+# that cannot regenerate it' failure this file warns about above. `/CLAUDE.md` anchors to
+# the repo root. Verified with `git check-attr merge -- modules/economy/CLAUDE.md`.
+/CLAUDE.md                 merge=otb-regen
 docs/repo-map.md           merge=otb-regen
 docs/file-map.md           merge=otb-regen
 docs/session-log-index.md  merge=otb-regen

package/clients/bongos-client/index.d.ts

@@ -384,7 +384,6 @@ export interface PostTasksIdMergeRequest { into_task_id: number; reason?: string
 export interface PostTasksIdOverrideRequestRequest { rationale: string }
 export interface PostTasksIdOverrideRequestResponse { ok: boolean; request: unknown }
 export interface PostTasksIdPublishBranchRequest { branch: string; head_sha: string; bundle_b64: string; value_summary?: string }
-export interface PostTasksIdPublishBranchResponse { ok: boolean; pr_url: unknown; pr_number: unknown; head_sha: unknown; auto_merge: unknown }
 export interface PostTasksIdShipResponse { ok: boolean; task: unknown }
 export interface PostTasksIdVisualRequest { image_b64: string; content_type: string; alt?: string }
 export interface PostTasksIdVisualResponse { ok: boolean; visual_url: unknown; visual_alt: unknown; bytes: unknown }
@@ -1203,7 +1202,7 @@ export interface BongosClient {
     /** POST /tasks/{id}/promote — rank: metic+archon */
     postTasksIdPromote(args?: RequestArgs): Promise<ApiResponse>;
     /** POST /tasks/{id}/publish-branch — rank: any-builder */
-    postTasksIdPublishBranch(args: RequestArgs & { body: PostTasksIdPublishBranchRequest }): Promise<PostTasksIdPublishBranchResponse>;
+    postTasksIdPublishBranch(args: RequestArgs & { body: PostTasksIdPublishBranchRequest }): Promise<ApiResponse>;
     /** GET /tasks/{id}/publish-status — rank: any-builder */
     getTasksIdPublishStatus(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /tasks/{id}/recommendations — rank: any-builder */

package/docs/api/openapi.json

@@ -15704,14 +15704,7 @@
         },
         "responses": {
           "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostTasksIdPublishBranchResponse"
-                }
-              }
-            }
+            "description": "Success."
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
@@ -22442,25 +22435,6 @@
         ],
         "additionalProperties": false
       },
-      "PostTasksIdPublishBranchResponse": {
-        "type": "object",
-        "properties": {
-          "ok": {
-            "type": "boolean"
-          },
-          "pr_url": {},
-          "pr_number": {},
-          "head_sha": {},
-          "auto_merge": {}
-        },
-        "required": [
-          "ok",
-          "pr_url",
-          "pr_number",
-          "head_sha",
-          "auto_merge"
-        ]
-      },
       "PostTasksIdShipResponse": {
         "type": "object",
         "properties": {
@@ -23019,8 +22993,8 @@
     }
   },
   "x-endpoint-count": 363,
-  "x-schema-count": 402,
+  "x-schema-count": 401,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 271,
+  "x-response-schemas": 270,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/module-api-changelog.md

@@ -1819,5 +1819,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.678 with no explicit bump. run 34657605820. (task 1002620)
   1.19.680 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.679 with no explicit bump. run 34665216511. (task 1002620)
+  1.19.681 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.680 with no explicit bump. run 34666648354. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/github-push.js

@@ -513,8 +513,21 @@ async function openOrFindPullRequest({ branch, title, body }, deps = {}) {
 // without auto-merge enabled, or a PR already mergeable, returns false and the
 // caller surfaces the open PR (exactly like ciLand on a failed enable).
 async function enableAutoMerge({ nodeId }, deps = {}) {
+  return (await enableAutoMergeDetailed({ nodeId }, deps)).ok;
+}
+
+// enableAutoMergeDetailed — the same arming call, but it says WHY it failed
+// (task 1001431). enableAutoMerge collapses every failure to `false`, so the route
+// answered a builder with `auto_merge: false` and no cause, and the single most
+// common cause is not an outage at all: a repository with `allow_auto_merge` OFF
+// can never be armed, so every publish reports the same silent false forever and
+// the PR waits for a human nobody told. Returns { ok, reason } — reason is null on
+// success, else a short scrubbed string safe to hand the (ownership-gated) builder.
+// enableAutoMerge stays the boolean façade so existing callers are untouched.
+async function enableAutoMergeDetailed({ nodeId }, deps = {}) {
   const token = await resolveToken(deps);
-  if (!token || !nodeId) return false;
+  if (!token) return { ok: false, reason: 'no GitHub token could be resolved' };
+  if (!nodeId) return { ok: false, reason: 'the pull request has no node id to arm' };
   const doFetch = deps.fetchImpl || fetch;
   const query = `mutation($id:ID!){enablePullRequestAutoMerge(input:{pullRequestId:$id,mergeMethod:MERGE}){clientMutationId}}`;
   try {
@@ -523,11 +536,15 @@ async function enableAutoMerge({ nodeId }, deps = {}) {
       headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
       body: JSON.stringify({ query, variables: { id: nodeId } }),
     });
-    if (!res.ok) return false;
+    if (!res.ok) return { ok: false, reason: `GitHub GraphQL returned HTTP ${res.status}` };
     const out = await res.json();
-    return !out.errors;
-  } catch (_) {
-    return false;
+    if (!out || !out.errors) return { ok: true, reason: null };
+    // GitHub answers a repo with auto-merge disabled with a plain GraphQL error;
+    // its own message is the actionable one, so pass it through (truncated).
+    const msg = out.errors.map((e) => e && e.message).filter(Boolean).join('; ');
+    return { ok: false, reason: scrubCredential(msg || 'GitHub GraphQL rejected the mutation').slice(0, 300) };
+  } catch (e) {
+    return { ok: false, reason: scrubCredential((e && e.message) || 'the GraphQL request threw').slice(0, 300) };
   }
 }
 
@@ -1388,6 +1405,7 @@ module.exports = {
   pushBundle,
   openOrFindPullRequest,
   enableAutoMerge,
+  enableAutoMergeDetailed,
   getPublishStatus,
   getMergeState,
   mergeIfGreen,

package/modules/lifecycle/routes/tasks.js

@@ -67,6 +67,33 @@ const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, deHashRefs, detectsMigration,
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
 const registerTaskWriteRoutes = require('./task-write-routes.js'); // task 1003206 — POST /tasks + PATCH /tasks/:id
+// The body of the generic `publish_failed` 500 from POST /tasks/:id/publish-branch.
+// Pure and exported so the response a builder actually receives is testable without
+// standing up the route (the file's existing convention — see rankAttestsGateTrust).
+//
+// task 1001431 added `code` + `detail`. Seven error codes get their own mapped response
+// above the fallthrough; every OTHER code github-push can throw — APP_TOKEN_FAILED,
+// GRAPHQL_FAILED, BAD_PR, PR_PATCH_FAILED, STATUS_FETCH_FAILED — arrived here and was
+// dropped on the floor, so the builder saw a bare `publish_failed` with nothing to act
+// on and no way to tell an expired App token from a GraphQL outage. The code is an
+// internal constant rather than user data, and this route is ownership-gated (claim
+// holder or Archon) and already returns scrubbed git stderr — a short code name is
+// strictly less revealing than what it ships beside.
+//
+// Every field stays OPTIONAL and keeps its existing name and meaning: ship.js prints
+// `reason`, and older readers must not start seeing a key change shape under them.
+function publishFailedDetail(e = {}) {
+  return {
+    ...(e.code ? { code: e.code } : {}),
+    ...(e.detail ? { detail: e.detail } : {}),
+    ...(e.git_step ? { step: e.git_step } : {}),
+    ...(e.stderr ? { reason: e.stderr } : {}),
+    ...(e.stderr_bytes != null ? { reason_bytes: e.stderr_bytes } : {}),
+    ...(e.exit_code != null ? { git_exit_code: e.exit_code } : {}),
+    ...(e.timed_out ? { timed_out: true } : {}),
+  };
+}
+
 module.exports = function buildTasksRouter() {
   const router = express.Router();
 
@@ -1076,7 +1103,11 @@ module.exports = function buildTasksRouter() {
         `Merging triggers .github/workflows/deploy-prod.yml -> ${branding().domains.publicOrigin}. ` +
         `Auto-merge is enabled — GitHub lands it once the required checks pass.`;
       const pr = await githubPush.openOrFindPullRequest({ branch, title, body });
-      const autoMerge = await githubPush.enableAutoMerge({ nodeId: pr.node_id });
+      // task 1001431: ask WHY when arming fails. `auto_merge: false` on its own told the
+      // builder nothing, and the commonest cause is a repo with allow_auto_merge OFF —
+      // a permanent condition that reads exactly like a transient blip.
+      const autoMergeResult = await githubPush.enableAutoMergeDetailed({ nodeId: pr.node_id });
+      const autoMerge = autoMergeResult.ok;
       // task 1139 (ADR 0058): attest the author's trust tier on the pushed sha so the
       // gate-review check can auto-approve a Metic+ author's gate-surface PR with no
       // owner click. Only the SERVER can set this (it holds req.builder's server-
@@ -1098,6 +1129,8 @@ module.exports = function buildTasksRouter() {
       }
       return res.status(201).json({
         ok: true, pr_url: pr.url, pr_number: pr.number, head_sha: pushedSha, auto_merge: autoMerge,
+        // Only present when arming failed — the publish itself still succeeded (201).
+        ...(autoMerge ? {} : { auto_merge_reason: autoMergeResult.reason }),
       });
     } catch (e) {
       if (e.code === 'TIP_MISMATCH') {
@@ -1134,13 +1167,7 @@ module.exports = function buildTasksRouter() {
       // `reason` keeps its name and position so existing readers (ship.js prints it)
       // keep working; it is simply no longer amputated. Everything here is already
       // credential-scrubbed at the throw site by github-push.scrubCredential.
-      return res.fail('publish_failed', 500, {
-        ...(e.git_step ? { step: e.git_step } : {}),
-        ...(e.stderr ? { reason: e.stderr } : {}),
-        ...(e.stderr_bytes != null ? { reason_bytes: e.stderr_bytes } : {}),
-        ...(e.exit_code != null ? { git_exit_code: e.exit_code } : {}),
-        ...(e.timed_out ? { timed_out: true } : {}),
-      });
+      return res.fail('publish_failed', 500, publishFailedDetail(e));
     } finally {
       try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
     }
@@ -1336,6 +1363,7 @@ module.exports.MIGRATION_KEYWORD_RE = MIGRATION_KEYWORD_RE;
 // #871: exported so tests/task_ownership_gate.mjs can drive the claim-ownership
 // gate directly (with a stubbed db.getLastClaimHolder) — no server/DB needed.
 module.exports.gateTaskOwnership = gateTaskOwnership;
+module.exports.publishFailedDetail = publishFailedDetail;
 // task 1053 (F): exported so the verify-attestation guard is unit-tested.
 module.exports.isVerifyTask = isVerifyTask;
 // task 1139 / 1169 (ADR 0058): exported so the pure rank-attestation decision

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.680",
+  "version": "1.19.681",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.680",
+      "version": "1.19.681",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.680",
+  "version": "1.19.681",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

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/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.680'; // 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);