@bongos/core 1.19.645 → 1.19.647

package/modules/dev-box/box-access.js

@@ -254,6 +254,117 @@ function sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) {
   return [...base, ...extra];
 }
 
+// ---------------------------------------------------------------------------
+// PURE: builder-requested WIDENING (task 1003087 / idea 1000793)
+// ---------------------------------------------------------------------------
+
+// A builder sometimes needs a directory their task scope did not pull — to run
+// the full suite, to read a caller, to regenerate a TREE-DEPENDENT artifact. The
+// obvious move, `git sparse-checkout add <path>`, does not survive: the */10
+// source-fetch cron re-applies the SERVER-computed set and deletes the addition,
+// including WHILE A COMMAND IS RUNNING (a live suite died mid-run with
+// MODULE_NOT_FOUND that read exactly like a code bug; a box-committed
+// gen-repo-map regen off a narrow tree reds CI's freshness gate — learning
+// 1000192, which stranded PR #254).
+//
+// So the widening is recorded SERVER-side and unioned in HERE, which is what
+// makes it tick-surviving: the cron asks this endpoint for the set on every tick,
+// so it gets the union too. Nothing in the instance-owned fetch script changes —
+// which matters, because the neutral core does not ship it (ADR 0150).
+
+// Bounds. Small on purpose: this is an escape hatch for a handful of dirs, not a
+// second scope system. Over the cap the extras are dropped, not an error — a
+// truncated widen still fetches, and failing the source pull over it would be a
+// far worse trade than materializing less.
+const MAX_WIDEN_PATHS = 24;
+const MAX_WIDEN_PATH_LEN = 200;
+
+// withinAny(p, roots) — is p one of roots, or underneath one? Cone mode
+// materializes a directory and everything below it, so "already covered" and
+// "inside the allowed surface" are the same ancestor walk.
+function withinAny(p, roots) {
+  let q = p;
+  for (;;) {
+    if (roots.includes(q)) return true;
+    const cut = q.lastIndexOf('/');
+    if (cut < 0) return false;
+    q = q.slice(0, cut);
+  }
+}
+
+// normalizeWidenPath — repo-relative POSIX directory, or null when it is not one.
+//
+// This is a path that reaches `git sparse-checkout set` on a box, so it is
+// validated as INPUT rather than trusted: absolute paths, Windows drive letters,
+// '..' traversal and empty segments are all refused rather than normalized away,
+// because "cleaned up into something that still works" is how a traversal becomes
+// a shrug. Backslashes are folded to '/' first so a Windows-typed path is judged
+// on what it means, not on its separator.
+function normalizeWidenPath(raw) {
+  if (typeof raw !== 'string') return null;
+  // BACKSLASH by char code, not as a literal: this file is edited through
+  // tooling that has silently collapsed a doubled backslash before, and a
+  // separator fold that quietly stops folding is invisible until a Windows
+  // path slips through as one long segment.
+  const BACKSLASH = String.fromCharCode(92);
+  let p = raw.trim().split(BACKSLASH).join('/');
+  while (p.startsWith('./')) p = p.slice(2);
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  if (!p || p === '.' || p.length > MAX_WIDEN_PATH_LEN) return null;
+  if (p.startsWith('/') || /^[A-Za-z]:/.test(p)) return null;
+  const segs = p.split('/');
+  if (!segs.every((s) => s && s !== '.' && s !== '..' && /^[A-Za-z0-9._-]+$/.test(s))) return null;
+  return p;
+}
+
+// admissibleWidenPaths — the widen requests this builder's RANK actually permits,
+// normalized, deduped, capped and sorted.
+//
+// THIS IS THE SECURITY BOUNDARY OF THE FEATURE, so it is stated plainly: widening
+// changes what is MATERIALIZED on a box, and rank decides how much of the repo a
+// box may hold at all (ADR 0031 section 9.2 — 'full' for Metic+, the 'starter'
+// surface below that). Honoring an arbitrary widen would hand a Xenos the whole
+// tree through a convenience flag, which is a rank escalation dressed as
+// ergonomics. So:
+//   - a builder whose RANK scope is 'full' may widen anywhere (they are already
+//     entitled to the entire repo; the widen only decides what gets pulled);
+//   - anyone else may widen only INSIDE the starter surface. That is not a null
+//     grant: a task-scoped box is BASE union its modules, which is NARROWER than
+//     starter, so this is exactly the room to climb back to what their rank
+//     already allowed — and no further.
+// The authoring wall is untouched either way. What a builder may CHANGE is still
+// goal-scope-check against the module globs, never what happens to be on disk
+// (ADR 0148).
+function admissibleWidenPaths(widenPaths, rank) {
+  const unrestricted = boxScopeForRank(rank) === 'full';
+  const out = [];
+  const seen = new Set();
+  for (const raw of Array.isArray(widenPaths) ? widenPaths : []) {
+    const p = normalizeWidenPath(raw);
+    if (!p || seen.has(p)) continue;
+    if (!unrestricted && !withinAny(p, STARTER_SPARSE_PATHS)) continue;
+    seen.add(p);
+    out.push(p);
+    if (out.length >= MAX_WIDEN_PATHS) break;
+  }
+  return out.sort();
+}
+
+// withWidenPaths — union admitted widen dirs into a computed sparse set, skipping
+// any the set already covers (cone mode pulls a dir and everything under it, so
+// adding 'scripts/gds' when 'scripts' is present is noise in the git command and
+// noise in the box's scope readout). A null set is the 'full' clone — there is
+// nothing to widen into, so it passes through untouched.
+function withWidenPaths(sparsePaths, admitted) {
+  if (!Array.isArray(sparsePaths) || !admitted || admitted.length === 0) return sparsePaths;
+  const out = [...sparsePaths];
+  for (const dir of admitted) {
+    if (withinAny(dir, out)) continue;
+    out.push(dir);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // PURE: the per-fetch access decision (consumed by GET /box/source-access)
 // ---------------------------------------------------------------------------
@@ -295,7 +406,7 @@ function sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) {
 //   { allowed:false, reason:'BUILDER_INACTIVE' }
 //   { allowed:false, reason:'INSUFFICIENT_RANK', required, actual }
 //   { allowed:true,  scope, spec }
-function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, hasActiveClaims, moduleScopeMap } = {}) {
+function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, hasActiveClaims, moduleScopeMap, widenPaths } = {}) {
   if (status && status !== 'active') {
     return { allowed: false, reason: 'BUILDER_INACTIVE' };
   }
@@ -307,23 +418,32 @@ function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, sco
       actual: rank ?? null,
     };
   }
