@bongos/core 1.19.306 → 1.19.307

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.306",
-  "core_contract": "1.19.306",
-  "source_commit": "bfb69ddea49ebcce6d1d0608dd8e1fc50cc755e2",
+  "core_version": "1.19.307",
+  "core_contract": "1.19.307",
+  "source_commit": "b8d2ed227fd6cb0b948128e23f0daf0070b50bcc",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T19:41:29.546Z",
+  "built_at": "2026-08-23T20:16:34.186Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 322,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1416,
+    "functional_verbatim": 1418,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1760,
-  "tree_sha256": "a2c3f65e69e891c0076d0b10268d3549cfddf8d76d1f320274e86fd833d56013",
+  "file_count": 1762,
+  "tree_sha256": "2ce3db5cb1a893df39826469894f19d4acdee021e5729859eaa8d429933be04d",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -97,7 +97,7 @@
     {
       "path": ".claude/skills/builder-ship/SKILL.md",
       "mode": "0000644",
-      "sha256": "bb9075e768b4cbc6142e2b4b24a57f92e9a4ae75d76f6849566082e0c5495d13"
+      "sha256": "78fcb68ce3ff4b1028904acb9d4d0a37dadd8377108fefef248feef010e4c8b1"
     },
     {
       "path": ".claude/skills/builder-stage/SKILL.md",
@@ -142,7 +142,7 @@
     {
       "path": ".claude/skills/fix-task/SKILL.md",
       "mode": "0000644",
-      "sha256": "2ccc2a59ce44ba21c18db999c86768252b2fa6c8be6fa81f2b00a71eb727e664"
+      "sha256": "59b29fcdf54fe51e85191d1a66be237ef35432b76b26a10ec67e46bf08b4d1d3"
     },
     {
       "path": ".claude/skills/goal-create/SKILL.md",
@@ -1662,7 +1662,7 @@
     {
       "path": "docs/recipes/claude-design-loop.md",
       "mode": "0000644",
-      "sha256": "4f2e7cc445ae05968ba65fcb0c995cb358f144344dcb498047ec753a5a229a39"
+      "sha256": "389dbbbfb7c941315731d533e300b5d43f40a8aac866c5a1c74c32d5be212a22"
     },
     {
       "path": "docs/recipes/core-release-pipeline.md",
@@ -1687,7 +1687,7 @@
     {
       "path": "docs/recipes/figma-design-loop.md",
       "mode": "0000644",
-      "sha256": "0c2c462d59634b9ec0e777d713cbc0bdc5af06408aa8b3717d2afac09c0070f0"
+      "sha256": "6bfee82bddc07a5743316e310dda1e6cb7266fa7805fc1eed67bc8cc17980b46"
     },
     {
       "path": "docs/recipes/gds-db-backup.md",
@@ -4577,12 +4577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ab53e6d02f437a24895dd3d04b3e8ef39ddf4257b8c4b2e784a84dd10820adc4"
+      "sha256": "4815e8ce78e80ac2fff7dad9f77bef508e2f0090459c67e59722b65af3e27294"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c98acd264e43f570b82f0c7c72efb952d6e68758794f4c49a78db06cf44a867f"
+      "sha256": "bdeee91142d9d7f3930c99134be76d03f28329222adcf293deaa8f8354ab2cd8"
     },
     {
       "path": "public-docs/index.html",
@@ -5082,7 +5082,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "95574e210b1fd215b10c7664da109b0698b18aa7724daa736bade6d752318f63"
+      "sha256": "5aa658b099b2acda06cdb3aecfe905da7de79f2b12c844faca091ff061454017"
     },
     {
       "path": "scripts/gds/code.js",
@@ -5784,10 +5784,15 @@
       "mode": "0000644",
       "sha256": "087def1396283b19cb8a6deea4cc7f362d7a2f164d496a587220f0a48568aae6"
     },
+    {
+      "path": "scripts/gds/ship-honesty.js",
+      "mode": "0000644",
+      "sha256": "32827178a46cc01c36c422e1adef433be99492e8444a8affbe51e5e8c1e8ce9f"
+    },
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "73c2e91340171d6a9112e869552be17e0f82aeb80a5c680205ac452d34c3ddc4"
+      "sha256": "f3005175abc0ba20e958381df6aee02402267e9956da466386656dd4e86ad8cf"
     },
     {
       "path": "scripts/gds/smoke-batch-claim.sh",
@@ -6242,7 +6247,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "31f8e9579aa3e015fc2c1f819d5d84076db27e831bfb3419ca48141cbcd84038"
+      "sha256": "90436d6db6e32424c48549f61ad48a3a77f5c7cac1ae16d5559b7db76fee7b4a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -8282,7 +8287,7 @@
     {
       "path": "tests/route_rank_check.mjs",
       "mode": "0000644",
-      "sha256": "1cb0af04d3f0f837ab19c5c821e91ca7a183f2744608d7ee3b79b4886fbbd4ed"
+      "sha256": "bdc58224050392ece492ae8e8f12f62a8934d86e3993e0df5b8cb0aac80602e8"
     },
     {
       "path": "tests/route_validation.mjs",
@@ -8504,6 +8509,11 @@
       "mode": "0000644",
       "sha256": "afdb09a3ee072fea82390a187c12c42d8249fce0ce84644a4b8dff6a643dd009"
     },
+    {
+      "path": "tests/ship_cannot_lie.mjs",
+      "mode": "0000644",
+      "sha256": "82f6f951cc50c34860545be0f309e18a796ebb5baa712ccb341e1fd0dd72a233"
+    },
     {
       "path": "tests/ship_card.mjs",
       "mode": "0000644",
@@ -8552,7 +8562,7 @@
     {
       "path": "tests/ship_smoke_gate.mjs",
       "mode": "0000644",
-      "sha256": "43e2f109ce85e99e71daa4573a6ec4fc591b167fe81ee02f2f73ea1ce84d465c"
+      "sha256": "6ce7bd5d2a8910e201a9869c8a3f22ef210fd4400fbd14777d8d15d13252a97e"
     },
     {
       "path": "tests/ship_upload_skip.mjs",

package/.claude/skills/builder-ship/SKILL.md

@@ -7,7 +7,7 @@ You are shipping a task on behalf of the current builder. Shipping is the moment
 
 ## What this skill does
 
-Runs `node scripts/gds/ship.js <task-id> --notes "..." --summary "..."`.
+Runs `node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt`.
 
 The CLI drives a **three-state lifecycle** with a subagent grader between states (Phase 5, 2026-05-10):
 
@@ -34,7 +34,7 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
 
    **When you see that block, position the sandbox link prominently for the builder.** `ship.js` also emits the deterministic lifecycle card for the `review` stage (an `[otb-card-html] <path>` marker) — if an in-feed visualization tool is available, render that card (its primary action is **Open in sandbox ↗**, the URL); it's the cleanest way to make the link impossible to miss. Either way, surface the URL as its own standalone, clickable line in chat — a clear callout, NOT buried inside a paragraph of command output — and say in one line what to look at. This is the moment the change is ready to review; the link must be impossible to miss. Let the builder open it, review, and suggest changes; iterate if needed. **Only once the builder explicitly approves, re-run with `node scripts/gds/ship.js <id> --approved`** — that records their sign-off as a durable `sandbox_review` fact on the task (who, when, and the content stamp of exactly what was reviewed). Never pass `--approved` yourself without a real human go; the pause + sign-off IS the feature. `--skip-stage` is the escape hatch (use sparingly — the gate exists so unreviewed game changes don't ride straight to prod). Laptop sessions and non-game diffs are unaffected.
 
-2. **Compose the handoff notes (`--notes`)** following the structure in `docs/handoff-template.md`:
+2. **Compose the handoff notes (`--notes-file`)** following the structure in `docs/handoff-template.md`:
    - What shipped (with confidence tags: verified-prod | verified-smoke | implemented-not-verified)
    - What's broken or unverified
    - Manual checks the next session should run first
@@ -52,16 +52,28 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
    - "Sessions can claim work atomically; merge conflicts can't happen across worktrees."
    No jargon, no file paths, no commit hashes.
 
-4. **Run**:
+4. **Run** — write the prose to files and pass the file (task 1003168):
    ```bash
-   node scripts/gds/ship.js <task-id> \
-     --notes "$(cat <<'EOF'
-   ...handoff markdown...
-   EOF
-   )" \
-     --summary "the one-liner"
+   # write notes.md and summary.txt with your editor/Write tool first
+   node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt
    ```
 
+   **Use the `-file` forms.** Handoff notes are technical prose, so they contain
+   backticks — and a backtick in an inline `--notes "..."` is command-substituted
+   by the shell *before* node runs: the span executes, its output replaces it, and
+   the rest of the argument list is truncated. That is not hypothetical; it shipped
+   a task with **empty notes and no summary**, so the ledger held nothing about a
+   session that had happened (learning 1000197). A file argument is the one form
+   the shell cannot rewrite. `-` reads stdin if you'd rather pipe.
+
+   Inline `--notes "..."` / `--summary "..."` still work for short prose with no
+   backticks, `$`, or newlines. The older documented form —
+   `--notes "$(cat <<'EOF' … EOF)"` — is *also* shell-safe, because the quoted
+   heredoc delimiter suppresses expansion; it is simply easy to get subtly wrong,
+   and when you do the failure is silent. Passing both `--notes` and
+   `--notes-file` is refused rather than resolved by precedence, so nothing you
+   wrote is dropped without a word.
+
    **Never merge a task branch to main before running `ship.js`.** `ship.js` diffs the claim branch against `main`; an already-merged branch yields an empty diff, and the only exits are `--allow-empty` (dead-ends the task at `completed`, requiring an Archon-only confirm) or reverting the merge. Ship from the branch, then let `ship.js` land it. (This trap was hit on tasks 1002417 and 1002419, producing blockers 1000081/1000082 and an ~8.5-hour stall.)
 
 5. **Render the completion card — it IS the summary; do NOT write a prose recap (task 1270).**

package/.claude/skills/fix-task/SKILL.md

@@ -39,7 +39,7 @@ Runs the recurring "claim, fix, and ship task NNNN" macro end to end. Its own va
 
 6. **Ship from the claim branch** — see `/builder-ship` for handoff notes, the value summary, and the completion-card rendering contract. In short:
    ```
-   node scripts/gds/ship.js <id> --notes "..." --summary "..."
+   node scripts/gds/ship.js <id> --notes-file notes.md --summary-file summary.txt
    ```
    **Never merge the claim branch into `main` before running `ship.js`.** `ship.js` diffs the branch against `main`; a pre-merged branch yields an empty diff, and the only way out is `--allow-empty` (dead-ends the task at `completed`, needing an Archon-only confirm) or reverting the merge. Ship from the branch and let `ship.js` land it — the same trap `/builder-ship` calls out.
 

package/docs/recipes/claude-design-loop.md

@@ -113,7 +113,7 @@ The adapter writes files to `src/ui/<surfaceId>/` and updates `config/design-sou
 ```bash
 git add src/ui/hall-ui/ config/design-sources.json
 git commit -m "ui(hall-ui): Claude Design export (task 1234)"
-node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+node scripts/gds/ship.js 1234 --notes-file notes.md --summary-file summary.txt
 ```
 
 ---

package/docs/recipes/figma-design-loop.md

@@ -98,7 +98,7 @@ The adapter translates frames/text/solid-fill rectangles into `.js` + `.css` fil
 ```bash
 git add src/ui/hall-ui/ config/design-sources.json
 git commit -m "ui(hall-ui): Figma export (task 1234)"
-node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+node scripts/gds/ship.js 1234 --notes-file notes.md --summary-file summary.txt
 ```
 
 ---

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.306",
+  "version": "1.19.307",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.306",
+      "version": "1.19.307",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.306",
+  "version": "1.19.307",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/cli-lib.js

@@ -266,6 +266,58 @@ function stripBom(s) {
   return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
 }
 
+// argText(name, args, io) — resolve prose passed EITHER inline (`--notes "..."`)
+// or from a file (`--notes-file path`, or `-` for stdin). Returns
+// { value, source, error }: `value` is a string ('' when neither flag is
+// present), `source` is 'inline' | 'file' | 'stdin' | 'none', and `error` is a
+// caller-printable string when the request was refused or unreadable.
+//
+// WHY THIS EXISTS (learning 1000197). Prose handed to a CLI inline goes through
+// the SHELL first. A handoff note containing backticks — which technical prose
+// constantly does — is command-substituted by bash before node ever runs: the
+// backticked span executes, its output replaces it, and the rest of the argument
+// list is truncated. That is not a theoretical hazard; it silently shipped a task
+// with EMPTY notes and no summary, so the ledger recorded nothing about a session
+// that had happened. A file argument is the only form the shell cannot rewrite.
+//
+// BOTH-GIVEN IS AN ERROR, never a silent precedence. Picking one would mean the
+// caller's other input vanished without a word — the same class of quiet loss
+// this helper exists to end (the capture.js --spark/--full refusal precedent).
+function argText(name, args = process.argv.slice(2), io = {}) {
+  const readFile = io.readFile || ((f) => require('fs').readFileSync(f, 'utf8'));
+  const readStdin = io.readStdin || (() => require('fs').readFileSync(0, 'utf8'));
+  const fileFlag = `${name}-file`;
+  const inline = arg(name, args);
+  // arg() returns undefined (not null) for a flag present as the LAST token, so
+  // presence must be tested separately — otherwise `--notes-file` with no path
+  // slips past the null check and resolves to an empty string, which is the very
+  // silent-empty outcome this helper exists to prevent.
+  const filePresent = args.includes(fileFlag) || args.some((a) => a.startsWith(`${fileFlag}=`));
+  const file = filePresent ? arg(fileFlag, args) : null;
+
+  if (inline != null && filePresent) {
+    return {
+      value: '', source: 'none',
+      error: `${name} and ${fileFlag} were both given. Pass one — ${fileFlag} is the safe form for prose `
+        + '(a shell rewrites backticks in an inline value before node sees it). Refusing rather than '
+        + 'silently picking one, so nothing you wrote is dropped without a word.',
+    };
+  }
+  if (filePresent) {
+    if (file == null || file === '' || file.startsWith('--')) {
+      return { value: '', source: 'none', error: `${fileFlag} needs a path (or - for stdin).` };
+    }
+    try {
+      const raw = file === '-' ? readStdin() : readFile(file);
+      return { value: stripBom(String(raw)), source: file === '-' ? 'stdin' : 'file', error: null };
+    } catch (err) {
+      return { value: '', source: 'none', error: `could not read ${fileFlag} ${file}: ${err.message}` };
+    }
+  }
+  if (inline != null) return { value: inline, source: 'inline', error: null };
+  return { value: '', source: 'none', error: null };
+}
+
 // resolveQuiet(args, env) — true when api.js's stderr status banner should be
 // suppressed: the --quiet flag or the GDS_QUIET env var. Both default to the
 // live process, matching hasFlag()'s own default-args contract. Default OFF —
@@ -853,6 +905,7 @@ module.exports = {
   loadSessionSync,
   saveSession,
   arg,
+  argText,
   hasFlag,
   stripBom,
   repairMsysMangledPath,

package/scripts/gds/ship-honesty.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// scripts/gds/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/gds/ship.js ${id}` : 'node scripts/gds/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/gds/ship.js ${taskId}`,
+      `  - Ship anyway (deliberate):    node scripts/gds/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/gds/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.)",
+    ],
+  };
+}
+
+module.exports = {
+  resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages,
+  _resetForTest: () => { shipProgress = { stage: 'preflight', taskId: null }; },
+  _peekForTest: () => shipProgress,
+};

package/scripts/gds/ship.js

@@ -12,6 +12,7 @@
 // the task stays at 'confirmed' for /merge-mode to land later.
 //
 // Usage:
+//   node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt
 //   node scripts/gds/ship.js <task-id> --notes "handoff markdown" --summary "value-summary line"
 //   node scripts/gds/ship.js <task-id> --no-merge      # stop after confirm; skip auto-merge
 //   node scripts/gds/ship.js <task-id> --db-only       # deliberate zero-commit / direct-SQL ship (task 391):
@@ -62,6 +63,8 @@ const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
 const { cliClient, requireSession, loadSession, loadSessionSync, printOnboardingNudge, arg, rewardPolicy } = require('./cli-lib');
+// task 1003168 (G04): how a ship reports prose + an unfinished run — see that file.
+const { resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages } = require('./ship-honesty.js');
 
 // The instance's reward policy, as reported by the server on GET /me (ADR 0146 /
 // task 1002469). Cached module-level because the credits print + the completion
@@ -2235,32 +2238,6 @@ function runSmokeAsync() {
   });
 }
 
-// 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/gds/ship.js ${taskId}`,
-      `  - Ship anyway (deliberate):    node scripts/gds/ship.js ${taskId} --allow-smoke-fail`,
-      `    (parks the task at 'completed' ungraded; resume later with --regrade)`,
-    ],
-    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/gds/ship.js ${taskId} --regrade`,
-    ],
-  };
-}
-
 // ---------- Step 3: merge + deploy chain ----------
 
 function currentBranch() {
@@ -3696,11 +3673,14 @@ async function shipMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --notes "..." --summary "..." [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('  prefer the -file forms for prose: a shell command-substitutes backticks in an inline value before node sees it (learning 1000197).');
     process.exit(2);
   }
-  const notes = arg('--notes', args) || '';
-  const summary = arg('--summary', args) || '';
+  // 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,
@@ -4114,6 +4094,8 @@ async function shipMain() {
 
   const taskStatus = r.data.taskStatus || 'shipped (legacy response)';
   console.log(`Task #${r.data.taskId} is now: ${taskStatus}`);
+  // Claim CONSUMED, task at 'completed' — a crash from here needs fatalRecoveryLines.
+  markShipProgress('resolved', taskId);
 
   // ---- Step 2: subagent quality grader ----
   // Runs when local verification passed AND resolveClaim landed at completed.
@@ -4241,6 +4223,10 @@ async function shipMain() {
   // ---- Step 3: confirmed→shipped tail (merge + deploy → memory/session sync →
   // Done → onboarding nudge → completion card), shared with regradeMain via
   // finishShip (#1093/C9). ----
+  // Graded. If it passed, only the merge remains — a different crash story.
+  if (postGradeStatus === 'confirmed' || postGradeStatus === 'shipped') {
+    markShipProgress(postGradeStatus === 'shipped' ? 'landed' : 'graded', taskId);
+  }
   await finishShip({
     taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly,
     // task 1270: data for the deterministic completion card.
@@ -4283,14 +4269,15 @@ async function regradeMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary "..."] [--response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary-file <path|-> | --summary "..."] [--response-file <path|-> | --response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
     process.exit(2);
   }
-  const summaryArg = arg('--summary', args) || '';
+  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 = arg('--response', args) || '';
+  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>`
@@ -4609,6 +4596,7 @@ module.exports = {
   // / non-ci → false) is unit-tested with no gh/network (env-driven via
   // OTB_DEPLOY_MODE + OTB_PUSH_VIA_SERVER).
   broadcastHandledByServer,
+  fatalRecoveryLines, // G04 re-export (definition in ship-honesty.js)
 };
 
 if (require.main === module) {
@@ -4617,6 +4605,9 @@ if (require.main === module) {
   const main = process.argv.slice(2).includes('--regrade') ? regradeMain : shipMain;
   main().catch((err) => {
     console.error('fatal:', err);
+    // G04: never exit on a stack trace alone — say which leg died.
+    console.error('');
+    for (const line of fatalRecoveryLines()) console.error(line);
     process.exit(1);
   });
 }

package/src/module-api.js

@@ -1039,8 +1039,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.304 with no explicit bump. run 32660902666. (task 1002620)
 //   1.19.306 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.305 with no explicit bump. run 32662000590. (task 1002620)
+//   1.19.307 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.306 with no explicit bump. run 32663876767. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.306'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.307'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/route_rank_check.mjs

@@ -427,19 +427,127 @@ test('LIVE: checkRouteRanks() on src/bongos/routes/ has zero unknowns', () => {
   assert.equal(res.hardFail, false);
 });
 
-// The census invariant (BV1.R109b). Asserting that the 10 known multi-line paths parse
-// would prove nothing about the ELEVENTH — the next route someone declares in a form
-// this scanner doesn't handle. So count instead: every `router.<method>(` line in every
-// discovered route file must yield exactly one classified route.
+// The census invariant (BV1.R109b, re-derived in task 1002671). Asserting that the 10
+// known multi-line paths parse would prove nothing about the ELEVENTH — the next route
+// someone declares in a form this scanner doesn't handle. So count instead: every
+// `router.<method>(` call in every discovered route file must yield exactly one
+// classified route.
 //
-// The census regex below is HAND-WRITTEN here on purpose and NOT imported from the
-// module. Importing ROUTE_DECL_RE would move both sides of the comparison together and
-// prove nothing (the oracle trap tests/route_permission_check.mjs documents).
-const CENSUS_DECL_RE = /^\s*router\.(?:get|post|patch|put|delete)\s*\(/;
+// ORACLE INDEPENDENCE (the 2026-07-30 review's HIGH finding, confirmed): the first cut
+// of this census was a verbatim copy of the scanner's own ROUTE_DECL_RE — hand-written,
+// but shape-identical, so any widening of the scanner would be pasted into the census
+// and both sides would move together. The census below is derived on a structurally
+// different axis instead:
+//   • token-level, not line-level — comments and string/template/regex literals are
+//     stripped first by a tiny tokenizer, then calls are counted in the whole text;
+//   • not line-anchored — an inline/chained/mid-line declaration counts here even
+//     though the scanner's `^\s*` form cannot see it;
+//   • whitespace-tolerant across the member access (`router . get (` counts).
+// A unilateral change to the scanner's recognizer now shows up as a census mismatch
+// and forces a DELIBERATE census-side decision, instead of going green by paste.
+//
+// The tokenizer is deliberately small and fail-closed: if it ever misreads a future
+// route file, the equality below goes red and a human looks — that is the correct
+// failure mode for an audit oracle (never silently green).
+function stripNonCode(src) {
+  let out = '';
+  const n = src.length;
+  const tplBraceDepth = []; // one entry per open template-literal interpolation
+  let i = 0;
+  const KEYWORDS_BEFORE_REGEX = new Set(['return', 'typeof', 'case', 'in', 'of', 'instanceof', 'new', 'delete', 'void', 'do', 'else', 'yield', 'await']);
+  const regexCanFollow = () => {
+    const t = out.trimEnd();
+    if (t === '') return true;
+    const last = t[t.length - 1];
+    if ('(,=:[!&|?{};+-*%~^<>'.includes(last)) return true;
+    const word = /[A-Za-z_$][\w$]*$/.exec(t);
+    return !!(word && KEYWORDS_BEFORE_REGEX.has(word[0]));
+  };
+  // Consume string/template BODY starting at src[i] (opening quote already emitted
+  // and consumed). For templates, stops early at `${` and pushes an interpolation
+  // frame — the main loop then lexes the interpolation as code until its `}`.
+  const skipStringBody = (quote) => {
+    while (i < n && src[i] !== quote) {
+      if (src[i] === '\\') { out += '..'; i += 2; continue; }
+      if (quote === '`' && src[i] === '$' && src[i + 1] === '{') { out += '${'; i += 2; tplBraceDepth.push(0); return 'interp'; }
+      out += (src[i] === '\n' ? '\n' : '.'); i++;
+    }
+    out += quote; i++; // closing quote (or EOF)
+    return 'closed';
+  };
+  const skipString = (quote) => {
+    out += quote; i++;
+    return skipStringBody(quote);
+  };
+  while (i < n) {
+    const c = src[i], d = src[i + 1];
+    if (c === '/' && d === '/') { while (i < n && src[i] !== '\n') i++; continue; }
+    if (c === '/' && d === '*') { i += 2; while (i < n && !(src[i] === '*' && src[i + 1] === '/')) { if (src[i] === '\n') out += '\n'; i++; } i += 2; out += ' '; continue; }
+    if (c === '/' && regexCanFollow()) { // regex literal (handles quotes inside, e.g. /[&<>"']/)
+      out += '/'; i++;
+      let inClass = false;
+      while (i < n && (inClass || src[i] !== '/')) {
+        if (src[i] === '\\') { out += '..'; i += 2; continue; }
+        if (src[i] === '[') inClass = true;
+        else if (src[i] === ']') inClass = false;
+        out += '.'; i++;
+      }
+      out += '/'; i++;
+      while (i < n && /[a-z]/i.test(src[i])) { out += src[i]; i++; } // flags
+      continue;
+    }
+    if (c === '\'' || c === '"' || c === '`') { skipString(c); continue; }
+    if (tplBraceDepth.length) { // inside a template interpolation: brace-track back to the template
+      if (c === '{') tplBraceDepth[tplBraceDepth.length - 1]++;
+      if (c === '}') {
+        if (tplBraceDepth[tplBraceDepth.length - 1] === 0) {
+          tplBraceDepth.pop(); out += '}'; i++;
+          skipStringBody('`'); // resume the enclosing template's body (may re-enter an interpolation)
+          continue;
+        }
+        tplBraceDepth[tplBraceDepth.length - 1]--;
+      }
+    }
+    out += c; i++;
+  }
+  return out;
+}
+
+// HAND-WRITTEN on purpose and NOT imported from the module (the oracle trap
+// tests/route_permission_check.mjs documents) — and, unlike the pre-1002671 census,
+// deliberately NOT shape-identical to the scanner's ROUTE_DECL_RE either.
+const CENSUS_CALL_RE = /\brouter\s*\.\s*(?:get|post|patch|put|delete)\s*\(/g;
+// A computed member declaration (`router[method](…)`) is invisible to every static
+// recognizer on both sides. Fail loud instead of silently under-counting.
+const CENSUS_DYNAMIC_RE = /\brouter\s*\[/;
 // A floor, so a change that silently guts BOTH sides (e.g. discoverRouteFiles stops
 // finding module routes) reds instead of trivially "matching" at a smaller number.
 const ROUTE_CENSUS_FLOOR = 258;
 
+function censusCount(text) {
+  const code = stripNonCode(String(text));
+  assert.ok(!CENSUS_DYNAMIC_RE.test(code),
+    'route file uses a computed router[method](…) declaration — invisible to the rank auditor; declare it statically');
+  return (code.match(CENSUS_CALL_RE) || []).length;
+}
+
+test('census tokenizer: strips comments, strings, and quote-bearing regex literals', () => {
+  assert.equal(censusCount(`// router.get('/a', h)\nrouter.post('/b', h);`), 1);
+  assert.equal(censusCount(`const s = "router.get('/a'"; router.get('/b', h);`), 1);
+  assert.equal(censusCount(`s.replace(/[&<>"']/g, esc); router.get('/x', h);`), 1);
+  assert.equal(censusCount('const t = `x ${router.get(\'/live\', h)} y`;'), 1);
+});
+
+test('census independence: counts declarations the line-anchored scanner cannot see', () => {
+  // Inline (mid-line) declaration: census sees it, scanDeclarations does not. If the
+  // scanner ever learns this form, this fixture forces the census comparison to be
+  // revisited deliberately rather than drifting in lockstep.
+  const text = `if (flag) router.get('/inline', h);`;
+  assert.equal(censusCount(text), 1);
+  assert.equal(rrc.classifyText(text).length, 0,
+    'fixture stale: the scanner now classifies inline declarations — update the census comment');
+});
+
 test('LIVE census: every router.<method>( declaration classifies to exactly one route [BV1.R109b]', () => {
   const fs = require('node:fs');
   let declared = 0;
@@ -447,7 +555,7 @@ test('LIVE census: every router.<method>( declaration classifies to exactly one
   const shortfall = [];
   for (const { abs, rel } of rrc.discoverRouteFiles()) {
     const text = fs.readFileSync(abs, 'utf8');
-    const d = text.split('\n').filter((l) => CENSUS_DECL_RE.test(l)).length;
+    const d = censusCount(text);
     const c = rrc.classifyText(text).length;
     declared += d;
     classified += c;

package/tests/ship_cannot_lie.mjs

@@ -0,0 +1,168 @@
+// tests/ship_cannot_lie.mjs — G04, task 1003168, goal 1000077, criterion
+// guards-ship-cannot-lie.
+//
+// TWO fixes, one incident, so one test file.
+//
+// (1) Prose reaches ship.js through a FILE, never only through the shell.
+//     Backticks in handoff notes are command-substituted by bash BEFORE node
+//     runs: the span executes, its output replaces it, and the remaining
+//     arguments are truncated. That shipped a task with empty notes and no
+//     summary — the ledger recorded nothing about a session that happened
+//     (learning 1000197).
+//
+// (2) A ship that dies mid-pipeline must say where it stopped. resolveClaim
+//     lands the task at 'completed' before the grade runs, and 'completed' is
+//     ALSO what a grade-failed task looks like — so a bare `fatal: <stack>`
+//     left nobody able to tell how far it got.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { argText } = require('../scripts/gds/cli-lib.js');
+const { fatalRecoveryLines, markShipProgress, _peekForTest } = require('../scripts/gds/ship-honesty.js');
+
+// Injected IO so no case touches the filesystem.
+const io = {
+  readFile: (f) => {
+    if (f === 'notes.md') return 'real notes with `backticks` in them';
+    if (f === 'bom.md') return 'after a BOM';
+    throw new Error('ENOENT: no such file');
+  },
+  readStdin: () => 'from stdin',
+};
+
+// ---- (1) prose from a file -------------------------------------------------
+test('THE INCIDENT: a file argument carries backticks through untouched', () => {
+  // The shell never sees this content, so the backticks survive verbatim —
+  // that is the entire point of the flag.
+  const r = argText('--notes', ['--notes-file', 'notes.md'], io);
+  assert.equal(r.source, 'file');
+  assert.match(r.value, /`backticks`/);
+  assert.equal(r.error, null);
+});
+
+test('inline still works, for a short summary with no awkward characters', () => {
+  const r = argText('--summary', ['--summary', 'one line'], io);
+  assert.deepEqual([r.value, r.source, r.error], ['one line', 'inline', null]);
+});
+
+test('BOTH given is REFUSED, never silently resolved', () => {
+  // Precedence would mean one of the caller's two inputs vanished with no word
+  // said — the same quiet loss the flag exists to end.
+  const r = argText('--notes', ['--notes', 'a', '--notes-file', 'notes.md'], io);
+  assert.ok(r.error, 'both-given must be an error');
+  assert.match(r.error, /both/i);
+  assert.equal(r.value, '', 'a refusal must not hand back a half-resolved value');
+});
+
+test('a dash reads stdin', () => {
+  const r = argText('--notes', ['--notes-file', '-'], io);
+  assert.deepEqual([r.value, r.source], ['from stdin', 'stdin']);
+});
+
+test('an unreadable file is an error, not silently empty', () => {
+  // Silently-empty is precisely how the original incident hid itself.
+  const r = argText('--notes', ['--notes-file', 'gone.md'], io);
+  assert.ok(r.error);
+  assert.match(r.error, /could not read/);
+});
+
+test('a missing value for the file flag is caught, including a following flag', () => {
+  for (const args of [['--notes-file'], ['--notes-file', '--summary', 'x']]) {
+    const r = argText('--notes', args, io);
+    assert.ok(r.error, `${JSON.stringify(args)} must error`);
+    assert.match(r.error, /needs a path/);
+  }
+});
+
+test('a PowerShell BOM is stripped', () => {
+  // PS 5.1's `>` redirection writes a UTF-8 BOM; without stripping it the first
+  // character of every note would be U+FEFF.
+  const r = argText('--notes', ['--notes-file', 'bom.md'], io);
+  assert.equal(r.value, 'after a BOM');
+});
+
+test('neither flag yields empty string, not null — callers concatenate it', () => {
+  const r = argText('--notes', [], io);
+  assert.deepEqual([r.value, r.source, r.error], ['', 'none', null]);
+});
+
+// ---- (2) the ship cannot lie about how far it got --------------------------
+test('every stage names the task, its real status, and a recovery command', () => {
+  for (const stage of ['preflight', 'resolved', 'graded', 'landed']) {
+    const lines = fatalRecoveryLines({ stage, taskId: 4242 });
+    assert.ok(Array.isArray(lines) && lines.length >= 3, `${stage} must say something`);
+    for (const l of lines) assert.equal(typeof l, 'string', `${stage} lines are printable as-is`);
+    assert.ok(lines.some((l) => l.includes('4242')), `${stage} must name the task`);
+    assert.ok(
+      lines.some((l) => l.includes('node scripts/gds/ship.js 4242')),
+      `${stage} must name the command that recovers it`,
+    );
+  }
+});
+
+test('pre-resolve says the claim is INTACT — the opposite of the post-resolve case', () => {
+  const text = fatalRecoveryLines({ stage: 'preflight', taskId: 7 }).join('\n');
+  assert.match(text, /NOT resolved/);
+  assert.match(text, /still active/);
+});
+
+test("post-resolve names 'completed' AND that the grade did not record", () => {
+  // The distinction the status itself cannot make.
+  const text = fatalRecoveryLines({ stage: 'resolved', taskId: 7 }).join('\n');
+  assert.match(text, /'completed'/);
+  assert.match(text, /grade did NOT record/);
+  assert.match(text, /No credits/i);
+});
+
+test("post-grade names 'confirmed' and that the grade PASSED", () => {
+  const text = fatalRecoveryLines({ stage: 'graded', taskId: 7 }).join('\n');
+  assert.match(text, /'confirmed'/);
+  assert.match(text, /PASSED/);
+});
+
+test('the landed stage does NOT claim the ship failed', () => {
+  // It reached 'shipped'; only the after-work broke. Saying "the ship did not
+  // finish" there would be the same lying-status problem in reverse.
+  const lines = fatalRecoveryLines({ stage: 'landed', taskId: 7 });
+  assert.match(lines[0], /LANDED/);
+  assert.ok(!/did NOT finish/.test(lines.join('\n')));
+});
+
+test('NO stage recommends --regrade as the recovery', () => {
+  // A plain re-run routes by the task's CURRENT status, so it resumes whichever
+  // leg stalled. --regrade accepts only 'completed' and refuses a task that got
+  // to 'confirmed' — and the builder reading a crash cannot know which it is.
+  for (const stage of ['preflight', 'resolved', 'graded', 'landed']) {
+    const text = fatalRecoveryLines({ stage, taskId: 7 });
+    for (const l of text) {
+      assert.ok(
+        !/^\s*Resume:?\s+node .*--regrade/.test(l) && !/re-run:\s+node .*--regrade/.test(l),
+        `${stage} must not prescribe --regrade: ${l}`,
+      );
+    }
+  }
+});
+
+test('an unknown stage degrades to the safe pre-resolve message', () => {
+  // A future leg added without a case here must not produce a confident wrong
+  // claim about credits or status.
+  const text = fatalRecoveryLines({ stage: 'something-new', taskId: 7 }).join('\n');
+  assert.match(text, /NOT resolved/);
+});
+
+test('a missing taskId still yields a usable command', () => {
+  const text = fatalRecoveryLines({ stage: 'resolved', taskId: null }).join('\n');
+  assert.match(text, /ship\.js <task-id>/);
+});
+
+test('markShipProgress is the single writer, and ship.js re-exports the reader', () => {
+  // Wiring proof: the extraction must not have left ship.js reading a stale copy.
+  markShipProgress('graded', 99);
+  assert.deepEqual(_peekForTest(), { stage: 'graded', taskId: 99 });
+  assert.match(fatalRecoveryLines().join('\n'), /#99/, 'the default arg reads live progress');
+  const shipCli = require('../scripts/gds/ship.js');
+  assert.equal(typeof shipCli.fatalRecoveryLines, 'function', 'ship.js still exposes it');
+  assert.equal(shipCli.fatalRecoveryLines, fatalRecoveryLines, 'same function, not a copy');
+});

package/tests/ship_smoke_gate.mjs

@@ -14,7 +14,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const { smokeGateMessages } = require('../scripts/gds/ship.js');
+const { smokeGateMessages } = require('../scripts/gds/ship-honesty.js');
 
 let passed = 0;
 let failed = 0;
@@ -61,8 +61,14 @@ t('parked: names the deliberate stop, the exact status, and that nothing was pai
   assert.match(parkedText, /no credits/i);
 });
 
-t('parked: names the resume path (--regrade)', () => {
-  assert.match(parkedText, /ship\.js 1234 --regrade/);
+t('parked: names the resume path (a plain re-run, not --regrade)', () => {
+  // task 1003168 (G04): this used to say --regrade. A plain re-run routes by the
+  // task's CURRENT status, so it resumes whichever leg stalled; --regrade accepts
+  // only 'completed' and refuses a task that got as far as 'confirmed'. Since the
+  // builder reading this cannot know which leg died, the advice must be the
+  // command that works from either.
+  assert.match(parkedText, /ship\.js 1234$|ship\.js 1234\s/m);
+  assert.ok(!/ship\.js 1234 --regrade/.test(parkedText), 'must not recommend --regrade');
 });
 
 t('both message sets are non-empty arrays of strings (printable as-is)', () => {