@bongos/core 1.21.102 → 1.21.104

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.102",
-  "core_contract": "1.21.102",
-  "source_commit": "f552db78c82ef1ca4418a9de313e150bb29ce4b1",
+  "core_version": "1.21.104",
+  "core_contract": "1.21.104",
+  "source_commit": "cfc8c3651ea3f442385e6d0ba405c6a578b4d83a",
   "source_ref": "HEAD",
-  "built_at": "2026-10-09T13:15:03.097Z",
+  "built_at": "2026-10-09T13:49:17.283Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 592,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3019,
+    "functional_verbatim": 3021,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3640,
-  "tree_sha256": "834d88c63001764c8ed72f393a6c49d3d123469f268cf129a13cab0b342e5ebe",
+  "file_count": 3642,
+  "tree_sha256": "b23d12f504071337f2882e99100b69132448daa2e65560c851411b6a667c5f67",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -207,7 +207,7 @@
     {
       "path": ".claude/skills/planning-session/SKILL.md",
       "mode": "0000644",
-      "sha256": "692b9954a308f817798c8ce6c6811a61a020c588555073f7ba99f75044ab3b18"
+      "sha256": "0447f0526aaf9735f47cb52fe7423914f8aba4cfbeb0f9b56fa49e0d4e5073fd"
     },
     {
       "path": ".claude/skills/priority-session/SKILL.md",
@@ -2872,7 +2872,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b44e9230778cf7b2aafd8d7971fb862c00ab3c8c667da525dc83ceb6238a0908"
+      "sha256": "6e7ad3fddfaca1cfb1dfe79cbdb4a5588007b30eedd458df7212a971da96e324"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2997,7 +2997,7 @@
     {
       "path": "docs/recipes/core-release-pipeline.md",
       "mode": "0000644",
-      "sha256": "23ebe6ce28667a82c457badf8db3116c5dc86e19fd799603bbfe8b22be4fc560"
+      "sha256": "00d1879609d950f379acdf411e8c91acc6da0b08838c49a338257433af24ceb8"
     },
     {
       "path": "docs/recipes/failed-ship-recovery-proof.md",
@@ -7109,6 +7109,11 @@
       "mode": "0000644",
       "sha256": "16667b27f462627277da092dd0cf8905cf7144f1a959fdaf3174a9fb41a91da4"
     },
+    {
+      "path": "modules/lifecycle/merge-reach.js",
+      "mode": "0000644",
+      "sha256": "f800bcd7e9f78cd680a06fa3242e70deed97c3399a435e783bec7288a5708cb8"
+    },
     {
       "path": "modules/lifecycle/migrations/lifecycle_001_goal_first_leads.sql",
       "mode": "0000644",
@@ -7427,7 +7432,7 @@
     {
       "path": "modules/lifecycle/ship-card.js",
       "mode": "0000644",
-      "sha256": "fc803defc468a0e625d82f305d00118ec77bb63d74d7b75b4d3ba03bdd16659d"
+      "sha256": "db49d616bad9ae851bb86f3729252290827db46cd6a6f3c1f86c60c9b9d2691a"
     },
     {
       "path": "modules/lifecycle/ship-files.js",
@@ -10132,12 +10137,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4abc8512ca8578d3a43a7d915574dc473061e2e77cd20e3902c5478af77a671f"
+      "sha256": "7f4d097ca5d827a3fad698b3e3fbbedc38f7469e29b565cfed34489f4eaab008"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7b6b52ae08358107e824752af2427b6efaa33d7ea5bcf9a0b464584eef6708a5"
+      "sha256": "a0fb2f62847ad58e78ec122f44bb7e97281f124bdfd0324c767a50bfe26b5a9e"
     },
     {
       "path": "public-docs/index.html",
@@ -10157,7 +10162,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "947800c2b145b25a07f38bdfc1274ba9316de0b1bccc35e43de3ea2ddc44f7a3"
+      "sha256": "f65d5a86053502037145a87a3e996ce4ff32c84651d4a8f8afe62c486172ef2d"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10562,7 +10567,7 @@
     {
       "path": "scripts/gds/deploy-divergence.js",
       "mode": "0000644",
-      "sha256": "bffaceec8b47b238f4a7911aee10a651b45cd75e0c5a67b2b8e3daa90e3cd54a"
+      "sha256": "0fd4f72d74f1f39ebbd6267f485a24705a0c20706a2475507c895e726b6f2287"
     },
     {
       "path": "scripts/gds/deploy-main-audit-gate.sh",
@@ -11212,7 +11217,7 @@
     {
       "path": "scripts/gds/provision-repo.js",
       "mode": "0000644",
-      "sha256": "8e2cf2e362b5e38832b53720a84ee0fb9003f9062cf9b7d03353a62fde936566"
+      "sha256": "a52e17d4341c7498d9fc204bfaa7447305a19924e8e05f0fde10583eb1f0a6da"
     },
     {
       "path": "scripts/gds/provision-teardown.js",
@@ -11632,12 +11637,12 @@
     {
       "path": "scripts/gds/ship-finish.js",
       "mode": "0000644",
-      "sha256": "23856ecf2ed0224fcc69fa4e67413d2248462813896e3b832a20f3a2d0a886e6"
+      "sha256": "03bd3bacc00dfb644f25e22bf90a2864700cb570dcdf051e6c9fb9ca3edfb11a"
     },
     {
       "path": "scripts/gds/ship-flow.js",
       "mode": "0000644",
-      "sha256": "d114ae690d86270db76770fc3531a5530d1ab64a031a2528368864f4b330ac56"
+      "sha256": "ad768320095b1d6693e6da5cee1f8e857ac69cbbfbea0a64dfeaa7092c432de2"
     },
     {
       "path": "scripts/gds/ship-git.js",
@@ -11717,7 +11722,7 @@
     {
       "path": "scripts/gds/ship-visual.js",
       "mode": "0000644",
-      "sha256": "21ce15f1e49388bb3f8a46b9cfd8b05b23b77efbe93228ca04d9b13740e6d901"
+      "sha256": "a97c5628609b622ad8972e93af13ff32a85138c350756f4895bea24d469bc2fc"
     },
     {
       "path": "scripts/gds/ship.js",
@@ -12432,7 +12437,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "090a1a041a5e03ddfd2bb4c93ff9e28407a1cb662da2492e3741450900282f44"
+      "sha256": "a00e2f13c266f639d3052f84844f2f38634759e57cfd81830667a9bf1e3e7be7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13437,7 +13442,7 @@
     {
       "path": "tests/core_upgrade_runner.mjs",
       "mode": "0000644",
-      "sha256": "1c6e820ed45b489749f68f0cc00615fe2c4d6a4b08312316897cd1777c82b4dc"
+      "sha256": "33507dcd145bca157be08b9c8b55ad7d2c3ebae07ab8c94af7af9e235ac60769"
     },
     {
       "path": "tests/cosmos_token_contrast.mjs",
@@ -13647,7 +13652,7 @@
     {
       "path": "tests/deploy_divergence_line.mjs",
       "mode": "0000644",
-      "sha256": "3b2f0623db91ffecb0f7a52380b2f50a5e6e87d82d3e3d1a9e40944037d28629"
+      "sha256": "0eb792d18f705ba4990936822195d931802bad7f49b951633173446d5b7f2cba"
     },
     {
       "path": "tests/deploy_instance.mjs",
@@ -16517,7 +16522,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "64ffc593089622c6901669a29eee6a0d75ae6b47cbfc0729e2c8eae09e8386e1"
+      "sha256": "71ea3289a3007e08249cfb309272208c6ec740d7345d8fbf9638e81b6ece5010"
     },
     {
       "path": "tests/provision_account_identity.mjs",
@@ -17337,7 +17342,7 @@
     {
       "path": "tests/ship_card.mjs",
       "mode": "0000644",
-      "sha256": "d7214e2916f124462543eb05f68163c21a6d34c2d6fec24691ce3f865510c298"
+      "sha256": "e79fdf44d85523853ebbcefe8fcdae1806f258e9c546d8f086a46a806016f085"
     },
     {
       "path": "tests/ship_card_injection.mjs",
@@ -17439,6 +17444,11 @@
       "mode": "0000644",
       "sha256": "75aa59accad12d197202457ed36281e5d3eca1040762a5045972c4b10cf09006"
     },
+    {
+      "path": "tests/ship_visual_regrade.mjs",
+      "mode": "0000644",
+      "sha256": "4e469f6f5801032dff196a57a84eeb3603e7a53760144a7ed4d582699c9747f9"
+    },
     {
       "path": "tests/ship_zero_commit.mjs",
       "mode": "0000644",

package/.claude/skills/planning-session/SKILL.md

@@ -151,7 +151,7 @@ For the version being planned, **group the agreed criteria into goals**. For eac
 - **`scope_modules`** — the module **keys** (NOT file paths) whose files this goal's members may touch. **This is the wall, and it is set here and only here — never self-granted.** Keep it tight: the modules the goal's work actually needs. Widening later goes through an explicit request a trusted rank approves (`POST /goals/:id/scope`; Archon for a `protected` module) — BV1.R64.
   > **The valid key list is the source of truth in [`src/bongos/module-scope-map.js`](../../../src/bongos/module-scope-map.js) — read it, don't trust this list.** It exports `moduleKeys()` (all keys), `protectedModules()` / `isProtectedModule(key)` (which are PROTECTED), and `scopeForModule(key)` (a key's globs + `protected` flag). Each key maps to path-globs; `protected` is **derived** (the key's globs overlap the trust/ship-pipeline/migration/authz core), and a goal scoped to any protected key is **Archon-only** to create. The current roster (run `node -e "const m=require('./src/bongos/module-scope-map');console.log(m.moduleKeys().map(k=>k+(m.isProtectedModule(k)?' 🔒':'')).join('\n'))"` to print it live):
   >   - **No roster is written down here on purpose.** The previous snapshot went stale within a release (it still omitted a key that had been added), which is exactly the failure a "read it live" rule prevents. Run the one-liner above; `protected` is derived from glob overlap, so it changes when the globs change.
-  >   - **That file is the SOURCE. The RUNNING SERVER is the GATE.** `POST /goals` validates `scope_modules` against the roster the LIVE server loaded — not the one in your checkout — so a key added since the last deploy is valid here and refused on the wire. Merging to main deploys nothing (gate 3 of [the release pipeline](../../../docs/recipes/core-release-pipeline.md)), and this is not a rare race: the module roster grows precisely during the versions when planning sessions run. On 2026-08-16 goal 1000069 was created with `government` in scope and came back `unknown: ["government"]` — the key was on main; the site was a release behind. **The SessionStart deploy-state line already tells you whether you are exposed.** If it says the site is behind main, treat any recently-added key as suspect before you compose the goal, not after.
+  >   - **That file is the SOURCE. The RUNNING SERVER is the GATE.** `POST /goals` validates `scope_modules` against the roster the LIVE server loaded — not the one in your checkout — so a key added since the last deploy is valid here and refused on the wire. The site picks up a merge only on its next redeploy ([who sees a merge](../../../docs/recipes/core-release-pipeline.md#who-sees-a-merge-and-when)), and this is not a rare race: the module roster grows precisely during the versions when planning sessions run. On 2026-08-16 goal 1000069 was created with `government` in scope and came back `unknown: ["government"]` — the key was on main; the site was a release behind. **The SessionStart deploy-state line already tells you whether you are exposed.** If it says the site is behind main, treat any recently-added key as suspect before you compose the goal, not after.
   >   - **The refusal is not a dead end — it hands you the answer.** `unknown_module` comes back with `valid: [...]`: the LIVE roster, from the server that just refused you. One rejected call tells you exactly what will be accepted, so read it and re-point rather than trying keys one at a time. (`tests/goal_unknown_module_hint.mjs` pins that the refusal keeps carrying it, because this instruction is only true while it does.)
   >   - **Prefer a deployed alias where one exists, and write the re-point down.** Goal 1000069 was walled to the deprecated `governance` alias, which ADR 0174 deliberately kept carrying BOTH sets of globs through the transition — so the wall was identical, not weaker — and the goal description recorded that `scope_modules` should be re-pointed once the newer release went live. A goal walled to an alias with no note is a goal nobody re-points.
 - **No covering key? → file a module-map prep task FIRST.** Every `scope_modules` entry must be a real key from `moduleKeys()`. If a goal's planned work touches file paths that **no existing key covers** (e.g. a brand-new module dir, or code still fused under `src/bongos/` that isn't yet broken out as its own key), the scope wall cannot place that work. Do **not** invent a key. Instead, **add a prep task to this version** — `kind='refactor'`, scoped to `kernel` (the module that owns `module-scope-map.js`) — to extend `MODULE_GLOBS` so a key covers those paths, and make the dependent goal's tasks depend on it. Adding/editing a key is itself a `kernel`-scoped (Archon-gated) change, so flag it for Archon sign-off in this session.

package/docs/module-api-changelog.md

@@ -3041,5 +3041,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.100 with no explicit bump. run 37933684016. (task 1002620)
   1.21.102 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.101 with no explicit bump. run 37935415352. (task 1002620)
+  1.21.103 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.102 with no explicit bump. run 37936846665. (task 1002620)
+  1.21.104 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.103 with no explicit bump. run 37939497390. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/core-release-pipeline.md

@@ -1,10 +1,17 @@
 # Recipe — the core release pipeline: how a change to Cloud Bongos reaches a live instance
 
-> **The map.** Three sibling recipes each cover one leg — [packaging-the-core](packaging-the-core.md) (build the artifact), [private-npm-distribution](private-npm-distribution.md) (publish it), [upgrading-the-core](upgrading-the-core.md) (consume it). This file is the thing that connects them, and it exists to state one fact loudly:
->
-> ## **Merging to `main` ships nothing.**
+## Who sees a merge, and when
+
+| Who | Gets a merged change | How to check |
+|---|---|---|
+| **cloudbongos.com** — the projects hub and the builders hall | on **every merge**, within minutes: it redeploys from `main` | its `/version`; the ship card's **Deploy** row reads it: *"live at `<sha>` (includes this merge \| not yet)"* |
+| **Projects hosted on the platform** | only when a **published core release** carries it (auto-published per merge, [ADR 0161](../adr/0161-publish-on-merge.md)) **and that project's pin moves** — a patch-channel subscription or a core-upgrade | that project's `/version` `coreVersion`; the ship card's **Projects** row states the rule |
+
+So a shipped task is live on the hub minutes after its merge, and on a hosted project only once that project's pin has moved — say which one you mean. The wording has one source, [`modules/lifecycle/merge-reach.js`](../../modules/lifecycle/merge-reach.js); the ship card, `deploy-divergence.js` and the SessionStart line all print it (task 1004682). `/recall who sees a merge` finds the same rule as learning 1000291.
+
+> **The map.** Three sibling recipes each cover one leg — [packaging-the-core](packaging-the-core.md) (build the artifact), [private-npm-distribution](private-npm-distribution.md) (publish it), [upgrading-the-core](upgrading-the-core.md) (consume it). This file is the thing that connects them.
 >
-> A change that has landed on `main` is running on **zero** instances. It reaches users only after someone bumps `CORE_VERSION`, cuts an artifact, and moves an instance's pin. Those are three separate acts by design ([ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md)) — and every layer around them reports success in the meantime.
+> **History, not the current rule.** Under [ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md) (manual, owner-gated publish) a merge reached no instance at all, and this file opened with "Merging to `main` ships nothing." [ADR 0161](../adr/0161-publish-on-merge.md) superseded that. Sessions that kept repeating the old line told the owner that live work was not live. The gates below still exist; for patches they now run unattended.
 
 > ## Working on a hosted project? Stop here — nothing in this file is yours to run.
 >
@@ -70,7 +77,7 @@ The ordinary claim→ship loop: `/builder-claim N` → build → `/builder-ship`
 
 Landing is CI-gated (tasks 1002610/1002611/1002619, ADR 0159): every PR runs the **`unit`** check — the DB-free suite plus the fitness gates, via `npm test` — and branch protection **requires** it, so a red suite blocks the merge. PRs touching the hard-floor safety surfaces (`CODEOWNERS` (instance-side)) additionally need the owner's review. The owner kill-switch is `node scripts/gds/gating.js on|off|status` — reversible by construction, snapshot-restored.
 
-**Stop here and nothing happens to any user.** This is the gate that feels like the finish line and is not.
+**Stop here and the hub has it within minutes; no hosted project does.** This is the gate that feels like the finish line for every project, and is one only for the hub (see [Who sees a merge](#who-sees-a-merge-and-when)).
 
 ## Gate 2 — cut a release
 
@@ -334,8 +341,8 @@ node scripts/gds/deploy-divergence.js --url https://<instance-host>
 
 It reports the two gaps **separately**, because they have different fixes:
 
-- **UNRELEASED** — commits on `main` past the last `CORE_VERSION` bump. *No instance can take these at any pin* — no version contains them. Fix: bump + land (gate 2a).
-- **UNDEPLOYED** — the live instance's `coreVersion` is behind `main`'s. A release exists; this instance has not moved its pin. Fix: gate 3.
+- **UNRELEASED** — commits on `main` past the last `CORE_VERSION` bump. *No hosted project can take these at any pin* — no published version contains them yet. The publish lane (ADR 0161) normally carries a merge within minutes; a gap that stays means the lane is disarmed or red.
+- **UNDEPLOYED** — the live instance's `coreVersion` is behind `main`'s. A release exists it has not picked up: on the hub, its redeploy is late or stuck; on a hosted project, its pin has not moved (gate 3).
 
 Exit codes: `0` aligned, `1` diverged, `2` undetermined.
 

package/modules/lifecycle/merge-reach.js

@@ -0,0 +1,56 @@
+// modules/lifecycle/merge-reach.js — who sees a merge, and when. The ONE source of
+// the sentence (task 1004682).
+//
+// Two audiences, two rules:
+//   1. The hub this checkout ships to (cloudbongos.com: the projects hub and the
+//      builders hall) redeploys from main on every merge, within minutes.
+//   2. Projects hosted on the platform get a change only when a published core
+//      release carries it (auto-published per merge, ADR 0161) AND their pin moves
+//      (a patch-channel subscription or a core-upgrade).
+//
+// Before this, deploy-divergence.js printed "Merging to main deploys nothing" on
+// every ship — true under ADR 0137, false since ADR 0161 — and sessions repeated
+// it to the owner about work that was in fact live. The ship card, the divergence
+// report and the SessionStart line all read their wording from here, so the three
+// cannot drift apart again.
+//
+// PURE and dependency-free: callers pass an already-sanitised reading (host, short
+// sha, inclusion), never a raw network response — some of this text is injected
+// into an agent's SessionStart context.
+
+'use strict';
+
+const HOSTED_LINE = 'Hosted projects: only when a published core release carries the change and their pin moves (patch-channel subscription or a core-upgrade).';
+
+function hubRule(host) {
+  return `${host || 'The hub'} redeploys from main on every merge, within minutes`;
+}
+
+// includes: true (the live build carries this merge), false (not yet), null (cannot tell).
+function hubLine({ host = null, liveShort = null, includes = null } = {}) {
+  if (!liveShort) return `${hubRule(host)}.`;
+  const state = includes === true ? 'includes this merge'
+    : includes === false ? 'not yet'
+      : 'cannot tell yet whether it includes this merge';
+  return `${host || 'The hub'}: live at ${liveShort} (${state}) — it redeploys from main on every merge, within minutes.`;
+}
+
+// Re-bound a reading that may have travelled (a land-watch breadcrumb file) before
+// it is printed: host-shaped, hex, boolean — anything else is dropped. A reading with
+// no usable host is null, so the caller keeps its own fallback.
+function boundReading(r) {
+  const host = r && typeof r.host === 'string' && /^[A-Za-z0-9.:_-]{1,120}$/.test(r.host) ? r.host : null;
+  if (!host) return null;
+  return {
+    host,
+    liveShort: typeof r.liveShort === 'string' && /^[0-9a-f]{4,40}$/i.test(r.liveShort) ? r.liveShort : null,
+    includes: typeof r.includes === 'boolean' ? r.includes : null,
+  };
+}
+
+// The two-line wording, in order: [hub, hosted projects].
+function whoSeesAMerge(reading) {
+  return [hubLine(reading || {}), HOSTED_LINE];
+}
+
+module.exports = { HOSTED_LINE, hubRule, whoSeesAMerge, boundReading };

package/modules/lifecycle/ship-card.js

@@ -23,6 +23,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { branding } = require('../../src/module-api');
+const { whoSeesAMerge, boundReading } = require('./merge-reach.js');
 
 // tone -> the widget's banner color family. 'neutral' has no semantic CSS var, so
 // every tone resolves through this map (never `--color-background-${tone}`).
@@ -445,9 +446,20 @@ function buildCardModel(input = {}) {
     // Deploy
     let deployText;
     let deployCommit = null;
+    let hostedText = null;
     if (stage === 'shipped') {
       deployCommit = input.deploy && input.deploy.commit ? String(input.deploy.commit) : null;
-      deployText = deployCommit ? `live · ${deployCommit}` : 'live';
+      const reach = boundReading(input.deploy && input.deploy.reach);
+      if (reach) {
+        // task 1004682: who sees this merge, in the one shared wording
+        // (merge-reach.js) — the hub's live build as read, then the hosted rule.
+        // A bare "live · <sha>" read as "every user has it", which is only true
+        // of the hub. The reading can come back from a breadcrumb file, so
+        // boundReading re-bounds it (host-shaped, hex, boolean) before printing.
+        [deployText, hostedText] = whoSeesAMerge(reach);
+      } else {
+        deployText = deployCommit ? `live · ${deployCommit}` : 'live';
+      }
     } else if (stage === 'confirmed') {
       // task 1002541: this line used to be unconditional, driven by the STATUS
       // alone — so a merge that bailed still reported "landing automatically".
@@ -471,6 +483,7 @@ function buildCardModel(input = {}) {
 
     addRow('Value', value); addRow('Changed', changed); addRow('Grade', gradeText);
     addRow('Credits', creditsText); addRow('Usage', usageText); addRow('Deploy', deployText);
+    addRow('Projects', hostedText);
     // task 1003150: the session-boundary nudge. Not a row — it qualifies the
     // Next-> action rather than reporting a fact about the task, so both renderers
     // hang it off the action. Usually null.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.102",
+  "version": "1.21.104",
   "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/release-notes.json

@@ -9450,5 +9450,25 @@
       "id": "1004588",
       "text": "The guilds test now sets up everything it needs on a brand-new database, so it runs all the way through instead of stopping early. It also checks, without needing a database, that its setup keeps up with the tables the guild c"
     }
+  ],
+  "1.21.103": [
+    {
+      "id": "1004663",
+      "text": "Two test suites that always failed on Windows machines now pass there, so a builder on Windows can trust a red result again. Two checks that had been passing without really checking anything now check properly."
+    },
+    {
+      "id": "1004682",
+      "text": "Ship reports now say plainly who sees a merge. The old line \"Merging to main deploys nothing\" is gone: it stopped being true when every merge began publishing automatically. A shipped card now reads the live site and says, for"
+    },
+    {
+      "id": "1004684",
+      "text": "New house rule, Slop Bongo: when an AI realises it was wrong about something, it now says 'Bongo Slop Detected, Filing Bug' in chat and files a bug against the doc or message that misled it, so the same mistake stops repeating"
+    }
+  ],
+  "1.21.104": [
+    {
+      "id": "1004665",
+      "text": "When a builder re-runs a review and attaches a screenshot, the screenshot now actually gets attached to the task. Before, it was quietly thrown away, so reviewers asking for a picture never saw one unless someone added it by h"
+    }
   ]
 }

package/scripts/gds/deploy-divergence.js

@@ -1,20 +1,29 @@
 #!/usr/bin/env node
 // Compare what a live instance is SERVING against what is on main.
 //
-// Merging to main deploys nothing (ADR 0108/0137 — publishing is manual and
-// owner-gated). That is by design, but every layer around it still reports
-// success: /builder-ship prints success, the publish-reconciler flips
-// confirmed → shipped, and credits pay out on "land". Nothing compared live
-// against main, so between 2026-07-24 and 2026-08-03 a hundred and seventy-one
-// commits — including a whole governance permission system — sat on main while
-// cloudbongos.com served 1.18.17, and nobody noticed for ten days (blocker
-// 1000097 / task 1002521). This script is the missing comparison.
+// WHO SEES A MERGE (task 1004682; the wording lives in modules/lifecycle/merge-reach.js):
+//   - The hub this checkout ships to (cloudbongos.com: the projects hub and the
+//     builders hall) redeploys from main on every merge, within minutes.
+//   - Projects hosted on the platform get a change only when a published core
+//     release carries it (auto-published per merge, ADR 0161) and their pin moves
+//     (patch-channel subscription or a core-upgrade).
+// This script used to print "Merging to main deploys nothing" — the ADR 0137 rule
+// (manual, owner-gated publish), false since ADR 0161 — and sessions repeated it
+// to the owner about work that was live. It now READS the hub's /version and says
+// whether the live build includes main's tip, instead of a blanket claim.
+//
+// Why it exists at all: between 2026-07-24 and 2026-08-03 a hundred and
+// seventy-one commits — including a whole governance permission system — sat on
+// main while cloudbongos.com served 1.18.17, every layer reported success, and
+// nobody noticed for ten days (blocker 1000097 / task 1002521). This script is
+// the comparison that was missing.
 //
 // Three independent gaps, all reported:
-//   1. UNRELEASED — commits on main since the last CORE_VERSION bump. No
-//      instance can take these at any pin, because no version carries them.
+//   1. UNRELEASED — commits on main since the last CORE_VERSION bump. No hosted
+//      project can take these at any pin, because no published version carries them.
 //   2. UNDEPLOYED — the live instance's coreVersion is behind the CORE_VERSION
-//      on main. A release exists; this instance has not moved its pin to it.
+//      on main. A release exists that it has not picked up: on the hub, its
+//      redeploy is late or stuck; on a hosted project, its pin has not moved.
 //   3. SCHEMA BEHIND — live's /version reports schemaPending > 0: its database
 //      lacks migrations its running code ships (the 2026-07-04 502 outage
 //      shape; task 1002002). An instance too old to report it is not flagged.
@@ -35,6 +44,7 @@ const path = require('node:path');
 const { execSync } = require('node:child_process');
 
 const { API_BASE, arg, hasFlag } = require('./cli-lib');
+const { whoSeesAMerge, hubRule, HOSTED_LINE } = require('../../modules/lifecycle/merge-reach.js');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const MODULE_API = path.join(REPO_ROOT, 'src', 'module-api.js');
@@ -99,6 +109,51 @@ function unreleasedSince(mainRef) {
   };
 }
 
+// Does the live build include commit `sha`? true / false, or null when this
+// checkout cannot tell (task 1004682). Two ways to know, tried in order:
+//   1. The /version commit is one this repo has (a box that runs this checkout
+//      directly) — plain ancestry.
+//   2. Otherwise the commit is the hub's OWN repo (it consumes the core as a
+//      published package — measured 2026-10-09: cloudbongos.com reports a commit
+//      core main does not contain, at the coreVersion main declares). Then: find the
+//      first CORE_VERSION bump on main at or after `sha` — the release that carries
+//      it — and compare the live coreVersion against it. No bump yet ⇒ not yet.
+// Both inputs reach git, so both are hex-or-nothing and the ref is a fixed name.
+function liveIncludes(live, sha, mainRef = resolveMainRef()) {
+  const want = typeof sha === 'string' && /^[0-9a-f]{7,40}$/i.test(sha) ? sha.toLowerCase() : null;
+  if (!live || !want || !/^(origin\/main|HEAD)$/.test(mainRef)) return null;
+  const liveCommit = typeof live.commit === 'string' && /^[0-9a-f]{40}$/i.test(live.commit) ? live.commit : null;
+  if (liveCommit && git(`cat-file -e ${liveCommit}`) !== null) {
+    return git(`merge-base --is-ancestor ${want} ${liveCommit}`) !== null;
+  }
+  if (!isPlausibleVersion(live.coreVersion)) return null;
+  if (git(`merge-base --is-ancestor ${want} ${mainRef}`) === null) return null; // not on main here yet
+  // `sha` itself may be the bump (a hand-cut release); otherwise the first bump after it.
+  const selfBump = git(`log -1 --format=%H -G"^const CORE_VERSION = " ${want} -- src/module-api.js`, '');
+  const after = git(`log --ancestry-path --reverse --format=%H -G"^const CORE_VERSION = " ${want}..${mainRef} -- src/module-api.js`, '');
+  const carrier = selfBump && selfBump.startsWith(want) ? selfBump : (after ? after.split('\n')[0].trim() : null);
+  if (!carrier) return false; // on main, but no release carries it yet
+  const carried = coreVersionAt(carrier);
+  return carried ? cmpSemver(live.coreVersion, carried) >= 0 : null;
+}
+
+// The sanitised reading the merge-reach sentence is built from. `live` may be a
+// raw /version body (ship-finish passes one), so it goes through the same filters
+// fetchLive applies before anything is interpolated.
+// Prefer origin/main — the released trunk — but fall back to HEAD in a checkout with
+// no remote (a box, a tarball). Shared by check() and hubReading() so both agree.
+function resolveMainRef() {
+  return git('rev-parse --verify --quiet origin/main') ? 'origin/main' : 'HEAD';
+}
+
+function hubReading({ target, live, sha, mainRef = resolveMainRef() } = {}) {
+  return {
+    host: safeHost(target || API_BASE),
+    liveShort: live ? safeCommitShort(live.commitShort) || safeCommitShort(typeof live.commit === 'string' ? live.commit.slice(0, 8) : null) : null,
+    includes: live ? liveIncludes(live, sha, mainRef) : null,
+  };
+}
+
 function cmpSemver(a, b) {
   const pa = String(a).split('.').map(Number);
   const pb = String(b).split('.').map(Number);
@@ -162,6 +217,8 @@ async function fetchLive(base, timeoutMs = DEFAULT_TIMEOUT_MS) {
       url,
       coreVersion: String(body.coreVersion),
       commitShort: safeCommitShort(body.commitShort),
+      // Full sha, hex-or-nothing: only ever handed to git (liveIncludes), never printed.
+      commit: typeof body.commit === 'string' && /^[0-9a-f]{40}$/i.test(body.commit) ? body.commit : null,
       schemaPending: safeCount(body.schemaPending),
     };
   } catch (e) {
@@ -193,7 +250,9 @@ function subscriptionHealth(dir = REPO_ROOT) {
   }
 }
 
-async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+// withReach: compute the who-sees-a-merge reading (a few git calls). The SessionStart
+// --line never prints it, so it passes false and pays nothing for it.
+async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS, withReach = true } = {}) {
   const target = base || arg('--url') || API_BASE;
   const local = coreVersionAt(null);
   if (!local) return { ok: false, undetermined: true, reason: 'could not read CORE_VERSION from src/module-api.js', target };
@@ -201,7 +260,7 @@ async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   // Prefer origin/main — the released trunk — but fall back to HEAD in a
   // checkout with no remote (a box, a tarball) so the check still says
   // something useful instead of bailing.
-  const mainRef = git('rev-parse --verify --quiet origin/main') ? 'origin/main' : 'HEAD';
+  const mainRef = resolveMainRef();
   const onMain = coreVersionAt(mainRef) || local;
   const unreleased = unreleasedSince(mainRef);
   const live = await fetchLive(target, timeoutMs);
@@ -214,10 +273,12 @@ async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   const ahead = cmpSemver(live.coreVersion, onMain) > 0;
   const hasUnreleased = !!(unreleased && unreleased.count > 0);
   const schemaBehind = live.schemaPending > 0;
+  // "this merge", read from here, is main's tip: ship-finish runs this right after a land.
+  const reach = withReach ? hubReading({ target, live, sha: git(`rev-parse ${mainRef}`), mainRef }) : null;
 
   return {
     ok: !behind && !hasUnreleased && !schemaBehind,
-    target, local, onMain, mainRef, unreleased, live, behind, ahead, hasUnreleased, schemaBehind, subscriptions,
+    target, local, onMain, mainRef, unreleased, live, behind, ahead, hasUnreleased, schemaBehind, subscriptions, reach,
   };
 }
 
@@ -243,9 +304,16 @@ function report(r, { quiet = false } = {}) {
   }
   say('');
 
+  // Who sees a merge — the same two lines the ship card prints (merge-reach.js).
+  const reachBlock = () => {
+    say('');
+    for (const l of whoSeesAMerge(r.reach || { host: safeHost(r.target) })) say(`  ${l}`);
+    say('');
+  };
+
   if (r.ok) {
     say('  ✓ aligned — live matches main, and main carries no unreleased commits.');
-    say('');
+    reachBlock();
     return;
   }
 
@@ -257,13 +325,13 @@ function report(r, { quiet = false } = {}) {
     const merges = u.countWithMerges != null && u.countWithMerges !== u.count
       ? ` (${u.countWithMerges} counting merges)` : '';
     say(`  ⚠ UNRELEASED — ${u.count} work commit${u.count === 1 ? '' : 's'}${merges} on ${r.mainRef} since the last CORE_VERSION bump.`);
-    say('    No instance can take these at ANY pin: no published version contains them.');
-    say(`    Fix: bump CORE_VERSION in src/module-api.js (+ an entry in docs/module-api-changelog.md) and land it.`);
+    say('    No hosted project can take these at ANY pin: no published version contains them yet.');
+    say('    The publish lane (ADR 0161) normally carries a merge within minutes; a gap that stays means it is disarmed or red.');
   }
   if (r.behind) {
     say(`  ⚠ UNDEPLOYED — live is ${r.live.coreVersion}, main declares ${r.onMain}.`);
-    say('    A release exists that this instance has not moved its pin to.');
-    say('    Fix: package-core, then move the instance pin (see docs/recipes/upgrading-the-core.md).');
+    say('    A release exists that this instance has not picked up. On the hub, its redeploy is late or stuck;');
+    say('    on a hosted project, its pin has not moved (see docs/recipes/upgrading-the-core.md).');
   }
   if (r.schemaBehind) {
     const n = r.live.schemaPending;
@@ -281,10 +349,7 @@ function report(r, { quiet = false } = {}) {
     say(`  ${r.subscriptions.level === 'alarm' ? '⚠ AUTO-UPGRADE' : 'note: auto-upgrade'} — ${r.subscriptions.message}`);
     if (r.behind) say('    So the gap above will NOT close by itself.');
   }
-  say('');
-  say('  Merging to main deploys nothing by design. "shipped" means "merged" —');
-  say('  it does not mean users can see it.');
-  say('');
+  reachBlock();
 }
 
 // ONE line, for injecting into an agent's SessionStart context (task 1002713).
@@ -324,7 +389,8 @@ function line(r) {
   if (!parts.length) return null;
 
   const advice = [];
-  if (versionParts) advice.push('Merging to main deploys nothing — do not claim work is visible to users until the pin moves.');
+  // Fixed vocabulary + the bounded host only (this line is injected context).
+  if (versionParts) advice.push(`${hubRule(host)}; ${HOSTED_LINE.charAt(0).toLowerCase()}${HOSTED_LINE.slice(1)} Say which one you mean before calling work live.`);
   if (pending) advice.push('Run migrate against that instance DB (PGDATABASE set) before anything else.');
   return `Deploy state (read from ${host}/version): ${parts.join('; ')}. ${advice.join(' ')}`;
 }
@@ -350,7 +416,7 @@ async function main() {
       // seconds apart asked this same question four times and all four timed out, which
       // emits NO line — and silence from a truth-teller reads as "nothing to report".
       const { cached } = require('./probe-cache.js');
-      const { value: one } = await cached('deploy-divergence-line', async () => line(await check({ timeoutMs: ms })));
+      const { value: one } = await cached('deploy-divergence-line', async () => line(await check({ timeoutMs: ms, withReach: false })));
       if (one) console.log(one);
     } catch { /* offline, no git, unreadable module-api — all silence */ }
     process.exitCode = 0;
@@ -377,4 +443,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { check, report, line, coreVersionAt, unreleasedSince, cmpSemver, subscriptionHealth };
+module.exports = { check, report, line, coreVersionAt, unreleasedSince, cmpSemver, subscriptionHealth, liveIncludes, hubReading };

package/scripts/gds/provision-repo.js

@@ -147,9 +147,14 @@ function standaloneRoot(inst, { base = CONFIG.standaloneBase } = {}) { return pa
 // This is a string question, not a filesystem one: the vendored layout is the only
 // way a core ends up under `node_modules/`, so the suffix IS the answer. Keeping it
 // pure means the control-plane path is testable without a box.
+// Either separator counts as a segment boundary (task 1004663): a suffix built from
+// path.sep alone never matched a POSIX-shaped path on Windows, so the suite went red
+// there while the Linux box (the only place this runs for real) stayed green.
 function selfInstanceRoot(repoRoot = REPO_ROOT) {
-  const suffix = path.sep + CORE_PKG_DIR.split('/').join(path.sep);
-  return repoRoot.endsWith(suffix) ? repoRoot.slice(0, -suffix.length) : repoRoot;
+  const segs = CORE_PKG_DIR.split('/');
+  const tail = repoRoot.split(/[\\/]/).slice(-(segs.length + 1));
+  const isVendored = tail.length === segs.length + 1 && segs.every((s, i) => tail[i + 1] === s);
+  return isVendored ? repoRoot.slice(0, -(segs.join('/').length + 1)) : repoRoot;
 }
 // Sync the instance's own repo (host content + the core pin). Mirrors deploy-instance.sh
 // step 1 — assumes the repo is already cloned at standaloneRoot (initial clone is a

package/scripts/gds/ship-finish.js

@@ -16,7 +16,7 @@ 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 } = require('./ship-deploy-target.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');
@@ -282,9 +282,17 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage, land
 
     // 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
@@ -342,7 +350,7 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage, land
       grade: card.grade || null,
       credits: { awarded: card.creditsAwarded, total, perTaskCredit: rewardPolicy(getServerReward()).perTaskCredit },
       usage: { tokens, costUsd, newTokens, cachedTokens },
-      deploy: { commit },
+      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.
@@ -376,12 +384,13 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage, land
     /* a summary card must never fail a ship */
   }
 
-  // task 1002521: the card above says SHIPPED, which means "merged" — it does
-  // NOT mean users can see it. Publishing is manual and owner-gated, so a ship
-  // can land on main and change nothing live, and until now nothing said so.
-  // Blocker 1000097: 171 commits (a whole governance system) 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.
+  // task 1002521: the card above says SHIPPED, which means "merged". Its Deploy
+  // row says who sees that (task 1004682: the hub redeploys on every merge;
+  // hosted projects when a release carries it and their 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();

package/scripts/gds/ship-flow.js

@@ -139,7 +139,7 @@ async function shipMain() {
     const action = evaluateResumeAction({ task, lastClaim, builder: me.data.builder });
     if (action.action === 'resume-grade') {
       console.log(`Task #${taskId} is at 'completed' (grade stalled) and ${action.via === 'owner' ? 'you last held the claim' : 'you are an Archon'} — resuming the grade (no re-claim needed).`);
-      return regradeMain();
+      return regradeMain({ visual });
     }
     if (action.action === 'resume-merge') {
       console.log(`Task #${taskId} is at 'confirmed' (merge/deploy stalled) and ${action.via === 'owner' ? 'you last held the claim' : 'you are an Archon'} — resuming the merge + deploy (no re-claim needed).`);
@@ -822,12 +822,12 @@ async function persistRegradeSummary({ taskId, summaryArg, task }) {
 //     promotes completed→confirmed + awards credits on pass, idempotent)
 //   - on pass: the normal confirmed→shipped merge + sync tail runs.
 
-async function regradeMain() {
+async function regradeMain(opts = {}) {
   await requireSession();
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary-file <path|-> | --summary "..."] [--response-file <path|-> | --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 "..."] [--visual <image>] [--visual-alt "caption"] [--no-merge] [--force] [--verified] [--base <ref>]');
     process.exit(2);
   }
   // task 1003702: refuse --notes rather than swallowing it. The reasoning — why
@@ -840,6 +840,16 @@ async function regradeMain() {
     for (const line of regradeNotesRefusal(taskId)) console.error(line);
     process.exit(2);
   }
+  // task 1004665: --visual used to be screened by shipMain and then dropped here
+  // without a word — this path returned before shipMain's upload, so visual_url
+  // stayed null (task 1004351). Screen it at the same early position as the
+  // --notes refusal (bad input costs no grade spend), and attach it on every
+  // path below that goes on to grade or land. shipMain's resume-grade dispatch
+  // hands over the visual it already screened rather than reading the file twice.
+  const visual = opts.visual !== undefined ? opts.visual : shipVisual.fromArgs(args, { regrade: true });
+  const attachVisual = async () => (visual
+    ? shipVisual.upload({ taskId, visual, client: await cliClient(), errorLine: apiErrorLine })
+    : false);
   const regradeProse = resolveProse(args, ['summary', 'response']);
   const summaryArg = regradeProse.summary;
   // task 1002662: the builder's response to the prior round's findings — how
@@ -908,6 +918,7 @@ async function regradeMain() {
   // only re-publishes the branch (the recovery for a publish that failed).
   if (tweakHold.isHeldForArtist(task, tRes.data.grade ? tRes.data.grade.passed : null)) {
     console.log(`Task #${taskId} already passed its grade and is waiting for the artist: re-publishing its branch, not re-grading.`);
+    await attachVisual();
     await finishShip({
       taskId, summary: summaryArg || task.value_summary || '', held: true, postGradeStatus: 'completed', doneLine: 'Done.',
       card: { title: task.title, valueSummary: summaryArg || task.value_summary || '', notes: '' },
@@ -989,6 +1000,7 @@ async function regradeMain() {
       console.log('');
       console.log(`Nothing to grade (the committed diff vs ${graderBaseline || 'baseline'} is empty) and this ship`);
       console.log('declares itself artifact-free — manual-confirming via POST /tasks/:id/confirm.');
+      await attachVisual();
       // A kind='verify' task cannot reach here without --verified: the gate above
       // exits first, so the server's verify_attestation_required can't fire below.
       const confirm = await (await cliClient()).tasks.postTasksIdConfirm({ id: taskId, body: { verified } });
@@ -1060,6 +1072,9 @@ async function regradeMain() {
   // the panel runs afterwards. The row, the grader prompt, the merge commit and
   // the PR then all carry the same sentence.
   await persistRegradeSummary({ taskId, summaryArg, task });
+  // task 1004665: the picture goes up at the same point and for the same reason
+  // as the summary — after every guard that can still refuse, before the panel.
+  await attachVisual();
 
   // ---- Delta-aware prior-round context (task 1002662) ----
   // The prior grade's findings + the builder's response + the interim fix diff

package/scripts/gds/ship-visual.js

@@ -28,17 +28,24 @@ const taskVisuals = require('../../modules/lifecycle/task-visuals');
 // EXITS (code 2) on bad input: this runs before any heavy work, so a wrong path
 // costs the builder a retyped command, not a claim. Pure enough to reason about;
 // the exit is the deliberate CLI edge.
-function fromArgs(args) {
+//
+// `regrade: true` is the `ship.js <id> --regrade` caller (task 1004665). There is
+// no claim left to resolve on that path, so the wording names what IS true there:
+// the task stays at completed, and the picture goes up before the grade runs.
+function fromArgs(args, { regrade = false } = {}) {
   const file = arg('--visual', args) || '';
   if (!file) return null;
   const read = taskVisuals.readImageFile(file);
   if (!read.ok) {
-    console.error(`Ship aborted: --visual ${file} — ${read.message}`);
-    console.error('Fix the path (or drop --visual: a visual is always optional). No claim resolved, no credits awarded.');
+    console.error(`${regrade ? 'Re-grade' : 'Ship'} aborted: --visual ${file} — ${read.message}`);
+    console.error(regrade
+      ? 'Fix the path (or drop --visual: a visual is always optional). Nothing was graded; the task stays at completed.'
+      : 'Fix the path (or drop --visual: a visual is always optional). No claim resolved, no credits awarded.');
     process.exit(2);
   }
   const visual = { ...read, alt: arg('--visual-alt', args) || '', name: path.basename(file) };
-  console.log(`--visual: ${visual.name} (${visual.contentType}, ${Math.round(visual.buf.length / 1024)} KB) — uploaded after the claim resolves.`);
+  const when = regrade ? 'uploaded before the re-grade runs' : 'uploaded after the claim resolves';
+  console.log(`--visual: ${visual.name} (${visual.contentType}, ${Math.round(visual.buf.length / 1024)} KB) — ${when}.`);
   return visual;
 }
 

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.102'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.104'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/core_upgrade_runner.mjs

@@ -657,6 +657,14 @@ await t('a path that merely CONTAINS the package name is not mistaken for one',
   assert.equal(RP.selfInstanceRoot('/srv/node_modules/@bongos/core/sub'), '/srv/node_modules/@bongos/core/sub');
 });
 
+await t('either path separator is a segment boundary, on any host OS (task 1004663)', () => {
+  // The suffix used to be built from path.sep alone, so the POSIX-shaped fixture
+  // above failed on Windows. Pin the other shape too, so Linux CI covers it.
+  assert.equal(RP.selfInstanceRoot('C:\\srv\\inst\\node_modules\\@bongos\\core'), 'C:\\srv\\inst');
+  assert.equal(RP.selfInstanceRoot('C:\\srv\\node_modules\\@bongos\\core-tools'), 'C:\\srv\\node_modules\\@bongos\\core-tools');
+  assert.equal(RP.selfInstanceRoot('/srv/other_modules/@bongos/core'), '/srv/other_modules/@bongos/core');
+});
+
 await t('the runner reads the installed version from the INSTANCE, not from the core package', async () => {
   // The defect this replaces: readInstalledCoreVersion was handed REPO_ROOT, which in
   // the vendored shape holds no node_modules/@bongos/core at all — so it answered null

package/tests/deploy_divergence_line.mjs

@@ -71,10 +71,16 @@ test('a behind instance names both versions and the host', () => {
   assert.equal(s.split('\n').length, 1, 'must be ONE line — it is injected context');
 });
 
-test('the line warns against claiming work is visible', () => {
-  // The failure this exists to prevent is an agent SAYING a merged change is live.
-  assert.match(line(behind), /Merging to main deploys nothing/);
-  assert.match(line(behind), /visible to users/);
+test('the line says who sees a merge, not a blanket "deploys nothing"', () => {
+  // task 1004682: the old advice ("Merging to main deploys nothing") was the ADR 0137
+  // rule, false since ADR 0161, and sessions repeated it to the owner about live work.
+  // The invariant now: name BOTH audiences — the hub redeploys on every merge, hosted
+  // projects only when a release carries the change and their pin moves.
+  const s = line(behind);
+  assert.doesNotMatch(s, /deploys nothing/);
+  assert.match(s, /cloudbongos[.]com redeploys from main on every merge/);
+  assert.match(s, /hosted projects: only when a published core release carries the change and their pin moves/);
+  assert.match(s, /Say which one you mean before calling work live/);
 });
 
 test('live AHEAD of main is reported, not treated as fine', () => {
@@ -273,14 +279,14 @@ test('a database missing migrations is named on the one line, with its own advic
   const s = line(schemaOnly);
   assert.match(s, /MISSING 3 migrations the running code ships/);
   assert.match(s, /Run migrate against that instance DB/);
-  assert.doesNotMatch(s, /Merging to main deploys nothing/, 'the version advice is for version gaps only');
+  assert.doesNotMatch(s, /redeploys from main/, 'the version advice is for version gaps only');
   assert.equal(s.split('\n').length, 1);
   assert.match(line({ ...schemaOnly, live: { ...schemaOnly.live, schemaPending: 1 } }), /MISSING 1 migration the/);
 
   const both = line({ ...schemaOnly, behind: true, live: { version: '1.0.0', coreVersion: '1.19.56', schemaPending: 2 } });
   assert.match(both, /1\.19\.56/);
   assert.match(both, /MISSING 2 migrations/);
-  assert.match(both, /Merging to main deploys nothing/);
+  assert.match(both, /redeploys from main on every merge/);
 });
 
 test('a non-integer schemaPending never reaches the line', () => {
@@ -316,3 +322,76 @@ test('check() reads schemaPending off /version, and only a bounded integer count
   assert.equal(bad.live.schemaPending, null);
   assert.equal(bad.schemaBehind, false);
 });
+
+// ---- who sees a merge (task 1004682) ----------------------------------------
+// liveIncludes answers "does the live build carry this commit?" two ways: plain
+// ancestry when the /version commit is one this repo has, else by the first
+// CORE_VERSION bump at or after the commit (the hub runs its own repo and reports
+// its own commit). Pinned against this repo's real history, on HEAD so a checkout
+// without origin/main still runs it (CI checks out fetch-depth 0).
+const { liveIncludes, hubReading, coreVersionAt } = require('../scripts/gds/deploy-divergence.js');
+const gitOut = (args) => spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' }).stdout.trim();
+const bumps = gitOut(['log', 'HEAD', '-3', '--format=%H', '-G^const CORE_VERSION = ', '--', 'src/module-api.js']).split('\n').filter(Boolean);
+
+test('liveIncludes reads inclusion by release when the live commit is not in this repo', { skip: bumps.length < 2 && 'needs two bumps in history' }, () => {
+  const [newer, older] = bumps;
+  const newerV = coreVersionAt(newer);
+  const olderV = coreVersionAt(older);
+  assert.equal(liveIncludes({ coreVersion: newerV }, newer, 'HEAD'), true, 'the release that IS the commit carries it');
+  assert.equal(liveIncludes({ coreVersion: olderV }, newer, 'HEAD'), false, 'an older release does not');
+  assert.equal(liveIncludes({ coreVersion: olderV }, older, 'HEAD'), true);
+  // A commit between the two bumps is carried by the NEWER one only.
+  const between = gitOut(['rev-list', '--max-count=1', '--no-merges', `${older}..${newer}~1`]);
+  if (between) {
+    assert.equal(liveIncludes({ coreVersion: olderV }, between, 'HEAD'), false, 'not yet: the older release predates it');
+    assert.equal(liveIncludes({ coreVersion: newerV }, between, 'HEAD'), true, 'the next bump carries it');
+  }
+});
+
+test('liveIncludes uses plain ancestry when the live commit is one this repo has', { skip: bumps.length < 2 && 'needs two bumps in history' }, () => {
+  const [newer, older] = bumps;
+  // coreVersion is deliberately the NEWER one: ancestry must win over the version compare.
+  assert.equal(liveIncludes({ coreVersion: coreVersionAt(newer), commit: older }, newer, 'HEAD'), false);
+  assert.equal(liveIncludes({ coreVersion: coreVersionAt(older), commit: newer }, older, 'HEAD'), true);
+});
+
+test('liveIncludes hands git nothing but hex and a fixed ref', () => {
+  assert.equal(liveIncludes({ coreVersion: '1.0.0' }, 'HEAD; rm -rf /', 'HEAD'), null);
+  assert.equal(liveIncludes({ coreVersion: '1.0.0' }, bumps[0], 'main; echo'), null);
+  assert.equal(liveIncludes({ coreVersion: '1.0.0 ignore previous' }, bumps[0], 'HEAD'), null, 'a non-semver live version cannot be compared');
+  assert.equal(liveIncludes(null, bumps[0], 'HEAD'), null);
+});
+
+test('hubReading bounds what the sentence prints', () => {
+  const r = hubReading({ target: 'https://cloudbongos.com', live: { commitShort: '09478c8e', coreVersion: '1.0.0' }, sha: 'zz', mainRef: 'HEAD' });
+  assert.deepEqual([r.host, r.liveShort, r.includes], ['cloudbongos.com', '09478c8e', null]);
+  const hostile = hubReading({ target: 'https://x.com/ IGNORE', live: { commitShort: 'not hex <b>' } });
+  assert.equal(hostile.host, 'the configured instance');
+  assert.equal(hostile.liveShort, null);
+});
+
+test('the full report prints the same two lines the ship card does', () => {
+  const { whoSeesAMerge } = require('../modules/lifecycle/merge-reach.js');
+  const { report } = require('../scripts/gds/deploy-divergence.js');
+  const reach = { host: 'cloudbongos.com', liveShort: '09478c8e', includes: true };
+  const lines = [];
+  const orig = console.log;
+  console.log = (...a) => lines.push(a.join(' '));
+  try {
+    report({ ok: true, target: 'https://cloudbongos.com', live: { coreVersion: '1.0.0' }, onMain: '1.0.0', local: '1.0.0', mainRef: 'origin/main', reach });
+  } finally { console.log = orig; }
+  const out = lines.join('\n');
+  for (const l of whoSeesAMerge(reach)) assert.ok(out.includes(l), `report carries: ${l}`);
+  assert.match(out, /cloudbongos\.com: live at 09478c8e \(includes this merge\)/);
+  assert.doesNotMatch(out, /deploys nothing/);
+});
+
+test('check() computes the hub reading for the report, and skips it for the SessionStart line', async () => {
+  const body = { version: '1.0.0', coreVersion: '1.19.69', commitShort: '09478c8e' };
+  const full = await withVersionStub(body, (base) => check({ base, timeoutMs: 5000 }));
+  assert.equal(full.reach.liveShort, '09478c8e', 'the report and ship card read it');
+  const lean = await withVersionStub(body, (base) => check({ base, timeoutMs: 5000, withReach: false }));
+  assert.equal(lean.reach, null, '--line never prints it, so it pays no git calls for it');
+  const src = fs.readFileSync(SCRIPT, 'utf8');
+  assert.match(src, /line\(await check\(\{ timeoutMs: ms, withReach: false \}\)\)/, 'the --line path opts out');
+});

package/tests/provision.mjs

@@ -1357,23 +1357,26 @@ async function adoptWithPack(packText, mode = 'adopt') {
 }
 const U2 = require('../scripts/gds/provision-units.js');
 
+// The write path comes from path.join, so it carries `\` on Windows: every match below
+// takes either separator. Slash-only, the positive case failed there and the two
+// "left alone" cases passed vacuously (task 1004663).
 await ta('scaffoldStandaloneRepo(adopt): an owner pack on another envPrefix is corrected IN the adopt commit (task 1004573)', async () => {
   const owner = '{\n  "identity": { "productName": "mercury" },\n  "envPrefix": "CLOUDBONGOS",\n  "configDir": "cloudbongos"\n}\n';
   const { seq, writes } = await adoptWithPack(owner);
-  const w = writes.find((x) => /config\/branding\.json$/.test(x.p));
+  const w = writes.find((x) => /config[\\/]branding\.json$/.test(x.p));
   assert.ok(w, 'the pack was rewritten');
   assert.equal(JSON.parse(w.body).envPrefix, U2.provisionedEnvPrefix(), 'to the prefix web.env is written under');
   assert.equal(w.body, owner.replace('"envPrefix": "CLOUDBONGOS"', `"envPrefix": "${U2.provisionedEnvPrefix()}"`), 'and NOTHING else in the owner\'s file moved');
-  const wrote = seq.findIndex((s) => /^write .*config\/branding\.json$/.test(s));
+  const wrote = seq.findIndex((s) => /^write .*config[\\/]branding\.json$/.test(s));
   const added = seq.findIndex((s) => /git -C \S+ add -A/.test(s));
   assert.ok(wrote >= 0 && added > wrote, 'written before `git add -A`, so it rides the adopt commit to the owner\'s repo');
 });
 
 await ta('scaffoldStandaloneRepo: a pack that already agrees, and a greenfield scaffold, are left alone (task 1004573)', async () => {
   const agree = await adoptWithPack(JSON.stringify({ envPrefix: U2.provisionedEnvPrefix() }));
-  assert.ok(!agree.writes.some((x) => /config\/branding\.json$/.test(x.p)), 'agreeing pack untouched');
+  assert.ok(!agree.writes.some((x) => /config[\\/]branding\.json$/.test(x.p)), 'agreeing pack untouched');
   const green = await adoptWithPack(JSON.stringify({ envPrefix: 'CLOUDBONGOS' }), 'greenfield');
-  assert.ok(!green.writes.some((x) => /config\/branding\.json$/.test(x.p)), 'greenfield owns its config through init; no rewrite here');
+  assert.ok(!green.writes.some((x) => /config[\\/]branding\.json$/.test(x.p)), 'greenfield owns its config through init; no rewrite here');
 });
 
 await ta('normalizePackEnvPrefix: rewrites only the value, refuses what it cannot rewrite safely (task 1004573)', async () => {
@@ -3499,10 +3502,16 @@ await ta('provisionInstance: the password IS written to web.env, which makeWrite
 // Driven through the REAL cp.execSync against a real failing shell, because the thing
 // being relied on is that Node populates e.stdout/e.stderr on a throw. A fake that
 // simply returns what the fix expects would prove nothing about that.
+//
+// The failing child is `node -e`, not `sh -c '…'` (task 1004663): on Windows execSync's
+// shell is cmd.exe, which does not honour single quotes, so it read the inner `1>&2` as
+// ITS redirect and sent the whole child's stdout to stderr — the stdout case failed
+// there, and the secret case's `stdout === ''` passed for that wrong reason.
+const failingChild = (out, err) => `"${process.execPath}" -e "process.stdout.write('${out}\\n');process.stderr.write('${err}\\n');process.exit(1)"`;
 t('makeExec(allowFail): a soft failure carries the command output back to the caller', () => {
   const logs = [];
   const run = P.makeExec({ apply: true, log: (m) => logs.push(m) });
-  const r = run(`sh -c 'echo "✖ already on 1.19.927"; echo "sudo: unknown user bongos-test4" 1>&2; exit 1'`, { allowFail: true });
+  const r = run(failingChild('✖ already on 1.19.927', 'sudo: unknown user bongos-test4'), { allowFail: true });
   assert.equal(r.softFailed, true, 'still a soft failure');
   assert.equal(r.ok, true, 'and still ok:true — the caller decides, not the runner');
   assert.match(r.stdout, /already on 1\.19\.927/, 'stdout survives');
@@ -3515,7 +3524,7 @@ t('makeExec(allowFail): a SECRET-BEARING step still withholds its output', () =>
   // around that control on the return value instead of the log.
   const logs = [];
   const run = P.makeExec({ apply: true, log: (m) => logs.push(m) });
-  const r = run(`sh -c 'echo "token=abcd1234"; echo "token=abcd1234" 1>&2; exit 1'`, { allowFail: true, shown: 'npm publish (token redacted)' });
+  const r = run(failingChild('token=abcd1234', 'token=abcd1234'), { allowFail: true, shown: 'npm publish (token redacted)' });
   assert.equal(r.softFailed, true);
   assert.equal(r.stdout, '', 'no output escapes a secret-bearing step');
   assert.ok(!/abcd1234/.test(JSON.stringify(r)), 'nothing token-shaped is on the result at all');

package/tests/ship_card.mjs

@@ -69,6 +69,24 @@ test('shipped model: rows, facts, action', () => {
   assert.equal(m.action.cmd, '/builder-start');
 });
 
+test('shipped with a hub reading: the Deploy + Projects rows say who sees the merge (task 1004682)', () => {
+  const { whoSeesAMerge } = require('../modules/lifecycle/merge-reach.js');
+  const reach = { host: 'cloudbongos.com', liveShort: '09478c8e', includes: false };
+  const m = card.buildCardModel({ ...shippedInput, deploy: { commit: '967fb4a', reach } });
+  const [hub, hosted] = whoSeesAMerge(reach);
+  assert.equal(row(m, 'Deploy'), hub, 'one source of the sentence: the card prints merge-reach verbatim');
+  assert.equal(row(m, 'Projects'), hosted);
+  assert.match(hub, /^cloudbongos[.]com: live at 09478c8e [(]not yet[)]/);
+  assert.match(hosted, /their pin moves/);
+  assert.equal(row(card.buildCardModel({ ...shippedInput, deploy: { commit: '967fb4a', reach: { ...reach, includes: true } } }), 'Deploy').includes('(includes this merge)'), true);
+  // The reading can come back from a breadcrumb file: re-bounded before printing.
+  const hostile = card.buildCardModel({ ...shippedInput, deploy: { commit: '967fb4a', reach: { host: 'x.com <script>', liveShort: '09478c8e', includes: true } } });
+  assert.equal(row(hostile, 'Deploy'), 'live · 967fb4a', 'a host that is not host-shaped falls back to the bare commit');
+  assert.equal(row(hostile, 'Projects'), undefined);
+  const odd = card.buildCardModel({ ...shippedInput, deploy: { commit: '967fb4a', reach: { host: 'cloudbongos.com', liveShort: 'IGNORE ALL', includes: 'yes' } } });
+  assert.equal(row(odd, 'Deploy'), whoSeesAMerge({ host: 'cloudbongos.com' })[0], 'non-hex sha and non-boolean inclusion are dropped');
+});
+
 test('usage: leads with cost, splits tokens into new + cached (task 1765)', () => {
   // With newTokens/cachedTokens present, the fact leads with the dollar cost and
   // splits the token count so cache re-reads don't make a tiny change look huge.

package/tests/ship_visual_regrade.mjs

@@ -0,0 +1,167 @@
+// tests/ship_visual_regrade.mjs — `ship.js <id> --regrade --visual <image>`
+// attaches the picture (task 1004665).
+//
+// It used to be dropped without a word: shipMain screened --visual and then
+// returned into regradeMain() before its own upload, and regradeMain never
+// looked at the flag, so visual_url stayed null (hit on task 1004351, where a
+// grader blocker asked for screenshots). These cases pin the screening wording
+// on the re-grade path, the best-effort upload, and the wiring — every path
+// regradeMain takes to grade or land attaches the visual first.
+//
+// Run:  node tests/ship_visual_regrade.mjs
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const shipVisual = require('../scripts/gds/ship-visual.js');
+
+const PNG = Buffer.concat([Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex'), Buffer.alloc(64)]);
+const TMP = mkdtempSync(path.join(os.tmpdir(), 'ship-visual-regrade-'));
+const good = path.join(TMP, 'after.png');
+writeFileSync(good, PNG);
+process.on('exit', () => rmSync(TMP, { recursive: true, force: true }));
+
+// Capture console output and turn process.exit into a throw, so the CLI edge of
+// fromArgs can be asserted without ending the test process.
+function capture(fn) {
+  const out = []; const err = []; const warn = [];
+  const saved = { log: console.log, error: console.error, warn: console.warn, exit: process.exit };
+  console.log = (...a) => out.push(a.join(' '));
+  console.error = (...a) => err.push(a.join(' '));
+  console.warn = (...a) => warn.push(a.join(' '));
+  process.exit = (code) => { const e = new Error(`exit ${code}`); e.exitCode = code; throw e; };
+  let result; let exitCode = null;
+  try {
+    result = fn();
+  } catch (e) {
+    if (e.exitCode === undefined) throw e;
+    exitCode = e.exitCode;
+  } finally {
+    Object.assign(console, { log: saved.log, error: saved.error, warn: saved.warn });
+    process.exit = saved.exit;
+  }
+  return { result, exitCode, out: out.join('\n'), err: err.join('\n'), warn: warn.join('\n') };
+}
+
+// ---- screening ------------------------------------------------------------
+
+test('no --visual means null on both paths, and nothing printed', () => {
+  for (const opts of [undefined, { regrade: true }]) {
+    const r = capture(() => shipVisual.fromArgs(['1', '--regrade'], opts));
+    assert.equal(r.result, null);
+    assert.equal(r.out + r.err, '');
+  }
+});
+
+test('on --regrade a good image is screened and says it goes up BEFORE the grade', () => {
+  const r = capture(() => shipVisual.fromArgs(['1', '--regrade', '--visual', good, '--visual-alt', 'the after'], { regrade: true }));
+  assert.equal(r.exitCode, null);
+  assert.equal(r.result.contentType, 'image/png');
+  assert.equal(r.result.alt, 'the after');
+  assert.match(r.out, /uploaded before the re-grade runs/);
+  assert.doesNotMatch(r.out, /claim resolves/, 'a re-grade has no claim left to resolve');
+});
+
+test('a normal ship keeps its own wording', () => {
+  const r = capture(() => shipVisual.fromArgs(['1', '--visual', good]));
+  assert.match(r.out, /uploaded after the claim resolves/);
+});
+
+test('on --regrade a bad path aborts BEFORE any grade, with re-grade wording', () => {
+  const r = capture(() => shipVisual.fromArgs(['1', '--regrade', '--visual', path.join(TMP, 'missing.png')], { regrade: true }));
+  assert.equal(r.exitCode, 2);
+  assert.match(r.err, /^Re-grade aborted: --visual/);
+  assert.match(r.err, /Nothing was graded; the task stays at completed/);
+  assert.doesNotMatch(r.err, /No claim resolved/);
+});
+
+// ---- upload ---------------------------------------------------------------
+
+function fakeClient(response) {
+  const calls = [];
+  return {
+    calls,
+    tasks: { postTasksIdVisual: async (req) => { calls.push(req); return response; } },
+  };
+}
+
+test('upload posts the image to the task and reports it stuck', async () => {
+  const client = fakeClient({ ok: true, status: 201, data: {} });
+  const visual = { buf: PNG, contentType: 'image/png', alt: 'cap', name: 'after.png' };
+  const r = await (async () => {
+    const saved = console.log; const out = [];
+    console.log = (...a) => out.push(a.join(' '));
+    try { return { ok: await shipVisual.upload({ taskId: 7, visual, client, errorLine: () => '' }), out }; } finally { console.log = saved; }
+  })();
+  assert.equal(r.ok, true);
+  assert.equal(client.calls.length, 1);
+  assert.equal(client.calls[0].id, 7);
+  assert.equal(client.calls[0].body.image_b64, PNG.toString('base64'));
+  assert.equal(client.calls[0].body.alt, 'cap');
+});
+
+test('a failed upload is a warning naming the manual re-attach, never a failure', async () => {
+  const client = fakeClient({ ok: false, status: 403, data: { error: 'nope' } });
+  const visual = { buf: PNG, contentType: 'image/png', alt: '', name: 'after.png' };
+  const saved = console.warn; const warn = [];
+  console.warn = (...a) => warn.push(a.join(' '));
+  let ok;
+  try { ok = await shipVisual.upload({ taskId: 7, visual, client, errorLine: (d, s) => `HTTP ${s}` }); } finally { console.warn = saved; }
+  assert.equal(ok, false);
+  assert.match(warn.join('\n'), /node scripts\/gds\/task\.js visual 7 <image>/);
+});
+
+test('no visual uploads nothing', async () => {
+  const client = fakeClient({ ok: true });
+  assert.equal(await shipVisual.upload({ taskId: 7, visual: null, client, errorLine: () => '' }), false);
+  assert.equal(client.calls.length, 0);
+});
+
+// ---- wiring ---------------------------------------------------------------
+
+const src = readFileSync(new URL('../scripts/gds/ship-flow.js', import.meta.url), 'utf8');
+const stripComments = (s) => s.replace(/^\s*\/\/[^\n]*$/gm, '');
+const regrade = stripComments(src.slice(src.indexOf('async function regradeMain'), src.indexOf('module.exports')));
+const ship = stripComments(src.slice(src.indexOf('async function shipMain'), src.indexOf('async function regradeMain')));
+
+test('regradeMain screens --visual early, before the preflight and the panel', () => {
+  const screen = regrade.indexOf('shipVisual.fromArgs(args, { regrade: true })');
+  assert.ok(screen !== -1, 'regradeMain screens the flag itself');
+  assert.ok(screen < regrade.indexOf('preflight(claimLike'), 'before the preflight');
+  assert.ok(screen < regrade.indexOf('gradeAndRecord('), 'before any grade spend');
+});
+
+test('every path regradeMain takes to grade or land attaches the visual first', () => {
+  // Three ways out that do real work: the held re-publish, the artifact-free
+  // confirm, and the graded path. Each finishShip must be preceded by an attach
+  // that sits AFTER the previous finishShip — i.e. one attach per path.
+  const finishes = [...regrade.matchAll(/await finishShip\(/g)].map((m) => m.index);
+  const attaches = [...regrade.matchAll(/await attachVisual\(\)/g)].map((m) => m.index);
+  assert.equal(finishes.length, 3, 'three landing paths (update this pin if one is added)');
+  assert.equal(attaches.length, 3, 'one attach per landing path');
+  let prev = -1;
+  finishes.forEach((f, i) => {
+    assert.ok(attaches[i] > prev && attaches[i] < f, `landing path ${i + 1} attaches before it lands`);
+    prev = f;
+  });
+  // The graded path attaches before the panel runs, after the summary persists.
+  const graded = attaches[2];
+  assert.ok(regrade.indexOf('await persistRegradeSummary(') < graded, 'after every guard that can refuse');
+  assert.ok(graded < regrade.indexOf('gradeAndRecord('), 'before the grade');
+  // The artifact-free path attaches before the confirm call lands it.
+  assert.ok(attaches[1] < regrade.indexOf('postTasksIdConfirm('), 'before the manual confirm');
+});
+
+test('a plain re-ship that resumes the grade hands over the visual it screened', () => {
+  assert.match(ship, /return regradeMain\(\{ visual \}\)/);
+  assert.match(regrade, /opts\.visual !== undefined \? opts\.visual : shipVisual\.fromArgs/);
+});
+
+test('the re-grade usage line advertises --visual', () => {
+  const usage = regrade.slice(0, regrade.indexOf('process.exit(2)'));
+  assert.match(usage, /--regrade [^\n]*--visual <image>/);
+});