+  // The builder's own widening, narrowed to what their rank already reaches
+  // (task 1003087). Computed once here so every sparse branch below unions the
+  // SAME set — a widen that applied to one scope and not another would be a
+  // surprise that only surfaces when a claim changes.
+  const widen = admissibleWidenPaths(widenPaths, rank);
+
   // Claim-driven task scope (present → the box asks for exactly its work's code).
   if (Array.isArray(scopeKeys)) {
     if (scopeKeys.length > 0) {
-      const sparsePaths = sparsePathsForScopeKeys(scopeKeys, moduleScopeMap);
+      const sparsePaths = withWidenPaths(sparsePathsForScopeKeys(scopeKeys, moduleScopeMap), widen);
       return { allowed: true, scope: 'task', spec: { scope: 'task', mode: 'sparse', sparsePaths } };
     }
     // Empty. A builder mid-claim whose goals declare no wall gets the rank scope,
     // NOT a stripped box — the planning gap is not theirs to pay for.
     if (!hasActiveClaims) {
-      const sparsePaths = sparsePathsForScopeKeys([], moduleScopeMap);
+      const sparsePaths = withWidenPaths(sparsePathsForScopeKeys([], moduleScopeMap), widen);
       return { allowed: true, scope: 'base', spec: { scope: 'base', mode: 'sparse', sparsePaths } };
     }
   }
   // No claim signal (no lifecycle port on this instance), or claims with an
   // undeclared goal wall: the pre-ADR-0148 rank fallback.
   const scope = boxScopeForRank(rank);
-  return { allowed: true, scope, spec: cloneSpecForScope(scope) };
+  const spec = cloneSpecForScope(scope);
+  // 'full' carries sparsePaths null (the whole repo) — withWidenPaths passes it
+  // through, because there is no sparse set to widen INTO.
+  return { allowed: true, scope, spec: { ...spec, sparsePaths: withWidenPaths(spec.sparsePaths, widen) } };
 }
 
 // scopeMetadata — PURE. The credential-FREE projection of a source-access
