@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/ship-finish.js

@@ -0,0 +1,420 @@
+// scripts/bongos/ship-finish.js — merge+deploy orchestration, post-ship sync/closeout and the completion card.
+//
+// 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 3008-3352 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 fs = require('node:fs');
+const os = require('node:os');
+const { cliClient, printOnboardingNudge, rewardPolicy, cardFlagsFromMe } = require('./cli-lib');
+const { closeoutPlan } = require('../../modules/lifecycle/ship-preflight');
+const { syncMemoryOnShip } = require('./ship-memory-sync.js');
+const { uploadSessionOnShip } = require('./ship-session-upload.js');
+const { execFileSync } = require('node:child_process');
+const { gitOk } = require('./ship-git.js');
+const { fetchDeployedVersion, resolveInstanceBase } = require('./ship-deploy-target.js');
+const { landBailed, reconciledCardStatus } = require('./ship-land.js');
+const { autoMerge, publishHeld } = require('./ship-merge.js');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
+const { normalizeApiError, playShipBell, postLandShipOutcome } = require('./ship-io.js');
+const { getServerReward, noteServerReward } = require('./ship-state.js');
+
+async function mergeAndDeploy({ taskId, summary, advanceToMerge, skipMerge, dbOnly = false }) {
+  if (advanceToMerge && skipMerge) {
+    console.log('');
+    console.log('--no-merge: stopping at confirmed. Run /merge-mode later to land it.');
+    return landBailed('--no-merge was passed, so the land was skipped', '/merge-mode');
+  }
+  // Grade failed: the card renders the 'failed' stage ('not deployed'), so there
+  // is no land outcome to report.
+  if (!advanceToMerge) return null;
+
+  console.log('');
+  console.log('Auto-merge chain (confirmed → shipped):');
+  const merged = await autoMerge(taskId, summary, { dbOnly });
+  // NOTE: `merged` is an OBJECT now — every value is truthy, so this MUST test
+  // .ok. A bare `if (!merged)` would fall through on a bail and POST /ship for a
+  // task that never landed.
+  if (!merged.ok) return merged;
+
+  const shipBody = merged.noArtifact ? { no_artifact: true, no_artifact_reason: merged.noArtifactReason || 'deliberate empty ship (--db-only)' } : {}; // ADR 0184
+  const ship = await (await cliClient()).tasks.postTasksIdShip({ id: taskId, body: shipBody });
+  if (!ship.ok) {
+    // task 1049 / 1002809: the server may have already flipped this task to
+    // shipped (reconcile-on-read, or the reconciler racing this call). Verify
+    // the LIVE status before treating the refusal as a failure — the old
+    // flat-shape string check never matched the R01 envelope, so this success
+    // path was dead and every reconciled land reported as a failed ship.
+    const { code, message } = normalizeApiError(ship.data);
+    let liveStatus = null;
+    try {
+      const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
+      if (t.ok && t.data && t.data.task) liveStatus = t.data.task.status;
+    } catch (_) { /* verify is best-effort; fall back to the code-based call */ }
+    const outcome = postLandShipOutcome({ code, liveStatus });
+    if (outcome.alreadyShipped) {
+      console.log(`Task #${taskId} is now: shipped (${outcome.why}).`);
+    } else {
+      const e = message || code || `HTTP ${ship.status}`;
+      console.error(`  /tasks/${taskId}/ship failed: ${e}${liveStatus ? ` (task is at '${liveStatus}')` : ''}`);
+      // The merge itself succeeded — only the status flip failed, so a re-run
+      // resumes cleanly (task 941). Report it rather than letting the card claim
+      // the land is in progress.
+      return landBailed(`merged, but the ship call failed — ${e}`, `node scripts/bongos/ship.js ${taskId}`);
+    }
+  } else {
+    console.log(`Task #${taskId} is now: shipped`);
+  }
+
+  // task 1442: the task-shipped bell used to play HERE, but this point is only
+  // reached on a SYNCHRONOUS merge+deploy. In ci/async landing mode (now the
+  // norm) ship.js exits at 'confirmed' and never gets here, so the bell never
+  // rang. It now plays at the confirmed/shipped success milestone via
+  // playShipBell() (finishShip + resumeMerge), which covers both paths.
+
+  // If the builder was promoted during this ship, write the promotion flag so
+  // the NEXT Claude turn plays the fanfare via the Stop hook.
+  const TMP_FLAGS = process.platform === 'win32'
+    ? (process.env.TEMP || process.env.TMP || os.tmpdir())
+    : '/tmp';
+  if (ship.data?.task?.graduatedTo) {
+    try { fs.writeFileSync(require('path').join(TMP_FLAGS, 'otb-promotion'), ''); } catch (_) {}
+    console.log(`  Rank promotion: ${ship.data.task.graduatedTo} — fanfare queued.`);
+  }
+
+
+  if (summary) {
+    // task 1749: the SERVER is now the SINGLE ship broadcaster. It emits
+    // task.shipped on the confirmed→shipped transition from every entry point
+    // (POST /ship, the publish-status reconcile-on-read, and the 5-min
+    // reconciler sweep — all idempotent via db.shipTask), and the discord
+    // module posts the #ship-feed line off that one event. This local post used
+    // to fire IN ADDITION to the server's, so a single ship announced FOUR
+    // messages (local #ship-news + #ship-feed, then the server's #ship-news +
+    // #ship-feed). Defer unconditionally so exactly one broadcast fires — from
+    // the server, after the deploy lands. (That one broadcast is the #ship-feed
+    // line, plus a plain #ship-news headline for a feature or a bug — the kind
+    // filter in chooseBroadcastTargets, task 1002846.) The security-sensitive
+    // fail-closed routing lives server-side in ship-broadcast.postShipBroadcast,
+    // so it is preserved.
+    console.log('  Discord broadcast: deferred to the server — it posts #ship-feed after the deploy lands.');
+  }
+  return merged;
+}
+
+// Memory + session-digest push, gated on a successful land (confirmed/shipped).
+// Both are best-effort — a failure here is a warning, never a ship failure.
+async function postShipSync(taskId, postGradeStatus) {
+  if (postGradeStatus !== 'confirmed' && postGradeStatus !== 'shipped') return null;
+  console.log('');
+  console.log('Memory sync (best-effort):');
+  await syncMemoryOnShip();
+  console.log('');
+  console.log('Session upload (best-effort):');
+  // task 1270: the upload returns { totalTokens, modelUsage } (or null) so the
+  // completion card can show Claude usage + an estimated cost.
+  return await uploadSessionOnShip(taskId);
+}
+
+// Post-ship onboarding nudge (V3.R13 #237). Best-effort — never let a stale /me
+// read make the script exit non-zero after a successful ship.
+async function onboardingNudgeBestEffort() {
+  try {
+    const meRes = noteServerReward(await (await cliClient()).me.getMe());
+    if (meRes.ok) {
+      console.log('');
+      printOnboardingNudge(meRes.data);
+    }
+  } catch (_) {
+    /* never block on a UX nudge */
+  }
+}
+
+// finishShip — the confirmed→shipped tail shared by shipMain + regradeMain (task
+// 1093 / C9): auto-merge + deploy, then the best-effort memory/session sync, the
+// Done line, and the onboarding nudge. Only this UNIFORM tail is shared;
+// printGradeOutcome + printCreditsAndAchievements stay caller-owned (their inputs
+// differ between the two paths). `doneLine` is a param so each caller keeps its
+// own wording ('Done.' vs the re-grade pass/fail message).
+// task 932 (Lars 2026-06-12): deterministic, no-LLM post-ship working-tree
+// close-out, folded into the delivery process (NOT a separate skill). After a
+// ship lands, scratch often lingers uncommitted — untracked files the preflight
+// lets through, generated artifacts, post-commit edits — making the session
+// hard to archive cleanly. This REPORTS what's left and leaves it in place.
+// task 1004254: it used to `git stash push -u` the leftover, but the stash stack
+// is repo-global across every worktree (task 1003344), so one builder's scratch
+// landed where a parallel agent's pop could apply it to the wrong branch — and
+// it swallowed review renders an owner still needed. It never touches the stash.
+// STRICTLY fail-open: the ship has already succeeded by the time this runs, so
+// nothing here may throw, prompt, or change the exit status — a messy tree must
+// never surface as a ship failure. The caller gates this on a SUCCESSFUL land.
+function postShipCloseout(taskId) {
+  try {
+    // Untrimmed: gitOk's trim() eats the first line's leading status column, so
+    // " M a.txt" was listed as ".txt" (task 1004254).
+    let out;
+    try {
+      out = execFileSync('git', ['status', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch (_) { return; } // git unavailable / not a repo — nothing to reconcile
+    const plan = closeoutPlan(out);
+    if (plan.clean) {
+      console.log('Close-out: working tree clean — session is archive-ready.');
+      return;
+    }
+    console.log('');
+    console.log(`Close-out: ${plan.leftover.length} uncommitted/untracked path(s) remain after the ship:`);
+    for (const f of plan.leftover.slice(0, 15)) console.log(`  ${f}`);
+    if (plan.leftover.length > 15) console.log(`  … and ${plan.leftover.length - 15} more`);
+    console.log(`Close-out: left in place (task ${taskId} already shipped) — commit, move or delete them before archiving this worktree.`);
+  } catch (err) {
+    // Fail-open — a post-ship close-out problem must never look like a ship failure.
+    console.log(`Close-out: skipped (${err && err.message ? err.message : 'error'}).`);
+  }
+}
+
+async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine, card, dbOnly = false, held = false }) {
+  // task 1004322 (ADR 0341 D7): a page tweak whose grade passed is HELD for its
+  // artist. It publishes its branch and PR and stops; nothing merges.
+  if (held) return finishHeld({ taskId, summary, postGradeStatus, card });
+  // task 1002541: the land outcome carries WHY a land didn't happen. Without it
+  // the card had only the status to go on and printed 'landing automatically'
+  // over a merge that had already bailed.
+  const land = await mergeAndDeploy({ taskId, summary, advanceToMerge, skipMerge, dbOnly });
+  // task 1719: mergeAndDeploy may have landed the task to 'shipped' IN-SESSION — the
+  // enable-success poll (pollCiDeploy) or, since task 1718, the enable-failure server
+  // poll (pollServerPublish). finishShip was handed postGradeStatus from the CONFIRM
+  // step ('confirmed'), so without re-reading it the completion card renders the stale
+  // 'confirmed — landing' banner AND printCompletionCard writes a pending-land
+  // breadcrumb — the SHIPPED banner then only appears on a LATER prompt, in whatever
+  // session is next (the owner-reported confusion). Re-fetch the authoritative status
+  // (exactly as resumeMerge does, task 1275) so a real in-session land shows the
+  // SHIPPED banner here and writes no breadcrumb. Best-effort: any read failure keeps
+  // today's behavior; the grade-fail path (advanceToMerge=false) never re-fetches.
+  let landedStatus = postGradeStatus;
+  if (advanceToMerge && (postGradeStatus === 'confirmed' || postGradeStatus === 'shipped')) {
+    try {
+      const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
+      const live = (t.ok && t.data && t.data.task) ? t.data.task.status : null;
+      landedStatus = reconciledCardStatus(live, postGradeStatus);
+    } catch (_) { /* keep postGradeStatus — the land above already awaited its outcome */ }
+  }
+  // Memory + session sync (#274 / 6D.1 / ADR 0027) — postShipSync itself gates on
+  // a successful land (confirmed/shipped); both legs are best-effort. It returns
+  // the session usage ({ totalTokens, modelUsage } | null) so the completion card
+  // can show Claude usage + an estimated cost (task 1270).
+  const usage = await postShipSync(taskId, landedStatus);
+  console.log('');
+  console.log(doneLine);
+  await onboardingNudgeBestEffort();
+  // task 1270: the ONE deterministic completion card — the same shape every ship.
+  // Replaces the agent's free-form prose recap (the builder-ship skill renders the
+  // rich in-feed card from the HTML this writes; the monospace card below is the
+  // always-printed fallback + the headless summary). Strictly best-effort.
+  // task 1719: pass the reconciled status so a just-landed ship shows SHIPPED (and
+  // writes no breadcrumb), not the stale pre-merge 'confirmed'.
+  await printCompletionCard({ taskId, postGradeStatus: landedStatus, card, usage, land });
+  // task 932: reconcile the working tree — ONLY on a successful land. A
+  // grade-failed ship stays at 'completed'; leave that tree untouched so the
+  // builder can fix findings + re-ship.
+  if (landedStatus === 'confirmed' || landedStatus === 'shipped') {
+    // task 1442: ring the ship bell at the success milestone. 'confirmed' counts —
+    // in ci/async mode the work is done + credited here and the deploy lands later
+    // server-side, so this is the moment the builder experiences as "shipped".
+    playShipBell();
+    postShipCloseout(taskId);
+  }
+}
+
+// finishHeld — the tail of a held pass (task 1004322). The session is finished
+// work, so it syncs exactly as a confirmed ship does (the applier's session
+// reward is computed from the upload, and pays on land). No bell and no tree
+// close-out: nothing landed, and a send-back brings the round back to be
+// re-applied. `deps` is a test seam only.
+async function finishHeld({ taskId, summary, postGradeStatus, card }, deps = {}) {
+  console.log('');
+  console.log('Publishing the applied branch for the artist (ADR 0341 D7):');
+  const land = await (deps.publishHeld || publishHeld)(taskId, summary);
+  if (land && land.held) {
+    for (const line of tweakHold.heldLines(taskId, { prUrl: land.prUrl })) console.log(line);
+  } else {
+    console.error(`  The branch did not publish${land && land.reason ? `: ${land.reason}` : ''}. The task stays at completed with its passed grade.`);
+    console.error(`  Re-run to publish it again (the grade is not re-run): node scripts/bongos/ship.js ${taskId}`);
+  }
+  const usage = await (deps.postShipSync || postShipSync)(taskId, 'confirmed');
+  // task 1004379: name the stage — at 'completed' the card would otherwise read a failed grade.
+  await (deps.printCompletionCard || printCompletionCard)({ taskId, postGradeStatus, card, usage, land, stage: 'held' });
+  return land;
+}
+
+// task 1275: sum the committed diffstat (added/removed lines) over baseline...HEAD.
+// Shared by the completion card and the in-review card. Best-effort: returns
+// nulls when there's no baseline or git is unavailable.
+function diffstatFor(baseline) {
+  if (!baseline) return { added: null, removed: null };
+  const numstat = gitOk(`git diff --numstat ${baseline}...HEAD`) || gitOk(`git diff --numstat ${baseline} HEAD`);
+  if (!numstat) return { added: null, removed: null };
+  let added = 0;
+  let removed = 0;
+  for (const line of numstat.split('\n')) {
+    const [a, r] = line.split('\t');
+    if (a !== '-' && a != null && a !== '') added += Number(a) || 0;
+    if (r !== '-' && r != null && r !== '') removed += Number(r) || 0;
+  }
+  return { added, removed };
+}
+
+// task 1270: build + print the deterministic completion card. Prints the
+// alignment-proof monospace card to stdout (always), then writes the branded
+// in-feed HTML to a temp file and prints an [otb-card-html] marker the
+// builder-ship skill picks up to render it in the chat feed. Every step is
+// best-effort — a summary card must NEVER fail or undo a completed ship.
+async function printCompletionCard({ taskId, postGradeStatus, card, usage, land = null, stage = undefined }) {
+  if (!card) return;
+  try {
+    const shipCard = require('../../modules/lifecycle/ship-card');
+
+    // Diffstat from the committed range the grader used (baseline...HEAD).
+    const fileCount = Array.isArray(card.files) && card.files.length ? card.files.length : null;
+    const { added, removed } = diffstatFor(card.baseline);
+
+    // Deployed commit (shipped only): prefer prod /version, fall back to short HEAD.
+    let commit = null;
+    let reach = null;
+    if (postGradeStatus === 'shipped') {
+      const v = fetchDeployedVersion();
+      commit = (v && v.commit) ? String(v.commit).slice(0, 7) : (gitOk('git rev-parse --short HEAD') || null);
+      // task 1004682: say WHO sees this merge — the hub's live build (read, not
+      // assumed) and the hosted-projects rule — in the merge-reach wording.
+      try {
+        reach = require('./deploy-divergence').hubReading({
+          target: resolveInstanceBase(), live: v, sha: gitOk('git rev-parse HEAD'),
+        });
+      } catch (_) { /* the card falls back to the bare commit */ }
+    }
+
+    // Running drachmae total + the builder's card-richness level (task 1279's
+    // knob, a ladder since task 1002518), both from one /me fetch (best-effort).
+    let total = null;
+    let cardFlags = cardFlagsFromMe(null);
+    try {
+      const me = noteServerReward(await (await cliClient()).me.getMe());
+      if (me.ok && me.data) {
+        if (me.data.builder) total = me.data.builder.total_credits;
+        cardFlags = cardFlagsFromMe(me);
+      }
+    } catch (_) { /* total + knob are optional; default to the standard rung */ }
+    const widgetsEnabled = cardFlags.showWidget;
+
+    // Token count + estimated cost from the session usage. Split the tokens into
+    // 'new' (fresh input + output + first-time cache writes) vs 'cached' re-reads
+    // (cache_read — the same large context re-read every turn) so the card can
+    // lead with cost and not with a single all-in count that cache re-reads make
+    // look alarmingly huge (task 1765). The per-model breakdown is already on hand
+    // via usage.modelUsage — no new server data needed.
+    let tokens = null;
+    let costUsd = null;
+    let newTokens = null;
+    let cachedTokens = null;
+    if (usage) {
+      tokens = usage.totalTokens;
+      const mu = usage.modelUsage || {};
+      let cache = 0;
+      let fresh = 0;
+      let sawUsage = false;
+      for (const u of Object.values(mu)) {
+        if (!u) continue;
+        sawUsage = true;
+        cache += Number(u.cache_read) || 0;
+        fresh += (Number(u.input) || 0) + (Number(u.output) || 0) + (Number(u.cache_creation) || 0);
+      }
+      if (sawUsage) { newTokens = fresh; cachedTokens = cache; }
+      try {
+        const { priceModelUsage } = require('../../src/bongos/llm-pricing');
+        costUsd = priceModelUsage(mu).true_cost_usd;
+      } catch (_) { /* cost is optional */ }
+    }
+
+    const cardInputs = {
+      stage, // task 1004379: 'held' from finishHeld; undefined ⇒ derived from postGradeStatus
+      postGradeStatus,
+      taskId,
+      title: card.title,
+      valueSummary: card.valueSummary,
+      notes: card.notes,
+      fileCount,
+      added,
+      removed,
+      grade: card.grade || null,
+      credits: { awarded: card.creditsAwarded, total, perTaskCredit: rewardPolicy(getServerReward()).perTaskCredit },
+      usage: { tokens, costUsd, newTokens, cachedTokens },
+      deploy: { commit, reach },
+      // task 1002541: absent (the default) ⇒ the card behaves exactly as before,
+      // which keeps every other caller — resumeMerge, the claim card, and
+      // land-watch replaying breadcrumbs written by older versions — unchanged.
+      land,
+    };
+    const model = shipCard.buildCardModel(cardInputs);
+
+    // Print the monospace card + write the branded HTML for the in-feed renderer
+    // (shared emitCard, task 1275). The skill reads the printed path and passes
+    // the contents to the visualization tool — the agent authors nothing, so the
+    // card is identical every ship. task 1002518: the resolved richness level
+    // reaches emitCard as flags — at the plain rung no HTML is written or
+    // relayed, at the minimal rung not even the monospace card is printed (the
+    // guaranteed [otb-confirm] line always is), and at the rich rung the
+    // widget's summary arrives already open.
+    shipCard.emitCard(model, taskId, { flags: cardFlags });
+
+    // task 1687: in CI deploy mode this card is 'confirmed — landing' and the real
+    // confirmed->shipped land happens minutes later, server-side — so the SHIPPED
+    // banner would never render in-session. Drop a pending-land breadcrumb; the
+    // land-watch hook renders the shipped card on a later prompt once it lands.
+    // Best-effort: a breadcrumb must never fail a ship (mirrors the card itself).
+    if (postGradeStatus === 'confirmed') {
+      // `cardFlags` carries the resolved rung so the later-rendered shipped card
+      // matches the one this session printed; `widgetsEnabled` stays beside it
+      // so a breadcrumb written by an older CLI still reads correctly.
+      try { require('./land-watch').writeBreadcrumb(taskId, { widgetsEnabled, cardFlags, cardInputs }); }
+      catch (_) { /* breadcrumb is best-effort */ }
+    }
+  } catch (_) {
+    /* a summary card must never fail a ship */
+  }
+
+  // task 1002521: the card above says SHIPPED, which means "merged". Its Deploy
+  // row says who sees that (tasks 1004682, 1004873: any instance, the hub
+  // included, only once a release carries it and its pin moves). This adds
+  // the full divergence report when live and main disagree — blocker 1000097:
+  // 171 commits sat unreleased for ten days while every layer reported success.
+  // Warn, never block — a shipped task is still shipped, and an offline builder
+  // must not be punished for it.
+  try {
+    const { check, report } = require('./deploy-divergence');
+    const r = await check();
+    if (!r.undetermined && !r.ok) report(r);
+  } catch (_) {
+    /* a divergence warning must never fail a ship */
+  }
+}
+
+// Decide whether a builder may re-grade a task via `--regrade` (#678). Pure so
+// it's unit-testable. A re-grade is allowed iff the task is stuck at `completed`
+// (a ship whose grade failed) AND the caller either last held the claim or is an
+// Archon. Every other status gets a tailored, actionable message. Note this is a
+// client-side UX guard, not a trust boundary: /tasks/:id/grade is rank-open by
+// design (the subagent grade is the authority, not builder identity).
+
+module.exports = {
+  diffstatFor,
+  finishShip,
+  finishHeld,
+  mergeAndDeploy,
+  onboardingNudgeBestEffort,
+  postShipCloseout,
+  postShipSync,
+  printCompletionCard,
+};