@bongos/core 1.19.319 → 1.19.320

package/scripts/gds/ship-flow.js

@@ -0,0 +1,814 @@
+// scripts/gds/ship-flow.js — the two entry flows — shipMain and regradeMain.
+//
+// Carved out of scripts/gds/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 3478-4259 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const { cliClient, requireSession, arg } = require('./cli-lib');
+const { resolveProse, markShipProgress, smokeGateMessages } = require('./ship-honesty.js');
+const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
+const { scopeForModule, isModuleKey } = require('../../src/bongos/module-scope-map');
+const { matchOne } = require('../../src/bongos/path-match');
+const { runShipGate } = require('./sandbox-stage');
+const { captureSurpriseLearning, promptSurprise } = require('./ship-surprise.js');
+const { gitOk } = require('./ship-git.js');
+const { autoLinkifyChangedDocs, mergeMainIntoBranch, preflight } = require('./ship-preflight-steps.js');
+const { applyBaseOverride, computeChangedFiles, computeGraderBaseline, runSmokeAsync } = require('./ship-grade.js');
+const { buildPriorRoundContext, computeGradeResult, gradeAndRecord, printCreditsAndAchievements, printGradeOutcome } = require('./ship-grade-steps.js');
+const { apiErrorLine, normalizeApiError } = require('./ship-io.js');
+const { diffstatFor, finishShip } = require('./ship-finish.js');
+const { evaluateRegradeEligibility, evaluateResumeAction, resumeMerge } = require('./ship-resume.js');
+const { noteServerReward } = require('./ship-state.js');
+
+// ---------- Main flow ----------
+
+async function shipMain() {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  if (!Number.isFinite(taskId)) {
+    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('  prefer the -file forms for prose: a shell command-substitutes backticks in an inline value before node sees it (learning 1000197).');
+    process.exit(2);
+  }
+  // G04: prose from a FILE or inline, never shell-mangled in silence.
+  const prose = resolveProse(args, ['notes', 'summary']);
+  const notes = prose.notes;
+  const summary = prose.summary;
+  const skipMerge = args.includes('--no-merge');
+  const force = args.includes('--force');
+  // task 391 (idea #37): a deliberate zero-commit / direct-SQL ship. Without it,
+  // a branch with no commits ahead of main is REFUSED (not silently shipped).
+  // task 1002422: --base <ref> also implies db-only — the work is already on main
+  // (that's the whole point of --base), so the merge leg has nothing to merge and
+  // advances straight to shipped. Unlike --allow-empty it does NOT skip the grade:
+  // the pinned baseline gives the grader a real diff (see resolveBaseRef / main).
+  const baseRefRaw = arg('--base', args);
+  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty') || Boolean(baseRefRaw);
+  // task 1053 (F): explicit attestation that a verification task's verify
+  // actually passed. Required to confirm a kind='verify' task (the server
+  // enforces it too); a no-op for every other task.
+  const verified = args.includes('--verified');
+  // #853 (ADR 0041): `let` not `const` — when the server has the temporary
+  // global grader bypass ON (surfaced as me.grader_bypass below), we force the
+  // skip-grade/confirm path for everyone so no builder runs the subagent grader
+  // during a grader outage window.
+  let skipGrade = args.includes('--skip-grade');
+  // task 1365: explicit acknowledgement that this task legitimately has NO
+  // committed artifact (a pure DB-only / no-op task). Required for the
+  // empty-diff guard below to ALLOW an empty committed diff; without it, an
+  // empty diff is refused (it used to slip through under --skip-grade — the
+  // task-1363 phantom ship). Never overrides a dirty working tree.
+  const allowEmpty = args.includes('--allow-empty');
+  // task 1002605 (G-18): explicit opt-in to continue past a FAILED production
+  // smoke run. Without it a smoke FAIL now ABORTS before the claim resolves
+  // (claim intact); with it, the resolve proceeds and the task deliberately
+  // parks at 'completed' ungraded — and the ship says so instead of "Done."
+  const allowSmokeFail = args.includes('--allow-smoke-fail');
+  // Surprise flag handling — see captureSurpriseLearning(). Resolved below
+  // once we know which claim is being shipped (so touches[] can become tags).
+  const surpriseRaw = arg('--surprise', args);
+  const surpriseProvided = surpriseRaw !== null;
+  const noSurprise = args.includes('--no-surprise');
+
+  // task 1002422 (blocker 1000082): resolve + validate --base BEFORE any heavy
+  // work so a bad ref aborts with the claim STILL ACTIVE. On success it sets the
+  // module-level baseOverrideSha that computeGraderBaseline() reads, so the grader
+  // reads <base>...HEAD (a real diff) and the ship takes the rank-open graded path
+  // instead of the --allow-empty → skip-grade → Archon-only /confirm dead-end.
+  if (baseRefRaw) {
+    const res = applyBaseOverride(baseRefRaw);
+    if (!res.ok) {
+      console.error(`Ship aborted: ${res.reason}. No claim resolved, no credits awarded.`);
+      console.error('Omit --base and ship normally — the grader reviews ALL your commits and the merge lands them. Your claim is still active.');
+      process.exit(2);
+    }
+    console.log(`--base: grading ${res.sha.slice(0, 9)}...HEAD — the task's real committed diff (work already on main). Graded via the rank-open path; no --allow-empty needed.`);
+  }
+
+  const me = noteServerReward(await (await cliClient()).me.getMe());
+  if (!me.ok) {
+    console.error('failed to load profile:', me.data);
+    process.exit(1);
+  }
+  // #853 (ADR 0041): honor the server-side global grader bypass. When ON, every
+  // builder lands work without the subagent grader (the /tasks/:id/confirm gate
+  // is relaxed to any-builder server-side to match). Default OFF.
+  if (me.data.grader_bypass && !skipGrade) {
+    skipGrade = true;
+    console.log('Note: GRADER_BYPASS_ENABLED is on server-side — skipping the subagent grader and confirming directly (temporary outage window).');
+  }
+  const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+  const ac = claims.find((c) => Number(c.task_id) === taskId);
+  if (!ac) {
+    // task 941 (V4.R03): no active claim in THIS session is NOT automatically a
+    // dead-end. The claim is consumed at resolve, so a ship that stalled AFTER it
+    // (grade fail → `completed`; merge/deploy fail → `confirmed`, the #1027 case)
+    // leaves no claim — but a plain re-run should RESUME the stalled leg, not
+    // strand the task. Route on the task's current status + ownership.
+    const tRes = await (await cliClient()).tasks.getTasksId({ id: taskId, query: { include: 'last_claim' } });
+    const task = tRes.ok ? tRes.data.task : null;
+    const lastClaim = tRes.ok ? (tRes.data.last_claim || null) : null;
+    const action = evaluateResumeAction({ task, lastClaim, builder: me.data.builder });
+    if (action.action === 'resume-grade') {
+      console.log(`Task #${taskId} is at 'completed' (grade stalled) and ${action.via === 'owner' ? 'you last held the claim' : 'you are an Archon'} — resuming the grade (no re-claim needed).`);
+      return regradeMain();
+    }
+    if (action.action === 'resume-merge') {
+      console.log(`Task #${taskId} is at 'confirmed' (merge/deploy stalled) and ${action.via === 'owner' ? 'you last held the claim' : 'you are an Archon'} — resuming the merge + deploy (no re-claim needed).`);
+      return resumeMerge(taskId, { summary, skipMerge, force, task, dbOnly });
+    }
+    if (action.action === 'done') {
+      console.log(action.reason);
+      return;
+    }
+    console.error(action.reason || `You don't have an active claim on task #${taskId}.`);
+    if (claims.length > 0) {
+      console.error(`Your active claims:`);
+      for (const c of claims) console.error(`  #${c.task_id}: ${c.title}`);
+    }
+    process.exit(1);
+  }
+
+  // ---- Hard cap: refuse to ship over the monthly budget (V3.R84 #302, C3) ----
+  // Shipping runs the subagent grader, which spends API $. If this builder is at
+  // or over their monthly budget, refuse here — BEFORE the grader runs and BEFORE
+  // the claim resolves, so the claim stays active and no cost is incurred. Any
+  // Metic+ builder lifts the block by raising the builder's budget
+  // (PATCH /builders/:id/budget — builder.budget.set, metic-floored since ADR 0157).
+  // Fail-open: a missing/unreadable cost status (e.g. an older server) never blocks a ship.
+  const costStatus = me.data.cost;
+  if (costStatus && costStatus.level === 'over') {
+    console.error('');
+    console.error(`Ship refused: monthly budget exceeded — $${costStatus.spend_mtd_usd} of $${costStatus.budget_mtd_usd} spent this month (${costStatus.pct_used}%).`);
+    console.error('Shipping runs the quality grader, which spends API budget. No claim resolved, no credits awarded.');
+    console.error('Ask any Metic or Archon to raise your monthly budget (PATCH /builders/:id/budget), then re-ship.');
+    process.exit(1);
+  }
+
+  // ---- Surprise gate: forced "anything surprise you?" prompt ----
+  //
+  // Resolve the user's intent into a single value: either a non-empty surprise
+  // string (capture a learning) or empty (no surprise, ship normally).
+  //   --surprise "text"   → capture
+  //   --surprise none     → no surprise
+  //   --surprise ""       → no surprise
+  //   --no-surprise       → no surprise
+  //   neither + TTY       → prompt
+  //   neither + non-TTY   → no surprise, with stderr warning
+  let surpriseText = '';
+  if (surpriseProvided) {
+    const v = (surpriseRaw || '').trim();
+    surpriseText = (v === '' || v.toLowerCase() === 'none') ? '' : v;
+  } else if (noSurprise) {
+    surpriseText = '';
+  } else if (process.stdout.isTTY && process.stdin.isTTY) {
+    surpriseText = await promptSurprise();
+    if (surpriseText.toLowerCase() === 'none') surpriseText = '';
+  } else {
+    console.error('warn: no --surprise or --no-surprise provided in non-interactive context; defaulting to no surprise.');
+    surpriseText = '';
+  }
+
+  // ---- Step 0: preflight (working tree + branch freshness) ----
+  console.log(`Verifying claim #${ac.claim_id} on task #${ac.task_id}: ${ac.title}`);
+  console.log('Preflight (working tree + branch freshness)...');
+  const pre = preflight(ac, { force });
+  if (!pre.ok) {
+    console.error('');
+    console.error(`Ship aborted: ${pre.reason}. No claim resolved, no credits awarded.`);
+    process.exit(1);
+  }
+
+  // ---- Step 0b: pull origin/main into the branch up front (#1068, gap 2) ----
+  // So the tree reviewed on the sandbox == the tree we ship — no post-approval
+  // re-stage loop. Skipped under --no-merge (a deliberate "don't touch main"
+  // opt-out). Aborts only on a genuine conflict, claim left intact.
+  if (!skipMerge) {
+    const m = mergeMainIntoBranch();
+    if (!m.ok) {
+      console.error('');
+      console.error(`Ship aborted: ${m.reason}.`);
+      console.error('No claim resolved, no credits awarded — your claim is still active.');
+      process.exit(1);
+    }
+  }
+
+  // ---- Capture surprise learning (if any) ----
+  if (surpriseText) {
+    console.log('Capturing surprise as a learning...');
+    await captureSurpriseLearning(surpriseText, ac, taskId);
+  }
+
+  // ---- Pre-verify: auto-linkify this ship's own changed docs (#747) ----
+  // Fix bare "#NNN" task refs in the docs this ship changed BEFORE the merge,
+  // so they never red-X the doc-ref-linkify gate (tests/linkify_check.mjs in
+  // the `unit` check). Best-effort.
+  autoLinkifyChangedDocs(ac);
+
+  // ---- Empty-diff / phantom-ship guard (must run BEFORE the review gate + resolve) ----
+  // #513 added this check, but at step 2 — AFTER the resolve below already
+  // landed the task at `completed` and consumed the claim. A builder who ran
+  // /builder-ship before committing then burned the claim and couldn't re-ship
+  // ("You don't have an active claim" — the task-595-regrade-gap). Observed
+  // live on #662 (Windows). Moving it here means an empty committed diff aborts
+  // cleanly with the claim STILL ACTIVE, so the builder can commit and re-run.
+  // The grader reads committed history (baseline...HEAD), independent of
+  // touches[] (see computeGraderBaseline). The computed list is reused by the
+  // grader at step 2 so we don't diff twice.
+  //
+  // task 1365: this guard now runs REGARDLESS of --skip-grade. The old version
+  // was gated on `!skipGrade`, so --skip-grade (and the server-side
+  // grader_bypass that forces skipGrade) sailed an empty committed diff straight
+  // through to resolve → manual-confirm → the publish reconciler then shipped a
+  // task with NO artifact on main (task 1363: a new doc left UNTRACKED, never
+  // committed, HEAD never moved — the ledger lied, CLAUDE.md §8). classifyEmptyShip
+  // splits the three cases: a dirty/untracked working tree means the deliverable
+  // was never committed (refuse, even under --allow-empty); a clean tree with an
+  // explicit --allow-empty is a genuine no-artifact/DB-only ship (allow); a clean
+  // tree without the flag is nothing-to-ship (refuse). Refusing here leaves the
+  // claim ACTIVE so the builder can commit + re-run.
+  const graderBaseline = computeGraderBaseline(ac);
+  const committedFiles = computeChangedFiles(graderBaseline);
+  if (committedFiles.length === 0) {
+    const verdict = classifyEmptyShip(gitOk('git status --porcelain'), { allowEmpty });
+    if (verdict.reason === 'uncommitted-work') {
+      console.error('Ship refused: nothing is committed on this branch, but your working tree has uncommitted changes:');
+      for (const f of verdict.uncommitted) console.error(`    - ${f}`);
+      console.error('');
+      console.error('Your work was never committed — shipping now would mark the task "shipped" with NO artifact on main (the ledger would lie).');
+      console.error('Stage + commit your work (e.g. `git add -A && git commit`), then re-run /builder-ship. Your claim is still active.');
+      process.exit(1);
+    }
+    if (verdict.reason === 'nothing-to-ship') {
+      console.error(`Nothing to ship: the committed diff vs ${graderBaseline || 'baseline'} is empty and the working tree is clean.`);
+      console.error('The grader reads committed history, not the working tree — commit your work on this branch, then re-run /builder-ship. Your claim is still active.');
+      console.error('If this task legitimately has no code/doc artifact (a pure DB-only or no-op task), re-run with --allow-empty.');
+      process.exit(1);
+    }
+    // verdict.reason === 'allow-empty': a deliberate no-artifact / DB-only ship.
+    // There is no committed diff for the subagent grader to read, so confirm
+    // directly (this is the DB-only path the old --skip-grade route served).
+    if (!skipGrade) skipGrade = true;
+    console.log('--allow-empty: no committed diff (no-artifact / DB-only ship) — confirming directly without the subagent grader.');
+  }
+
+  // ---- Module drift check (BV1.R53, task 1422) ----
+  // If the task carries a module_key, verify the committed diff doesn't stray
+  // into a DIFFERENT module's territory. "You said game, you touched dev-box" is
+  // the semantic violation this catches. Files outside all module scopes (docs,
+  // session logs, general scripts) are allowed — they're cross-cutting. Only
+  // contact with a DIFFERENT module's glob set is refused.
+  //
+  // The check is ADVISORY (warns but does not refuse) on the first cut because
+  // the module_key column is new and existing tasks may carry a broader diff scope
+  // until all tasks are labelled. Enforced tasks can opt in with --enforce-module.
+  // ac.module_key comes from getActiveClaimsForBuilder (t.module_key in the join).
+  const enforceModule = args.includes('--enforce-module');
+  if (ac.module_key && isModuleKey(ac.module_key) && committedFiles.length > 0) {
+    const declaredScope = scopeForModule(ac.module_key);
+    const { MODULE_SCOPE_MAP } = require('../../src/bongos/module-scope-map');
+    const moduleDriftFiles = committedFiles.filter((f) => {
+      if (declaredScope && matchOne(f, declaredScope.globs)) return false;
+      for (const [key, entry] of Object.entries(MODULE_SCOPE_MAP)) {
+        if (key === ac.module_key) continue;
+        if (matchOne(f, entry.globs)) return true;
+      }
+      return false;
+    });
+    if (moduleDriftFiles.length > 0) {
+      const msg = [
+        `\n⚠ Module drift detected: task is scoped to '${ac.module_key}' but ${moduleDriftFiles.length} file(s) touch a different module:`,
+        ...moduleDriftFiles.map((f) => `  - ${f}`),
+        '',
+        enforceModule
+          ? 'Refused (--enforce-module). Confine your changes to modules/' + ac.module_key + '/ or clear the module_key label.'
+          : 'Advisory — ship proceeds, but consider confining your changes to modules/' + ac.module_key + '/.',
+      ].join('\n');
+      console.log(msg);
+      if (enforceModule) process.exit(1);
+    }
+  }
+
+  // ---- Sandbox-first review gate (#927, ADR 0046) ----
+  // On a dev box, a diff that touches game surfaces must be STAGED on the
+  // builder's own live preview (sandbox-<login>.amazonprimea.com, ADR 0044)
+  // and reviewed in a browser before the claim resolves — see it running,
+  // get the chance to iterate, THEN decide to ship to the main game. Laptop
+  // sessions, non-game diffs, quick-tunnel boxes, and --skip-stage all pass
+  // through untouched. Interactive: stage + ask; declining aborts with the
+  // claim intact. Non-TTY (agent-driven sessions): stage, then abort with the
+  // review URL — the re-run after the human reviews passes on the fresh
+  // staged marker. Never hangs on stdin.
+  const sandboxGate = await runShipGate({
+    taskId,
+    files: committedFiles,
+    skipStage: args.includes('--skip-stage'),
+    // #1048: --approved records the builder's sign-off after they reviewed the
+    // staged change on their sandbox. Only honored on a re-run whose game state
+    // is already staged-fresh — it can't pre-approve an unstaged change.
+    approved: args.includes('--approved'),
+    tty: Boolean(process.stdout.isTTY && process.stdin.isTTY),
+  });
+  if (!sandboxGate.ok) {
+    if (sandboxGate.review) {
+      // task 1275: the in-review card — the SAME lifecycle card, amber, whose
+      // action is "Open in sandbox ↗" (the sandbox URL the owner asked to surface
+      // here). Best-effort, never blocks the pause.
+      try {
+        const shipCard = require('../../modules/lifecycle/ship-card');
+        const { added, removed } = diffstatFor(graderBaseline);
+        const model = shipCard.buildCardModel({
+          stage: 'review',
+          taskId,
+          title: ac.title,
+          valueSummary: summary,
+          fileCount: committedFiles.length || null,
+          added,
+          removed,
+          sandboxUrl: sandboxGate.url,
+        });
+        // task 1279: honour the builder's render-widgets knob (from the /me
+        // fetched at the top of shipMain; default ON if absent/older server).
+        const widgetsEnabled = me?.data?.render?.widgets_enabled !== false;
+        shipCard.emitCard(model, taskId, { widgetsEnabled });
+      } catch (_) { /* the review pause stands with or without the card */ }
+      // #1061 polish: a sandbox review pause is a DELIBERATE, expected
+      // checkpoint — not a failed ship. printReviewBlock already showed the URL
+      // + the --approved next step, so don't follow it with red "Ship aborted /
+      // no credits awarded" text that makes the review moment read as broken.
+      // Calm note on stdout (not stderr); the claim is left fully intact.
+      console.log('');
+      console.log('⏸  Paused for your sandbox review — this is expected, not an error.');
+      console.log('   Your claim is still active; nothing was lost.');
+      console.log('   Walk the change at the link above, then approve with: /builder-ship --approved');
+      process.exit(1);
+    }
+    console.error('');
+    console.error(`Ship aborted: ${sandboxGate.reason}.`);
+    console.error('No claim resolved, no credits awarded — your claim is still active.');
+    process.exit(1);
+  }
+  // #1048: the recorded sandbox self-approval (when the builder approved a
+  // staged game change), threaded into the resolve call below so the server
+  // persists it on the task. null on laptop ships, non-game diffs, quick-tunnel
+  // boxes, --skip-stage, and bare fresh-marker re-runs without --approved.
+  const sandboxReview = sandboxGate.sandboxReview || null;
+
+  // ---- Step 1+2: verify locally (smoke) — runs AFTER the review gate (#1061) ----
+  // touches[] cleanup [4/8] (task 879): the predictive drift scanner is gone;
+  // local verification is smoke-only. Smoke runs HERE (post-gate) so a review
+  // PAUSE doesn't bury the sandbox link under the smoke output — smoke only runs
+  // on the actual ship: the --approved re-run, or a laptop / non-game ship the
+  // gate waved straight through. (#1061 — the gate is a no-op for those, so this
+  // is the same single smoke run as before, just sequenced after it.)
+
+  // task 1002660: start the grade COMPUTATION now, so the multi-minute panel
+  // overlaps the smoke run + claim resolve instead of serializing behind them.
+  // computeGradeResult performs no server writes — the grade POST stays in the
+  // grade step below, after the resolve lands the task at 'completed'. On a
+  // smoke abort the in-flight panel is discarded (its partial spend is lost —
+  // rare, and cheaper than serializing every ship behind smoke).
+  let gradeCompute = null;
+  let fullTaskForGrade = null;
+  if (!skipGrade) {
+    const tFetch = await (await cliClient()).tasks.getTasksId({ id: taskId });
+    fullTaskForGrade = tFetch.ok ? tFetch.data.task : { id: taskId, title: ac.title };
+    console.log('Starting the quality grader panel (overlaps the smoke run — task 1002660)...');
+    gradeCompute = computeGradeResult({
+      taskId, task: fullTaskForGrade, summary,
+      baseline: graderBaseline, committedFiles,
+    });
+    gradeCompute.catch(() => {}); // an abort path must not die on an unhandled rejection
+  }
+
+  console.log('Running smoke tests against production...');
+  // task 1002660: the async twin — awaiting keeps the event loop free so the
+  // overlapped panel's subprocess callbacks progress while smoke runs.
+  const smoke = await runSmokeAsync();
+  const passed = smoke.clean;
+  console.log('');
+  console.log(`Verification: smoke=${smoke.clean ? 'clean' : 'FAIL'}, overall=${passed ? 'PASS' : 'FAIL'}`);
+  console.log('');
+
+  // task 1002605 (G-18): a smoke FAIL used to fall straight through into the
+  // claim resolve — claim consumed, grading silently skipped, task parked at
+  // 'completed', exit 0, and the builder read "Done." believing they shipped.
+  // Abort BEFORE the resolve instead — the same claim-preserving posture as the
+  // budget cap and the sandbox-review gate above. --allow-smoke-fail is the
+  // deliberate continuation; the parked message where the grader would have run
+  // says exactly where that leaves the task.
+  if (!passed && !allowSmokeFail) {
+    console.error('');
+    for (const line of smokeGateMessages(taskId).abort) console.error(line);
+    process.exit(1);
+  }
+
+  // ---- Step 1: resolve the claim (lands at completed) ----
+  // V3.R18 (#209): resolveClaim no longer runs the v1 deterministic grader.
+  // It now lands the task at `completed` when verification (smoke) passes, and
+  // stops. The v2 subagent grader (step 2 below) is what gates the credits +
+  // the completed→confirmed transition.
+  const r = await (await cliClient()).claims.postClaimsIdResolve({
+    id: ac.claim_id,
+    body: {
+    outcome: 'shipped',
+    notes_md: notes,
+    value_summary: summary,
+    verification: {
+      passed,
+      // touches[] cleanup [4/8] (task 879): the drift scanner is gone; with no
+      // scanner there is nothing to drift, so this audit-trail signal
+      // (grader.scoreScannerSmoke) is vacuously clean.
+      scanner_clean: true,
+      smoke_clean: smoke.clean,
+    },
+    // touches[] cleanup [7/8] (task 882): the real committed changed-files, so
+    // the server backfills touches[] from reality (the planning prediction is
+    // now optional). Same list the grader already used.
+    committed_files: committedFiles,
+    // #1048: the sandbox self-approval { stamp, url, method } when the builder
+    // reviewed + approved a staged game change. The server stamps by/at and
+    // persists it to tasks.sandbox_review. null = nothing to record.
+    sandbox_review: sandboxReview,
+    },
+  });
+  if (!r.ok) {
+    const resolveErr = normalizeApiError(r.data);
+    if (resolveErr.code === 'CLAIM_SESSION_MISMATCH') {
+      const wt = resolveErr.details.claimWorktree;
+      console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
+      console.error('You can only ship from the session that originally claimed this task.');
+      console.error(`To force-release from this session: node scripts/gds/release.js ${taskId} --force`);
+    } else {
+      console.error(`resolve failed: ${apiErrorLine(r.data, r.status)}`);
+    }
+    process.exit(1);
+  }
+
+  const taskStatus = r.data.taskStatus || 'shipped (legacy response)';
+  console.log(`Task #${r.data.taskId} is now: ${taskStatus}`);
+  // Claim CONSUMED, task at 'completed' — a crash from here needs fatalRecoveryLines.
+  markShipProgress('resolved', taskId);
+
+  // ---- Step 2: subagent quality grader ----
+  // Runs when local verification passed AND resolveClaim landed at completed.
+  // If verification did not pass we don't bother grading — the task stays at
+  // completed (or whatever resolveClaim returned) with no credits.
+  let credits = r.data.creditsAwarded ?? 0;
+  let postGradeStatus = taskStatus;
+  let postGradeJustUnlocked = r.data.just_unlocked || [];
+  let gradePassed = false;
+  let advanceToMerge = false;
+  let gradeObj = null; // task 1270: the grade result, hoisted for the completion card
+  // V3.R27 (#247): credit breakdown surfaced from the grade or confirm
+  // response. Kept separate from `credits` so we only print the multiplier
+  // line when the multiplier actually moved the payout.
+  let creditsRaw = null;
+  let creditsMultiplier = null;
+  let ideaBonusInfo = null;
+
+  if (passed && taskStatus === 'completed' && skipGrade) {
+    // Escape hatch: skip the subagent grader and manual-confirm. The
+    // task_grades row gets grader_kind='lars' so the audit trail captures
+    // that this ship bypassed the v2 grader.
+    console.log('');
+    console.log('--skip-grade: skipping subagent grader; manual-confirming via POST /tasks/:id/confirm.');
+    // task 1053 (F): pass the verify attestation. The server refuses to confirm a
+    // kind='verify' task without it (so a hardware-verify can't land before the
+    // verify ran). --verified is a no-op for every other kind.
+    const confirm = await (await cliClient()).tasks.postTasksIdConfirm({ id: taskId, body: { verified } });
+    if (!confirm.ok) {
+      if (confirm.status === 409 && normalizeApiError(confirm.data).code === 'verify_attestation_required') {
+        console.error('');
+        console.error(`This is a VERIFICATION task — it won't confirm until you attest the verify actually passed.`);
+        console.error(`Run the verification, then re-ship with --verified:`);
+        console.error(`  node scripts/gds/ship.js ${taskId} --verified`);
+        console.error(`(Your work is committed and the task is at 'completed' — re-running resumes, task 941.)`);
+        process.exit(1);
+      }
+      // task 1002613 (map P-1): the one genuine permission wall on the ship path
+      // used to surface as a raw envelope dump — an atom name is not a rank, and
+      // no remedy printed at the one station where self-service exists. Interpret
+      // it: name the wall, the floor (from the server's floors map — never
+      // hardcoded), and both ways forward.
+      const errObj = confirm.data && confirm.data.error;
+      const errCode = typeof errObj === 'string' ? errObj : (errObj && errObj.code);
+      if (confirm.status === 403 && errCode === 'permission_forbidden') {
+        const details = (errObj && typeof errObj === 'object' && errObj.details) || {};
+        const floor = details.floors && details.floors['task.confirm.grade_bypass'];
+        const floorNote = floor ? ` (floor: ${floor})` : '';
+        console.error('');
+        console.error(`✖ Confirming without a passing grade is permission-gated: task.confirm.grade_bypass${floorNote}.`);
+        console.error('  This is an authorization wall, not a verdict on your work.');
+        console.error('  Self-service: re-run WITHOUT --skip-grade to use the subagent grader, and if a');
+        console.error('  grade fails, fix its findings and re-run (unlimited, no attempt cap):');
+        console.error(`      node scripts/gds/ship.js ${taskId} --regrade`);
+        console.error(`  If the grade genuinely cannot pass, ask a builder whose role holds`);
+        console.error(`  task.confirm.grade_bypass${floorNote} to POST /api/gds/tasks/${taskId}/confirm.`);
+        process.exit(1);
+      }
+      console.error(`manual-confirm failed: ${apiErrorLine(confirm.data, confirm.status)}`);
+      process.exit(1);
+    }
+    postGradeStatus = confirm.data.taskStatus;
+    credits = confirm.data.creditsAwarded ?? 0;
+    ideaBonusInfo = confirm.data.ideaBonus ?? null;
+    advanceToMerge = postGradeStatus === 'confirmed';
+    gradePassed = true; // by builder fiat, not by grader
+  } else if (passed && taskStatus === 'completed') {
+    console.log('');
+    console.log('Running subagent quality grader...');
+
+    // #513 + #536: the grader reads COMMITTED history (baseline...HEAD), not
+    // the working tree. The empty-committed-diff guard now runs earlier — BEFORE
+    // the claim is resolved (see above) — so by the time we reach here the diff
+    // is guaranteed non-empty on the grader path. Reuse the baseline + file list
+    // computed there so we don't diff twice. #678: gradeAndRecord POSTs the
+    // result and logs the panel cost — the same unit the --regrade path reuses.
+    // task 1002660: the panel computation was started BEFORE the smoke gate
+    // (gradeCompute above) — hand it in so this step only waits out whatever
+    // panel time smoke + resolve didn't already absorb.
+    const gradePost = await gradeAndRecord({
+      taskId,
+      task: fullTaskForGrade || { id: taskId, title: ac.title },
+      summary,
+      baseline: graderBaseline,
+      committedFiles,
+      precomputed: gradeCompute,
+    });
+
+    if (!gradePost.ok) {
+      console.error(`grade POST failed (${gradePost.status}):`, gradePost.data);
+      console.error('Task stays at completed. Manual options:');
+      console.error(`  - Re-run /builder-ship ${taskId} to try grading again, or`);
+      console.error(`  - node scripts/gds/ship.js ${taskId} --regrade after fixing findings, or`);
+      console.error(`  - POST /api/gds/tasks/${taskId}/confirm to manual-confirm (last resort —`);
+      console.error('    permission-gated on task.confirm.grade_bypass).');
+      process.exit(1);
+    }
+
+    const g = gradePost.data.grade;
+    gradeObj = g;
+    gradePassed = g.passed;
+    advanceToMerge = gradePost.data.advanceToMerge;
+    postGradeStatus = gradePost.data.taskStatus;
+    credits = gradePost.data.creditsAwarded;
+    postGradeJustUnlocked = gradePost.data.just_unlocked || [];
+    // V3.R27 (#247): pull the multiplier breakdown + idea-bonus info forward.
+    creditsRaw = gradePost.data.creditsRaw ?? null;
+    creditsMultiplier = gradePost.data.creditsMultiplier ?? null;
+    ideaBonusInfo = gradePost.data.ideaBonus ?? null;
+
+    printGradeOutcome(g, taskId);
+  } else if (!passed && taskStatus === 'completed') {
+    // task 1002605 (G-18): the --allow-smoke-fail continuation. The resolve above
+    // consumed the claim with verification.passed=false, so the grader deliberately
+    // does not run. This used to be a silent fall-through; say where the task is.
+    console.log('');
+    for (const line of smokeGateMessages(taskId).parked) console.log(line);
+  }
+
+  printCreditsAndAchievements({
+    postGradeStatus, credits, creditsRaw, creditsMultiplier, ideaBonusInfo,
+    justUnlocked: postGradeJustUnlocked,
+  });
+
+  // ---- Step 3: confirmed→shipped tail (merge + deploy → memory/session sync →
+  // Done → onboarding nudge → completion card), shared with regradeMain via
+  // finishShip (#1093/C9). ----
+  // Graded. If it passed, only the merge remains — a different crash story.
+  if (postGradeStatus === 'confirmed' || postGradeStatus === 'shipped') {
+    markShipProgress(postGradeStatus === 'shipped' ? 'landed' : 'graded', taskId);
+  }
+  await finishShip({
+    taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly,
+    // task 1270: data for the deterministic completion card.
+    card: {
+      title: ac.title,
+      valueSummary: summary,
+      notes,
+      files: committedFiles,
+      baseline: graderBaseline,
+      creditsAwarded: credits,
+      // task 1275: a real grade ran → pass/fail + issues; otherwise (--skip-grade
+      // or server-side GRADER_BYPASS) it was confirmed without a grade → skipped,
+      // so the card reads "grade skipped" rather than implying a real pass.
+      grade: gradeObj
+        ? { passed: gradeObj.passed, issues: gradeObj.issues || [], panel: Array.isArray(gradeObj.workers) ? gradeObj.workers.length : null, skipped: false }
+        : { passed: gradePassed, skipped: true },
+    },
+  });
+}
+
+// ---------- Re-grade flow (#678) ----------
+//
+// `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-file <path|-> | --summary "..."] [--response-file <path|-> | --response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
+    process.exit(2);
+  }
+  const regradeProse = resolveProse(args, ['summary', 'response']);
+  const summaryArg = regradeProse.summary;
+  // task 1002662: the builder's response to the prior round's findings — how
+  // each was fixed, tracked (a task ref), or why it's out of scope. Rides to
+  // the panel fenced, under the delta re-grade policy.
+  const responseArg = regradeProse.response;
+  const skipMerge = args.includes('--no-merge');
+  const force = args.includes('--force');
+  // task 1002422: honor --base on regrade/resume too, so `--regrade --base <ref>`
+  // and shipMain's resume-grade dispatch grade the real <base>...HEAD diff and
+  // advance already-on-main work, instead of aborting "nothing to grade". Same
+  // 0-ahead security guard as shipMain (applyBaseOverride is the shared gate).
+  const baseRefRaw = arg('--base', args);
+  const dbOnly = args.includes('--db-only') || args.includes('--allow-empty') || Boolean(baseRefRaw); // task 391 — honor --db-only on a regrade too
+  const verified = args.includes('--verified'); // task 1053 (F) — see gate below
+
+  if (baseRefRaw) {
+    const res = applyBaseOverride(baseRefRaw);
+    if (!res.ok) {
+      console.error(`Regrade aborted: ${res.reason}. Omit --base and re-grade normally.`);
+      process.exit(2);
+    }
+    console.log(`--base: re-grading ${res.sha.slice(0, 9)}...HEAD (work already on main).`);
+  }
+
+  // ---- Eligibility: completed + (owner | archon) ----
+  const me = noteServerReward(await (await cliClient()).me.getMe());
+  if (!me.ok) {
+    console.error('failed to load profile:', me.data);
+    process.exit(1);
+  }
+  const builder = me.data.builder || {};
+  // ?include=grade,last_claim — the claim-holder lookup for eligibility (#678)
+  // + the stored grade row for the delta-aware prior-round payload (task 1002662).
+  const tRes = await (await cliClient()).tasks.getTasksId({ id: taskId, query: { include: 'grade,last_claim' } });
+  if (!tRes.ok) {
+    if (tRes.status === 404) {
+      console.error(`Task #${taskId} not found.`);
+    } else {
+      console.error(`failed to load task #${taskId} (${tRes.status}):`, tRes.data);
+    }
+    process.exit(1);
+  }
+  const task = tRes.data.task;
+  const lastClaim = tRes.data.last_claim || null;
+  // pushVia() decides whether /merge-mode is even runnable here (task 1003221).
+  const elig = evaluateRegradeEligibility({ task, lastClaim, builder, pushMode: pushVia() });
+  if (!elig.ok) {
+    console.error(elig.reason);
+    process.exit(1);
+  }
+  // task 1053 (F): the resume/regrade path promotes completed→confirmed via the
+  // grade (applyGrade), which the server-side /confirm verify guard does NOT
+  // cover. Gate it here so a verification task can't be confirmed by simply
+  // re-running without attesting the verify passed (closing the bypass).
+  if (task.kind === 'verify' && !verified) {
+    console.error('');
+    console.error(`Task #${taskId} is a VERIFICATION task — it won't confirm until you attest the verify actually passed.`);
+    console.error(`Run the verification, then re-run with --verified:`);
+    console.error(`  node scripts/gds/ship.js ${taskId} --verified`);
+    process.exit(1);
+  }
+  console.log(`Re-grading task #${taskId}: ${task.title}`);
+  console.log(`  eligibility: ${elig.reason} (${elig.via})`);
+
+  // A grade-failed ship never reached the merge/broadcast step, so a passing
+  // re-grade is the FIRST time this task actually ships. Fall back to the
+  // task's stored value_summary so the merge commit + Discord #ship-news post
+  // carry meaningful text even when --summary is omitted.
+  const summary = summaryArg || task.value_summary || '';
+
+  // The grader helpers want a claim-like object for touches[] (preflight's
+  // working-tree-drift check) and head_sha (baseline fallback). The claim is
+  // gone, so synthesize one from the task row + the last claim's head_sha.
+  const claimLike = { touches: task.touches || [], head_sha: lastClaim?.head_sha ?? null, task_id: taskId, title: task.title };
+
+  // ---- Preflight: work committed + ship/grade tooling current ----
+  // No scanner/smoke re-run — --regrade re-runs ONLY the grade step. But the
+  // grader judges COMMITTED history, so uncommitted fixes on touches[] files
+  // wouldn't be graded — refuse that (it would grade a stale diff). Also refuse
+  // if the local ship/grade tooling is behind main (a stale grader silently
+  // fails the same way — the #662 lesson). --force overrides the freshness leg.
+  console.log('Preflight (working tree + branch freshness)...');
+  const pre = preflight(claimLike, { force });
+  if (!pre.ok) {
+    console.error('');
+    console.error(`Re-grade aborted: ${pre.reason}. Task stays at completed.`);
+    process.exit(1);
+  }
+
+  // ---- Empty-diff guard (the grader reads committed history) ----
+  const graderBaseline = computeGraderBaseline(claimLike);
+  const committedFiles = computeChangedFiles(graderBaseline);
+  if (committedFiles.length === 0) {
+    console.error(`Nothing to grade: the committed diff vs ${graderBaseline || 'baseline'} is empty.`);
+    console.error('The grader reads committed history, not the working tree — commit your fixes on this branch, then re-run --regrade.');
+    process.exit(1);
+  }
+
+  // ---- Delta-aware prior-round context (task 1002662) ----
+  // The prior grade's findings + the builder's response + the interim fix diff
+  // ride to the panel so an already-answered finding can't re-veto on
+  // re-wording alone. The interim range comes from the prior grade's
+  // signals.graded_head_sha (recorded by runSubagentGrader since this task);
+  // older grade rows lack it — the findings still ride, just without the diff.
+  const storedGradeRow = tRes.data.grade ?? null;
+  let interimCommits = '';
+  let interimDiffStat = '';
+  const priorSha = storedGradeRow?.signals?.graded_head_sha;
+  // The sha comes from a DB JSONB blob — validate the shape before shelling out.
+  if (typeof priorSha === 'string' && /^[0-9a-f]{7,40}$/i.test(priorSha) && gitOk(`git rev-parse --verify --quiet ${priorSha}`)) {
+    interimCommits = gitOk(`git log --oneline ${priorSha}..HEAD`) || '';
+    interimDiffStat = gitOk(`git diff --stat ${priorSha}..HEAD`) || '';
+  }
+  const priorRound = buildPriorRoundContext({
+    storedGrade: storedGradeRow,
+    responseText: responseArg,
+    interimCommits,
+    interimDiffStat,
+  });
+  if (priorRound) {
+    console.log(`  prior round context: ${priorRound.audit.prior_findings_count} finding(s) from the prior grade${priorRound.audit.response_present ? ' + builder response' : ''}${priorRound.audit.interim_present ? ' + interim fix diff' : ''} → round ${priorRound.audit.round}`);
+  }
+
+  // ---- Grade step (the only step) ----
+  console.log('');
+  console.log('Running subagent quality grader...');
+  const gradePost = await gradeAndRecord({
+    taskId,
+    task,
+    summary,
+    baseline: graderBaseline,
+    committedFiles,
+    priorRound,
+  });
+  if (!gradePost.ok) {
+    console.error(`grade POST failed (${gradePost.status}):`, gradePost.data);
+    console.error('Task stays at completed. Fix the issue and re-run --regrade (unlimited, no attempt cap).');
+    console.error('(POST /confirm is a last resort — it is permission-gated on task.confirm.grade_bypass.)');
+    process.exit(1);
+  }
+
+  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 = {
+  regradeMain,
+  shipMain,
+};