@bongos/core 1.19.969 → 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.969",
-  "core_contract": "1.19.969",
-  "source_commit": "55409bed0b968ea075ebd993255b3e71131ad01e",
+  "core_version": "1.19.970",
+  "core_contract": "1.19.970",
+  "source_commit": "6fcd89630051b6a8a27ab995131716370ed9082e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-22T23:40:21.961Z",
+  "built_at": "2026-09-23T01:02:05.515Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 515,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2369,
+    "functional_verbatim": 2370,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2910,
-  "tree_sha256": "46d085a64c600456dab078e43c39f7b0bdff7a4d90ca202ebdfff0bb0cd98581",
+  "file_count": 2911,
+  "tree_sha256": "60a4632de03ed24bd98cbfe694a93acfed70e02c72838da91213a9c68ad14813",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2697,7 +2697,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8874af5deda6102925f3caea6c829bc6c637ec707eb7b6cf8ef67fa79b0919a7"
+      "sha256": "e842c06ae274c61f5f38063af7b5eb5da4798954df2b9e3e42c1929352dd9a3f"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8107,12 +8107,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ede312c963ab08f5b2fec23b90c3c5fc829149893c08e83196be37b2a3ef11b5"
+      "sha256": "b398350d28d5e528b46daafbadd4b19ddd9e9423a0c234aaabd27dc1718d6864"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "40a32e40062ce4becee8999e5b2cdb5dd54d5a0ad65885341afcf3651e002d55"
+      "sha256": "03e808eb0d1d2cb9be5d0ee13830a79fd5b0752ee5ff7f0a17993df3dc147903"
     },
     {
       "path": "public-docs/index.html",
@@ -8162,7 +8162,7 @@
     {
       "path": "scripts/gds/abandon.js",
       "mode": "0000644",
-      "sha256": "723aea2c66f8897822507a7b3c7556170336ec021676b3cb8898e5c3bc4e98ca"
+      "sha256": "a1246dd85fe90e105561d4069bd65a79fc1b516addbbeea22c69ce3fcf1e19ab"
     },
     {
       "path": "scripts/gds/accessibility-replay.js",
@@ -8472,7 +8472,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "a6c486243cf675fe9929997b09160616cbd05607423b1b6a823d2d57efba7619"
+      "sha256": "013a3ff00e01912efabe65d58d5c2cbff93bd61ad052e645d03c034aff203ddb"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8542,7 +8542,7 @@
     {
       "path": "scripts/gds/demote.js",
       "mode": "0000644",
-      "sha256": "ff479b432170d2482efe411c9d0aea43641521ff18a25e4380d5d5e492ec8814"
+      "sha256": "3b80acbc43ce96e07f11e6531c35499bc9a5bf8e4103d57e37c83169afdf0087"
     },
     {
       "path": "scripts/gds/deploy-divergence.js",
@@ -8912,7 +8912,7 @@
     {
       "path": "scripts/gds/login.js",
       "mode": "0000644",
-      "sha256": "a5502a11527ac903446e13536e78900c3af82b3382757a547e2561761ef7e396"
+      "sha256": "0d719e43955fdbcc40aee500438db5b31c6c006490e90d99caadf31b215196f7"
     },
     {
       "path": "scripts/gds/main-audit.js",
@@ -9087,7 +9087,7 @@
     {
       "path": "scripts/gds/provision-repo.js",
       "mode": "0000644",
-      "sha256": "ab6b240d93920bb81bf096aff9553c478a2c3e8c0c4926b81c468e99aee89d67"
+      "sha256": "6e025cfa37165ff491f736f31bb97fa439e3e6cece9eaeeb4edcd6698e9868c0"
     },
     {
       "path": "scripts/gds/provision-teardown.js",
@@ -9162,7 +9162,7 @@
     {
       "path": "scripts/gds/release.js",
       "mode": "0000644",
-      "sha256": "b7de35b15fef0cd61da00c4c7263920c82fcc0606d9ff787951be6fc1377406e"
+      "sha256": "5c260296937727b4445f4df0b851ba174334b7680b6cad6243cc94b73d3934c4"
     },
     {
       "path": "scripts/gds/rename-goals.js",
@@ -9427,7 +9427,7 @@
     {
       "path": "scripts/gds/setup.js",
       "mode": "0000644",
-      "sha256": "edbebc4a0f4557cc8fc9dd0eb7115379a2fd0e34247725180cfb8eccb1cb0a18"
+      "sha256": "156e63c837a5b3bd57ac3f76c4770ef73ad469d27a6f03f8b8a617b57f4020d0"
     },
     {
       "path": "scripts/gds/ship-check.js",
@@ -9602,7 +9602,7 @@
     {
       "path": "scripts/gds/start.js",
       "mode": "0000644",
-      "sha256": "66874523193640a115f202a31224246b3beea868b7ba017cfc3a35448103a7dc"
+      "sha256": "36c814dcf1b233f2279f1a7b06a337dea0d1799119acbfac004af88c6e1a56d1"
     },
     {
       "path": "scripts/gds/status.js",
@@ -10122,7 +10122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "37d85c40aec959cbe0091ef9f1c2d14831fcc8271dcaf91a8d42c5d879a80878"
+      "sha256": "a16e899a5c50b65af3e0976a27e72e2f1e50b7cfc8a8acafc64b19cebae1eb93"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10914,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",
@@ -12972,7 +12977,7 @@
     {
       "path": "tests/plain_cards.mjs",
       "mode": "0000644",
-      "sha256": "e7a255bdb636adb6206c9e34bafa007eb7c815a9fe65337aefd79fcc719e3182"
+      "sha256": "90310dd37d97dff67feaed377c2db4efdf906902f5c0fa8f49ee721941c2b272"
     },
     {
       "path": "tests/planning_session_skill.mjs",
@@ -13202,7 +13207,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "b6558cb094a2d38c837d3e5028573c14e5c55c832555b382c1d1135a55b5c6b5"
+      "sha256": "58dd9185b37e9f5654564a5c700e51995b303f26af9eaae3b4b4d3ee29351864"
     },
     {
       "path": "tests/provision_account_identity.mjs",

package/docs/module-api-changelog.md

@@ -2412,5 +2412,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.969",
+  "version": "1.19.970",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.969",
+      "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.969",
+  "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/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);

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/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.969'; // 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/plain_cards.mjs

@@ -181,7 +181,11 @@ test('the sign-in printers, the release refusals and the claim guard each print
 
 test('every way start.js can refuse or fail prints a card', () => {
   const src = read('scripts/gds/start.js');
-  const codes = [...src.matchAll(/\.error === '([A-Za-z_]+)'/g)].map((m) => m[1]);
+  // BOTH spellings, or this assertion pins the bug it was written above: ADR 0116
+  // nests the slug as `{ error: { code } }`, so the flat `.error === 'slug'` compares
+  // an object to a string and is never true. Task 1003658 moved the live site to
+  // errCode(); matching only the flat form made the FIX read as "the branch moved".
+  const codes = [...src.matchAll(/(?:\.error|errCode\([^)]*\)) === '([A-Za-z_]+)'/g)].map((m) => m[1]);
   assert.ok(codes.includes('stage_required'), 'start.js no longer names its refusal — has the branch moved?');
   assert.deepEqual(missing(codes), []);
   for (const code of [...new Set(codes)]) assert.ok(src.includes(`plainCardLines('${code}')`), `start.js never prints the ${code} card`);

package/tests/provision.mjs

@@ -2858,6 +2858,111 @@ await ta('ensurePrivateRepoAccess(dry-run): fully OFFLINE — no token read, no
   assert.equal(tokenReads, 0, 'not even the credential read');
 });
 
+console.log('\nflip-to-private: wiring BEFORE the flip (task 1004167):');
+
+// The flip must wire first and flip second — a deploy key authenticates fine against a
+// still-public repo, so wiring first leaves no broken window, whereas flipping first
+// breaks the very next deploy pull. But at wire time GitHub still answers `private:
+// false`, and the function branches on that OBSERVED value. `intendedPrivate` is the
+// caller's declaration of where the repo is going.
+
+await ta('intendedPrivate: wires a repo GitHub still reports PUBLIC — the pre-flip window', async () => {
+  const { deps, cmds, apiCalls } = repoAuthDeps({ priv: false, existing: false });
+  deps.intendedPrivate = true;
+  const r = await P.ensurePrivateRepoAccess(privInst, deps);
+  assert.equal(r.private, true, 'the declared INTENT decides, not the current visibility');
+  const add = apiCalls.find((c) => c[0] === 'add');
+  assert.ok(add, 'the key registers while the repo is still public — it authenticates either way');
+  assert.equal(add[3], true, 'still read-only: the override widens WHEN we wire, never what the key may do');
+  const joined = cmds.join('\n');
+  assert.match(joined, /ssh-keygen -q -t ed25519/);
+  assert.match(joined, /remote set-url origin git@github\.com:example-owner\/demo\.git/);
+  assert.match(joined, /config core\.sshCommand/);
+});
+
+await ta('intendedPrivate: does NOT un-wire an existing key — the un-wire branch is what made pre-flip wiring impossible', async () => {
+  const { deps, cmds, apiCalls } = repoAuthDeps({
+    priv: false, existing: true,
+    keys: [{ id: 11, title: 'cloudbongos-deploy-demo', key: 'ssh-ed25519 AAAAlocal', read_only: true }],
+  });
+  deps.intendedPrivate = true;
+  const r = await P.ensurePrivateRepoAccess(privInst, deps);
+  assert.ok(!r.unwired, 'the caller asked for wiring; tearing it down is the exact opposite');
+  assert.ok(!apiCalls.some((c) => c[0] === 'del'), 'the registered key survives');
+  const joined = cmds.join('\n');
+  assert.ok(!/config --unset core\.sshCommand/.test(joined), 'sshCommand stays pinned');
+  assert.ok(!/remote set-url origin git@github-deploy:/.test(joined), 'origin is not returned to the shared alias');
+});
+
+await ta('intendedPrivate does NOT bypass the admin precondition', async () => {
+  const { deps, cmds, apiCalls } = repoAuthDeps({ priv: false, existing: false });
+  deps.intendedPrivate = true;
+  deps.githubRepos.getUserRepo = async () => ({ full_name: 'example-owner/demo', private: false, admin: false });
+  await assert.rejects(() => P.ensurePrivateRepoAccess(privInst, deps), /repository access is not admin: .*ADMIN/);
+  assert.ok(!cmds.some((c) => /ssh-keygen/.test(c)), 'no key minted for a credential that cannot register it');
+  assert.ok(!apiCalls.some((c) => c[0] === 'add'));
+});
+
+await ta('no override → every existing path is byte-identical (the override is opt-in only)', async () => {
+  const { deps, cmds, apiCalls } = repoAuthDeps({ priv: false, existing: false });
+  const r = await P.ensurePrivateRepoAccess(privInst, deps);
+  assert.equal(r.private, false);
+  assert.equal(cmds.length, 0);
+  assert.deepEqual(apiCalls.map((c) => c[0]), ['get'], 'still one visibility read and nothing else');
+});
+
+// A declared intent changes what a soft skip MEANS. Without it, "no credential" is a
+// warning about a repo that merely might be private. With it, the caller is about to
+// flip — so skipping quietly hands back an unwired checkout and the flip then breaks
+// the recurring pull for good (walk finding N4, the thing ADR 0176 exists to prevent).
+
+await ta('intendedPrivate + no token: REFUSES rather than skipping — a silent skip would break the next pull', async () => {
+  const { deps, cmds, apiCalls } = repoAuthDeps({ token: null });
+  deps.intendedPrivate = true;
+  await assert.rejects(() => P.ensurePrivateRepoAccess(privInst, deps), /cannot be made private[\s\S]*credential/i);
+  assert.equal(cmds.length, 0);
+  assert.equal(apiCalls.length, 0);
+});
+
+await ta('intendedPrivate + unreachable GitHub: REFUSES rather than skipping', async () => {
+  const { deps, cmds } = repoAuthDeps({ existing: false });
+  deps.intendedPrivate = true;
+  deps.githubRepos.getUserRepo = async () => { throw new Error('socket hang up'); };
+  await assert.rejects(() => P.ensurePrivateRepoAccess(privInst, deps), /cannot be made private[\s\S]*try again/i);
+  assert.ok(!cmds.some((c) => /ssh-keygen/.test(c)), 'nothing wired on a read we could not complete');
+});
+
+await ta('without the intent, both soft skips stay soft (unchanged for every existing caller)', async () => {
+  const noTok = repoAuthDeps({ token: null });
+  assert.equal((await P.ensurePrivateRepoAccess(privInst, noTok.deps)).skipped, 'no_token');
+  const unreach = repoAuthDeps({ existing: false });
+  unreach.deps.githubRepos.getUserRepo = async () => { throw new Error('socket hang up'); };
+  assert.equal((await P.ensurePrivateRepoAccess(privInst, unreach.deps)).skipped, 'github_unreachable');
+});
+
+await ta('intendedPrivate: the apply-path log does not claim the repo IS private when GitHub says otherwise', async () => {
+  const lines = [];
+  const { deps } = repoAuthDeps({ priv: false, existing: false });
+  deps.intendedPrivate = true;
+  deps.log = (m) => lines.push(String(m));
+  await P.ensurePrivateRepoAccess(privInst, deps);
+  const joined = lines.join('\n');
+  assert.doesNotMatch(joined, /is PRIVATE/, 'GitHub reported it public — the ops log must not misstate that');
+  assert.match(joined, /ABOUT TO BE MADE PRIVATE/);
+});
+
+await ta('intendedPrivate(dry-run): names the pre-flip intent in the plan line, and stays OFFLINE', async () => {
+  const lines = [];
+  const { deps, cmds, apiCalls } = repoAuthDeps({ apply: false, priv: false, existing: false });
+  deps.intendedPrivate = true;
+  deps.log = (m) => lines.push(String(m));
+  const r = await P.ensurePrivateRepoAccess(privInst, deps);
+  assert.equal(r.planned, true);
+  assert.equal(cmds.length, 0, 'no mutation in dry-run');
+  assert.deepEqual(apiCalls, [], 'a plan run stays a safe inspection tool');
+  assert.match(lines.join('\n'), /ABOUT TO BE MADE PRIVATE/, 'the plan says which intent it planned for');
+});
+
 await ta('provisionInstance(standalone): the private-repo wiring lands BETWEEN the scaffold and the step-2 pull', async () => {
   const { deps, cmds } = repoAuthDeps({ existing: false });
   const r = await P.provisionInstance({ ...coTenant, hosting_shape: 'standalone', target_ref: 'example-owner/mercury' }, deps);