@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/ship-honesty.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// scripts/bongos/ship-honesty.js — a ship must not lose the builder's prose, and
+// must not lie about how far it got (task 1003168 / G04, goal 1000077;
+// criterion guards-ship-cannot-lie).
+//
+// TWO fixes live here because they are one incident. A ship was invoked with
+// handoff notes containing backticks; bash command-substituted them before node
+// ran, truncating the argument list. The task resolved with EMPTY notes, landed
+// at 'completed', and the process died before grading with a bare
+// `fatal: <stack>`. Two failures compounded: the prose was lost (nothing in the
+// ledger about a session that happened), and the status could not say which leg
+// died — 'completed' is ALSO what a grade-failed task looks like.
+//
+// Split out of ship.js, which is ~4600 lines and far over the size ratchet, so
+// adding this there would have regressed excess_lines_total.
+
+'use strict';
+
+const { argText } = require('./cli-lib.js');
+
+// resolveProse(args, specs) — resolve every prose argument for one invocation
+// through cli-lib.argText, refusing the combinations that would silently lose
+// text. Returns a { [bareName]: string } map, or exits 2 having explained why.
+//
+// The extra rule argText cannot enforce alone: stdin can only be consumed ONCE,
+// so two `-file -` arguments in the same command would hand the first reader
+// everything and the second an empty string. Refuse instead — a ship whose notes
+// silently came back empty is the exact incident this whole task is about
+// (learning 1000197).
+function resolveProse(args, specs) {
+  const out = {};
+  const stdinUsers = [];
+  for (const name of specs) {
+    const r = argText(`--${name}`, args);
+    if (r.error) {
+      console.error(r.error);
+      process.exit(2);
+    }
+    if (r.source === 'stdin') stdinUsers.push(`--${name}-file`);
+    out[name] = r.value;
+  }
+  if (stdinUsers.length > 1) {
+    console.error(`${stdinUsers.join(' and ')} both read stdin, which can only be consumed once — `
+      + 'the second would silently come back empty. Put at least one in a real file.');
+    process.exit(2);
+  }
+  return out;
+}
+
+// ---------- The ship must not lie about how far it got (G04, task 1003168) ----
+//
+// THE INCIDENT. A ship died after the claim resolved and before the grade
+// recorded. resolveClaim had already landed the task at 'completed', so the
+// process printed `fatal: <stack>` and exited — and 'completed' is exactly what
+// a task ALSO looks like when its grade ran and failed. The status could not
+// distinguish "the pipeline stopped here" from "the pipeline got further and the
+// grade said no", and the work went unrecovered because nobody could tell.
+//
+// The cure is not more status values: it is that the process which knows where it
+// died must SAY so on the way out. shipProgress records the last leg that
+// completed; fatalRecoveryLines turns it into an instruction.
+let shipProgress = { stage: 'preflight', taskId: null };
+
+// The one writer. Called by ship.js as each leg completes.
+function markShipProgress(stage, taskId) {
+  shipProgress = { stage, taskId };
+}
+
+// Pure so the wording is pinned by a DB-free test (the smokeGateMessages
+// precedent) — a recovery message that drifts out of date is worse than none.
+//
+// WHY EVERY STAGE POINTS AT A PLAIN RE-RUN, never --regrade: shipMain on a task
+// with no active claim routes by the task's CURRENT status (evaluateResumeAction)
+// — 'completed' resumes the grade, 'confirmed' resumes the merge. --regrade only
+// accepts 'completed' and REFUSES a 'confirmed' task with "its grade passed;
+// nothing to re-grade". A builder reading a crash does not know which leg died,
+// which is the entire problem, so the advice must be the command that works from
+// either — and a plain re-run of a 'completed' task calls regradeMain() anyway.
+function fatalRecoveryLines(progress = shipProgress) {
+  const id = progress.taskId;
+  const rerun = id ? `node scripts/bongos/ship.js ${id}` : 'node scripts/bongos/ship.js <task-id>';
+  const head = 'The ship did NOT finish. Where it stopped, and what recovers it:';
+  switch (progress.stage) {
+    case 'resolved':
+      return [
+        head,
+        `  Task #${id} is at 'completed' — the claim resolved, the grade did NOT record.`,
+        '  No credits awarded. Your commits are safe; nothing was lost but the grade.',
+        `  Resume:  ${rerun}`,
+        "  (A plain re-run resumes the stalled leg. Do NOT reach for --regrade: it only",
+        "   accepts 'completed', so it refuses outright if the ship actually got further.)",
+      ];
+    case 'graded':
+      return [
+        head,
+        `  Task #${id} is at 'confirmed' — it graded and PASSED; the merge/deploy did not finish.`,
+        '  Credits land on the merge, so they have not been awarded yet.',
+        `  Resume:  ${rerun}`,
+        '  (--regrade would refuse this one — its grade already passed.)',
+      ];
+    case 'landed':
+      return [
+        'The ship LANDED; the failure above is in the after-work:',
+        `  Task #${id} reached 'shipped' — the merge landed and credits were awarded.`,
+        '  Broadcast / card / cleanup did not complete, which does not undo the ship.',
+        `  Safe to re-run if you want the after-work retried:  ${rerun}`,
+      ];
+    case 'preflight':
+    default:
+      return [
+        head,
+        '  The claim was NOT resolved — it is still active and the task is unchanged.',
+        `  Fix the error above and re-run:  ${rerun}`,
+      ];
+  }
+}
+
+// task 1002605 (G-18): the pre-resolve smoke gate's two message sets, pure so the
+// wording is pinned by a DB-free unit test (tests/ship_smoke_gate.mjs). A smoke
+// FAIL used to fall silently through into the claim resolve — claim consumed,
+// grading skipped with no message, task parked at 'completed', exit 0 — the
+// choke-point map's likeliest "my task vanished" shape. `abort` is the default
+// (printed BEFORE the resolve; the claim stays active); `parked` is the
+// --allow-smoke-fail continuation (printed where the grader would have run, so
+// the builder knows exactly where the task stopped and how to resume).
+function smokeGateMessages(taskId) {
+  return {
+    abort: [
+      'Ship ABORTED: the production smoke test FAILED — see the FAIL line(s) above.',
+      'No claim resolved, no credits awarded — your claim is still active and nothing changed.',
+      'The smoke suite hits LIVE endpoints (your change is not deployed yet), so this usually means production is briefly degraded — not that your change broke it.',
+      `  - Re-run once it recovers:     node scripts/bongos/ship.js ${taskId}`,
+      `  - Ship anyway (deliberate):    node scripts/bongos/ship.js ${taskId} --allow-smoke-fail`,
+      `    (parks the task at 'completed' ungraded; a plain re-run resumes it)`,
+    ],
+    parked: [
+      '--allow-smoke-fail: smoke FAILED and the ship deliberately stops here.',
+      `Task #${taskId} is parked at 'completed' — ungraded, unconfirmed, no credits awarded.`,
+      `Resume when production is healthy:  node scripts/bongos/ship.js ${taskId}`,
+      '  (A plain re-run routes to whichever leg stalled. --regrade only accepts a task at',
+      "   'completed', so it refuses if the ship got further — task 1003168.)",
+    ],
+  };
+}
+
+// ---- --regrade must not swallow --notes (task 1003702) ----------------------
+//
+// THE THIRD WAY TO LOSE THE BUILDER'S PROSE, and the reason this lives in the
+// prose-loss file rather than beside regradeMain. `--regrade` resolves only
+// `summary` and `response`, so `--notes` parsed as an unknown flag, produced no
+// error, and vanished. A builder answering a "no evidence in the notes" blocker
+// passed it again in --notes, saw the ship run, and got the identical finding
+// back marked unanswered — with nothing anywhere saying why.
+//
+// AND THE FIX IS A REFUSAL, NOT A PERSIST, because the premise the bug was filed
+// under is wrong in the builder's favour: the panel NEVER reads ship notes, on a
+// first ship or a re-grade. modules/grading/grader-prompt.js buildPrompt() puts
+// the task row, the VALUE SUMMARY, the changed files, the diffstat and the diff
+// in the prompt and nothing else, and the workers get the same bundle. So
+// storing the notes would have fixed the silence and none of the substance: the
+// builder would pass --notes, watch it save, and STILL get "unanswered" — a
+// worse failure, because now it looks like it worked.
+//
+// The two channels that do reach the panel are named in the refusal: --response
+// (fenced into the prior-round block, task 1002662) and the DIFF itself, which
+// is why the workaround that actually worked on task 1003698 was committing the
+// evidence as a file. Nothing is written and nothing is lost: the first ship's
+// notes stay the durable ledger record, which is the one thing --notes on a
+// re-grade could legitimately have meant.
+function proseFlagPresent(args, name) {
+  const list = Array.isArray(args) ? args : [];
+  return list.some((a) => a === `--${name}` || String(a).startsWith(`--${name}=`)
+    || a === `--${name}-file` || String(a).startsWith(`--${name}-file=`));
+}
+
+// Pure so the refusal's WORDING is testable — a message that fails to name the
+// alternative is the same dead end with an error code on it.
+function regradeNotesRefusal(taskId) {
+  return [
+    '--regrade does not take --notes, and your notes have NOT been saved or graded.',
+    '',
+    'The grader never reads ship notes — not on a re-grade, and not on the first ship.',
+    'The panel is given the task, your VALUE SUMMARY, the changed files and the diff.',
+    'So notes cannot answer a finding, and silently keeping them would only look like it had.',
+    '',
+    'Put the evidence where the panel can actually see it:',
+    `  --response "..."   answers the prior round's findings; it rides to the panel fenced.`,
+    `  --response-file <path>   the safe form for prose (a shell eats backticks in an inline value).`,
+    '  the DIFF           commit the proof — a test, a dry-run log, a session-log file.',
+    '                     The panel reads the committed diff and can Read every changed file.',
+    '',
+    `  node scripts/bongos/ship.js ${taskId} --regrade --response-file notes.md`,
+    '',
+    "The first ship's notes stay the durable record; nothing you wrote earlier was lost.",
+  ];
+}
+
+// THE FOURTH WAY TO LOSE THE BUILDER'S PROSE — and the only one where what
+// survives is worse than nothing, because it is a sentence that was true once.
+//
+// regradeMain falls back to the stored value_summary when --summary is omitted
+// (`summaryArg || task.value_summary`), and persistRegradeSummary deliberately
+// writes nothing on an omission. Both postures are right alone: a re-grade with
+// no summary must not blank the row, and an empty broadcast would be worse than
+// a stale one. Together they mean the DEFAULT re-grade re-publishes the first
+// attempt's sentence with nothing saying so.
+//
+// That is the task-1002343 incident exactly. Shipped 2026-09-04 asserting "No
+// project was created and nothing on the live system was left changed"; parked
+// at completed on a failing grade; redone 2026-09-07, when a project WAS created
+// (instance 40, r24-proof). The re-grade omitted --summary, so the ledger and the
+// #ship-news post both announced the opposite of what landed. Nobody ignored a
+// correction — there was no prompt to make one.
+//
+// So this is a NOTICE, not a refusal and not a behaviour change. The fallback is
+// correct and stays; task 1003817 already built the correction path (--summary on
+// a re-grade now reaches the row, the hall, /status and the broadcast). What was
+// missing is the moment that tells the builder that path exists, while the run
+// can still be corrected. Printed BEFORE the grade spend for the reason the
+// --notes refusal is: a warning that first costs a 4-worker panel run is barely
+// a warning at all.
+//
+// Returns [] when the row holds no stored summary — there is no stale text to
+// warn about then, and an empty summary is the merge leg's problem, not this
+// one. Pure, so the WORDING is testable: a notice that fails to name the fix is
+// noise with a warning sign on it.
+function staleSummaryNotice(taskId, storedSummary) {
+  // Control characters are stripped BEFORE the whitespace collapse, which only
+  // matches \s and would leave an ESC through. The stored summary is builder prose
+  // that has already been server-side stored and is already bound for Discord and
+  // the hall, so this crosses no new trust boundary — but this is the one place it
+  // reaches a TERMINAL, where an escape sequence could repaint the notice around it.
+  const stored = String(storedSummary || '')
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!stored) return [];
+  const shown = stored.length > 140 ? `${stored.slice(0, 139)}…` : stored;
+  return [
+    '⚠ No --summary given — this re-grade reuses the summary stored at the FIRST ship:',
+    `      "${shown}"`,
+    '  That sentence describes the attempt that FAILED its grade. A re-grade usually means the',
+    '  work changed since, and this text is what the panel reads, what the merge commit and PR',
+    '  say, and what goes to Discord #ship-news as the durable record of this ship.',
+    '',
+    '  If it still describes what landed, ignore this. If not, correct it in this same run:',
+    `    node scripts/bongos/ship.js ${taskId} --regrade --summary-file summary.txt`,
+    '  (the -file form is the safe one for prose — a shell eats backticks in an inline value)',
+  ];
+}
+
+// ---- a --db-only that cannot apply must SAY so (task 1003959) ---------------
+//
+// THE FIFTH SILENCE, and the only one that is not about prose: a flag the
+// operator typed, dropped without a word. zeroCommitVerdict(commitsAhead, dbOnly)
+// consults dbOnly ONLY at zero commits ahead — with commits ahead the verdict is
+// 'has-commits' and the run falls through to the ordinary merge/PR path, which
+// never receives dbOnly at all.
+//
+// The BEHAVIOUR is right and stays: a branch carrying real commits must be
+// merged, not waved through as an empty ship. What was missing is the sentence
+// saying so, and its absence is expensive out of proportion to its size — task
+// 1003229 was filed against --db-only and survived for days on the strength of
+// it. The reporter's flag was dropped here, their PR then failed to land for an
+// unrelated reason (the reconciler, task 1002723), and with nothing in the
+// output distinguishing an honoured flag from an ignored one, every visible sign
+// pointed at --db-only.
+//
+// So: a notice, not a refusal and not a behaviour change — the same posture as
+// staleSummaryNotice above, and testable for the same reason. It names the path
+// actually being taken, because "your flag was ignored" without "and here is
+// what is happening instead" only moves the confusion.
+//
+// Returns [] when the flag was HONOURED (zero commits ahead) or never passed —
+// a notice that fires on the happy path is noise.
+function dbOnlyIgnoredNotice(taskId, { dbOnly = false, commitsAhead = '0', branch = '', deployMode = 'laptop' } = {}) {
+  if (!dbOnly) return [];
+  // The one case the flag really covers. gitOk returns null when the count could
+  // not be read, which zeroCommitVerdict already treats as 'has-commits' — keep
+  // that reading rather than inventing a second opinion about the same branch.
+  if (String(commitsAhead) === '0') return [];
+
+  // Branch names and a git count both reach a TERMINAL here. git forbids control
+  // characters in a refname, so this strips nothing in practice — but the notice
+  // exists to be believed, and one that could be repainted from below by its own
+  // subject would be the wrong thing to have built.
+  const clean = (s) => String(s == null ? '' : s).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').replace(/\s+/g, ' ').trim();
+  const head = clean(branch) || 'this branch';
+  const n = Number(clean(commitsAhead));
+  const ahead = Number.isInteger(n) && n > 0
+    ? `${n} commit${n === 1 ? '' : 's'} ahead of origin/main`
+    : 'ahead of origin/main';
+  // Name the real path, not a generic one — 'ci' lands by PR and never touches
+  // the operator's main worktree; 'laptop' merges and deploys from this machine.
+  const instead = deployMode === 'ci'
+    ? `pushing ${head} and landing it by PR, with CI deploying`
+    : `pushing ${head}, merging it into main here and deploying`;
+
+  return [
+    `⚠ --db-only was passed, but ${head} is ${ahead} — the flag does not apply and is being IGNORED.`,
+    `  Shipping the normal way instead: ${instead}. Nothing is skipped and nothing is stranded.`,
+    '  --db-only only covers a ship with NOTHING to merge — work written straight to the prod DB.',
+    '  If you expected a zero-commit ship, this is the branch disagreeing; see what is on it:',
+    '    git log --oneline origin/main..HEAD',
+    `  Then re-ship when the branch is what you meant:  node scripts/bongos/ship.js ${taskId}`,
+  ];
+}
+
+module.exports = {
+  resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages,
+  proseFlagPresent, regradeNotesRefusal, staleSummaryNotice, dbOnlyIgnoredNotice,
+  _resetForTest: () => { shipProgress = { stage: 'preflight', taskId: null }; },
+  _peekForTest: () => shipProgress,
+};

