@bongos/core 1.19.932 → 1.19.933

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.932",
-  "core_contract": "1.19.932",
-  "source_commit": "d2abbbb5631c1442fe5699f12039542a2044b84b",
+  "core_version": "1.19.933",
+  "core_contract": "1.19.933",
+  "source_commit": "3ad7b40118fcad3d4ac54b7c18e2ccc36d3e7a6d",
   "source_ref": "HEAD",
-  "built_at": "2026-09-21T02:43:33.416Z",
+  "built_at": "2026-09-21T02:57:49.721Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 511,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2862,
-  "tree_sha256": "639ee94b251255963e185eb8bc26d41ced7c87d5f0e72931acdf76dfb644891a",
+  "tree_sha256": "0c42a78bb3f237ab0facaf9fee094236c11c19543f7a3deb08d9616db322b27f",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2677,7 +2677,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7b02e10e565ac40dfc301149ac22736254d6fa96db7ea43872660dd2ab4020da"
+      "sha256": "5c21da8442aac7c6bc744635d1e082b89e321f25743bcc0b7d6dbc659a7b7f31"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7967,12 +7967,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "bf02d212a688052c5330c5169c16cd5f8cc895f84e56931df8ee629503a2fe20"
+      "sha256": "23de484d5a08f0dc84ce22fb8d7671a3efbd0273ce878c1a63d6848fc1796273"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "6ea8cd02b01a88bbfe602657ca27a4dad0505cad4ee712f097e17b7794514214"
+      "sha256": "0a74e65c4330c8d5b855b5bc751fea858b493130d5c205f49d213bfe674a46b7"
     },
     {
       "path": "public-docs/index.html",
@@ -8322,7 +8322,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "37cbab033c9ba88ae557e8569fcabca9d361b4e26fc335ed5adacddf245ab38d"
+      "sha256": "2209cc2ca1476efc0af464e6e58ae87c5a5dc8d5a70b2ad067867adbfe0aab06"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -9522,7 +9522,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "9bf33575839de86c1361f78dab69f0e4607db37bbb473a38928fa6c03447d31e"
+      "sha256": "d736a08f303447e3889c478b0a22d6e9ae96e326f75bd57bead6199ffc23f1c5"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9972,7 +9972,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "04b4e543718c564aa70a79b83a60202eaac5f0c30b5fcaae897bdf29f9e9653a"
+      "sha256": "3870b0f3400bed8195ac80fa450e8e1f10d5b4f559f46b131db7b633669fc95f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14167,17 +14167,17 @@
     {
       "path": "tests/update_subscription_engine.mjs",
       "mode": "0000644",
-      "sha256": "a2ba2dca70c6192313c7a64e6dcbb5d7f9dbf2dc457592e643f1d59154b2665f"
+      "sha256": "a083174381f10d1cd19795b43580a3113c4f758e4b98da1f7c8e389429cb6a26"
     },
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "3fe93c21665f73be4e2c17198af35626b2a3a045eceadda8827195910ad64e4c"
+      "sha256": "8bd1c116b5459b54a847208c01669159414fed17b3704d621e1dc5acfb00f255"
     },
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",
-      "sha256": "2e1fd181c580070c3625035d39d038c137dbf04c6c8e74132977b877c0d73c76"
+      "sha256": "47698d59e0f728fee112bc55989a2271293007e4fba2b3447a0d2e4a3a93401a"
     },
     {
       "path": "tests/verify_task_guard.mjs",

package/docs/module-api-changelog.md

@@ -2338,5 +2338,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.930 with no explicit bump. run 35551146764. (task 1002620)
   1.19.932 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.931 with no explicit bump. run 35555080510. (task 1002620)
+  1.19.933 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.932 with no explicit bump. run 35555853466. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.932",
+  "version": "1.19.933",
   "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/claude-materialize.js

@@ -32,7 +32,7 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
 const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
-const { isCorePackageName } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
+const { isCorePackageName, CORE_PACKAGE_NAMES } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
 const { renderInstanceClaudeMd } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
 
 // script basename (e.g. "ship.js") → dedicated bongos verb, for verbs that map to a bare script with
@@ -630,11 +630,19 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
     summary.notes.push('no .instance-skills.json provenance in .claude/skills/ yet, so nothing was withdrawn — this run records it; a later run can withdraw the skills of a module that has since been disabled.');
   }
   // Record what landed, so the NEXT run can withdraw what this one placed.