@@ -470,6 +590,10 @@ module.exports = {
   boxCanHoldSource,
   cloneSpecForScope,
   sparsePathsForScopeKeys, // ADR 0148 — BASE ∪ the claims' module dirs (cone-mode)
+  MAX_WIDEN_PATHS,         // task 1003087 — the builder-widening cap
+  normalizeWidenPath,      // task 1003087 — repo-relative dir, or null
+  admissibleWidenPaths,    // task 1003087 — the widen requests this RANK permits
+  withWidenPaths,          // task 1003087 — union a widen set into a sparse set
   scopeMetadata, // BV1.R100 — credential-free projection for GET /box/scope
   // pure — decisions
   decideSourceAccess,

package/modules/dev-box/boxes.js

@@ -397,6 +397,26 @@ function decideEnsureAction({ boxState, rank, status, blocked = false, floor = D
 // DB helpers (async). Each takes the pg pool (or a client mid-transaction).
 // ---------------------------------------------------------------------------
 
+// setBoxWidenPaths — replace a box row's builder-requested widen set (task
+// 1003087). Whole-set replace rather than add/remove SQL: the set is tiny and
+// capped, the caller has already normalized and rank-filtered it, and a
+// read-modify-write in one statement keeps two concurrent widens from
+// interleaving into a half-applied list.
+//
+// Returns the stored array, or null when the builder has no box row — the
+// caller turns that into a 404 rather than silently creating one, because a
+// widen with no box to apply it to is a request that has not happened yet.
+async function setBoxWidenPaths(db, builderId, paths) {
+  const { rows } = await db.query(
+    `UPDATE builder_boxes
+        SET widen_paths = $2::text[], updated_at = now()
+      WHERE builder_id = $1
+      RETURNING widen_paths`,
+    [builderId, Array.isArray(paths) ? paths : []]
+  );
+  return rows[0] ? rows[0].widen_paths : null;
+}
+
 async function getBoxByBuilderId(db, builderId) {
   const { rows } = await db.query(
     `SELECT * FROM builder_boxes WHERE builder_id = $1`,
@@ -891,6 +911,7 @@ module.exports = {
   decideEnsureAction,
   // db
   getBoxByBuilderId,
+  setBoxWidenPaths,
   ensureBoxRow,
   listBoxes,
   recordEvent,

package/modules/dev-box/routes/box.js

@@ -480,8 +480,16 @@ module.exports = function buildBoxRouter() {
           hasActiveClaims = undefined;
         }
       }
-      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap });
+      // Read the box BEFORE deciding: its widen_paths are an INPUT to the sparse
+      // set now (task 1003087). A builder-requested directory is unioned in here,
+      // which is what makes it survive the */10 cron — the cron re-asks THIS
+      // endpoint every tick, so the union comes back with it instead of being
+      // deleted by the next `git sparse-checkout set`.
       const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      const decision = boxAccess.decideSourceAccess({
+        rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap,
+        widenPaths: box ? box.widen_paths : null,
+      });
       const auditDeny = (reason, extra) =>
         box && boxAccess.recordSourceEvent(pool, {
           box, builderId: req.builder.id, event: 'source_deny',
@@ -598,7 +606,13 @@ module.exports = function buildBoxRouter() {
           hasActiveClaims = undefined;
         }
       }
-      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap });
+      // Same widen input as the real fetch — this readout exists precisely so it
+      // cannot drift from what the box will actually hold.
+      const scopeBox = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      const decision = boxAccess.decideSourceAccess({
+        rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap,
+        widenPaths: scopeBox ? scopeBox.widen_paths : null,
+      });
       if (!decision.allowed) {
         return res.fail('SOURCE_ACCESS_REVOKED', 403, {
           reason: decision.reason,
@@ -753,6 +767,98 @@ module.exports = function buildBoxRouter() {
     }
   });
 
+  // GET /box/widen — the caller's own recorded widen set (task 1003087).
+  // rank: any authenticated builder, own resource. Reports what is STORED plus
+  // what is currently ADMITTED, because those differ whenever a request sits
+  // outside the builder's rank scope — showing only the stored list would let a
+  // Xenos believe a widen took effect that the fetch quietly drops.
+  router.get('/box/widen', auth.requireBuilder, async (req, res) => {
+    try {
+      const builder = await gdsDb.getBuilderById(req.builder.id);
+      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      if (!box) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
+      const stored = Array.isArray(box.widen_paths) ? box.widen_paths : [];
+      const admitted = boxAccess.admissibleWidenPaths(stored, builder ? builder.rank : null);
+      res.json({
+        widen_paths: stored,
+        admitted,
+        ignored: stored.filter((p) => !admitted.includes(boxAccess.normalizeWidenPath(p))),
+        max: boxAccess.MAX_WIDEN_PATHS,
+      });
+    } catch (err) {
+      log.error('[gds] GET /box/widen', err);
+      res.fail('widen_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /box/widen — record extra sparse-checkout directories that must SURVIVE
+  // the */10 source-fetch (task 1003087, idea 1000793). rank: any authenticated
+  // builder, OWN box (builder_id-scoped in SQL, so no id from the body can point
+  // this at someone else's box).
+  //
+  // Deliberately NOT allowBoxScope. The on-box crons read source-access with a
+  // box-scoped session (ADR 0053); this is a WRITE that changes what the box
+  // pulls forever after, so it takes the builder's own session — the same posture
+  // that keeps a stolen box token from re-scoping the checkout it was stolen from.
+  //
+  // add/remove are applied to the stored set and the result is re-normalized, so
+  // the endpoint is idempotent: widening twice is not an error, and neither is
+  // removing something that was never there.
+  //
+  // A path outside the caller's rank scope is ACCEPTED into storage but reported
+  // in `ignored` rather than refused. That is the honest shape: rank can change,
+  // and a builder promoted to Metic should find the widen they asked for as a
+  // Xenos simply start working, instead of having been silently discarded months
+  // earlier. What it can never do is take effect early — admissibleWidenPaths is
+  // re-evaluated against the LIVE rank on every single fetch.
+  router.post('/box/widen', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      add: { type: 'array' },
+      remove: { type: 'array' },
+      clear: { type: 'boolean' },
+    })) return;
+    try {
+      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      if (!box) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
+      const builder = await gdsDb.getBuilderById(req.builder.id);
+
+      const current = Array.isArray(box.widen_paths) ? box.widen_paths : [];
+      const next = new Set(req.body && req.body.clear === true ? [] : current);
+
+      const rejected = [];
+      for (const raw of Array.isArray(req.body && req.body.add) ? req.body.add : []) {
+        const p = boxAccess.normalizeWidenPath(raw);
+        if (!p) { rejected.push(String(raw).slice(0, 120)); continue; }
+        next.add(p);
+      }
+      for (const raw of Array.isArray(req.body && req.body.remove) ? req.body.remove : []) {
+        const p = boxAccess.normalizeWidenPath(raw);
+        if (p) next.delete(p);
+      }
+      if (rejected.length) {
+        return res.fail('bad_widen_path', 400, {
+          rejected,
+          message: 'a widen path must be a repo-relative directory: no absolute paths, no "..", no drive letters',
+        });
+      }
+
+      const stored = [...next].sort().slice(0, boxAccess.MAX_WIDEN_PATHS);
+      const saved = await boxes.setBoxWidenPaths(pool, req.builder.id, stored);
+      if (saved === null) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
+      const admitted = boxAccess.admissibleWidenPaths(saved, builder ? builder.rank : null);
+      res.json({
+        ok: true,
+        widen_paths: saved,
+        admitted,
+        ignored: saved.filter((p) => !admitted.includes(p)),
+        max: boxAccess.MAX_WIDEN_PATHS,
+      });
+    } catch (err) {
+      log.error('[gds] POST /box/widen', err);
+      res.fail('widen_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // GET /box/authorized-keys — the box pulls its builder's authorized_keys.
   // rank: any authenticated builder (own resource) — but the ALLOW/DENY is decided
   // INSIDE from the caller's LIVE rank+status (boxAccess.decideSourceAccess), NOT a

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.645",
+  "version": "1.19.647",
   "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/box-sync.js

@@ -15,6 +15,18 @@
 //
 // Usage:  node scripts/gds/box-sync.js            # re-fetch now
 //         node scripts/gds/box-sync.js --dry-run  # print what it WOULD run
+//         node scripts/gds/box-sync.js --widen <dir>    # keep <dir> across ticks
+//         node scripts/gds/box-sync.js --unwiden <dir>  # stop keeping it
+//         node scripts/gds/box-sync.js --widen-list     # what is kept, and what is ignored
+//
+// WHY --widen EXISTS (task 1003087 / idea 1000793). `git sparse-checkout add`
+// does not survive: the */10 cron re-applies the SERVER-computed set and deletes
+// the addition, sometimes MID-COMMAND — a live test suite died with
+// MODULE_NOT_FOUND that read exactly like a code bug. --widen records the
+// directory server-side instead, so every fetch (the cron included) returns it
+// in the set and it stops being deleted. It is capped, and it can never widen
+// past what your RANK already reaches — a request outside it is stored but
+// reported as ignored rather than silently applied.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -36,7 +48,78 @@ function resolveFetchScript(opts = {}) {
   try { return fs.existsSync(p) ? p : null; } catch { return null; }
 }
 
+// valueAfter(argv, flag) — the argument following a flag, or null. Kept tiny and
+// pure so the arg handling is testable without spawning anything.
+function valueAfter(argv, flag) {
+  const i = argv.indexOf(flag);
+  if (i < 0) return null;
+  const v = argv[i + 1];
+  return typeof v === 'string' && v && !v.startsWith('--') ? v : null;
+}
+
+// formatWidenReport — PURE. The lines to print for a /box/widen body. Reports
+// IGNORED entries loudly: a widen the server accepted into storage but will not
+// apply (because it is outside your rank scope) looks identical to a working one
+// unless it is said out loud, and a silently-inert widen is exactly the class of
+// bug this whole task is about.
+function formatWidenReport(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return ['widen: could not read your widen set.'];
+  }
+  const kept = Array.isArray(body.widen_paths) ? body.widen_paths : [];
+  const ignored = Array.isArray(body.ignored) ? body.ignored : [];
+  const out = [];
+  out.push(kept.length
+    ? `widen: keeping ${kept.length} path(s) across ticks: ${kept.join(', ')}`
+    : 'widen: nothing kept — the fetch set is whatever your claim scope says.');
+  if (ignored.length) {
+    out.push(`widen: IGNORED (outside your rank scope, stored but not applied): ${ignored.join(', ')}`);
+  }
+  return out;
+}
+
+// The --widen family. Talks to the control plane, so it works off a box too —
+// unlike the fetch itself, the widen set is server state you can inspect and
+// edit from anywhere.
+async function runWiden(argv) {
+  const { apiCall } = require('./cli-lib');
+  const add = valueAfter(argv, '--widen');
+  const remove = valueAfter(argv, '--unwiden');
+  const clear = argv.includes('--widen-clear');
+  const listOnly = !add && !remove && !clear;
+
+  const r = listOnly
+    ? await apiCall('GET', '/api/gds/box/widen')
+    : await apiCall('POST', '/api/gds/box/widen', {
+      ...(add ? { add: [add] } : {}),
+      ...(remove ? { remove: [remove] } : {}),
+      ...(clear ? { clear: true } : {}),
+    });
+
+  if (!r || (r.status !== 200 && r.status !== 201)) {
+    const code = r && r.data && r.data.error ? r.data.error : `HTTP ${r ? r.status : '?'}`;
+    if (code === 'no_box') {
+      console.error('widen: you have no dev box — there is nothing to widen. Provision one first.');
+    } else if (code === 'bad_widen_path') {
+      const bad = r.data && r.data.rejected ? r.data.rejected.join(', ') : '';
+      console.error(`widen: refused ${bad} — give a repo-relative DIRECTORY (no leading /, no "..").`);
+    } else {
+      console.error(`widen: failed (${code}).`);
+    }
+    return 1;
+  }
+  for (const line of formatWidenReport(r.data)) console.log(line);
+  if (!listOnly) console.log('widen: run `box-sync` (no flags) to apply it to the checkout now.');
+  return 0;
+}
+
 function main(argv = process.argv.slice(2)) {
+  // The widen family is server state, not a fetch — handled before the on-a-box
+  // check, so it works from a laptop too.
+  if (argv.some((a) => a === '--widen' || a === '--unwiden' || a === '--widen-list' || a === '--widen-clear')) {
+    runWiden(argv).then((code) => process.exit(code), () => process.exit(1));
+    return;
+  }
   const dryRun = argv.includes('--dry-run') || argv.includes('-n');
   const script = resolveFetchScript();
   if (!script) {
@@ -130,4 +213,4 @@ async function reportScope() {
 
 if (require.main === module) main();
 
-module.exports = { resolveFetchScript, FETCH_SCRIPT, formatScopeReport };
+module.exports = { resolveFetchScript, FETCH_SCRIPT, formatScopeReport, formatWidenReport, valueAfter };

package/scripts/gds/claude-materialize.js

@@ -431,7 +431,20 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       landedNow[name] = { module: mod.key, source: `.claude/skills/${name}`, coreShipped: true };
     }
   }
-  const withdrawable = Object.keys(landedPreviously).filter((n) => SKILL_NAME_RE.test(n) && !landedNow[n]);
+  // A name the CORE ships now is the core's, whatever an older manifest said — a core
+  // skill can take over a name a module once owned, and step 1 copies it in on this very
+  // run. Without this guard 1c deleted it again immediately (task 1003818, a regression
+  // in 1003632's own first cut). materializeModuleSkillsIntoCore states the same rule for
+  // the checkout side via its `tracked(name)` check; this is the instance-side twin.
+  //
+  // The `!skipSkills.has(name)` half is load-bearing, not belt-and-braces: when a DISABLED
+  // module declares a core-shipped name, step 1 SKIPS the copy (that is the task 2103b
+  // exclusion), so the instance's dir really is stale and must still be withdrawn. Keeping
+  // it on the strength of "the core ships this name" would resurrect exactly the bug 1c
+  // exists to fix. Deliberately asked of the CORE source tree rather than the roster, so a
+  // name no enabled module declares any more is still recognised as legitimately sourced.
+  const coreShipsNow = (name) => fs.existsSync(path.join(skillsSrc, name)) && !skipSkills.has(name);
+  const withdrawable = Object.keys(landedPreviously).filter((n) => SKILL_NAME_RE.test(n) && !landedNow[n] && !coreShipsNow(n));
   if (!overwrite) {
     // adopt mode never clobbers what the owner already has; withdrawing is a clobber.
     if (withdrawable.length) summary.notes.push(`${withdrawable.length} skill(s) of a now-disabled module were left in place (adopt mode does not withdraw): ${withdrawable.sort().join(', ')}.`);

package/scripts/gds/ship-flow.js

@@ -9,7 +9,7 @@
 'use strict';
 
 const { cliClient, requireSession, arg, detectWorktreeName } = require('./cli-lib');
-const { resolveProse, markShipProgress, smokeGateMessages } = require('./ship-honesty.js');
+const { resolveProse, markShipProgress, smokeGateMessages, proseFlagPresent, regradeNotesRefusal } = require('./ship-honesty.js');
 const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
 const { scopeForModule, isModuleKey } = require('../../src/bongos/module-scope-map');
 const { matchOne } = require('../../src/bongos/path-match');
@@ -684,6 +684,16 @@ async function regradeMain() {
     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);
   }
+  // task 1003702: refuse --notes rather than swallowing it. The reasoning — why
+  // a refusal and not a persist — is in ship-honesty.js above regradeNotesRefusal
+  // and is not repeated here. What is load-bearing at THIS call site is the
+  // POSITION: before the preflight and before any grade spend, because a refusal
+  // that first costs a 4-worker panel run is barely better than the silence it
+  // replaces. tests/ship_cannot_lie.mjs pins that order.
+  if (proseFlagPresent(args, 'notes')) {
+    for (const line of regradeNotesRefusal(taskId)) console.error(line);
+    process.exit(2);
+  }
   const regradeProse = resolveProse(args, ['summary', 'response']);
   const summaryArg = regradeProse.summary;
   // task 1002662: the builder's response to the prior round's findings — how
@@ -753,6 +763,17 @@ async function regradeMain() {
   // re-grade is the FIRST time this task actually ships. Fall back to the
   // task's stored value_summary so the merge commit + Discord #ship-news post
   // carry meaningful text even when --summary is omitted.
+  //
+  // AND IT NEVER REACHES THE TASK ROW — task 1003702's acceptance 3 asked this
+  // question; the answer is a real, separate defect, filed as task 1003817.
+  // `summary` from here feeds the grader prompt, the merge commit message and
+  // the PR title/body, and NOTHING writes it back to tasks.value_summary. All
+  // three candidate write paths were read and ruled out: publish-branch accepts
+  // value_summary but uses it only for PR text; PATCH /tasks/:id does not accept
+  // the field at all; the claim-resolve route is the sole writer and a re-grade
+  // has no claim (which is why claimLike is synthesized above). Fixing it needs
+  // a server route change, so it is deliberately NOT folded into this CLI fix.
+  // tests/ship_cannot_lie.mjs pins both halves of that so the answer cannot rot.
   const summary = summaryArg || task.value_summary || '';
 
   // The grader helpers want a claim-like object for touches[] (preflight's
@@ -848,6 +869,11 @@ async function regradeMain() {
     card: {
       title: task.title,
       valueSummary: summary,
+      // Empty by design, not by omission (task 1003702). A re-grade takes no
+      // --notes at all now — it is refused above — so there are none from THIS
+      // round to show. The first ship's notes are the durable record and live on
+      // the resolved claim; re-printing them here would suggest this round
+      // produced them.
       notes: '',
       files: committedFiles,
       baseline: graderBaseline,

package/scripts/gds/ship-honesty.js

@@ -143,8 +143,61 @@ function smokeGateMessages(taskId) {
   };
 }
 
+// ---- --regrade must not swallow --notes (task 1003702) ----------------------
+//
+// THE THIRD WAY TO LOSE THE BUILDER'S PROSE, and the reason this lives in the
+// prose-loss file rather than beside regradeMain. `--regrade` resolves only
+// `summary` and `response`, so `--notes` parsed as an unknown flag, produced no
+// error, and vanished. A builder answering a "no evidence in the notes" blocker
+// passed it again in --notes, saw the ship run, and got the identical finding
+// back marked unanswered — with nothing anywhere saying why.
+//
+// AND THE FIX IS A REFUSAL, NOT A PERSIST, because the premise the bug was filed
+// under is wrong in the builder's favour: the panel NEVER reads ship notes, on a
+// first ship or a re-grade. modules/grading/grader-prompt.js buildPrompt() puts
+// the task row, the VALUE SUMMARY, the changed files, the diffstat and the diff
+// in the prompt and nothing else, and the workers get the same bundle. So
+// storing the notes would have fixed the silence and none of the substance: the
+// builder would pass --notes, watch it save, and STILL get "unanswered" — a
+// worse failure, because now it looks like it worked.
+//
+// The two channels that do reach the panel are named in the refusal: --response
+// (fenced into the prior-round block, task 1002662) and the DIFF itself, which
+// is why the workaround that actually worked on task 1003698 was committing the
+// evidence as a file. Nothing is written and nothing is lost: the first ship's
+// notes stay the durable ledger record, which is the one thing --notes on a
+// re-grade could legitimately have meant.
+function proseFlagPresent(args, name) {
+  const list = Array.isArray(args) ? args : [];
+  return list.some((a) => a === `--${name}` || String(a).startsWith(`--${name}=`)
+    || a === `--${name}-file` || String(a).startsWith(`--${name}-file=`));
+}
+
+// Pure so the refusal's WORDING is testable — a message that fails to name the
+// alternative is the same dead end with an error code on it.
+function regradeNotesRefusal(taskId) {
+  return [
+    '--regrade does not take --notes, and your notes have NOT been saved or graded.',
+    '',
+    'The grader never reads ship notes — not on a re-grade, and not on the first ship.',
+    'The panel is given the task, your VALUE SUMMARY, the changed files and the diff.',
+    'So notes cannot answer a finding, and silently keeping them would only look like it had.',
+    '',
+    'Put the evidence where the panel can actually see it:',
+    `  --response "..."   answers the prior round's findings; it rides to the panel fenced.`,
+    `  --response-file <path>   the safe form for prose (a shell eats backticks in an inline value).`,
+    '  the DIFF           commit the proof — a test, a dry-run log, a session-log file.',
+    '                     The panel reads the committed diff and can Read every changed file.',
+    '',
+    `  node scripts/gds/ship.js ${taskId} --regrade --response-file notes.md`,
+    '',
+    "The first ship's notes stay the durable record; nothing you wrote earlier was lost.",
+  ];
+}
+
 module.exports = {
   resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages,
+  proseFlagPresent, regradeNotesRefusal,
   _resetForTest: () => { shipProgress = { stage: 'preflight', taskId: null }; },
   _peekForTest: () => shipProgress,
 };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.645'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.647'; // 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('dev-box'); log.info('mounted');