@bongos/core 1.17.0

package/scripts/gds/ship.js

@@ -0,0 +1,3618 @@
+#!/usr/bin/env node
+// Builder ship — three-step lifecycle (Phase 5, 2026-05-10):
+//
+//   1. completed:  builder declared work done. Always reached.
+//   2. confirmed:  smoke green. Credits land here.
+//   3. shipped:    branch merged into main + deployed. Visible in production.
+//
+// /builder-ship runs steps 1 + 2 inline. If step 2 succeeds (auto-confirm),
+// it chains into step 3 by pushing the branch, merging it on main, smoke-
+// testing, and running ~/deploy.sh. If step 2 fails, the task stays at
+// 'completed' for human follow-up; if step 3 fails (conflicts, smoke red),
+// the task stays at 'confirmed' for /merge-mode to land later.
+//
+// Usage:
+//   node scripts/gds/ship.js <task-id> --notes "handoff markdown" --summary "value-summary line"
+//   node scripts/gds/ship.js <task-id> --no-merge      # stop after confirm; skip auto-merge
+//   node scripts/gds/ship.js <task-id> --db-only       # deliberate zero-commit / direct-SQL ship (task 391):
+//                                                       # work was a write straight to the prod DB, nothing to
+//                                                       # merge. Without it, a branch with no commits ahead of
+//                                                       # main is REFUSED, not silently shipped.
+//   node scripts/gds/ship.js <task-id> --force         # override behind-main preflight warning
+//   node scripts/gds/ship.js <task-id> --skip-grade    # bypass subagent grader; manual-confirm via /confirm
+//                                                       # Only for: (a) rolling-deploy windows when the
+//                                                       # /tasks/:id/grade endpoint isn't live yet, or
+//                                                       # (b) explicit "the grader is down" recovery.
+//                                                       # NOT a routine flag — every use writes a
+//                                                       # task_grades row with grader_kind='lars' so the
+//                                                       # audit trail shows it was a manual override.
+//   node scripts/gds/ship.js <task-id> --allow-empty   # ship a task with NO committed artifact (a pure
+//                                                       # DB-only / no-op task). Required to get past the
+//                                                       # empty-diff guard; confirms directly (no diff to
+//                                                       # grade). REFUSED if the working tree is dirty —
+//                                                       # that means you forgot to commit (task 1363/1365).
+//   node scripts/gds/ship.js <task-id> --regrade       # re-grade a task STUCK at `completed` (a ship
+//                                                       # whose grade failed): re-runs ONLY the grade step
+//                                                       # against the committed diff, no claim required.
+//                                                       # Caller must have last held the claim (or be
+//                                                       # Archon). The cheap default after fixing grader
+//                                                       # findings — closes the task-595-regrade-gap (#678).
+//   node scripts/gds/ship.js <task-id> --skip-stage    # skip the sandbox-first review gate (#927,
+//                                                       # ADR 0046). On a dev box, game-surface diffs are
+//                                                       # otherwise staged to the builder's own live
+//                                                       # preview (sandbox-<login>, ADR 0044) for a
+//                                                       # browser review BEFORE the claim resolves.
+//   node scripts/gds/ship.js <task-id> --approved      # record your sandbox sign-off (#1048): re-run with
+//                                                       # this AFTER reviewing the staged change at the
+//                                                       # sandbox URL. Persists a sandbox_review row on the
+//                                                       # 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 } = 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, printOnboardingNudge, arg } = require('./cli-lib');
+// 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, '..', '..');
+const { playSound } = require(path.resolve(__dirname, '../../.claude/sounds/play.js'));
+const DROPLET = 'lars@104.236.254.243';
+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: replace every '/' and '.' with '-'.
+  return absProjectPath.replace(/[/.]/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;
+}
+
+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 — short, single-line, scrubbed excerpt for footgun context.
+function snippetOf(text, extraSecrets, max = 160) {
+  if (typeof text !== 'string' || text.length === 0) return undefined;
+  const flat = text.replace(/\s+/g, ' ').trim();
+  if (!flat) return undefined;
+  const cut = flat.length > max ? flat.slice(0, max) : flat;
+  const scrubbed = scrubSecrets(cut, extraSecrets);
+  return scrubbed || undefined;
+}
+
+// buildSessionDigest — turn parsed Claude Code transcript entries into
+// { startedAt, endedAt, durationSeconds, totalTokens, metrics, detail }.
+// Pure (no I/O) + exported for unit tests. `detail` is per-turn metadata + short
+// scrubbed snippets, capped at maxTurns (head+tail kept when over).
+// Harness guardrail retries (task 959) — an is_error tool_result that is NOT real
+// friction but the agent harness rejecting a tool call: an Edit/Write before the
+// file was Read ("File has not been read yet"), or a foreground sleep ("Blocked:
+// sleep"). These were counted in tool_error_count, inflating it and skewing the
+// BFG's order=tool_errors ranking (top sessions ranked on benign retries). They
+// now go into a separate harness_retry_count so tool_error_count stays NET — and
+// because the sessions/search ordering reads metrics->>'tool_error_count'
+// (src/bongos/db.js), that ordering automatically uses the net figure with no route
+// change. (ADR 0027 lineage — the 6D session evaluator.)
+const HARNESS_RETRY_RE =
+  /File has not been read yet|Read it first before (?:writing|editing)|Blocked:\s*sleep|sleep is blocked in (?:the )?foreground/i;
+
+// task 1676 — the family bucket unlabeled token-bearing turns are folded into so
+// the cost-plus reward (ADR 0054) prices the real spend instead of rounding to $0.
+// A concrete, priceable model id (llm-pricing.js maps it to the opus family by
+// substring) — NOT a fabricated dollar figure; it carries the REAL token counts
+// ship.js already parsed, priced server-side like any other bucket.
+const UNATTRIBUTED_MODEL = 'claude-opus-4-8';
+
+function buildSessionDigest(entries, opts = {}) {
+  const extra = opts.extraSecrets || [];
+  const MAX_TURNS = opts.maxTurns || 4000;
+  const m = {
+    assistant_turns: 0,
+    user_turns: 0,
+    tool_use_count: 0,
+    tool_result_count: 0,
+    tool_error_count: 0, // NET real errors (harness guardrail retries excluded)
+    harness_retry_count: 0, // benign harness guardrail retries (task 959)
+    tokens: { input: 0, output: 0, cache_read: 0, cache_creation: 0 },
+    model_usage: {}, // per-model token buckets for the cost-plus reward (task 1005)
+    // task 1676: tokens from turns with NO model id (not '<synthetic>'). Folded
+    // into a priceable bucket after the loop, then stripped from the digest.
+    _unlabeled: { input: 0, output: 0, cache_read: 0, cache_creation: 0 },
+  };
+  const detail = [];
+  let firstTs = null;
+  let lastTs = null;
+  let i = 0;
+  for (const e of Array.isArray(entries) ? entries : []) {
+    if (!e || typeof e !== 'object') continue;
+    const ts = typeof e.timestamp === 'string' ? e.timestamp : null;
+    if (ts) {
+      if (!firstTs) firstTs = ts;
+      lastTs = ts;
+    }
+    const msg = e.message;
+    if (e.type === 'assistant' && msg) {
+      m.assistant_turns++;
+      const u = msg.usage || {};
+      const tin = u.input_tokens || 0;
+      const tout = u.output_tokens || 0;
+      const tcr = u.cache_read_input_tokens || 0;
+      const tcc = u.cache_creation_input_tokens || 0;
+      m.tokens.input += tin;
+      m.tokens.output += tout;
+      m.tokens.cache_read += tcr;
+      m.tokens.cache_creation += tcc;
+      // task 1005: per-model bucket for the cost-plus token reward, reusing the
+      // tin/tout/tcr/tcc already parsed above (no second pass). Skip synthetic
+      // turns (a grader 429 etc. emits no real model id AND no real spend).
+      const model = msg.model;
+      if (model === '<synthetic>') {
+        // synthetic: no real spend — exclude from BOTH model_usage and the
+        // task-1676 unlabeled-remainder fold below (don't price phantom tokens).
+      } else if (model) {
+        const mu = m.model_usage[model] || (m.model_usage[model] =
+          { input: 0, output: 0, cache_read: 0, cache_creation: 0 });
+        mu.input += tin; mu.output += tout; mu.cache_read += tcr; mu.cache_creation += tcc;
+      } else {
+        // task 1676: a token-bearing turn with NO model id. Previously dropped
+        // from model_usage (→ total_tokens>0 but priced $0 on the dev-box/CI
+        // path; ADR 0097). Accumulate the unlabeled tokens so the digest can
+        // attribute them to a real, priceable family bucket after the loop.
+        m._unlabeled.input += tin; m._unlabeled.output += tout;
+        m._unlabeled.cache_read += tcr; m._unlabeled.cache_creation += tcc;
+      }
+      const tools = [];
+      let textLen = 0;
+      let firstText = '';
+      if (Array.isArray(msg.content)) {
+        for (const c of msg.content) {
+          if (c && c.type === 'tool_use') {
+            m.tool_use_count++;
+            tools.push(String(c.name || '?'));
+          } else if (c && c.type === 'text' && typeof c.text === 'string') {
+            textLen += c.text.length;
+            if (!firstText) firstText = c.text;
+          }
+        }
+      }
+      const row = { i, role: 'assistant', ts, in: tin, out: tout, cache_read: tcr, cache_creation: tcc };
+      if (tools.length) row.tools = tools;
+      if (textLen) row.text_len = textLen;
+      const snip = snippetOf(firstText, extra);
+      if (snip) row.snippet = snip;
+      detail.push(row);
+      i++;
+    } else if (e.type === 'user' && msg) {
+      m.user_turns++;
+      let results = 0;
+      let errors = 0;
+      let harnessRetries = 0;
+      let firstResult = '';
+      if (Array.isArray(msg.content)) {
+        for (const c of msg.content) {
+          if (c && c.type === 'tool_result') {
+            results++;
+            m.tool_result_count++;
+            const text = typeof c.content === 'string'
+              ? c.content
+              : Array.isArray(c.content)
+                ? c.content.map((p) => (p && typeof p.text === 'string' ? p.text : '')).join(' ')
+                : '';
+            if (c.is_error) {
+              // Split benign harness guardrail retries out of the net error count
+              // so order=tool_errors ranks on real friction (task 959).
+              if (HARNESS_RETRY_RE.test(text)) {
+                harnessRetries++;
+                m.harness_retry_count++;
+              } else {
+                errors++;
+                m.tool_error_count++;
+              }
+            }
+            if (!firstResult) firstResult = text;
+          }
+        }
+      }
+      const row = { i, role: 'user', ts };
+      if (results) row.tool_results = results;
+      if (errors) row.tool_errors = errors;
+      if (harnessRetries) row.harness_retries = harnessRetries;
+      const snip = snippetOf(firstResult, extra);
+      if (snip) row.snippet = snip;
+      detail.push(row);
+      i++;
+    }
+  }
+  m.total_tokens = m.tokens.input + m.tokens.output + m.tokens.cache_read + m.tokens.cache_creation;
+  // task 1676 — cost-plus reward zero-out fix. The cost-plus session reward
+  // (ADR 0054) prices `model_usage` server-side. model_usage is keyed on msg.model
+  // and SKIPS any token-bearing turn whose model id is missing. On the dev-box/CI
+  // agent path that gap was the difference between total_tokens>0 (so the digest
+  // passes the route's empty-session guard + gets stored) and model_usage={} (so
+  // priceModelUsage returns $0 → 0 drachmae) — ADR 0097's "upload no priced model
+  // usage" symptom. Fold the unlabeled remainder (NOT synthetic turns) into a real,
+  // priceable family bucket so the cost-plus reward reflects the true spend rather
+  // than silently dropping to $0. opus is the conservative family for an unlabeled
+  // turn (matches llm-pricing.js's unknown-model fallback) — this instance runs
+  // opus by default, and pricing an unlabeled turn as opus never UNDER-pays.
+  const un = m._unlabeled;
+  if (un.input + un.output + un.cache_read + un.cache_creation > 0) {
+    const fb = m.model_usage[UNATTRIBUTED_MODEL] || (m.model_usage[UNATTRIBUTED_MODEL] =
+      { input: 0, output: 0, cache_read: 0, cache_creation: 0 });
+    fb.input += un.input; fb.output += un.output;
+    fb.cache_read += un.cache_read; fb.cache_creation += un.cache_creation;
+  }
+  delete m._unlabeled; // scratch — never persisted to the digest
+  let boundedDetail = detail;
+  if (detail.length > MAX_TURNS) {
+    const head = Math.floor(MAX_TURNS * 0.7);
+    const tail = MAX_TURNS - head;
+    boundedDetail = detail.slice(0, head).concat(detail.slice(detail.length - tail));
+    m.detail_truncated = true;
+    m.detail_total_turns = detail.length;
+  }
+  let durationSeconds = null;
+  if (firstTs && lastTs) {
+    const d = (Date.parse(lastTs) - Date.parse(firstTs)) / 1000;
+    if (Number.isFinite(d) && d >= 0) durationSeconds = Math.round(d);
+  }
+  return {
+    startedAt: firstTs,
+    endedAt: lastTs,
+    durationSeconds,
+    totalTokens: m.total_tokens,
+    metrics: m,
+    detail: boundedDetail,
+  };
+}
+
+// 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 ? ` (${r.data.error})` : ''} — ` +
+          '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
+//      SSHes `~/deploy.sh` on the droplet. Today's behavior, byte-for-byte.
+//      Requires the droplet 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-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'); a machine WITH local push creds (a
+// real authed laptop) is byte-for-byte unchanged. Mirrors pushVia()'s existing
+// credential-awareness — the asymmetry (pushVia smart, resolveDeployMode blind)
+// WAS the bug. (task 1449)
+function effectiveDeployMode(mode, { canPushLocally, envForced } = {}) {
+  if (mode === 'laptop' && !envForced && !canPushLocally) return 'ci';
+  return mode;
+}
+
+function resolveDeployMode() {
+  let configRaw = null;
+  try {
+    configRaw = fs.readFileSync(path.join(REPO_ROOT, 'config', 'deploy.json'), 'utf8');
+  } catch (_) {
+    /* no config file → safe default */
+  }
+  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).
+  if (mode === 'laptop' && !envForced) {
+    return effectiveDeployMode(mode, { canPushLocally: ghAvailableAndAuthed(), envForced });
+  }
+  return mode;
+}
+
+// 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.
+function fetchDeployedVersion(url = 'https://amazonprimea.com/version') {
+  // 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;
+}
+
+// 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);
+}
+
+// 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 false;
+    }
+    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 && r.data && r.data.error === '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 false;
+    }
+    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 false;
+    }
+    if (!r.ok) {
+      const e = (r.data && (r.data.message || r.data.error)) || `HTTP ${r.status}`;
+      console.log(`  ci-land: server publish failed — ${e}. Task stays at confirmed. ${strandNextStep(taskId, 'server')}`);
+      return false;
+    }
+    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.
+function classifyLandOutcome(s) {
+  const merged = !!(s && s.merged);
+  const deployStatus = s && (s.deploy_status ?? s.deployStatus);
+  const prState = s && (s.pr_state ?? s.prState);
+  if (merged && deployStatus === 'success') return 'shipped';
+  if (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).`;
+}
+
+// Print 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).
+function printLandPending(taskId, { merged } = {}) {
+  console.log('');
+  console.log(`  ci-land: ✓ Published — auto-merge is armed${merged ? ' and the PR has merged' : ''}. This is NOT a failure.`);
+  console.log(`  CI is still finishing; GitHub will ${merged ? 'deploy' : 'merge + deploy'} automatically once the required checks pass,`);
+  console.log(`  and the task flips to 'shipped' on its own. Re-run \`node scripts/gds/ship.js ${taskId}\` anytime to confirm`);
+  console.log(`  it landed — it resumes from here (task 941). The task is at 'confirmed' until the deploy completes.`);
+}
+
+// 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)...');
+  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') {
+        console.log(`  ci-land: merged (${String(r.data.merge_sha || '').slice(0, 8)}) + deploy-prod succeeded. Prod is live.`);
+        return true;
+      }
+      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 false;
+      }
+    }
+    shellOk(POLL_SLEEP_CMD);
+  }
+  printLandPending(taskId);
+  return false;
+}
+
+// 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 false;
+  }
+
+  // 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 body =
+    `Auto-opened by ship.js (deploy mode: ci) for task ${taskId}.\n\n` +
+    `${sanitizeGitHubRefs(valueSummary) || '(no value summary)'}\n\n` +
+    `Merging this PR triggers .github/workflows/deploy-prod.yml to deploy to ` +
+    `https://amazonprimea.com. Auto-merge is enabled — GitHub lands it once the ` +
+    `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 false;
+    }
+  } 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 false;
+    }
+    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 false;
+  }
+  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);
+      if (status === 'match') {
+        console.log('  ci-land: /version confirms prod is live on the merge commit (commit-pinned).');
+      } else if (status === 'mismatch') {
+        console.log('  ci-land: deploy run succeeded; /version shows a different commit (a later deploy has since superseded it — fine, our change is in main).');
+      } else if (shellOk('curl -fsS --max-time 10 https://amazonprimea.com/healthz -o /dev/null')) {
+        console.log('  ci-land: /version unavailable; amazonprimea.com/healthz 200 — treating the successful deploy run as authoritative.');
+      } else {
+        console.log('  ci-land: deploy run succeeded but /version + healthz probes both missed (likely transient). Treating the successful deploy run as authoritative.');
+      }
+      return true;
+    }
+    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 false;
+}
+
+// ---------- 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.
+
+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' };
+    }
+  }
+
+  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 (.github/workflows/doc-ref-linkify.yml) runs on
+// push:main — i.e. AFTER ship's auto-merge has already landed the commit. So a
+// single bare "#NNN" task ref that slips into a doc red-Xes the build and
+// emails a failure for an already-merged commit. Caught post-merge, the gate is
+// pure noise: it can't prevent the leak, only complain about it (#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.
+//
+// #536: the grader's baseline is computed INDEPENDENTLY of touches[] — always
+// from merge-base, never gated on the declared scope. (Historically the
+// touches-gated drift scanner returned a null baseline for empty touches[],
+// which once blinded the grader to a fully-committed diff and hard-FAILed
+// empty-touches newcomer ships; the scanner is gone as of task 879, but the
+// grader keeping its own merge-base baseline remains the correct invariant.)
+function computeGraderBaseline(claim) {
+  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;
+}
+
+// --- 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 }) {
+  // 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 = 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
+  };
+  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({})} — 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,
+      runOpts,
+    });
+  } else {
+    const panel = grader.WORKERS.DEFAULT_PANEL;
+    console.log(`  subagent grader ${grader.VERSION}: panel of ${panel.length} workers (${panel.join(', ')}), model=${grader.DEFAULT_GRADER_MODEL} (assumed builder ${grader.ASSUMED_BUILDER_MODEL}), 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`);
+    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
+      runOpts,
+    });
+  }
+  const wallMs = Date.now() - t0;
+  // Decorate signals with the local shortstat — useful in audit-trail.
+  result.signals = {
+    ...(result.signals || {}),
+    diff_stats: shortstat,
+    wall_ms: wallMs,
+    changed_files_count: changedFiles.length,
+  };
+  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 };
+}
+
+// ---------- 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.
+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 in the core repo — a consumer instance has no devbox-app/, so skip.
+  // Resolve it WORKTREE-LOCALLY (like the generator above, __dirname=scripts/gds), NOT
+  // via REPO_ROOT: on a ship from a linked worktree REPO_ROOT is the MAIN checkout, so a
+  // REPO_ROOT path would vendor the main tree while gen-api-client just wrote THIS tree,
+  // leaving this worktree's vendored copy stale → the api_client byte-identity test reds
+  // the PR (task 2060 fix). __dirname keeps the generator, the vendored file, and the
+  // git add all on the same tree.
+  const vendorScript = path.join(__dirname, '..', '..', 'devbox-app', 'scripts', 'vendor-client.js');
+  if (fs.existsSync(vendorScript)) {
+    shellOk(`"${process.execPath}" ${JSON.stringify(vendorScript)}`);
+  }
+  const dirty = gitOk('git status --porcelain clients/bongos-client devbox-app/src/vendor/bongos-client.cjs');
+  if (!dirty) {
+    console.log('  API client already current — nothing to commit');
+    return 'current';
+  }
+  shellOk('git add clients/bongos-client devbox-app/src/vendor/bongos-client.cjs');
+  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') {
+    console.log(`  auto-merge: skipped (current branch is ${branch})`);
+    return false;
+  }
+
+  // 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 false;
+  }
+  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 false;
+  }
+  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 true;
+  }
+
+  // #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 false;
+  }
+
+  // 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 false;
+  }
+  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 false;
+    }
+
+    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 false;
+    }
+
+    // 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`);
+      return false;
+    }
+
+    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 false;
+    }
+
+    // #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 false;
+    }
+
+    console.log('  smoke against post-merge state...');
+    if (!runSmoke().clean) {
+      console.log('  auto-merge: post-merge smoke failed; task stays at confirmed; investigate');
+      return false;
+    }
+
+    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');
+      return false;
+    }
+
+    console.log('  triggering deploy on droplet...');
+    // Quote ~/deploy.sh so the LOCAL shell doesn't tilde-expand it to
+    // /Users/<mac-user>/deploy.sh before ssh transmits the command. With
+    // the quotes, ssh sends the literal `~/deploy.sh` and the REMOTE shell
+    // expands it to /home/lars/deploy.sh. (Matches /merge-mode SKILL.md:81.)
+    if (!shellOk(`ssh -o ConnectTimeout=10 ${DROPLET} "~/deploy.sh"`)) {
+      // task 984 / idea 180: ~/deploy.sh's internal /healthz curl can race the
+      // service-restart window (Node not yet bound) and exit non-zero even though
+      // the deploy succeeded — which used to false-fail the ship and force a
+      // needless /merge-mode. Before concluding failure, re-probe the public
+      // /healthz with backoff (curl's own --retry; cross-platform, no sleep).
+      // --retry-all-errors retries connection-refused during the bind window;
+      // -f makes a non-200 an error so a 502/503 also retries. If it comes up
+      // within the window the deploy really succeeded; only then-still-down fails.
+      console.log('  auto-merge: ~/deploy.sh returned non-zero — re-probing /healthz with backoff before concluding...');
+      if (shellOk('curl -fsS --max-time 10 --retry 5 --retry-delay 3 --retry-all-errors https://amazonprimea.com/healthz -o /dev/null')) {
+        console.log('  auto-merge: /healthz 200 on re-probe — deploy actually succeeded (deploy.sh raced the restart window). Proceeding.');
+      } else {
+        console.log('  auto-merge: deploy failed (/healthz never returned 200 after retries); task stays at confirmed');
+        return false;
+      }
+    }
+
+    // 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 true;
+  } 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}`);
+  }
+}
+
+// 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.
+async function gradeAndRecord({ taskId, task, summary, baseline, committedFiles }) {
+  // 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.');
+      // Re-POST 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,
+      };
+      const payload = { ...buildGradePayload(reusedResult, committedFiles), diff_hash: 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 = await runSubagentGrader({
+    task,
+    valueSummary: summary,
+    baseline,
+    changedFiles: committedFiles,
+  });
+  const payload = { ...buildGradePayload(gradeResult, committedFiles), diff_hash: 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>" https://amazonprimea.com/api/gds/tasks/${taskId}/confirm`);
+    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>" https://amazonprimea.com/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} (landed at confirmed)`);
+  } 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);
+}
+
+// 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;
+  }
+  if (!advanceToMerge) return;
+
+  console.log('');
+  console.log('Auto-merge chain (confirmed → shipped):');
+  const merged = await autoMerge(taskId, summary, { dbOnly });
+  if (!merged) return;
+
+  const ship = await (await cliClient()).tasks.postTasksIdShip({ id: taskId, body: {} });
+  if (!ship.ok) {
+    // task 1049: the server's publish-status reconcile-on-read may have already
+    // flipped this task to shipped (a concurrent status read saw merge+deploy).
+    // That's a SUCCESS — don't print it as a failure.
+    if (ship.status === 409 && ship.data && ship.data.error === 'task_not_confirmed') {
+      console.log(`Task #${taskId} is now: shipped (the server reconciled it from the merged PR).`);
+    } else {
+      console.error(`  /tasks/${taskId}/ship failed:`, ship.data);
+      return;
+    }
+  } 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.');
+  }
+}
+
+// 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 = 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 }) {
+  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 });
+  // 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 }) {
+  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 = 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 },
+      usage: { tokens, costUsd, newTokens, cachedTokens },
+      deploy: { commit },
+    };
+    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 */
+  }
+}
+
+// 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 || '';
+  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,
+      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 "..." --summary "..." [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty]');
+    process.exit(2);
+  }
+  const notes = arg('--notes', args) || '';
+  const summary = arg('--summary', args) || '';
+  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).
+  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty');
+  // 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');
+  // 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');
+
+  const me = 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. An
+  // Archon lifts the block by raising the builder's budget
+  // (PATCH /builders/:id/budget). 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 an 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 reach main and red-X the post-merge doc-ref-linkify gate.
+  // 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.)
+  console.log('Running smoke tests against production...');
+  const smoke = runSmoke();
+  const passed = smoke.clean;
+  console.log('');
+  console.log(`Verification: smoke=${smoke.clean ? 'clean' : 'FAIL'}, overall=${passed ? 'PASS' : 'FAIL'}`);
+  console.log('');
+
+  // ---- 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) {
+    if (r.data?.error === 'CLAIM_SESSION_MISMATCH') {
+      const wt = r.data.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 (${r.status}):`, r.data);
+    }
+    process.exit(1);
+  }
+
+  const taskStatus = r.data.taskStatus || 'shipped (legacy response)';
+  console.log(`Task #${r.data.taskId} is now: ${taskStatus}`);
+
+  // ---- 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 && confirm.data && confirm.data.error === '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);
+      }
+      console.error(`manual-confirm failed (${confirm.status}):`, confirm.data);
+      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...');
+
+    // Fetch the full task (description, kind, discipline, etc.) so the
+    // grader prompt has the intent the subagent is grading against.
+    const tFetch = await (await cliClient()).tasks.getTasksId({ id: taskId });
+    const fullTask = tFetch.ok ? tFetch.data.task : { id: taskId, title: ac.title };
+
+    // #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 runs the
+    // subagent grader, POSTs the result, and logs the panel cost — the same unit
+    // the --regrade path reuses.
+    const gradePost = await gradeAndRecord({
+      taskId,
+      task: fullTask,
+      summary,
+      baseline: graderBaseline,
+      committedFiles,
+    });
+
+    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.`);
+      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);
+  }
+
+  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). ----
+  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) ----------
+//
+// `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).
+//
+// 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 "..."] [--no-merge] [--force] [--verified]');
+    process.exit(2);
+  }
+  const summaryArg = arg('--summary', args) || '';
+  const skipMerge = args.includes('--no-merge');
+  const force = args.includes('--force');
+  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty'); // task 391 — honor --db-only on a regrade too
+  const verified = args.includes('--verified'); // task 1053 (F) — see gate below
+
+  // ---- Eligibility: completed + (owner | archon) ----
+  const me = 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=last_claim — opt into the claim-holder lookup (it's off by default
+  // so the supervisor hot path stays a single query; #678 quality finding).
+  const tRes = await (await cliClient()).tasks.getTasksId({ id: taskId, query: { include: '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);
+  }
+
+  // ---- Grade step (the only step) ----
+  console.log('');
+  console.log('Running subagent quality grader...');
+  const gradePost = await gradeAndRecord({
+    taskId,
+    task,
+    summary,
+    baseline: graderBaseline,
+    committedFiles,
+  });
+  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, or POST /confirm to manual-confirm.');
+    process.exit(1);
+  }
+
+  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 || [],
+  });
+
+  // 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 },
+    },
+  });
+}
+
+// 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 1003: transcript-grade scrubber internals, exported pure so the planted-
+  // secret corpus test (tests/scrubber_corpus.mjs) can exercise each layer + tune.
+  shannonEntropy, looksHighEntropySecret, redactHighEntropy, collectEnvSecrets,
+  classifyUploadSkip, recordUploadSkip,
+  // #678: re-grade path + the grade-step helpers it shares with shipMain.
+  // Exporting these formalizes learning #43 (which had to "replicate ~10
+  // lines" because runSubagentGrader wasn't reachable).
+  evaluateRegradeEligibility, computeGraderBaseline, computeChangedFiles,
+  runSubagentGrader, buildGradePayload,
+  // V4.R08: diff fingerprint + grade-reuse helpers — exported pure so the
+  // truth table (same hash+pass→reuse, fail→no reuse, mismatch→re-grade,
+  // null→re-grade) is unit-tested without git/network.
+  diffHash, computeRawDiffHash, shouldReuseGrade, gradeAndRecord,
+  // #943: pure grade-outcome formatter — exported so the grader-unavailable vs
+  // FAIL display branch is unit-tested without capturing stdout.
+  formatGradeOutcome,
+  // task 941 (V4.R03): pure resume-action decision for a claim-less `ship.js <id>`
+  // re-run — exported so the truth table (completed→grade, confirmed→merge,
+  // ownership, terminal states) is unit-tested with no git/network.
+  evaluateResumeAction,
+  // #747: pre-ship auto-linkify of the ship's own changed docs. The path
+  // predicate is pure + exported so the regression test can assert which
+  // changed files fall in the linkifier's domain without git/fs/API.
+  isLinkifiableDocPath,
+  // #681: shell-injection fix for autoMerge — argv git runner + pure merge-argv
+  // builder, exported so the regression test can prove no shell interpretation.
+  // task 916: sanitizeGitHubRefs keeps "#NNN" out of commit/PR text (GitHub
+  // autolinks it to dead issue numbers).
+  gitArgvOk, buildMergeArgv, sanitizeGitHubRefs,
+  // #679 / ADR 0042: CI deploy mode — pure helpers exported for the regression
+  // test (mode precedence/safe-default, no-shell PR argv, deploy-run match).
+  parseDeployMode, buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded,
+  // task 1049 (B): pure CI-land outcome classifier — a timed-out-but-armed PR is
+  // 'pending' (success), not failure. Exported so the semantics are unit-tested.
+  classifyLandOutcome,
+  // task 1718: pure poll-path decision — enable-failure polls the SERVER (not a
+  // dead-end strand at confirmed), enable-success watches GitHub. Exported so the
+  // regression test locks in that a worktree enable-failure still waits for the land.
+  landPollAfterAutoMerge,
+  // task 1719: pure post-land status reconciler — a task that reached 'shipped'
+  // in-session shows the SHIPPED banner + writes no breadcrumb; otherwise keep the
+  // pre-merge status (confirmed → next-turn breadcrumb fallback). Exported for tests.
+  reconciledCardStatus,
+  // task 1169 (ADR 0058): pure picker for the stale (completed-non-success)
+  // gate-review run on the current head SHA that must be re-run after the
+  // gate-author-trust attestation is posted (a new commit status doesn't
+  // re-trigger a pull_request check). Exported so the logic is tested without gh.
+  pickStaleGateReviewRun,
+  // task 1068: pure pre-stage-merge decision (skip on main/current, else merge).
+  decidePreMerge,
+  // task 1052 (E): box-aware "what to do next" for a confirmed-strand — a box
+  // (via 'server') is pointed at the resume, never at gh-only /merge-mode.
+  strandNextStep,
+  // #857: resolveDeployMode (env + committed config) so doctor.js reports the
+  // active deploy mode exactly as ship will use it.
+  resolveDeployMode,
+  // task 1449: pure credential-aware mode adjustment — a machine that can't push
+  // locally never honors a stale 'laptop' checkout (it would strand at merge);
+  // it falls back to ci/server-publish. Exported so the truth table is unit-tested
+  // without spawning gh / touching fs.
+  effectiveDeployMode,
+  // #858: commit-pinned deploy confirmation via the /version endpoint.
+  deployedCommitStatus,
+  // ADR 0055 / task 1025: which ci-mode publish path this machine uses
+  // ('local' = git+gh here; 'server' = server-mediated, e.g. a dev box) — so
+  // doctor.js reports the same path ship will take instead of failing on
+  // missing gh where gh isn't needed.
+  pushVia,
+  // task 1046: diagram regen returns a status string and SKIPS on the dev-box
+  // (server-publish) path so a box never leaves uncommitted .mmd/assertions in
+  // its tree — exported so the regression test proves the skip without git.
+  regenerateDiagrams,
+  regenerateRepoMap,
+  regenerateSessionIndex,
+  // ADR 0066 / task 1276: regenerate docs/file-map.md's skills + scheduled-tasks sections from disk.
+  regenerateFileMap,
+  // task 1037: autoMerge's fetch-failure decision — fatal only OFF the server-
+  // publish path (a credential-less dev box can't fetch but ships via ADR 0055).
+  // Exported pure so the regression test proves the truth table without git.
+  shouldBailOnFetchFailure,
+  // task 391 (idea #37): autoMerge's zero-commit verdict — refuse a zero-commit
+  // ship unless --db-only is explicitly passed. Exported pure so the gate is
+  // unit-tested (has-commits / db-only / refuse) without git.
+  zeroCommitVerdict,
+  // touches[] cleanup [3/8] (task 878): folder-tag derivation, now over the
+  // committed diff — exported pure so the regression test can assert it.
+  deriveTagsFromPaths,
+  // task 990: pure ship-broadcast router (security-sensitive → Archon-only
+  // #security-ship-feed; else public #ship-news + builder #ship-feed) —
+  // exported so tests/ship_broadcast_routing.mjs can prove the security branch
+  // can never reach a public channel, with no git/network. (Definition now lives
+  // in src/bongos/ship-broadcast.js — task 1045 — and is re-exported here.)
+  chooseBroadcastTargets,
+  // task 1045: the gate that defers the broadcast to the server on the server-
+  // mediated publish path — exported so the truth table (ci+server → true, laptop
+  // / non-ci → false) is unit-tested with no gh/network (env-driven via
+  // OTB_DEPLOY_MODE + OTB_PUSH_VIA_SERVER).
+  broadcastHandledByServer,
+};
+
+if (require.main === module) {
+  // #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;
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}