@bongos/core 1.19.318 → 1.19.320

package/scripts/gds/ship.js

@@ -56,4207 +56,109 @@
 //                                                       # task. Honored only when the game state is already
 //                                                       # staged-fresh (a re-run); it can't pre-approve.
 
-const crypto = require('node:crypto');
-const { execSync, execFileSync, spawnSync, spawn } = require('node:child_process');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const readline = require('node:readline');
-const { cliClient, requireSession, loadSession, loadSessionSync, printOnboardingNudge, arg, rewardPolicy } = require('./cli-lib');
-// task 1003168 (G04): how a ship reports prose + an unfinished run — see that file.
-const { resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages } = require('./ship-honesty.js');
 
-// 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).
-const { trackedDirty, classifyEmptyShip, cleanupMacFinderDupRefs, findMainWorktree, closeoutPlan } = require('../../modules/lifecycle/ship-preflight');
-const { scopeForModule, isModuleKey } = require('../../src/bongos/module-scope-map');
-const { matchOne } = require('../../src/bongos/path-match');
-// touches[] cleanup [4/8] (task 879): the predictive drift scanner
-// (src/bongos/touches-scan.js) is gone — git merge + /merge-mode are the
-// ground-truth collision detector. ship's gate is now smoke-only.
-const mergeLock = require('../../modules/lifecycle/merge-lock');
-const mergeRegen = require('./git-merge-regen');
-const grader = require('../../modules/grading/grader');
-const { runShipGate } = require('./sandbox-stage');
-// task 1045: the ship-broadcast channel router lives in a shared module so the
-// laptop-local path here and the server-mediated publish path (ADR 0055) route by
-// the exact same rule. Re-exported below for tests/ship_broadcast_routing.mjs.
-const { chooseBroadcastTargets } = require('../../modules/discord/ship-broadcast');
-
-// V3.R18 (#209): cap the diff we feed the Opus subagent grader. Very large
-// diffs blow up prompt size for marginal grading benefit — the subagent has
-// Read access to the post-resolve working tree anyway, so it can pull the
-// full text of any file it wants to inspect closely.
-const GRADER_DIFF_CHAR_CAP = 250_000;
-const GRADER_TIMEOUT_MS = 240_000; // 4 min — Opus on a big diff with Read tool calls
-
-// Where auto-merge runs — the worktree that has `main` checked out, not the
-// feature worktree this script lives in. Falls back to two-levels-up if we
-// can't ask git (e.g. fresh clone with no `main` worktree set up yet).
-const REPO_ROOT = findMainWorktree(__dirname) || path.resolve(__dirname, '..', '..');
-// Sound playback is COSMETIC — the ship pipeline must NEVER depend on it. Guard
-// the require so a missing/broken player (e.g. .claude/sounds/ absent on a fresh
-// clone or after a re-seed) degrades to a silent no-op instead of crashing ship.js
-// at load. A cosmetic feature can't be allowed to break shipping (task 1002199).
-const { playSound } = (() => {
-  try {
-    return require(path.resolve(__dirname, '../../.claude/sounds/play.js'));
-  } catch {
-    return { playSound: () => {} };
-  }
-})();
-// 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
-// single source, C11); imported above. ship.js's call sites pass `args`
-// explicitly, which cli-lib.arg() accepts (its default is process.argv.slice(2)).
-
-// ---------- Surprise / learning-capture helpers (Task #32) ----------
-//
-// Forced "anything surprise you?" gate so we never miss a learning. The flag
-// can be supplied explicitly (--surprise "text" / --surprise none / --no-surprise),
-// prompted interactively when stdin is a TTY, or default to no-surprise with a
-// stderr warning in non-interactive contexts.
-
-function promptSurprise() {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    rl.question('Anything surprise you in this work? (Enter for none, or describe): ', (answer) => {
-      rl.close();
-      resolve(answer == null ? '' : String(answer).trim());
-    });
-  });
-}
-
-function deriveTagsFromPaths(paths) {
-  // Each entry is a path/glob; take its leading folder segment as a tag.
-  // touches[] cleanup [3/8] (task 878): renamed from deriveTagsFromTouches — it
-  // now runs over the committed changed-files (reality), not the predicted
-  // touches[]. Same folder-segment logic, just a more honest input.
-  const tags = new Set();
-  for (const t of paths || []) {
-    if (!t) continue;
-    const first = String(t).split('/')[0].trim();
-    if (first && first !== '*' && first !== '**') tags.add(first);
-  }
-  if (tags.size === 0) tags.add('pms');
-  return [...tags];
-}
-
-async function captureSurpriseLearning(surpriseText, claim, taskId) {
-  const text = String(surpriseText).trim();
-  const title = text.length > 80 ? text.slice(0, 77) + '...' : text;
-  // touches[] cleanup [3/8] (task 878): tag + relate the learning by what was
-  // ACTUALLY shipped (the committed diff), not the predicted touches[]. Fall
-  // back to touches[] only when the diff is unavailable (no git / empty baseline).
-  const baseline = computeGraderBaseline(claim);
-  const changedFiles = computeChangedFiles(baseline);
-  const relatedFiles = changedFiles.length > 0 ? changedFiles : (claim.touches || []);
-  const tags = deriveTagsFromPaths(relatedFiles);
-  const r = await (await cliClient()).learnings.postLearnings({
-    body: {
-      title,
-      body_md: text,
-      tags,
-      related_files: relatedFiles,
-      source: 'ship-surprise',
-      source_ref: `task-${taskId}-claim-${claim.claim_id}`,
-      task_id: taskId,
-    },
-  });
-  if (r.status === 200 && r.data?.skipped) {
-    console.log(`📝 Learning already captured for this claim (skipped duplicate).`);
-    return true;
-  }
-  if (r.status !== 201) {
-    console.error(`  learning capture failed (${r.status}):`, r.data);
-    return false;
-  }
-  console.log(`📝 Captured learning: ${title}`);
-  return true;
-}
-
-// ---------- Memory sync-on-ship (Task #274 / V3.R55) ----------
-//
-// After a successful ship, push the builder's local Claude Code memory dir to
-// the server (POST /api/gds/memory/sync), so a builder's MEMORY.md +
-// feedback_*.md follow them across machines and survive a dead laptop. This is
-// the push half of ADR 0024's cloneable-memory chain; #275 wires the pull side.
-//
-// Convention for locating the memory dir (NO hardcoded identity — CLAUDE.md §10):
-// Claude Code stores per-project memory under
-//   <homedir>/.claude/projects/<encoded-project-path>/memory/
-// where <encoded-project-path> is the project's ABSOLUTE path with every '/'
-// and '.' replaced by '-' (e.g. /Users/x/Desktop/Claude-OTB →
-// -Users-x-Desktop-Claude-OTB). We derive the project path from the MAIN
-// worktree root (REPO_ROOT), not this ephemeral feature worktree, because the
-// memory dir is keyed to the canonical project checkout. CLAUDE_CONFIG_DIR
-// overrides the ~/.claude base when set (matches Claude Code's own behavior).
-//
-// Conflict policy: storeMemoryFile is an unconditional UPSERT (last-write-wins,
-// server clock — ADR 0024 §3), so we push every file and let the server
-// overwrite. Smarter mtime-diffing (skip files the server already has newer) is
-// a possible follow-up; for #274 a full push is correct and cheap (KB of md).
-//
-// BEST-EFFORT: any failure here is logged as a warning and swallowed — a memory
-// sync hiccup (dir missing, API down, quota) must NEVER fail or undo a ship.
-
-function claudeConfigBase() {
-  // Claude Code honors CLAUDE_CONFIG_DIR as the base for its state dir; default
-  // is ~/.claude. Resolve via os.homedir() so this works for any user.
-  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
-}
-
-function encodeProjectPath(absProjectPath) {
-  // 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
-// keys the transcript to the project dir of the CWD where the session RUNS, so
-// a session in a git worktree stores it under the WORKTREE-encoded dir, not the
-// main checkout. (6D.1 #540 shipped resolving only REPO_ROOT, which silently
-// missed every worktree session — #551.) We try the session-local dir
-// (process.cwd()) first, then REPO_ROOT as a fallback. Pure (exists + base
-// injectable for tests). Returns the first existing path, or null.
-function resolveTranscriptPath(sessionId, projectDirs, opts = {}) {
-  const exists = opts.existsFn || fs.existsSync;
-  const base = opts.base || claudeConfigBase();
-  for (const dir of projectDirs) {
-    if (!dir) continue;
-    const p = path.join(base, 'projects', encodeProjectPath(path.resolve(dir)), `${sessionId}.jsonl`);
-    if (exists(p)) return p;
-  }
-  return null;
-}
-
-// resolveBuilderModel — the REAL model that authored this session's work, read
-// from the session transcript (dominant by output tokens, synthetic turns
-// skipped), so selectGraderModel gets a true cross-model input instead of the
-// ASSUMED_BUILDER_MODEL fallback (task 1002659 — everything graded on the
-// assumed-builder default before this). Best-effort: no session id, no
-// transcript, or any read error → null → the grader assumes, as before.
-function resolveBuilderModel(opts = {}) {
-  try {
-    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
-    // Same path-traversal guard as uploadSessionOnShip: the id lands in a path.
-    if (!sessionId || !/^[A-Za-z0-9_-]+$/.test(sessionId)) return null;
-    const transcriptPath = resolveTranscriptPath(sessionId, [process.cwd(), REPO_ROOT].filter(Boolean), opts);
-    if (!transcriptPath) return null;
-    const perModel = new Map();
-    for (const line of fs.readFileSync(transcriptPath, 'utf8').split('\n')) {
-      if (!line.trim()) continue;
-      let o;
-      try { o = JSON.parse(line); } catch (_) { continue; }
-      const msg = o && o.message;
-      if (!msg || !msg.model || msg.model === '<synthetic>' || !msg.usage) continue;
-      perModel.set(msg.model, (perModel.get(msg.model) || 0) + (Number(msg.usage.output_tokens) || 0));
-    }
-    let best = null;
-    let bestTokens = 0;
-    for (const [model, tokens] of perModel) {
-      if (tokens > bestTokens) { best = model; bestTokens = tokens; }
-    }
-    return best;
-  } catch (_) {
-    return null;
-  }
-}
-
-function resolveMemoryDir() {
-  // REPO_ROOT is the main worktree (canonical project checkout). The memory dir
-  // is keyed to that path, not the per-task feature worktree we're shipping from.
-  const encoded = encodeProjectPath(path.resolve(REPO_ROOT));
-  return path.join(claudeConfigBase(), 'projects', encoded, 'memory');
-}
-
-// Enumerate the memory dir into [{ path, content, mtime }]. `path` is RELATIVE
-// to the memory dir (matches the server's (builder_id, relative-path) key).
-// Recurses so nested memory files (if Claude Code ever nests them) are caught.
-// Returns [] if the dir doesn't exist (not all builders have memory).
-function collectMemoryFiles(memDir) {
-  if (!fs.existsSync(memDir)) return [];
-  const out = [];
-  const walk = (absDir, relPrefix) => {
-    let entries;
-    try {
-      entries = fs.readdirSync(absDir, { withFileTypes: true });
-    } catch (_) {
-      return;
-    }
-    for (const ent of entries) {
-      const abs = path.join(absDir, ent.name);
-      const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
-      if (ent.isDirectory()) {
-        walk(abs, rel);
-      } else if (ent.isFile()) {
-        try {
-          const content = fs.readFileSync(abs, 'utf8');
-          const mtime = fs.statSync(abs).mtime.toISOString();
-          // Use POSIX-style relative paths regardless of OS so the server key
-          // is stable across machines.
-          out.push({ path: rel.split(path.sep).join('/'), content, mtime });
-        } catch (_) {
-          /* skip unreadable file — best-effort */
-        }
-      }
-    }
-  };
-  walk(memDir, '');
-  return out;
-}
-
-async function syncMemoryOnShip() {
-  try {
-    const memDir = resolveMemoryDir();
-    const files = collectMemoryFiles(memDir);
-    if (files.length === 0) {
-      // Silent-ish: a builder with no memory dir is normal. One quiet line so
-      // the absence is visible in the ship log without looking like an error.
-      console.log('  memory sync: no local memory dir found — skipping (this is fine).');
-      return;
-    }
-    console.log(`  syncing ${files.length} memory file${files.length === 1 ? '' : 's'} to the server...`);
-    const r = await (await cliClient({ allowUnauthenticated: true })).memory.postMemorySync({ body: { files } });
-    if (r.status === 401) {
-      console.log('  memory sync: skipped (session not valid for sync; non-blocking).');
-      return;
-    }
-    const d = r.data || {};
-    if (r.ok) {
-      const errN = Array.isArray(d.errors) ? d.errors.length : 0;
-      console.log(
-        `  memory sync: ${d.stored ?? 0} stored, ${d.skipped ?? 0} skipped${errN ? `, ${errN} error(s)` : ''}.`
-      );
-    } else if (r.status === 413) {
-      console.log(`  memory sync: quota/size limit hit (${d.error || 'quota'}) — prune memory and re-sync. Non-blocking; ship is complete.`);
-    } else {
-      console.log(`  memory sync: server returned ${r.status} (non-blocking):`, d.error || d);
-    }
-  } catch (e) {
-    // Any error at all — network, fs, anything — must not fail the ship.
-    console.log('  memory sync failed (non-blocking):', e && e.message ? e.message : e);
-  }
-}
-
-// ---------- Session upload-on-ship (6D.1 / ADR 0027) ----------
-//
-// After a successful ship, upload a COMPACT, secret-scrubbed digest of this
-// Claude Code session (POST /api/gds/sessions), so the BFG (a local Claude Code
-// routine — 6D.3) can later search the corpus (6D.2) and deep-dive the wasteful
-// sessions. We never upload raw transcript CONTENT — only per-turn metadata
-// (role, tool name, error flag, token usage, length) + short scrubbed snippets
-// + token aggregates. That keeps the row small and the secret surface minimal
-// (ADR 0027). BEST-EFFORT: any failure is a warning, never a ship failure —
-// exactly like syncMemoryOnShip.
-
-// The transcript-grade secret scrubber + its ADR-0022 internals now live in
-// modules/security/secret-scrub.js — extracted (task 1211 / GDS-V4 R72) so the
-// public-mirror export pipeline can reuse the ONE copy of the secret shapes
-// without requiring ship.js (whose grader / Discord / sound / session deps are
-// absent in a bare CI job). Imported + re-exported here so this file's public
-// surface and tests/scrubber_corpus.mjs are unchanged. See that module for the
-// recall-first design (a missed secret is a compromise; over-redaction is cosmetic).
-const {
-  REDACTED, scrubSecrets, shannonEntropy, looksHighEntropySecret,
-  redactHighEntropy, collectEnvSecrets,
-} = require('../../modules/security/secret-scrub');
-
-// snippetOf + buildSessionDigest moved to ./session-digest-build (task 1003217,
-// serving the de-monolith goal of task 1003203) — pure, separately tested, and
-// shared with session-digest.js. Re-exported below so this file's public surface
-// and tests/session_records.mjs are unchanged.
-const {
-  snippetOf, buildSessionDigest, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL,
-} = require('./session-digest-build');
-
-
-// classifyUploadSkip — PURE decision for whether the session upload must skip,
-// and the clear, actionable reason why. Separated from I/O so it is unit-tested
-// (tests/ship_upload_skip.mjs). Every reason names the cause AND states the
-// consequence plainly: a skip means this ship is absent from the BFG session
-// corpus — the silent gap #608 surfaced, this (#617) makes it loud + auditable.
-// Takes already-resolved preconditions so it stays free of env + fs reads.
-function classifyUploadSkip({ sessionId, sessionIdSafe, transcriptPath, pathsTried }) {
-  const tail = 'This ship will NOT appear in the BFG session corpus.';
-  if (!sessionId) {
-    return {
-      skip: true,
-      code: 'no_session_id',
-      reason:
-        'CLAUDE_CODE_SESSION_ID is not set — this ship did not run inside an interactive Claude Code ' +
-        `session (e.g. an autonomous / merge-mode / cron context), so there is no transcript to digest. ${tail}`,
-    };
-  }
-  if (!sessionIdSafe) {
-    return {
-      skip: true,
-      code: 'unsafe_session_id',
-      reason: `CLAUDE_CODE_SESSION_ID is not a plain token, refusing to interpolate it into a filesystem path. ${tail}`,
-    };
-  }
-  if (!transcriptPath) {
-    const where = Array.isArray(pathsTried) && pathsTried.length ? ` Looked in: ${pathsTried.join(' ; ')}.` : '';
-    return {
-      skip: true,
-      code: 'transcript_not_found',
-      reason: `the session transcript .jsonl was not found for ${sessionId}.${where} ${tail}`,
-    };
-  }
-  return { skip: false };
-}
-
-// recordUploadSkip — surface a skipped/failed session upload LOUDLY (not the old
-// quiet console.log that scrolled past + vanished in non-interactive runs) AND
-// leave a durable, append-only trace so a missed capture is auditable after the
-// fact. ~/.config/otb survives worktree churn (same home as the GDS session
-// token). Best-effort: never throws into the ship path. opts.dir overrides the
-// trace dir for tests. Returns the trace file path written, or null.
-function recordUploadSkip(taskId, { code, reason }, opts = {}) {
-  console.log(`  ⚠️  session upload SKIPPED [${code}]: ${reason}`);
-  try {
-    const dir = opts.dir || require('../../src/instance-config').configHome();
-    fs.mkdirSync(dir, { recursive: true });
-    const file = path.join(dir, 'session-upload-skips.jsonl');
-    const row = {
-      ts: new Date().toISOString(),
-      task_id: taskId != null && Number.isFinite(Number(taskId)) ? Number(taskId) : null,
-      session_id: process.env.CLAUDE_CODE_SESSION_ID || null,
-      code,
-      reason,
-    };
-    fs.appendFileSync(file, JSON.stringify(row) + '\n');
-    return file;
-  } catch (e) {
-    console.log(`  (could not persist skip trace: ${e && e.message ? e.message : e})`);
-    return null;
-  }
-}
-
-async function uploadSessionOnShip(taskId) {
-  try {
-    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
-    // Path-traversal guard: the session id is interpolated into a filesystem
-    // path below, so reject anything that isn't a plain UUID-ish token. A
-    // hostile env value with `../` could otherwise point the read elsewhere.
-    const sessionIdSafe = !!sessionId && /^[A-Za-z0-9_-]+$/.test(sessionId);
-    // The transcript is keyed to the session's CWD (the worktree when shipping
-    // from one), so try that before REPO_ROOT (#551). Reconstruct the exact
-    // paths resolveTranscriptPath checks so a transcript-not-found skip can name
-    // precisely where it looked (actionable, not a bare "not found").
-    const dirsTried = [process.cwd(), REPO_ROOT].filter(Boolean);
-    const pathsTried = sessionIdSafe
-      ? dirsTried.map((d) =>
-          path.join(claudeConfigBase(), 'projects', encodeProjectPath(path.resolve(d)), `${sessionId}.jsonl`)
-        )
-      : [];
-    const transcriptPath = sessionIdSafe ? resolveTranscriptPath(sessionId, dirsTried) : null;
-
-    const decision = classifyUploadSkip({ sessionId, sessionIdSafe, transcriptPath, pathsTried });
-    if (decision.skip) {
-      recordUploadSkip(taskId, decision);
-      return null;
-    }
-    const raw = fs.readFileSync(transcriptPath, 'utf8');
-    const entries = [];
-    for (const line of raw.split('\n')) {
-      const t = line.trim();
-      if (!t) continue;
-      try {
-        entries.push(JSON.parse(t));
-      } catch (_) {
-        /* skip a malformed line — best-effort */
-      }
-    }
-    // Dynamic secrets to scrub: every secret-shaped env VALUE (Apple/MAC_* CI
-    // creds, a baked GDS/DO token, GITHUB_TOKEN, ANTHROPIC_API_KEY, …) plus this
-    // run's live GDS session token. Defense in depth on top of the pattern +
-    // entropy scrubbers — these literals get redacted even with no known shape.
-    const extraSecrets = collectEnvSecrets();
-    // loadSession() returns null when there's no session — unlike
-    // requireSession(), it never process.exit()s, so the best-effort /
-    // non-blocking contract holds even with no valid session.
-    const s = await loadSession();
-    if (s && s.token) extraSecrets.push(s.token);
-    const digest = buildSessionDigest(entries, { extraSecrets });
-    // task 1270: surface the session usage so the completion card can show
-    // Claude tokens + an estimated cost. Returned even when the POST below fails
-    // (we already have the digest) — the card is best-effort either way.
-    const usageOut = {
-      totalTokens: digest.totalTokens,
-      modelUsage: (digest.metrics && digest.metrics.model_usage) || {},
-    };
-    // drachmae_earned is computed SERVER-SIDE from the credit_log ledger
-    // (POST /sessions). ship.js no longer fetches or sends it — that removes an
-    // extra apiCall whose 401 path would process.exit(2) and break this
-    // best-effort, non-blocking contract.
-    const payload = {
-      session_id: sessionId,
-      task_ids: [Number(taskId)].filter(Number.isFinite),
-      total_tokens: digest.totalTokens,
-      duration_seconds: digest.durationSeconds,
-      started_at: digest.startedAt,
-      ended_at: digest.endedAt,
-      detail: digest.detail,
-      metrics: digest.metrics,
-      model_usage: digest.metrics.model_usage || {}, // per-model tokens → cost-plus reward (task 1005)
-    };
-    const r = await (await cliClient({ allowUnauthenticated: true })).sessions.postSessions({ body: payload });
-    if (r.ok) {
-      console.log(
-        `  session upload: stored digest (${digest.metrics.assistant_turns} assistant turns, ${digest.totalTokens} tokens, ${digest.metrics.tool_error_count} tool errors, ${digest.metrics.harness_retry_count} harness retries).`
-      );
-    } else if (r.status === 401) {
-      recordUploadSkip(taskId, {
-        code: 'session_invalid',
-        reason:
-          'POST /api/gds/sessions returned 401 — the GDS session token is missing or invalid, so the ' +
-          'digest was rejected. Re-auth with /builder-reauth. This ship will NOT appear in the BFG session corpus.',
-      });
-    } else {
-      recordUploadSkip(taskId, {
-        code: `http_${r.status}`,
-        reason:
-          `POST /api/gds/sessions returned ${r.status}${r.data && r.data.error ? ` (${apiErrorLine(r.data)})` : ''} — ` +
-          'the API rejected or could not store the digest. This ship will NOT appear in the BFG session corpus.',
-      });
-    }
-    return usageOut;
-  } catch (e) {
-    recordUploadSkip(taskId, {
-      code: 'exception',
-      reason:
-        `session upload threw before completing: ${e && e.message ? e.message : e}. ` +
-        'This ship will NOT appear in the BFG session corpus.',
-    });
-    return null;
-  }
-}
-
-function gitOk(cmd, opts = {}) {
-  try {
-    return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
-  } catch (_) {
-    return null;
-  }
-}
-
-function shellOk(cmd, opts = {}) {
-  try {
-    execSync(cmd, { stdio: 'inherit', ...opts });
-    return true;
-  } catch (_) {
-    return false;
-  }
-}
-
-// argvOk / argvOut — the two no-shell exec primitives behind the git/gh wrappers.
-// Run `<cmd> <args...>` so each arg reaches the program as a literal argv element
-// (never interpolated into a shell string) — the discipline that closes the
-// autoMerge injection (#681), since branch names + DB-sourced value_summary flow
-// through here. `shell: false` is forced AFTER the opts spread so a caller can
-// never pass `{ shell: true }` and silently re-enable shell interpretation — the
-// no-shell guarantee is the whole point and must not be overridable.
-//   argvOk  — exit status only → boolean (gitArgvOk / ghArgvOk). stdio 'inherit'.
-//   argvOut — capture trimmed stdout → string|null (ghJson / fetchDeployedVersion).
-//             Default stdio captures BOTH stdout and stderr; a caller that must
-//             DISCARD stderr passes its own `stdio: ['ignore','pipe','ignore']`.
-function argvOk(cmd, args, opts = {}) {
-  try {
-    execFileSync(cmd, args, { stdio: 'inherit', ...opts, shell: false });
-    return true;
-  } catch (_) {
-    return false;
-  }
-}
-
-function argvOut(cmd, args, opts = {}) {
-  try {
-    return execFileSync(cmd, args, {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-      ...opts,
-      shell: false,
-    }).trim();
-  } catch (_) {
-    return null;
-  }
-}
-
-// gitArgvOk — the git boolean runner. The boolean/`stdio:'inherit'` contract
-// matches shellOk so callers can swap one for the other; see buildMergeArgv + the
-// #681 regression test.
-function gitArgvOk(args, opts = {}) {
-  return argvOk('git', args, opts);
-}
-
-// sanitizeGitHubRefs — rewrite "#NNN" → "task NNN" in any text that lands on a
-// GitHub-rendered surface that can't carry a markdown link (commit messages,
-// PR titles). GitHub autolinks every bare "#NNN" there to its OWN PR/issue
-// number space, which our GDS task ids long since diverged from — so a value
-// summary like "#914 player straw hat" rendered a dead link to issues/914 on
-// every merge commit (task 916). Pure + exported for the regression test.
-function sanitizeGitHubRefs(text) {
-  return String(text == null ? '' : text).replace(/#(\d{1,5})\b/g, 'task $1');
-}
-
-// buildMergeArgv — construct the argv for the auto-merge commit. Pure +
-// exported so the regression test can assert the untrusted value_summary lands
-// as a single literal argv element (never spliced into a shell string). The
-// merge message is `Merge <branch>: <summary>` with task refs de-#-ed (commit
-// messages can't carry markdown links, so a bare "#NNN" would autolink to a
-// dead GitHub issue — task 916); transport stays argv, never a shell string.
-function buildMergeArgv(branch, valueSummary) {
-  const summary = sanitizeGitHubRefs(valueSummary) || `(no value summary)`;
-  const mergeMsg = `Merge ${branch}: ${summary}`;
-  return ['merge', '--no-ff', branch, '-m', mergeMsg];
-}
-
-// ---------- 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;
-}
-
-// ---------- the land outcome (task 1002541, part 1) ----------
-//
-// The land chain used to answer with a bare boolean. Every bail site already
-// computes a precise reason and logs it, but `false` threw that reason away — so
-// the completion card had only the task's STATUS to go on ('confirmed') and
-// printed "Deploy  landing automatically" even when nothing was landing and the
-// builder was, under ADR 0120, unpaid. The failure announced itself as success.
-//
-// "Not shipped" is not one thing, so this is a three-way, not a boolean:
-//   landed()         — merged + deployed; the task flips to shipped.
-//   landPending()    — published and auto-merge armed: it DOES land on its own
-//                      (CI / the server reconciler), so "landing automatically"
-//                      is honest here. A poll timeout is this, not a failure
-//                      (task 1049) — keep it out of the loud path.
-//   landBailed(r, n) — nothing is landing. `r` is the reason already logged,
-//                      `n` the command that recovers it.
-// Only landBailed makes the card say NOT landed. Purely additive: no bail site
-// changes what it DOES, only what it now reports back.
-// ADR 0184: an EMPTY ship has no commit to prove, so it must DECLARE itself.
-function landed(o = {}) { return { ok: true, pending: false, reason: null, nextStep: null, noArtifact: o.noArtifact === true, noArtifactReason: o.noArtifactReason || null }; }
-function landPending() { return { ok: false, pending: true, reason: null, nextStep: null }; }
-function landBailed(reason, nextStep = null) { return { ok: false, pending: false, reason, nextStep }; }
-
-// The short COMMAND form of strandNextStep (which is prose, sized for the log).
-// The card has room for one command, not a sentence.
-function strandCommand(taskId, via) {
-  return via === 'server' ? `node scripts/gds/ship.js ${taskId}` : '/merge-mode';
-}
-
-// ciLand — dispatch the 'ci' confirmed->shipped land to the local or the
-// server-mediated path. Async because the server path awaits GDS API calls.
-async function ciLand(taskId, branch, valueSummary) {
-  console.log('  deploy mode: ci — landing via PR auto-merge (no droplet key needed)');
-  if (pushVia() === 'server') {
-    return ciLandServer(taskId, branch, valueSummary);
-  }
-  return await ciLandLocal(taskId, branch, valueSummary);
-}
-
-// task 1001916: render a FAILED POST /tasks/:id/publish-branch for the builder.
-// The server has carried { step, reason } — which git step failed + the
-// credential-scrubbed stderr — since task 1547, but the bail site printed only
-// `data.message || data.error`: "[object Object]" on the ADR 0116 envelope, a
-// bare `publish_failed` on the legacy flat shape. That hid a non-fast-forward
-// rejection (the server had already freshened the branch itself) across several
-// blind retry laps, so that case also gets its specific remedy. Pure + exported
-// for tests/ship_publish_error.mjs (no git, no network).
-const NON_FAST_FORWARD_RE = /fetch first|non-fast-forward/i;
-
-function formatPublishFailure(data, status, branch) {
-  const { code, message } = normalizeApiError(data);
-  const envelopeDetails = (data && data.error && typeof data.error === 'object' && data.error.details) || null;
-  const details = envelopeDetails || data || {};
-  const label = message || code || (data && data.message) || `HTTP ${status}`;
-  // git stderr is multi-line; this is embedded mid-sentence in one log line.
-  const reason = details.reason ? String(details.reason).replace(/\s+/g, ' ').trim() : '';
-  const parts = [];
-  if (details.step) parts.push(`step: ${details.step}`);
-  if (reason) parts.push(`reason: ${reason}`);
-  let out = parts.length ? `${label} (${parts.join('; ')})` : label;
-  if (NON_FAST_FORWARD_RE.test(reason)) {
-    out += ` — the server already moved ${branch}: fetch origin, reset onto origin/${branch}, `
-      + 're-run the generators, and re-ship so the push fast-forwards.';
-  }
-  return out;
-}
-
-// ciLandServer — the dev-box path: no GitHub push credential on this machine, so
-// hand the branch to the GDS, which pushes it + opens the PR + auto-merges with
-// the server-side credential. Requires a RE-AUTHED (non-box) cli session — a
-// box-scoped session is 403'd by the endpoint (it must `/builder-reauth` first).
-async function ciLandServer(taskId, branch, valueSummary) {
-  console.log('  ci-land: server-mediated publish (this machine has no GitHub push credential)');
-  const headSha = gitOk('git rev-parse HEAD');
-  // Make sure origin/main is current so the THIN bundle's `origin/main..HEAD`
-  // base is resolvable (a read-only fetch — works on a credential-less origin).
-  gitArgvOk(['fetch', 'origin', 'main'], { stdio: 'ignore' });
-
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-bundle-'));
-  const bundlePath = path.join(tmpDir, 'branch.bundle');
-  try {
-    if (!gitArgvOk(['bundle', 'create', bundlePath, `origin/main..${branch}`], { stdio: 'ignore' })) {
-      console.log(`  ci-land: could not build the branch bundle (nothing new to push, or a git error); task stays at confirmed. ${strandNextStep(taskId, 'server')}`);
-      return landBailed('could not build the branch bundle', strandCommand(taskId, 'server'));
-    }
-    const bundleB64 = fs.readFileSync(bundlePath).toString('base64');
-    // allowBoxScope: handle the box_scope 403 locally (graceful "stays at
-    // confirmed, re-auth + re-ship") instead of cli-lib's central exit — task
-    // 1050. (In practice unreachable: a box session can't have claimed/confirmed
-    // to get here. Kept as a defensive, graceful path.)
-    const r = await (await cliClient({ allowBoxScope: true })).tasks.postTasksIdPublishBranch({
-      id: taskId,
-      body: { branch, head_sha: headSha, value_summary: valueSummary, bundle_b64: bundleB64 },
-    });
-    if (r.status === 403 && normalizeApiError(r.data).code === 'box_scope') {
-      console.log('  ci-land: this session is BOX-SCOPED — run /builder-reauth (browser, no terminal) to mint a real session, then re-ship. Task stays at confirmed.');
-      return landBailed('this CLI session is box-scoped', '/builder-reauth');
-    }
-    if (r.status === 503) {
-      console.log('  ci-land: server-mediated push is not configured on the server yet (no GitHub App nor GITHUB_PUSH_TOKEN — operator action, ADR 0055). Task stays at confirmed.');
-      return landBailed('server-mediated push is not configured (operator action)', strandCommand(taskId, 'server'));
-    }
-    if (!r.ok) {
-      const e = formatPublishFailure(r.data, r.status, branch);
-      console.log(`  ci-land: server publish failed — ${e}. Task stays at confirmed. ${strandNextStep(taskId, 'server')}`);
-      return landBailed(`server publish failed — ${e}`, strandCommand(taskId, 'server'));
-    }
-    console.log(`  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge ${r.data.auto_merge ? 'enabled' : 'NOT enabled — merge it on GitHub'}).`);
-    return pollServerPublish(taskId, branch);
-  } finally {
-    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
-  }
-}
-
-// task 1049 (B — async land semantics): classify a CI-land poll outcome so a
-// SUCCESSFUL-but-still-running publish reads as success, not failure. The #1027
-// retrospective: the ship's poll window is shorter than real CI, so a PR that was
-// opened + auto-merge-armed (a SUCCESS) printed "did not merge — task stays at
-// confirmed" and looked like a failure. Outcomes:
-//   'shipped' — merged AND deploy-prod succeeded → flip the task to shipped
-//   'failed'  — PR closed without merging (a check failed / closed manually)
-//   'pending' — PR still open with auto-merge armed (or merged, deploy not yet):
-//               NOT a failure — it lands on its own (the server reconciles the
-//               task to shipped, and a re-run resumes — task 941).
-// 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' || deployStatus === 'unconfigured')) return 'shipped';
-  if (prState === 'closed' && !merged) return 'failed';
-  return 'pending';
-}
-
-// task 1718: PURE — after ciLandLocal tries to arm GitHub auto-merge, decide which
-// poll path lands + watches the PR. Arming auto-merge commonly FAILS when shipping
-// from a worktree (`gh pr merge --auto` runs a git op that trips on `'main' is
-// already used by worktree`) or with branch protection off — but the PR is open and
-// this is NOT a dead-end: the server's merge driver + reconciler still land green
-// PRs. So an enable-failure must NOT strand the builder at 'confirmed' (they'd never
-// see the SHIPPED banner in-session, and the machine-global land-watch breadcrumb
-// would surface it in some OTHER session). Instead:
-//   'ci'     → auto-merge armed: watch GitHub directly (pollCiDeploy).
-//   'server' → auto-merge NOT armed: drive + watch the server land via publish-status
-//              (pollServerPublish) — reading it is reconcile-on-read, so it DRIVES the
-//              merge and observes the flip to 'shipped'.
-// Both paths end at 'shipped' on a real land, so the banner renders in the shipping
-// session and no 'confirmed' breadcrumb is written. Exported for unit tests.
-function landPollAfterAutoMerge(autoMergeArmed) {
-  return autoMergeArmed ? 'ci' : 'server';
-}
-
-// task 1719: PURE — after mergeAndDeploy runs, the completion card + the pending-land
-// breadcrumb must reflect the AUTHORITATIVE post-land status, not the pre-merge one
-// finishShip was handed. If the task actually reached 'shipped' in-session (a laptop
-// sync land, the enable-success poll, or the task-1718 enable-failure server poll),
-// the card renders the SHIPPED banner and printCompletionCard writes NO breadcrumb;
-// otherwise keep the pre-merge status (the async land is still pending → 'confirmed' →
-// the next-turn land-watch breadcrumb is the intended fallback). Exported for tests.
-function reconciledCardStatus(liveStatus, preMergeStatus) {
-  return liveStatus === 'shipped' ? 'shipped' : preMergeStatus;
-}
-
-// task 1052 (E): the box-appropriate next step when a ship lands the task at
-// 'confirmed' without finishing. A dev box (pushVia 'server' — no authed gh)
-// CANNOT run /merge-mode (it needs gh + a main checkout), so the old "for
-// /merge-mode" advice was a dead end ON A BOX (the #1027 retrospective: the agent
-// had to reverse-engineer recovery from source). Point a box at the resume
-// instead (task 941); a laptop keeps /merge-mode (with resume as the alternative).
-// Pure + exported for unit tests.
-function strandNextStep(taskId, via) {
-  if (via === 'server') {
-    return `Re-run \`node scripts/gds/ship.js ${taskId}\` to resume — it picks up exactly where it stopped (task 941). ` +
-      `(/merge-mode is NOT available here — it needs gh + a main checkout this machine doesn't have.)`;
-  }
-  return `Run /merge-mode to land it — or re-run \`node scripts/gds/ship.js ${taskId}\`, which resumes from here (task 941).`;
-}
-
-// The standard "published — it'll land on its own" success-pending banner
-// (task 1049). Shared by both poll paths so the message is identical and never
-// reads as a failure. The task legitimately stays at 'confirmed' until CI lands
-// it; the server reconciles it to 'shipped' (publish-status reconcile-on-read)
-// and a re-run resumes (task 941).
-//
-// task 1002606 (finding P-3): the banner used to end at "NOT a failure", so when
-// a land DID fail (hand-written conflict, PR closed unmerged, persistent red
-// check) the builder's last signal said everything was fine and the strand sat
-// invisible until they happened to look. The banner now tells the failure story
-// too: the server flags a strand needs_rebase (definitive shapes within a sweep,
-// ambiguous ones at ~30 min), /builder-start warns, and new claims gate on it.
-// Pure + exported so the wording is pinned by tests/ship_ci_deploy.mjs.
-function landPendingLines(taskId, { merged } = {}) {
-  return [
-    `  ci-land: ✓ Published — auto-merge is armed${merged ? ' and the PR has merged' : ''}. This is NOT a failure.`,
-    `  CI is still finishing; GitHub will ${merged ? 'deploy' : 'merge + deploy'} automatically once the required checks pass,`,
-    `  and the task flips to 'shipped' on its own. Re-run \`node scripts/gds/ship.js ${taskId}\` anytime to confirm`,
-    `  it landed — it resumes from here (task 941). The task is at 'confirmed' until the deploy completes.`,
-    `  If it CANNOT land on its own (a hand-written merge conflict, the PR closed without merging, a check`,
-    `  that keeps failing), the server flags the task needs_rebase — /builder-start will warn you and new`,
-    `  claims are gated until you fix + re-land it (re-run the ship after fixing), or release it.`,
-  ];
-}
-function printLandPending(taskId, opts = {}) {
-  console.log('');
-  for (const line of landPendingLines(taskId, opts)) console.log(line);
-}
-
-// task 1002645 — the honest close-out when the PR MERGED but the server refused the
-// confirmed→shipped flip (reconcile_blocked: the task-1547 land proof missed — a
-// wrong/missing published tip, or the matched PR doesn't reference this task). The
-// optimistic "NOT a failure" banner was a lie here: without proof the auto-land can
-// NEVER finish, and the wave-5 ships sat at 'confirmed' with their last signal
-// saying everything was fine. Name the refusal and the remedy instead. Pure +
-// exported so the wording is pinned by tests/ship_ci_deploy.mjs.
-function reconcileBlockedLines(taskId, reason) {
-  return [
-    `  ci-land: the PR MERGED, but the task did NOT flip to 'shipped' — the server could not prove the land is`,
-    `  THIS task's: ${reason}.`,
-    `  The server reconciler retries the proof every ~5 min, so a late-recorded tip or PR reference still lands`,
-    `  on its own. Re-run \`node scripts/gds/ship.js ${taskId}\` to re-drive it; if it stays blocked the server`,
-    `  flags the task needs_rebase and /builder-start will show the remedy.`,
-  ];
-}
-
-// One module-scope sleep command shared by both poll loops (task 1093 / C9). A
-// child `node -e setTimeout` is used (not `await new Promise`) so it blocks
-// identically in the SYNCHRONOUS pollCiDeploy and the async pollServerPublish —
-// the loops keep their own structure (sync vs async, 1-stage vs 2-stage); only
-// the ~10s cadence is shared.
-const POLL_SLEEP_CMD = 'node -e "setTimeout(()=>{}, 10000)"';
-
-// pollServerPublish — the server-mediated analogue of pollCiDeploy. Polls the
-// GDS publish-status endpoint (which the server answers from GitHub, and which
-// reconciles the task to shipped when it observes merge+deploy — task 1049) until
-// the PR merges + deploy-prod succeeds. Returns true when prod is confirmed live;
-// a timeout with an armed PR is success-PENDING (the publish worked), not failure.
-async function pollServerPublish(taskId, branch) {
-  const TRIES = 54; // ~9 min at 10s — checks + auto-merge + Actions deploy
-  console.log('  ci-land: waiting for auto-merge + prod deploy (polling the server)...');
-  // task 1002645: GitHub can report merged+deployed while the SERVER refused the
-  // confirmed→shipped flip (reconcile_blocked — the task-1547 land proof missed).
-  // "Prod is live" + exit here was a lie that left the task stranded with no
-  // signal. Say the real reason and keep polling — attest-gate now records the
-  // pushed tip, so the proof usually heals within the window.
-  let blockedReason = null;
-  for (let i = 0; i < TRIES; i++) {
-    const r = await (await cliClient()).tasks.getTasksIdPublishStatus({ id: taskId, query: { branch } });
-    if (r.ok && r.data) {
-      const outcome = classifyLandOutcome(r.data);
-      if (outcome === 'shipped') {
-        if (r.data.reconcile_blocked) {
-          if (r.data.reconcile_blocked !== blockedReason) {
-            blockedReason = r.data.reconcile_blocked;
-            console.log(`  ci-land: merged, but the server did NOT flip the task to shipped: ${blockedReason}. Still polling (the reconciler retries every sweep)...`);
-          }
-        } else {
-          console.log(`  ci-land: merged (${String(r.data.merge_sha || '').slice(0, 8)}) + deploy-prod succeeded. Prod is live.`);
-          return landed();
-        }
-      }
-      if (outcome === 'failed') {
-        console.log(`  ci-land: PR was CLOSED without merging (a required check failed, or it was closed manually). Fix it and re-run \`node scripts/gds/ship.js ${taskId}\` to resume. Task stays at 'confirmed'.`);
-        return landBailed('the PR was closed without merging (a check failed, or it was closed manually)', `node scripts/gds/ship.js ${taskId}`);
-      }
-    }
-    shellOk(POLL_SLEEP_CMD);
-  }
-  if (blockedReason) {
-    console.log('');
-    for (const line of reconcileBlockedLines(taskId, blockedReason)) console.log(line);
-    return landBailed(`the PR merged but the server could not prove the land is this task's: ${blockedReason}`, `node scripts/gds/ship.js ${taskId}`);
-  }
-  printLandPending(taskId);
-  return landPending();
-}
-
-// attestGateTrust — task 1169 (ADR 0058). Ask the SERVER to post the trustless
-// gate-author-trust commit status for THIS builder's server-resolved rank on the
-// pushed head SHA. ship.js's local path pushes + opens the PR with the laptop's
-// OWN gh credential, but only the server can forge the rank attestation the
-// ENFORCING gate-review check reads — without it a Metic+ author's gate-surface PR
-// from a laptop is BLOCKED and they can't self-approve it (task 1162 / PR #131).
-// Best-effort + never throws: a non-Metic author, an unconfigured server, or a
-// transient failure just leaves the PR un-attested → it escalates (the safe
-// direction). A non-gate PR is unaffected by the attestation either way.
-async function attestGateTrust(taskId, headSha) {
-  if (!headSha) return;
-  try {
-    const r = await (await cliClient()).tasks.postTasksIdAttestGate({ id: taskId, body: { head_sha: headSha } });
-    if (r.ok && r.data) {
-      if (r.data.attested) {
-        console.log('  ci-land: gate-author-trust attested on the head SHA (Metic+) — a gate-surface PR auto-passes the ADR-0058 gatekeeper.');
-      } else {
-        console.log(`  ci-land: gate-author-trust NOT attested (${r.data.reason || 'rank below Metic'}) — a gate-surface PR will need owner approval; a non-gate PR is unaffected.`);
-      }
-    } else if (r.status === 503) {
-      console.log('  ci-land: the server has no push credential to post the gate attestation (operator: GITHUB_APP_* / GITHUB_PUSH_TOKEN). A gate-surface PR will need owner approval.');
-    } else {
-      console.log(`  ci-land: gate attestation request failed (HTTP ${r.status}); a gate-surface PR may need a manual re-run / owner approval.`);
-    }
-  } catch (_) {
-    /* best-effort — never block the ship on the attestation */
-  }
-}
-
-// pickStaleGateReviewRun — PURE. Among `gh run list --json
-// databaseId,headSha,status,conclusion` results for the gate-review workflow,
-// find a run on THIS head SHA that has already COMPLETED without success — the
-// one to re-run after the attestation is posted, because a new commit status does
-// NOT re-trigger a pull_request-triggered check (the task 1162 / PR #131 gotcha).
-// Returns the run's databaseId, or null when there's nothing stale to re-run (no
-// run yet, still in flight, or already green). Exported for unit tests.
-function pickStaleGateReviewRun(runs, headSha) {
-  if (!headSha || !Array.isArray(runs)) return null;
-  const hit = runs.find(
-    (r) => r && r.headSha === headSha && r.status === 'completed' && r.conclusion && r.conclusion !== 'success'
-  );
-  return hit ? (hit.databaseId ?? null) : null;
-}
-
-// rerunGateReviewIfStale — best-effort gh re-run of a stale (completed-non-success)
-// gate-review run on the current head, so it re-reads the freshly-posted
-// gate-author-trust attestation. Only acts when such a run exists: a freshly-opened
-// PR needs NO nudge (gate-review runs once, AFTER the attestation, and passes); the
-// SHA-reuse-after-red resume case (and the rare push-then-attest race) needs one.
-function rerunGateReviewIfStale(branch, headSha) {
-  const runs = ghJson([
-    'run', 'list', '--workflow', 'gate-review.yml', '--branch', branch,
-    '--json', 'databaseId,headSha,status,conclusion', '--limit', '15',
-  ]);
-  const id = pickStaleGateReviewRun(runs, headSha);
-  if (id == null) return false;
-  console.log(`  ci-land: re-running the stale gate-review check (run ${id}) so it re-reads the gate-author-trust attestation...`);
-  return ghArgvOk(['run', 'rerun', String(id)]);
-}
-
-// ciLandLocal — today's local path: this machine pushes the branch + opens the PR
-// + enables auto-merge via git + gh. async since task 1169 — it asks the server to
-// post the gate-author-trust attestation between the push and the PR open.
-async function ciLandLocal(taskId, branch, valueSummary) {
-  const headSha = gitOk('git rev-parse HEAD');
-
-  console.log(`  pushing ${branch} to origin...`);
-  if (!gitArgvOk(['push', 'origin', branch])) {
-    console.log('  ci-land: push failed; task stays at confirmed. Fix the push and re-ship.');
-    return landBailed(`could not push ${branch} to origin`, `node scripts/gds/ship.js ${taskId}`);
-  }
-
-  // task 1169 (ADR 0058): attest the author's trust tier on the head SHA BEFORE
-  // opening the PR, so the gate-review check reads it on its first (and only) run
-  // and a Metic+ gate-surface PR auto-passes — race-free for a fresh PR, since the
-  // `gh pr create` below is what fires gate-review and it runs only after this
-  // returns. (A reused open PR is handled by the re-run nudge after auto-merge.)
-  await attestGateTrust(taskId, headSha);
-
-  // Ensure exactly one PR for this branch. gh pr create is idempotent-ish: it
-  // errors if a PR already exists, so check first and reuse it.
-  const existing = ghJson(['pr', 'view', branch, '--json', 'number,url,state']);
-  // Reusing an already-open PR means gate-review may have ALREADY run (red, before
-  // the attestation existed) on this same head SHA — nudge a re-run below.
-  const reusingOpenPr = !!(existing && existing.state === 'OPEN');
-  // PR titles + bodies are GitHub-rendered: a bare "#NNN" autolinks into
-  // 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 ` +
-    `${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...');
-    if (!ghArgvOk(buildPrCreateArgv(branch, title, body))) {
-      console.log('  ci-land: `gh pr create` failed. Is the GitHub CLI installed + authenticated (`gh auth status`)? Open the PR manually; task stays at confirmed.');
-      return landBailed('`gh pr create` failed (is gh installed + authenticated?)', `node scripts/gds/ship.js ${taskId}`);
-    }
-  } else {
-    console.log(`  ci-land: reusing open PR ${existing.url}`);
-  }
-
-  console.log('  ci-land: enabling auto-merge (lands when required checks pass)...');
-  // task 1718: an enable-failure is NOT a dead-end — the PR is open and the server
-  // still lands green PRs. Don't return false (which stranded the builder at
-  // 'confirmed' with no in-session SHIPPED banner); fall through to the server poll,
-  // which drives + observes the land. See landPollAfterAutoMerge.
-  const autoMergeArmed = ghArgvOk(buildPrMergeArgv(branch));
-  if (!autoMergeArmed) {
-    console.log('  ci-land: GitHub auto-merge could not be armed from here (normal when shipping from a worktree, or with branch protection off). The PR is open; the server lands it — waiting for the land instead of stranding at confirmed...');
-  }
-
-  // task 1169: if we REUSED an open PR, a stale red gate-review run may sit on this
-  // same head SHA from before the attestation existed; a new commit status does not
-  // re-trigger a pull_request check, so re-run it (best-effort). A freshly-opened PR
-  // is left alone — its single gate-review run reads the attestation and passes.
-  if (reusingOpenPr) rerunGateReviewIfStale(branch, headSha);
-
-  // enable-success watches GitHub directly; enable-failure drives + watches the
-  // server land (publish-status reconcile-on-read). Both flip to 'shipped' on a real
-  // land, so the banner renders in-session and no 'confirmed' breadcrumb is written.
-  return landPollAfterAutoMerge(autoMergeArmed) === 'ci'
-    ? pollCiDeploy(taskId, branch, headSha)
-    : pollServerPublish(taskId, branch);
-}
-
-// Confirm the CI land actually reached production. Polls in stages:
-//   1. PR state -> MERGED (checks passing + branch protection satisfied); grabs
-//      the merge commit oid.
-//   2. the deploy-prod workflow run for that commit -> success.
-//   3. public edge healthz -> 200 (belt-and-braces, a different vantage).
-// Times out conservatively; on any timeout the task stays at confirmed with a
-// precise next step rather than a false "shipped".
-function pollCiDeploy(taskId, branch, headSha) {
-  const MERGE_TRIES = 30; // ~5 min at 10s — checks + auto-merge
-  const DEPLOY_TRIES = 24; // ~4 min at 10s — Actions deploy
-
-  console.log('  ci-land: waiting for auto-merge (checks + branch protection)...');
-  let mergeSha = null;
-  for (let i = 0; i < MERGE_TRIES; i++) {
-    const pr = ghJson(['pr', 'view', branch, '--json', 'state,mergeCommit']);
-    if (pr && pr.state === 'MERGED') {
-      mergeSha = pr.mergeCommit && pr.mergeCommit.oid;
-      break;
-    }
-    if (pr && pr.state === 'CLOSED') {
-      console.log(`  ci-land: PR was CLOSED without merging (a required check failed, or it was closed manually). Fix it and re-run \`node scripts/gds/ship.js ${taskId}\` to resume. Task stays at 'confirmed'.`);
-      return landBailed('the PR was closed without merging (a check failed, or it was closed manually)', `node scripts/gds/ship.js ${taskId}`);
-    }
-    shellOk(POLL_SLEEP_CMD);
-  }
-  if (!mergeSha) {
-    // task 1049: PR open + auto-merge armed but not merged in-window = the publish
-    // SUCCEEDED and is still in CI — success-pending, not a failure.
-    printLandPending(taskId);
-    return landPending();
-  }
-  console.log(`  ci-land: merged to main (${mergeSha.slice(0, 8)}). Waiting for the prod deploy...`);
-
-  for (let i = 0; i < DEPLOY_TRIES; i++) {
-    const runs = ghJson([
-      'run', 'list', '--workflow', 'deploy-prod.yml', '--branch', 'main',
-      '--json', 'headSha,status,conclusion', '--limit', '15',
-    ]);
-    if (deployRunSucceeded(runs, mergeSha)) {
-      console.log('  ci-land: deploy-prod workflow succeeded for the merge commit.');
-      // Commit-pin the confirmation against /version (#858) — stronger than a
-      // liveness probe. The deploy run succeeding for OUR mergeSha is already
-      // authoritative, so /version only refines the message (and never turns a
-      // 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 (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.');
-      }
-      return landed();
-    }
-    shellOk(POLL_SLEEP_CMD);
-  }
-  // task 1049: merged but the deploy run hasn't confirmed in-window — still
-  // success-pending (it deploys on its own), not a failure.
-  printLandPending(taskId, { merged: true });
-  return landPending();
-}
-
-// ---------- Step 0: preflight (working tree + branch freshness) ----------
-//
-// Catches the 2026-05-10 "phantom ship" bug: builder forgot to stage/commit
-// their actual work. The committed-diff scanner reported clean (because nothing
-// was committed), smoke passed, and the task auto-shipped with zero code
-// change. The fix is to inspect the working tree BEFORE the claim resolves and
-// refuse to proceed when any tracked file has uncommitted/staged changes.
-//
-// 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
-  // proves the builder's work is actually committed. touches[] cleanup [2/8]
-  // (task 877): this replaced the old touches[]-scoped match, which was skipped
-  // entirely for empty-touches tasks (leaving them unprotected). The plain
-  // clean-tree check is strictly stronger and needs no touches[]. Untracked /
-  // .gitignored files are ignored so autonomous scratch files don't false-refuse.
-  const porcelain = gitOk('git status --porcelain');
-  const dirty = trackedDirty(porcelain);
-  if (dirty.length > 0) {
-    console.log('  preflight: working tree has uncommitted tracked changes:');
-    for (const file of dirty) console.log(`    - ${file}`);
-    console.log('');
-    console.log('  Stage + commit these (or revert them) before shipping.');
-    console.log('  This guard exists because uncommitted work has shipped as "complete" before.');
-    return { ok: false, reason: 'working-tree-dirty' };
-  }
-
-  // (b) Branch-freshness check — refuse if behind origin/main by too much.
-  // Fetch quietly so the comparison is against current remote state. Clean
-  // macOS Finder/iCloud `* 2` duplicate refs first or fetch will fail with
-  // "bad object refs/heads/<name> 2".
-  const cleaned = cleanupMacFinderDupRefs(REPO_ROOT);
-  if (cleaned.length > 0) {
-    console.log(`  preflight: removed ${cleaned.length} stray refs (macOS Finder duplicates)`);
-  }
-  gitOk('git fetch origin main');
-  const behindStr = gitOk('git rev-list --count HEAD..origin/main');
-  const behind = behindStr ? Number(behindStr) : 0;
-  if (Number.isFinite(behind) && behind > 0) {
-    // (b) Branch-freshness is REPORT-ONLY now (#1068). Being behind origin/main
-    // is no longer a refusal: shipMain() merges origin/main INTO the branch up
-    // front (mergeMainIntoBranch), BEFORE the sandbox review gate, so the tree
-    // the human reviews == the tree we ship — killing the post-approval re-stage
-    // loop the #1057 retro hit. We still fetch (above) so that merge + the
-    // stale-tooling guard below see current remote state.
-    const note = behind > BEHIND_MAIN_LIMIT ? ` (well past the ${BEHIND_MAIN_LIMIT}-commit mark)` : '';
-    console.log(`  preflight: branch is ${behind} commit(s) behind origin/main${note} — shipMain merges it in before staging.`);
-  }
-
-  // (c) Stale ship-tooling guard. The behind-limit above is deliberately lenient
-  // so an unrelated commit to main doesn't block every parallel builder — but
-  // that means a branch a FEW commits behind sails through, and if those commits
-  // touched the ship/grade tooling, the builder runs a STALE ship.js / grader.js
-  // / smoke runner and the ship silently fails the same way every time. That was
-  // the #662 root cause (a grader.js predating the Windows spawn fix ran twice).
-  // So: regardless of commit count, refuse if origin/main carries changes to the
-  // tooling that runs the ship locally and this branch lacks them. Three-dot diff
-  // (HEAD...origin/main) scopes to changes on the origin/main side since the
-  // merge-base, so the builder's OWN edits to these files (e.g. shipping a
-  // ship.js fix) do not trip it.
-  const TOOLING_PATHS = [
-    'scripts/gds/ship.js',
-    'scripts/gds/smoke-gds.js',
-    'scripts/gds/cli-lib.js',
-    'modules/grading/grader.js', // BV1.R73: grading carved to modules/grading/
-  ];
-  const staleToolingStr = gitOk(`git diff --name-only HEAD...origin/main -- ${TOOLING_PATHS.join(' ')}`);
-  const staleTooling = staleToolingStr ? staleToolingStr.trim().split('\n').filter(Boolean) : [];
-  if (staleTooling.length > 0) {
-    if (opts.force) {
-      console.log(`  preflight: ship tooling is behind origin/main (${staleTooling.join(', ')}) — proceeding due to --force`);
-    } else {
-      console.log('  preflight: your ship/grade tooling is behind origin/main:');
-      for (const f of staleTooling) console.log(`    - ${f}`);
-      console.log('  These files RUN the ship + grader locally — shipping with a stale copy silently fails (root cause of #662).');
-      console.log('  Run `git merge origin/main` (or `git pull --rebase origin main`) on this branch, then re-ship. Or --force to override.');
-      return { ok: false, reason: 'stale-tooling' };
-    }
-  }
-
-  // (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 };
-}
-
-// mergeMainIntoBranch — pull origin/main INTO the current feature branch BEFORE
-// the sandbox review gate (#1068, gap 2), so the tree the human reviews == the
-// tree we ship and an --approved lands in ONE shot. This subsumes the old
-// behind-main hard refusal: instead of telling the builder to merge by hand
-// (which then invalidated their just-given sandbox approval — the #1057 retro),
-// we do it up front. Aborts ONLY on a genuine merge conflict (the human must
-// resolve those); a no-op when already current or not on a feature branch. Runs
-// in the session's worktree (currentBranch()/gitOk operate on process.cwd()).
-// Returns { ok, merged, conflict?, reason? }.
-// decidePreMerge — the PURE policy for the pre-stage merge: skip on main/detached
-// HEAD, on the server-publish path, or when already current; otherwise merge.
-// Exported so the truth table is unit-tested with no git. `via` is pushVia()'s
-// verdict ('server' | 'local' | undefined). Returns { action:'skip'|'merge', reason }.
-function decidePreMerge({ branch, behind, via }) {
-  if (!branch || branch === 'main' || branch === 'HEAD') {
-    return { action: 'skip', reason: `not on a feature branch (${branch})` };
-  }
-  // Server-mediated publish (ADR 0055): a credential-less partial-clone dev box
-  // (blob:none, HTTPS origin, no gh/credential-helper — ADR 0053) CANNOT run a
-  // local `git merge origin/main` — the ort merge lazily fetches main's blobs
-  // from the promisor remote and there are no credentials to authenticate that
-  // fetch, so the box strands here and can never ship while behind main, i.e.
-  // ≈always (idea #364). It also does not NEED to: ciLandServer bundles
-  // `origin/main..HEAD` and the SERVER reconciles the branch with the real main
-  // when it pushes + opens + auto-merges the PR; a genuine conflict surfaces
-  // server-side as merge_conflict (publish-reconciler / conflict-resolve,
-  // ADR 0082). The local pre-merge (#1068) is a LAPTOP-path optimization (so the
-  // sandbox-reviewed tree == the shipped tree); it stays exactly as-is there
-  // (via 'local'/undefined) and is simply skipped on the box.
-  if (via === 'server') {
-    return {
-      action: 'skip',
-      reason: 'server-mediated publish reconciles with origin/main server-side (credential-less partial-clone box cannot fetch main blobs locally — idea #364)',
-    };
-  }
-  if (!Number.isFinite(behind) || behind === 0) {
-    return { action: 'skip', reason: 'already up to date with origin/main' };
-  }
-  return { action: 'merge', reason: `${behind} commit(s) behind origin/main` };
-}
-
-function mergeMainIntoBranch() {
-  const branch = currentBranch();
-  // preflight already fetched origin/main + cleaned stray refs; reuse that state.
-  const behindStr = gitOk('git rev-list --count HEAD..origin/main');
-  const behind = behindStr ? Number(behindStr) : 0;
-  const decision = decidePreMerge({ branch, behind, via: pushVia() });
-  if (decision.action === 'skip') {
-    return { ok: true, merged: false, reason: decision.reason };
-  }
-  console.log(`  pre-stage: merging origin/main into ${branch} (${behind} commit(s) behind) so the reviewed tree == the shipped tree...`);
-  const msg = `Merge origin/main into ${branch} (pre-stage freshness, task 1068)`;
-  if (gitArgvOk(['merge', '--no-edit', '-m', msg, 'origin/main'])) {
-    console.log('  pre-stage: merged origin/main cleanly.');
-    return { ok: true, merged: true };
-  }
-  // Conflict (or other merge failure). Before giving up, AUTO-HEAL conflicts that
-  // are confined to GENERATED files (task 1243): docs/repo-map.md + the nested
-  // CLAUDE.md blocks reliably collide between parallel branches (they're rebuilt
-  // from code, so two branches render them differently), and re-resolving them by
-  // hand — three times — was the PR #167 churn. Regenerate them from the merged
-  // tree, stage, and complete the merge. This is the guaranteed-to-run safety net
-  // that backstops the `otb-regen` git merge driver (install-git-hooks.js), which
-  // only fires where it's been registered per-clone.
-  const conflicted = (gitOk('git diff --name-only --diff-filter=U') || '').trim();
-  const files = conflicted ? conflicted.split('\n').map((s) => s.trim()).filter(Boolean) : [];
-  if (files.length && files.every((f) => mergeRegen.REGENERABLE.has(f))) {
-    const healed = files.every((f) => mergeRegen.resolveInWorktree(f));
-    if (healed && gitArgvOk(['add', ...files]) && gitArgvOk(['commit', '--no-edit'])) {
-      console.log(`  pre-stage: auto-healed generated-file conflict(s) by regenerating ${files.join(', ')} from the merged tree.`);
-      return { ok: true, merged: true, healed: files };
-    }
-    // A hand-written conflict remained (resolveInWorktree returned false) or the
-    // commit failed — fall through to the clean abort below; no half-merged tree.
-  }
-  // Abort so the tree is left clean, and surface it — we must NOT ship a
-  // half-merged tree.
-  gitArgvOk(['merge', '--abort']);
-  return {
-    ok: false,
-    merged: false,
-    conflict: true,
-    reason: conflicted
-      ? `merge conflict with origin/main in: ${files.join(', ')}. Resolve on this branch (git merge origin/main), commit, then re-ship`
-      : 'could not merge origin/main into this branch (see git output). Resolve manually, then re-ship',
-  };
-}
-
-// ---------- Pre-verify: auto-linkify the ship's own changed docs ----------
-//
-// The doc-ref-linkify CI gate (tests/linkify_check.mjs, in the required `unit`
-// check — task 1002639; a standalone doc-ref-linkify.yml workflow never
-// actually existed) red-Xes a PR carrying a bare "#NNN" task ref in a doc. A
-// red-X after the builder walked away still strands the land (#747).
-//
-// The structural cure is to fix the ship's OWN changed docs here, before the
-// merge, and commit the rewrite. The gate then stays as the backstop for refs
-// that arrive by other paths (generated docs, direct pushes) but stops firing
-// in the normal /builder-ship path.
-//
-// Scope is deliberately the docs already in THIS commit's diff: rewriting only
-// files the builder already changed means it can NEVER rewrite a doc they
-// didn't touch, and a pre-existing bare ref elsewhere is left for
-// the periodic backlog sweep (`linkify-refs.js --apply`) + the CI gate.
-
-// Pure: which changed paths are in the linkifier's domain (the hand-authored
-// markdown a reader sees on github.com — root CLAUDE.md/README.md + docs/**).
-// Mirrors linkify-refs.js discoverDocs() roots. Exported for unit tests.
-function isLinkifiableDocPath(rel) {
-  return (
-    typeof rel === 'string' &&
-    rel.endsWith('.md') &&
-    (rel === 'CLAUDE.md' || rel === 'README.md' || rel.startsWith('docs/'))
-  );
-}
-
-function autoLinkifyChangedDocs(ac) {
-  const baseline = computeGraderBaseline(ac);
-  let docs = computeChangedFiles(baseline).filter(isLinkifiableDocPath);
-  // Mirror discoverDocs()'s GENERATED-FILE skip — an explicit file set bypasses
-  // it, and rewriting a generated doc just churns until its next regen.
-  docs = docs.filter((rel) => {
-    try {
-      const head = fs.readFileSync(path.resolve(process.cwd(), rel), 'utf8').slice(0, 200);
-      return !/GENERATED FILE/i.test(head);
-    } catch (_) {
-      return false;
-    }
-  });
-  if (docs.length === 0) return;
-
-  console.log(`Auto-linkify: scanning ${docs.length} changed doc(s) for bare "#NNN" task refs...`);
-  const linkifyScript = path.resolve(__dirname, 'linkify-refs.js');
-  try {
-    // --apply (no --check) throws on an unreachable id allow-list; treat any
-    // failure as best-effort and continue — the CI gate is the backstop, a
-    // network blip must never block a ship.
-    execFileSync(process.execPath, [linkifyScript, '--apply', ...docs], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      cwd: process.cwd(),
-    });
-  } catch (err) {
-    const line = (err.message || 'unknown error').split('\n')[0];
-    console.log(`  auto-linkify: skipped (linkifier unavailable: ${line}). CI gate remains the backstop.`);
-    return;
-  }
-
-  // Commit only if the rewrite actually changed something. status --porcelain
-  // over the explicit doc set, via argv (paths can't be spliced into a shell).
-  const dirty = gitOk(`git status --porcelain -- ${docs.map((d) => JSON.stringify(d)).join(' ')}`);
-  if (!dirty) {
-    console.log('  auto-linkify: changed docs already clean — nothing to commit.');
-    return;
-  }
-  gitArgvOk(['add', '--', ...docs]);
-  const committed = gitArgvOk(['commit', '-m', 'chore(docs): auto-linkify task refs before ship (task 747)']);
-  if (committed) {
-    const n = dirty.split('\n').filter(Boolean).length;
-    console.log(`  auto-linkify: rewrote bare task refs in ${n} doc(s) and committed before merge.`);
-  } else {
-    console.log('  auto-linkify: commit failed; continuing (CI gate is the backstop).');
-  }
-}
-
-// ---------- Step 1+2: local verification ----------
-
-// V3.R18 (#209) → MAS Phase 1 #395: inputs for the subagent grader. The grader
-// needs three things from the local working tree: the changed files list, the
-// 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.)
-// 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') ||
-    (claim && claim.head_sha) ||
-    null
-  );
-}
-
-function computeChangedFiles(baseline) {
-  if (!baseline) return [];
-  const out = gitOk(`git diff --name-only ${baseline}...HEAD`);
-  return out ? out.split('\n').map((s) => s.trim()).filter(Boolean) : [];
-}
-
-function computeDiffText(baseline) {
-  if (!baseline) return '';
-  // -M to track renames; --no-color so the subagent gets clean diff lines.
-  const diff = gitOk(`git diff --no-color -M ${baseline}...HEAD`);
-  if (!diff) return '';
-  if (diff.length > GRADER_DIFF_CHAR_CAP) {
-    const head = diff.slice(0, GRADER_DIFF_CHAR_CAP);
-    return `${head}\n\n[diff truncated — original was ${diff.length} chars, capped at ${GRADER_DIFF_CHAR_CAP}. The subagent can Read any file in its post-resolve state for the full picture.]`;
-  }
-  return diff;
-}
-
-function computeDiffShortstat(baseline) {
-  if (!baseline) return null;
-  const summary = gitOk(`git diff --shortstat ${baseline}...HEAD`);
-  if (!summary) return { files_changed: 0, lines_added: 0, lines_removed: 0 };
-  const files = /(\d+)\s+files?\s+changed/.exec(summary);
-  const ins = /(\d+)\s+insertions?\(\+\)/.exec(summary);
-  const del = /(\d+)\s+deletions?\(-\)/.exec(summary);
-  return {
-    files_changed: files ? Number(files[1]) : 0,
-    lines_added:   ins   ? Number(ins[1])   : 0,
-    lines_removed: del   ? Number(del[1])   : 0,
-  };
-}
-
-// ---------- V4.R08 — diff fingerprint + grade reuse ----------
-
-// SHA-256 of the raw diff string. Stable identifier for "has the committed
-// diff changed?" — used as the key to skip re-running the adversarial panel
-// when the diff is byte-for-byte identical to the last PASS.
-function diffHash(rawDiff) {
-  return crypto.createHash('sha256').update(rawDiff || '').digest('hex');
-}
-
-// Compute the hash of the full (untruncated) diff against baseline. Returns
-// null when baseline is unavailable so callers can treat null as "unknown".
-function computeRawDiffHash(baseline) {
-  if (!baseline) return null;
-  const raw = gitOk(`git diff --no-color -M ${baseline}...HEAD`);
-  return diffHash(raw || '');
-}
-
-// Pure predicate: should we reuse the stored grade instead of running the
-// panel again? True when a PASS grade exists for the exact same diff hash.
-// A null storedGrade, a non-PASS grade, or a hash mismatch all return false.
-function shouldReuseGrade(storedGrade, currentDiffHash) {
-  if (!storedGrade || !storedGrade.passed) return false;
-  if (!storedGrade.diff_hash || !currentDiffHash) return false;
-  return storedGrade.diff_hash === currentDiffHash;
-}
-
-// task 1002660: task_grades has no issues column — the panel's deduped
-// issues[] survive only inside signals.workers[].issues. Rebuild them (same
-// (file, summary) dedupe as aggregatePanel) so the reuse re-POST carries the
-// substance the original PASS carried. Before this, the reused body posted
-// issues: undefined, so every reused PASS with findings read as a zero-issue
-// pass server-side and tripped the SR-9 plausibility guard into
-// manual-confirm — 0/106 successful uses, the feature defeated itself.
-function reconstructPanelIssues(signals) {
-  const out = [];
-  const seen = new Set();
-  for (const w of (Array.isArray(signals?.workers) ? signals.workers : [])) {
-    for (const it of (Array.isArray(w?.issues) ? w.issues : [])) {
-      if (!it || typeof it !== 'object') continue;
-      const key = `${it.file || ''}|${it.summary || ''}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      out.push(it);
-    }
-  }
-  return out;
-}
-
-// --- Subagent grader runner ---
-// Wraps grader.gradeSubagent so ship.js callers see a single function with
-// progress logging. MAS Phase 2.0 #410: gradeSubagent now runs the WORKER
-// PANEL (Narc + Quality; Hacker / Efficiency Monger added in 2.1/2.2) in
-// parallel. Each worker is a specialized prompt with its own verdict; the
-// panel gate is unanimous PASS — any 'fail' blocks, any 'concerns' falls
-// through to manual-confirm.
-async function runSubagentGrader({ task, valueSummary, baseline, changedFiles: precomputedChanged, priorRound = null }) {
-  // Reuse the caller's changed-files list when provided (the empty-diff guard
-  // computes it just before calling us) so we don't run `git diff --name-only`
-  // twice per ship (#513).
-  const changedFiles = precomputedChanged || computeChangedFiles(baseline);
-  const diff = computeDiffText(baseline);
-  const shortstat = computeDiffShortstat(baseline);
-  // SEC #863: feed the grader the builder's LIVE rank so the deterministic
-  // permission-path pre-pass can hard-fail a sub-Metic diff that touches the
-  // rank/permission/ship-grade/deploy machinery. Best-effort read; if it fails
-  // the pre-pass fails OPEN (the pre-push hook + post-push main audit are the
-  // fail-closed layers).
-  let builderRank;
-  try {
-    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 = {
-    timeoutMs: GRADER_TIMEOUT_MS,
-    cwd: process.cwd(), // grade the FEATURE worktree, not REPO_ROOT
-  };
-  // task 1002659: the real session model (transcript-derived) drives the
-  // cross-model grader pick; null → the grader assumes, as before.
-  const builderModel = resolveBuilderModel();
-  const t0 = Date.now();
-  let result;
-  // #513: a small copy/docs-only diff gets a SINGLE generalist grader shot
-  // rather than the full adversarial panel — "lighter, not skipped". The 1-shot
-  // still returns ff+cq+economy+confidence so the server gate applies; the
-  // deterministic scanner + smoke + route-rank checks ran regardless. Fixes the
-  // inefficiency of running a 4-worker panel on a +1/-1 copy tweak.
-  if (grader.isTrivialDiff({ changedFiles, diffStats: shortstat })) {
-    const totalLines = (shortstat.lines_added || 0) + (shortstat.lines_removed || 0);
-    console.log(`  subagent grader ${grader.VERSION}: TRIVIAL diff (${shortstat.files_changed} file(s), ${totalLines} line(s), copy/docs only) → single generalist shot, model=${grader.selectGraderModel({ builderModel })} — instead of the ${grader.WORKERS.DEFAULT_PANEL.length}-worker panel (#513)`);
-    console.log(`  gate: the shot must return functional_fidelity>=${grader.THRESHOLD} AND code_quality>=${grader.THRESHOLD} AND confidence>=0.4`);
-    result = await grader.gradeSubagentV3MultiShot({
-      task,
-      valueSummary,
-      diff,
-      changedFiles,
-      diffStats: shortstat,
-      shots: 1,
-      builderModel, // task 1002659: real session model → cross-model grader pick
-      runOpts,
-    });
-    // task 1002660: the single generalist shot has no Hacker or Efficiency
-    // lens — acceptable for genuinely inert copy/docs files, but never
-    // silently. The marker makes the dropped lenses queryable by /grade-audit
-    // (same pattern as implausible_pass_waived, ADR 0164).
-    result.signals = {
-      ...(result.signals || {}),
-      trivial_path: true,
-      lenses_dropped: ['hacker', 'efficiency'],
-    };
-  } else {
-    const panel = grader.WORKERS.DEFAULT_PANEL;
-    console.log(`  subagent grader ${grader.VERSION}: panel of ${panel.length} workers (${panel.join(', ')}), model=${grader.selectGraderModel({ builderModel })} (builder ${builderModel || `${grader.ASSUMED_BUILDER_MODEL} assumed`}), changed_files=${changedFiles.length}, diff_chars=${diff.length}, per-worker timeout=${GRADER_TIMEOUT_MS}ms`);
-    console.log(`  gate: every worker must return verdict='pass'; 'concerns' → manual-confirm fall-through; 'fail' blocks`);
-    if (priorRound) {
-      console.log(`  delta re-grade (task 1002662): prior round's findings + builder response ride along, fenced; answered findings can only re-veto with NEW evidence`);
-    }
-    result = await grader.gradeSubagent({
-      task,
-      valueSummary,
-      diff,
-      changedFiles,
-      diffStats: shortstat, // V3.R92 #353: feed diff size into the economy axis
-      builderRank,          // SEC #863: drives the permission-path pre-pass
-      builderModel,         // task 1002659: real session model → cross-model grader pick
-      priorRound,           // task 1002662: delta-aware re-grade context (panel path only)
-      runOpts,
-    });
-  }
-  const wallMs = Date.now() - t0;
-  // Decorate signals with the local shortstat — useful in audit-trail.
-  // graded_head_sha (task 1002662): record WHAT commit this grade judged, so a
-  // later --regrade can compute the interim fix diff (prior graded HEAD → now)
-  // for the delta-aware prior-round payload.
-  result.signals = {
-    ...(result.signals || {}),
-    diff_stats: shortstat,
-    wall_ms: wallMs,
-    changed_files_count: changedFiles.length,
-    graded_head_sha: gitOk('git rev-parse HEAD') || null,
-  };
-  return result;
-}
-
-function runSmoke() {
-  // `cwd: REPO_ROOT` + a relative script path is robust to spaces or other
-  // shell metacharacters that may appear in the absolute repo path on some
-  // machines.
-  const okPms = shellOk(`"${process.execPath}" scripts/gds/smoke-gds.js`, { cwd: REPO_ROOT });
-  return { ran: true, clean: okPms };
-}
-
-// task 1002660: the async twin of runSmoke for the PRE-RESOLVE gate only. The
-// sync runSmoke blocks the event loop (execSync), which would freeze the
-// overlapped grade-panel promise mid-flight; awaiting this one keeps the loop
-// free so the panel's subprocess callbacks progress while smoke runs. The
-// post-merge smoke call keeps the sync form (nothing overlaps there).
-function runSmokeAsync() {
-  return new Promise((resolve) => {
-    const child = spawn(process.execPath, ['scripts/gds/smoke-gds.js'], {
-      cwd: REPO_ROOT, stdio: 'inherit', windowsHide: true,
-    });
-    child.on('error', () => resolve({ ran: true, clean: false }));
-    child.on('close', (code) => resolve({ ran: true, clean: code === 0 }));
-  });
-}
-
-// ---------- Step 3: merge + deploy chain ----------
-
-function currentBranch() {
-  return gitOk('git rev-parse --abbrev-ref HEAD');
-}
-
-// Task #357: keep the 3 mechanical onboarding diagrams current on every deploy.
-// Regenerate them from live facts; if any changed, commit the refresh on this
-// branch so it ships with the deploy. Non-fatal — a render/network hiccup must
-// never block a ship; the diagram-drift routine will flag any miss.
-//
-// Returns a status string ('skipped-server' | 'regen-failed' | 'current' |
-// 'committed' | 'committed-nofatal') so the regression test (task 1046) can
-// prove the dev-box skip without git or a headless browser.
-function regenerateDiagrams() {
-  // task 1046: on the server-mediated-publish path (a dev box — pushVia 'server'),
-  // there is no headless browser, so render-diagrams.sh fails and gen-diagrams.js
-  // exits non-zero AFTER writing the regenerated .mmd + assertions.json — which
-  // shellOk() then treats as a failed regen and returns BEFORE the commit below,
-  // leaving those files UNCOMMITTED in the builder's tree (had to be reverted by
-  // hand). The box must not attempt the regen at all: skip here and let a
-  // render-capable ship (the laptop path, which CAN render the PNGs) refresh them
-  // as a matched .mmd+.png+assertions set; the diagram-drift routine backstops any
-  // staleness in the meantime. Skipping entirely (vs --no-render) avoids committing
-  // a .mmd/.png mismatch to main. Mirrors gen-diagrams.js's own non-fatal skip when
-  // bash itself is absent (ENOENT).
-  if (pushVia() === 'server') {
-    console.log('  diagram regen skipped on the dev-box ship path (no GDS session for the conceptual diagrams) — a full-clone ship refreshes the .mmd; drift checker backstops staleness');
-    return 'skipped-server';
-  }
-  // ADR 0110 pt.3 (task 2027): the .svg/.png RENDERS are now gitignored and
-  // regenerated at deploy (deploy-prod.sh) — no longer committed here — so ship
-  // only refreshes the TRACKED sources. Run gen-diagrams with --no-render: it
-  // rewrites the mechanical .mmd + assertions.json from live facts WITHOUT
-  // invoking the headless-Chromium render, which is why this no longer needs a
-  // render-capable machine. The gitignored .svg/.png never appear in the git add
-  // below (a directory add silently skips ignored paths).
-  console.log('  regenerating onboarding diagram SOURCES from live facts (--no-render; renders are a deploy artifact, ADR 0110 pt.3)...');
-  // process.execPath (quoted) instead of bare `node`: on Windows cmd.exe can't
-  // resolve a bare `node` without a full PATH, the same failure #660 fixed for
-  // the smoke-gds spawn. The quotes survive spaces in a Windows install path
-  // (e.g. C:\Program Files\nodejs\node.exe).
-  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-diagrams.js'))} --no-render`)) {
-    console.log('  diagram regen failed (non-fatal) — drift checker will flag any staleness');
-    return 'regen-failed';
-  }
-  const dirty = gitOk('git status --porcelain docs/onboarding/diagrams');
-  if (!dirty) {
-    console.log('  diagram sources already current — nothing to commit');
-    return 'current';
-  }
-  shellOk('git add docs/onboarding/diagrams');
-  if (shellOk('git commit -m "chore(diagrams): auto-regenerate diagram sources from live facts (task 357)"')) {
-    console.log('  committed auto-regenerated diagrams');
-    return 'committed';
-  }
-  return 'committed-nofatal';
-}
-
-// task 1224 (Path B / ADR 0063): refresh the generated symbol skeleton from the shipped tree so the
-// altitude map can't drift. Pure JS (no headless browser, no render) — unlike the diagrams it is safe
-// on EVERY ship path, including the dev-box server-publish path. Non-fatal: a hiccup must never block
-// a ship. ADR 0110 (task 1926): docs/repo-map.md is now GITIGNORED + regenerated at deploy — the
-// generator still WRITES it (untracked, harmless), but ship commits ONLY the tracked nested-doc
-// blocks. It is deliberately absent from the git add/status lists below: `git add <ignored path>`
-// ABORTS the whole command (exit 1), which would drop the nested-block commit. The block bucket is
-// backstopped on main by fitness.js (`gen-repo-map --check-block`).
-function regenerateRepoMap() {
-  console.log('  regenerating code symbol skeleton (repo map + nested-doc blocks) from the shipped tree...');
-  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-repo-map.js'))}`)) {
-    console.log('  repo-map regen failed (non-fatal) — CI --check-block backstops the tracked blocks');
-    return 'regen-failed';
-  }
-  const dirty = gitOk('git status --porcelain src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md scripts/gds/CLAUDE.md');
-  if (!dirty) {
-    console.log('  nested-doc symbol blocks already current — nothing to commit (docs/repo-map.md is gitignored, ADR 0110)');
-    return 'current';
-  }
-  shellOk('git add src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md scripts/gds/CLAUDE.md');
-  if (shellOk('git commit -m "chore(repo-map): auto-regenerate nested-doc symbol blocks (task 1224)"')) {
-    console.log('  committed auto-regenerated nested-doc symbol blocks');
-    return 'committed';
-  }
-  return 'committed-nofatal';
-}
-
-// Refresh the generated session-log index (docs/session-log-index.md) + the bounded CLAUDE.md §13
-// "recent sessions" snippet from the shipped tree's docs/session-logs/*.md (ADR 0062 §8, task 1226).
-// Pure JS (reads files, no DB, no headless browser) — safe on EVERY ship path including the dev-box
-// server-publish path. Non-fatal: a hiccup must never block a ship; the Path-C CI gate
-// (`gen-session-index --check`) backstops staleness on main.
-// Refresh the generated API docs (docs/api/openapi.json + docs/api-reference.md +
-// docs/routes-permissions.md) from the shipped route tree (task 1918). Pure JS (reads
-// route files, no DB, no headless browser) — safe on EVERY ship path incl. the dev-box
-// server-publish path. Non-fatal: a hiccup must never block a ship; the fitness
-// `gen-api-docs --check` gate backstops staleness on main.
-function regenerateApiDocs() {
-  console.log('  regenerating OpenAPI spec + API reference from the shipped route tree...');
-  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-api-docs.js'))}`)) {
-    console.log('  api-docs regen failed (non-fatal) — CI --check backstops staleness');
-    return 'regen-failed';
-  }
-  const dirty = gitOk('git status --porcelain docs/api/openapi.json docs/api-reference.md docs/routes-permissions.md');
-  if (!dirty) {
-    console.log('  API docs already current — nothing to commit');
-    return 'current';
-  }
-  shellOk('git add docs/api/openapi.json docs/api-reference.md docs/routes-permissions.md');
-  if (shellOk('git commit -m "chore(api-docs): auto-regenerate OpenAPI spec + reference (task 1918)"')) {
-    console.log('  committed auto-regenerated API docs');
-    return 'committed';
-  }
-  return 'committed-nofatal';
-}
-
-// Refresh the generated typed client (clients/bongos-client) FROM the just-regenerated
-// spec, then keep the devbox vendored CJS copy in lockstep (task 2051). Runs right
-// after regenerateApiDocs so the client reflects the same route tree. Automatic here
-// (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'))}`)) {
-    console.log('  api-client regen failed (non-fatal) — CI api_client freshness test backstops staleness');
-    return 'regen-failed';
-  }
-  // 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 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 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 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 ${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';
-  }
-  return 'committed-nofatal';
-}
-
-// ADR 0110 (task 1926): docs/session-log-index.md is GITIGNORED + deploy-regenerated — the generator
-// still writes it (untracked), but ship commits ONLY the tracked CLAUDE.md §13 snippet. The index is
-// omitted from the git add/status lists (an explicit `git add` of an ignored path aborts the commit);
-// the tracked snippet is backstopped on main by fitness.js (`gen-session-index --check-block`).
-function regenerateSessionIndex() {
-  console.log('  regenerating session-log index + CLAUDE.md snippet from the shipped tree...');
-  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-session-index.js'))}`)) {
-    console.log('  session-index regen failed (non-fatal) — CI --check-block backstops the tracked snippet');
-    return 'regen-failed';
-  }
-  const dirty = gitOk('git status --porcelain CLAUDE.md');
-  if (!dirty) {
-    console.log('  CLAUDE.md §13 snippet already current — nothing to commit (docs/session-log-index.md is gitignored, ADR 0110)');
-    return 'current';
-  }
-  shellOk('git add CLAUDE.md');
-  if (shellOk('git commit -m "chore(session-log): auto-regenerate CLAUDE.md §13 snippet (task 1226)"')) {
-    console.log('  committed auto-regenerated CLAUDE.md §13 snippet');
-    return 'committed';
-  }
-  return 'committed-nofatal';
-}
-
-// Refresh the generated file-map sections (.claude/skills/ + .claude/scheduled-tasks/ trees in
-// docs/file-map.md) from what is on disk (ADR 0066, task 1276). Pure JS (reads dirs + the
-// docs/file-map.notes.json sidecar, no DB, no headless browser) — safe on EVERY ship path including
-// the dev-box server-publish path. Non-fatal: a hiccup must never block a ship; the Path-C CI gate
-// (`gen-file-map --check`, in fitness.js) backstops staleness on main. NB gen-file-map exits 2 when
-// a skill/routine has no note, so shellOk may report "failed" on a legit note-gap ship — that is
-// fine, we still commit whatever it wrote and CI surfaces the missing note.
-function regenerateFileMap() {
-  console.log('  regenerating file-map sections (skills + scheduled-tasks) from the shipped tree...');
-  shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-file-map.js'))}`);
-  const dirty = gitOk('git status --porcelain docs/file-map.md');
-  if (!dirty) {
-    console.log('  file-map already current — nothing to commit');
-    return 'current';
-  }
-  shellOk('git add docs/file-map.md');
-  if (shellOk('git commit -m "chore(file-map): auto-regenerate skills + scheduled-tasks sections (task 1276)"')) {
-    console.log('  committed auto-regenerated file-map sections');
-    return 'committed';
-  }
-  return 'committed-nofatal';
-}
-
-// ---------- merge serialization lock (#462 C4; extended in #269 C6) ----------
-//
-// autoMerge() mutates the SHARED main worktree (REPO_ROOT). Two concurrent
-// ships — or a ship racing a /merge-mode in another session — collide on that
-// single working tree. Observed 2026-05-30: a parallel session was mid-merge
-// in REPO_ROOT, so this ship's `git merge --ff-only` failed and it bailed with
-// the misleading "main is ahead of origin somehow".
-//
-// The lock primitives now live in src/bongos/merge-lock.js (V3.R50 / #269) so BOTH
-// ship.js AND the /merge-mode CLI take the SAME mutex — closing the
-// ship-vs-merge-mode and merge-mode-vs-merge-mode races that the in-ship.js
-// lock could not cover. See docs/recipes/multi-builder-merge.md.
-
-// REPO_ROOT must be on main, not mid-merge, and clean before we mutate it.
-// Returns a human reason string if busy, or null if safe to proceed.
-function mainWorktreeBusy() {
-  if (gitOk('git rev-parse -q --verify MERGE_HEAD', { cwd: REPO_ROOT })) {
-    return 'a merge is already in progress';
-  }
-  const dirty = gitOk('git status --porcelain', { cwd: REPO_ROOT });
-  if (dirty && dirty.trim().length > 0) {
-    return 'the working tree is dirty or has unmerged files';
-  }
-  return null;
-}
-
-// task 391 (idea #37): the verdict for a ship whose branch has no commits ahead
-// of main. Pure, so the gate is unit-tested.
-//   'has-commits' → normal path: there is a real diff to merge + deploy. (Also
-//                   the value when `git rev-list` failed/returned null — same as
-//                   the original `=== '0'` check, which only short-circuited an
-//                   exact '0'.)
-//   'db-only'     → zero commits + explicit --db-only: a deliberate direct-SQL
-//                   ship (work already live in the prod DB); short-circuit to shipped.
-//   'refuse'      → zero commits + NO --db-only: almost always a mistake
-//                   (uncommitted work / wrong branch / empty touches[]); refuse.
-function zeroCommitVerdict(commitsAhead, dbOnly) {
-  if (commitsAhead !== '0') return 'has-commits';
-  return dbOnly ? 'db-only' : 'refuse';
-}
-
-async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
-  const branch = currentBranch();
-  if (!branch || branch === 'main' || branch === 'HEAD') {
-    // task 1002723: an --allow-empty / --db-only ship legitimately runs FROM the
-    // main checkout (nothing was ever committed), but this bail fired BEFORE the
-    // deliberate-empty landing below could — the task parked at confirmed with no
-    // branch and no published tip, a shape the server sweep can never prove (the
-    // task-1002716 strand). Land it here iff the checkout has zero commits ahead
-    // of origin/main; anything else keeps the safe bail.
-    if (dbOnly && shellOk('git fetch origin main')
-        && zeroCommitVerdict(gitOk('git rev-list origin/main..HEAD --count'), true) === 'db-only') {
-      console.log('  auto-merge: deliberate empty ship (--db-only / --allow-empty) from the main checkout - nothing to merge; advancing to shipped without merge/deploy.');
-      return landed({ noArtifact: true, noArtifactReason: 'empty ship from the main checkout — no commits to merge' });
-    }
-    console.log(`  auto-merge: skipped (current branch is ${branch})`);
-    // The merge source IS the current branch, so on main there is nothing to
-    // merge. Half of the single-checkout catch-22 this task documents: the other
-    // half is the "main worktree is on <branch>, not main" bail below.
-    return landBailed(`nothing to merge — this checkout is on ${branch}, not a task branch`, '/merge-mode');
-  }
-
-  // Refresh the data-driven diagrams before computing commits-ahead, so a
-  // diagram-only refresh still counts as something to deploy.
-  regenerateDiagrams();
-  // Refresh the generated code symbol skeleton (Path B / task 1224) on the same beat.
-  regenerateRepoMap();
-  // Refresh the generated session-log index + the bounded CLAUDE.md §13 snippet (ADR 0062 §8 / task 1226).
-  regenerateSessionIndex();
-  // Refresh the generated file-map sections (skills + scheduled-tasks) on the same beat (ADR 0066 / task 1276).
-  regenerateFileMap();
-  // Refresh the generated OpenAPI spec + API reference from the shipped route tree (task 1918).
-  regenerateApiDocs();
-  // ...then the typed client FROM that spec (+ the devbox vendored copy) on the same beat (task 2051).
-  regenerateApiClient();
-
-  // Resolve the deploy mode ONCE (task 1093 / C9) — it reads config/deploy.json;
-  // reused at the fetch-bail check + the ci-land branch below.
-  const deployMode = resolveDeployMode();
-
-  // DB-only / no-op ship detection (task #219). Some legitimate ships have
-  // no commits to merge — e.g. a task whose work was a direct SQL write to
-  // the production DB. The change is already live; the merge step has
-  // nothing to push, merge, or deploy. Short-circuit so the caller's POST
-  // /tasks/:id/ship still flips status to shipped instead of stranding the
-  // task at confirmed forever.
-  // A credential-less dev box can't `git fetch origin main` (private origin, no
-  // creds — ADR 0053), but that's only fatal OFF the server-publish path: the
-  // box's ADR-0055 path bundles against its LOCAL origin/main and the server tops
-  // up main. Without this, the box dead-ends here and strands every ship at
-  // confirmed (task 1027). The `!fetchedMain &&` short-circuit keeps the gh-probe
-  // (pushVia) off the happy laptop path, so laptop behavior is byte-for-byte.
-  const fetchedMain = shellOk('git fetch origin main');
-  if (!fetchedMain && shouldBailOnFetchFailure(fetchedMain, deployMode, pushVia())) {
-    console.log('  auto-merge: fetch failed; task stays at confirmed for /merge-mode');
-    return landBailed('could not fetch origin/main', '/merge-mode');
-  }
-  const commitsAhead = gitOk('git rev-list origin/main..HEAD --count');
-  const verdict = zeroCommitVerdict(commitsAhead, dbOnly);
-  if (verdict === 'refuse') {
-    // task 391 (idea #37): the old code short-circuited ANY zero-commit branch
-    // straight to shipped — silently advancing a claim with empty/wrong touches[]
-    // or simply uncommitted work, awarding credit for no change. Now a zero-commit
-    // ship must be DELIBERATELY declared with --db-only. Fail-safe: the claim is
-    // already resolved by this point, so the task stays at confirmed and a plain
-    // re-run resumes the merge leg (task 941) once they commit or pass --db-only.
-    console.error('');
-    console.error('  Ship refused: no commits ahead of main, and --db-only was not passed.');
-    console.error('  A zero-commit ship is almost always a mistake (uncommitted work, wrong branch, or empty/incorrect touches[]).');
-    console.error('   • If you have local changes, commit them, then re-ship.');
-    console.error('   • If this is a DELIBERATE direct-SQL / DB-only ship (the work was a write straight to the prod');
-    console.error('     DB — nothing to merge or deploy), re-run with --db-only:');
-    console.error(`       node scripts/gds/ship.js ${taskId} --db-only`);
-    console.error('  The task stays at confirmed; nothing was merged or deployed.');
-    return landBailed('no commits ahead of main, and --db-only was not passed', `node scripts/gds/ship.js ${taskId} --db-only`);
-  }
-  if (verdict === 'db-only') {
-    console.log('  auto-merge: deliberate empty ship (--db-only / --allow-empty) - no commits ahead of main; advancing to shipped without merge/deploy.');
-    return landed({ noArtifact: true, noArtifactReason: 'empty ship — no commits ahead of main' });
-  }
-
-  // #679 / ADR 0042: in 'ci' deploy mode the operator's machine never merges or
-  // SSHes the droplet — ship lands via PR auto-merge and CI deploys. The laptop
-  // block below stays the default ('laptop' mode) so this is inert until the
-  // deliberate cutover. The DB-only short-circuit above is shared by both modes.
-  if (deployMode === 'ci') {
-    return await ciLand(taskId, branch, valueSummary);
-  }
-
-  console.log(`  pushing ${branch} to origin...`);
-  if (!gitArgvOk(['push', 'origin', branch])) {
-    console.log('  auto-merge: push failed; task stays at confirmed for /merge-mode');
-    return landBailed(`could not push ${branch} to origin`, '/merge-mode');
-  }
-
-  // Serialize the shared-main-worktree merge (#462 C4; #269 C6). Concurrent
-  // ships AND manual /merge-mode runs queue on this one lock; if a live holder
-  // is still merging past the wait window we bail cleanly to /merge-mode rather
-  // than racing its working tree.
-  if (!mergeLock.acquire(REPO_ROOT)) {
-    console.log('  auto-merge: another active ship or /merge-mode run holds the merge lock; task stays at confirmed for /merge-mode');
-    return landBailed('another ship or /merge-mode run holds the merge lock', '/merge-mode');
-  }
-  let mergedClean = false;
-  try {
-    // Never touch REPO_ROOT if a parallel session left it mid-merge or dirty —
-    // this is the exact collision that previously bailed with the misleading
-    // "main is ahead of origin somehow" (#462).
-    const busy = mainWorktreeBusy();
-    if (busy) {
-      console.log(`  auto-merge: main worktree busy (${busy}); task stays at confirmed for /merge-mode`);
-      return landBailed(`the main worktree is busy (${busy})`, '/merge-mode');
-    }
-
-    console.log(`  switching to main worktree (${REPO_ROOT}) for merge...`);
-    // Same cleanup as preflight: drop macOS Finder/iCloud `* 2` ref duplicates
-    // before fetching, otherwise `git fetch origin` fails with "bad object
-    // refs/heads/<name> 2" and the auto-merge bails. Was a recurring 2026-05-10
-    // failure mode — every ship of the day hit this and required /merge-mode.
-    const dupRefs = cleanupMacFinderDupRefs(REPO_ROOT);
-    if (dupRefs.length > 0) {
-      console.log(`  auto-merge: removed ${dupRefs.length} stray refs (macOS Finder duplicates)`);
-    }
-    if (!shellOk(`git fetch origin`, { cwd: REPO_ROOT })) {
-      console.log('  auto-merge: fetch failed; task stays at confirmed for /merge-mode');
-      return landBailed('could not fetch origin in the main worktree', '/merge-mode');
-    }
-
-    // The main worktree must currently have main checked out.
-    const onMain = gitOk('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT });
-    if (onMain !== 'main') {
-      console.log(`  auto-merge: main worktree is on ${onMain}, not main; task stays at confirmed`);
-      // The other half of the single-checkout catch-22: the merge target tree is
-      // the one holding the feature branch, so there is nowhere to merge INTO.
-      // Name the cure, not just the symptom — this is the bail that used to be
-      // invisible behind "landing automatically".
-      return landBailed(
-        `the main checkout is on ${onMain}, not main — work a task in its own worktree so the main checkout stays on main`,
-        '/merge-mode',
-      );
-    }
-
-    if (!gitArgvOk(['merge', '--ff-only', 'origin/main'], { cwd: REPO_ROOT })) {
-      console.log('  auto-merge: main is ahead of origin somehow; task stays at confirmed');
-      return landBailed('the local main is ahead of origin/main', '/merge-mode');
-    }
-
-    // #681: build the merge argv and run it WITHOUT a shell. valueSummary is
-    // DB-sourced (untrusted) — passing it as a literal argv element means
-    // `$(...)`/backticks in it can never be interpreted as a command.
-    if (!gitArgvOk(buildMergeArgv(branch, valueSummary), { cwd: REPO_ROOT })) {
-      console.log('  auto-merge: merge failed (conflicts?); task stays at confirmed for manual /merge-mode');
-      return landBailed(`merging ${branch} into main failed (conflicts?)`, '/merge-mode');
-    }
-
-    console.log('  smoke against post-merge state...');
-    if (!runSmoke().clean) {
-      console.log('  auto-merge: post-merge smoke failed; task stays at confirmed; investigate');
-      return landBailed('post-merge smoke tests failed', '/merge-mode');
-    }
-
-    console.log('  pushing merged main to origin...');
-    // SEC #863: route through push-main.js, which carries the
-    // OTB_ALLOW_MAIN_PUSH override so the pre-push permission gate lets THIS
-    // graded+confirmed pipeline push through while still blocking ad-hoc
-    // `git push origin main`. process.execPath (quoted) for the same
-    // cross-platform reason as the other node spawns here (#660).
-    if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'push-main.js'))}`, { cwd: REPO_ROOT })) {
-      console.log('  auto-merge: push failed; task stays at confirmed');
-      // task 1002629: a branch-protected main refuses EVERY direct push, so
-      // retrying here can never work — resolveDeployMode normally reroutes to
-      // the ci PR path before this point; reaching this with protection on
-      // means an env-forced 'laptop' or a failed protection probe.
-      if (mainIsProtected() === true) {
-        return landBailed('main is branch-protected — the direct push can never land; unset OTB_DEPLOY_MODE (the ci PR path lands it)', `node scripts/gds/ship.js ${taskId}`);
-      }
-      return landBailed('could not push the merged main to origin', '/merge-mode');
-    }
-
-    // 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 landBailed('merged to main, but the deploy failed (/healthz never returned 200)', '/merge-mode');
-          }
-        } else {
-          console.log('  auto-merge: ~/deploy.sh returned non-zero and no healthzUrl configured to re-probe; task stays at confirmed');
-          return landBailed('merged to main, but ~/deploy.sh returned non-zero (no healthz to re-probe)', '/merge-mode');
-        }
-      }
-    }
-
-    // Merged + deployed — the feature branch is permanently in main's history
-    // (--no-ff merge commit) and no longer needed on origin. Deleting it keeps
-    // GitHub's "Create PR" affordance from offering empty PRs against zero-diff
-    // branches and prevents builder confusion about whether a branch landed.
-    // Local refs/heads ref stays so the worktree on the Mac isn't disturbed
-    // (cleanup of stale local refs happens next `git fetch --prune`).
-    // Non-blocking: a deploy that succeeded shouldn't be marked failed just
-    // because the cleanup push fails (e.g. branch already deleted manually,
-    // permission glitch, network blip).
-    console.log(`  cleaning up: deleting ${branch} on origin...`);
-    if (!gitArgvOk(['push', 'origin', '--delete', branch], { cwd: REPO_ROOT })) {
-      console.log(`  warn: could not delete origin/${branch} — may already be gone (non-blocking)`);
-    }
-
-    console.log('  flipping task to shipped...');
-    mergedClean = true;
-    return landed();
-  } finally {
-    // Leave REPO_ROOT clean for the NEXT ship/merge no matter how we exited.
-    // A failed merge here wedges everyone else: a conflict leaves the tree
-    // mid-merge (MERGE_HEAD + conflicted index → mainWorktreeBusy() rejects all
-    // future ships), and a failure AFTER the local merge commit but BEFORE push
-    // (post-merge smoke/push/deploy) leaves main ahead-but-unpushed (the next
-    // `git merge --ff-only origin/main` then fails with the misleading "main is
-    // ahead of origin somehow"). Only normalize on the failure path — on the
-    // success path we already pushed, so touching the tree is needless risk.
-    // Best-effort: cleanup must never mask the real outcome. This is the
-    // clean-failure twin of merge-lock.recoverWorktree() (which handles the
-    // crash/stale-reclaim case where we never reach this finally at all).
-    if (!mergedClean) {
-      try {
-        if (gitOk('git rev-parse -q --verify MERGE_HEAD', { cwd: REPO_ROOT })) {
-          shellOk('git merge --abort', { cwd: REPO_ROOT });
-        }
-        if (gitOk('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT }) === 'main') {
-          shellOk('git reset --hard origin/main', { cwd: REPO_ROOT });
-        }
-      } catch (_) {
-        /* best-effort cleanup; the lock release below is what matters most */
-      }
-    }
-    mergeLock.release(REPO_ROOT);
-  }
-}
-
-// ---------- Shared grade-step helpers (used by shipMain AND regradeMain) ----------
-//
-// #678: the grade step is factored out of shipMain so the `--regrade` recovery
-// path can reuse it verbatim instead of replicating ~50 lines (the trap that
-// learning #43 warned about — "runSubagentGrader in ship.js is NOT exported, so
-// replicate its ~10 lines"). These helpers are behavior-preserving lifts of the
-// inline blocks shipMain used before; both paths now share one implementation.
-
-// Map a grader result into the POST /tasks/:id/grade request body. Forwards the
-// advisory sub-scores (economy/security/efficiency) only when present so the
-// server's validateAndScore re-records them (back-compat: omitted when null).
-function buildGradePayload(gradeResult, committedFiles = null) {
-  return {
-    // touches[] cleanup [3/8] (task 878): pass the real committed changed-files
-    // so the server keys the shipper badges off the diff, not touches[].
-    ...(Array.isArray(committedFiles) && committedFiles.length > 0
-      ? { committed_files: committedFiles }
-      : {}),
-    subagent_output: {
-      functional_fidelity: gradeResult.rubric_scores?.functional_fidelity,
-      code_quality: gradeResult.rubric_scores?.code_quality,
-      ...(gradeResult.rubric_scores?.economy != null
-        ? { economy: gradeResult.rubric_scores.economy }
-        : {}),
-      ...(gradeResult.rubric_scores?.security_score != null
-        ? { security_score: gradeResult.rubric_scores.security_score }
-        : {}),
-      ...(gradeResult.rubric_scores?.efficiency_score != null
-        ? { efficiency_score: gradeResult.rubric_scores.efficiency_score }
-        : {}),
-      notes_md: gradeResult.notes_md,
-      confidence: gradeResult.signals?.confidence ?? null,
-      issues: gradeResult.issues,
-    },
-    signals: gradeResult.signals,
-  };
-}
-
-// Log the grader panel's own API spend (#486 / ADR 0028 path 1). Best-effort +
-// idempotent on (source, source_ref): a cost-log failure must never block a
-// ship/re-grade, and re-grading at the same HEAD is a no-op.
-async function logGraderPanelCost(taskId, gradeResult) {
-  const panelCostUsd = Number(gradeResult.panel_cost_usd) || 0;
-  if (panelCostUsd <= 0) return;
-  const headSha = gitOk('git rev-parse --short HEAD') || 'nohead';
-  const costPost = await (await cliClient()).cost.postCost({
-    body: {
-      task_id: Number(taskId),
-      amount_usd: panelCostUsd,
-      category: 'api',
-      source: 'grader',
-      source_ref: `grade-${taskId}-${headSha}`,
-      description: `grader panel (${gradeResult.grader_kind || 'subagent'}) on #${taskId}`,
-    },
-  });
-  // An idempotent conflict returns HTTP 200 {skipped:true} (cost.js), so
-  // costPost.ok is TRUE on a skip — check `skipped` first.
-  if (costPost.data && costPost.data.skipped) {
-    console.log(`  grader cost already logged for ${headSha} (idempotent skip)`);
-  } else if (costPost.ok) {
-    console.log(`  grader cost logged: $${panelCostUsd.toFixed(4)} → cost_log (category=api, source=grader)`);
-  } else {
-    console.log(`  grader cost log skipped (non-fatal): HTTP ${costPost.status}`);
-  }
-}
-
-// task 1002662: assemble the delta-aware prior-round context for a --regrade.
-// Pure (no git/network) so the payload shape is unit-tested. Returns null when
-// there is no prior grade worth being delta-aware of; otherwise:
-//   forPanel — { round, findings_md, response_md, interim_md } for the worker
-//              prompts (fenced as untrusted by the shared scaffold);
-//   audit    — the compact regrade block recorded into the new grade's signals
-//              so grade_attempts rounds read as remediation history (the
-//              task-1002661 reader consumes this).
-const PRIOR_ROUND_TEXT_CAP = 4000;
-function buildPriorRoundContext({ storedGrade, responseText = '', interimCommits = '', interimDiffStat = '' }) {
-  if (!storedGrade || typeof storedGrade !== 'object') return null;
-  const issues = Array.isArray(storedGrade.issues) ? storedGrade.issues : [];
-  const notes = typeof storedGrade.notes_md === 'string' ? storedGrade.notes_md.trim() : '';
-  if (issues.length === 0 && !notes) return null;
-  const verdictLine = `Prior verdict: ${storedGrade.passed ? 'PASS' : 'FAIL'} · score ${storedGrade.score ?? '?'}/10 · ${issues.length} finding(s)`;
-  const findingLines = issues.map((it) => `- [${it.severity || '?'}] ${it.worker || 'panel'} · ${it.file || '?'} — ${it.summary || ''}`);
-  const findings_md = [
-    verdictLine,
-    '',
-    ...(findingLines.length ? findingLines : ['(no per-finding rows — see the prior notes below)']),
-    ...(notes ? ['', 'Prior panel notes:', notes.slice(0, PRIOR_ROUND_TEXT_CAP)] : []),
-  ].join('\n');
-  const interimParts = [];
-  if (interimCommits) interimParts.push('Interim commits since the prior grade:', String(interimCommits).slice(0, PRIOR_ROUND_TEXT_CAP));
-  if (interimDiffStat) interimParts.push('', 'Interim diffstat:', String(interimDiffStat).slice(0, PRIOR_ROUND_TEXT_CAP));
-  const response = String(responseText || '').trim();
-  // Round numbering is self-consistent across regrades: the first grade is
-  // round 1; each regrade reads the prior signals.regrade.round when present.
-  const round = (Number(storedGrade.signals?.regrade?.round) || 1) + 1;
-  return {
-    forPanel: {
-      round,
-      findings_md,
-      response_md: response ? response.slice(0, PRIOR_ROUND_TEXT_CAP) : null,
-      interim_md: interimParts.length ? interimParts.join('\n') : null,
-    },
-    audit: {
-      round,
-      prior_passed: storedGrade.passed === true,
-      prior_score: storedGrade.score ?? null,
-      prior_findings_count: issues.length,
-      response_present: Boolean(response),
-      interim_present: Boolean(interimCommits || interimDiffStat),
-    },
-  };
-}
-
-// Run the subagent grader against the committed diff, POST the result to the
-// rank-open /tasks/:id/grade endpoint, and log the panel cost on success.
-// Returns the raw apiCall response so the caller can branch on .ok / read the
-// grade. Shared by the ship path and the --regrade path.
-//
-// V4.R08: before spawning the adversarial panel we compute the raw diff hash
-// and check whether a stored PASS grade exists for the same hash. On a match
-// we re-POST the stored grade (marking it reused in signals) and skip the
-// panel entirely — cheap re-ships with an unchanged diff stay fast.
-// task 1002660: the COMPUTE half — the reuse lookup + the panel run. No server
-// writes, so shipMain can start it before the smoke gate and overlap the
-// multi-minute panel with smoke + the claim resolve. Returns
-// { kind: 'reuse', currentHash, reusedResult } | { kind: 'fresh', currentHash, gradeResult }.
-async function computeGradeResult({ taskId, task, summary, baseline, committedFiles, priorRound = null }) {
-  // Compute the fingerprint of the raw (untruncated) diff so we can compare
-  // against any stored grade, independent of the display-truncation cap.
-  const currentHash = computeRawDiffHash(baseline);
-
-  if (currentHash) {
-    const storedGradeRes = await (await cliClient()).tasks.getTasksId({ id: taskId, query: { include: 'grade' } });
-    const storedGrade = storedGradeRes.ok ? (storedGradeRes.data.grade ?? null) : null;
-
-    if (shouldReuseGrade(storedGrade, currentHash)) {
-      console.log('  Grade reuse: stored PASS grade matches current diff hash — skipping panel.');
-      // Reuse the stored result with a reused marker so the audit trail is
-      // complete. We keep the original grader_kind and inject reuse metadata
-      // into signals so a bare table scan can spot reused grades.
-      const reusedSignals = {
-        ...(storedGrade.signals || {}),
-        reused_from_diff_hash: storedGrade.diff_hash,
-        reused_at: new Date().toISOString(),
-      };
-      const reusedResult = {
-        passed:        storedGrade.passed,
-        score:         storedGrade.score,
-        threshold:     storedGrade.threshold,
-        grader_kind:   storedGrade.grader_kind,
-        grader_version: storedGrade.grader_version,
-        rubric_scores: storedGrade.rubric_scores,
-        notes_md:      storedGrade.notes_md,
-        signals:       reusedSignals,
-        // task 1002660: carry the original panel's issues (rebuilt from
-        // signals.workers[].issues — the row stores them nowhere else) so the
-        // reused PASS stands on the same substance/evidence it passed with.
-        issues:        reconstructPanelIssues(storedGrade.signals),
-      };
-      return { kind: 'reuse', currentHash, reusedResult };
-    }
-  }
-
-  const gradeResult = await runSubagentGrader({
-    task,
-    valueSummary: summary,
-    baseline,
-    changedFiles: committedFiles,
-    priorRound: priorRound?.forPanel ?? null,
-  });
-  // task 1002662: record the regrade audit block on the new grade's signals so
-  // this round is readable as remediation history (grade_attempts keeps one row
-  // per round; the latest grade's signals.regrade names what it responded to).
-  if (priorRound?.audit) {
-    gradeResult.signals = { ...(gradeResult.signals || {}), regrade: priorRound.audit };
-  }
-  return { kind: 'fresh', currentHash, gradeResult };
-}
-
-// The RECORD half: POST the computed grade + log the panel cost. `precomputed`
-// (a promise from computeGradeResult, task 1002660) lets the ship path hand in
-// the overlapped computation; the --regrade path passes nothing and computes
-// inline — behavior identical to the pre-split gradeAndRecord either way.
-async function gradeAndRecord({ taskId, task, summary, baseline, committedFiles, priorRound = null, precomputed = null }) {
-  const computed = await (precomputed
-    || computeGradeResult({ taskId, task, summary, baseline, committedFiles, priorRound }));
-
-  if (computed.kind === 'reuse') {
-    const payload = { ...buildGradePayload(computed.reusedResult, committedFiles), diff_hash: computed.currentHash };
-    return (await cliClient()).tasks.postTasksIdGrade({ id: taskId, body: payload });
-    // No logGraderPanelCost — the panel didn't run, there's no cost to log.
-  }
-
-  const { gradeResult } = computed;
-  const payload = { ...buildGradePayload(gradeResult, committedFiles), diff_hash: computed.currentHash ?? undefined };
-  const gradePost = await (await cliClient()).tasks.postTasksIdGrade({ id: taskId, body: payload });
-  // Log the panel's cost once the grade is recorded — independent of the
-  // pass/fail VERDICT (the panel ran, and cost money, either way), but only
-  // when the POST itself succeeded (a failed POST means nothing was recorded).
-  if (gradePost.ok) await logGraderPanelCost(taskId, gradeResult);
-  return gradePost;
-}
-
-// Build the grade verdict display block as a string (per-axis scores + notes +
-// issues + next-step hints). Pure + exported so the #943 grader-unavailable vs
-// FAIL branch is unit-tested without capturing stdout. printGradeOutcome just
-// prints what this returns.
-function formatGradeOutcome(g, taskId) {
-  const out = [];
-  // #943: a TOTAL grader outage (every gating worker failed to spawn / the
-  // grader was bypassed pre-spawn) is NOT a quality rejection — it's "the grader
-  // could not run". Present it distinctly so a worker-infra failure never reaches
-  // the builder as a misleading "FAIL · 0/10 — fix the issues" (the session-1659
-  // false-FAIL). There are no issues to fix; the path forward is re-grade when the
-  // grader is reachable, or manual-confirm.
-  if (g.signals?.panel_outcome === 'unavailable') {
-    const reason = g.signals?.grader_unavailable_reason;
-    out.push('');
-    out.push(`Subagent grade: GRADER UNAVAILABLE${reason ? ` (${reason})` : ''}  ·  no quality signal produced — NOT a quality rejection`);
-    if (g.notes_md) out.push(g.notes_md.split('\n').map((l) => '  ' + l).join('\n'));
-    out.push('');
-    out.push('The grader could not run (infra/outage/bypass) — there are no findings to fix. Task stays at completed.');
-    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>" ${resolveInstanceBase() || '<instance-origin>'}/api/gds/tasks/${taskId}/confirm`);
-    return out.join('\n');
-  }
-
-  // task 1002614 (map P-2): a protected-path refusal used to render as an
-  // ordinary quality FAIL — "fix the issues and --regrade" — although no rank of
-  // the builder's can land that diff. Present it as the authorization wall it is
-  // (the #943 grader-unavailable branch is the precedent for a distinct shape).
-  // Keyed off the guard name so it also reads grades from servers predating the
-  // authorization_refusal marker.
-  const guardTripped = g.signals?.server_guard?.tripped || [];
-  const permRefusal = g.signals?.server_guard?.authorization_refusal === true
-    || guardTripped.some((t) => t.guard === 'permission_path');
-  if (!g.passed && permRefusal) {
-    out.push('');
-    out.push('Subagent grade: REFUSED (authorization)  ·  not a quality verdict — your work was not judged and rejected');
-    out.push('');
-    out.push('The committed diff touches PROTECTED surfaces above your rank, so the server');
-    out.push('refused to accept it — no re-attempt at your rank can land this diff as-is.');
-    if ((g.issues || []).length > 0) {
-      out.push('');
-      out.push('What was refused (file · rule):');
-      for (const it of g.issues.filter((i) => String(i.worker || '').includes('permission-path'))) {
-        out.push(`  ${it.file || '?'} — ${it.summary || ''}`);
-      }
-    }
-    out.push('');
-    out.push('Ways forward:');
-    out.push('  - Split the protected files out of your diff and re-ship the rest, or');
-    out.push('  - hand this task to a builder at/above the floor the refusal names.');
-    out.push(`(--regrade re-runs the same server check and will refuse again unless the diff changes.)`);
-    return out.join('\n');
-  }
-
-  const verdict = g.passed ? 'PASS' : 'FAIL';
-  out.push('');
-  out.push(`Subagent grade: ${verdict}  ·  blended ${g.score}/10  ·  threshold ${g.threshold} (both axes)`);
-  if (g.rubric_scores) {
-    const ff = g.rubric_scores.functional_fidelity;
-    const cq = g.rubric_scores.code_quality;
-    if (ff != null) out.push(`  functional_fidelity: ${ff}/10`);
-    if (cq != null) out.push(`  code_quality:        ${cq}/10`);
-  }
-  if (g.notes_md) out.push(g.notes_md.split('\n').map((l) => '  ' + l).join('\n'));
-  if ((g.issues || []).length > 0) {
-    out.push('');
-    out.push(`Issues (${g.issues.length}):`);
-    for (const it of g.issues) {
-      const sev = String(it.severity || '?').padEnd(7);
-      out.push(`  [${sev}] ${it.file || '?'} — ${it.summary || ''}`);
-    }
-  }
-  if (!g.passed) {
-    out.push('');
-    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>" ${resolveInstanceBase() || '<instance-origin>'}/api/gds/tasks/${taskId}/confirm`);
-  }
-  return out.join('\n');
-}
-
-// Print the grade verdict + per-axis scores + notes + issues. On a FAIL, print
-// both the re-grade hint (the cheap default) and the Archon override curl (the
-// last resort — see feedback_prefer_regrade_over_override). #943: a total grader
-// outage prints as "GRADER UNAVAILABLE", not a 0/10 FAIL — see formatGradeOutcome.
-function printGradeOutcome(g, taskId) {
-  console.log(formatGradeOutcome(g, taskId));
-}
-
-// Print the credits line + multiplier breakdown + idea bonus + unlocked
-// achievements from a grade/confirm response.
-function printCreditsAndAchievements({ postGradeStatus, credits, creditsRaw, creditsMultiplier, ideaBonusInfo, justUnlocked }) {
-  console.log('');
-  if (postGradeStatus === 'completed') {
-    console.log(`Credits awarded: ${credits} (none — task at completed, grade not passed)`);
-  } else if (postGradeStatus === '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}`);
-  }
-  // Write the credits flag so the NEXT Claude turn plays the credits-awarded
-  // sound via the Stop hook (task 582). Only when credits were actually awarded.
-  if (typeof credits === 'number' && credits > 0) {
-    const tmpDir = process.platform === 'win32'
-      ? (process.env.TEMP || process.env.TMP || os.tmpdir()) : '/tmp';
-    try { fs.writeFileSync(require('path').join(tmpDir, 'otb-credits'), ''); } catch (_) {}
-  }
-  if (creditsRaw != null && creditsMultiplier != null && Number(creditsMultiplier) !== 1.0) {
-    const mult = Number(creditsMultiplier).toFixed(2).replace(/0$/, '').replace(/\.$/, '.0');
-    console.log(`  Kind multiplier: ${creditsRaw}c × ${mult}× → ${credits}c`);
-  }
-  if (ideaBonusInfo && ideaBonusInfo.ideaBonusAwarded > 0) {
-    console.log(
-      `  Idea-promotion bonus: +${ideaBonusInfo.ideaBonusAwarded}c paid to builder #${ideaBonusInfo.bonusBuilderId} (idea #${ideaBonusInfo.ideaId})`
-    );
-  }
-  for (const ach of justUnlocked || []) {
-    const bonus = ach.credit_bonus > 0 ? ` (+${ach.credit_bonus}c bonus)` : '';
-    console.log(`✨ Achievement unlocked: ${ach.name}${bonus}`);
-  }
-}
-
-// chooseBroadcastTargets — the ship-broadcast channel router (task 990) now lives
-// in src/bongos/ship-broadcast.js (task 1045) so the server-mediated publish path
-// shares the exact same security-sensitive routing. Imported at the top of this
-// file; still re-exported below for tests/ship_broadcast_routing.mjs.
-
-// task 1442: play the task-shipped "ship bell". ship.js runs as its own process
-// (not inside a Claude turn), so it plays the sound directly rather than via the
-// Stop hook. Called at the confirmed/shipped success milestone so it rings on
-// the ci/async landing path too — there ship.js exits at 'confirmed' and the
-// deploy finishes later server-side, which is exactly why the old post-deploy
-// call site never fired (bug #1442). Resolve the builder's chosen variant from
-// the local prefs file; fall back to 'ship'. Best-effort: playSound swallows all
-// errors and is a silent no-op with no audio player, so this can never fail a ship.
-function playShipBell() {
-  let shipWav = 'ship';
-  try {
-    const prefsPath = require('path').join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
-    const raw = require('fs').readFileSync(prefsPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    const ev = parsed && parsed.event_sounds && parsed.event_sounds['task-shipped'];
-    if (typeof ev === 'string') shipWav = ev;
-  } catch (_) { /* fall through to default */ }
-  playSound(shipWav);
-}
-
-// task 1002809: normalize an API error body across BOTH wire shapes — the live
-// ADR 0116 (R01) envelope `{ error: { code, message } }` and the legacy flat
-// `{ error: 'code' }`. Same normalization as claim.js:formatClaimFailure and
-// cli-lib:isBoxScope; pure + exported for tests/ship_post_land_verify.mjs.
-function normalizeApiError(data) {
-  const errRaw = data ? data.error : undefined;
-  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
-  return {
-    code: isEnvelope ? errRaw.code : errRaw,
-    message: isEnvelope ? errRaw.message : undefined,
-    // task 1002789: `details` is where the envelope carries the structured
-    // payload the flat shape used to put at the TOP level (claimWorktree,
-    // step/reason, floors). A site that reads `data.<field>` directly is
-    // reading a field that moved. Fall back to the body so a legacy flat
-    // response still resolves.
-    details: (isEnvelope && errRaw.details && typeof errRaw.details === 'object')
-      ? errRaw.details
-      : (data && typeof data === 'object' ? data : {}),
-  };
-}
-
-// task 1002789: the ONE renderer for a failed API call on the ship path.
-// Every generic bail site used to hand the raw body to console.error (or
-// interpolate `data.error` into a template, which stringifies the ADR 0116
-// envelope object to the literal "[object Object]"). Both hide a fully
-// diagnosable server error: console.error's util.inspect stops at depth 2, so
-// the `details` that names WHICH git step failed prints as "[Object]".
-// Collapse the body to one readable line instead, whichever shape it is.
-// Pure + exported for tests/ship_error_shape.mjs.
-function apiErrorLine(data, status) {
-  const { code, message, details } = normalizeApiError(data);
-  const head = code
-    ? (message && message !== code ? `${code}: ${message}` : code)
-    : (message || (status ? `HTTP ${status}` : 'unknown error'));
-  // Only the small scalar fields — a details blob can carry a whole bundle.
-  const extras = Object.entries(details || {})
-    .filter(([k, v]) => k !== 'code' && k !== 'message' && k !== 'error'
-      && (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'))
-    .map(([k, v]) => `${k}: ${String(v).replace(/\s+/g, ' ').trim()}`);
-  const line = extras.length ? `${head} (${extras.join('; ')})` : head;
-  return status ? `${line} [HTTP ${status}]` : line;
-}
-
-// task 1002809: classify a FAILED post-land POST /tasks/<id>/ship. The merge
-// already succeeded, so the server may simply have landed the task first
-// (reconcile-on-read — task 1049 — or the ~5-min reconciler racing this call).
-// The old check compared `data.error === 'task_not_confirmed'` — dead against
-// the envelope shape, so the already-landed SUCCESS rendered as a failure with
-// an "[object Object]" reason (the HANDOFF-apex-ui "400 after a successful
-// land" gotcha). liveStatus is the task's status from a verify GET (null when
-// that GET itself failed): 'shipped' is authoritative success whatever the
-// error said; task_not_confirmed with no live status keeps the task-1049
-// benefit of the doubt; any KNOWN non-shipped status stays a loud failure.
-// Pure + exported for tests/ship_post_land_verify.mjs.
-function postLandShipOutcome({ code, liveStatus }) {
-  if (liveStatus === 'shipped') {
-    return { alreadyShipped: true, why: 'the server landed it first — the failed ship call lost that race, nothing to fix' };
-  }
-  if (liveStatus == null && code === 'task_not_confirmed') {
-    return { alreadyShipped: true, why: 'the server reconciled it from the merged PR' };
-  }
-  return { alreadyShipped: false };
-}
-
-// Step 3 of the lifecycle: confirmed → shipped. Merge the branch into main,
-// deploy, flip the task to shipped, and fire the Discord broadcast (only when
-// the change actually deploys — #94 / ADR 0032; best-effort). Side-effecting;
-// the early returns are control flow only.
-async function mergeAndDeploy({ taskId, summary, advanceToMerge, skipMerge, dbOnly = false }) {
-  if (advanceToMerge && skipMerge) {
-    console.log('');
-    console.log('--no-merge: stopping at confirmed. Run /merge-mode later to land it.');
-    return landBailed('--no-merge was passed, so the land was skipped', '/merge-mode');
-  }
-  // Grade failed: the card renders the 'failed' stage ('not deployed'), so there
-  // is no land outcome to report.
-  if (!advanceToMerge) return null;
-
-  console.log('');
-  console.log('Auto-merge chain (confirmed → shipped):');
-  const merged = await autoMerge(taskId, summary, { dbOnly });
-  // NOTE: `merged` is an OBJECT now — every value is truthy, so this MUST test
-  // .ok. A bare `if (!merged)` would fall through on a bail and POST /ship for a
-  // task that never landed.
-  if (!merged.ok) return merged;
-
-  const shipBody = merged.noArtifact ? { no_artifact: true, no_artifact_reason: merged.noArtifactReason || 'deliberate empty ship (--db-only)' } : {}; // ADR 0184
-  const ship = await (await cliClient()).tasks.postTasksIdShip({ id: taskId, body: shipBody });
-  if (!ship.ok) {
-    // task 1049 / 1002809: the server may have already flipped this task to
-    // shipped (reconcile-on-read, or the reconciler racing this call). Verify
-    // the LIVE status before treating the refusal as a failure — the old
-    // flat-shape string check never matched the R01 envelope, so this success
-    // path was dead and every reconciled land reported as a failed ship.
-    const { code, message } = normalizeApiError(ship.data);
-    let liveStatus = null;
-    try {
-      const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
-      if (t.ok && t.data && t.data.task) liveStatus = t.data.task.status;
-    } catch (_) { /* verify is best-effort; fall back to the code-based call */ }
-    const outcome = postLandShipOutcome({ code, liveStatus });
-    if (outcome.alreadyShipped) {
-      console.log(`Task #${taskId} is now: shipped (${outcome.why}).`);
-    } else {
-      const e = message || code || `HTTP ${ship.status}`;
-      console.error(`  /tasks/${taskId}/ship failed: ${e}${liveStatus ? ` (task is at '${liveStatus}')` : ''}`);
-      // The merge itself succeeded — only the status flip failed, so a re-run
-      // resumes cleanly (task 941). Report it rather than letting the card claim
-      // the land is in progress.
-      return landBailed(`merged, but the ship call failed — ${e}`, `node scripts/gds/ship.js ${taskId}`);
-    }
-  } else {
-    console.log(`Task #${taskId} is now: shipped`);
-  }
-
-  // task 1442: the task-shipped bell used to play HERE, but this point is only
-  // reached on a SYNCHRONOUS merge+deploy. In ci/async landing mode (now the
-  // norm) ship.js exits at 'confirmed' and never gets here, so the bell never
-  // rang. It now plays at the confirmed/shipped success milestone via
-  // playShipBell() (finishShip + resumeMerge), which covers both paths.
-
-  // If the builder was promoted during this ship, write the promotion flag so
-  // the NEXT Claude turn plays the fanfare via the Stop hook.
-  const TMP_FLAGS = process.platform === 'win32'
-    ? (process.env.TEMP || process.env.TMP || os.tmpdir())
-    : '/tmp';
-  if (ship.data?.task?.graduatedTo) {
-    try { fs.writeFileSync(require('path').join(TMP_FLAGS, 'otb-promotion'), ''); } catch (_) {}
-    console.log(`  Rank promotion: ${ship.data.task.graduatedTo} — fanfare queued.`);
-  }
-
-
-  if (summary) {
-    // task 1749: the SERVER is now the SINGLE ship broadcaster. It emits
-    // task.shipped on the confirmed→shipped transition from every entry point
-    // (POST /ship, the publish-status reconcile-on-read, and the 5-min
-    // reconciler sweep — all idempotent via db.shipTask), and the discord
-    // module posts the #ship-feed line off that one event. This local post used
-    // to fire IN ADDITION to the server's, so a single ship announced FOUR
-    // messages (local #ship-news + #ship-feed, then the server's #ship-news +
-    // #ship-feed). Defer unconditionally so exactly one broadcast fires — from
-    // the server, after the deploy lands. (#ship-news itself is paused in
-    // chooseBroadcastTargets, so that one broadcast is the #ship-feed line —
-    // task 1749 / idea 458.) The security-sensitive fail-closed routing lives
-    // server-side in ship-broadcast.postShipBroadcast, so it is preserved.
-    console.log('  Discord broadcast: deferred to the server — it posts #ship-feed after the deploy lands.');
-  }
-  return merged;
-}
-
-// Memory + session-digest push, gated on a successful land (confirmed/shipped).
-// Both are best-effort — a failure here is a warning, never a ship failure.
-async function postShipSync(taskId, postGradeStatus) {
-  if (postGradeStatus !== 'confirmed' && postGradeStatus !== 'shipped') return null;
-  console.log('');
-  console.log('Memory sync (best-effort):');
-  await syncMemoryOnShip();
-  console.log('');
-  console.log('Session upload (best-effort):');
-  // task 1270: the upload returns { totalTokens, modelUsage } (or null) so the
-  // completion card can show Claude usage + an estimated cost.
-  return await uploadSessionOnShip(taskId);
-}
-
-// Post-ship onboarding nudge (V3.R13 #237). Best-effort — never let a stale /me
-// read make the script exit non-zero after a successful ship.
-async function onboardingNudgeBestEffort() {
-  try {
-    const meRes = noteServerReward(await (await cliClient()).me.getMe());
-    if (meRes.ok) {
-      console.log('');
-      printOnboardingNudge(meRes.data);
-    }
-  } catch (_) {
-    /* never block on a UX nudge */
-  }
-}
-
-// finishShip — the confirmed→shipped tail shared by shipMain + regradeMain (task
-// 1093 / C9): auto-merge + deploy, then the best-effort memory/session sync, the
-// Done line, and the onboarding nudge. Only this UNIFORM tail is shared;
-// printGradeOutcome + printCreditsAndAchievements stay caller-owned (their inputs
-// differ between the two paths). `doneLine` is a param so each caller keeps its
-// own wording ('Done.' vs the re-grade pass/fail message).
-// task 932 (Lars 2026-06-12): deterministic, no-LLM post-ship working-tree
-// close-out, folded into the delivery process (NOT a separate skill). After a
-// ship lands, scratch often lingers uncommitted — untracked files the preflight
-// lets through, generated artifacts, post-commit edits — making the session
-// hard to archive cleanly. This reports what's left and stashes it under a
-// labeled, RECOVERABLE stash so the tree is left clean + archive-ready and
-// nothing is lost. STRICTLY fail-open: the ship has already succeeded by the
-// time this runs, so nothing here may throw, prompt, or change the exit status —
-// a messy tree (or a stash failure) must never surface as a ship failure. The
-// caller gates this on a SUCCESSFUL land so a grade-failed 'completed' tree the
-// builder still needs to fix is never stashed out from under them.
-function postShipCloseout(taskId) {
-  try {
-    const out = gitOk('git status --porcelain');
-    if (out == null) return; // git unavailable / not a repo — nothing to reconcile
-    const plan = closeoutPlan(out, taskId);
-    if (plan.clean) {
-      console.log('Close-out: working tree clean — session is archive-ready.');
-      return;
-    }
-    console.log('');
-    console.log(`Close-out: ${plan.leftover.length} uncommitted/untracked path(s) remain after the ship:`);
-    for (const f of plan.leftover.slice(0, 15)) console.log(`  ${f}`);
-    if (plan.leftover.length > 15) console.log(`  … and ${plan.leftover.length - 15} more`);
-    // --include-untracked so scratch the preflight waved through is captured too.
-    // Label is `otb-postship-<numericId>` — no shell metacharacters.
-    const stashed = shellOk(`git stash push --include-untracked -m "${plan.stashLabel}"`);
-    if (stashed) {
-      console.log(`Close-out: stashed the leftover as "${plan.stashLabel}" — tree is now clean + archive-ready.`);
-      console.log('           Recover anytime:  git stash list  →  git stash pop');
-    } else {
-      console.log('Close-out: could not stash the leftover; left it in place (the ship already succeeded — tidy up manually when convenient).');
-    }
-  } catch (err) {
-    // Fail-open — a post-ship close-out problem must never look like a ship failure.
-    console.log(`Close-out: skipped (${err && err.message ? err.message : 'error'}).`);
-  }
-}
-
-async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine, card, dbOnly = false }) {
-  // task 1002541: the land outcome carries WHY a land didn't happen. Without it
-  // the card had only the status to go on and printed 'landing automatically'
-  // over a merge that had already bailed.
-  const land = await mergeAndDeploy({ taskId, summary, advanceToMerge, skipMerge, dbOnly });
-  // task 1719: mergeAndDeploy may have landed the task to 'shipped' IN-SESSION — the
-  // enable-success poll (pollCiDeploy) or, since task 1718, the enable-failure server
-  // poll (pollServerPublish). finishShip was handed postGradeStatus from the CONFIRM
-  // step ('confirmed'), so without re-reading it the completion card renders the stale
-  // 'confirmed — landing' banner AND printCompletionCard writes a pending-land
-  // breadcrumb — the SHIPPED banner then only appears on a LATER prompt, in whatever
-  // session is next (the owner-reported confusion). Re-fetch the authoritative status
-  // (exactly as resumeMerge does, task 1275) so a real in-session land shows the
-  // SHIPPED banner here and writes no breadcrumb. Best-effort: any read failure keeps
-  // today's behavior; the grade-fail path (advanceToMerge=false) never re-fetches.
-  let landedStatus = postGradeStatus;
-  if (advanceToMerge && (postGradeStatus === 'confirmed' || postGradeStatus === 'shipped')) {
-    try {
-      const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
-      const live = (t.ok && t.data && t.data.task) ? t.data.task.status : null;
-      landedStatus = reconciledCardStatus(live, postGradeStatus);
-    } catch (_) { /* keep postGradeStatus — the land above already awaited its outcome */ }
-  }
-  // Memory + session sync (#274 / 6D.1 / ADR 0027) — postShipSync itself gates on
-  // a successful land (confirmed/shipped); both legs are best-effort. It returns
-  // the session usage ({ totalTokens, modelUsage } | null) so the completion card
-  // can show Claude usage + an estimated cost (task 1270).
-  const usage = await postShipSync(taskId, landedStatus);
-  console.log('');
-  console.log(doneLine);
-  await onboardingNudgeBestEffort();
-  // task 1270: the ONE deterministic completion card — the same shape every ship.
-  // Replaces the agent's free-form prose recap (the builder-ship skill renders the
-  // rich in-feed card from the HTML this writes; the monospace card below is the
-  // always-printed fallback + the headless summary). Strictly best-effort.
-  // task 1719: pass the reconciled status so a just-landed ship shows SHIPPED (and
-  // writes no breadcrumb), not the stale pre-merge 'confirmed'.
-  await printCompletionCard({ taskId, postGradeStatus: landedStatus, card, usage, land });
-  // task 932: reconcile the working tree — ONLY on a successful land. A
-  // grade-failed ship stays at 'completed'; leave that tree untouched so the
-  // builder can fix findings + re-ship.
-  if (landedStatus === 'confirmed' || landedStatus === 'shipped') {
-    // task 1442: ring the ship bell at the success milestone. 'confirmed' counts —
-    // in ci/async mode the work is done + credited here and the deploy lands later
-    // server-side, so this is the moment the builder experiences as "shipped".
-    playShipBell();
-    postShipCloseout(taskId);
-  }
-}
-
-// task 1275: sum the committed diffstat (added/removed lines) over baseline...HEAD.
-// Shared by the completion card and the in-review card. Best-effort: returns
-// nulls when there's no baseline or git is unavailable.
-function diffstatFor(baseline) {
-  if (!baseline) return { added: null, removed: null };
-  const numstat = gitOk(`git diff --numstat ${baseline}...HEAD`) || gitOk(`git diff --numstat ${baseline} HEAD`);
-  if (!numstat) return { added: null, removed: null };
-  let added = 0;
-  let removed = 0;
-  for (const line of numstat.split('\n')) {
-    const [a, r] = line.split('\t');
-    if (a !== '-' && a != null && a !== '') added += Number(a) || 0;
-    if (r !== '-' && r != null && r !== '') removed += Number(r) || 0;
-  }
-  return { added, removed };
-}
-
-// task 1270: build + print the deterministic completion card. Prints the
-// alignment-proof monospace card to stdout (always), then writes the branded
-// in-feed HTML to a temp file and prints an [otb-card-html] marker the
-// builder-ship skill picks up to render it in the chat feed. Every step is
-// best-effort — a summary card must NEVER fail or undo a completed ship.
-async function printCompletionCard({ taskId, postGradeStatus, card, usage, land = null }) {
-  if (!card) return;
-  try {
-    const shipCard = require('../../modules/lifecycle/ship-card');
-
-    // Diffstat from the committed range the grader used (baseline...HEAD).
-    const fileCount = Array.isArray(card.files) && card.files.length ? card.files.length : null;
-    const { added, removed } = diffstatFor(card.baseline);
-
-    // Deployed commit (shipped only): prefer prod /version, fall back to short HEAD.
-    let commit = null;
-    if (postGradeStatus === 'shipped') {
-      const v = fetchDeployedVersion();
-      commit = (v && v.commit) ? String(v.commit).slice(0, 7) : (gitOk('git rev-parse --short HEAD') || null);
-    }
-
-    // Running drachmae total + the builder's render-widgets knob (task 1279),
-    // both from one /me fetch (best-effort).
-    let total = null;
-    let widgetsEnabled = true;
-    try {
-      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;
-      }
-    } catch (_) { /* total + knob are optional; default widgets on */ }
-
-    // Token count + estimated cost from the session usage. Split the tokens into
-    // 'new' (fresh input + output + first-time cache writes) vs 'cached' re-reads
-    // (cache_read — the same large context re-read every turn) so the card can
-    // lead with cost and not with a single all-in count that cache re-reads make
-    // look alarmingly huge (task 1765). The per-model breakdown is already on hand
-    // via usage.modelUsage — no new server data needed.
-    let tokens = null;
-    let costUsd = null;
-    let newTokens = null;
-    let cachedTokens = null;
-    if (usage) {
-      tokens = usage.totalTokens;
-      const mu = usage.modelUsage || {};
-      let cache = 0;
-      let fresh = 0;
-      let sawUsage = false;
-      for (const u of Object.values(mu)) {
-        if (!u) continue;
-        sawUsage = true;
-        cache += Number(u.cache_read) || 0;
-        fresh += (Number(u.input) || 0) + (Number(u.output) || 0) + (Number(u.cache_creation) || 0);
-      }
-      if (sawUsage) { newTokens = fresh; cachedTokens = cache; }
-      try {
-        const { priceModelUsage } = require('../../src/bongos/llm-pricing');
-        costUsd = priceModelUsage(mu).true_cost_usd;
-      } catch (_) { /* cost is optional */ }
-    }
-
-    const cardInputs = {
-      postGradeStatus,
-      taskId,
-      title: card.title,
-      valueSummary: card.valueSummary,
-      notes: card.notes,
-      fileCount,
-      added,
-      removed,
-      grade: card.grade || null,
-      credits: { awarded: card.creditsAwarded, total, perTaskCredit: rewardPolicy(serverReward).perTaskCredit },
-      usage: { tokens, costUsd, newTokens, cachedTokens },
-      deploy: { commit },
-      // task 1002541: absent (the default) ⇒ the card behaves exactly as before,
-      // which keeps every other caller — resumeMerge, the claim card, and
-      // land-watch replaying breadcrumbs written by older versions — unchanged.
-      land,
-    };
-    const model = shipCard.buildCardModel(cardInputs);
-
-    // Print the monospace card + write the branded HTML for the in-feed renderer
-    // (shared emitCard, task 1275). The skill reads the printed path and passes
-    // the contents to the visualization tool — the agent authors nothing, so the
-    // card is identical every ship. task 1279: when the builder has widgets off,
-    // emitCard prints only the monospace card (no HTML written or relayed).
-    shipCard.emitCard(model, taskId, { widgetsEnabled });
-
-    // task 1687: in CI deploy mode this card is 'confirmed — landing' and the real
-    // confirmed->shipped land happens minutes later, server-side — so the SHIPPED
-    // banner would never render in-session. Drop a pending-land breadcrumb; the
-    // land-watch hook renders the shipped card on a later prompt once it lands.
-    // Best-effort: a breadcrumb must never fail a ship (mirrors the card itself).
-    if (postGradeStatus === 'confirmed') {
-      try { require('./land-watch').writeBreadcrumb(taskId, { widgetsEnabled, cardInputs }); }
-      catch (_) { /* breadcrumb is best-effort */ }
-    }
-  } 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
-// it's unit-testable. A re-grade is allowed iff the task is stuck at `completed`
-// (a ship whose grade failed) AND the caller either last held the claim or is an
-// Archon. Every other status gets a tailored, actionable message. Note this is a
-// client-side UX guard, not a trust boundary: /tasks/:id/grade is rank-open by
-// design (the subagent grade is the authority, not builder identity).
-function evaluateRegradeEligibility({ task, lastClaim, builder }) {
-  if (!task) {
-    return { ok: false, code: 'task_not_found', reason: 'Task not found.' };
-  }
-  const status = task.status;
-  if (status !== 'completed') {
-    let reason;
-    if (status === 'confirmed') {
-      reason = `Task #${task.id} is already 'confirmed' — its grade passed. Nothing to re-grade; run /merge-mode if it hasn't shipped.`;
-    } else if (status === 'shipped') {
-      reason = `Task #${task.id} is already 'shipped'. Done.`;
-    } else if (status === 'active' || status === 'ready') {
-      reason = `Task #${task.id} is '${status}', not 'completed'. Claim it and run a normal /builder-ship — --regrade only re-grades a ship that landed at 'completed'.`;
-    } else {
-      reason = `Task #${task.id} is '${status}'. --regrade only applies to a task stuck at 'completed' after a failed grade.`;
-    }
-    return { ok: false, code: 'not_completed', reason, status };
-  }
-  const isArchon = !!builder && builder.rank === 'archon';
-  const owns = !!lastClaim && !!builder && Number(lastClaim.builder_id) === Number(builder.id);
-  if (!isArchon && !owns) {
-    const holder = lastClaim?.github_login ? `@${lastClaim.github_login}` : 'another builder';
-    return {
-      ok: false,
-      code: 'not_owner',
-      reason: `Task #${task.id} was last claimed by ${holder}. Only that builder or an Archon can re-grade it.`,
-    };
-  }
-  return {
-    ok: true,
-    code: 'eligible',
-    via: owns ? 'owner' : 'archon',
-    reason: owns ? 'you last held this claim' : 'archon re-grade',
-  };
-}
-
-// task 941 (V4.R03 — idempotent ship re-drive): decide what a CLAIM-LESS
-// `ship.js <id>` re-run should do. The claim is consumed at the resolve step, so
-// a ship that fails AFTER it (grade fail → stuck `completed`; merge/deploy fail →
-// stuck `confirmed`, the task-1027 nightmare) left a re-run dead-ending at "you
-// don't have an active claim" — the builder had to know the `--regrade` flag (and
-// for `confirmed` there was NO path at all). This makes a PLAIN re-run resume
-// from the stalled leg: `completed` → re-grade, `confirmed` → re-merge/deploy.
-// Pure + exported so the truth table is unit-tested with no git/network. Returns
-// { action, via?, reason? } where action ∈
-//   resume-grade | resume-merge | done | claim-first | error
-function holderLabel(lastClaim) {
-  return lastClaim?.github_login ? `@${lastClaim.github_login}` : 'another builder';
-}
-function evaluateResumeAction({ task, lastClaim, builder }) {
-  if (!task) return { action: 'error', reason: 'Task not found.' };
-  const status = task.status;
-  if (status === 'shipped') {
-    return { action: 'done', reason: `Task #${task.id} is already 'shipped'. Nothing to do.` };
-  }
-  const isArchon = !!builder && builder.rank === 'archon';
-  const owns = !!lastClaim && !!builder && Number(lastClaim.builder_id) === Number(builder.id);
-  if (status === 'completed' || status === 'confirmed') {
-    const leg = status === 'completed' ? 'grade' : 'merge';
-    if (!isArchon && !owns) {
-      return {
-        action: 'error',
-        reason: `Task #${task.id} is at '${status}' but was last claimed by ${holderLabel(lastClaim)}. ` +
-          `Only that builder or an Archon can resume the ${leg}.`,
-      };
-    }
-    return {
-      action: status === 'completed' ? 'resume-grade' : 'resume-merge',
-      via: owns ? 'owner' : 'archon',
-    };
-  }
-  if (status === 'active') {
-    return {
-      action: 'claim-first',
-      reason: `Task #${task.id} is 'active' (claimed) but not in THIS session. Ship from the session that ` +
-        `claimed it, or \`node scripts/gds/release.js ${task.id} --force\` here, then re-claim.`,
-    };
-  }
-  if (status === 'ready' || status === 'backlog' || status === 'blocked') {
-    return {
-      action: 'claim-first',
-      reason: `Task #${task.id} is '${status}' — claim it first: \`node scripts/gds/claim.js ${task.id}\`.`,
-    };
-  }
-  return { action: 'error', reason: `Task #${task.id} is '${status}'. Nothing to resume.` };
-}
-
-// task 941: resume a `confirmed`-but-unshipped task — the merge/deploy leg only
-// (it already passed the grade + earned credits; this is the leg that stalls when
-// a box can't reach the server publish, a poll window expires, etc.). Mirrors the
-// tail of a normal ship: preflight → mergeAndDeploy → post-ship sync.
-async function resumeMerge(taskId, { summary, skipMerge, force, task, dbOnly = false }) {
-  console.log(`Resuming merge + deploy for task #${taskId}: ${task?.title || ''}`);
-  // Same working-tree-clean / branch-freshness guard a first ship runs before
-  // the land. head_sha is unused on this leg; touches is only for preflight.
-  const claimLike = { touches: task?.touches || [], head_sha: null, task_id: taskId, title: task?.title };
-  console.log('Preflight (working tree + branch freshness)...');
-  const pre = preflight(claimLike, { force });
-  if (!pre.ok) {
-    console.error('');
-    console.error(`Resume aborted: ${pre.reason}. Task stays at confirmed.`);
-    process.exit(1);
-  }
-  // The first ship stored value_summary; reuse it so the merge commit + broadcast
-  // carry meaningful text even when --summary is omitted on the re-run.
-  const effSummary = summary || task?.value_summary || '';
-  const land = await mergeAndDeploy({ taskId, summary: effSummary, advanceToMerge: true, skipMerge, dbOnly });
-  const usage = await postShipSync(taskId, 'confirmed');
-  console.log('');
-  console.log('Done — merge/deploy resume complete.');
-  playShipBell(); // task 1442: ring the bell when a stalled ship finally lands.
-  await onboardingNudgeBestEffort();
-  // task 1275: the resume path lands a stalled ship — show the completion card
-  // too (the gap surfaced on task 1270's own ship). Re-fetch the status so the
-  // card reflects whether it actually reached shipped. Best-effort.
-  try {
-    const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
-    const status = (t.ok && t.data && t.data.task) ? t.data.task.status : 'shipped';
-    await printCompletionCard({
-      taskId, postGradeStatus: status, usage, land,
-      card: { title: task?.title, valueSummary: effSummary, notes: '', creditsAwarded: null },
-    });
-  } catch (_) { /* the resume already succeeded; the card is a bonus */ }
-}
-
-// ---------- Main flow ----------
-
-async function shipMain() {
-  await requireSession();
-  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-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
-    console.error('  prefer the -file forms for prose: a shell command-substitutes backticks in an inline value before node sees it (learning 1000197).');
-    process.exit(2);
-  }
-  // G04: prose from a FILE or inline, never shell-mangled in silence.
-  const prose = resolveProse(args, ['notes', 'summary']);
-  const notes = prose.notes;
-  const summary = prose.summary;
-  const skipMerge = args.includes('--no-merge');
-  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).
-  // 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.
-  const verified = args.includes('--verified');
-  // #853 (ADR 0041): `let` not `const` — when the server has the temporary
-  // global grader bypass ON (surfaced as me.grader_bypass below), we force the
-  // skip-grade/confirm path for everyone so no builder runs the subagent grader
-  // during a grader outage window.
-  let skipGrade = args.includes('--skip-grade');
-  // task 1365: explicit acknowledgement that this task legitimately has NO
-  // committed artifact (a pure DB-only / no-op task). Required for the
-  // empty-diff guard below to ALLOW an empty committed diff; without it, an
-  // empty diff is refused (it used to slip through under --skip-grade — the
-  // task-1363 phantom ship). Never overrides a dirty working tree.
-  const allowEmpty = args.includes('--allow-empty');
-  // task 1002605 (G-18): explicit opt-in to continue past a FAILED production
-  // smoke run. Without it a smoke FAIL now ABORTS before the claim resolves
-  // (claim intact); with it, the resolve proceeds and the task deliberately
-  // parks at 'completed' ungraded — and the ship says so instead of "Done."
-  const allowSmokeFail = args.includes('--allow-smoke-fail');
-  // Surprise flag handling — see captureSurpriseLearning(). Resolved below
-  // once we know which claim is being shipped (so touches[] can become tags).
-  const surpriseRaw = arg('--surprise', args);
-  const surpriseProvided = surpriseRaw !== null;
-  const noSurprise = args.includes('--no-surprise');
-
-  // 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);
-  }
-  // #853 (ADR 0041): honor the server-side global grader bypass. When ON, every
-  // builder lands work without the subagent grader (the /tasks/:id/confirm gate
-  // is relaxed to any-builder server-side to match). Default OFF.
-  if (me.data.grader_bypass && !skipGrade) {
-    skipGrade = true;
-    console.log('Note: GRADER_BYPASS_ENABLED is on server-side — skipping the subagent grader and confirming directly (temporary outage window).');
-  }
-  const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
-  const ac = claims.find((c) => Number(c.task_id) === taskId);
-  if (!ac) {
-    // task 941 (V4.R03): no active claim in THIS session is NOT automatically a
-    // dead-end. The claim is consumed at resolve, so a ship that stalled AFTER it
-    // (grade fail → `completed`; merge/deploy fail → `confirmed`, the #1027 case)
-    // leaves no claim — but a plain re-run should RESUME the stalled leg, not
-    // strand the task. Route on the task's current status + ownership.
-    const tRes = await (await cliClient()).tasks.getTasksId({ id: taskId, query: { include: 'last_claim' } });
-    const task = tRes.ok ? tRes.data.task : null;
-    const lastClaim = tRes.ok ? (tRes.data.last_claim || null) : null;
-    const action = evaluateResumeAction({ task, lastClaim, builder: me.data.builder });
-    if (action.action === 'resume-grade') {
-      console.log(`Task #${taskId} is at 'completed' (grade stalled) and ${action.via === 'owner' ? 'you last held the claim' : 'you are an Archon'} — resuming the grade (no re-claim needed).`);
-      return regradeMain();
-    }
-    if (action.action === 'resume-merge') {
-      console.log(`Task #${taskId} is at 'confirmed' (merge/deploy stalled) and ${action.via === 'owner' ? 'you last held the claim' : 'you are an Archon'} — resuming the merge + deploy (no re-claim needed).`);
-      return resumeMerge(taskId, { summary, skipMerge, force, task, dbOnly });
-    }
-    if (action.action === 'done') {
-      console.log(action.reason);
-      return;
-    }
-    console.error(action.reason || `You don't have an active claim on task #${taskId}.`);
-    if (claims.length > 0) {
-      console.error(`Your active claims:`);
-      for (const c of claims) console.error(`  #${c.task_id}: ${c.title}`);
-    }
-    process.exit(1);
-  }
-
-  // ---- Hard cap: refuse to ship over the monthly budget (V3.R84 #302, C3) ----
-  // Shipping runs the subagent grader, which spends API $. If this builder is at
-  // or over their monthly budget, refuse here — BEFORE the grader runs and BEFORE
-  // the claim resolves, so the claim stays active and no cost is incurred. Any
-  // Metic+ builder lifts the block by raising the builder's budget
-  // (PATCH /builders/:id/budget — builder.budget.set, metic-floored since ADR 0157).
-  // Fail-open: a missing/unreadable cost status (e.g. an older server) never blocks a ship.
-  const costStatus = me.data.cost;
-  if (costStatus && costStatus.level === 'over') {
-    console.error('');
-    console.error(`Ship refused: monthly budget exceeded — $${costStatus.spend_mtd_usd} of $${costStatus.budget_mtd_usd} spent this month (${costStatus.pct_used}%).`);
-    console.error('Shipping runs the quality grader, which spends API budget. No claim resolved, no credits awarded.');
-    console.error('Ask any Metic or Archon to raise your monthly budget (PATCH /builders/:id/budget), then re-ship.');
-    process.exit(1);
-  }
-
-  // ---- Surprise gate: forced "anything surprise you?" prompt ----
-  //
-  // Resolve the user's intent into a single value: either a non-empty surprise
-  // string (capture a learning) or empty (no surprise, ship normally).
-  //   --surprise "text"   → capture
-  //   --surprise none     → no surprise
-  //   --surprise ""       → no surprise
-  //   --no-surprise       → no surprise
-  //   neither + TTY       → prompt
-  //   neither + non-TTY   → no surprise, with stderr warning
-  let surpriseText = '';
-  if (surpriseProvided) {
-    const v = (surpriseRaw || '').trim();
-    surpriseText = (v === '' || v.toLowerCase() === 'none') ? '' : v;
-  } else if (noSurprise) {
-    surpriseText = '';
-  } else if (process.stdout.isTTY && process.stdin.isTTY) {
-    surpriseText = await promptSurprise();
-    if (surpriseText.toLowerCase() === 'none') surpriseText = '';
-  } else {
-    console.error('warn: no --surprise or --no-surprise provided in non-interactive context; defaulting to no surprise.');
-    surpriseText = '';
-  }
-
-  // ---- Step 0: preflight (working tree + branch freshness) ----
-  console.log(`Verifying claim #${ac.claim_id} on task #${ac.task_id}: ${ac.title}`);
-  console.log('Preflight (working tree + branch freshness)...');
-  const pre = preflight(ac, { force });
-  if (!pre.ok) {
-    console.error('');
-    console.error(`Ship aborted: ${pre.reason}. No claim resolved, no credits awarded.`);
-    process.exit(1);
-  }
-
-  // ---- Step 0b: pull origin/main into the branch up front (#1068, gap 2) ----
-  // So the tree reviewed on the sandbox == the tree we ship — no post-approval
-  // re-stage loop. Skipped under --no-merge (a deliberate "don't touch main"
-  // opt-out). Aborts only on a genuine conflict, claim left intact.
-  if (!skipMerge) {
-    const m = mergeMainIntoBranch();
-    if (!m.ok) {
-      console.error('');
-      console.error(`Ship aborted: ${m.reason}.`);
-      console.error('No claim resolved, no credits awarded — your claim is still active.');
-      process.exit(1);
-    }
-  }
-
-  // ---- Capture surprise learning (if any) ----
-  if (surpriseText) {
-    console.log('Capturing surprise as a learning...');
-    await captureSurpriseLearning(surpriseText, ac, taskId);
-  }
-
-  // ---- Pre-verify: auto-linkify this ship's own changed docs (#747) ----
-  // Fix bare "#NNN" task refs in the docs this ship changed BEFORE the merge,
-  // so they never red-X the doc-ref-linkify gate (tests/linkify_check.mjs in
-  // the `unit` check). Best-effort.
-  autoLinkifyChangedDocs(ac);
-
-  // ---- Empty-diff / phantom-ship guard (must run BEFORE the review gate + resolve) ----
-  // #513 added this check, but at step 2 — AFTER the resolve below already
-  // landed the task at `completed` and consumed the claim. A builder who ran
-  // /builder-ship before committing then burned the claim and couldn't re-ship
-  // ("You don't have an active claim" — the task-595-regrade-gap). Observed
-  // live on #662 (Windows). Moving it here means an empty committed diff aborts
-  // cleanly with the claim STILL ACTIVE, so the builder can commit and re-run.
-  // The grader reads committed history (baseline...HEAD), independent of
-  // touches[] (see computeGraderBaseline). The computed list is reused by the
-  // grader at step 2 so we don't diff twice.
-  //
-  // task 1365: this guard now runs REGARDLESS of --skip-grade. The old version
-  // was gated on `!skipGrade`, so --skip-grade (and the server-side
-  // grader_bypass that forces skipGrade) sailed an empty committed diff straight
-  // through to resolve → manual-confirm → the publish reconciler then shipped a
-  // task with NO artifact on main (task 1363: a new doc left UNTRACKED, never
-  // committed, HEAD never moved — the ledger lied, CLAUDE.md §8). classifyEmptyShip
-  // splits the three cases: a dirty/untracked working tree means the deliverable
-  // was never committed (refuse, even under --allow-empty); a clean tree with an
-  // explicit --allow-empty is a genuine no-artifact/DB-only ship (allow); a clean
-  // tree without the flag is nothing-to-ship (refuse). Refusing here leaves the
-  // claim ACTIVE so the builder can commit + re-run.
-  const graderBaseline = computeGraderBaseline(ac);
-  const committedFiles = computeChangedFiles(graderBaseline);
-  if (committedFiles.length === 0) {
-    const verdict = classifyEmptyShip(gitOk('git status --porcelain'), { allowEmpty });
-    if (verdict.reason === 'uncommitted-work') {
-      console.error('Ship refused: nothing is committed on this branch, but your working tree has uncommitted changes:');
-      for (const f of verdict.uncommitted) console.error(`    - ${f}`);
-      console.error('');
-      console.error('Your work was never committed — shipping now would mark the task "shipped" with NO artifact on main (the ledger would lie).');
-      console.error('Stage + commit your work (e.g. `git add -A && git commit`), then re-run /builder-ship. Your claim is still active.');
-      process.exit(1);
-    }
-    if (verdict.reason === 'nothing-to-ship') {
-      console.error(`Nothing to ship: the committed diff vs ${graderBaseline || 'baseline'} is empty and the working tree is clean.`);
-      console.error('The grader reads committed history, not the working tree — commit your work on this branch, then re-run /builder-ship. Your claim is still active.');
-      console.error('If this task legitimately has no code/doc artifact (a pure DB-only or no-op task), re-run with --allow-empty.');
-      process.exit(1);
-    }
-    // verdict.reason === 'allow-empty': a deliberate no-artifact / DB-only ship.
-    // There is no committed diff for the subagent grader to read, so confirm
-    // directly (this is the DB-only path the old --skip-grade route served).
-    if (!skipGrade) skipGrade = true;
-    console.log('--allow-empty: no committed diff (no-artifact / DB-only ship) — confirming directly without the subagent grader.');
-  }
-
-  // ---- Module drift check (BV1.R53, task 1422) ----
-  // If the task carries a module_key, verify the committed diff doesn't stray
-  // into a DIFFERENT module's territory. "You said game, you touched dev-box" is
-  // the semantic violation this catches. Files outside all module scopes (docs,
-  // session logs, general scripts) are allowed — they're cross-cutting. Only
-  // contact with a DIFFERENT module's glob set is refused.
-  //
-  // The check is ADVISORY (warns but does not refuse) on the first cut because
-  // the module_key column is new and existing tasks may carry a broader diff scope
-  // until all tasks are labelled. Enforced tasks can opt in with --enforce-module.
-  // ac.module_key comes from getActiveClaimsForBuilder (t.module_key in the join).
-  const enforceModule = args.includes('--enforce-module');
-  if (ac.module_key && isModuleKey(ac.module_key) && committedFiles.length > 0) {
-    const declaredScope = scopeForModule(ac.module_key);
-    const { MODULE_SCOPE_MAP } = require('../../src/bongos/module-scope-map');
-    const moduleDriftFiles = committedFiles.filter((f) => {
-      if (declaredScope && matchOne(f, declaredScope.globs)) return false;
-      for (const [key, entry] of Object.entries(MODULE_SCOPE_MAP)) {
-        if (key === ac.module_key) continue;
-        if (matchOne(f, entry.globs)) return true;
-      }
-      return false;
-    });
-    if (moduleDriftFiles.length > 0) {
-      const msg = [
-        `\n⚠ Module drift detected: task is scoped to '${ac.module_key}' but ${moduleDriftFiles.length} file(s) touch a different module:`,
-        ...moduleDriftFiles.map((f) => `  - ${f}`),
-        '',
-        enforceModule
-          ? 'Refused (--enforce-module). Confine your changes to modules/' + ac.module_key + '/ or clear the module_key label.'
-          : 'Advisory — ship proceeds, but consider confining your changes to modules/' + ac.module_key + '/.',
-      ].join('\n');
-      console.log(msg);
-      if (enforceModule) process.exit(1);
-    }
-  }
-
-  // ---- Sandbox-first review gate (#927, ADR 0046) ----
-  // On a dev box, a diff that touches game surfaces must be STAGED on the
-  // builder's own live preview (sandbox-<login>.amazonprimea.com, ADR 0044)
-  // and reviewed in a browser before the claim resolves — see it running,
-  // get the chance to iterate, THEN decide to ship to the main game. Laptop
-  // sessions, non-game diffs, quick-tunnel boxes, and --skip-stage all pass
-  // through untouched. Interactive: stage + ask; declining aborts with the
-  // claim intact. Non-TTY (agent-driven sessions): stage, then abort with the
-  // review URL — the re-run after the human reviews passes on the fresh
-  // staged marker. Never hangs on stdin.
-  const sandboxGate = await runShipGate({
-    taskId,
-    files: committedFiles,
-    skipStage: args.includes('--skip-stage'),
-    // #1048: --approved records the builder's sign-off after they reviewed the
-    // staged change on their sandbox. Only honored on a re-run whose game state
-    // is already staged-fresh — it can't pre-approve an unstaged change.
-    approved: args.includes('--approved'),
-    tty: Boolean(process.stdout.isTTY && process.stdin.isTTY),
-  });
-  if (!sandboxGate.ok) {
-    if (sandboxGate.review) {
-      // task 1275: the in-review card — the SAME lifecycle card, amber, whose
-      // action is "Open in sandbox ↗" (the sandbox URL the owner asked to surface
-      // here). Best-effort, never blocks the pause.
-      try {
-        const shipCard = require('../../modules/lifecycle/ship-card');
-        const { added, removed } = diffstatFor(graderBaseline);
-        const model = shipCard.buildCardModel({
-          stage: 'review',
-          taskId,
-          title: ac.title,
-          valueSummary: summary,
-          fileCount: committedFiles.length || null,
-          added,
-          removed,
-          sandboxUrl: sandboxGate.url,
-        });
-        // task 1279: honour the builder's render-widgets knob (from the /me
-        // fetched at the top of shipMain; default ON if absent/older server).
-        const widgetsEnabled = me?.data?.render?.widgets_enabled !== false;
-        shipCard.emitCard(model, taskId, { widgetsEnabled });
-      } catch (_) { /* the review pause stands with or without the card */ }
-      // #1061 polish: a sandbox review pause is a DELIBERATE, expected
-      // checkpoint — not a failed ship. printReviewBlock already showed the URL
-      // + the --approved next step, so don't follow it with red "Ship aborted /
-      // no credits awarded" text that makes the review moment read as broken.
-      // Calm note on stdout (not stderr); the claim is left fully intact.
-      console.log('');
-      console.log('⏸  Paused for your sandbox review — this is expected, not an error.');
-      console.log('   Your claim is still active; nothing was lost.');
-      console.log('   Walk the change at the link above, then approve with: /builder-ship --approved');
-      process.exit(1);
-    }
-    console.error('');
-    console.error(`Ship aborted: ${sandboxGate.reason}.`);
-    console.error('No claim resolved, no credits awarded — your claim is still active.');
-    process.exit(1);
-  }
-  // #1048: the recorded sandbox self-approval (when the builder approved a
-  // staged game change), threaded into the resolve call below so the server
-  // persists it on the task. null on laptop ships, non-game diffs, quick-tunnel
-  // boxes, --skip-stage, and bare fresh-marker re-runs without --approved.
-  const sandboxReview = sandboxGate.sandboxReview || null;
-
-  // ---- Step 1+2: verify locally (smoke) — runs AFTER the review gate (#1061) ----
-  // touches[] cleanup [4/8] (task 879): the predictive drift scanner is gone;
-  // local verification is smoke-only. Smoke runs HERE (post-gate) so a review
-  // PAUSE doesn't bury the sandbox link under the smoke output — smoke only runs
-  // on the actual ship: the --approved re-run, or a laptop / non-game ship the
-  // gate waved straight through. (#1061 — the gate is a no-op for those, so this
-  // is the same single smoke run as before, just sequenced after it.)
-
-  // task 1002660: start the grade COMPUTATION now, so the multi-minute panel
-  // overlaps the smoke run + claim resolve instead of serializing behind them.
-  // computeGradeResult performs no server writes — the grade POST stays in the
-  // grade step below, after the resolve lands the task at 'completed'. On a
-  // smoke abort the in-flight panel is discarded (its partial spend is lost —
-  // rare, and cheaper than serializing every ship behind smoke).
-  let gradeCompute = null;
-  let fullTaskForGrade = null;
-  if (!skipGrade) {
-    const tFetch = await (await cliClient()).tasks.getTasksId({ id: taskId });
-    fullTaskForGrade = tFetch.ok ? tFetch.data.task : { id: taskId, title: ac.title };
-    console.log('Starting the quality grader panel (overlaps the smoke run — task 1002660)...');
-    gradeCompute = computeGradeResult({
-      taskId, task: fullTaskForGrade, summary,
-      baseline: graderBaseline, committedFiles,
-    });
-    gradeCompute.catch(() => {}); // an abort path must not die on an unhandled rejection
-  }
-
-  console.log('Running smoke tests against production...');
-  // task 1002660: the async twin — awaiting keeps the event loop free so the
-  // overlapped panel's subprocess callbacks progress while smoke runs.
-  const smoke = await runSmokeAsync();
-  const passed = smoke.clean;
-  console.log('');
-  console.log(`Verification: smoke=${smoke.clean ? 'clean' : 'FAIL'}, overall=${passed ? 'PASS' : 'FAIL'}`);
-  console.log('');
-
-  // task 1002605 (G-18): a smoke FAIL used to fall straight through into the
-  // claim resolve — claim consumed, grading silently skipped, task parked at
-  // 'completed', exit 0, and the builder read "Done." believing they shipped.
-  // Abort BEFORE the resolve instead — the same claim-preserving posture as the
-  // budget cap and the sandbox-review gate above. --allow-smoke-fail is the
-  // deliberate continuation; the parked message where the grader would have run
-  // says exactly where that leaves the task.
-  if (!passed && !allowSmokeFail) {
-    console.error('');
-    for (const line of smokeGateMessages(taskId).abort) console.error(line);
-    process.exit(1);
-  }
-
-  // ---- Step 1: resolve the claim (lands at completed) ----
-  // V3.R18 (#209): resolveClaim no longer runs the v1 deterministic grader.
-  // It now lands the task at `completed` when verification (smoke) passes, and
-  // stops. The v2 subagent grader (step 2 below) is what gates the credits +
-  // the completed→confirmed transition.
-  const r = await (await cliClient()).claims.postClaimsIdResolve({
-    id: ac.claim_id,
-    body: {
-    outcome: 'shipped',
-    notes_md: notes,
-    value_summary: summary,
-    verification: {
-      passed,
-      // touches[] cleanup [4/8] (task 879): the drift scanner is gone; with no
-      // scanner there is nothing to drift, so this audit-trail signal
-      // (grader.scoreScannerSmoke) is vacuously clean.
-      scanner_clean: true,
-      smoke_clean: smoke.clean,
-    },
-    // touches[] cleanup [7/8] (task 882): the real committed changed-files, so
-    // the server backfills touches[] from reality (the planning prediction is
-    // now optional). Same list the grader already used.
-    committed_files: committedFiles,
-    // #1048: the sandbox self-approval { stamp, url, method } when the builder
-    // reviewed + approved a staged game change. The server stamps by/at and
-    // persists it to tasks.sandbox_review. null = nothing to record.
-    sandbox_review: sandboxReview,
-    },
-  });
-  if (!r.ok) {
-    const resolveErr = normalizeApiError(r.data);
-    if (resolveErr.code === 'CLAIM_SESSION_MISMATCH') {
-      const wt = resolveErr.details.claimWorktree;
-      console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
-      console.error('You can only ship from the session that originally claimed this task.');
-      console.error(`To force-release from this session: node scripts/gds/release.js ${taskId} --force`);
-    } else {
-      console.error(`resolve failed: ${apiErrorLine(r.data, r.status)}`);
-    }
-    process.exit(1);
-  }
-
-  const taskStatus = r.data.taskStatus || 'shipped (legacy response)';
-  console.log(`Task #${r.data.taskId} is now: ${taskStatus}`);
-  // Claim CONSUMED, task at 'completed' — a crash from here needs fatalRecoveryLines.
-  markShipProgress('resolved', taskId);
-
-  // ---- Step 2: subagent quality grader ----
-  // Runs when local verification passed AND resolveClaim landed at completed.
-  // If verification did not pass we don't bother grading — the task stays at
-  // completed (or whatever resolveClaim returned) with no credits.
-  let credits = r.data.creditsAwarded ?? 0;
-  let postGradeStatus = taskStatus;
-  let postGradeJustUnlocked = r.data.just_unlocked || [];
-  let gradePassed = false;
-  let advanceToMerge = false;
-  let gradeObj = null; // task 1270: the grade result, hoisted for the completion card
-  // V3.R27 (#247): credit breakdown surfaced from the grade or confirm
-  // response. Kept separate from `credits` so we only print the multiplier
-  // line when the multiplier actually moved the payout.
-  let creditsRaw = null;
-  let creditsMultiplier = null;
-  let ideaBonusInfo = null;
-
-  if (passed && taskStatus === 'completed' && skipGrade) {
-    // Escape hatch: skip the subagent grader and manual-confirm. The
-    // task_grades row gets grader_kind='lars' so the audit trail captures
-    // that this ship bypassed the v2 grader.
-    console.log('');
-    console.log('--skip-grade: skipping subagent grader; manual-confirming via POST /tasks/:id/confirm.');
-    // task 1053 (F): pass the verify attestation. The server refuses to confirm a
-    // kind='verify' task without it (so a hardware-verify can't land before the
-    // verify ran). --verified is a no-op for every other kind.
-    const confirm = await (await cliClient()).tasks.postTasksIdConfirm({ id: taskId, body: { verified } });
-    if (!confirm.ok) {
-      if (confirm.status === 409 && normalizeApiError(confirm.data).code === 'verify_attestation_required') {
-        console.error('');
-        console.error(`This is a VERIFICATION task — it won't confirm until you attest the verify actually passed.`);
-        console.error(`Run the verification, then re-ship with --verified:`);
-        console.error(`  node scripts/gds/ship.js ${taskId} --verified`);
-        console.error(`(Your work is committed and the task is at 'completed' — re-running resumes, task 941.)`);
-        process.exit(1);
-      }
-      // task 1002613 (map P-1): the one genuine permission wall on the ship path
-      // used to surface as a raw envelope dump — an atom name is not a rank, and
-      // no remedy printed at the one station where self-service exists. Interpret
-      // it: name the wall, the floor (from the server's floors map — never
-      // hardcoded), and both ways forward.
-      const errObj = confirm.data && confirm.data.error;
-      const errCode = typeof errObj === 'string' ? errObj : (errObj && errObj.code);
-      if (confirm.status === 403 && errCode === 'permission_forbidden') {
-        const details = (errObj && typeof errObj === 'object' && errObj.details) || {};
-        const floor = details.floors && details.floors['task.confirm.grade_bypass'];
-        const floorNote = floor ? ` (floor: ${floor})` : '';
-        console.error('');
-        console.error(`✖ Confirming without a passing grade is permission-gated: task.confirm.grade_bypass${floorNote}.`);
-        console.error('  This is an authorization wall, not a verdict on your work.');
-        console.error('  Self-service: re-run WITHOUT --skip-grade to use the subagent grader, and if a');
-        console.error('  grade fails, fix its findings and re-run (unlimited, no attempt cap):');
-        console.error(`      node scripts/gds/ship.js ${taskId} --regrade`);
-        console.error(`  If the grade genuinely cannot pass, ask a builder whose role holds`);
-        console.error(`  task.confirm.grade_bypass${floorNote} to POST /api/gds/tasks/${taskId}/confirm.`);
-        process.exit(1);
-      }
-      console.error(`manual-confirm failed: ${apiErrorLine(confirm.data, confirm.status)}`);
-      process.exit(1);
-    }
-    postGradeStatus = confirm.data.taskStatus;
-    credits = confirm.data.creditsAwarded ?? 0;
-    ideaBonusInfo = confirm.data.ideaBonus ?? null;
-    advanceToMerge = postGradeStatus === 'confirmed';
-    gradePassed = true; // by builder fiat, not by grader
-  } else if (passed && taskStatus === 'completed') {
-    console.log('');
-    console.log('Running subagent quality grader...');
-
-    // #513 + #536: the grader reads COMMITTED history (baseline...HEAD), not
-    // the working tree. The empty-committed-diff guard now runs earlier — BEFORE
-    // the claim is resolved (see above) — so by the time we reach here the diff
-    // is guaranteed non-empty on the grader path. Reuse the baseline + file list
-    // computed there so we don't diff twice. #678: gradeAndRecord POSTs the
-    // result and logs the panel cost — the same unit the --regrade path reuses.
-    // task 1002660: the panel computation was started BEFORE the smoke gate
-    // (gradeCompute above) — hand it in so this step only waits out whatever
-    // panel time smoke + resolve didn't already absorb.
-    const gradePost = await gradeAndRecord({
-      taskId,
-      task: fullTaskForGrade || { id: taskId, title: ac.title },
-      summary,
-      baseline: graderBaseline,
-      committedFiles,
-      precomputed: gradeCompute,
-    });
-
-    if (!gradePost.ok) {
-      console.error(`grade POST failed (${gradePost.status}):`, gradePost.data);
-      console.error('Task stays at completed. Manual options:');
-      console.error(`  - Re-run /builder-ship ${taskId} to try grading again, or`);
-      console.error(`  - node scripts/gds/ship.js ${taskId} --regrade after fixing findings, or`);
-      console.error(`  - POST /api/gds/tasks/${taskId}/confirm to manual-confirm (last resort —`);
-      console.error('    permission-gated on task.confirm.grade_bypass).');
-      process.exit(1);
-    }
-
-    const g = gradePost.data.grade;
-    gradeObj = g;
-    gradePassed = g.passed;
-    advanceToMerge = gradePost.data.advanceToMerge;
-    postGradeStatus = gradePost.data.taskStatus;
-    credits = gradePost.data.creditsAwarded;
-    postGradeJustUnlocked = gradePost.data.just_unlocked || [];
-    // V3.R27 (#247): pull the multiplier breakdown + idea-bonus info forward.
-    creditsRaw = gradePost.data.creditsRaw ?? null;
-    creditsMultiplier = gradePost.data.creditsMultiplier ?? null;
-    ideaBonusInfo = gradePost.data.ideaBonus ?? null;
-
-    printGradeOutcome(g, taskId);
-  } else if (!passed && taskStatus === 'completed') {
-    // task 1002605 (G-18): the --allow-smoke-fail continuation. The resolve above
-    // consumed the claim with verification.passed=false, so the grader deliberately
-    // does not run. This used to be a silent fall-through; say where the task is.
-    console.log('');
-    for (const line of smokeGateMessages(taskId).parked) console.log(line);
-  }
-
-  printCreditsAndAchievements({
-    postGradeStatus, credits, creditsRaw, creditsMultiplier, ideaBonusInfo,
-    justUnlocked: postGradeJustUnlocked,
-  });
-
-  // ---- Step 3: confirmed→shipped tail (merge + deploy → memory/session sync →
-  // Done → onboarding nudge → completion card), shared with regradeMain via
-  // finishShip (#1093/C9). ----
-  // Graded. If it passed, only the merge remains — a different crash story.
-  if (postGradeStatus === 'confirmed' || postGradeStatus === 'shipped') {
-    markShipProgress(postGradeStatus === 'shipped' ? 'landed' : 'graded', taskId);
-  }
-  await finishShip({
-    taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly,
-    // task 1270: data for the deterministic completion card.
-    card: {
-      title: ac.title,
-      valueSummary: summary,
-      notes,
-      files: committedFiles,
-      baseline: graderBaseline,
-      creditsAwarded: credits,
-      // task 1275: a real grade ran → pass/fail + issues; otherwise (--skip-grade
-      // or server-side GRADER_BYPASS) it was confirmed without a grade → skipped,
-      // so the card reads "grade skipped" rather than implying a real pass.
-      grade: gradeObj
-        ? { passed: gradeObj.passed, issues: gradeObj.issues || [], panel: Array.isArray(gradeObj.workers) ? gradeObj.workers.length : null, skipped: false }
-        : { passed: gradePassed, skipped: true },
-    },
-  });
-}
-
-// ---------- Re-grade flow (#678) ----------
+// ---------------------------------------------------------------------------
+// FACADE + CLI ENTRY (task 1003205, goal 1000079). This file was 4,613 lines;
+// the R03 de-monolith plan carved it into the ship-*.js phase modules required
+// below, each well under the 1,500-line ratchet. The carve was STRUCTURAL: no
+// function body changed, the module.exports block at the bottom is the original
+// one verbatim, and the flag surface documented above is untouched — so both the
+// ship contract and the five other files that import from here are unaffected.
 //