-  if (!dryRun && overwrite) {
+  //
+  // REPORTED on a dry run, written only on a real one — the same split the starter CLAUDE.md
+  // below already uses. writtenPaths is a "what this run rewrites" list, and a dry run's job is
+  // to preview exactly that: upgrade.js asks for one to decide which dirty paths its clean-tree
+  // pre-flight may ignore (task 1004122), so a generated file missing from the preview is a file
+  // the pre-flight halts on and the real run then rewrites anyway.
+  if (overwrite) {
     const names = Object.keys(landedNow).sort();
     const manifest = { _doc: 'GENERATED by scripts/gds/claude-materialize.js (task 1003632): the module-declared skills a materialize landed in this instance. It is the provenance record that lets a later run WITHDRAW a skill whose module has since been disabled — a name absent from here is never deleted, so a hand-written skill is safe. Commit it; do not hand-edit.', skills: Object.fromEntries(names.map((n) => [n, landedNow[n]])) };
-    fs.mkdirSync(skillsDest, { recursive: true });
-    fs.writeFileSync(path.join(skillsDest, INSTANCE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
+    if (!dryRun) {
+      fs.mkdirSync(skillsDest, { recursive: true });
+      fs.writeFileSync(path.join(skillsDest, INSTANCE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
+    }
     addWritten(path.join('.claude/skills', INSTANCE_SKILLS_MANIFEST));
   }
 
@@ -741,6 +749,41 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   return summary;
 }
 
+// materializeWillRewrite — the instance-relative paths a materialize WOULD rewrite here, changing
+// nothing. `bongos upgrade` asks before it starts, to decide which dirty paths its clean-tree
+// pre-flight may waive.
+//
+// THE WEDGE THIS EXISTS FOR (task 1004122). The upgrade's materialize step rewrites `.claude/`
+// from the new core on EVERY bump, so after an upgrade that did not commit it — one from before
+// task 1003957, or any run without --commit-pin — the instance carries ~40 modified
+// `.claude/skills/*` files that nobody edited. upgrade.js's clean-tree pre-flight then read them
+// as a human's uncommitted work and refused, so the instance took exactly one upgrade and stuck:
+// `test4` (instance 11) failed its Deploy-page upgrade this way, and provision-core-upgrade.js
+// passes --commit-pin but NOT --force, so the button stayed dead until someone committed by hand.
+//
+// Asking materializeClaude what it WOULD write is a real provenance answer, not a path
+// allow-list: the set is derived from the core actually installed here, and every path in it
+// is one the materialize step overwrites unconditionally a few seconds later. Whatever those files hold right
+// now is discarded either way, so refusing on them protects nothing and stops every future
+// update. A path materialize would NOT touch — an owner's own skill, a dirty migration, a
+// half-finished edit — is absent from the set and still halts the bump, which is the whole
+// safety property. Under --commit-pin the same paths come back from that step as persistPin's
+// artifactPaths and are committed, so the tree ends clean and the next upgrade needs none of this.
+//
+// Probed against the core on disk NOW, not the target: the target is not installed yet, and the
+// two ship the same `.claude/` surface. Fail-soft — a materialize that throws (no core
+// installed, an unreadable tree) returns nothing and the pre-flight is as strict as it ever was.
+function materializeWillRewrite({ instanceDir, coreRoot, materialize = materializeClaude }, err = console.error) {
+  try {
+    const root = coreRoot || path.join(instanceDir, 'node_modules', CORE_PACKAGE_NAMES[0]);
+    const sum = materialize({ coreRoot: root, instanceDir, dryRun: true, log: () => {} });
+    return (sum && Array.isArray(sum.writtenPaths)) ? sum.writtenPaths : [];
+  } catch (e) {
+    err(`  ! could not preview the .claude/ materialization (${e && e.message ? e.message : e}) — pre-flight will treat every dirty path as a human's work.`);
+    return [];
+  }
+}
+
 // ---- the dev checkout: module-owned skills materialised INTO the core (task 1003330, ADR 0224) ----
 // materializeClaude's self-copy guard is right for init/upgrade (instance == core is a no-op),
 // but Claude Code discovers only .claude/skills/ at the project root, so a builder working IN
@@ -850,4 +893,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+module.exports = { scriptToVerb, bongosify, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/scripts/gds/upgrade.js

@@ -129,11 +129,13 @@ function restorePin(instanceDir, depString, fsImpl = fs) {
 
 // ---- steps (each injectable for tests) --------------------------------------
 
-function gitTreeClean(instanceDir, run = spawnSync) {
+// `ignore` is waived (it comes from — and is argued for in — claude-materialize.js materializeWillRewrite, task 1004122); every OTHER dirty path still halts the bump.
+function gitTreeClean(instanceDir, run = spawnSync, ignore = []) {
   const r = run('git', ['status', '--porcelain'], { cwd: instanceDir, encoding: 'utf8' });
   if (!r || r.error || r.status !== 0) return { ok: false, reason: 'git status failed (not a git repo?)' };
-  const dirty = (r.stdout || '').trim();
-  return { ok: dirty === '', dirty };
+  const skip = new Set(ignore), all = (r.stdout || '').split('\n').filter((l) => l.trim());
+  const kept = all.filter((l) => !skip.has(l.slice(3).trim()));
+  return { ok: !kept.length, dirty: kept.join('\n'), ignored: all.length - kept.length };
 }
 
 // ---- persisting the pin (task 1002712) --------------------------------------
@@ -1114,8 +1116,11 @@ async function runUpgrade(opts, deps = {}) {
 
   // 1. pre-flight: clean tree (so the pin change is reviewable + revertable) + module compatibility.
   if (!opts.force) {
-    const tree = gitTreeClean(instanceDir, run);
+    // Step 5's own output is not dirt (task 1004122) — but only when step 5 is going to run.
+    const preview = opts.skipMaterialize ? () => [] : (deps.willRewrite || require('./claude-materialize').materializeWillRewrite);
+    const tree = gitTreeClean(instanceDir, run, preview({ instanceDir, materialize }, err));
     if (!tree.ok) return { ok: false, error: `working tree not clean — commit/stash first, or pass --force.\n${tree.dirty || tree.reason || ''}` };
+    if (tree.ignored) log(`  • pre-flight: ignored ${tree.ignored} dirty path(s) this upgrade rewrites from the core (.claude/ materialization)${opts.commitPin ? ' — they are committed with the pin' : ' — pass --commit-pin to commit them'}.`);
   }
   const mods = preflightModules({ instanceDir, targetVersion }, deps);
   log(`  ✓ pre-flight: ${mods.note}`);

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.932'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.933'; // 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');

package/tests/update_subscription_engine.mjs

@@ -356,12 +356,74 @@ test('every commitPin call site in the lane decides about push', () => {
   }
 });
 
-test('the direct-upgrade fallback withholds --commit-pin unless the mode is push', () => {
+test('the direct-upgrade fallback asks pinFlagsFor rather than deciding inline', () => {
   const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
-  // --commit-pin makes upgrade.js commit AND push, so the fallback has to gate it too — the
-  // policy must not depend on which engine the instance's core happened to support.
-  assert.match(src, /if \(canCommitPin && pinMode === 'push'\) upArgs\.push\('--commit-pin'\)/,
-    'the fallback path would push a co-tenant pin through upgrade.js instead of the lane');
+  // The fourth version of this assertion. It used to pin the inline `if` verbatim, which froze
+  // the bug of task 1004122 in place: the line was correct about NOT pushing a co-tenant pin and
+  // wrong about how, and a test that quotes an expression can only ever confirm it is still there.
+  assert.match(src, /upArgs\.push\(\.\.\.pinFlagsFor\(\{ pinMode, canCommitPin, canPinNoPush \}\)\)/,
+    'the fallback decides its pin flags inline again, where no test can reach them');
+});
+
+// ---------------------------------------------------------------------------
+// 8b. pinFlagsFor — the fallback's pin policy, and the cross-file contract (task 1004122)
+//
+// go-live.js is the PREFERRED engine and the fallback must not apply a weaker policy just
+// because an instance's core could not support it. It did: the fallback withheld --commit-pin
+// on `local-commit`, so upgrade.js left the `.claude/` it had just rewritten uncommitted, the
+// lane's own net can stage nothing but PIN_FILES, and the next sweep halted on those files
+// forever. The instance took exactly one upgrade and then needed a human.
+// ---------------------------------------------------------------------------
+
+test('pinFlagsFor: local-commit commits the bump WITHOUT pushing — the fix for the one-upgrade wedge', () => {
+  assert.deepEqual(
+    S.pinFlagsFor({ pinMode: 'local-commit', canCommitPin: true, canPinNoPush: true }),
+    ['--commit-pin', '--pin-no-push'],
+    'upgrade.js commits the pin AND the .claude/ it materialized, and pushes nothing');
+});
+
+test('pinFlagsFor: push keeps --commit-pin alone, leave-dirty still commits nothing', () => {
+  assert.deepEqual(S.pinFlagsFor({ pinMode: 'push', canCommitPin: true, canPinNoPush: true }), ['--commit-pin']);
+  // --pin-no-push WITHOUT --commit-pin: nothing is committed, and upgrade.js's pull-deploy alarm
+  // drops to a note, because on this target no reset is coming to revert the bump.
+  assert.deepEqual(S.pinFlagsFor({ pinMode: 'leave-dirty', canCommitPin: true, canPinNoPush: true }), ['--pin-no-push']);
+});
+
+test('pinFlagsFor: an old core that lacks --pin-no-push gets NOTHING, never the lone --commit-pin', () => {
+  // parseArgs silently ignores an unknown flag, so the pair would degrade to a bare --commit-pin
+  // and push the bump into the CUSTOMER's repo. Fail closed: keep today's behaviour instead.
+  assert.deepEqual(S.pinFlagsFor({ pinMode: 'local-commit', canCommitPin: true, canPinNoPush: false }), []);
+  assert.deepEqual(S.pinFlagsFor({ pinMode: 'leave-dirty', canCommitPin: true, canPinNoPush: false }), []);
+  // …and a core with no --commit-pin at all is never asked to commit.
+  for (const mode of ['push', 'local-commit', 'leave-dirty']) {
+    assert.ok(!S.pinFlagsFor({ pinMode: mode, canCommitPin: false, canPinNoPush: true }).includes('--commit-pin'), `mode ${mode}`);
+  }
+});
+
+test('pinFlagsFor mirrors go-live.js upgradeCommand() mode for mode', () => {
+  // The cross-file contract, pinned at the source in the same way GO_LIVE_REQUIRED is: go-live
+  // builds a command STRING on a box, so the two can only be compared through its source.
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'go-live.js'), 'utf8');
+  const body = src.slice(src.indexOf('function upgradeCommand('));
+  const commitPinModes = /\.\.\.\(mode === 'leave-dirty' \? \[\] : \['--commit-pin'\]\)/.test(body);
+  const noPushModes = /\.\.\.\(mode === 'push' \? \[\] : \['--pin-no-push'\]\)/.test(body);
+  assert.ok(commitPinModes && noPushModes, 'go-live.js upgradeCommand() moved — re-derive pinFlagsFor from it');
+  for (const mode of ['push', 'local-commit', 'leave-dirty']) {
+    const goLive = [
+      ...(mode === 'leave-dirty' ? [] : ['--commit-pin']),
+      ...(mode === 'push' ? [] : ['--pin-no-push']),
+    ];
+    assert.deepEqual(
+      S.pinFlagsFor({ pinMode: mode, canCommitPin: true, canPinNoPush: true }), goLive,
+      `mode ${mode}: the fallback applies a different pin policy from the engine it stands in for`);
+  }
+});
+
+test('supportsPinNoPush probes the file, and is fail-closed on anything it cannot read', () => {
+  assert.equal(S.supportsPinNoPush('/x/upgrade.js', () => 'usage: --commit-pin --pin-no-push'), true);
+  assert.equal(S.supportsPinNoPush('/x/upgrade.js', () => 'usage: --commit-pin'), false, 'a core that predates the flag');
+  assert.equal(S.supportsPinNoPush(null, () => '--pin-no-push'), false);
+  assert.equal(S.supportsPinNoPush('/x/upgrade.js', () => { throw new Error('ENOENT'); }), false);
 });
 
 // ---------------------------------------------------------------------------

package/tests/upgrade.mjs

@@ -171,6 +171,58 @@ t('guard: dirty tree refuses (unless --force)', async () => {
   assert.match(res.error, /not clean/);
 });
 
+// task 1004122 — the pre-flight must not refuse on what step 5 is about to overwrite anyway.
+// An instance upgraded before task 1003957 carries ~40 modified `.claude/skills/*` nobody
+// edited, and provision-core-upgrade.js (the Deploy page) passes --commit-pin but NOT --force,
+// so the button stayed dead forever. The waiver is scoped to what a dry-run materialize on THIS
+// instance says it rewrites; anything else still halts.
+t('guard: a dirty tree that is ONLY this upgrade\'s own .claude/ materialization proceeds', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer();
+  const dryRuns = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, healthCheck: false, skipMigrate: true },
+    {
+      log: () => {}, err: () => {},
+      run: fakeRun([], { dirty: ' M .claude/skills/builder-end/SKILL.md\n M .claude/settings.json', installTo: '1.15.0', dir }),
+      materialize: (a) => { if (a.dryRun) dryRuns.push(a); return { skills: 2, writtenPaths: ['.claude/skills/builder-end/SKILL.md', '.claude/settings.json'] }; },
+      regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: '', pgDatabase: '',
+    }
+  );
+  assert.equal(res.ok, true, 'the bump runs, and step 5 rewrites those same files');
+  assert.equal(dryRuns.length, 1, 'the pre-flight previewed the materialization exactly once');
+  assert.equal(dryRuns[0].instanceDir, dir);
+  assert.ok(dryRuns[0].coreRoot.endsWith(join('node_modules', '@bongos', 'core')), 'against the core the instance has NOW — the target is not installed yet');
+});
+
+t('guard: a dirty tree with anything ELSE in it still refuses', async () => {
+  const dir = scratchConsumer();
+  const res = await u.runUpgrade({ to: '1.15.0', instance: dir }, {
+    log: () => {}, err: () => {},
+    run: fakeRun([], { dirty: ' M .claude/settings.json\n M migrations/core_253_wip.sql' }),
+    materialize: () => ({ skills: 1, writtenPaths: ['.claude/settings.json'] }),
+  });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /not clean/);
+  assert.match(res.error, /migrations\/core_253_wip\.sql/, 'and it names the path that is genuinely a human\'s');
+  assert.ok(!res.error.includes('.claude/settings.json'), 'without re-listing the half it waived');
+});
+
+t('guard: --skip-materialize waives nothing — step 5 rewrites nothing, so every dirty path is real', async () => {
+  const dir = scratchConsumer();
+  let asked = 0;
+  const res = await u.runUpgrade({ to: '1.15.0', instance: dir, skipMaterialize: true }, {
+    log: () => {}, err: () => {},
+    run: fakeRun([], { dirty: ' M .claude/settings.json' }),
+    materialize: () => { asked += 1; return { skills: 1, writtenPaths: ['.claude/settings.json'] }; },
+  });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /not clean/);
+  assert.equal(asked, 0, 'and materialize was never even asked');
+});
+
 t('guard: already on the target refuses (unless --force)', async () => {
   const dir = scratchConsumer({ installed: '1.15.0' });
   const res = await u.runUpgrade({ to: '1.15.0', instance: dir }, { log: () => {}, err: () => {}, run: fakeRun([], { dirty: '' }) });

package/tests/upgrade_persist_pin.mjs

@@ -365,11 +365,10 @@ test('real git: an owner edit outside the generated files is never swept into th
 // when anything but the pin is dirty, which is simultaneously the `failed=1` on a successful
 // upgrade and the next sweep's permanent halt.
 
-const { materializeClaude } = require('../scripts/gds/claude-materialize.js');
+const { materializeClaude, materializeWillRewrite } = require('../scripts/gds/claude-materialize.js');
 
 // A minimal core package: just the .claude/ tree materialize copies out of it.
-function scratchCore(version) {
-  const dir = mkdtempSync(join(tmpdir(), 'upgrade-core-'));
+function coreAt(dir, version) {
   put(dir, 'package.json', JSON.stringify({ name: '@bongos/core', version }));
   put(dir, 'config/branding.json', JSON.stringify({ identity: {} }));
   put(dir, '.claude/skills/builder-end/SKILL.md', `# builder-end (core ${version})\n`);
@@ -378,6 +377,13 @@ function scratchCore(version) {
   put(dir, '.claude/hooks/stop.js', `// hook for ${version}\n`);
   return dir;
 }
+function scratchCore(version) {
+  return coreAt(mkdtempSync(join(tmpdir(), 'upgrade-core-')), version);
+}
+// The same tree where an instance really carries it — what materializeWillRewrite probes.
+function installCore(instanceDir, version) {
+  return coreAt(join(instanceDir, 'node_modules', '@bongos', 'core'), version);
+}
 
 // A scaffolded co-tenant that already TRACKS the .claude/ a previous materialize landed.
 function scratchCoTenant(version = '1.19.737') {
@@ -390,6 +396,7 @@ function scratchCoTenant(version = '1.19.737') {
   put(dir, 'package-lock.json', `lock ${version}\n`);
   put(dir, 'config/branding.json', JSON.stringify({ identity: {} }));
   put(dir, 'CLAUDE.md', 'the instance owns this\n');
+  put(dir, '.gitignore', 'node_modules/\n');
   materializeClaude({ coreRoot: scratchCore(version), instanceDir: dir, log: quiet });
   git(dir, 'add', '-A');
   git(dir, 'commit', '-q', '-m', 'scaffold');
@@ -477,3 +484,90 @@ test('adopt mode records nothing, so `init --adopt` never commits over what it r
   assert.ok(!sum.writtenPaths.includes('.claude/settings.json'));
   assert.equal(readFileSync(join(dir, '.claude/skills/builder-end/SKILL.md'), 'utf8'), 'the adopting project already had this\n');
 });
+
+// ── the fleet that was ALREADY wedged (task 1004122) ────────────────────────────
+//
+// Task 1003957 above stops an upgrade CREATING the dirt. It does nothing for the instances
+// that were upgraded before it shipped: every one of them still carries ~40 modified
+// `.claude/skills/*` files nobody edited, and the clean-tree pre-flight refuses on them. So
+// `test4` (instance 11) failed its Deploy-page upgrade on 2026-09-20 — provision-core-upgrade.js
+// passes --commit-pin but NOT --force, so the button stays dead until someone commits by hand.
+//
+// The fix is that the pre-flight stops counting a path THIS upgrade is about to overwrite as
+// evidence of anything. The set is not an allow-list: it is what a dry-run materialize against
+// the core actually installed here says it would write.
+
+test('gitTreeClean: an ignored path stops counting, and is reported rather than hidden', () => {
+  const dir = scratchCoTenant();
+  writeFileSync(join(dir, '.claude/skills/builder-end/SKILL.md'), 'rewritten by an earlier upgrade\n');
+  assert.equal(gitTreeClean(dir).ok, false, 'by default it is dirt like any other');
+  const t = gitTreeClean(dir, spawnSync, ['.claude/skills/builder-end/SKILL.md']);
+  assert.equal(t.ok, true);
+  assert.equal(t.ignored, 1, 'and the caller can say how many it waived');
+  assert.equal(t.dirty, '');
+});
+
+test('gitTreeClean: ignoring the materialized paths never waives anything else', () => {
+  const dir = scratchCoTenant();
+  writeFileSync(join(dir, '.claude/skills/builder-end/SKILL.md'), 'rewritten by an earlier upgrade\n');
+  put(dir, 'config/branding.json', 'the owner was here\n');
+  const t = gitTreeClean(dir, spawnSync, ['.claude/skills/builder-end/SKILL.md']);
+  assert.equal(t.ok, false, 'the owner edit still halts the bump');
+  assert.match(t.dirty, /config\/branding\.json/);
+  assert.ok(!t.dirty.includes('builder-end'), 'and only the materialized half was waived');
+  assert.equal(t.ignored, 1);
+});
+
+test('materializeWillRewrite: the set comes from the core the instance actually has', () => {
+  const dir = scratchCoTenant();
+  installCore(dir, '1.19.785');
+  const paths = materializeWillRewrite({ instanceDir: dir, materialize: materializeClaude }, quiet);
+  assert.ok(paths.includes('.claude/skills/builder-end/SKILL.md'));
+  assert.ok(paths.includes('.claude/settings.json'));
+  assert.ok(paths.includes('.claude/hooks/stop.js'));
+  assert.ok(paths.includes('.claude/skills/.instance-skills.json'), 'the provenance manifest is rewritten every run too');
+  assert.ok(!paths.includes('CLAUDE.md'), 'a file materialize writes only when ABSENT is not rewritten — the instance owns it');
+  assert.equal(git(dir, 'status', '--porcelain').stdout, '', 'and previewing it changed nothing on disk');
+});
+
+test('materializeWillRewrite: no core installed → no skill is waived, and a throw waives nothing at all', () => {
+  const dir = scratchCoTenant();
+  // Nothing to copy out of: materialize reports only the provenance record it rewrites anyway.
+  const paths = materializeWillRewrite({ instanceDir: dir, materialize: materializeClaude }, quiet);
+  assert.ok(!paths.some((p) => p.startsWith('.claude/skills/builder-')), 'no skill file is waived on the strength of a core that is not there');
+
+  // And an outright failure is fail-SOFT in the strict direction — an empty set plus a note.
+  const notes = [];
+  const boom = () => { throw new Error('unreadable core tree'); };
+  assert.deepEqual(materializeWillRewrite({ instanceDir: dir, materialize: boom }, (m) => notes.push(m)), []);
+  assert.equal(notes.length, 1, 'it says so rather than failing silently');
+  assert.match(notes[0], /unreadable core tree/);
+});
+
+test('real git: an instance wedged by a pre-1003957 upgrade unwedges itself on the next bump', () => {
+  const dir = scratchCoTenant();
+  sweep(dir, '1.19.737', '1.19.785', { artifactPaths: [] }); // the upgrade that left the mess
+  installCore(dir, '1.19.785');                              // …and the core it installed
+  assert.equal(gitTreeClean(dir).ok, false, 'today: the next `bongos upgrade` refuses here');
+
+  // What runUpgrade's pre-flight now does.
+  const rewritable = materializeWillRewrite({ instanceDir: dir, materialize: materializeClaude }, quiet);
+  assert.equal(gitTreeClean(dir, spawnSync, rewritable).ok, true, 'the bump is allowed to proceed');
+
+  // …and proceeding is what cleans it up: step 5 rewrites those same paths and persistPin commits them.
+  const { pin } = sweep(dir, '1.19.785', '1.19.786');
+  assert.equal(pin.committed, true);
+  assert.equal(git(dir, 'status', '--porcelain').stdout, '', 'one bump, no human hands, tree clean');
+});
+
+test('real git: a wedged instance with an owner edit beside the mess still refuses', () => {
+  const dir = scratchCoTenant();
+  sweep(dir, '1.19.737', '1.19.785', { artifactPaths: [] });
+  installCore(dir, '1.19.785');
+  put(dir, 'core_999_half_written.sql', '-- not finished\n');
+  const rewritable = materializeWillRewrite({ instanceDir: dir, materialize: materializeClaude }, quiet);
+  const t = gitTreeClean(dir, spawnSync, rewritable);
+  assert.equal(t.ok, false, 'a human really does need to look');
+  assert.match(t.dirty, /core_999_half_written\.sql/);
+  assert.ok(!t.dirty.includes('.claude/skills/builder-end'), 'the materialization half is still waived');
+});