@bongos/core 1.19.968 → 1.19.970

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.970",
+  "core_contract": "1.19.970",
+  "source_commit": "6fcd89630051b6a8a27ab995131716370ed9082e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-22T23:25:06.335Z",
+  "built_at": "2026-09-23T01:02:05.515Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 515,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2365,
+    "functional_verbatim": 2370,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2906,
-  "tree_sha256": "4ccb083b8cb616dd5c4c9c49f498b566996a1ead6ea244f46e5344d7a726a322",
+  "file_count": 2911,
+  "tree_sha256": "60a4632de03ed24bd98cbfe694a93acfed70e02c72838da91213a9c68ad14813",
   "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": "e842c06ae274c61f5f38063af7b5eb5da4798954df2b9e3e42c1929352dd9a3f"
     },
     {
       "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": "b398350d28d5e528b46daafbadd4b19ddd9e9423a0c234aaabd27dc1718d6864"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4d9fb5822b9ba10648ba9d9e0c2bd7c5659215e65bb8395455913b7b14c43998"
+      "sha256": "03e808eb0d1d2cb9be5d0ee13830a79fd5b0752ee5ff7f0a17993df3dc147903"
     },
     {
       "path": "public-docs/index.html",
@@ -8157,7 +8162,7 @@
     {
       "path": "scripts/gds/abandon.js",
       "mode": "0000644",
-      "sha256": "723aea2c66f8897822507a7b3c7556170336ec021676b3cb8898e5c3bc4e98ca"
+      "sha256": "a1246dd85fe90e105561d4069bd65a79fc1b516addbbeea22c69ce3fcf1e19ab"
     },
     {
       "path": "scripts/gds/accessibility-replay.js",
@@ -8467,7 +8472,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "a6c486243cf675fe9929997b09160616cbd05607423b1b6a823d2d57efba7619"
+      "sha256": "013a3ff00e01912efabe65d58d5c2cbff93bd61ad052e645d03c034aff203ddb"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -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",
@@ -8532,7 +8542,7 @@
     {
       "path": "scripts/gds/demote.js",
       "mode": "0000644",
-      "sha256": "ff479b432170d2482efe411c9d0aea43641521ff18a25e4380d5d5e492ec8814"
+      "sha256": "3b80acbc43ce96e07f11e6531c35499bc9a5bf8e4103d57e37c83169afdf0087"
     },
     {
       "path": "scripts/gds/deploy-divergence.js",
@@ -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",
@@ -8902,7 +8912,7 @@
     {
       "path": "scripts/gds/login.js",
       "mode": "0000644",
-      "sha256": "a5502a11527ac903446e13536e78900c3af82b3382757a547e2561761ef7e396"
+      "sha256": "0d719e43955fdbcc40aee500438db5b31c6c006490e90d99caadf31b215196f7"
     },
     {
       "path": "scripts/gds/main-audit.js",
@@ -9077,7 +9087,7 @@
     {
       "path": "scripts/gds/provision-repo.js",
       "mode": "0000644",
-      "sha256": "ab6b240d93920bb81bf096aff9553c478a2c3e8c0c4926b81c468e99aee89d67"
+      "sha256": "6e025cfa37165ff491f736f31bb97fa439e3e6cece9eaeeb4edcd6698e9868c0"
     },
     {
       "path": "scripts/gds/provision-teardown.js",
@@ -9152,7 +9162,7 @@
     {
       "path": "scripts/gds/release.js",
       "mode": "0000644",
-      "sha256": "b7de35b15fef0cd61da00c4c7263920c82fcc0606d9ff787951be6fc1377406e"
+      "sha256": "5c260296937727b4445f4df0b851ba174334b7680b6cad6243cc94b73d3934c4"
     },
     {
       "path": "scripts/gds/rename-goals.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",
@@ -9417,7 +9427,7 @@
     {
       "path": "scripts/gds/setup.js",
       "mode": "0000644",
-      "sha256": "edbebc4a0f4557cc8fc9dd0eb7115379a2fd0e34247725180cfb8eccb1cb0a18"
+      "sha256": "156e63c837a5b3bd57ac3f76c4770ef73ad469d27a6f03f8b8a617b57f4020d0"
     },
     {
       "path": "scripts/gds/ship-check.js",
@@ -9592,7 +9602,7 @@
     {
       "path": "scripts/gds/start.js",
       "mode": "0000644",
-      "sha256": "66874523193640a115f202a31224246b3beea868b7ba017cfc3a35448103a7dc"
+      "sha256": "36c814dcf1b233f2279f1a7b06a337dea0d1799119acbfac004af88c6e1a56d1"
     },
     {
       "path": "scripts/gds/status.js",
@@ -10112,7 +10122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "4f5478f0a18dbb167df7e86861ae757cceaf084a43436461af1fca4855256505"
+      "sha256": "a16e899a5c50b65af3e0976a27e72e2f1e50b7cfc8a8acafc64b19cebae1eb93"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10904,6 +10914,11 @@
       "mode": "0000644",
       "sha256": "3e3e17428a6c8f50ce0512cfacc4e18e0b6a2c506d185fa5f2adf21c9feffe9f"
     },
+    {
+      "path": "tests/cli_err_code.mjs",
+      "mode": "0000644",
+      "sha256": "ec9d2cc2054545b3fc886a9b7168ca851acf4cfb7937fab6e065e8fd7ed5eeb4"
+    },
     {
       "path": "tests/cli_exit_no_abort.mjs",
       "mode": "0000644",
@@ -11049,10 +11064,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 +12644,11 @@
       "mode": "0000644",
       "sha256": "d05b6e354ac08cf5512a62b76b213df44ab1ef8639a1ba635319e9b5e8511a5c"
     },
+    {
+      "path": "tests/merge_driver_register.mjs",
+      "mode": "0000644",
+      "sha256": "c75880064b52b6edb2689232eb1e6401567618f46b16581140685ccceee2d41c"
+    },
     {
       "path": "tests/merge_lease.mjs",
       "mode": "0000644",
@@ -12952,7 +12977,7 @@
     {
       "path": "tests/plain_cards.mjs",
       "mode": "0000644",
-      "sha256": "e7a255bdb636adb6206c9e34bafa007eb7c815a9fe65337aefd79fcc719e3182"
+      "sha256": "90310dd37d97dff67feaed377c2db4efdf906902f5c0fa8f49ee721941c2b272"
     },
     {
       "path": "tests/planning_session_skill.mjs",
@@ -13182,7 +13207,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "b6558cb094a2d38c837d3e5028573c14e5c55c832555b382c1d1135a55b5c6b5"
+      "sha256": "58dd9185b37e9f5654564a5c700e51995b303f26af9eaae3b4b4d3ee29351864"
     },
     {
       "path": "tests/provision_account_identity.mjs",
@@ -13652,7 +13677,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,9 @@ 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)
+  1.19.970 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.969 with no explicit bump. run 35804568036. (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.970",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.968",
+      "version": "1.19.970",
       "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.970",
   "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/abandon.js

@@ -17,7 +17,7 @@
 // the ledger stays complete. Retired the wrong task? POST /tasks/<id>/promote
 // restores it to backlog at the same rank (db.restoreTask) — no Archon SQL needed.
 
-const { cliClient, requireSession, arg } = require('./cli-lib');
+const { errCode, cliClient, requireSession, arg } = require('./cli-lib');
 // task 1003153 — the live-status set, shared with the dead-edge detector so
 // "who did this cut strand" means the same thing in both places.
 const { LIVE_STATUSES } = require('../../modules/lifecycle/dead-deps.js');
@@ -68,12 +68,16 @@ function commitsAheadOfMain(branch) {
   const api = await cliClient();
   const r = await api.tasks.postTasksIdAbandon({ id: taskId, body: { reason } });
   if (!r.ok) {
-    if (r.data?.error === 'cannot_abandon_shipped') {
+    // ADR 0116 nests the slug at error.code; a flat `r.data.error === '…'` compares an
+    // object to a string and never matches, so every branch below was unreachable
+    // against a live server (task 1003658).
+    const code = errCode(r.data);
+    if (code === 'cannot_abandon_shipped') {
       console.error(`Task #${taskId} is shipped — shipped work is immutable history and cannot be abandoned.`);
-    } else if (r.data?.error === 'task_has_active_claim') {
+    } else if (code === 'task_has_active_claim') {
       console.error(`Task #${taskId} has an active claim. Release it first:`);
       console.error(`  node scripts/gds/release.js ${taskId}`);
-    } else if (r.data?.error === 'task_not_found') {
+    } else if (code === 'task_not_found') {
       console.error(`Task #${taskId} not found.`);
     } else if (r.status === 403) {
       console.error('Abandoning a task needs Metic+ rank (ADR 0152).');

package/scripts/gds/cli-lib.js

@@ -1098,7 +1098,58 @@ function cardFlagsFromMe(me) {
   return { level: null, showCard: true, showWidget: enabled, expanded: false };
 }
 
+// ---------------------------------------------------------------------------
+// errCode — read the error slug out of an ADR 0116 response envelope.
+// ---------------------------------------------------------------------------
+// ADR 0116 standardised every failure on a NESTED envelope:
+//
+//     { "error": { "code": "task_not_found", "message": "…", "details": … } }
+//
+// so the obvious-looking `r.data.error === 'task_not_found'` compares an OBJECT to a
+// STRING and is never true. That is not a cosmetic bug: each such comparison guards a
+// helpful, specific message, so against a live server every one of those branches is
+// unreachable and the user falls through to the raw `(409): [object Object]` dump —
+// the failure looks like a tooling crash rather than the clear refusal the server sent.
+//
+// Verified live 2026-09-22 against cloudbongos.com:
+//     POST /api/bongos/tasks/1003846/abandon
+//     -> 409 {"error":{"code":"cannot_abandon_shipped","message":"shipped tasks are immutable history"}}
+//
+// The flat-string fallback is deliberate, not defensive padding: some older routes and
+// every non-envelope transport error (a proxy's plain-text body, a pre-0116 instance an
+// upgraded CLI is talking to) still surface `error` as a bare string. Reading both is
+// what makes one helper safe to use everywhere.
+//
+// Fixed in ship.js under task 1002789; extracted here under task 1003658 so the next
+// caller cannot reintroduce the same comparison. Pure — tests/cli_err_code.mjs.
+function errCode(data) {
+  const e = data && data.error;
+  if (typeof e === 'string') return e;
+  if (e && typeof e === 'object' && typeof e.code === 'string') return e.code;
+  return null;
+}
+
+// errDetails — the structured payload beside the slug, same envelope.
+//
+// This matters as much as errCode and is easy to miss: the sibling fields moved WITH
+// the code. demote.js printed `r.data.current_status` beside its message; ADR 0116 put
+// that at `error.details.current_status`, so a fix that changed only the comparison
+// would have restored the branch and then printed "it is 'undefined', not 'ready'" —
+// a half-fix that looks like a whole one. Verified live 2026-09-22:
+//
+//     POST /api/bongos/tasks/1003846/demote
+//     -> 409 {"error":{"code":"cannot_demote","details":{"current_status":"shipped"}}}
+//
+// Falls back to the top-level body so a pre-0116 flat response still resolves.
+function errDetails(data) {
+  const e = data && data.error;
+  if (e && typeof e === 'object' && e.details && typeof e.details === 'object') return e.details;
+  return (data && typeof data === 'object') ? data : {};
+}
+
 module.exports = {
+  errCode,
+  errDetails,
   API_BASE,
   detectWorktreeName,
   hallBase,

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/demote.js

@@ -9,7 +9,7 @@
 // prod. Strictly ready -> backlog — the server refuses any other status (a
 // claimed/active task, or a later lifecycle state). Metic+ only (mirrors promote).
 
-const { cliClient, requireSession } = require('./cli-lib');
+const { cliClient, errCode, errDetails, requireSession } = require('./cli-lib');
 
 (async () => {
   await requireSession();
@@ -23,10 +23,15 @@ const { cliClient, requireSession } = require('./cli-lib');
   const api = await cliClient();
   const r = await api.tasks.postTasksIdDemote({ id: taskId });
   if (!r.ok) {
-    if (r.data?.error === 'cannot_demote') {
-      console.error(`Cannot demote task #${taskId}: it is '${r.data.current_status}', not 'ready'.`);
+    // ADR 0116 nests BOTH the slug and its payload — see the note in cli-lib errCode
+    // (task 1003658). current_status moved to error.details with the code, so reading
+    // it off the top level printed 'undefined' even once the branch was reachable.
+    const code = errCode(r.data);
+    const details = errDetails(r.data);
+    if (code === 'cannot_demote') {
+      console.error(`Cannot demote task #${taskId}: it is '${details.current_status}', not 'ready'.`);
       console.error("demote only moves a task ready -> backlog (the inverse of promote).");
-    } else if (r.data?.error === 'task_not_found') {
+    } else if (code === 'task_not_found') {
       console.error(`No task #${taskId}.`);
     } else {
       console.error(`demote failed (${r.status}):`, r.data);