@bongos/core 1.19.680 → 1.19.682

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.682",
+  "core_contract": "1.19.682",
+  "source_commit": "b499e76b5b34ee8e7e753b7b89a3f6e1e8874224",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T01:35:27.332Z",
+  "built_at": "2026-09-12T16:22:24.694Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 476,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2624,
-  "tree_sha256": "912d1481802f12085195156ce06ab53a39ca1e159441ebee3efe401ddbedf56d",
+  "tree_sha256": "a8aca2d995556a722b4debefe87ae388610d584d4954da4285b7dbf0a642eef4",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -322,7 +322,7 @@
     {
       "path": ".gitattributes",
       "mode": "0000644",
-      "sha256": "83c94b055dc619fdbf3bc1142fc5357810d901e4200644f1fb399e6939571c5f"
+      "sha256": "38bf33dd14a7bff6545f961c4f30172ac850f6a0578900a3c10295c4fc0f27e9"
     },
     {
       "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": "1f62636e946a5b5bbf9b546d2e532b704db15ca21c3a9d0e71f5a8b17cde150b"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5642,7 +5642,7 @@
     {
       "path": "modules/lifecycle/conflict-resolve.js",
       "mode": "0000644",
-      "sha256": "1a281a4233b3805550a05ed6bd38b163ab18db658d48675f055b90d2ba722a16"
+      "sha256": "3e20f4965d1d83d17f8e777201bd7e4fd7857843295180542914de16ae51e936"
     },
     {
       "path": "modules/lifecycle/criterion-suggest.js",
@@ -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": "db81ab75a6e749de67b91e13f3605d79a58a90b2e57c83332f535d48273dabcb"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "60cff4653b02fd38c3c7fb8673cb423a57f8360955578a6a345ccaef9bf1ac9a"
+      "sha256": "f4d50516d2a3a9ee031a89735502c1c8ec01789eeb4dfa3fd20da07713679279"
     },
     {
       "path": "public-docs/index.html",
@@ -8282,7 +8282,7 @@
     {
       "path": "scripts/gds/gen-api-client.js",
       "mode": "0000644",
-      "sha256": "d363c76caf379a051faea40a2497db8bbba18effd68e9cd9922e9445638c57c5"
+      "sha256": "2d8b35709e19b339bc55c57237f2add36fa6bdeb83a9b036faa902b0c4b8e3f9"
     },
     {
       "path": "scripts/gds/gen-api-docs.js",
@@ -8332,7 +8332,7 @@
     {
       "path": "scripts/gds/git-merge-regen.js",
       "mode": "0000644",
-      "sha256": "f6f9c93faeb589d07105027655e42bd842d8d766119812b16bd534d58aa50816"
+      "sha256": "9d65420d85f20d10dba3af63c45d8dd0425ee11dd3d5cfa14d3019abf7354aed"
     },
     {
       "path": "scripts/gds/go-live.js",
@@ -8372,7 +8372,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "1d63c1485820ad2e81e97979402eabd3829e86503f4c06318a251dc3a6874047"
+      "sha256": "b0971625852fca93ca474d2f9e31e3601397f1b9efbef3241a0b0c47f17d925f"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -9112,7 +9112,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "642d0ade55c203d6b07478a07d3c21c26fa4635dc8a92e4fe989434e635abbbb"
+      "sha256": "4f30ee3036846f449f6fc8143da32b3767376352743d373c39ace2f50f66e913"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9142,7 +9142,7 @@
     {
       "path": "scripts/gds/worktree.js",
       "mode": "0000644",
-      "sha256": "56549d4c288f55699ceb1fea10f4f65756a9114b4628b3f2b6c44fed0ec6ab26"
+      "sha256": "849cd462b9c50866ca1582ed2156fb68ac76699c8270796d1daf6942c09713dc"
     },
     {
       "path": "scripts/hall-preview/README.md",
@@ -9542,7 +9542,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "19014335bfaede6fba2e6ff79ba1fe746a2149345e25448b2ed0176bdb8a6649"
+      "sha256": "9f875091ba63a70601a61a1d486f5b561026167aa524bd371e457c9a93c2635c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10212,7 +10212,7 @@
     {
       "path": "tests/conflict_resolve.mjs",
       "mode": "0000644",
-      "sha256": "7ad7be450b9350e7888f075944888ddf2a0e2d57a23568f410a9ff17bd340dec"
+      "sha256": "da8182c4235c7735bdee351cfa7dc1146f7ded33b9d594dc0ba498a3b5206d83"
     },
     {
       "path": "tests/connections_api.mjs",
@@ -10642,7 +10642,7 @@
     {
       "path": "tests/git_merge_regen.mjs",
       "mode": "0000644",
-      "sha256": "c6cb1bda6809d8d384a9c35b376995af038d18c26b1b935cb5c0faebb163b72e"
+      "sha256": "a55ae255245a53429cc7948e35ea0515bf58307f826d605d6ffd52cc60196ef8"
     },
     {
       "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",
@@ -12987,7 +12987,7 @@
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "106735a9ab28b4a23e2f25269030d982798da3fa39e31d40a1ec78277ac971bc"
+      "sha256": "492b9dc7efdd6f63b81f1662d5fdc9a7541b7f8ccc6c0ec77a456ad3f574ee74"
     },
     {
       "path": "tests/upgrade_persist_pin.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
@@ -98,6 +112,34 @@ src/bongos/routes/CLAUDE.md   merge=otb-regen
 docs/copy-registry.json    merge=otb-regen
 docs/copy-inventory.md     merge=otb-regen text eol=lf
 
+# Generated API contract + client (task 1003537). gen-api-docs.js writes the first
+# three of these wholesale from a scan of the route files; gen-api-client.js writes the
+# six client files wholesale from that spec. Nothing is hand-authored in any of the
+# nine, so they are the same whole-file shape as docs/session-log-index.md above — and
+# any branch that adds or changes a route regenerates all nine differently and conflicts
+# on ordinary text. Measured on task 1002334: main took 41 commits in 3 hours and four
+# consecutive merge -> regenerate -> reship cycles each lost the race to a fresh conflict
+# in exactly these files, with a PASSING grade the whole time. REGENERABLE in
+# git-merge-regen.js carries the matching rules, and tests/git_merge_regen.mjs pins the
+# two lists as one set.
+#
+# EVERY PATH IS LISTED EXPLICITLY -- deliberately no `clients/bongos-client/*` glob, for
+# two independent reasons. The lockstep test compares these tokens against REGENERABLE as
+# literal path strings, and the driver is handed git's %P, so a glob would match nothing
+# on either side. And clients/bongos-client/examples/hello-world.mjs is HAND-WRITTEN (the
+# generator owns only the six files below): a glob that captured it would route it through
+# a driver that has no rule for it, forcing a conflict git would otherwise merge cleanly --
+# the same trap the leading slash on /CLAUDE.md above exists to avoid.
+docs/api/openapi.json         merge=otb-regen
+docs/api-reference.md         merge=otb-regen
+docs/routes-permissions.md    merge=otb-regen
+clients/bongos-client/index.mjs               merge=otb-regen
+clients/bongos-client/index.cjs               merge=otb-regen
+clients/bongos-client/bongos-client.global.js merge=otb-regen
+clients/bongos-client/index.d.ts              merge=otb-regen
+clients/bongos-client/package.json            merge=otb-regen
+clients/bongos-client/README.md               merge=otb-regen
+
 # Append-only index tables (task 1385 / ADR 0082). docs/adr/README.md is a
 # hand-maintained ADR index whose ONLY recurring conflict is two branches each
 # appending a new row — there is no generator to regen it from, so `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,9 @@ 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)
+  1.19.682 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.681 with no explicit bump. run 34704993368. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/conflict-resolve.js

@@ -311,6 +311,19 @@ const GENERATOR_SCRIPTS = [
   // burned the attempt cap, and announceStrand flagged the task needs_rebase
   // (PR #536 / task 1003544).
   'scripts/gds/copy-inventory.js',
+  // task 1003537: the generated API contract + client. gen-api-docs.js writes
+  // docs/api/openapi.json + docs/api-reference.md + docs/routes-permissions.md from a
+  // scan of the route files; gen-api-client.js then writes the six
+  // clients/bongos-client files FROM that spec. Both are `--check` gates on the merge
+  // ref, so the same trap copy-inventory.js fell into applies verbatim: covered by the
+  // merge driver, regenerated by nobody, and the resulting staleness reported as
+  // `no_regen_diff` — "a real check failure" — rather than as drift.
+  //
+  // ORDER IS LOAD-BEARING: gen-api-client.js reads docs/api/openapi.json off disk, so
+  // it must run AFTER gen-api-docs.js has rewritten it for the merged tree. This list
+  // is walked in order, one await at a time, which is what makes that safe.
+  'scripts/gds/gen-api-docs.js',
+  'scripts/gds/gen-api-client.js',
 ];
 
 // Run the CLONE's generator scripts in WRITE mode against the merged working tree.

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.682",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.680",
+      "version": "1.19.682",
       "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.682",
   "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/gen-api-client.js

@@ -487,8 +487,13 @@ function renderReadme(spec, ops) {
   ].join('\n');
 }
 
-function build() {
-  const spec = JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
+// injectedSpec (task 1003537): the otb-regen merge driver regenerates this client
+// DURING a merge, when docs/api/openapi.json on disk may be the conflicted file git has
+// just written markers into — JSON.parse would throw on it. Passing a spec built in
+// memory keeps the heal working and keeps the client consistent with the api-reference.md
+// the same merge resolves. Omitted everywhere else, so the CLI path is unchanged.
+function build(injectedSpec) {
+  const spec = injectedSpec || JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
   const ops = buildModel(spec);
   const esm = renderClientJs(spec, ops);
   return {

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
@@ -47,9 +54,40 @@ const G = require('./gen-repo-map');
 const FM = require('./gen-file-map');
 const SI = require('./gen-session-index');
 const CI = require('./copy-inventory');
+// gen-api-docs / gen-api-client are required LAZILY, inside the two rules that use them —
+// deliberately NOT here (task 1003537). gen-api-docs pulls src/bongos/routes/_helpers.js
+// for its LIMITS caps, and ship.js requires this module, so an eager require put a server
+// route file into the boot of every `bongos` subcommand. tests/module_api_lazy.mjs catches
+// exactly that. require() is cached, so the merge path pays the load once and the CLI
+// path never pays it at all.
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
+// The generated API contract (task 1003537). gen-api-docs.js writes all three of these
+// wholesale from a scan of the route files, so one build() call answers whichever of
+// them git hands us.
+const API_DOC_FILES = new Set([
+  'docs/api/openapi.json',
+  'docs/api-reference.md',
+  'docs/routes-permissions.md',
+]);
+
+// The generated client (task 1003537), written wholesale from the spec by
+// gen-api-client.js. These six names mirror the keys of its build().files; the
+// lockstep is asserted in tests/git_merge_regen.mjs rather than derived here, because
+// deriving it would mean running the generator at require time. NOTE what is absent:
+// clients/bongos-client/examples/hello-world.mjs is hand-written and must stay out of
+// this set, or the driver would force a conflict on a file git can merge by itself.
+const API_CLIENT_DIR = 'clients/bongos-client';
+const API_CLIENT_FILES = new Set([
+  'index.mjs',
+  'index.cjs',
+  'bongos-client.global.js',
+  'index.d.ts',
+  'package.json',
+  'README.md',
+].map((n) => `${API_CLIENT_DIR}/${n}`));
+
 // The files this driver knows how to regenerate. docs/repo-map.md and
 // docs/session-log-index.md are whole-file; each NESTED_DIRS CLAUDE.md is
 // hand-written prose with one generated block; docs/file-map.md is hand-written
@@ -61,13 +99,25 @@ 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).
+// task 1003537: the two API sets above are spread in whole — every one of those nine files
+// is generated end to end, so they take the docs/repo-map.md path (ignore all three merge
+// sides, rebuild). They are named up there rather than inline here because the rules below
+// test set membership, and tests/git_merge_regen.mjs cross-checks them against .gitattributes.
 const REGENERABLE = new Set([
+  'CLAUDE.md',
   'docs/repo-map.md',
   'docs/file-map.md',
   'docs/session-log-index.md',
   'docs/copy-inventory.md',
   'docs/copy-registry.json',
   ...G.NESTED_DIRS.map((d) => `${d}/CLAUDE.md`),
+  ...API_DOC_FILES,
+  ...API_CLIENT_FILES,
 ]);
 
 // A line that begins with a git conflict marker. If any survives our resolution,
@@ -124,6 +174,49 @@ function regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {})
     return { content: CI.renderReport(CI.buildRegistry()), ok: true };
   }
 
+  // The generated API contract (task 1003537): gen-api-docs.js writes openapi.json,
+  // api-reference.md and routes-permissions.md wholesale from a scan of the route files
+  // — nothing hand-authored in any of them — so like docs/repo-map.md below they ignore
+  // all three merge sides and rebuild. One build() yields all three; take the one asked
+  // for. This is the rule that ends the task-1002334 stall, where four merge → reship
+  // cycles each lost the race to a fresh textual conflict in exactly these files.
+  if (API_DOC_FILES.has(relpath)) {
+    const AD = require('./gen-api-docs'); // lazy — see the require block up top
+    const f = AD.build().files.find((x) => x.rel === relpath);
+    return { content: f.content, ok: true };
+  }
+
+  // The generated client (task 1003537): gen-api-client.js renders all six files from
+  // the spec, so it heals the same way. Hand it a FRESHLY BUILT spec instead of letting
+  // build() read docs/api/openapi.json off disk — mid-merge that file is very often the
+  // one git has just written conflict markers into, and JSON.parse would throw on them
+  // (an uncaught throw here exits non-zero, which git reads as "unresolved", so the
+  // failure would be a silent fallback to a textual conflict on the very files this
+  // rule exists to heal). Rebuilding also keeps the client consistent with the
+  // api-reference.md the same merge is healing.
+  if (API_CLIENT_FILES.has(relpath)) {
+    const AD = require('./gen-api-docs');   // lazy — see the require block up top
+    const AC = require('./gen-api-client'); // lazy — same reason
+    const { files } = AC.build(AD.buildOpenapi(AD.extractModel()));
+    return { content: files[relpath.slice(API_CLIENT_DIR.length + 1)], 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/init.js

@@ -943,7 +943,7 @@ async function main(argv) {
       console.error(`init: could not derive the core version from ${path.basename(tgz)} — expected a tarball named ${upgrade.ARTIFACT}-<version>.tgz (produced by \`node scripts/gds/package-core.js\`).`);
       return 1;
     }
-    const vendorRel = path.join('vendor', `${upgrade.ARTIFACT}-${version}.tgz`);
+    const vendorRel = upgrade.vendorRelFor(version);
     coreDep = `file:${vendorRel}`;
     vendorPlan = { tgz, version, vendorRel };
   }

package/scripts/gds/upgrade.js

@@ -34,6 +34,16 @@ const { writeNpmrc, hasNpmToken, resolveNpmToken } = require('./npmrc'); // ADR
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
+// WHERE THE VENDORED TARBALL SITS, as a package.json `file:` specifier — and the reason
+// this is not a path.join(). The same string is spent two ways: it is joined onto an
+// absolute dir for an fs check (path.join normalises a forward slash on every platform,
+// so that direction is free), and it is WRITTEN INTO package.json as `file:<vendorRel>`.
+// npm specifiers are POSIX. A path.join() here emits `file:vendor\\bongos-core-x.y.z.tgz`
+// on a Windows builder's machine, and that pin is then COMMITTED to the instance repo —
+// where the provisioner runs `npm ci` on Linux and reads a literal backslash in the
+// filename. One copy, POSIX by construction, so a scaffold cannot be platform-stamped
+// by the box that happened to run the scaffolder (task 1003839).
+function vendorRelFor(version) { return path.posix.join('vendor', `${ARTIFACT}-${version}.tgz`); }
 
 // ---- pure helpers (no I/O side effects beyond the injected fs) --------------
 
@@ -245,7 +255,7 @@ function vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs) {
   if (fsImpl.existsSync(fromManifest)) {
     fsImpl.copyFileSync(fromManifest, path.join(vendorDir, `${ARTIFACT}-${targetVersion}.manifest.json`));
   }
-  return path.join('vendor', destName);
+  return path.posix.join('vendor', destName);
 }
 
 // Lightweight module-compat pre-check reusing module.js against the TARGET core version. Best-effort:
@@ -940,10 +950,10 @@ async function runUpgrade(opts, deps = {}) {
     if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
   } else {
-    let vendorRel = opts.pinPath || (opts.from ? null : path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`));
+    let vendorRel = opts.pinPath || (opts.from ? null : vendorRelFor(targetVersion));
     if (opts.from) {
       if (!fsImpl.existsSync(opts.from)) return { ok: false, error: `--from tarball not found: ${opts.from}` };
-      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`); }
+      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = vendorRelFor(targetVersion); }
       else vendorRel = vendorTarball({ instanceDir, fromTgz: path.resolve(opts.from), targetVersion }, fsImpl);
     }
     if (!fsImpl.existsSync(path.join(instanceDir, vendorRel)) && !dryRun) {
@@ -1225,7 +1235,7 @@ module.exports = {
   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, deriveVersionUrl, pollServedVersion,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
-  CORE_PKG, ARTIFACT,
+  CORE_PKG, ARTIFACT, vendorRelFor,
 };
 
 if (require.main === module) {

package/scripts/gds/worktree.js

@@ -31,6 +31,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
+const { registerMergeDriver, MERGE_DRIVER_NAME } = require('./install-git-hooks');
 
 // -- pure helpers (exported for tests/worktree_helper.mjs) --------------------
 
@@ -145,6 +146,25 @@ function cmdAdd(root, argv) {
     process.exit(1);
   }
 
+  // Register the otb-regen merge driver (task 1003537). .gitattributes routes the
+  // generated files through it, but git honours that ONLY where merge.otb-regen.driver is
+  // configured — which install-git-hooks.js does per CLONE, on /builder-setup. A builder
+  // who never ran the installer got a silent TEXTUAL merge of files no textual merge can
+  // resolve: measured on task 1002334, a scripts/gds/CLAUDE.md symbol block matching
+  // neither generator, clean enough that nothing flagged it until fitness ran in CI.
+  // Worktree-per-claim is the default path to a new tree, so doing it here is what closes
+  // that gap for a clone whose owner never ran setup. git config is shared with every
+  // linked worktree, so registering against the main root covers this tree and all later
+  // ones. Idempotent, and best-effort on purpose: failing to register only restores the
+  // pre-existing fallback-to-conflict behaviour, which must never fail `worktree add`.
+  const driver = registerMergeDriver(root);
+  if (driver.ok) {
+    console.log(`  merge driver '${MERGE_DRIVER_NAME}' registered (generated files auto-regenerate on merge)`);
+  } else {
+    console.log(`  ⚠ could not register the '${MERGE_DRIVER_NAME}' merge driver: ${driver.error}`);
+    console.log('    (generated files will merge textually here; ship.js still self-heals the same set)');
+  }
+
   if (needsJunction({ wtPath, repoRoot: root, platform: process.platform })) {
     const target = path.join(root, 'node_modules');
     if (!fs.existsSync(target)) {

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.682'; // 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,9 +554,27 @@ 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']),
+    // task 1003537 — the generated API contract + client joined REGENERABLE. Mapped by
+    // PATH PREFIX rather than by calling the generators: this suite deliberately sets
+    // *_INSTANCE_ROOT (see the env-hardening case above), which repoints their docs root
+    // at a fake server checkout, so a build() here reads a file that does not exist.
+    // Nothing is lost by not running them — drift between REGENERABLE and what they
+    // actually write is pinned by tests/git_merge_regen.mjs case 11, and a future entry
+    // under either prefix is picked up here automatically.
+    ...[...regen.REGENERABLE]
+      .filter((p) => p.startsWith('docs/api/') || p === 'docs/api-reference.md' || p === 'docs/routes-permissions.md')
+      .map((p) => [p, 'scripts/gds/gen-api-docs.js']),
+    ...[...regen.REGENERABLE]
+      .filter((p) => p.startsWith('clients/bongos-client/'))
+      .map((p) => [p, 'scripts/gds/gen-api-client.js']),
   ]);
 
   for (const p of regen.REGENERABLE) {

package/tests/git_merge_regen.mjs

@@ -28,6 +28,12 @@
 //      the merge's OWNER must regenerate afterwards (conflict-resolve.js step 7b).
 //      Needs a real clone (the driver's __dirname must BE the merging tree), so it
 //      skips where the environment cannot host that.
+//  11. The generated API contract + client (task 1003537) — docs/api/openapi.json,
+//      docs/api-reference.md, docs/routes-permissions.md and the six
+//      clients/bongos-client files regenerate clean from the merged tree, the client
+//      heals even when the on-disk spec is the conflicted file, and the driver's file
+//      list still matches what gen-api-client actually writes. Also pins the ABSENCE of
+//      clients/bongos-client/examples/hello-world.mjs, which is hand-written.
 //
 // Run:  node tests/git_merge_regen.mjs
 
@@ -45,6 +51,9 @@ 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 AD = require('../scripts/gds/gen-api-docs.js');   // task 1003537 — the generated API contract
+const AC = require('../scripts/gds/gen-api-client.js'); // task 1003537 — the generated client
 
 const MARKERS = /^(<{7}|={7}|>{7})/m;
 
@@ -120,10 +129,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 +259,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`);
@@ -376,4 +446,56 @@ function withBlockBody(src, body) {
   }
 }
 
+// ── 11) the generated API contract + client (task 1003537) ─────────────────────
+// gen-api-docs.js and gen-api-client.js write nine fully generated files that used to
+// merge textually, so any branch touching a route conflicted with every concurrent land
+// (task 1002334: four merge → reship cycles, each beaten by a fresh conflict). They heal
+// like docs/repo-map.md — all three merge sides ignored, rebuilt from the merged tree.
+{
+  const conflicted = (a, b) => `<<<<<<< ours\n${a}\n=======\n${b}\n>>>>>>> theirs\n`;
+
+  // (a) the three doc artifacts rebuild to exactly what the generator would write.
+  const fresh = new Map(AD.build().files.map((f) => [f.rel, f.content]));
+  for (const rel of ['docs/api/openapi.json', 'docs/api-reference.md', 'docs/routes-permissions.md']) {
+    const r = regen.regenerateResolved(rel, {
+      base: 'base\n', ours: conflicted('{"a":1}', '{"b":2}'), theirs: 'nonsense\n',
+    });
+    assert.equal(r.ok, true, `${rel} heal must succeed`);
+    assert.ok(!MARKERS.test(r.content), `${rel} heal must leave no conflict markers`);
+    assert.equal(r.content, fresh.get(rel), `${rel} heal must equal a fresh generation`);
+  }
+
+  // (b) the six client files do too. The driver rebuilds the spec in memory rather than
+  // reading docs/api/openapi.json, so this must hold no matter what is on disk.
+  const freshClient = AC.build().files;
+  for (const [name, content] of Object.entries(freshClient)) {
+    const rel = `clients/bongos-client/${name}`;
+    const r = regen.regenerateResolved(rel, {
+      base: 'base\n', ours: conflicted('one', 'two'), theirs: 'nonsense\n',
+    });
+    assert.equal(r.ok, true, `${rel} heal must succeed`);
+    assert.ok(!MARKERS.test(r.content), `${rel} heal must leave no conflict markers`);
+    assert.equal(r.content, content, `${rel} heal must equal a fresh generation`);
+  }
+
+  // (c) LOCKSTEP: the driver's hardcoded client list must be exactly what the generator
+  // writes. Without this, a seventh generated client file would be added to
+  // gen-api-client.js and silently fall back to a textual merge — the original defect.
+  const declared = [...regen.REGENERABLE]
+    .filter((f) => f.startsWith('clients/bongos-client/'))
+    .map((f) => f.slice('clients/bongos-client/'.length))
+    .sort();
+  assert.deepEqual(declared, Object.keys(freshClient).sort(),
+    'REGENERABLE\'s clients/bongos-client entries must match gen-api-client build().files exactly');
+
+  // (d) the hand-written example must stay OUT. A `clients/bongos-client/*` glob would
+  // have swept it in, and the driver has no rule for it — so git would be forced into a
+  // conflict on a file it can merge by itself (the /CLAUDE.md leading-slash trap again).
+  assert.ok(!regen.REGENERABLE.has('clients/bongos-client/examples/hello-world.mjs'),
+    'the hand-written example must never be routed through the regenerating driver');
+  assert.equal(regen.regenerateResolved('clients/bongos-client/examples/hello-world.mjs',
+    { base: 'a\n', ours: 'b\n', theirs: 'c\n' }).content, null,
+    'a non-generated path under the client dir must not resolve');
+}
+
 console.log('git_merge_regen: all assertions passed');

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

package/tests/upgrade.mjs

@@ -88,11 +88,51 @@ t('vendorTarball: copies the .tgz + side-car manifest under the canonical name',
   writeFileSync(join(src, 'bongos-core-1.15.0.manifest.json'), '{"v":1}');
   const dir = scratchConsumer();
   const rel = u.vendorTarball({ instanceDir: dir, fromTgz: join(src, 'bongos-core-1.15.0.tgz'), targetVersion: '1.15.0' });
-  assert.equal(rel, join('vendor', 'bongos-core-1.15.0.tgz'));
+  // POSIX outright, not join(): this return value is written into package.json as a
+  // `file:` specifier, so the separator is part of the contract, not of the platform
+  assert.equal(rel, 'vendor/bongos-core-1.15.0.tgz');
   assert.equal(readFileSync(join(dir, rel), 'utf8'), 'TGZBYTES');
   assert.ok(existsSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json')), 'manifest copied too');
 });
 
+// The pin is a POSIX specifier on EVERY platform (task 1003839). `bongos init
+// --vendor-core` and `bongos upgrade` both write `file:<vendorRel>` into an
+// instance's package.json, and that package.json is COMMITTED — so a scaffold cut
+// on a Windows laptop was shipping `file:vendor\\bongos-core-x.y.z.tgz` to a Linux
+// provisioner running `npm ci`, which reads the backslash as part of the filename.
+//
+// Two halves, because neither alone can see the bug from CI. The STATIC half reads
+// the sources and so fails on any platform; the BEHAVIOURAL half below it is silent on
+// Linux (path.join already yields a forward slash there) and loud on Windows. The
+// static half runs FIRST for exactly that reason: on Windows a regression trips the
+// behavioural assertions and would abort the case before the platform-independent
+// ones ever ran, hiding whether CI could have caught it.
+t('the vendored core pin is POSIX on every platform, and no call site rebuilds it', () => {
+  // one place decides the separator, and that place spells it posix
+  const upgradeSrc = readFileSync(new URL('../scripts/gds/upgrade.js', import.meta.url), 'utf8');
+  assert.match(upgradeSrc, /function vendorRelFor\([^)]*\)\s*{\s*return path\.posix\.join\(/,
+    'vendorRelFor must build the pin with path.posix.join — it is an npm specifier, not a filesystem path');
+  for (const rel of ['scripts/gds/upgrade.js', 'scripts/gds/init.js']) {
+    const code = readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+    assert.doesNotMatch(code, /path\.join\(\s*['"]vendor['"]\s*,/,
+      `${rel} must build the pin with vendorRelFor(), not path.join('vendor', …)`);
+  }
+
+  // and the string it produces, end to end
+  assert.equal(u.vendorRelFor('1.17.0'), 'vendor/bongos-core-1.17.0.tgz');
+  assert.doesNotMatch(u.vendorRelFor('1.17.0'), /\\/, 'a package.json file: specifier carries no backslash');
+  // still a usable path: join() normalises a forward-slash relative on Windows too,
+  // so POSIX costs the fs side nothing
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, u.vendorRelFor('1.17.0')), 'TGZ');
+  assert.ok(existsSync(join(dir, u.vendorRelFor('1.17.0'))), 'the POSIX rel still resolves on disk');
+  // and the pin that reaches package.json is that string, verbatim
+  u.writePin(dir, u.vendorRelFor('1.17.0'));
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies[u.CORE_PKG],
+    'file:vendor/bongos-core-1.17.0.tgz');
+});
+
 // ---- 3. step shims issue the right argv ------------------------------------
 t('npmInstall / runMigrate / restartService: correct commands', () => {
   const calls = [];