@bongos/core 1.19.968 → 1.19.970

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

@@ -22,7 +22,7 @@
 
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
-const { saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
+const { errCode, saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
 // The device-flow refusal detector + its plain-language cure (task 1003881). A leaf
 // module, NOT setup.js: setup requires this file for runDeviceFlow, so requiring it
 // back would close a require cycle. Both callers depend on the leaf instead.
@@ -104,7 +104,11 @@ async function runDeviceFlow(base, { log, idp = null }) {
     // assertion scoped to the instance the user actually typed (ADR 0141 §1).
     ...(idp ? { body: JSON.stringify({ origin: base }) } : {}),
   });
-  if (start.status === 503 || (start.data && (start.data.error === 'auth_not_configured' || (start.data.error && start.data.error.code === 'idp_signing_unconfigured')))) {
+  // ADR 0116 nests the slug at error.code (task 1003658). This site was half-converted:
+  // it read the nested shape for idp_signing_unconfigured but kept a FLAT comparison for
+  // auth_not_configured, so that arm was dead against a live server. errCode reads both.
+  const startCode = errCode(start.data);
+  if (start.status === 503 || startCode === 'auth_not_configured' || startCode === 'idp_signing_unconfigured') {
     throw new Error('that instance has no sign-in configured yet — ask its Archon to set it up.');
   }
   // Device Flow is OFF on every GitHub App born from a manifest, and GitHub exposes no

package/scripts/gds/provision-repo.js

@@ -871,6 +871,15 @@ function deployKeyPath(inst) { return path.posix.join(standaloneRoot(inst), '.gi
 // github.com and core.sshCommand pinned to the key with -F /dev/null so no
 // ~/.ssh/config identity can shadow it. Public repos return untouched; no token →
 // skip (the request-time refusal is task 1002909's preflight). Dry-run plans only.
+//
+// `deps.intendedPrivate` (task 1004167) declares that the repo is ABOUT to be made
+// private, so the wiring runs before the flip rather than after it. Opt-in, and it
+// widens only WHEN we wire: the key stays read-only and repository ADMIN is still
+// required. It also HARDENS the two soft skips — no credential, GitHub unreachable —
+// into refusals, because a caller that has committed to flipping cannot be handed an
+// unwired checkout. NO PRODUCTION CALLER SETS IT YET: the flip route and its
+// provisioning intent are splits (b) + (c) of task 1003078, which need a migration
+// this deliberately does not. The seam ships first so the ordering is settled.
 async function ensurePrivateRepoAccess(inst, deps) {
   const { log, apply } = deps;
   const exec = deps.controlExec || deps.exec;
@@ -881,11 +890,19 @@ async function ensurePrivateRepoAccess(inst, deps) {
   // preflight is apply-gated for the same reason): no token read, no GitHub call —
   // a plan run must stay a safe inspection tool for a snagged instance.
   if (!apply) {
-    log(`  [repo-auth] would check ${repo.owner}/${repo.name} visibility with the owner's credential and, if PRIVATE, mint + register a read-only deploy key and wire origin + core.sshCommand to it (ADR 0176)`);
+    log(deps.intendedPrivate === true
+      ? `  [repo-auth] would treat ${repo.owner}/${repo.name} as ABOUT TO BE MADE PRIVATE (pre-flip) and mint + register a read-only deploy key, wiring origin + core.sshCommand to it before the flip (ADR 0176)`
+      : `  [repo-auth] would check ${repo.owner}/${repo.name} visibility with the owner's credential and, if PRIVATE, mint + register a read-only deploy key and wire origin + core.sshCommand to it (ADR 0176)`);
     return { planned: true };
   }
   const ownerToken = await resolveOwnerGithubToken(inst, deps);
   if (!ownerToken) {
+    // With an intent declared the caller is ABOUT to flip, so a soft skip hands back
+    // an unwired checkout and the flip then breaks the recurring pull for good. The
+    // same missing credential is only a warning when nobody has committed to flipping.
+    if (deps.intendedPrivate === true) {
+      throw new Error(`${repo.owner}/${repo.name} cannot be made private: there is no usable GitHub credential stored for this project, and without one its deploy key cannot be registered — which would break the next deploy. Reconnect the project's GitHub access, then try again.`);
+    }
     log('  [repo-auth] no usable owner GitHub credential (none stored, or it could not be read) — a PRIVATE repo would fail at the deploy pull (public repos are unaffected)');
     return { skipped: 'no_token' };
   }
@@ -898,6 +915,11 @@ async function ensurePrivateRepoAccess(inst, deps) {
       // Plain sentence: this rides error_note onto the owner's project card.
       throw new Error(`repository not found: GitHub answered 404 for ${repo.owner}/${repo.name} even with your granted credential — the repository may have been renamed or deleted, or the credential lost access. Check it on GitHub, then try again.`);
     }
+    // Same asymmetry as the missing credential above: soft when nothing is committed,
+    // hard once the caller has declared the flip.
+    if (deps.intendedPrivate === true) {
+      throw new Error(`${repo.owner}/${repo.name} cannot be made private right now: GitHub could not be reached to set up its deploy key (${e && e.message}). Nothing has been changed — try again.`);
+    }
     log(`  [repo-auth] could not read ${repo.owner}/${repo.name} (${e && e.message}) — continuing; a PRIVATE repo would fail at the deploy pull`);
     return { skipped: 'github_unreachable' };
   }
@@ -907,7 +929,16 @@ async function ensurePrivateRepoAccess(inst, deps) {
   const title = deployKeyTitle(inst);
   const fsImpl = deps.fsImpl || fs;
 
-  if (!info.private) {
+  // A flip-to-private must wire BEFORE it flips — a deploy key authenticates fine
+  // against a still-public repo, so wiring first leaves no broken window, while
+  // flipping first breaks the very next deploy pull. At that moment GitHub still
+  // answers `private: false`, so the observed value is the wrong thing to branch on:
+  // untouched, this takes the public path and (worse, if a key file exists) actively
+  // UN-wires. `intendedPrivate` is the caller declaring where the repo is going.
+  // Opt-in: absent, every path below is exactly what it was.
+  const treatPrivate = info.private || deps.intendedPrivate === true;
+
+  if (!treatPrivate) {
     // Flipped private → public since we wired it: un-wire, or the checkout stays
     // pinned (IdentitiesOnly + -F /dev/null admit no other identity) to a key the
     // owner is now free to delete from their repo settings. Keyed on our key file
@@ -933,7 +964,9 @@ async function ensurePrivateRepoAccess(inst, deps) {
     throw new Error(`repository access is not admin: your granted credential can read ${repo.owner}/${repo.name}, but registering its deploy key needs repository ADMIN. Ask a repository admin to raise your access (or make the repository public), then try again.`);
   }
 
-  log(`  [repo-auth] ${repo.owner}/${repo.name} is PRIVATE — wiring its own read-only deploy key (ADR 0176)`);
+  log(info.private
+    ? `  [repo-auth] ${repo.owner}/${repo.name} is PRIVATE — wiring its own read-only deploy key (ADR 0176)`
+    : `  [repo-auth] ${repo.owner}/${repo.name} is ABOUT TO BE MADE PRIVATE — wiring its own read-only deploy key first (ADR 0176)`);
   if (!fsImpl.existsSync(keyPath) || !fsImpl.existsSync(`${keyPath}.pub`)) {
     exec(`rm -f ${keyPath} ${keyPath}.pub`, { allowFail: true });
     exec(`ssh-keygen -q -t ed25519 -N '' -C ${title} -f ${keyPath}`);

package/scripts/gds/release.js

@@ -8,7 +8,7 @@
 
 const { execFileSync } = require('node:child_process');
 const path = require('node:path');
-const { cliClient, requireSession, arg } = require('./cli-lib');
+const { errCode, errDetails, cliClient, requireSession, arg } = require('./cli-lib');
 const { parkedMainCheckoutWarning } = require('./worktree-claim-guard');
 const { plainCardLines } = require('./plain-cards');
 
@@ -96,8 +96,16 @@ function mainCheckoutRoot() {
     },
   });
   if (!r.ok) {
-    if (r.data?.error === 'CLAIM_SESSION_MISMATCH') {
-      const wt = r.data.claimWorktree;
+    // ADR 0116 nests the slug at error.code AND its payload at error.details — see the
+    // note in abandon.js (task 1003658). claimWorktree reaches the wire through
+    // `res.fail(err.code, status, { ...err })` in modules/lifecycle/routes/claims.js:612,
+    // so it lands in details, not at the top level. Reading it off r.data directly made
+    // `wt` undefined and silently dropped the worktree name from the message — the exact
+    // half-fix this task exists to avoid, caught by the grader on the first round.
+    const code = errCode(r.data);
+    const details = errDetails(r.data);
+    if (code === 'CLAIM_SESSION_MISMATCH') {
+      const wt = details.claimWorktree;
       console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
       console.error('Only the original session can release it.');
       console.error('If that session is gone, re-run with --force to override.');

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/scripts/gds/setup.js

@@ -19,7 +19,7 @@
 // home directory) and prints the builder profile.
 
 const readline = require('readline');
-const { cliClient, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE, hallBase, surfaceAction, isTerminalSurface } = require('./cli-lib');
+const { cliClient, errCode, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE, hallBase, surfaceAction, isTerminalSurface } = require('./cli-lib');
 
 // The instance's status dashboard, from branding — never a hardcoded host, so a
 // non-OTB instance points its builders at ITS OWN dashboard (task 1002428).
@@ -566,7 +566,7 @@ async function main() {
       process.exit(0);
     }
     console.error(`device/start failed (${start.status}):`, start.data);
-    if (start.data?.error === 'auth_not_configured') {
+    if (errCode(start.data) === 'auth_not_configured') {  // ADR 0116 nests the slug (task 1003658)
       console.error('');
       console.error('The server does not yet have GitHub OAuth credentials.');
       console.error('An Archon needs to register the GitHub OAuth App and provision credentials on the server.');

package/scripts/gds/start.js

@@ -67,7 +67,7 @@ const { checkTree: _checkTree } = require('./tree-preflight.js');
   if (_fault) { console.error(_fault); process.exit(1); }
 }
 
-const { cliClient, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge, hallBase, API_BASE, rewardPolicy, costPlusOnlyNote, isDispatcherIncompatError, cardFlagsFromMe } = require('./cli-lib');
+const { cliClient, errCode, errDetails, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge, hallBase, API_BASE, rewardPolicy, costPlusOnlyNote, isDispatcherIncompatError, cardFlagsFromMe } = require('./cli-lib');
 const { plainCardLines } = require('./plain-cards');
 const { contextPack, formatContextPackCompact } = require('./context-pack');
 const { depsFinding } = require('./preflight');
@@ -723,9 +723,13 @@ async function main() {
   // #766: the primer-read gate on the claimable endpoint was removed, so a
   // newcomer no longer gets a 403 stage_required here. A generic stage_required
   // (any future onboarding gate) still renders cleanly rather than crashing.
-  if (r.status === 403 && r.data && r.data.error === 'stage_required') {
+  // ADR 0116 nests the slug and its payload — see the note in cli-lib errCode (task
+  // 1003658). The onboarding copy lives in error.details, so reading it off the top
+  // level rendered an empty prompt even when the branch fired.
+  if (r.status === 403 && errCode(r.data) === 'stage_required') {
+    const d = errDetails(r.data);
     console.log('');
-    console.log(r.data.what_to_do || `Clear "${r.data.required_stage_label || r.data.required_stage}" before the work queue opens.`);
+    console.log(d.what_to_do || `Clear "${d.required_stage_label || d.required_stage}" before the work queue opens.`);
     for (const line of plainCardLines('stage_required')) console.log(line);
     console.log('');
     process.exit(0);

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.970'; // 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/cli_err_code.mjs

@@ -0,0 +1,148 @@
+// tests/cli_err_code.mjs
+//
+// Task 1003658 — ADR 0116 standardised every failure on a NESTED envelope:
+//
+//     { "error": { "code": "task_not_found", "message": "…", "details": {…} } }
+//
+// so `r.data.error === 'task_not_found'` compares an OBJECT to a STRING and is never
+// true. Each such comparison guarded a specific, helpful message, so against a live
+// server every one of those branches was UNREACHABLE and the user fell through to a raw
+// `(409): [object Object]` dump — a clear server refusal rendered as a tooling crash.
+//
+// NINE sites across SIX scripts now route through errCode/errDetails: abandon x3,
+// release, demote x2, setup, start, login. (login.js was HALF converted — nested for
+// idp_signing_unconfigured, flat for auth_not_configured — so one arm was dead. It was
+// found by the source scan at the bottom of this file, not by reading.)
+//
+// THE HALF-FIX THIS ALSO GUARDS AGAINST. The sibling fields moved WITH the code.
+// demote.js printed `r.data.current_status` beside its message; 0116 put that at
+// `error.details.current_status`. Changing only the comparison restores the branch and
+// then prints "it is 'undefined', not 'ready'" — which looks like a whole fix. Both
+// readers are therefore tested, and both are tested against the REAL shapes observed
+// live on 2026-09-22 rather than shapes we assumed.
+//
+// Run:  node --test tests/cli_err_code.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { errCode, errDetails } = require(path.join(REPO_ROOT, 'scripts/gds/cli-lib.js'));
+
+// Captured verbatim from cloudbongos.com on 2026-09-22 — not invented.
+const LIVE_ABANDON_SHIPPED = { error: { code: 'cannot_abandon_shipped', message: 'shipped tasks are immutable history' } };
+const LIVE_DEMOTE_REFUSED = { error: { code: 'cannot_demote', message: 'cannot_demote', details: { current_status: 'shipped' } } };
+const LIVE_NOT_FOUND = { error: { code: 'task_not_found', message: 'task_not_found' } };
+
+test('THE BUG: the old flat comparison never matches a real envelope', () => {
+  // This is the whole finding. If this assertion ever fails, the envelope changed and
+  // the fix below is no longer needed — which is worth knowing loudly.
+  assert.notEqual(LIVE_ABANDON_SHIPPED.error, 'cannot_abandon_shipped');
+  assert.equal(typeof LIVE_ABANDON_SHIPPED.error, 'object',
+    'error is an OBJECT — comparing it to a string is why every branch was dead');
+});
+
+test('errCode reads the slug out of real observed envelopes', () => {
+  assert.equal(errCode(LIVE_ABANDON_SHIPPED), 'cannot_abandon_shipped');
+  assert.equal(errCode(LIVE_DEMOTE_REFUSED), 'cannot_demote');
+  assert.equal(errCode(LIVE_NOT_FOUND), 'task_not_found');
+});
+
+test('errCode still reads a legacy flat string', () => {
+  // Older routes, and any non-envelope transport error (a proxy returning a plain body,
+  // or a pre-0116 instance an upgraded CLI is talking to) still surface a bare string.
+  assert.equal(errCode({ error: 'auth_not_configured' }), 'auth_not_configured');
+});
+
+test('errCode returns null rather than throwing on anything unexpected', () => {
+  for (const input of [null, undefined, {}, { error: null }, { error: {} }, { error: 42 }, { error: { code: 7 } }, 'a string']) {
+    assert.equal(errCode(input), null, `errCode(${JSON.stringify(input)}) must be null, never a throw`);
+  }
+});
+
+test('THE HALF-FIX GUARD: errDetails finds the sibling field 0116 moved', () => {
+  assert.equal(errDetails(LIVE_DEMOTE_REFUSED).current_status, 'shipped',
+    'reading current_status off the top level yields undefined — the half-fix this prevents');
+  assert.equal(LIVE_DEMOTE_REFUSED.current_status, undefined,
+    'proving the naive read really is empty, so the guard is not vacuous');
+});
+
+test('errDetails falls back to the top-level body for a pre-0116 shape', () => {
+  assert.equal(errDetails({ error: 'cannot_demote', current_status: 'shipped' }).current_status, 'shipped');
+});
+
+test('errDetails always returns an object, so callers can destructure safely', () => {
+  for (const input of [null, undefined, {}, { error: {} }, { error: { details: 'not-an-object' } }]) {
+    assert.equal(typeof errDetails(input), 'object');
+    assert.notEqual(errDetails(input), null);
+  }
+});
+
+test('no flat `.error === <string>` comparison survives in scripts/gds', () => {
+  // The durable half: this is what stops a sixth script reintroducing the bug. It scans
+  // source rather than trusting that the sweep was complete — the filed row said 11
+  // sites across 6 scripts, a later correction said 4 across 2, and the truth was 8
+  // across 5. A count in prose rots; a scan does not.
+  const fs = require('node:fs');
+  const dir = path.join(REPO_ROOT, 'scripts/gds');
+  const offenders = [];
+  for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.js'))) {
+    const src = fs.readFileSync(path.join(dir, f), 'utf8');
+    src.split('\n').forEach((line, i) => {
+      if (/^\s*(\/\/|\*)/.test(line)) return;            // commentary may quote the bug
+      if (/\.data\??\.error\s*===\s*['"]/.test(line)) offenders.push(`${f}:${i + 1}: ${line.trim()}`);
+    });
+  }
+  assert.deepEqual(offenders, [],
+    'use errCode(r.data) — a flat comparison against the ADR 0116 envelope is always false');
+});
+
+// ---------------------------------------------------------------------------
+// End-to-end branch selection (grader finding, round 1).
+// ---------------------------------------------------------------------------
+// The tests above prove the PRIMITIVE is right. They do not prove each script WIRED it
+// right — a script could call errCode() and still order its if/else wrongly, or read a
+// sibling field off the top level. That second mistake is not hypothetical: the first
+// round of this task shipped exactly it in release.js (`r.data.claimWorktree`, which
+// ADR 0116 moved to error.details), and only the grader caught it.
+//
+// So this block asserts the WIRING, by the one property that distinguishes a real fix
+// from a half fix: for every branch, no sibling field may be read off the top level of
+// the response body. It scans source rather than spawning the CLIs, because spawning
+// them needs a live server and a session — which would make this an integration test
+// that silently self-skips, the failure mode tests/copy_inventory-class suites already
+// demonstrate.
+test('no converted branch reads a sibling payload field off the top level', () => {
+  const fs = require('node:fs');
+  // The fields ADR 0116 moved into error.details, and the scripts that render them.
+  const MOVED = ['claimWorktree', 'current_status', 'what_to_do', 'required_stage_label', 'required_stage'];
+  const offenders = [];
+  for (const f of ['abandon.js', 'release.js', 'demote.js', 'setup.js', 'start.js', 'login.js']) {
+    const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts/gds', f), 'utf8');
+    src.split('\n').forEach((line, i) => {
+      if (/^\s*(\/\/|\*)/.test(line)) return;
+      for (const field of MOVED) {
+        if (new RegExp(`\\.data\\??\\.${field}\\b`).test(line)) offenders.push(`${f}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+  assert.deepEqual(offenders, [],
+    'ADR 0116 moved these beside the code into error.details — read them via errDetails(r.data), '
+    + 'or the branch fires and then renders undefined (the half-fix)');
+});
+
+test('every script that compares an error code imports errCode', () => {
+  const fs = require('node:fs');
+  const missing = [];
+  for (const f of fs.readdirSync(path.join(REPO_ROOT, 'scripts/gds')).filter((n) => n.endsWith('.js'))) {
+    const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts/gds', f), 'utf8');
+    const uses = /\berrCode\s*\(/.test(src);
+    const imports = /require\('\.\/cli-lib'\)/.test(src) && /\berrCode\b/.test(src.split('\n').find((l) => l.includes("require('./cli-lib')")) || '');
+    if (uses && !imports && f !== 'cli-lib.js') missing.push(f);
+  }
+  assert.deepEqual(missing, [], 'a script calling errCode() without importing it throws at the branch it was meant to fix');
+});

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