@bongos/core 1.18.0 → 1.18.18

package/scripts/gds/ship.js

@@ -31,6 +31,13 @@
 //                                                       # empty-diff guard; confirms directly (no diff to
 //                                                       # grade). REFUSED if the working tree is dirty —
 //                                                       # that means you forgot to commit (task 1363/1365).
+//   node scripts/gds/ship.js <task-id> --base <ref>     # grade a task whose commits ALREADY landed on main
+//                                                       # (e.g. a release task: package-core needs the merge
+//                                                       # first). Pins <ref> as the pre-task baseline so the
+//                                                       # grader reads the REAL diff <ref>...HEAD and confirms
+//                                                       # via the RANK-OPEN graded path — the sub-Archon-safe
+//                                                       # alternative to --allow-empty (task 1002422 / blocker
+//                                                       # 1000082). Implies db-only (nothing left to merge).
 //   node scripts/gds/ship.js <task-id> --regrade       # re-grade a task STUCK at `completed` (a ship
 //                                                       # whose grade failed): re-runs ONLY the grade step
 //                                                       # against the committed diff, no claim required.
@@ -54,7 +61,20 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
-const { cliClient, requireSession, loadSession, printOnboardingNudge, arg } = require('./cli-lib');
+const { cliClient, requireSession, loadSession, loadSessionSync, printOnboardingNudge, arg, rewardPolicy } = require('./cli-lib');
+
+// The instance's reward policy, as reported by the server on GET /me (ADR 0146 /
+// task 1002469). Cached module-level because the credits print + the completion
+// card are reached through several call chains and the mode is a single
+// instance-wide fact — threading it through each would be noise. Stays null
+// until a /me lands; rewardPolicy(null) then degrades to the paying default, so
+// a missed fetch under-explains rather than wrongly claiming "not paid".
+let serverReward = null;
+function noteServerReward(meRes) {
+  const r = meRes && meRes.ok && meRes.data && meRes.data.reward;
+  if (r && typeof r.mode === 'string') serverReward = r;
+  return meRes;
+}
 // ship-preflight + merge-lock carved to modules/lifecycle/ (BV1.R86). A script may
 // require a module directly (it's outside the kernel boundary — the grading/economy
 // CLI precedent).
@@ -95,7 +115,11 @@ const { playSound } = (() => {
     return { playSound: () => {} };
   }
 })();
-const DROPLET = 'lars@104.236.254.243';
+// The laptop-mode SSH deploy target is resolved at land time from config/deploy.json
+// ("sshTarget") or <PREFIX>_DEPLOY_SSH_TARGET — see resolveDeployTarget(). There is NO
+// hardcoded default: the core carries no deploy target of its own. The founder
+// instance's old game-box SSH target used to be baked in here, which post-migration
+// meant a laptop-mode ship deployed to the WRONG server (task 1002202).
 const BEHIND_MAIN_LIMIT = 5;
 
 // arg() — the =-aware flag-value parser now lives in cli-lib (the canonical
@@ -199,8 +223,14 @@ function claudeConfigBase() {
 }
 
 function encodeProjectPath(absProjectPath) {
-  // Claude Code's encoding: replace every '/' and '.' with '-'.
-  return absProjectPath.replace(/[/.]/g, '-');
+  // Claude Code's encoding: every NON-ALPHANUMERIC char becomes '-'. The old
+  // `[/.]` class silently no-op'd on Windows (separator '\', drive ':', spaces),
+  // so the transcript was never found, no session_record was written, and the
+  // cost-plus reward — the only stream a cost-plus-only instance pays (ADR 0146)
+  // — could never book: every Windows ship paid 0 (task 1002471). Same rule as
+  // scripts/gds/onboarding-config.js, which already had it right. POSIX output is
+  // unchanged for paths whose only specials are '/' and '.'.
+  return String(absProjectPath).replace(/[^a-zA-Z0-9]/g, '-');
 }
 
 // resolveTranscriptPath — find this session's transcript .jsonl. Claude Code
