@bongos/core 1.19.968 → 1.19.969

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.968",
-  "core_contract": "1.19.968",
-  "source_commit": "8ccf04d976e2b856bc48cbfc6ad7d6563522bc51",
+  "core_version": "1.19.969",
+  "core_contract": "1.19.969",
+  "source_commit": "55409bed0b968ea075ebd993255b3e71131ad01e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-22T23:25:06.335Z",
+  "built_at": "2026-09-22T23:40:21.961Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 515,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2365,
+    "functional_verbatim": 2369,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2906,
-  "tree_sha256": "4ccb083b8cb616dd5c4c9c49f498b566996a1ead6ea244f46e5344d7a726a322",
+  "file_count": 2910,
+  "tree_sha256": "46d085a64c600456dab078e43c39f7b0bdff7a4d90ca202ebdfff0bb0cd98581",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -57,7 +57,7 @@
     {
       "path": ".claude/skills/builder-cost/SKILL.md",
       "mode": "0000644",
-      "sha256": "d649e2e39359b11dbe156cfd35d6895d1283c0b56feba0ca96f6eff4f56f923a"
+      "sha256": "0f9b196e81b99a2313f6e1a0c0f091caaaf4b11b0d669076509ca60e3d10434a"
     },
     {
       "path": ".claude/skills/builder-end/SKILL.md",
@@ -2697,7 +2697,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "aa4b0d91bfda4df6b776aa7ea600750b3f24be1e0ffee255ceb170184df90636"
+      "sha256": "8874af5deda6102925f3caea6c829bc6c637ec707eb7b6cf8ef67fa79b0919a7"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2892,7 +2892,7 @@
     {
       "path": "docs/recipes/parallel-goal-waves.md",
       "mode": "0000644",
-      "sha256": "0ce5b2395e8e4a78a58af68e45cc25d1ca10a5ddc6cc349e2d2b300a85a83a68"
+      "sha256": "4879badb2ab0678098d3f5cfa1002a6b4b50e8a691a5d4afc17b533803fbe262"
     },
     {
       "path": "docs/recipes/private-npm-distribution.md",
@@ -4244,15 +4244,20 @@
       "mode": "0000644",
       "sha256": "fefd4908bd22aa3b747a7c8b4146e5a7e53731fe92612db105ea3512ae34300c"
     },
+    {
+      "path": "modules/economy/cost-report.js",
+      "mode": "0000644",
+      "sha256": "484448390d675c3884cbee5d15405e1e7167bbc111f8461e06890750b7f68be4"
+    },
     {
       "path": "modules/economy/cost-summary-shape.js",
       "mode": "0000644",
-      "sha256": "4aedb7a2d412be5ead4e6e59bd993d650078299bd4625a4de043bdd0201bc28b"
+      "sha256": "449251df02a484bc865c3844d0a85beffe5e3be920db0f09833f962df3e8b3d4"
     },
     {
       "path": "modules/economy/cost.js",
       "mode": "0000644",
-      "sha256": "6cc28fe57bb50b6c3f4b7d4485838427fa5f12b5a79848f0358fdaa2874f6c1e"
+      "sha256": "ce3ce114f5315c78a2feb810bce09cde84941765629f0e5a10a44aced2c34210"
     },
     {
       "path": "modules/economy/credits.js",
@@ -8102,12 +8107,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "a4f60be63bc56da8ba3332e604d1fbb0b4b3288f9b3cf14a52d05227e040a3f4"
+      "sha256": "ede312c963ab08f5b2fec23b90c3c5fc829149893c08e83196be37b2a3ef11b5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4d9fb5822b9ba10648ba9d9e0c2bd7c5659215e65bb8395455913b7b14c43998"
+      "sha256": "40a32e40062ce4becee8999e5b2cdb5dd54d5a0ad65885341afcf3651e002d55"
     },
     {
       "path": "public-docs/index.html",
@@ -8509,6 +8514,11 @@
       "mode": "0000644",
       "sha256": "55ac5440a1c5481766198d6a89cef601fde816024b592b1e77f535c465a2df47"
     },
+    {
+      "path": "scripts/gds/cost-report.js",
+      "mode": "0000644",
+      "sha256": "988d9e5dec9ed4bd35a3aea25fc841a832a2a251ee6eefa7fb0d86f7ee5b7b2e"
+    },
     {
       "path": "scripts/gds/cost.js",
       "mode": "0000644",
@@ -8607,7 +8617,7 @@
     {
       "path": "scripts/gds/doctor.js",
       "mode": "0000644",
-      "sha256": "f690a26bac623e67d4d4a8d889c5f69b05a8afb98eda13309e73b45c9f5fbbaa"
+      "sha256": "be0f4da3a9885bdc555f720d853923b226ae993a6a965a934c728032a0575988"
     },
     {
       "path": "scripts/gds/enroll-control-plane.js",
@@ -8832,7 +8842,7 @@
     {
       "path": "scripts/gds/install-git-hooks.js",
       "mode": "0000644",
-      "sha256": "668d97543e863394527bad2a629037bfc81eea2f8244f53eb5e79fd43f7485c0"
+      "sha256": "6234ca799f99e5a16622043b0f43d42624efe5fb6862d74e4b8c2b7603cf8bef"
     },
     {
       "path": "scripts/gds/instance-apex.js",
@@ -9237,7 +9247,7 @@
     {
       "path": "scripts/gds/search-ingest-md.js",
       "mode": "0000644",
-      "sha256": "802d16a48f6a47bf41b1768fff3da0ae1b18a4d73147b3559a781f18ea47c75c"
+      "sha256": "7638bd1d2160ef1aa5b386dd555084cb33e1af02bcd9e2f55967cb32a8e0bba5"
     },
     {
       "path": "scripts/gds/security-baseline-check.sh",
@@ -10112,7 +10122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "4f5478f0a18dbb167df7e86861ae757cceaf084a43436461af1fca4855256505"
+      "sha256": "37d85c40aec959cbe0091ef9f1c2d14831fcc8271dcaf91a8d42c5d879a80878"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11049,10 +11059,15 @@
       "mode": "0000644",
       "sha256": "8356250d8fc753afb2960d867f81586531053afd15f4e66da1a1b7b62b6b5db7"
     },
+    {
+      "path": "tests/cost_report.mjs",
+      "mode": "0000644",
+      "sha256": "cb69ea9b53e37f8590bb1cd2e594df1a63fa07f452ad7b0bf7a607507f8e2c82"
+    },
     {
       "path": "tests/cost_summary_shape.mjs",
       "mode": "0000644",
-      "sha256": "397619dac27a319b1c4c2ef2ca5b92b02815429825e983dbba68be27fb4701d5"
+      "sha256": "50f195ef2060df92016b58f541a28e7492dd95ad4da8bd0781bdc07007193338"
     },
     {
       "path": "tests/credit_grant.mjs",
@@ -12624,6 +12639,11 @@
       "mode": "0000644",
       "sha256": "d05b6e354ac08cf5512a62b76b213df44ab1ef8639a1ba635319e9b5e8511a5c"
     },
+    {
+      "path": "tests/merge_driver_register.mjs",
+      "mode": "0000644",
+      "sha256": "c75880064b52b6edb2689232eb1e6401567618f46b16581140685ccceee2d41c"
+    },
     {
       "path": "tests/merge_lease.mjs",
       "mode": "0000644",
@@ -13652,7 +13672,7 @@
     {
       "path": "tests/search_ingest.mjs",
       "mode": "0000644",
-      "sha256": "8d685a46ab9f4cf9aaa71b9ee78774d95c16daa27c15a229b8628a97688b9a55"
+      "sha256": "dd92de1e35d82fc4ea82c2f5cb99b506153e5386e4668846cba87e0f8d135d97"
     },
     {
       "path": "tests/search_ingest_db.mjs",

package/.claude/skills/builder-cost/SKILL.md

@@ -42,7 +42,11 @@ The CLI hits `POST /api/bongos/cost`, which inserts a `cost_log` row.
 - **Don't double-count.** Before logging an art-pipeline cost manually, verify it isn't already in the DB from the one-time cost-ledger backfill (those rows use `source: 'art-cost-ledger'`).
 - **Don't log without a description for `other` category.**
 
+## Reading the ledger back
+
+To see what has been spent rather than add to it, run `node scripts/gds/cost-report.js` — total spend plus totals by month, category and source. The endpoint it reads is public, so no rank is needed, but the session still supplies the instance URL. `--source X`, `--category Y` and `--days N` scope the breakdowns (the header total stays project-wide); `--json` prints the raw payload. The newest month is labelled partial — it is spend to date, not a month's worth.
+
 ## Files this skill touches
 
 - Reads: `~/.config/otb/gds-session.json`
-- Calls: `POST /api/bongos/cost`
+- Calls: `POST /api/bongos/cost` (logging), `GET /public/cost-summary` (the read-out, via `scripts/gds/cost-report.js`)

package/docs/module-api-changelog.md

@@ -2410,5 +2410,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.966 with no explicit bump. run 35795807836. (task 1002620)
   1.19.968 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.967 with no explicit bump. run 35797263467. (task 1002620)
+  1.19.969 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.968 with no explicit bump. run 35798488315. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/parallel-goal-waves.md

@@ -105,6 +105,11 @@ One file will become the contention point. Here it was the module's nested `CLAU
 **Generated files: always resolve by regenerating, never by picking a side.**
 
 ```bash
+# --theirs only CLEARS THE CONFLICT MARKERS so git will accept the path as resolved
+# (git add refuses a still-conflicted path). It is not a choice of content: the
+# generator on the next line overwrites the file from source, so whichever side you
+# took is discarded. --ours works identically here. This is the one place the "never
+# pick a side" rule above does not apply, because nothing is being picked.
 git checkout --theirs <file>
 node scripts/gds/gen-repo-map.js      # or gen-api-docs.js, gen-diagrams.js
 git add <file> && git commit --no-edit
@@ -112,6 +117,8 @@ git add <file> && git commit --no-edit
 
 Picking a side leaves the artefact inconsistent with source, and the freshness fitness check fails on the *next* task instead of yours. The generated symbol blocks and the OpenAPI spec both bit us this way.
 
+**If the generator is not the last thing you run, you have picked a side.** That is the test to apply, not the flag you typed.
+
 > If `ship.js` says *"auto-merge: bailed; task stays at confirmed"*, don't reach for `/merge-mode` first. Merge `origin/main` into the **task's own branch**, resolve there, re-run `fitness.js`, then re-run `ship.js <id>` — it resumes from `confirmed`. `/merge-mode` is an operator procedure that mutates the main worktree and assumes a bash/SSH environment.
 
 ---

package/modules/economy/cost-report.js

@@ -0,0 +1,66 @@
+// modules/economy/cost-report.js — the spend read-out's text rendering (task
+// 1001621: "what did this cost, by month, category and source", the figures
+// hosting ROI is sized against). Pure (no DB, no I/O) so the CLI
+// (scripts/gds/cost-report.js) stays a thin fetch-and-print shell and the
+// wording is unit-testable DB-free (tests/cost_report.mjs). Reads a
+// db.costSummary() payload / the GET /public/cost-summary response as-is.
+
+function usd(n) {
+  return `$${(Number(n) || 0).toFixed(2)}`;
+}
+
+// A dimension the server did not send is NOT the same as a dimension with no
+// rows: the CLI reads a LIVE instance, which may predate the key. Say which,
+// so an old server never reads as "nothing was spent".
+function section(label, rows, render) {
+  if (!Array.isArray(rows)) return [`  ${label}: unavailable (this server predates the rollup)`];
+  if (!rows.length) return [`  ${label}: no spend recorded`];
+  return [`  ${label}:`, ...rows.map((r) => `    - ${render(r)}`)];
+}
+
+// The newest month is spend-to-date, not a month's worth, so an unlabelled row
+// reads as a collapse in spend at the top of every month — in the one figure a
+// hosting bill is sized against. Compared in UTC: a boundary mismatch with the
+// server's timezone only drops the label for a few hours, which under-claims
+// rather than calling a partial month complete.
+function monthLabel(row, now) {
+  const current = now.toISOString().slice(0, 7);
+  const partial = row.month === current ? '  (partial — month to date)' : '';
+  return `${row.month}: ${usd(row.total_usd)}${partial}`;
+}
+
+function filterLabel(filters) {
+  const f = filters || {};
+  const parts = [];
+  if (f.source) parts.push(`source=${f.source}`);
+  if (f.category) parts.push(`category=${f.category}`);
+  if (f.days) parts.push(`last ${f.days} days`);
+  return parts.join(' · ');
+}
+
+/**
+ * Render a spend rollup — total, then totals by month, category and source —
+ * from a cost-summary payload, for the `cost-report` CLI.
+ * @param {object} summary - db.costSummary() / GET /public/cost-summary.
+ * @param {object} [opts] - { now } — the clock, injectable so the partial-month
+ *   label is testable.
+ * @returns {string} the printable report.
+ */
+function formatCostReport(summary, { now = new Date() } = {}) {
+  const s = summary || {};
+  const lines = ['Spend rollup — cost_log'];
+  // The header total stays project-wide whatever the filter: costSummary scopes
+  // only the breakdowns, so labelling it is what keeps the two figures honest.
+  lines.push(`  total spend:   ${usd(s.total_usd)}  (project-wide, all time)`);
+  const label = filterLabel(s.applied_filters);
+  if (label) {
+    lines.push(`  filter:        ${label}`);
+    lines.push(`  under filter:  ${usd(s.filtered_total_usd)}`);
+  }
+  lines.push(...section('by month', s.by_month, (r) => monthLabel(r, now)));
+  lines.push(...section('by category', s.by_category, (r) => `${r.category}: ${usd(r.total_usd)}`));
+  lines.push(...section('by source', s.by_source, (r) => `${r.source}: ${usd(r.total_usd)}`));
+  return lines.join('\n');
+}
+
+module.exports = { formatCostReport };

package/modules/economy/cost-summary-shape.js

@@ -87,4 +87,16 @@ function shapeCostCalibration(rows) {
   };
 }
 
-module.exports = { shapeBySource, shapeByTier, shapeSavings, shapeCostCalibration };
+// by_month: cost_log rows grouped by calendar month (task 1001621), the axis the
+// daily series cannot answer — "what does a month of this cost" is the figure
+// hosting ROI is sized against. The month label is formatted in SQL (to_char),
+// not here, so a driver Date + a UTC-shifted server can never move a row into
+// the neighbouring month. Rows arrive pre-sorted oldest-first by SQL.
+function shapeByMonth(rows) {
+  return (rows || []).map((r) => ({
+    month: String(r.month),
+    total_usd: round2(r.total_usd),
+  }));
+}
+
+module.exports = { shapeBySource, shapeByTier, shapeSavings, shapeCostCalibration, shapeByMonth };

package/modules/economy/cost.js

@@ -327,6 +327,7 @@ async function costSummary(filters = {}) {
     { rows: filteredTotalRows },
     { rows: sourceOptRows },
     { rows: categoryOptRows },
+    { rows: byMonthRows },
   ] = await Promise.all([
     pool.query(`SELECT COALESCE(SUM(amount_usd), 0) AS total_usd FROM cost_log`),
     pool.query(
@@ -423,6 +424,16 @@ async function costSummary(filters = {}) {
     pool.query(
       `SELECT DISTINCT category FROM cost_log WHERE category IS NOT NULL ORDER BY category`
     ),
+    // task 1001621: by_month — the axis `daily` cannot answer. A month of spend
+    // is what a hosting bill is compared against, and the day series is
+    // deliberately project-wide, so it cannot be re-bucketed per slice. This one
+    // honors the same filters as the other breakdowns. to_char formats the label
+    // in SQL so no driver Date/timezone can shift a row into the next month.
+    pool.query(
+      `SELECT to_char(recorded_at, 'YYYY-MM') AS month, COALESCE(SUM(amount_usd), 0) AS total_usd
+         FROM cost_log ${whereCl} GROUP BY month ORDER BY month`,
+      params
+    ),
   ]);
 
   // savings — the counterfactual ledger (cost_baseline, migration 124). Guarded:
@@ -474,6 +485,9 @@ async function costSummary(filters = {}) {
     daily_credits: valueHistory.map((r) => ({ day: r.day, credits: Number(r.credits) })),
     // System 1 / task 1345 — additive dimensions (existing keys keep shape).
     by_source: costSummaryShape.shapeBySource(bySourceRows),
+    // task 1001621 — spend per calendar month, under the same filters as the
+    // other breakdowns. Additive; existing keys keep their shape.
+    by_month: costSummaryShape.shapeByMonth(byMonthRows),
     by_tier: costSummaryShape.shapeByTier(byTierRows[0]),
     savings: costSummaryShape.shapeSavings(savingsRows),
     // task 572 / spend-audit F6 — cost-per-task & cost-per-credit medians.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.968",
+  "version": "1.19.969",
   "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/cost-report.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Read the spend rollup: total spend, and totals by month, category and source.
+//
+// The read half of cost.js, which only LOGS spend — task 1001621 (ADR 0092
+// finding): nothing rolled it up where a person could size hosting against real
+// numbers. The endpoint it reads is public, so no RANK is needed — but the base
+// URL still comes from your CLI session (or <PREFIX>_API_BASE), which is what
+// says WHICH instance to ask.
+//
+// Usage:
+//   node scripts/gds/cost-report.js [--source X] [--category Y] [--days N] [--json]
+//
+// The filters scope the BREAKDOWNS only — the header total stays project-wide,
+// which is how the server's treasury filter already behaves.
+
+const { cliClient, arg, readSessionToken } = require('./cli-lib');
+// A CLI may require a module directly (the backfill-cost.js / cost-classify
+// precedent, BV1.R77 / ADR 0093 §1-2). The rendering is pure and lives there so
+// it is testable without a server (tests/cost_report.mjs).
+const { formatCostReport } = require('../../modules/economy/cost-report');
+
+// arg() hands back whatever follows the flag, so `--source --json` would filter
+// on the literal '--json' and silently report $0 — a wrong answer, not an error.
+function value(name, args) {
+  const v = arg(name, args);
+  if (v == null) return null;
+  if (String(v).startsWith('--')) {
+    console.error(`${name} needs a value (got '${v}')`);
+    process.exit(2);
+  }
+  return v;
+}
+
+(async () => {
+  const args = process.argv.slice(2);
+  const query = {};
+  const source = value('--source', args);
+  const category = value('--category', args);
+  const days = value('--days', args);
+  if (source) query.source = source;
+  if (category) query.category = category;
+  if (days) query.days = days;
+
+  const api = await cliClient();
+  const r = await api.public.getPublicCostSummary({ query });
+  if (!r.ok) {
+    console.error(`cost report failed (HTTP ${r.status}):`, r.data);
+    process.exit(1);
+  }
+  console.log(args.includes('--json') ? JSON.stringify(r.data, null, 2) : formatCostReport(r.data));
+})().catch((err) => {
+  // A session-less or offline run lands here, and a raw fetch stack says nothing
+  // about WHICH instance was tried. readSessionToken() returns null when not
+  // signed in, which is itself the answer in that case.
+  const session = readSessionToken();
+  const msg = (err && err.message) || String(err);
+  console.error(`cost-report failed (instance: ${session ? session.apiBase : 'no session — falling back to this checkout\'s default'}).`);
+  console.error(`  cause: ${msg}`);
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN/.test(msg)) {
+    console.error('  The instance could not be reached. Sign in with `node scripts/gds/setup.js`, or name one with <PREFIX>_API_BASE.');
+  }
+  process.exit(1);
+});

package/scripts/gds/doctor.js

@@ -28,6 +28,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { execSync, spawnSync } = require('node:child_process');
 const { cliClient, SESSION_PATH, loadSession } = require('./cli-lib');
+const { classifyMergeDriverState, MERGE_DRIVER_NAME } = require('./install-git-hooks.js');
 const { preflightChecks } = require('./preflight');
 
 // ANSI helpers (only if stdout is a TTY; otherwise emit plain text)
@@ -253,6 +254,20 @@ function classifyPreCommitState({ preCommitPath, present, executable }) {
 
 function checkGitPlumbing() {
   section('Git plumbing');
+
+  // The merge-driver section is reported FIRST and unconditionally — it is checked
+  // even when core.hooksPath is unset, because the two are independent and the
+  // half-written-section wedge (task 1003846) is silent until a merge dies with
+  // `fatal: custom merge driver ... lacks command line`. A builder who hits that has
+  // no reason to connect it to a setup step that ran days ago, so doctor naming it
+  // is the whole point. Early-returning before this line would hide it on exactly
+  // the clones most likely to be mis-set-up.
+  const md = classifyMergeDriverState({
+    name: gitOut(`git config --get merge.${MERGE_DRIVER_NAME}.name`),
+    driver: gitOut(`git config --get merge.${MERGE_DRIVER_NAME}.driver`),
+  });
+  ({ ok, warn, fail }[md.status])('git', md.message);
+
   const verdict = classifyHooksState({
     hooksPath: gitOut('git config --get core.hooksPath'),
     worktreeRoot: gitOut('git rev-parse --show-toplevel'),
@@ -438,7 +453,7 @@ function checkRunnerDrift() {
 // --------------------------------------------------------------------------
 // Guarded so requiring this file for its pure helpers (tests/doctor_hooks.mjs)
 // does not run the checks, which shell out to git and hit the network.
-module.exports = { classifyHooksState, classifyPreCommitState, runnerDriftRows };
+module.exports = { classifyHooksState, classifyMergeDriverState, classifyPreCommitState, runnerDriftRows };
 
 if (require.main === module) (async () => {
   console.log(`${C.bold}GDS Doctor${C.reset} — local-machine health check`);

package/scripts/gds/install-git-hooks.js

@@ -30,21 +30,88 @@ function git(args) {
 // the generated files (docs/repo-map.md + the nested CLAUDE.md blocks).
 const MERGE_DRIVER_NAME = 'otb-regen';
 
-function registerMergeDriver(root) {
+// ORDER MATTERS, and the wrong order is worse than not registering at all (task 1003846).
+//
+// These are two git-config writes, not one atomic operation. If the first succeeds and
+// the second throws, the half-written section SURVIVES — and git does not treat a named
+// driver with no command as "fall back to a text merge". It treats it as fatal:
+//
+//     fatal: custom merge driver otb-regen lacks command line.
+//
+// exit 128, no unmerged paths, nothing that looks like a merge conflict. Every merge
+// touching any `merge=otb-regen` path then dies — which is now the root CLAUDE.md, the
+// file/session-log maps, two nested CLAUDE.md files, the copy-registry pair and the nine
+// generated API artifacts. So the failure mode of the old order was "no merge in this
+// clone can complete", where not registering at all merely yields an ordinary conflict.
+//
+// Both halves of the fix are verified, not assumed (see tests/merge_driver_register.mjs):
+//   - `.driver` alone IS a valid section — git runs it and the merge succeeds.
+//   - `.name` alone is the fatal state above.
+// So writing `.driver` FIRST makes the intermediate state safe, and removing the whole
+// section on failure makes even a mid-write abort leave no trace.
+function registerMergeDriver(root, { run = execFileSync } = {}) {
   // execFileSync (arg array, no shell) so the literal %O/%A/%B/%P placeholders and
   // the spaces in the command survive verbatim on every platform (a shell would
   // mangle %VARS on Windows cmd).
   try {
-    execFileSync('git', ['config', `merge.${MERGE_DRIVER_NAME}.name`,
-      `${require('./cli-lib').productName()} generated-file regenerator (task 1243)`], { cwd: root, stdio: 'ignore' });
-    execFileSync('git', ['config', `merge.${MERGE_DRIVER_NAME}.driver`,
+    // .driver FIRST — a section carrying only .driver is valid and works.
+    run('git', ['config', `merge.${MERGE_DRIVER_NAME}.driver`,
       'node scripts/gds/git-merge-regen.js %O %A %B %P'], { cwd: root, stdio: 'ignore' });
+    // .name SECOND — cosmetic (it is what `git config --list` shows); if this throws,
+    // the section left behind is the safe driver-only one.
+    run('git', ['config', `merge.${MERGE_DRIVER_NAME}.name`,
+      `${require('./cli-lib').productName()} generated-file regenerator (task 1243)`], { cwd: root, stdio: 'ignore' });
     return { ok: true };
   } catch (e) {
+    // Belt and braces: leave NO trace rather than a possibly-partial section. A missing
+    // section is a normal textual conflict; a partial one can be the exit-128 wedge.
+    // This removal is itself best-effort — if it throws (e.g. no section to remove, which
+    // git reports as an error) the original failure is still what we report.
+    try {
+      run('git', ['config', '--remove-section', `merge.${MERGE_DRIVER_NAME}`], { cwd: root, stdio: 'ignore' });
+    } catch (_) { /* nothing to clean up, or we cannot — report the original failure */ }
     return { ok: false, error: e.message };
   }
 }
 
+// The doctor-facing verdict for an already-registered driver, pure so it is testable
+// without a git repo (the classifyHooksState precedent in doctor.js).
+//
+// The wedge state is INVISIBLE until the next merge dies, which is exactly why doctor
+// should say so: a builder who hits `fatal: custom merge driver ... lacks command line`
+// has no reason to connect it to a setup step that ran days earlier.
+function classifyMergeDriverState({ name, driver }) {
+  const hasName = Boolean(name && String(name).trim());
+  const hasDriver = Boolean(driver && String(driver).trim());
+  const installer = 'node scripts/gds/install-git-hooks.js';
+
+  if (hasDriver) {
+    return {
+      status: 'ok',
+      code: 'registered',
+      message: `merge driver '${MERGE_DRIVER_NAME}' registered — generated-file conflicts auto-regenerate on merge.`,
+    };
+  }
+  if (hasName) {
+    return {
+      status: 'fail',
+      code: 'name-without-driver',
+      message:
+        `merge.${MERGE_DRIVER_NAME}.name is set but .driver is MISSING. Git treats this as fatal, not as a `
+        + `fallback: every merge touching a \`merge=${MERGE_DRIVER_NAME}\` path will die with `
+        + `"fatal: custom merge driver ${MERGE_DRIVER_NAME} lacks command line" (exit 128, no conflict shown). `
+        + `Repair with: ${installer}  — or clear it with: git config --remove-section merge.${MERGE_DRIVER_NAME}`,
+    };
+  }
+  return {
+    status: 'warn',
+    code: 'unregistered',
+    message:
+      `merge driver '${MERGE_DRIVER_NAME}' is not registered, so generated-file merges will raise ordinary `
+      + `text conflicts instead of auto-regenerating (ship.js still self-heals). Register with: ${installer}`,
+  };
+}
+
 // Resolve the configured hooks dir (absolute) for reporting / verification.
 function configuredHooksDir() {
   try {
@@ -114,4 +181,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { activate, configuredHooksDir, registerMergeDriver, MERGE_DRIVER_NAME };
+module.exports = { activate, classifyMergeDriverState, configuredHooksDir, registerMergeDriver, MERGE_DRIVER_NAME };

package/scripts/gds/search-ingest-md.js

@@ -48,7 +48,7 @@ const SENSITIVE_DOC_GLOBS = [
   'docs/canonical-permissions.md',  // the rank-ladder / authority reference
   'docs/security/',                 // threat models + red-team reports
   'docs/audits/',                   // security + architecture audit findings
-  'docs/governance/',               // the gate ENUMERATION + choke-point map — task 1002598
+  'docs/governance/',               // the gate ENUMERATION + choke-point map
   'docs/adr/0016-trust-boundary-server-enforced-permissions.md',
   'docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md',
 ];

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.968'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.969'; // 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/cost_report.mjs

@@ -0,0 +1,83 @@
+// tests/cost_report.mjs — the spend read-out's text rendering (task 1001621).
+// DB-free. Run: node tests/cost_report.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { formatCostReport } = require('../modules/economy/cost-report.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+const FULL = {
+  total_usd: 123.45,
+  filtered_total_usd: 123.45,
+  applied_filters: { source: null, category: null, days: null },
+  by_month: [
+    { month: '2026-06', total_usd: 100 },
+    { month: '2026-07', total_usd: 23.45 },
+  ],
+  by_category: [{ category: 'api', total_usd: 120 }, { category: 'infra', total_usd: 3.45 }],
+  by_source: [{ source: 'session:interactive', total_usd: 123.45 }],
+};
+
+test('renders the three dimensions the task asks for: month, category, source', () => {
+  const out = formatCostReport(FULL);
+  assert.match(out, /total spend:\s+\$123\.45/);
+  assert.match(out, /2026-06: \$100\.00/);
+  assert.match(out, /2026-07: \$23\.45/);
+  assert.match(out, /api: \$120\.00/);
+  assert.match(out, /session:interactive: \$123\.45/);
+});
+
+test('no filter applied → no filter line and no filtered subtotal', () => {
+  const out = formatCostReport(FULL);
+  assert.doesNotMatch(out, /filter:/);
+  assert.doesNotMatch(out, /under filter:/);
+});
+
+test('a filter applied → the filter is named and the subtotal is separate from the total', () => {
+  const out = formatCostReport({
+    ...FULL,
+    filtered_total_usd: 23.45,
+    applied_filters: { source: 'grader', category: 'api', days: 30 },
+  });
+  assert.match(out, /filter:.*source=grader/);
+  assert.match(out, /filter:.*category=api/);
+  assert.match(out, /filter:.*last 30 days/);
+  assert.match(out, /under filter:\s+\$23\.45/);
+  // the header total stays project-wide — costSummary never rescopes it
+  assert.match(out, /total spend:\s+\$123\.45/);
+});
+
+test('a server predating by_month says so rather than reading as zero spend', () => {
+  const { by_month, ...older } = FULL;
+  const out = formatCostReport(older);
+  assert.match(out, /by month:\s+unavailable/);
+  assert.doesNotMatch(out, /2026-06/);
+});
+
+test('the current month is labelled partial — it is spend to date, not a month', () => {
+  const out = formatCostReport(FULL, { now: new Date('2026-07-15T00:00:00Z') });
+  assert.match(out, /2026-07: \$23\.45\s+\(partial — month to date\)/);
+  // a month that has closed carries no such caveat
+  assert.match(out, /2026-06: \$100\.00\n/);
+});
+
+test('no row is labelled partial once the newest month has closed', () => {
+  const out = formatCostReport(FULL, { now: new Date('2026-09-22T00:00:00Z') });
+  assert.doesNotMatch(out, /partial/);
+});
+
+test('an empty by_month is reported as no spend, not as unavailable', () => {
+  const out = formatCostReport({ ...FULL, by_month: [] });
+  assert.match(out, /by month:/);
+  assert.doesNotMatch(out, /unavailable/);
+  assert.match(out, /no spend recorded/);
+});
+
+console.log(`\ncost_report: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/cost_summary_shape.mjs

@@ -4,7 +4,7 @@
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
-const { shapeBySource, shapeByTier, shapeSavings, shapeCostCalibration } = require('../modules/economy/cost-summary-shape.js');
+const { shapeBySource, shapeByTier, shapeSavings, shapeCostCalibration, shapeByMonth } = require('../modules/economy/cost-summary-shape.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {
@@ -90,5 +90,21 @@ test('shapeCostCalibration empty/undefined → empty by_kind, null overall', ()
   assert.deepEqual(shapeCostCalibration(undefined), { by_kind: [], overall: null });
 });
 
+test('shapeByMonth coerces numbers and preserves the SQL month ordering (task 1001621)', () => {
+  const out = shapeByMonth([
+    { month: '2026-06', total_usd: '100.005' },
+    { month: '2026-07', total_usd: 23.45 },
+  ]);
+  assert.deepEqual(out, [
+    { month: '2026-06', total_usd: 100.01 }, // round2
+    { month: '2026-07', total_usd: 23.45 },
+  ]);
+});
+
+test('shapeByMonth handles empty/undefined input', () => {
+  assert.deepEqual(shapeByMonth([]), []);
+  assert.deepEqual(shapeByMonth(undefined), []);
+});
+
 console.log(`\ncost_summary_shape: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/merge_driver_register.mjs

@@ -0,0 +1,150 @@
+// tests/merge_driver_register.mjs
+//
+// Task 1003846 — registerMergeDriver wrote two git-config keys in sequence inside one
+// try, `.name` first. If the first succeeded and the second threw, the half-written
+// section SURVIVED, and git does not treat a named driver with no command as "fall back
+// to a text merge" — it treats it as fatal:
+//
+//     fatal: custom merge driver otb-regen lacks command line.
+//
+// exit 128, no unmerged paths. Every merge touching any `merge=otb-regen` path then dies
+// — the root CLAUDE.md, the file/session-log maps, two nested CLAUDE.md files, the
+// copy-registry pair and the nine generated API artifacts. So the partial-write state was
+// strictly WORSE than not registering at all, which merely yields an ordinary conflict.
+//
+// This file pins BOTH halves of the fix, and pins them against real git rather than a
+// mock, because the whole finding rests on how git itself reads a partial section — a
+// mock would only assert what we already believe. The first two tests would have passed
+// on the buggy code too if they were written against a stub; they are written against a
+// throwaway repo on disk precisely so they cannot.
+//
+// Run:  node --test tests/merge_driver_register.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+// fileURLToPath, never URL.pathname — on Windows the latter yields '/C:/…', which is not
+// a usable path. Enforced by fitness.js (task 1002889).
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { classifyMergeDriverState, registerMergeDriver, MERGE_DRIVER_NAME } =
+  require(path.join(REPO_ROOT, 'scripts/gds/install-git-hooks.js'));
+
+// A throwaway repo with one file attributed to the driver and two divergent branches,
+// so `git merge` actually has to consult the driver config.
+function scratchRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mergedriver-'));
+  const git = (args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  git(['init', '-q', '.']);
+  git(['config', 'user.email', 'test@example.com']);
+  git(['config', 'user.name', 'test']);
+  fs.writeFileSync(path.join(dir, 'f.md'), 'base\n');
+  fs.writeFileSync(path.join(dir, '.gitattributes'), `f.md merge=${MERGE_DRIVER_NAME}\n`);
+  git(['add', '-A']);
+  git(['commit', '-qm', 'base']);
+  const base = git(['branch', '--show-current']).trim();
+  git(['checkout', '-qb', 'other']);
+  fs.writeFileSync(path.join(dir, 'f.md'), 'theirs\n');
+  git(['commit', '-qam', 'other']);
+  git(['checkout', '-q', base]);
+  fs.writeFileSync(path.join(dir, 'f.md'), 'ours\n');
+  git(['commit', '-qam', 'mine']);
+  return { dir, git };
+}
+
+// Returns null on a clean merge, or git's stderr on failure.
+function tryMerge(dir) {
+  try {
+    execFileSync('git', ['merge', 'other'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return null;
+  } catch (e) {
+    return String(e.stderr || e.message);
+  }
+}
+
+test('THE BUG: a section with .name and no .driver makes every merge fatal', () => {
+  const { dir, git } = scratchRepo();
+  git(['config', `merge.${MERGE_DRIVER_NAME}.name`, 'half-written']);
+  const err = tryMerge(dir);
+  assert.ok(err, 'merge must FAIL in the half-written state — if this passes, the premise is gone');
+  assert.match(err, /lacks command line/,
+    'git must reject a named driver with no command (this is why .name cannot be written first)');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('THE FIX RESTS ON THIS: a section with only .driver is valid and runs', () => {
+  const { dir, git } = scratchRepo();
+  // `cp %B %A` stands in for git-merge-regen.js: it resolves by taking theirs, which is
+  // observable in the file afterwards, so this asserts the driver RAN — not merely that
+  // the merge exited 0, which a fallback text merge would also do.
+  git(['config', `merge.${MERGE_DRIVER_NAME}.driver`, 'cp %B %A']);
+  assert.equal(tryMerge(dir), null, 'a driver-only section must merge cleanly');
+  assert.equal(fs.readFileSync(path.join(dir, 'f.md'), 'utf8'), 'theirs\n',
+    'the custom driver must have run — otherwise this proves nothing about ordering');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('registerMergeDriver writes .driver BEFORE .name', () => {
+  const order = [];
+  const run = (_bin, args) => { order.push(args[1]); };
+  const res = registerMergeDriver('/nowhere', { run });
+  assert.equal(res.ok, true);
+  assert.deepEqual(order, [`merge.${MERGE_DRIVER_NAME}.driver`, `merge.${MERGE_DRIVER_NAME}.name`],
+    'order is the fix: the intermediate state after write #1 must be the SAFE one');
+});
+
+test('a failure mid-registration removes the whole section, leaving no trace', () => {
+  const calls = [];
+  const run = (_bin, args) => {
+    calls.push(args);
+    // Fail on the SECOND write (.name) — the exact partial-write this task is about.
+    if (args[1] === `merge.${MERGE_DRIVER_NAME}.name`) throw new Error('simulated config failure');
+  };
+  const res = registerMergeDriver('/nowhere', { run });
+  assert.equal(res.ok, false, 'a failed registration must report failure');
+  assert.match(res.error, /simulated config failure/, 'and must report the ORIGINAL error, not the cleanup');
+  assert.deepEqual(calls[calls.length - 1], ['config', '--remove-section', `merge.${MERGE_DRIVER_NAME}`],
+    'the last action must be removing the section, so nothing partial survives');
+});
+
+test('cleanup failing does not mask the original error', () => {
+  const run = (_bin, args) => {
+    if (args[1] === `merge.${MERGE_DRIVER_NAME}.name`) throw new Error('original failure');
+    if (args[1] === '--remove-section') throw new Error('cleanup also failed');
+  };
+  const res = registerMergeDriver('/nowhere', { run });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /original failure/, 'the reported error must be the one that matters');
+});
+
+test('classifyMergeDriverState: name without driver is the FAIL doctor must surface', () => {
+  const v = classifyMergeDriverState({ name: 'something', driver: '' });
+  assert.equal(v.status, 'fail');
+  assert.equal(v.code, 'name-without-driver');
+  assert.match(v.message, /lacks command line/, 'the message must quote the fatal a builder will actually see');
+  assert.match(v.message, /--remove-section/, 'and must give a way out');
+});
+
+test('classifyMergeDriverState: driver present is ok, with or without a name', () => {
+  assert.equal(classifyMergeDriverState({ name: 'n', driver: 'd' }).status, 'ok');
+  assert.equal(classifyMergeDriverState({ name: '', driver: 'd' }).status, 'ok',
+    'driver-only is a WORKING section (proved against real git above), so it must not be reported as a fault');
+});
+
+test('classifyMergeDriverState: neither set is a warn, not a fail', () => {
+  const v = classifyMergeDriverState({ name: '', driver: '' });
+  assert.equal(v.status, 'warn');
+  assert.equal(v.code, 'unregistered');
+  assert.match(v.message, /ship\.js still self-heals/, 'absent is not a hole in the walls — say so');
+});
+
+test('whitespace-only config values count as absent', () => {
+  assert.equal(classifyMergeDriverState({ name: '   ', driver: '  ' }).code, 'unregistered');
+  assert.equal(classifyMergeDriverState({ name: 'n', driver: '   ' }).code, 'name-without-driver');
+});

package/tests/search_ingest.mjs

@@ -54,10 +54,46 @@ test('CLAUDE.md is xenos (write-protected but READ-PUBLIC — the carve-out)', (
   assert.equal(minRankForDoc('CLAUDE.md'), 'xenos');
 });
 
-test('SENSITIVE_DOC_GLOBS is the curated source of truth (subtrees end with /)', () => {
-  assert.ok(SENSITIVE_DOC_GLOBS.includes('docs/security/'));
-  assert.ok(SENSITIVE_DOC_GLOBS.includes('docs/audits/'));
-  assert.ok(SENSITIVE_DOC_GLOBS.includes('docs/canonical-permissions.md'));
+// EXHAUSTIVE, not a spot-check (task 1002882). The old version asserted three of the
+// six entries with includes(), which meant the list could GAIN or LOSE an entry — a
+// whole read-gated subtree appearing or vanishing — with nothing red. docs/governance/
+// was added under task 1002598 and this test never noticed.
+//
+// A deepEqual pin makes every change to the read floor a deliberate, reviewed edit:
+// you cannot widen or narrow what a sub-Metic search can reach without also editing
+// this line and saying why. The functional assertions above already cover BEHAVIOUR
+// (minRankForDoc returns 'metic'); this one states the list's INTENT, which is the
+// half that was under-described.
+//
+// Keep it in sync with scripts/gds/publish-manifest.js:185, where SENSITIVE_DOC_EXCLUDE
+// is derived from this same array by filtering to docs/security + docs/audits — a
+// silent addition here changes the PUBLISH boundary too.
+test('SENSITIVE_DOC_GLOBS is the curated source of truth (exhaustive pin)', () => {
+  assert.deepEqual(SENSITIVE_DOC_GLOBS, [
+    'docs/canonical-permissions.md',
+    'docs/security/',
+    'docs/audits/',
+    'docs/governance/',
+    'docs/adr/0016-trust-boundary-server-enforced-permissions.md',
+    'docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md',
+  ], 'adding or removing a read-gated doc must be a deliberate edit here, not a silent one');
+
+  // A trailing '/' means "subtree" to the glob dialect this shares with
+  // permission-path-check; a missing one would gate only an exact file of that name.
+  for (const g of ['docs/security/', 'docs/audits/', 'docs/governance/']) {
+    assert.ok(SENSITIVE_DOC_GLOBS.includes(g), `${g} must keep its trailing slash to gate the subtree`);
+  }
+});
+
+// The publish boundary reads this same array, so a change here silently moves what the
+// public AGPL mirror ships. Pin the derivation, not just the source (task 1002882).
+test('SENSITIVE_DOC_EXCLUDE derives docs/security + docs/audits from the same array', () => {
+  const derived = SENSITIVE_DOC_GLOBS.filter(
+    (g) => g.startsWith('docs/security') || g.startsWith('docs/audits')
+  );
+  assert.deepEqual(derived, ['docs/security/', 'docs/audits/'],
+    'publish-manifest.js:185 applies exactly this filter — if the array gains another '
+    + 'docs/security* or docs/audits* entry, the publish denylist changes with it');
 });
 
 test('collectMarkdown finds the repo corpus but excludes node_modules/.git/worktrees/public', () => {