-// `node scripts/gds/ship.js <id> --regrade` closes the task-595-regrade-gap
-// (re-hit on #600): when a ship lands at `completed` but the subagent grader
-// fails, /builder-ship has already resolved+consumed the claim, leaving no CLI
-// path back in (claim refuses "not ready", PATCH refuses, promote refuses, a
-// fresh ship.js says "no active claim"). The only escapes were the Archon
-// /confirm override (bypasses the grader — see feedback_prefer_regrade_over_override)
-// or hand-building a grader harness (learning #43).
+// The phases form a DAG (no require cycles). Roughly in dependency order:
+//   ship-state · ship-git · ship-io  →  ship-memory-sync · ship-deploy-target
+//   →  ship-surprise · ship-session-upload · ship-land · ship-regen · ship-grade
+//   →  ship-preflight-steps · ship-merge · ship-grade-steps
+//   →  ship-finish  →  ship-resume  →  ship-flow (shipMain / regradeMain).
 //
-// This re-runs ONLY the grade step against the committed diff, with no claim:
-//   - eligibility: task at `completed` AND (you last held the claim OR Archon)
-//   - preflight: working tree committed + ship/grade tooling current
-//   - empty-diff guard: the grader reads committed history, so refuse if empty
-//   - grade: gradeAndRecord → POST /tasks/:id/grade (rank-open; applyGrade
-//     promotes completed→confirmed + awards credits on pass, idempotent)
-//   - on pass: the normal confirmed→shipped merge + sync tail runs.
-async function regradeMain() {
-  await requireSession();
-  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-file <path|-> | --summary "..."] [--response-file <path|-> | --response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
-    process.exit(2);
-  }
-  const regradeProse = resolveProse(args, ['summary', 'response']);
-  const summaryArg = regradeProse.summary;
-  // task 1002662: the builder's response to the prior round's findings — how
-  // each was fixed, tracked (a task ref), or why it's out of scope. Rides to
-  // the panel fenced, under the delta re-grade policy.
-  const responseArg = regradeProse.response;
-  const skipMerge = args.includes('--no-merge');
-  const force = args.includes('--force');
-  // 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 = noteServerReward(await (await cliClient()).me.getMe());
-  if (!me.ok) {
-    console.error('failed to load profile:', me.data);
-    process.exit(1);
-  }
-  const builder = me.data.builder || {};
-  // ?include=grade,last_claim — the claim-holder lookup for eligibility (#678)
-  // + the stored grade row for the delta-aware prior-round payload (task 1002662).
-  const tRes = await (await cliClient()).tasks.getTasksId({ id: taskId, query: { include: 'grade,last_claim' } });
-  if (!tRes.ok) {
-    if (tRes.status === 404) {
-      console.error(`Task #${taskId} not found.`);
-    } else {
-      console.error(`failed to load task #${taskId} (${tRes.status}):`, tRes.data);
-    }
-    process.exit(1);
-  }
-  const task = tRes.data.task;
-  const lastClaim = tRes.data.last_claim || null;
-  const elig = evaluateRegradeEligibility({ task, lastClaim, builder });
-  if (!elig.ok) {
-    console.error(elig.reason);
-    process.exit(1);
-  }
-  // task 1053 (F): the resume/regrade path promotes completed→confirmed via the
-  // grade (applyGrade), which the server-side /confirm verify guard does NOT
-  // cover. Gate it here so a verification task can't be confirmed by simply
-  // re-running without attesting the verify passed (closing the bypass).
-  if (task.kind === 'verify' && !verified) {
-    console.error('');
-    console.error(`Task #${taskId} is a VERIFICATION task — it won't confirm until you attest the verify actually passed.`);
-    console.error(`Run the verification, then re-run with --verified:`);
-    console.error(`  node scripts/gds/ship.js ${taskId} --verified`);
-    process.exit(1);
-  }
-  console.log(`Re-grading task #${taskId}: ${task.title}`);
-  console.log(`  eligibility: ${elig.reason} (${elig.via})`);
-
-  // A grade-failed ship never reached the merge/broadcast step, so a passing
-  // re-grade is the FIRST time this task actually ships. Fall back to the
-  // task's stored value_summary so the merge commit + Discord #ship-news post
-  // carry meaningful text even when --summary is omitted.
-  const summary = summaryArg || task.value_summary || '';
-
-  // The grader helpers want a claim-like object for touches[] (preflight's
-  // working-tree-drift check) and head_sha (baseline fallback). The claim is
-  // gone, so synthesize one from the task row + the last claim's head_sha.
-  const claimLike = { touches: task.touches || [], head_sha: lastClaim?.head_sha ?? null, task_id: taskId, title: task.title };
-
-  // ---- Preflight: work committed + ship/grade tooling current ----
-  // No scanner/smoke re-run — --regrade re-runs ONLY the grade step. But the
-  // grader judges COMMITTED history, so uncommitted fixes on touches[] files
-  // wouldn't be graded — refuse that (it would grade a stale diff). Also refuse
-  // if the local ship/grade tooling is behind main (a stale grader silently
-  // fails the same way — the #662 lesson). --force overrides the freshness leg.
-  console.log('Preflight (working tree + branch freshness)...');
-  const pre = preflight(claimLike, { force });
-  if (!pre.ok) {
-    console.error('');
-    console.error(`Re-grade aborted: ${pre.reason}. Task stays at completed.`);
-    process.exit(1);
-  }
-
-  // ---- Empty-diff guard (the grader reads committed history) ----
-  const graderBaseline = computeGraderBaseline(claimLike);
-  const committedFiles = computeChangedFiles(graderBaseline);
-  if (committedFiles.length === 0) {
-    console.error(`Nothing to grade: the committed diff vs ${graderBaseline || 'baseline'} is empty.`);
-    console.error('The grader reads committed history, not the working tree — commit your fixes on this branch, then re-run --regrade.');
-    process.exit(1);
-  }
-
-  // ---- Delta-aware prior-round context (task 1002662) ----
-  // The prior grade's findings + the builder's response + the interim fix diff
-  // ride to the panel so an already-answered finding can't re-veto on
-  // re-wording alone. The interim range comes from the prior grade's
-  // signals.graded_head_sha (recorded by runSubagentGrader since this task);
-  // older grade rows lack it — the findings still ride, just without the diff.
-  const storedGradeRow = tRes.data.grade ?? null;
-  let interimCommits = '';
-  let interimDiffStat = '';
-  const priorSha = storedGradeRow?.signals?.graded_head_sha;
-  // The sha comes from a DB JSONB blob — validate the shape before shelling out.
-  if (typeof priorSha === 'string' && /^[0-9a-f]{7,40}$/i.test(priorSha) && gitOk(`git rev-parse --verify --quiet ${priorSha}`)) {
-    interimCommits = gitOk(`git log --oneline ${priorSha}..HEAD`) || '';
-    interimDiffStat = gitOk(`git diff --stat ${priorSha}..HEAD`) || '';
-  }
-  const priorRound = buildPriorRoundContext({
-    storedGrade: storedGradeRow,
-    responseText: responseArg,
-    interimCommits,
-    interimDiffStat,
-  });
-  if (priorRound) {
-    console.log(`  prior round context: ${priorRound.audit.prior_findings_count} finding(s) from the prior grade${priorRound.audit.response_present ? ' + builder response' : ''}${priorRound.audit.interim_present ? ' + interim fix diff' : ''} → round ${priorRound.audit.round}`);
-  }
-
-  // ---- Grade step (the only step) ----
-  console.log('');
-  console.log('Running subagent quality grader...');
-  const gradePost = await gradeAndRecord({
-    taskId,
-    task,
-    summary,
-    baseline: graderBaseline,
-    committedFiles,
-    priorRound,
-  });
-  if (!gradePost.ok) {
-    console.error(`grade POST failed (${gradePost.status}):`, gradePost.data);
-    console.error('Task stays at completed. Fix the issue and re-run --regrade (unlimited, no attempt cap).');
-    console.error('(POST /confirm is a last resort — it is permission-gated on task.confirm.grade_bypass.)');
-    process.exit(1);
-  }
+// Its own module doc always told agents to search by PHASE keyword rather than
+// read end-to-end; the phases are now files, so the search is a file open.
+// ---------------------------------------------------------------------------
 
