@bongos/core 1.19.319 → 1.19.321

package/scripts/gds/gds-db-offsite.timer

@@ -1,6 +1,17 @@
+# TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
+# substituted at install time; a provisioned instance gets a correct per-instance
+# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# file. Substitute:
+#   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
+#   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
+#                          full clone: <instance-root>/scripts/gds
+#   __CONFIG_DIR__       the instance config dir name (offsite unit only)
+# One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]
 Description=Weekly timer for GDS DB offsite archive to Spaces (filed by #415)
-Documentation=file:///home/lars/amazonprimea/docs/recipes/gds-db-backup.md
+Documentation=file://__INSTANCE_ROOT__/docs/recipes/gds-db-backup.md
 
 [Timer]
 # Run weekly on Sunday at 05:00 UTC. That's one hour after the daily local

package/scripts/gds/instance-apex.js

@@ -0,0 +1,28 @@
+'use strict';
+// instance-apex.js — the instance's own registrable apex + the addresses derived
+// from it, read from its branding pack (task 1002757).
+//
+// WHY THIS EXISTS. Operator-plane defaults used to carry the founder's apex as a
+// literal (box DNS zones, the Cloudflare zone, the provisioner's git identity),
+// so another operator's fleet pointed at the founder's DNS and its commits were
+// attributed to the hub. These resolvers return NULL rather than guessing when the
+// pack names no public origin: every caller treats null as "not configured" and
+// refuses, which fails loudly instead of minting an unreachable host.
+function instanceApex() {
+  try {
+    const host = new URL(require('../../src/branding').branding().domains.publicOrigin).hostname;
+    return host && !/^localhost$/i.test(host) ? host : null;
+  } catch { return null; }
+}
+
+// The git identity a provisioner commits scaffold/pin changes as: explicit env →
+// bot@<instance apex> → a neutral, deliberately-undeliverable platform address
+// (never a live inbox by accident).
+function provisionerBotEmail(env = process.env) {
+  const explicit = String(env.PROVISION_BOT_EMAIL || '').trim();
+  if (explicit) return explicit;
+  const apex = instanceApex();
+  return apex ? `bot@${apex}` : 'bot@cloud-bongos.invalid';
+}
+
+module.exports = { instanceApex, provisionerBotEmail };

package/scripts/gds/newcomer-floor.templates.json

@@ -49,7 +49,7 @@
       "est_minutes": 55,
       "credits_reward": 15,
       "title": "Generate one new in-world art asset of your choice (a prop, plant, animal, or accessory) via the pixel-art pipeline",
-      "description": "## What you're doing\n\nAmazonprimea is a young ancient-Greek coastal world, and it always needs more to look at. Your first ship as an artist is to **generate ONE new in-world asset of your own choosing** and add it to the world. You pick the subject — that's the fun part. Good candidates, all in-world (Mediterranean coast just south of Athens, mythic 'discovered secret' tone):\n- **Props**: amphora, fishing net, basket, crate, urn, torch, market awning, oar, clay pot.\n- **Plants**: olive tree, cypress, reeds, grapevine, shrub, wild herbs.\n- **Animals**: goat, chicken, duck, donkey, fish, gull, lizard.\n- **Accessories**: a sandal, a sun hat, a length of rope, a string of beads.\n\nIt is identical for every newcomer and **always valuable**, because a growing world has effectively unbounded demand for new props, flora, fauna, and detail — every newcomer picks a different subject, so two runs never collide.\n\n## How to find your way in\n\n1. Read `art/README.md` and `docs/recipes/pixel-art-pipeline.md`, plus `modules/art-pipeline/template/style_guide.md`, `modules/art-pipeline/template/rubric.json`, and `modules/art-pipeline/template/palette.json` — that's the look you must hit: 16-bit pixel art, early-Pokémon (FireRed) touchstone, top-down, 32×32, locked 64-colour Mediterranean palette (olive greens, warm tans, turquoise sea, weathered marble — NOT spring green, NOT navy, NOT pine).\n2. **Pick ONE subject.** Keep it to a SINGLE 32×32 tile/sprite — not a whole spritesheet or family (that's a bigger task).\n3. **Check the budget first**: `python3 modules/art-pipeline/pipeline/cost_ledger.py status` (the pipeline hard-stops at $80; one asset is ~$0.05–0.45).\n4. **Generate via the pipeline — do not hand-draw or freelance.** Use the `/otb-tile-generate` skill: it appends your new entry to `modules/art-pipeline/template/vocabulary.json`, runs the generate → post-process-to-32×32 → score-against-rubric → retry orchestrator, saves the final PNG to `modules/art-pipeline/generated/tiles/<id>.png`, and logs cost. (This needs the art pipeline's `GOOGLE_AI_STUDIO_KEY`, which resolves from `~/.config/otb/env`; most builder setups have it. If yours doesn't, claim the engineer or ideator newcomer chore instead, or ask an Archon to enable it.)\n5. **Confirm it PASSED** the rubric (`modules/art-pipeline/iterations/run_summary.json` shows `status: \"pass\"`). If it only reached best-effort, regenerate with the fix_hint — never paper over a fail.\n6. **See it in-game**: `node scripts/gds/art-stage.js` rebuilds the atlas and surfaces it on your sandbox preview (`sandbox-<login>.amazonprimea.com`).\n7. Ship via `/builder-ship`; the ship notes name your asset and its rubric score.\n\n## Stay clear of (READ-ONLY)\n\nNever modify the locked palette (`modules/art-pipeline/template/palette.json`) or the rubric (`modules/art-pipeline/template/rubric.json`) — those are theme-defining and changing them needs an ADR (out of scope for a first ship). Touch only art assets/vocabulary under `art/` (and, only if your asset is a genuinely new base-tile TYPE, the `public/game/world/tilePalette.js` mapping). Do not touch any permission/pipeline-core/migration/infra file.",
+      "description": "## What you're doing\n\nThis instance's world always needs more to look at. Your first ship as an artist is to **generate ONE new in-world asset of your own choosing** and add it to the world. You pick the subject — that's the fun part. Good candidates, all in-world (Mediterranean coast just south of Athens, mythic 'discovered secret' tone):\n- **Props**: amphora, fishing net, basket, crate, urn, torch, market awning, oar, clay pot.\n- **Plants**: olive tree, cypress, reeds, grapevine, shrub, wild herbs.\n- **Animals**: goat, chicken, duck, donkey, fish, gull, lizard.\n- **Accessories**: a sandal, a sun hat, a length of rope, a string of beads.\n\nIt is identical for every newcomer and **always valuable**, because a growing world has effectively unbounded demand for new props, flora, fauna, and detail — every newcomer picks a different subject, so two runs never collide.\n\n## How to find your way in\n\n1. Read `art/README.md` and `docs/recipes/pixel-art-pipeline.md`, plus `modules/art-pipeline/template/style_guide.md`, `modules/art-pipeline/template/rubric.json`, and `modules/art-pipeline/template/palette.json` — that's the look you must hit: 16-bit pixel art, early-Pokémon (FireRed) touchstone, top-down, 32×32, locked 64-colour Mediterranean palette (olive greens, warm tans, turquoise sea, weathered marble — NOT spring green, NOT navy, NOT pine).\n2. **Pick ONE subject.** Keep it to a SINGLE 32×32 tile/sprite — not a whole spritesheet or family (that's a bigger task).\n3. **Check the budget first**: `python3 modules/art-pipeline/pipeline/cost_ledger.py status` (the pipeline hard-stops at $80; one asset is ~$0.05–0.45).\n4. **Generate via the pipeline — do not hand-draw or freelance.** Use the `/otb-tile-generate` skill: it appends your new entry to `modules/art-pipeline/template/vocabulary.json`, runs the generate → post-process-to-32×32 → score-against-rubric → retry orchestrator, saves the final PNG to `modules/art-pipeline/generated/tiles/<id>.png`, and logs cost. (This needs the art pipeline's `GOOGLE_AI_STUDIO_KEY`, which resolves from `~/.config/otb/env`; most builder setups have it. If yours doesn't, claim the engineer or ideator newcomer chore instead, or ask an Archon to enable it.)\n5. **Confirm it PASSED** the rubric (`modules/art-pipeline/iterations/run_summary.json` shows `status: \"pass\"`). If it only reached best-effort, regenerate with the fix_hint — never paper over a fail.\n6. **See it in-game**: `node scripts/gds/art-stage.js` rebuilds the atlas and surfaces it on your sandbox preview (`sandbox-<login>.<instance-apex>`).\n7. Ship via `/builder-ship`; the ship notes name your asset and its rubric score.\n\n## Stay clear of (READ-ONLY)\n\nNever modify the locked palette (`modules/art-pipeline/template/palette.json`) or the rubric (`modules/art-pipeline/template/rubric.json`) — those are theme-defining and changing them needs an ADR (out of scope for a first ship). Touch only art assets/vocabulary under `art/` (and, only if your asset is a genuinely new base-tile TYPE, the `public/game/world/tilePalette.js` mapping). Do not touch any permission/pipeline-core/migration/infra file.",
       "done_when": [
         "Exactly one NEW in-world asset (your chosen subject) was generated via the pixel-art pipeline (`/otb-tile-generate` / orchestrator.py); the final PNG exists at modules/art-pipeline/generated/tiles/<id>.png.",
         "It PASSED the rubric (modules/art-pipeline/iterations/run_summary.json status 'pass', or /otb-design-review numbers reported at/above the bar) and every pixel is on the locked palette (modules/art-pipeline/template/palette.json).",
@@ -70,7 +70,7 @@
       "est_minutes": 45,
       "credits_reward": 12,
       "title": "Idea-seed pass: file 5-8 fresh in-world ideas (names, lore, or builder-UX) into the idea inbox",
-      "description": "## What you'll do\n\nThe seed of almost everything built here is the **idea_inbox** — a queue anyone can drop ideas into, which trusted builders later triage into real tasks. Your first ship as an ideator is simple and concrete: **add a small batch of fresh ideas to that inbox.** You write no code, touch no game, change no system — you think, write a few short well-shaped ideas, and file them with one command each.\n\nIt is identical for every newcomer and **always valuable**: the inbox is never \"done\" — every triage pass consumes ideas (promote/discard/merge), so it is permanently hungry for fresh input, and a world the size of Amazonprimea always wants more names, more lore, more texture. Your batch is brand-new content, so it can never duplicate \"the work\" — the supply IS the work.\n\n## Pick ONE branch\n\n- **Branch A — PRODUCT flavour (default).** Ideas that grow the world players see: **names + one line of lore** for a character, structure, landmark, district, ship, or festival; or a world-background snippet (a custom, a superstition, a line a named NPC says). Tone: mythic, mysterious, a \"discovered secret\"; Mediterranean ancient-Greek coast (just south of Athens); NOT modern, NOT tongue-in-cheek-modern. Ground it in CLAUDE.md §3/§6/§7.\n- **Branch B — INTERNAL / builder-UX.** Small user-experience improvement ideas for the GDS / builders' hall (the surfaces builders use, not the game): a clearer label, a confusing onboarding message, a quality-of-life tweak to a status page or a slash-command's output. See `docs/TRACKS.md` for product vs internal.\n\n## How to find your way in\n\n1. (Branch A) Read CLAUDE.md §3/§6/§7 for tone. (Branch B) Skim `docs/TRACKS.md` and click around https://amazonprimea.com/builders for the rough edge you'll write up.\n2. See what's already filed so you don't repeat it: `node scripts/gds/api.js GET /api/gds/inbox`.\n3. File each idea with `node scripts/gds/capture.js \"<title>\" --body-file <path>` (filing an idea is the open-to-all path — a Xenos/Thetes session is allowed to do it; you just can't triage them). Put one line of detail + a `track: product` or `track: internal` line in each body file.",
+      "description": "## What you'll do\n\nThe seed of almost everything built here is the **idea_inbox** — a queue anyone can drop ideas into, which trusted builders later triage into real tasks. Your first ship as an ideator is simple and concrete: **add a small batch of fresh ideas to that inbox.** You write no code, touch no game, change no system — you think, write a few short well-shaped ideas, and file them with one command each.\n\nIt is identical for every newcomer and **always valuable**: the inbox is never \"done\" — every triage pass consumes ideas (promote/discard/merge), so it is permanently hungry for fresh input, and a growing world always wants more names, more lore, more texture. Your batch is brand-new content, so it can never duplicate \"the work\" — the supply IS the work.\n\n## Pick ONE branch\n\n- **Branch A — PRODUCT flavour (default).** Ideas that grow the world players see: **names + one line of lore** for a character, structure, landmark, district, ship, or festival; or a world-background snippet (a custom, a superstition, a line a named NPC says). Tone: mythic, mysterious, a \"discovered secret\"; Mediterranean ancient-Greek coast (just south of Athens); NOT modern, NOT tongue-in-cheek-modern. Ground it in CLAUDE.md §3/§6/§7.\n- **Branch B — INTERNAL / builder-UX.** Small user-experience improvement ideas for the GDS / builders' hall (the surfaces builders use, not the game): a clearer label, a confusing onboarding message, a quality-of-life tweak to a status page or a slash-command's output. See `docs/TRACKS.md` for product vs internal.\n\n## How to find your way in\n\n1. (Branch A) Read CLAUDE.md §3/§6/§7 for tone. (Branch B) Skim `docs/TRACKS.md` and click around your instance's /builders hall for the rough edge you'll write up.\n2. See what's already filed so you don't repeat it: `node scripts/gds/api.js GET /api/gds/inbox`.\n3. File each idea with `node scripts/gds/capture.js \"<title>\" --body-file <path>` (filing an idea is the open-to-all path — a Xenos/Thetes session is allowed to do it; you just can't triage them). Put one line of detail + a `track: product` or `track: internal` line in each body file.",
       "done_when": [
         "You filed 5–8 fresh ideas into the idea_inbox via `node scripts/gds/capture.js` (each prints a `Captured idea #N` confirmation), all in ONE branch (A product, or B internal/UX).",
         "Each idea has a clear title and a body with at least one sentence of detail — for Branch A, one line of in-world lore (who/what it is); for Branch B, what the rough edge is and what 'better' looks like.",

package/scripts/gds/provision.js

@@ -169,6 +169,10 @@ const CONFIG = {
   sshOpts: process.env.PROVISION_SSH_OPTS || '-o BatchMode=yes -o StrictHostKeyChecking=accept-new',
 };
 
+// task 1002757 — the provisioner's git identity resolves from the instance's own
+// apex (env → bot@<apex> → neutral), never the hub's address hardcoded.
+const { provisionerBotEmail } = require('./instance-apex');
+
 const MAX_INTENT_ATTEMPTS = numEnv('PROVISION_INTENT_MAX_ATTEMPTS', 3);
 
 // Manifest-placement verification budget (task 1002720 / QA-walk F23): a child
@@ -709,7 +713,7 @@ async function scaffoldStandaloneRepo(inst, deps) {
       writeFile(giPath, INSTANCE_GITIGNORE);
     }
     exec(`git -C ${root} config user.name "Cloud Bongos"`);
-    exec(`git -C ${root} config user.email "bot@cloudbongos.com"`);
+    exec(`git -C ${root} config user.email "${provisionerBotEmail()}"`);
     exec(`git -C ${root} add -A`);
     const commitMsg = mode === 'adopt'
       ? `chore: adopt Cloud Bongos onto ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0121)`
@@ -939,7 +943,7 @@ function buildCorePinRefreshCommit({ root, fromVersion, toVersion, repo, ownerTo
   return {
     config: [
       `git -C ${root} config user.name "Cloud Bongos"`,
-      `git -C ${root} config user.email "bot@cloudbongos.com"`,
+      `git -C ${root} config user.email "${provisionerBotEmail()}"`,
     ],
     add: `git -C ${root} add -A`,
     commit: `git -C ${root} commit -m "${msg}"`,
@@ -2477,7 +2481,7 @@ async function main() {
 if (require.main === module) main();
 
 module.exports = {
-  CONFIG, MAX_INTENT_ATTEMPTS,
+  CONFIG, MAX_INTENT_ATTEMPTS, provisionerBotEmail,
   // pure step generators (tested directly)
   dbName, dbCreateCmd, migrateCmd, seedFirstVersionCmd, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath,
   backupUnitName, backupServicePath, backupTimerPath, backupScriptPath, backupService, backupTimer,

package/scripts/gds/ship-deploy-target.js

@@ -0,0 +1,388 @@
+// scripts/gds/ship-deploy-target.js — deploy-mode + deploy-target resolution, the gh helpers and push-path selection.
+//
+// Carved out of scripts/gds/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 639-989 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadSessionSync } = require('./cli-lib');
+const { argvOk, argvOut } = require('./ship-git.js');
+const { REPO_ROOT } = require('./ship-state.js');
+
+// ---------- CI deploy mode (#679, ADR 0042) ----------
+//
+// Two ways the confirmed→shipped land can run, chosen by a SINGLE committed
+// switch (config/deploy.json `mode`, env OTB_DEPLOY_MODE overrides):
+//
+//   'laptop' (default) — the operator's machine merges to main locally and, IFF a
+//      deploy target is configured (config/deploy.json "sshTarget" or
+//      <PREFIX>_DEPLOY_SSH_TARGET, resolveDeployTarget()), SSHes `~/deploy.sh` on it.
+//      The core carries NO target of its own, so by default this is a merge-to-main
+//      with no SSH deploy — a change reaches a live instance via package-core +
+//      `bongos upgrade` (pin-bump), NOT an SSH deploy (ADR 0108). When a target IS
+//      set it requires that host's SSH key, so only the operator can land.
+//
+//   'ci' — NO builder box holds the prod key. ship pushes the branch, opens a
+//      PR, and enables GitHub auto-merge; once required checks pass, GitHub
+//      merges to main and .github/workflows/deploy-prod.yml deploys from
+//      Actions. ship then CONFIRMS the deploy landed (PR merged + the
+//      deploy-prod workflow run succeeded for the merge commit + public
+//      healthz 200) so the synchronous "deploy-confirmed" UX is preserved
+//      without the key. This is what lets a Windows/Chromebook builder with no
+//      main checkout and no droplet key land their own work.
+//
+// parseDeployMode is pure (env string + raw config file contents → mode) and
+// exported so the test can assert the precedence + the safe default without
+// touching fs/env. The default is 'laptop' precisely so this code is INERT
+// until the deliberate, atomic cutover (config flip + GitHub arming together).
+function parseDeployMode(envVal, configRaw) {
+  const fromEnv = String(envVal || '').trim().toLowerCase();
+  if (fromEnv === 'ci' || fromEnv === 'laptop') return fromEnv;
+  if (configRaw) {
+    try {
+      const m = String(JSON.parse(configRaw).mode || '').trim().toLowerCase();
+      if (m === 'ci' || m === 'laptop') return m;
+    } catch (_) {
+      /* malformed config → fall through to the safe default */
+    }
+  }
+  return 'laptop';
+}
+
+// effectiveDeployMode — credential- and protection-aware adjustment of the parsed
+// mode (pure; exported for the regression test). The 'laptop' land path pushes
+// main + SSHes the droplet FROM THIS MACHINE, so it requires a local GitHub push
+// credential. A machine without one — a dev box, or a fresh/stale local clone that
+// can't even `git pull` (token-less origin, ADR 0053) — physically cannot run it;
+// it must ship via the 'ci' server-mediated publish path instead
+// (pushVia()==='server', ADR 0055), which lets the GDS server push with its own
+// credential. So when the parsed mode is 'laptop' but the machine can't push
+// locally AND the mode was NOT pinned by an explicit OTB_DEPLOY_MODE, fall back to
+// 'ci' rather than strand every ship at merge. This is the scootermack 2026-06-22
+// case: a checkout left at the pre-cutover 'laptop' default that can't pull
+// forward to 'ci', so it kept attempting a push it had no credential for. An
+// explicit env override always wins (tests/staging may force 'laptop'). Mirrors
+// pushVia()'s existing credential-awareness — the asymmetry (pushVia smart,
+// resolveDeployMode blind) WAS the bug. (task 1449)
+//
+// Second input, same shape (task 1002629): a machine WITH push credentials but a
+// branch-PROTECTED main also cannot run the laptop land — GitHub refuses the
+// direct `git push origin main` no matter whose credential it is. When task
+// 1002619 armed protection (required `unit` check), every ship resolved 'laptop'
+// and pushed into the wall, stranding graded-PASS tasks at confirmed (tasks
+// 1002608/1002609; learning 1000177). mainProtected must be STRICTLY true to
+// trigger — null/undefined means the probe couldn't answer (no gh, offline, no
+// permission) and keeps today's behavior rather than rerouting on a guess.
+function effectiveDeployMode(mode, { canPushLocally, envForced, mainProtected } = {}) {
+  if (mode === 'laptop' && !envForced && !canPushLocally) return 'ci';
+  if (mode === 'laptop' && !envForced && mainProtected === true) return 'ci';
+  return mode;
+}
+
+// mainIsProtected — true/false when GitHub answers, null when it can't. The
+// `gh api` resolves {owner}/{repo} from the checkout's origin; any failure
+// (gh missing, offline, non-200) is null = unknown, which effectiveDeployMode
+// treats as "no change". Same spawn discipline as ghAvailableAndAuthed().
+function mainIsProtected() {
+  try {
+    const r = spawnSync('gh', ['api', 'repos/{owner}/{repo}/branches/main', '--jq', '.protected'], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    if (!r || r.error || r.status !== 0) return null;
+    const out = String(r.stdout || '').trim();
+    if (out === 'true') return true;
+    if (out === 'false') return false;
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function resolveDeployMode() {
+  const configRaw = readDeployConfigRaw();
+  const mode = parseDeployMode(process.env.OTB_DEPLOY_MODE, configRaw);
+  const envForced = ['ci', 'laptop'].includes(
+    String(process.env.OTB_DEPLOY_MODE || '').trim().toLowerCase()
+  );
+  // Probe `gh` ONLY when it can change the answer (resolved 'laptop', no env
+  // override) — the happy 'ci' path and an env-pinned mode spawn no extra gh,
+  // keeping the documented spawn discipline (the line-1019 note). The protection
+  // probe runs only when the credential check kept us on 'laptop' (a
+  // credential-less machine already falls back without it).
+  if (mode === 'laptop' && !envForced) {
+    const canPushLocally = ghAvailableAndAuthed();
+    const mainProtected = canPushLocally ? mainIsProtected() : null;
+    const effective = effectiveDeployMode(mode, { canPushLocally, envForced, mainProtected });
+    if (effective === 'ci' && mainProtected === true) {
+      console.log('  deploy mode: main is branch-protected (direct pushes refused) — landing via the ci PR path');
+    }
+    return effective;
+  }
+  return mode;
+}
+
+// readDeployConfigRaw — raw contents of config/deploy.json (or null if absent /
+// unreadable). One reader shared by resolveDeployMode (the mode switch) and
+// resolveDeployTarget (the SSH target) so they never diverge on where the file is.
+function readDeployConfigRaw() {
+  try {
+    return fs.readFileSync(path.join(REPO_ROOT, 'config', 'deploy.json'), 'utf8');
+  } catch (_) {
+    return null; // no config file → callers apply their safe default
+  }
+}
+
+// safeBranding — the instance brand pack, or null if it can't be read. Guarded the
+// same way ship.js guards the sound player (line ~91): a deploy must never crash
+// because the brand file is missing on a fresh / re-seeded checkout.
+function safeBranding() {
+  try {
+    return require('../../src/branding').branding();
+  } catch (_) {
+    return null;
+  }
+}
+
+// readSessionApiBase — the signed-in session's persisted api_base (the instance the
+// CLI is actually pointed at), or null when not signed in / unreadable. This is the
+// session's OWN value only — deliberately NOT readSessionToken().apiBase, which
+// already folds in the env override + branding default; resolveInstanceBase orders
+// that precedence itself so it stays pure over its injected inputs.
+function readSessionApiBase() {
+  try {
+    const s = loadSessionSync();
+    return (s && typeof s.api_base === 'string' && s.api_base.trim()) ? s.api_base.trim() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// resolveInstanceBase — the ORIGIN of the instance this ship is landing on, used by
+// the ci-land deployed-version probe (/version), the /healthz re-probe, the ci
+// PR-body deploy note, and the manual-confirm curl guidance. Precedence mirrors the
+// CLI's own base resolution: <PREFIX>_API_BASE env → the signed-in session's
+// api_base → branding publicOrigin → null (unknowable). There is NO hardcoded
+// founder host — 5 sites here baked in `https://amazonprimea.com`, so a ci-land /
+// manual-confirm on a migrated instance pointed the builder at the WRONG box; the
+// ci-land/guidance sibling of resolveDeployTarget()'s laptop-mode fix (task 1002232
+// ⊃ task 1002202). Pure over its injected inputs (env / sessionApiBase / branding)
+// so the precedence is unit-tested without fs/env/network; the defaults read the
+// real session file + brand pack.
+function resolveInstanceBase({
+  env = process.env,
+  sessionApiBase = readSessionApiBase(),
+  branding = safeBranding(),
+} = {}) {
+  const ic = require('../../src/instance-config');
+  const trim = (s) => (typeof s === 'string' && s.trim() ? s.trim().replace(/\/+$/, '') : null);
+  const envBase = trim(ic.resolveEnv('API_BASE', { env }));
+  if (envBase) return envBase;
+  const sess = trim(sessionApiBase);
+  if (sess) return sess;
+  const origin = branding && branding.domains && branding.domains.publicOrigin;
+  return trim(origin);
+}
+
+// deployedVersionUrl — the instance's /version endpoint, or null when no instance
+// origin is resolvable (then fetchDeployedVersion is a no-op). Derived from
+// resolveInstanceBase — no hardcoded host (task 1002232).
+function deployedVersionUrl() {
+  const base = resolveInstanceBase();
+  return base ? `${base}/version` : null;
+}
+
+// resolveDeployTarget — WHERE a laptop-mode ship SSHes `~/deploy.sh`, and which
+// /healthz it re-probes when deploy.sh's own health check races the restart window.
+// Pure (env + raw config + branding → target) and exported so the precedence and the
+// safe "no target" default are unit-tested without touching fs/env/network.
+//
+// There is deliberately NO hardcoded default. The founder instance's old game-box
+// SSH target was baked in here, so a laptop-mode ship from a migrated
+// checkout SSHed the WRONG server (task 1002202). The core carries no deploy target
+// of its own — under the standalone model a core change reaches a live instance via
+// package-core + `bongos upgrade` (pin-bump), not an SSH deploy (ADR 0108). An
+// instance whose OWN checkout is its live server opts back into laptop-SSH deploy by
+// setting the target:
+//   config/deploy.json  → { "sshTarget": "user@host", "healthzUrl": "https://…/healthz" }
+//   env                 → <PREFIX>_DEPLOY_SSH_TARGET, <PREFIX>_DEPLOY_HEALTHZ_URL
+// healthzUrl, when unset, falls back to the instance's own publicOrigin + /healthz
+// (never a hardcoded host); null when even that is unknown (re-probe then skipped).
+function resolveDeployTarget({ env = process.env, configRaw = null, branding = null } = {}) {
+  const ic = require('../../src/instance-config');
+  let cfg = {};
+  if (configRaw) {
+    try { cfg = JSON.parse(configRaw) || {}; } catch (_) { cfg = {}; }
+  }
+  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+  const sshTarget = ic.resolveEnv('DEPLOY_SSH_TARGET', { env }) || str(cfg.sshTarget) || null;
+
+  let healthzUrl = ic.resolveEnv('DEPLOY_HEALTHZ_URL', { env }) || str(cfg.healthzUrl) || null;
+  const publicOrigin = branding && branding.domains && branding.domains.publicOrigin;
+  if (!healthzUrl && str(publicOrigin)) {
+    try { healthzUrl = new URL('/healthz', publicOrigin).toString(); }
+    catch (_) { /* malformed origin → leave healthzUrl null */ }
+  }
+  return { sshTarget, healthzUrl };
+}
+
+// gh runners — mirror gitArgvOk/gitOk but for the GitHub CLI. No shell, ever:
+// branch names + DB-sourced value_summary reach `gh` as literal argv elements
+// (same injection discipline as #681). ghArgvOk = boolean side-effect; ghJson =
+// parse `gh ... --json` stdout to an object/array (null on any failure).
+function ghArgvOk(args, opts = {}) {
+  return argvOk('gh', args, opts);
+}
+
+function ghJson(args, opts = {}) {
+  const out = argvOut('gh', args, opts);
+  if (out == null) return null;
+  try { return JSON.parse(out); } catch (_) { return null; }
+}
+
+// Pure argv builders for the PR land path — exported + tested so the untrusted
+// value_summary is proven to ride as ONE literal argv element (never a shell
+// string), exactly like buildMergeArgv.
+function buildPrCreateArgv(branch, title, body) {
+  return ['pr', 'create', '--head', branch, '--base', 'main', '--title', title, '--body', body];
+}
+
+// --merge keeps the project's --no-ff merge-commit convention (architecture.md
+// branch-cleanup note); --auto arms GitHub to merge the instant required checks
+// pass + branch protection is satisfied; --delete-branch mirrors the laptop
+// path's origin-branch cleanup.
+function buildPrMergeArgv(branch) {
+  return ['pr', 'merge', '--auto', '--merge', '--delete-branch', branch];
+}
+
+// Pure: did the prod-deploy workflow finish successfully for the merge commit?
+// `runs` is the parsed `gh run list --json headSha,status,conclusion` array.
+function deployRunSucceeded(runs, mergeSha) {
+  if (!mergeSha) return false;
+  return (runs || []).some(
+    (r) => r && r.headSha === mergeSha && r.status === 'completed' && r.conclusion === 'success'
+  );
+}
+
+// Pure: does the prod /version endpoint (#858) report it's running the commit we
+// just merged? 'match' = commit-pinned confirmation; 'mismatch' = prod is on a
+// different commit (e.g. a later deploy already superseded ours — still fine, our
+// run succeeded); 'unknown' = /version absent or unparseable (older prod / blip)
+// → caller falls back to the deploy-run + healthz signal. Compares on the shorter
+// length so a short vs full sha still matches. Exported + tested.
+function deployedCommitStatus(versionBody, mergeSha) {
+  if (!versionBody || !mergeSha) return 'unknown';
+  const c = String(versionBody.commit || '');
+  if (!/^[0-9a-f]{7,40}$/i.test(c)) return 'unknown';
+  const n = Math.min(c.length, String(mergeSha).length);
+  return c.slice(0, n).toLowerCase() === String(mergeSha).slice(0, n).toLowerCase()
+    ? 'match'
+    : 'mismatch';
+}
+
+// Fetch + parse the prod /version JSON (#858). null on any failure — never throws.
+// Default target is the resolved instance origin (no hardcoded host — task 1002232);
+// null when none is resolvable, in which case the probe is skipped.
+function fetchDeployedVersion(url = deployedVersionUrl()) {
+  if (!url) return null; // no resolvable instance origin → nothing to probe
+  // stdio override DISCARDS stderr (a curl progress/error line must not pollute
+  // the JSON parse) — the documented per-caller difference from ghJson.
+  const out = argvOut('curl', ['-fsS', '--max-time', '10', url], { stdio: ['ignore', 'pipe', 'ignore'] });
+  if (out == null) return null;
+  try { return JSON.parse(out); } catch (_) { return null; }
+}
+
+// ciLand — the 'ci' deploy-mode analogue of the laptop merge+SSH block. Pushes
+// the branch, ensures a PR exists, enables auto-merge, then confirms the deploy
+// actually landed. Returns true ONLY when prod is confirmed live on the merge
+// commit — so the caller flips the task to shipped exactly as the laptop path
+// does. Any earlier exit leaves the task at confirmed with a clear next step.
+// pushVia — which publish path ship uses in 'ci' mode (ADR 0055 / task 1025):
+//   'local'  — this machine pushes the branch + opens the PR with git + gh
+//              (laptop: gh present + authenticated). Today's behaviour.
+//   'server' — this machine has NO GitHub push credential (a dev box: no gh, a
+//              credential-less origin). ship uploads a thin branch bundle to the
+//              GDS, which pushes + opens the PR + auto-merges with the SERVER's
+//              credential. The box holds nothing (#919 model preserved).
+// Override with OTB_PUSH_VIA_SERVER=1 (force server) / =0 (force local) for tests.
+function ghAvailableAndAuthed() {
+  try {
+    const a = spawnSync('gh', ['auth', 'status'], {
+      stdio: 'ignore',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    return !!a && !a.error && a.status === 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+function pushVia() {
+  const o = String(process.env.OTB_PUSH_VIA_SERVER || '').trim();
+  if (o === '1') return 'server';
+  if (o === '0') return 'local';
+  // No explicit override: a machine that can run an authenticated gh (laptop)
+  // takes the local path; everything else (a dev box) goes server-mediated.
+  return ghAvailableAndAuthed() ? 'local' : 'server';
+}
+
+// broadcastHandledByServer — task 1045: on the server-mediated publish path the
+// SERVER posts the Discord ship-broadcast after it confirms the deploy (it holds
+// the webhook secrets; the box does NOT — ADR 0053). So ship.js must NOT also post
+// locally there, or the box would either double-post (impossible — no secret) or,
+// as before, fail silently. True only when the publish actually goes server-side:
+// ci deploy mode AND this machine has no GitHub push credential (pushVia 'server').
+// The laptop path (pushVia 'local') keeps posting locally, exactly as today. Pure
+// w.r.t. its inputs (env + committed deploy.json) + exported so the gate is tested.
+function broadcastHandledByServer() {
+  return resolveDeployMode() === 'ci' && pushVia() === 'server';
+}
+
+// shouldBailOnFetchFailure — autoMerge's decision when `git fetch origin main`
+// fails. A credential-less dev box (private origin, scrubbed clone token —
+// ADR 0053) CANNOT fetch origin, and that is FINE for the server-mediated
+// publish path (ADR 0055): ciLandServer bundles against the box's LOCAL
+// origin/main and the SERVER tops up main with its own credential. So a fetch
+// failure is fatal ONLY when we are NOT taking that path — otherwise the box can
+// never reach ciLand and strands every ship at confirmed (the bug task 1027
+// surfaced: ADR 0055 shipped the server path but left this fetch guard in front
+// of it). Pure + exported for the regression test (no git, no network).
+// NOTE: callers must still guard the pushVia() gh-probe behind `!fetchedMain` so
+// the happy path (fetch ok) spawns no extra gh and laptop behavior is unchanged.
+function shouldBailOnFetchFailure(fetchedMain, deployMode, via) {
+  if (fetchedMain) return false;
+  const serverPublish = deployMode === 'ci' && via === 'server';
+  return !serverPublish;
+}
+
+module.exports = {
+  broadcastHandledByServer,
+  buildPrCreateArgv,
+  buildPrMergeArgv,
+  deployRunSucceeded,
+  deployedCommitStatus,
+  effectiveDeployMode,
+  fetchDeployedVersion,
+  ghArgvOk,
+  ghJson,
+  mainIsProtected,
+  parseDeployMode,
+  pushVia,
+  readDeployConfigRaw,
+  resolveDeployMode,
+  resolveDeployTarget,
+  resolveInstanceBase,
+  safeBranding,
+  shouldBailOnFetchFailure,
+};