@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/ship-flow.js

@@ -0,0 +1,1217 @@
+// scripts/bongos/ship-flow.js — the two entry flows — shipMain and regradeMain.
+//
+// Carved out of scripts/bongos/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, detectWorktreeName, cardFlagsFromMe, apiCall, cliExit } = require('./cli-lib');
+// task 1004630: the first ship asks for the ship mode once (ADR 0369).
+const { runFirstShipAsk } = require('./ship-mode-ask.js');
+const { resolveProse, markShipProgress, smokeGateMessages, proseFlagPresent, regradeNotesRefusal, staleSummaryNotice } = require('./ship-honesty.js');
+const { plainCardLines } = require('./plain-cards.js');
+const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
+const { isModuleKey, scopeForModule, moduleDriftFiles: computeModuleDrift } = require('../../src/bongos/module-scope-map');
+const { runShipGate } = require('./sandbox-stage');
+const { captureSurpriseLearning, promptSurprise } = require('./ship-surprise.js');
+// task 1003109: the optional `--visual` leg of a ship (goal 1000072).
+const shipVisual = require('./ship-visual.js');
+const { gitOk } = require('./ship-git.js');
+const { autoLinkifyChangedDocs, mergeMainIntoBranch, preflight, shipInputPaths } = 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, isUnknownFieldRejection } = require('./ship-io.js');
+// task 1003205's carve left pushVia() used at regradeMain but never imported, so
+// EVERY resume of a 'completed' task died with ReferenceError before resolving.
+const { pushVia } = require('./ship-deploy-target.js');
+
+const { diffstatFor, finishShip } = require('./ship-finish.js');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
+const { evaluateRegradeEligibility, evaluateResumeAction, resumeMerge, shouldConfirmWithoutGrade } = require('./ship-resume.js');
+const { fileNoArtifactEscalation, noArtifactRefusalLines } = require('./ship-escalation.js');
+const { noteServerReward } = require('./ship-state.js');
+// task 1004536: each graded round lands in the autonomous run's ledger (inert
+// without one), so ship.js can refuse a third grade at its entry point.
+const { recordGradeOutcome } = require('./autobongos-grade-cap.js');
+// task 1004631: on a Manual project an AI session asks before it ships (ADR 0369).
+const manualShip = require('./ship-mode-manual.js');
+
+// stopForManualApproval(args, taskId) — Manual ship mode (task 1004631, ADR 0369). Every path
+// that can LAND work calls this first: a fresh ship, a resumed merge, and a re-grade (whose pass
+// runs finishShip). When an AI session runs it on a Manual project without the person's yes, it
+// prints the ask, exits 5 and returns true; the caller returns. A mode that cannot be read is
+// Auto and never stops a ship. Who is stopped is ship-mode-manual.js's pure verdict.
+async function stopForManualApproval(args, taskId) {
+  let shipMode = null;
+  try {
+    const r = await apiCall('GET', '/api/bongos/project-settings/ship-mode');
+    shipMode = r.ok ? r.data : null;
+  } catch (_) { shipMode = null; }
+  if (!manualShip.manualShipVerdict({ shipMode, args }).stop) return false;
+  for (const line of manualShip.manualAskLines(args, taskId)) console.log(line);
+  cliExit(manualShip.MANUAL_ASK_EXIT);
+  return true;
+}
+
+// ---------- 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/bongos/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--visual <image>] [--visual-alt "caption"] [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>] [--ship-mode auto|manual]');
+    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 1003950: set only when the empty-diff guard below classifies this ship as a
+  // deliberate no-artifact close. Gates the auto-escalation at the confirm wall.
+  let noArtifactClose = false;
+  // task 1004011: this ship has no committed diff, so the grade's subject is the
+  // builder's CLAIM (notes + value summary) rather than a diff. Distinct from
+  // noArtifactClose, which marks the older "reached the archon gate" case: a ship
+  // can now be no-artifact and still fully graded, which is the point.
+  let noArtifactGrade = false;
+  // 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.`);
+  }
+
+  // task 1003109: screen --visual BEFORE any heavy work, so bad input aborts with
+  // the claim STILL ACTIVE (the --base posture above). null when none was asked for.
+  const visual = shipVisual.fromArgs(args);
+
+  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({ visual });
+    }
+    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).`);
+      if (await stopForManualApproval(args, taskId)) return; // a resumed land is a ship too (task 1004631)
+      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);
+  }
+
+  // ---- First ship asks for the ship mode, once (task 1004630, ADR 0369) ----
+  // A project that never chose Auto or Manual stops HERE, before anything resolves,
+  // so the AI can ask the person; the re-run carries --ship-mode and saves it. Never
+  // blocks a ship nobody can answer for (see ship-mode-ask.js).
+  const firstShip = await runFirstShipAsk({
+    args,
+    getShipMode: async () => {
+      const r = await apiCall('GET', '/api/bongos/project-settings/ship-mode');
+      return r.ok ? r.data : null;
+    },
+    saveShipMode: (mode) => apiCall('PATCH', '/api/bongos/project-settings/ship-mode', { mode }),
+  });
+  if (firstShip.stop) {
+    for (const line of firstShip.lines) console.log(line);
+    cliExit(firstShip.exit);
+    return;
+  }
+
+  // ---- 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);
+  }
+
+  // ---- Manual ship mode: an AI session asks the person first (task 1004631, ADR 0369) ----
+  // Before anything resolves, so a "not yet" leaves the claim exactly as it was.
+  if (await stopForManualApproval(args, taskId)) return;
+
+  // ---- 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)...');
+  // task 1001436: inputFiles keeps --notes-file/--summary-file/--visual out of the
+  // preflight's untracked-file warning — they are this ship's input, not its artifact.
+  const pre = preflight(ac, { force, inputFiles: shipInputPaths(args) });
+  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.');
+      for (const line of plainCardLines('uncommitted_work')) console.error(line);
+      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.');
+      for (const line of plainCardLines('nothing_to_ship')) console.error(line);
+      process.exit(1);
+    }
+    // verdict.reason === 'allow-empty': a deliberate no-artifact / DB-only ship.
+    //
+    // task 1004011 (ADR 0320): this used to force `skipGrade = true` — no grade at
+    // all, then the Archon-only `task.confirm.grade_bypass` gate. Both halves were
+    // wrong. An empty diff is not an UNGRADED diff, it is a diff the grader has
+    // nothing to say about, so it should not need the key that ratifies past a
+    // FAILING grade. And something here does deserve adversarial scrutiny: not the
+    // absent diff, but the CLAIM that nothing was needed. "The premise was already
+    // fixed", "this was a pure ops verification" are assertions the ledger records
+    // and, until now, nothing checked.
+    //
+    // So the grader is no longer skipped — it is re-pointed at the notes. A pass is
+    // a REAL passing grade and confirms through the ordinary rank-open path; a fail
+    // is a real fail, and the builder fixes the evidence rather than reaching for a
+    // permission. skipGrade stays false; only an explicit --skip-grade still skips.
+    // Set only when a grade will actually run. With --skip-grade (or the server-side
+    // grader_bypass, which forces skipGrade above) the `if (!skipGrade)` gate below
+    // skips grading entirely and this flag would be inert — but an inert flag makes a
+    // reader trace two of them to see why nothing happened, and invites a later
+    // refactor to treat it as "this ship graded its notes" when it graded nothing.
+    noArtifactGrade = !skipGrade;
+    // task 1003950: mark WHY the grader is being skipped. A --skip-grade ship past a
+    // failing grade and a genuinely artifact-free close both reach the same archon
+    // gate below, but only the second one may be escalated automatically — the first
+    // has a diff the grader DID read and reject, and auto-filing a blocker for it
+    // would be a builder routing their own rejected work to an override queue.
+    //
+    // Still set, and still needed: since task 1004011 this close reaches the archon
+    // gate only when the builder ALSO passed --skip-grade, or the server bypassed
+    // the grader for them. Those are the cases where the escalation split still
+    // decides which refusal is printed.
+    noArtifactClose = true;
+    console.log('--allow-empty: no committed diff (no-artifact / DB-only ship).');
+    if (noArtifactGrade) {
+      console.log('  The grader is not skipped — it is re-pointed: your handoff notes and value summary are graded');
+      console.log('  against the task description, so the claim that nothing was needed is what gets checked (task 1004011).');
+    } else {
+      console.log('  The grader is skipped (--skip-grade / server bypass), so the claim is NOT checked — this close');
+      console.log('  routes to the archon confirm gate. Drop --skip-grade to have your notes graded instead.');
+    }
+  }
+
+  // ---- 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 provisioning" is
+  // the semantic violation this catches. Files no module owns are allowed —
+  // they're cross-cutting — as is the territory of a CROSS-CUTTING module, which
+  // every craft legitimately writes into. Only contact with a different OWNING
+  // module's glob set is flagged.
+  //
+  // The rule itself lives in module-scope-map.js (moduleDriftFiles) next to the
+  // map it reads, so it can be tested without running a ship (task 1003770). It
+  // used to be inline here, and read "files outside all module scopes (docs,
+  // session logs, general scripts) are allowed" — a premise task 1002989 ended by
+  // giving `methodology` the whole docs/ subtree. Since every ship writes a
+  // session log, the advisory then fired for 25 of the 26 module keys on that log
+  // alone. See CROSS_CUTTING_KEYS for why the glob was not shrunk instead.
+  //
+  // 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 moduleDriftFiles = computeModuleDrift(ac.module_key, committedFiles);
+    if (moduleDriftFiles.length > 0) {
+      // Name the module's REAL territory rather than guessing 'modules/<key>/'.
+      // That guess is wrong for every module whose code has not been carved out
+      // yet (ADR 0083) — kernel lives in src/bongos/, methodology in docs/ — so
+      // the advisory used to tell those builders to move their work somewhere
+      // their module does not own. scopeForModule is the roster's own answer.
+      const declared = scopeForModule(ac.module_key);
+      const territory = declared && declared.globs.length
+        ? declared.globs.slice(0, 4).join(', ') + (declared.globs.length > 4 ? `, +${declared.globs.length - 4} more` : '')
+        : `modules/${ac.module_key}/`;
+      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}`),
+        '',
+        `  '${ac.module_key}' owns: ${territory}`,
+        '',
+        enforceModule
+          ? `Refused (--enforce-module). Confine your changes to that territory, or clear the module_key label.`
+          : 'Advisory — ship proceeds, but consider confining your changes to that territory.',
+      ].join('\n');
+      console.log(msg);
+      if (enforceModule) process.exit(1);
+    }
+  }
+
+  // ---- Sandbox-first review gate (#927, ADR 0046) ----
+  // On a clone that carries the game preview, a diff that touches game
+  // surfaces must be STAGED on the builder's own local preview (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. A
+  // checkout with no game preview, non-game diffs, 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 / 1002518: honour the builder's card-richness level (from the
+        // /me fetched at the top of shipMain; the standard rung if absent, and
+        // the boolean's old meaning against an older server).
+        shipCard.emitCard(model, taskId, { flags: cardFlagsFromMe(me) });
+      } 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 a checkout with no game preview, non-game
+  // diffs, --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(noArtifactGrade
+      ? 'Starting the no-artifact grader over your notes (overlaps the smoke run — task 1002660)...'
+      : 'Starting the quality grader panel (overlaps the smoke run — task 1002660)...');
+    gradeCompute = computeGradeResult({
+      taskId, task: fullTaskForGrade, summary,
+      baseline: graderBaseline, committedFiles,
+      // task 1004011: present ⇒ grade the claim, not the (empty) diff. The notes
+      // are the evidence, so they have to travel with it.
+      noArtifact: noArtifactGrade ? { notes } : null,
+    });
+    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);
+    for (const line of plainCardLines('smoke_failed')) 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 resolveBody = {
+    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
+      // (read by the retired v1 grader, task 1002842) 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,
+    // task 1003767: the working tree this ship is running in, so the server's
+    // resolve lock can key on the TREE instead of the auth session. Without it
+    // a /builder-reauth mid-claim re-issued the session and stranded the ship
+    // with `release --force` (forfeiting graded work) the only way out. Same
+    // detector claim.js uses, so the two names always agree.
+    resolver_worktree: detectWorktreeName(),
+  };
+  let r = await (await cliClient()).claims.postClaimsIdResolve({ id: ac.claim_id, body: resolveBody });
+
+  // FORWARD COMPATIBILITY (task 1003767). The resolve route validates STRICTLY:
+  // an unknown body field is a hard 400, not an ignored extra. @cloudbongos/cli
+  // is published separately from the core and instances pin their own core
+  // version, so a CLI carrying a field the server has not learned yet would
+  // otherwise be unable to ship AT ALL against that instance — the diff that
+  // added `resolver_worktree` hit exactly this on its own ship.
+  //
+  // So: if the server rejects specifically because it does not know
+  // `resolver_worktree`, drop it and retry ONCE. The lock then falls back to
+  // the session compare server-side, which is what an older core did anyway —
+  // no behaviour is lost that that server ever had.
+  //
+  // Deliberately narrow: it retries only when the details name THIS field as
+  // unknown. Any other validation failure — including an unknown field we did
+  // not send on purpose — still surfaces, so this cannot mask a real bug.
+  if (!r.ok && isUnknownFieldRejection(r.status, r.data, 'resolver_worktree')) {
+    console.error("note: this instance's core predates resolver_worktree — retrying without it.");
+    console.error('      (the resolve lock falls back to the session check on that server.)');
+    delete resolveBody.resolver_worktree;
+    r = await (await cliClient()).claims.postClaimsIdResolve({ id: ac.claim_id, body: resolveBody });
+  }
+  if (!r.ok) {
+    const resolveErr = normalizeApiError(r.data);
+    if (resolveErr.code === 'CLAIM_SESSION_MISMATCH') {
+      const wt = resolveErr.details.claimWorktree;
+      // task 1003767: name WHICH lock fired. 'worktree_mismatch' means the claim
+      // really was made in another working tree — the branch this ship would
+      // publish is not the branch that did the work, so shipping here would land
+      // the wrong commits. That is the guard doing its job, and the fix is to run
+      // the ship from the right tree, NOT to force-release. Only a fallback
+      // 'session_mismatch' (no tree named on one side — a plain clone, or an
+      // older CLI) is the historical session case.
+      if (resolveErr.details.reason === 'worktree_mismatch') {
+        console.error(`This claim belongs to a different working tree${wt ? ` (worktree: ${wt})` : ''}.`);
+        console.error(`Ship it from there — its branch holds the work: cd .claude/worktrees/${wt || '<name>'}`);
+        console.error('Shipping from this tree would publish the wrong branch, which is why it is refused.');
+      } else {
+        console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
+        console.error('No working tree was named on one side, so the older session check applied.');
+      }
+      console.error(`If the work is genuinely gone, give the task back: node scripts/bongos/release.js ${taskId} --force`);
+      console.error('(--force abandons the claim and forfeits its credits — it is the give-up exit, not the fix.)');
+    } 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}`);
+  // task 1003109: attach the optional visual now the claim has resolved (the upload
+  // gate is "the task's last claim holder" — still us). Best-effort: it prints its
+  // own warning, and a failed picture never fails a successful ship.
+  await shipVisual.upload({ taskId, visual, client: await cliClient(), errorLine: apiErrorLine });
+  // 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 held = false; // task 1004322: a page tweak's pass, held for its artist (ADR 0341 D7)
+  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/bongos/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})` : '';
+        // task 1003950: these two cases used to print the same advice, and for a
+        // no-artifact close that advice was a LOOP — --regrade on an empty diff
+        // refuses and points back at --allow-empty, which lands here again. Split
+        // them: a rejected-grade bypass still has a real diff and a real remedy
+        // (fix the findings, re-grade); an artifact-free close has neither, so it
+        // gets the escalation filed for it and terminates.
+        if (noArtifactClose) {
+          const escalation = await fileNoArtifactEscalation({
+            taskId, title: ac.title, floor, summary, notes, builder: (me.data.builder || {}).github_login,
+          });
+          for (const line of noArtifactRefusalLines({ taskId, floor, escalation })) console.error(line);
+          process.exit(1);
+        }
+        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/bongos/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/bongos/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(noArtifactGrade
+      ? 'Running the no-artifact grader (subject: your claim that nothing was needed)...'
+      : '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, EXCEPT on the task 1004011
+    // no-artifact species, where it is guaranteed empty and the notes are the
+    // subject instead. 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,
+      // No `noArtifact` here on purpose: `precomputed` is ALWAYS set on this path, and
+      // gradeAndRecord only falls back to computing inline when it is absent. Passing it would be
+      // unreachable by construction — defensive symmetry that reads like a live argument. The
+      // species reaches the grader through gradeCompute above, which was built with it.
+    });
+
+    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/bongos/ship.js ${taskId} --regrade after fixing findings, or`);
+      console.error(`  - POST /api/bongos/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;
+    recordGradeOutcome({ taskId, grade: g });
+    gradeObj = g;
+    gradePassed = g.passed;
+    advanceToMerge = gradePost.data.advanceToMerge;
+    held = gradePost.data.held === true;
+    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, held,
+  });
+
+  // ---- 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, held,
+    // 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 },
+    },
+  });
+}
+
+// persistRegradeSummary — store a re-grade's corrected --summary on the task row
+// (task 1003817). A re-grade has no claim, so it cannot reach claim-resolve, the
+// only writer of tasks.value_summary before this; PATCH /tasks/:id is the route
+// it uses instead.
+//
+// WHY PATCH AND NOT publish-branch, which already RECEIVES value_summary and
+// could have persisted it with a one-line change: publish-branch is only called
+// when pushVia() === 'server'. A laptop land goes through ciLandLocal (gh), and
+// --no-merge / --db-only / --allow-empty never land at all — so persisting there
+// would have fixed one path of four and left the defect standing on the rest. It
+// would also have made publish-branch a SECOND writer racing claim-resolve on
+// the normal ship path, which sends the same field. Writing from here keeps one
+// writer per ship: the claim on a first ship, this on a re-grade.
+//
+// Three deliberate postures:
+//   - OMITTED --summary writes NOTHING. The stored value is the fallback the
+//     grader was already handed, so a re-grade that omits the flag must leave
+//     the row exactly as it was — the COALESCE/NULLIF posture every other
+//     value_summary write in db-ship.js keeps. This is acceptance 2.
+//   - UNCHANGED text writes nothing either, so a no-op edit mints no audit_log row.
+//   - A FAILURE is LOUD BUT NON-BLOCKING. The grade is the expensive step and it
+//     has not run yet; discarding a re-grade over a summary that did not persist
+//     would trade the cheap problem for the costly one. The builder is told
+//     plainly that the row still holds the old sentence, so nothing is silent.
+//     An older pinned core that has not learned the field is named as exactly
+//     that rather than reported as a generic error — the same forward-compat
+//     posture the resolve call in shipMain documents at length (task 1003767),
+//     because @cloudbongos/cli ships separately from the core and an instance
+//     pins its own core version.
+async function persistRegradeSummary({ taskId, summaryArg, task }) {
+  const next = (summaryArg || '').trim();
+  if (!next) return { written: false, reason: 'omitted' };
+  if (next === (task.value_summary || '').trim()) return { written: false, reason: 'unchanged' };
+  let r;
+  try {
+    r = await (await cliClient()).tasks.patchTasksId({ id: taskId, body: { value_summary: next } });
+  } catch (err) {
+    console.error(`  ⚠ value_summary NOT stored (${err && err.message ? err.message : 'request failed'}) — task #${taskId} keeps its previous summary. The grade below is unaffected.`);
+    return { written: false, reason: 'error' };
+  }
+  if (!r.ok) {
+    if (isUnknownFieldRejection(r.status, r.data, 'value_summary')) {
+      console.error(`  ⚠ value_summary NOT stored: this instance's core predates PATCH /tasks/:id accepting the field. Upgrade the core, or edit the summary in the hall. The grade below is unaffected.`);
+    } else {
+      console.error(`  ⚠ value_summary NOT stored (${apiErrorLine(r.data, r.status)}) — task #${taskId} keeps its previous summary. The grade below is unaffected.`);
+    }
+    return { written: false, reason: 'refused' };
+  }
+  console.log(`  value_summary updated on task #${taskId} — the hall, /status and the ship broadcast now read the corrected sentence.`);
+  return { written: true };
+}
+
+// ---------- Re-grade flow (#678) ----------
+//
+// `node scripts/bongos/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(opts = {}) {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  if (!Number.isFinite(taskId)) {
+    console.error('usage: node scripts/bongos/ship.js <task-id> --regrade [--summary-file <path|-> | --summary "..."] [--response-file <path|-> | --response "..."] [--visual <image>] [--visual-alt "caption"] [--no-merge] [--force] [--verified] [--base <ref>]');
+    process.exit(2);
+  }
+  // A passing re-grade runs finishShip, the same land as a fresh ship, so Manual mode asks
+  // here too — whether reached by --regrade or by shipMain's resume-grade dispatch (task 1004631).
+  if (await stopForManualApproval(args, taskId)) return;
+  // task 1003702: refuse --notes rather than swallowing it. The reasoning — why
+  // a refusal and not a persist — is in ship-honesty.js above regradeNotesRefusal
+  // and is not repeated here. What is load-bearing at THIS call site is the
+  // POSITION: before the preflight and before any grade spend, because a refusal
+  // that first costs a 4-worker panel run is barely better than the silence it
+  // replaces. tests/ship_cannot_lie.mjs pins that order.
+  if (proseFlagPresent(args, 'notes')) {
+    for (const line of regradeNotesRefusal(taskId)) console.error(line);
+    process.exit(2);
+  }
+  // task 1004665: --visual used to be screened by shipMain and then dropped here
+  // without a word — this path returned before shipMain's upload, so visual_url
+  // stayed null (task 1004351). Screen it at the same early position as the
+  // --notes refusal (bad input costs no grade spend), and attach it on every
+  // path below that goes on to grade or land. shipMain's resume-grade dispatch
+  // hands over the visual it already screened rather than reading the file twice.
+  const visual = opts.visual !== undefined ? opts.visual : shipVisual.fromArgs(args, { regrade: true });
+  const attachVisual = async () => (visual
+    ? shipVisual.upload({ taskId, visual, client: await cliClient(), errorLine: apiErrorLine })
+    : false);
+  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/bongos/ship.js ${taskId} --verified`);
+    process.exit(1);
+  }
+  // task 1004322 (ADR 0341 D7): a page tweak already HELD for its artist has a
+  // passed grade. A plain re-run lands here (completed -> resume-grade), and
+  // re-grading would spend the panel again for the verdict it already has, so it
+  // only re-publishes the branch (the recovery for a publish that failed).
+  if (tweakHold.isHeldForArtist(task, tRes.data.grade ? tRes.data.grade.passed : null)) {
+    console.log(`Task #${taskId} already passed its grade and is waiting for the artist: re-publishing its branch, not re-grading.`);
+    await attachVisual();
+    await finishShip({
+      taskId, summary: summaryArg || task.value_summary || '', held: true, postGradeStatus: 'completed', doneLine: 'Done.',
+      card: { title: task.title, valueSummary: summaryArg || task.value_summary || '', notes: '' },
+    });
+    return;
+  }
+  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.
+  //
+  // AND IT NOW REACHES THE TASK ROW TOO — task 1003817. It did not before: this
+  // `summary` fed the grader prompt, the merge commit message and the PR
+  // title/body and stopped there, so a builder who re-graded with a CORRECTED
+  // --summary saw it applied everywhere except the place that is the record —
+  // the hall, /status and the Discord #ship-news line all kept the first ship's
+  // sentence forever. persistRegradeSummary (below the preflight) is the write;
+  // PATCH /tasks/:id is the route it uses, and `value_summary` was added to that
+  // schema by this same task. tests/ship_cannot_lie.mjs pins the wiring.
+  const summary = summaryArg || task.value_summary || '';
+  // task 1003693: the fallback above is silent, and on a re-grade silence means
+  // re-publishing the failed attempt's sentence. Say so while it can still be
+  // corrected — see staleSummaryNotice for the incident this comes from.
+  if (!summaryArg) {
+    for (const line of staleSummaryNotice(taskId, task.value_summary)) console.log(line);
+  }
+
+  // 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, inputFiles: shipInputPaths(args) });
+  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) {
+    // task 1003147: a DELIBERATELY artifact-free task used to dead-end here.
+    // shipMain routes every 'completed' task to this re-grade BEFORE reading any
+    // flag (evaluateResumeAction takes none), so --allow-empty / --skip-grade never
+    // reached the manual-confirm path that a no-artifact task actually needs — and
+    // that path is unreachable from 'completed' any other way. Hit for real on task
+    // 1003146: a kind=verify task landed at 'completed' with no grade row, and
+    // --allow-empty, --skip-grade and --verified all bailed on this same line.
+    //
+    // BOTH conditions are required, and the diff emptiness is MEASURED, not taken
+    // on the builder's word. A flag alone must not reach confirm: a task with a
+    // real diff whose grade failed would then bypass the grader by passing
+    // --allow-empty, which is a quality hole, not a fix. Here the grader has
+    // nothing to read, so there is no verdict to dodge. Confirming is additionally
+    // permission-gated server-side on task.confirm.grade_bypass, so this widens
+    // no authority — it only stops the ONE shape that had no exit at all.
+    // task 1003944: the porcelain is MEASURED here and handed to the decision, so a
+    // re-grade weighs the same evidence a first ship does. Without it the guard saw
+    // only the flag and the (empty) committed diff, and an UNTRACKED deliverable —
+    // invisible to preflight's trackedDirty — confirmed straight through to shipped.
+    const emptyShip = shouldConfirmWithoutGrade({
+      committedFileCount: committedFiles.length,
+      porcelain: gitOk('git status --porcelain'),
+      args,
+    });
+    if (emptyShip.confirm) {
+      console.log('');
+      console.log(`Nothing to grade (the committed diff vs ${graderBaseline || 'baseline'} is empty) and this ship`);
+      console.log('declares itself artifact-free — manual-confirming via POST /tasks/:id/confirm.');
+      await attachVisual();
+      // A kind='verify' task cannot reach here without --verified: the gate above
+      // exits first, so the server's verify_attestation_required can't fire below.
+      const confirm = await (await cliClient()).tasks.postTasksIdConfirm({ id: taskId, body: { verified } });
+      if (!confirm.ok) {
+        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'];
+          // task 1003950: this branch is reached ONLY via shouldConfirmWithoutGrade,
+          // which requires both an empty committed diff and an explicit --allow-empty —
+          // so it is always a no-artifact close, and never a bypass of a failing grade.
+          // It used to end at "ask a builder whose role holds it", which is the exact
+          // dead end the bug names: a builder who knows no archon had nowhere to go.
+          const escalation = await fileNoArtifactEscalation({
+            // no `notes` on this path by design: regradeMain REFUSES --notes (see
+            // proseFlagPresent above), so the summary is the only reason the builder gave.
+            taskId, title: task && task.title, floor, summary, builder: builder.github_login,
+          });
+          for (const line of noArtifactRefusalLines({ taskId, floor, escalation })) console.error(line);
+          process.exit(1);
+        }
+        console.error(`manual-confirm failed: ${apiErrorLine(confirm.data, confirm.status)}`);
+        process.exit(1);
+      }
+      const confirmedStatus = confirm.data.taskStatus;
+      printCreditsAndAchievements({
+        postGradeStatus: confirmedStatus,
+        credits: confirm.data.creditsAwarded ?? 0,
+        creditsRaw: null,
+        creditsMultiplier: null,
+        ideaBonusInfo: confirm.data.ideaBonus ?? null,
+        justUnlocked: confirm.data.just_unlocked || [],
+      });
+      // The same confirmed→shipped tail a normal ship runs, so a no-artifact resume
+      // lands identically instead of stopping one step short.
+      await finishShip({
+        taskId, summary, advanceToMerge: confirmedStatus === 'confirmed', skipMerge, dbOnly: true,
+        postGradeStatus: confirmedStatus,
+        doneLine: 'Done — confirmed with no artifact (grader had nothing to read).',
+        card: { title: task.title, valueSummary: summary, notes: '' },
+      });
+      return;
+    }
+    // task 1003944: the two refusals are DIFFERENT advice. 'uncommitted-work' means
+    // the deliverable exists and was never committed — offering --allow-empty there
+    // would be telling the builder to assert the opposite of what the tree shows,
+    // which is how task 1363 shipped nothing and called it done. Only the genuinely
+    // clean tree gets pointed at the flag.
+    if (emptyShip.reason === 'uncommitted-work') {
+      console.error('Nothing to grade: nothing is committed on this branch, but your working tree has uncommitted changes:');
+      for (const f of emptyShip.uncommitted) console.error(`    - ${f}`);
+      console.error('');
+      console.error('Your work was never committed — confirming 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 --regrade.');
+      process.exit(1);
+    }
+    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.');
+    console.error('If this task is DELIBERATELY artifact-free (a DB-only close, an ops verification), say so:');
+    console.error(`  node scripts/bongos/ship.js ${taskId} --allow-empty`);
+    process.exit(1);
+  }
+
+  // ---- Persist a corrected --summary to the task row (task 1003817) ----
+  // Placed HERE deliberately: after the guards that can still abort the re-grade
+  // (so a refused run writes nothing), and BEFORE the grade — which is the order
+  // the normal ship already has, where claim-resolve stores value_summary and
+  // the panel runs afterwards. The row, the grader prompt, the merge commit and
+  // the PR then all carry the same sentence.
+  await persistRegradeSummary({ taskId, summaryArg, task });
+  // task 1004665: the picture goes up at the same point and for the same reason
+  // as the summary — after every guard that can still refuse, before the panel.
+  await attachVisual();
+
+  // ---- 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;
+  recordGradeOutcome({ taskId, grade: g });
+  const postGradeStatus = gradePost.data.taskStatus;
+  const held = gradePost.data.held === true; // task 1004322: a page tweak's pass waits for its artist
+  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 || [],
+    held, // task 1004379: a held pass is not 'grade not passed'
+  });
+
+  // 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,
+    held,
+    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,
+      // Empty by design, not by omission (task 1003702). A re-grade takes no
+      // --notes at all now — it is refused above — so there are none from THIS
+      // round to show. The first ship's notes are the durable record and live on
+      // the resolved claim; re-printing them here would suggest this round
+      // produced them.
+      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,
+};