-  const g = gradePost.data.grade;
-  const postGradeStatus = gradePost.data.taskStatus;
-  printGradeOutcome(g, taskId);
-  printCreditsAndAchievements({
-    postGradeStatus,
-    credits: gradePost.data.creditsAwarded,
-    creditsRaw: gradePost.data.creditsRaw ?? null,
-    creditsMultiplier: gradePost.data.creditsMultiplier ?? null,
-    ideaBonusInfo: gradePost.data.ideaBonus ?? null,
-    justUnlocked: gradePost.data.just_unlocked || [],
-  });
+'use strict';
 
-  // On a pass the task is now confirmed — run the SAME confirmed→shipped tail as a
-  // normal ship (finishShip, #1093/C9) so a re-grade lands identically.
-  await finishShip({
-    taskId, summary, advanceToMerge: gradePost.data.advanceToMerge, skipMerge, dbOnly,
-    postGradeStatus,
-    doneLine: g.passed ? 'Done — re-grade passed.' : 'Done — re-grade still failing; fix and try again.',
-    // task 1270: completion card for the re-grade path too.
-    card: {
-      title: task.title,
-      valueSummary: summary,
-      notes: '',
-      files: committedFiles,
-      baseline: graderBaseline,
-      creditsAwarded: gradePost.data.creditsAwarded,
-      grade: { passed: g.passed, issues: g.issues || [], panel: Array.isArray(g.workers) ? g.workers.length : null },
-    },
-  });
-}
+const { buildMergeArgv, gitArgvOk, sanitizeGitHubRefs } = require('./ship-git.js');
+const { apiErrorLine, normalizeApiError, postLandShipOutcome } = require('./ship-io.js');
+const { deriveTagsFromPaths } = require('./ship-surprise.js');
+const {
+  encodeProjectPath,
+  resolveBuilderModel,
+  resolveTranscriptPath,
+} = require('./ship-memory-sync.js');
+const {
+  broadcastHandledByServer,
+  buildPrCreateArgv,
+  buildPrMergeArgv,
+  deployRunSucceeded,
+  deployedCommitStatus,
+  effectiveDeployMode,
+  parseDeployMode,
+  pushVia,
+  resolveDeployMode,
+  resolveDeployTarget,
+  resolveInstanceBase,
+  shouldBailOnFetchFailure,
+} = require('./ship-deploy-target.js');
+const { classifyUploadSkip, recordUploadSkip } = require('./ship-session-upload.js');
+const {
+  classifyLandOutcome,
+  formatPublishFailure,
+  landBailed,
+  landPending,
+  landPendingLines,
+  landPollAfterAutoMerge,
+  landed,
+  pickStaleGateReviewRun,
+  reconcileBlockedLines,
+  reconciledCardStatus,
+  strandCommand,
+  strandNextStep,
+} = require('./ship-land.js');
+const {
+  VENDORED_CLIENT_REL,
+  apiClientPathspec,
+  regenerateDiagrams,
+  regenerateFileMap,
+  regenerateRepoMap,
+  regenerateSessionIndex,
+} = require('./ship-regen.js');
+const {
+  baseRefShipGuard,
+  computeChangedFiles,
+  computeGraderBaseline,
+  computeRawDiffHash,
+  diffHash,
+  reconstructPanelIssues,
+  resolveBaseRef,
+  runSubagentGrader,
+  shouldReuseGrade,
+} = require('./ship-grade.js');
+const {
+  decidePreMerge,
+  isLinkifiableDocPath,
+  parseDeletedUpstreamPaths,
+} = require('./ship-preflight-steps.js');
+const { zeroCommitVerdict } = require('./ship-merge.js');
+const {
+  buildGradePayload,
+  buildPriorRoundContext,
+  computeGradeResult,
+  formatGradeOutcome,
+  gradeAndRecord,
+} = require('./ship-grade-steps.js');
+const { evaluateRegradeEligibility, evaluateResumeAction } = require('./ship-resume.js');
+const { regradeMain, shipMain } = require('./ship-flow.js');
+const { fatalRecoveryLines, smokeGateMessages } = require('./ship-honesty.js');
+const { chooseBroadcastTargets } = require('../../modules/discord/ship-broadcast');
+const {
+  collectEnvSecrets,
+  looksHighEntropySecret,
+  redactHighEntropy,
+  scrubSecrets,
+  shannonEntropy,
+} = require('../../modules/security/secret-scrub');
+const { buildSessionDigest, snippetOf } = require('./session-digest-build');
 