@@ -323,7 +353,11 @@ const {
 // snippetOf — short, single-line, scrubbed excerpt for footgun context.
 function snippetOf(text, extraSecrets, max = 160) {
   if (typeof text !== 'string' || text.length === 0) return undefined;
-  const flat = text.replace(/\s+/g, ' ').trim();
+  // Drop NULs first: Postgres rejects a literal NUL in jsonb, so ONE of them anywhere in
+  // ONE snippet made the whole digest unstorable — POST /sessions answered 500 and
+  // the session never paid. UTF-16LE tool output (`wsl --list` is the observed
+  // case) is full of them, and \s below does NOT match NUL, so it must go here.
+  const flat = text.replace(/\0/g, '').replace(/\s+/g, ' ').trim();
   if (!flat) return undefined;
   const cut = flat.length > max ? flat.slice(0, max) : flat;
   const scrubbed = scrubSecrets(cut, extraSecrets);
@@ -762,9 +796,13 @@ function buildMergeArgv(branch, valueSummary) {
 // 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
-//      SSHes `~/deploy.sh` on the droplet. Today's behavior, byte-for-byte.
-//      Requires the droplet SSH key, so only the operator can land.
+//   '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
@@ -815,12 +853,7 @@ function effectiveDeployMode(mode, { canPushLocally, envForced } = {}) {
 }
 
 function resolveDeployMode() {
-  let configRaw = null;
-  try {
-    configRaw = fs.readFileSync(path.join(REPO_ROOT, 'config', 'deploy.json'), 'utf8');
-  } catch (_) {
-    /* no config file → safe default */
-  }
+  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()
@@ -834,6 +867,111 @@ function resolveDeployMode() {
   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 =
@@ -889,7 +1027,10 @@ function deployedCommitStatus(versionBody, mergeSha) {
 }
 
 // Fetch + parse the prod /version JSON (#858). null on any failure — never throws.
-function fetchDeployedVersion(url = 'https://amazonprimea.com/version') {
+// 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'] });
@@ -1032,11 +1173,15 @@ async function ciLandServer(taskId, branch, valueSummary) {
 // Pure + exported for unit tests (no git/network). Accepts the publish-status
 // response shape verbatim — getPublishStatus returns snake_case (pr_state,
 // deploy_status); camelCase aliases are tolerated for test convenience.
+// task 1002472: 'unconfigured' means the repo has no deploy-prod.yml to wait for
+// (ADR 0108 pin-bump publishing), so the merge IS the land. Mirrors
+// github-push.landConfirmed — kept in step by tests/ship_ci_deploy.mjs, since this
+// CLI cannot import the server module.
 function classifyLandOutcome(s) {
   const merged = !!(s && s.merged);
   const deployStatus = s && (s.deploy_status ?? s.deployStatus);
   const prState = s && (s.pr_state ?? s.prState);
-  if (merged && deployStatus === 'success') return 'shipped';
+  if (merged && (deployStatus === 'success' || deployStatus === 'unconfigured')) return 'shipped';
   if (prState === 'closed' && !merged) return 'failed';
   return 'pending';
 }
@@ -1221,11 +1366,12 @@ async function ciLandLocal(taskId, branch, valueSummary) {
   // GitHub's PR/issue number space (dead links for GDS task ids — task 916),
   // so the task ref is written as "task NNN" and the summary is de-#-ed.
   const title = `task ${taskId}: ${sanitizeGitHubRefs(valueSummary) || branch}`.slice(0, 240);
+  const deployTargetNote = resolveInstanceBase() || 'the configured instance';
   const body =
     `Auto-opened by ship.js (deploy mode: ci) for task ${taskId}.\n\n` +
     `${sanitizeGitHubRefs(valueSummary) || '(no value summary)'}\n\n` +
     `Merging this PR triggers .github/workflows/deploy-prod.yml to deploy to ` +
-    `https://amazonprimea.com. Auto-merge is enabled — GitHub lands it once the ` +
+    `${deployTargetNote}. Auto-merge is enabled — GitHub lands it once the ` +
     `required checks pass.`;
   if (!existing || existing.state === 'CLOSED' || existing.state === 'MERGED') {
     console.log('  ci-land: opening PR -> main...');
@@ -1307,12 +1453,14 @@ function pollCiDeploy(taskId, branch, headSha) {
       // real deploy into a false negative on a transient miss or a concurrent
       // later deploy).
       const status = deployedCommitStatus(fetchDeployedVersion(), mergeSha);
+      const instanceBase = resolveInstanceBase();
+      const healthzUrl = instanceBase ? `${instanceBase}/healthz` : null;
       if (status === 'match') {
         console.log('  ci-land: /version confirms prod is live on the merge commit (commit-pinned).');
       } else if (status === 'mismatch') {
         console.log('  ci-land: deploy run succeeded; /version shows a different commit (a later deploy has since superseded it — fine, our change is in main).');
-      } else if (shellOk('curl -fsS --max-time 10 https://amazonprimea.com/healthz -o /dev/null')) {
-        console.log('  ci-land: /version unavailable; amazonprimea.com/healthz 200 — treating the successful deploy run as authoritative.');
+      } else if (healthzUrl && shellOk(`curl -fsS --max-time 10 ${healthzUrl} -o /dev/null`)) {
+        console.log(`  ci-land: /version unavailable; ${healthzUrl} 200 — treating the successful deploy run as authoritative.`);
       } else {
         console.log('  ci-land: deploy run succeeded but /version + healthz probes both missed (likely transient). Treating the successful deploy run as authoritative.');
       }
@@ -1337,6 +1485,16 @@ function pollCiDeploy(taskId, branch, headSha) {
 // Also refuses when the branch is far behind origin/main — merging a stale
 // branch is a known regression vector.
 
+// parseDeletedUpstreamPaths — pure: turn `git log --diff-filter=D --name-only
+// --pretty=format:` output (one deleted path per line, blank lines between
+// commits) into a deduped, order-preserving list. Exported so preflight's
+// upstream-deletion warning (step (d)) is unit-tested without a live git repo.
+// Null/empty input (no matches, or the git call failed closed) → [].
+function parseDeletedUpstreamPaths(rawLogOutput) {
+  if (!rawLogOutput) return [];
+  return [...new Set(rawLogOutput.split('\n').map((s) => s.trim()).filter(Boolean))];
+}
+
 function preflight(claim, opts = {}) {
   // (a) Working-tree check — refuse if any TRACKED file carries an uncommitted
   // modification or staged change. This fires post-commit, so a clean tree
@@ -1409,6 +1567,39 @@ function preflight(claim, opts = {}) {
     }
   }
 
+  // (d) Upstream-deletion warning (WARN-ONLY — never blocks, never changes the
+  // exit code). main can delete or relocate a surface between when a task was
+  // claimed and when it ships (a cutover, a carve, a rename — the R89 hall-ui
+  // cutover class); the branch's own diff still touches the OLD path, and an
+  // oblivious ship can silently revert the upstream deletion or leave this
+  // branch's work orphaned. Scoped to the paths THIS branch's diff actually
+  // touches — the same baseline/diff computeGraderBaseline/computeChangedFiles
+  // compute for the grader — so an unrelated upstream deletion elsewhere in the
+  // repo never fires it. Silent no-op if origin/main isn't resolvable (offline /
+  // never fetched) or this branch's diff is empty — the check itself must never
+  // be why a ship breaks. parseDeletedUpstreamPaths is the pure parsing seam,
+  // exported + unit-tested (tests/ship_upstream_deletion.mjs) without a live git
+  // repo; this block is just the git I/O + presentation around it.
+  const upstreamDelBaseline = computeGraderBaseline(claim);
+  const upstreamDelTouched = upstreamDelBaseline ? computeChangedFiles(upstreamDelBaseline) : [];
+  if (upstreamDelTouched.length > 0) {
+    const deletedUpstreamStr = argvOut('git', [
+      'log', 'HEAD..origin/main', '--diff-filter=D', '--name-only', '--pretty=format:',
+      '--', ...upstreamDelTouched,
+    ]);
+    const deletedUpstream = parseDeletedUpstreamPaths(deletedUpstreamStr);
+    if (deletedUpstream.length > 0) {
+      console.error('');
+      console.error(`⚠ Upstream deletion warning: main has removed ${deletedUpstream.length} path(s) this branch still touches, since this task was claimed:`);
+      for (const f of deletedUpstream) console.error(`    - ${f}`);
+      console.error('  This looks like the R89 hall-ui cutover class: a surface removed or relocated upstream while the claim was in flight.');
+      console.error('  Verify these paths still exist on main (or that the removal/rename is intentional) before shipping —');
+      console.error("  shipping anyway may silently revert the upstream deletion or leave this branch's work orphaned.");
+      console.error('  Warning only — not blocking; the ship proceeds.');
+      console.error('');
+    }
+  }
+
   console.log(`  preflight: working tree clean, branch ${behind} commits behind main, ship tooling current — OK`);
   return { ok: true };
 }
@@ -1585,13 +1776,80 @@ function autoLinkifyChangedDocs(ac) {
 // full unified diff against the baseline, and (for the audit-trail signals)
 // the shortstat summary.
 //
+// task 1002422 (blocker 1000082): a builder-settable pre-task baseline. When a
+// task's artifact reached main BEFORE the ship (a release task: package-core
+// archives committed HEAD, so the version bump must merge first), merge-base(
+// origin/main, HEAD) == HEAD → an EMPTY committed diff → the --allow-empty /
+// skip-grade / Archon-only /confirm dead-end that NO sub-Archon builder can
+// finish. --base <ref> pins the pre-task commit so the grader reads the REAL diff
+// <base>...HEAD and the ship confirms via the rank-open graded path instead. Set
+// once in main() after resolveBaseRef() validates it; null on a normal ship.
+let baseOverrideSha = null;
+
+// resolveBaseRef — validate + resolve a --base <ref> to a commit sha. Injection-
+// safe: the ref reaches git as a literal argv element (execFile, no shell), never
+// a string interpolation. Pure over injected git runners so the unit test drives
+// it with fakes (no real repo). Returns { ok:true, sha } or { ok:false, reason }.
+function resolveBaseRef(rawBase, { revParse, isAncestor } = {}) {
+  const ref = String(rawBase == null ? '' : rawBase).trim();
+  if (!ref) return { ok: false, reason: 'empty ref' };
+  // Conservative allowlist (defence-in-depth even though transport is argv): no
+  // whitespace, no leading dash (git would read it as a flag), no shell metachar.
+  if (!/^[A-Za-z0-9][A-Za-z0-9._/~^-]*$/.test(ref)) {
+    return { ok: false, reason: `invalid ref syntax "${ref}"` };
+  }
+  const rp = revParse || ((r) => argvOut('git', ['rev-parse', '--verify', '--quiet', `${r}^{commit}`]));
+  const sha = rp(ref);
+  if (!sha) return { ok: false, reason: `"${ref}" is not a commit this repo knows` };
+  const anc = isAncestor || ((s) => gitArgvOk(['merge-base', '--is-ancestor', s, 'HEAD']));
+  if (!anc(sha)) {
+    return { ok: false, reason: `"${ref}" (${sha.slice(0, 9)}) is not an ancestor of HEAD — --base must be a commit your work built on top of` };
+  }
+  return { ok: true, sha };
+}
+
+// baseRefShipGuard — the SECURITY invariant behind --base. --base decouples the
+// GRADED diff (<base>...HEAD) from what the merge leg lands (the whole branch:
+// autoMerge runs `git merge <branch>`, bringing every commit ahead of main, not
+// just <base>...HEAD). So if HEAD has commits AHEAD of origin/main, honoring
+// --base would let the grader review only a SUBSET while the full branch merges —
+// an unreviewed-code path onto main. --base is therefore ONLY valid for work
+// ALREADY fully on main (its documented premise: "nothing left to merge"). Pure
+// over the ahead-count string (git rev-list --count origin/main..HEAD) so it is
+// unit-tested without a repo. '0' → allowed; anything else (or null) → refuse.
+function baseRefShipGuard(aheadCount) {
+  if (aheadCount === '0') return { ok: true };
+  const n = aheadCount == null ? 'an unknown number of' : aheadCount;
+  return { ok: false, reason: `HEAD is ${n} commit(s) ahead of origin/main — --base is only for work already merged to main` };
+}
+
+// applyBaseOverride — the SINGLE source of truth for --base validation, shared by
+// shipMain + regradeMain so the security guard can never diverge between entry
+// points. Resolves the ref, enforces the 0-ahead invariant, and sets the module-
+// level baseOverrideSha on success. Returns { ok:true, sha } | { ok:false, reason }
+// (the caller prints + exits). runGit is injectable for tests.
+function applyBaseOverride(baseRefRaw, { runGit = gitOk } = {}) {
+  const r = resolveBaseRef(baseRefRaw);
+  if (!r.ok) return { ok: false, reason: `--base ${baseRefRaw} is unusable (${r.reason})` };
+  // Freshen origin/main (best-effort; a stale ref only OVER-counts → errs to refuse).
+  runGit('git fetch origin main --quiet');
+  const guard = baseRefShipGuard(runGit('git rev-list --count origin/main..HEAD'));
+  if (!guard.ok) return { ok: false, reason: guard.reason };
+  baseOverrideSha = r.sha;
+  return { ok: true, sha: r.sha };
+}
+
 // #536: the grader's baseline is computed INDEPENDENTLY of touches[] — always
 // from merge-base, never gated on the declared scope. (Historically the
 // touches-gated drift scanner returned a null baseline for empty touches[],
 // which once blinded the grader to a fully-committed diff and hard-FAILed
 // empty-touches newcomer ships; the scanner is gone as of task 879, but the
 // grader keeping its own merge-base baseline remains the correct invariant.)
-function computeGraderBaseline(claim) {
+// baseSha (task 1002422): a validated --base override wins over merge-base, so a
+// task whose commits already landed on main still grades its real diff instead of
+// seeing an empty one.
+function computeGraderBaseline(claim, baseSha = baseOverrideSha) {
+  if (baseSha) return baseSha;
   return (
     gitOk('git merge-base origin/main HEAD') ||
     gitOk('git merge-base main HEAD') ||
@@ -1679,7 +1937,7 @@ async function runSubagentGrader({ task, valueSummary, baseline, changedFiles: p
   // fail-closed layers).
   let builderRank;
   try {
-    const meRes = await (await cliClient()).me.getMe();
+    const meRes = noteServerReward(await (await cliClient()).me.getMe());
     if (meRes.ok) builderRank = meRes.data?.builder?.rank;
   } catch (_) { /* unknown rank → pre-pass fails open; audit + hook still gate */ }
   const runOpts = {
@@ -1860,6 +2118,23 @@ function regenerateApiDocs() {
 // (not fail-if-forgotten): before this, ship regenerated the spec but not the client,
 // so a route change left the client stale until the api_client test caught it in CI.
 // Non-fatal + safe on every ship path; the api_client freshness test backstops main.
+
+// Where the devbox Electron app vendors the CJS client (ADR 0045). It lives inside the
+// dev-box MODULE (ADR 0145) — an instance that ships without that module has no copy.
+const VENDORED_CLIENT_REL = 'modules/dev-box/app/src/vendor/bongos-client.cjs';
+
+// The git pathspec for the regenerated client. Pure + exported so the rule is unit-tested
+// with no git/fs (task 1002417). `git status` tolerates an unmatched pathspec (exit 0) but
+// `git add` aborts the ENTIRE staging step (exit 128), which leaves the regenerated client
+// unstaged and the worktree dirty — and a dirty worktree makes the ship's auto-merge bail,
+// stranding the task at `confirmed` with no PR. So the vendored copy is named ONLY when it
+// is actually on disk.
+function apiClientPathspec({ worktreeRoot, existsSync = fs.existsSync } = {}) {
+  const paths = ['clients/bongos-client'];
+  if (existsSync(path.join(worktreeRoot, VENDORED_CLIENT_REL))) paths.push(VENDORED_CLIENT_REL);
+  return paths;
+}
+
 function regenerateApiClient() {
   console.log('  regenerating typed API client (clients/bongos-client) from the OpenAPI spec...');
   if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-api-client.js'))}`)) {
@@ -1868,23 +2143,28 @@ function regenerateApiClient() {
   }
   // The devbox Electron app can't require() clients/ at runtime, so it vendors the CJS
   // build (ADR 0045); keep the copy byte-identical (the api_client test asserts it).
-  // Present only in the core repo — a consumer instance has no devbox-app/, so skip.
+  // Present only where the dev-box module ships — an instance without it has no vendored
+  // copy, so both the vendor step and the git pathspec below drop out (task 1002417: the
+  // app moved from top-level devbox-app/ to modules/dev-box/app/ per ADR 0145, and these
+  // paths were not updated, so the guard below silently never fired).
   // Resolve it WORKTREE-LOCALLY (like the generator above, __dirname=scripts/gds), NOT
   // via REPO_ROOT: on a ship from a linked worktree REPO_ROOT is the MAIN checkout, so a
   // REPO_ROOT path would vendor the main tree while gen-api-client just wrote THIS tree,
   // leaving this worktree's vendored copy stale → the api_client byte-identity test reds
   // the PR (task 2060 fix). __dirname keeps the generator, the vendored file, and the
   // git add all on the same tree.
-  const vendorScript = path.join(__dirname, '..', '..', 'devbox-app', 'scripts', 'vendor-client.js');
+  const worktreeRoot = path.join(__dirname, '..', '..');
+  const vendorScript = path.join(worktreeRoot, 'modules', 'dev-box', 'app', 'scripts', 'vendor-client.js');
   if (fs.existsSync(vendorScript)) {
     shellOk(`"${process.execPath}" ${JSON.stringify(vendorScript)}`);
   }
-  const dirty = gitOk('git status --porcelain clients/bongos-client devbox-app/src/vendor/bongos-client.cjs');
+  const clientPathspec = apiClientPathspec({ worktreeRoot }).join(' ');
+  const dirty = gitOk(`git status --porcelain ${clientPathspec}`);
   if (!dirty) {
     console.log('  API client already current — nothing to commit');
     return 'current';
   }
-  shellOk('git add clients/bongos-client devbox-app/src/vendor/bongos-client.cjs');
+  shellOk(`git add ${clientPathspec}`);
   if (shellOk('git commit -m "chore(api-client): auto-regenerate typed client + devbox vendor (task 2051)"')) {
     console.log('  committed auto-regenerated API client');
     return 'committed';
@@ -2129,26 +2409,48 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
       return false;
     }
 
-    console.log('  triggering deploy on droplet...');
-    // Quote ~/deploy.sh so the LOCAL shell doesn't tilde-expand it to
-    // /Users/<mac-user>/deploy.sh before ssh transmits the command. With
-    // the quotes, ssh sends the literal `~/deploy.sh` and the REMOTE shell
-    // expands it to /home/lars/deploy.sh. (Matches /merge-mode SKILL.md:81.)
-    if (!shellOk(`ssh -o ConnectTimeout=10 ${DROPLET} "~/deploy.sh"`)) {
-      // task 984 / idea 180: ~/deploy.sh's internal /healthz curl can race the
-      // service-restart window (Node not yet bound) and exit non-zero even though
-      // the deploy succeeded — which used to false-fail the ship and force a
-      // needless /merge-mode. Before concluding failure, re-probe the public
-      // /healthz with backoff (curl's own --retry; cross-platform, no sleep).
-      // --retry-all-errors retries connection-refused during the bind window;
-      // -f makes a non-200 an error so a 502/503 also retries. If it comes up
-      // within the window the deploy really succeeded; only then-still-down fails.
-      console.log('  auto-merge: ~/deploy.sh returned non-zero — re-probing /healthz with backoff before concluding...');
-      if (shellOk('curl -fsS --max-time 10 --retry 5 --retry-delay 3 --retry-all-errors https://amazonprimea.com/healthz -o /dev/null')) {
-        console.log('  auto-merge: /healthz 200 on re-probe — deploy actually succeeded (deploy.sh raced the restart window). Proceeding.');
-      } else {
-        console.log('  auto-merge: deploy failed (/healthz never returned 200 after retries); task stays at confirmed');
-        return false;
+    // Deploy step. 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). So unless an
+    // instance whose own checkout IS its live server has configured a target
+    // (config/deploy.json "sshTarget" or <PREFIX>_DEPLOY_SSH_TARGET), the land is
+    // complete at "merged + pushed to main" and the SSH deploy is skipped. (This
+    // used to SSH a hardcoded target — the founder instance's old game box, i.e. the
+    // WRONG server post-migration. task 1002202.)
+    const { sshTarget, healthzUrl } = resolveDeployTarget({
+      configRaw: readDeployConfigRaw(),
+      branding: safeBranding(),
+    });
+    if (!sshTarget) {
+      console.log('  merged + pushed to main. No deploy target configured, so no SSH deploy —');
+      console.log('  expected for the core. To publish to a live instance run the standalone release');
+      console.log('  flow: package-core → bongos upgrade (pin-bump), per ADR 0108. (Not an SSH deploy.)');
+    } else {
+      console.log(`  triggering deploy on ${sshTarget}...`);
+      // Quote ~/deploy.sh so the LOCAL shell doesn't tilde-expand it before ssh
+      // transmits the command; with the quotes ssh sends the literal `~/deploy.sh`
+      // and the REMOTE shell expands it. (Matches /merge-mode SKILL.md:81.)
+      if (!shellOk(`ssh -o ConnectTimeout=10 ${sshTarget} "~/deploy.sh"`)) {
+        // task 984 / idea 180: ~/deploy.sh's internal /healthz curl can race the
+        // service-restart window (Node not yet bound) and exit non-zero even though
+        // the deploy succeeded — which used to false-fail the ship and force a
+        // needless /merge-mode. Before concluding failure, re-probe the CONFIGURED
+        // /healthz with backoff (curl's own --retry; cross-platform, no sleep) —
+        // never a hardcoded host. --retry-all-errors retries connection-refused
+        // during the bind window; -f makes a non-200 an error so a 502/503 also
+        // retries. If it comes up within the window the deploy really succeeded.
+        if (healthzUrl) {
+          console.log('  auto-merge: ~/deploy.sh returned non-zero — re-probing /healthz with backoff before concluding...');
+          if (shellOk(`curl -fsS --max-time 10 --retry 5 --retry-delay 3 --retry-all-errors ${JSON.stringify(healthzUrl)} -o /dev/null`)) {
+            console.log('  auto-merge: /healthz 200 on re-probe — deploy actually succeeded (deploy.sh raced the restart window). Proceeding.');
+          } else {
+            console.log('  auto-merge: deploy failed (/healthz never returned 200 after retries); task stays at confirmed');
+            return false;
+          }
+        } else {
+          console.log('  auto-merge: ~/deploy.sh returned non-zero and no healthzUrl configured to re-probe; task stays at confirmed');
+          return false;
+        }
       }
     }
 
@@ -2344,7 +2646,7 @@ function formatGradeOutcome(g, taskId) {
     out.push('When the grader is reachable again, re-grade:');
     out.push(`  node scripts/gds/ship.js ${taskId} --regrade`);
     out.push('Or land it now via manual-confirm:');
-    out.push(`  curl -X POST -H "Authorization: Bearer <token>" https://amazonprimea.com/api/gds/tasks/${taskId}/confirm`);
+    out.push(`  curl -X POST -H "Authorization: Bearer <token>" ${resolveInstanceBase() || '<instance-origin>'}/api/gds/tasks/${taskId}/confirm`);
     return out.join('\n');
   }
 
@@ -2371,7 +2673,7 @@ function formatGradeOutcome(g, taskId) {
     out.push('Grade failed — task stays at completed. Fix the issues above, commit, then re-grade:');
     out.push(`  node scripts/gds/ship.js ${taskId} --regrade`);
     out.push('Last resort (only if the grade was wrong):');
-    out.push(`  curl -X POST -H "Authorization: Bearer <token>" https://amazonprimea.com/api/gds/tasks/${taskId}/confirm`);
+    out.push(`  curl -X POST -H "Authorization: Bearer <token>" ${resolveInstanceBase() || '<instance-origin>'}/api/gds/tasks/${taskId}/confirm`);
   }
   return out.join('\n');
 }
@@ -2391,7 +2693,14 @@ function printCreditsAndAchievements({ postGradeStatus, credits, creditsRaw, cre
   if (postGradeStatus === 'completed') {
     console.log(`Credits awarded: ${credits} (none — task at completed, grade not passed)`);
   } else if (postGradeStatus === 'confirmed') {
-    console.log(`Credits awarded: ${credits} (landed at confirmed)`);
+    console.log(`Credits awarded: ${credits} (none yet — credits land when the task merges to main)`);
+  } else if (!rewardPolicy(serverReward).perTaskCredit) {
+    // cost-plus-only (ADR 0146): the per-task estimate is never paid, so this is
+    // 0 BY DESIGN. Left unexplained it reads as a broken payout — it sent a real
+    // session diagnosing the reward gate on 2026-07-26 (task 1002469).
+    console.log(`Credits awarded: ${credits} — expected: this instance pays cost-plus only.`);
+    console.log("  The task's estimate is a guide, never a payout. You're paid for this session's");
+    console.log('  real cost + 20%, booked separately from your token spend.');
   } else {
     console.log(`Credits awarded: ${credits}`);
   }
@@ -2526,7 +2835,7 @@ async function postShipSync(taskId, postGradeStatus) {
 // read make the script exit non-zero after a successful ship.
 async function onboardingNudgeBestEffort() {
   try {
-    const meRes = await (await cliClient()).me.getMe();
+    const meRes = noteServerReward(await (await cliClient()).me.getMe());
     if (meRes.ok) {
       console.log('');
       printOnboardingNudge(meRes.data);
@@ -2671,7 +2980,7 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage }) {
     let total = null;
     let widgetsEnabled = true;
     try {
-      const me = await (await cliClient()).me.getMe();
+      const me = noteServerReward(await (await cliClient()).me.getMe());
       if (me.ok && me.data) {
         if (me.data.builder) total = me.data.builder.total_credits;
         if (me.data.render) widgetsEnabled = me.data.render.widgets_enabled !== false;
@@ -2717,7 +3026,7 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage }) {
       added,
       removed,
       grade: card.grade || null,
-      credits: { awarded: card.creditsAwarded, total },
+      credits: { awarded: card.creditsAwarded, total, perTaskCredit: rewardPolicy(serverReward).perTaskCredit },
       usage: { tokens, costUsd, newTokens, cachedTokens },
       deploy: { commit },
     };
@@ -2742,6 +3051,20 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage }) {
   } catch (_) {
     /* a summary card must never fail a ship */
   }
+
+  // task 1002521: the card above says SHIPPED, which means "merged" — it does
+  // NOT mean users can see it. Publishing is manual and owner-gated, so a ship
+  // can land on main and change nothing live, and until now nothing said so.
+  // Blocker 1000097: 171 commits (a whole governance system) sat unreleased for
+  // ten days while every layer reported success. Warn, never block — a shipped
+  // task is still shipped, and an offline builder must not be punished for it.
+  try {
+    const { check, report } = require('./deploy-divergence');
+    const r = await check();
+    if (!r.undetermined && !r.ok) report(r);
+  } catch (_) {
+    /* a divergence warning must never fail a ship */
+  }
 }
 
 // Decide whether a builder may re-grade a task via `--regrade` (#678). Pure so
@@ -2882,7 +3205,7 @@ async function shipMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --notes "..." --summary "..." [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty]');
+    console.error('usage: node scripts/gds/ship.js <task-id> --notes "..." --summary "..." [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--base <ref>]');
     process.exit(2);
   }
   const notes = arg('--notes', args) || '';
@@ -2891,7 +3214,12 @@ async function shipMain() {
   const force = args.includes('--force');
   // task 391 (idea #37): a deliberate zero-commit / direct-SQL ship. Without it,
   // a branch with no commits ahead of main is REFUSED (not silently shipped).
-  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty');
+  // task 1002422: --base <ref> also implies db-only — the work is already on main
+  // (that's the whole point of --base), so the merge leg has nothing to merge and
+  // advances straight to shipped. Unlike --allow-empty it does NOT skip the grade:
+  // the pinned baseline gives the grader a real diff (see resolveBaseRef / main).
+  const baseRefRaw = arg('--base', args);
+  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty') || Boolean(baseRefRaw);
   // task 1053 (F): explicit attestation that a verification task's verify
   // actually passed. Required to confirm a kind='verify' task (the server
   // enforces it too); a no-op for every other task.
@@ -2913,7 +3241,22 @@ async function shipMain() {
   const surpriseProvided = surpriseRaw !== null;
   const noSurprise = args.includes('--no-surprise');
 
-  const me = await (await cliClient()).me.getMe();
+  // task 1002422 (blocker 1000082): resolve + validate --base BEFORE any heavy
+  // work so a bad ref aborts with the claim STILL ACTIVE. On success it sets the
+  // module-level baseOverrideSha that computeGraderBaseline() reads, so the grader
+  // reads <base>...HEAD (a real diff) and the ship takes the rank-open graded path
+  // instead of the --allow-empty → skip-grade → Archon-only /confirm dead-end.
+  if (baseRefRaw) {
+    const res = applyBaseOverride(baseRefRaw);
+    if (!res.ok) {
+      console.error(`Ship aborted: ${res.reason}. No claim resolved, no credits awarded.`);
+      console.error('Omit --base and ship normally — the grader reviews ALL your commits and the merge lands them. Your claim is still active.');
+      process.exit(2);
+    }
+    console.log(`--base: grading ${res.sha.slice(0, 9)}...HEAD — the task's real committed diff (work already on main). Graded via the rank-open path; no --allow-empty needed.`);
+  }
+
+  const me = noteServerReward(await (await cliClient()).me.getMe());
   if (!me.ok) {
     console.error('failed to load profile:', me.data);
     process.exit(1);
@@ -3382,17 +3725,31 @@ async function regradeMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary "..."] [--no-merge] [--force] [--verified]');
+    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
     process.exit(2);
   }
   const summaryArg = arg('--summary', args) || '';
   const skipMerge = args.includes('--no-merge');
   const force = args.includes('--force');
-  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty'); // task 391 — honor --db-only on a regrade too
+  // task 1002422: honor --base on regrade/resume too, so `--regrade --base <ref>`
+  // and shipMain's resume-grade dispatch grade the real <base>...HEAD diff and
+  // advance already-on-main work, instead of aborting "nothing to grade". Same
+  // 0-ahead security guard as shipMain (applyBaseOverride is the shared gate).
+  const baseRefRaw = arg('--base', args);
+  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty') || Boolean(baseRefRaw); // task 391 — honor --db-only on a regrade too
   const verified = args.includes('--verified'); // task 1053 (F) — see gate below
 
+  if (baseRefRaw) {
+    const res = applyBaseOverride(baseRefRaw);
+    if (!res.ok) {
+      console.error(`Regrade aborted: ${res.reason}. Omit --base and re-grade normally.`);
+      process.exit(2);
+    }
+    console.log(`--base: re-grading ${res.sha.slice(0, 9)}...HEAD (work already on main).`);
+  }
+
   // ---- Eligibility: completed + (owner | archon) ----
-  const me = await (await cliClient()).me.getMe();
+  const me = noteServerReward(await (await cliClient()).me.getMe());
   if (!me.ok) {
     console.error('failed to load profile:', me.data);
     process.exit(1);
@@ -3517,6 +3874,14 @@ async function regradeMain() {
 // exported: it does I/O + network and is covered by the live smoke at ship.)
 module.exports = {
   scrubSecrets, snippetOf, buildSessionDigest, resolveTranscriptPath,
+  // task 1002471: the project-path encoder, exported pure so the win32 shapes
+  // (drive colon, backslash separators, spaces) are pinned cross-platform —
+  // resolveTranscriptPath itself runs path.resolve, which can't carry a Windows
+  // path through a Linux CI run.
+  encodeProjectPath,
+  // task 1002417: the regenerated-client pathspec rule, exported pure so the
+  // "never name a path git add cannot match" invariant is tested without git/fs.
+  apiClientPathspec, VENDORED_CLIENT_REL,
   // task 1003: transcript-grade scrubber internals, exported pure so the planted-
   // secret corpus test (tests/scrubber_corpus.mjs) can exercise each layer + tune.
   shannonEntropy, looksHighEntropySecret, redactHighEntropy, collectEnvSecrets,
@@ -3524,7 +3889,7 @@ module.exports = {
   // #678: re-grade path + the grade-step helpers it shares with shipMain.
   // Exporting these formalizes learning #43 (which had to "replicate ~10
   // lines" because runSubagentGrader wasn't reachable).
-  evaluateRegradeEligibility, computeGraderBaseline, computeChangedFiles,
+  evaluateRegradeEligibility, computeGraderBaseline, computeChangedFiles, resolveBaseRef, baseRefShipGuard,
   runSubagentGrader, buildGradePayload,
   // V4.R08: diff fingerprint + grade-reuse helpers — exported pure so the
   // truth table (same hash+pass→reuse, fail→no reuse, mismatch→re-grade,
@@ -3548,7 +3913,12 @@ module.exports = {
   gitArgvOk, buildMergeArgv, sanitizeGitHubRefs,
   // #679 / ADR 0042: CI deploy mode — pure helpers exported for the regression
   // test (mode precedence/safe-default, no-shell PR argv, deploy-run match).
-  parseDeployMode, buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded,
+  // task 1002202: resolveDeployTarget — SSH target / healthz precedence + the safe
+  // "no target" default (the core has none), exported for the same reason.
+  // task 1002232: resolveInstanceBase — the ci-land/guidance origin precedence
+  // (env → session api_base → branding publicOrigin → null), pure over injected
+  // inputs so the precedence + the "no hardcoded host" guarantee are unit-tested.
+  parseDeployMode, resolveDeployTarget, resolveInstanceBase, buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded,
   // task 1049 (B): pure CI-land outcome classifier — a timed-out-but-armed PR is
   // 'pending' (success), not failure. Exported so the semantics are unit-tested.
   classifyLandOutcome,
@@ -3567,6 +3937,10 @@ module.exports = {
   pickStaleGateReviewRun,
   // task 1068: pure pre-stage-merge decision (skip on main/current, else merge).
   decidePreMerge,
+  // task 1002475: pure `git log --diff-filter=D` output parser behind
+  // preflight's upstream-deletion warning — exported so it's unit-tested
+  // without a live git repo.
+  parseDeletedUpstreamPaths,
   // task 1052 (E): box-aware "what to do next" for a confirmed-strand — a box
   // (via 'server') is pointed at the resume, never at gh-only /merge-mode.
   strandNextStep,