package/scripts/bongos/ship-io.js

@@ -0,0 +1,139 @@
+// scripts/bongos/ship-io.js — API-error normalization and the small terminal effects (bell, post-land outcome).
+//
+// 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 2928-3007 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 os = require('node:os');
+const { playSound } = require('./ship-state.js');
+
+function playShipBell() {
+  let shipWav = 'ship';
+  try {
+    const raw = require('fs').readFileSync(shipPrefsPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    const ev = parsed && parsed.event_sounds && parsed.event_sounds['task-shipped'];
+    if (typeof ev === 'string') shipWav = ev;
+  } catch (_) { /* fall through to default */ }
+  playSound(shipWav);
+}
+
+// task 1003272: this used to hardcode ~/.config/otb/, the PRE-RENAME location,
+// while fetch-sound-prefs.js writes the mirror through
+// instance-config.configPath() — today ~/.config/cloudbongos/. Reader and writer
+// were looking at different files, so a builder's chosen ship sound was never
+// found and this always fell through to the 'ship' default. Resolve the SAME way
+// the writer does, with the legacy path as a fallback for an older box.
+function shipPrefsPath() {
+  try {
+    const p = require('../../src/instance-config').configPath('sound-prefs.json');
+    if (require('fs').existsSync(p)) return p;
+  } catch (_) { /* fall through to the legacy location */ }
+  return require('path').join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
+}
+
+// task 1002809: normalize an API error body across BOTH wire shapes — the live
+// ADR 0116 (R01) envelope `{ error: { code, message } }` and the legacy flat
+// `{ error: 'code' }`. Same normalization as claim.js:formatClaimFailure and
+// cli-lib:isBoxScope; pure + exported for tests/ship_post_land_verify.mjs.
+function normalizeApiError(data) {
+  const errRaw = data ? data.error : undefined;
+  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
+  return {
+    code: isEnvelope ? errRaw.code : errRaw,
+    message: isEnvelope ? errRaw.message : undefined,
+    // task 1002789: `details` is where the envelope carries the structured
+    // payload the flat shape used to put at the TOP level (claimWorktree,
+    // step/reason, floors). A site that reads `data.<field>` directly is
+    // reading a field that moved. Fall back to the body so a legacy flat
+    // response still resolves.
+    details: (isEnvelope && errRaw.details && typeof errRaw.details === 'object')
+      ? errRaw.details
+      : (data && typeof data === 'object' ? data : {}),
+  };
+}
+
+// isUnknownFieldRejection — did the server reject this request ONLY because it
+// does not know the named body field? (task 1003767)
+//
+// WHY THIS EXISTS. The resolve route validates STRICTLY: an unknown body field
+// is a hard 400, not an ignored extra. @cloudbongos/cli ships separately from
+// the core and instances pin their own core version, so a CLI that starts
+// sending a NEW field cannot resolve a claim at all against an instance whose
+// server has not learned it yet — the change that added `resolver_worktree` hit
+// exactly that on its own ship. A caller uses this to drop the field and retry
+// once, degrading to the older server's behaviour instead of failing to ship.
+//
+// Deliberately NARROW: true only when every returned detail names THIS field.
+// If the server also complained about anything else, the request has a real
+// problem and must surface — a blanket "retry without extras" would turn every
+// validation bug into a silent second attempt.
+//
+// Pure + exported so the decision is unit-testable without a server.
+function isUnknownFieldRejection(status, data, field) {
+  if (status !== 400) return false;
+  const details = normalizeApiError(data).details;
+  if (!Array.isArray(details) || details.length === 0) return false;
+  return details.every((d) => d && d.field === field);
+}
+
+// task 1002789: the ONE renderer for a failed API call on the ship path.
+// Every generic bail site used to hand the raw body to console.error (or
+// interpolate `data.error` into a template, which stringifies the ADR 0116
+// envelope object to the literal "[object Object]"). Both hide a fully
+// diagnosable server error: console.error's util.inspect stops at depth 2, so
+// the `details` that names WHICH git step failed prints as "[Object]".
+// Collapse the body to one readable line instead, whichever shape it is.
+// Pure + exported for tests/ship_error_shape.mjs.
+function apiErrorLine(data, status) {
+  const { code, message, details } = normalizeApiError(data);
+  const head = code
+    ? (message && message !== code ? `${code}: ${message}` : code)
+    : (message || (status ? `HTTP ${status}` : 'unknown error'));
+  // Only the small scalar fields — a details blob can carry a whole bundle.
+  const extras = Object.entries(details || {})
+    .filter(([k, v]) => k !== 'code' && k !== 'message' && k !== 'error'
+      && (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'))
+    .map(([k, v]) => `${k}: ${String(v).replace(/\s+/g, ' ').trim()}`);
+  const line = extras.length ? `${head} (${extras.join('; ')})` : head;
+  return status ? `${line} [HTTP ${status}]` : line;
+}
+
+// task 1002809: classify a FAILED post-land POST /tasks/<id>/ship. The merge
+// already succeeded, so the server may simply have landed the task first
+// (reconcile-on-read — task 1049 — or the ~5-min reconciler racing this call).
+// The old check compared `data.error === 'task_not_confirmed'` — dead against
+// the envelope shape, so the already-landed SUCCESS rendered as a failure with
+// an "[object Object]" reason (the HANDOFF-apex-ui "400 after a successful
+// land" gotcha). liveStatus is the task's status from a verify GET (null when
+// that GET itself failed): 'shipped' is authoritative success whatever the
+// error said; task_not_confirmed with no live status keeps the task-1049
+// benefit of the doubt; any KNOWN non-shipped status stays a loud failure.
+// Pure + exported for tests/ship_post_land_verify.mjs.
+function postLandShipOutcome({ code, liveStatus }) {
+  if (liveStatus === 'shipped') {
+    return { alreadyShipped: true, why: 'the server landed it first — the failed ship call lost that race, nothing to fix' };
+  }
+  if (liveStatus == null && code === 'task_not_confirmed') {
+    return { alreadyShipped: true, why: 'the server reconciled it from the merged PR' };
+  }
+  return { alreadyShipped: false };
+}
+
+// Step 3 of the lifecycle: confirmed → shipped. Merge the branch into main,
+// deploy, flip the task to shipped, and fire the Discord broadcast (only when
+// the change actually deploys — #94 / ADR 0032; best-effort). Side-effecting;
+// the early returns are control flow only.
+
+module.exports = {
+  shipPrefsPath,
+  apiErrorLine,
+  normalizeApiError,
+  isUnknownFieldRejection,
+  playShipBell,
+  postLandShipOutcome,
+};