-// Pure helpers are exported for unit tests (tests/session_records.mjs). The
-// orchestration only runs when ship.js is invoked directly — so `require()`ing
-// this module (a test) does NOT kick off a ship. (uploadSessionOnShip is not
-// exported: it does I/O + network and is covered by the live smoke at ship.)
 module.exports = {
   scrubSecrets, snippetOf, buildSessionDigest, resolveTranscriptPath,
   // task 1002659: transcript-derived real builder model (dominant by output
@@ -4409,6 +311,14 @@ module.exports = {
 };
 
 if (require.main === module) {
+  // --print-deploy-mode (task 1003221): the EFFECTIVE mode, one word, no session or
+  // network. The /merge-mode skill used to probe parseDeployMode directly, which
+  // defaults to 'laptop' when config/deploy.json is absent — as it is on every dev
+  // box (ADR 0148) — sending the builder down a push path they had no credential for.
+  if (process.argv.slice(2).includes('--print-deploy-mode')) {
+    console.log(require('./ship-deploy-target.js').resolveDeployMode());
+    process.exit(0);
+  }
   // #678: --regrade re-grades a grade-failed `completed` task (no claim needed).
   // Dispatched here so it owns its own arg-parsing + session bootstrap.
   const main = process.argv.slice(2).includes('--regrade') ? regradeMain : shipMain;