@bongos/core 1.19.63 → 1.19.65

package/modules/ideas/module.json

@@ -4,6 +4,7 @@
   "description": "The idea inbox (capture, triage, criterion-proposal ratification) and the blockers queue — the methodology surfaces that feed the backlog. A core-domain module carved out of the GDS core in BV1.R78 (ADR 0093 §1); default-on because every instance captures ideas and tracks what's stuck on its owner. Registers the `ideas.capture` kernel PORT the discord #ideas inbound resolves (ADR 0093 §5 — retiring the temporary `captureIdea` doorway leak).",
   "coreVersion": "^1.8.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["inbox", "blockers"] },
   "provides": ["ideas.capture"],
   "consumes": []

package/modules/lifecycle/db.js

@@ -335,6 +335,30 @@ function singleRungPromotionError(oldRank, newRank) {
   };
 }
 
+// foldWorktreeName — task 1002522. The ONE normalization of an incoming
+// worktree_name, applied at every ingest point so the app guard
+// (shouldRefuseSessionClaim) and its DB backstop (core_204's index, keyed on
+// (creator_session_id, COALESCE(worktree_name, ''))) can never disagree about
+// which claims share a working tree.
+//
+// The index folds NULL to '' — so to Postgres an EMPTY-string name IS the
+// worktree-less group. The guard compared raw values, where '' !== null: it
+// waved through a ''-named claim beside a worktree-less one, and the INSERT
+// then failed the backstop with a 23505 the caller never earned. Whitespace-only
+// is the same case wearing a coat (`.claude/worktrees/<blank>` is the repo root,
+// not a tree), so it folds too, and surrounding whitespace is trimmed rather
+// than stored — an untrimmed name would key the index differently from the
+// trimmed one the guard compared.
+//
+// Fold ONCE, at ingest: claimTask/claimTasksBatch normalize before the INSERT,
+// so every stored name is already trimmed-or-NULL and the guard's comparison of
+// stored rows is exact. Pure + exported for DB-free tests.
+function foldWorktreeName(name) {
+  if (name == null) return null;
+  const trimmed = String(name).trim();
+  return trimmed === '' ? null : trimmed;
+}
+
 // disambiguateWorktreeName — V3.R51 (#270). Two simultaneously-ACTIVE claims
 // must never share a worktree_name: `.claude/worktrees/<name>` is a filesystem
 // path, and two live builders pointing at the same one would stomp each other.
@@ -2762,7 +2786,10 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     // which is what the overnight builder relies on. We hold FOR UPDATE on the
     // task row already; reading the active names inside the same txn is good
     // enough for the disambiguation to be stable for this insert.
-    let finalWorktreeName = worktreeName ?? null;
+    // task 1002522: fold ''/whitespace → NULL before anything keys on the name.
+    // core_204's index folds them together anyway (COALESCE(worktree_name, ''));
+    // normalizing here means the stored row matches what the guard compared.
+    let finalWorktreeName = foldWorktreeName(worktreeName);
     if (finalWorktreeName) {
       const { rows: activeNameRows } = await client.query(
         `SELECT worktree_name FROM claims
@@ -3121,8 +3148,12 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
         );
         reservedMigrationNumber = bumpRows[0].allocated;
       }
-      const worktreeName = worktreePrefix
-        ? `${worktreePrefix}-${t.id}`
+      // task 1002522: fold the prefix the same way a single claim's name is
+      // folded, so a blank/whitespace prefix yields worktree-less rows rather
+      // than names like "  -1234" that the index would key as distinct trees.
+      const foldedPrefix = foldWorktreeName(worktreePrefix);
+      const worktreeName = foldedPrefix
+        ? `${foldedPrefix}-${t.id}`
         : null;
       const rowCreatorSessionId = i === 0 ? (creatorSessionId ?? null) : null;
       try {
@@ -5546,6 +5577,7 @@ module.exports = {
   countShippedTasksForBuilder,
   singleRungPromotionError,
   disambiguateWorktreeName,
+  foldWorktreeName,
   updateTaskParallelSafe,
   updateTaskSecuritySensitive,
   updateTaskAutomationTag,

package/modules/lifecycle/module.json

@@ -4,6 +4,7 @@
   "description": "The build state machine — tasks · claims · versions · done-when criteria · goals · dependencies · the claim→ship→grade→credit lifecycle · override requests · the ship/confirm/promote orchestration · github-push + merge-lease + conflict-resolve + the publish reconciler. The LAST and most-coupled core domain carved out of the GDS core in BV1.R86 (ADR 0093 §1,§3, 02-module-map §4 — kept whole, never split). default-on; every instance runs the lifecycle. Registers the `lifecycle` kernel PORT (createTask · VOTABLE_TASK_STATUSES · classifyTaskKind · tallyPeerVotes + the work-tracking reads) that core read routes + the ideas/discord/autonomy modules resolve. As a transaction-participant it RESOLVES the `reward` + `onboarding` ports inside its claim/ship/confirm txns — but via resolveOptional (graceful, like sessions→reward), so consumes is empty: a vanilla instance without those modules degrades the credit/onboarding writes to best-effort no-ops, it does not fail.",
   "coreVersion": "^1.12.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": {
     "routes": ["tasks", "claims", "versions", "done-when", "goals", "dependencies", "gate-approvals", "analytics", "lifecycle"],
     "pollers": ["publish-reconciler"]

package/modules/lifecycle/routes/claims.js

@@ -80,13 +80,17 @@ function shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId, wo
     return { refuse: false, inFlightTaskId: null, inFlightTitle: null, reason: null };
   }
   const claims = Array.isArray(activeClaimsForSession) ? activeClaimsForSession : [];
-  const incomingTree = worktreeName == null ? null : worktreeName;
-  // Two claims share a WORKING TREE iff their worktree_names match, or both are
-  // null (a worktree-less clone — the single branch genuinely commingles).
-  const sameWorkingTree = (name) => {
-    const t = name == null ? null : name;
-    return t === incomingTree;
-  };
+  // task 1002522: fold through db.foldWorktreeName — the SAME normalization the
+  // INSERT applies — so this decision keys trees exactly the way core_204's
+  // backstop index does (it folds NULL and '' into one group via
+  // COALESCE(worktree_name, '')). Comparing raw values let a ''-named claim slip
+  // past the guard and then trip the index, refusing a claim on a task that was
+  // never taken.
+  const incomingTree = db.foldWorktreeName(worktreeName);
+  // Two claims share a WORKING TREE iff their folded worktree_names match — which
+  // includes both being worktree-less (a plain clone, whose single branch
+  // genuinely commingles).
+  const sameWorkingTree = (name) => db.foldWorktreeName(name) === incomingTree;
   // Defence in depth: only count claims that belong to THIS session, are genuinely
   // session-bound (a NULL-session row must never trip the block), AND would land in
   // the SAME working tree as the incoming claim.
@@ -122,7 +126,9 @@ async function gateOneActiveClaimPerSession(req, res, next) {
   // The incoming claim's working tree — the hazard boundary the guard keys on. A
   // second claim in a DIFFERENT worktree is safe (different branch); only a second
   // claim into the SAME tree (or off one worktree-less clone) commingles.
-  const worktreeName = req.body?.worktree_name ?? null;
+  // Folded (task 1002522) so the guard, the refusal message, and the row the
+  // INSERT will actually write all speak about the same tree.
+  const worktreeName = db.foldWorktreeName(req.body?.worktree_name);
   let activeClaimsForSession;
   try {
     activeClaimsForSession = await db.getActiveClaimsForSession(creatorSessionId);

package/modules/memory/module.json

@@ -4,6 +4,7 @@
   "description": "Per-builder session memory, the lexical recall/search retrieval layer (ADR 0060), and durable learnings. A core-domain module carved out of the GDS core in BV1.R72 (ADR 0091); default-on because every instance needs the build system's memory.",
   "coreVersion": "^1.5.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": {
     "routes": ["memory", "search", "learnings"]
   },

package/modules/onboarding/module.json

@@ -4,6 +4,7 @@
   "description": "The newcomer ADMISSION + ORIENTATION domain — the public access-request → Archon-approval gate, the server-ticked onboarding state machine (the 'Path into the City' checklist that graduates a Xenos to Thetes), the friction analyzer (feedback-without-asking on consented onboarding transcripts), and the evergreen newcomer-chore restock (a fresh first-builder task is always waiting). A core-domain module carved out of the GDS core in BV1.R81 (ADR 0093 §1); default-on because every instance onboards its own builders. The access-requests admission routes mount here; the core lifecycle (db.js claim/ship), auth callbacks, and the me/builders profile readers resolve the `onboarding` kernel PORT for the state-machine + restock surface they need — never importing the module.",
   "coreVersion": "^1.9.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["onboarding"] },
   "provides": ["onboarding"],
   "consumes": []

package/modules/platform-identity/module.json

@@ -8,6 +8,7 @@
   "origin": "Cloud Bongos platform (cloudbongos.com)",
   "license": "AGPL-3.0",
   "maintainer": "Cloud Bongos maintainers",
+  "maintenance": { "status": "core-maintained" },
   "contributes": {
     "routes": ["sso", "projects", "my-projects", "scouting"],
     "migrations": true,

package/modules/provisioning/module.json

@@ -8,6 +8,7 @@
   "origin": "Off the Boats (the first Cloud Bongos instance, amazonprimea.com)",
   "license": "AGPL-3.0",
   "maintainer": "Off the Boats maintainers",
+  "maintenance": { "status": "core-maintained" },
   "contributes": {
     "routes": ["provisioning"],
     "migrations": true

package/modules/security/module.json

@@ -4,6 +4,7 @@
   "description": "The red-team / vulnerability-report intake and the bounty payout system (rank-gated Metic+): the /builder-redteam skill files a report, the Archon dashboard adjudicates (confirm/dispute/fix/link-fix), and the env-aware bounty table sets the per-severity drachmae payout. A core-domain module carved out of the GDS core in BV1.R79 (ADR 0093 §1; 02-module-map §5 — security-the-FEATURE, NOT security-the-property, which stays kernel). default-on because every instance can take red-team reports. Registers the `security` kernel PORT the core /public/bounty-table resolves for the payout schedule. Also owns the scan-before-install surface (goal 1000055): the artifact-scan engine (quarantine/manifest/mirror) and the security_tool_scans record — POST Metic+, GET every rank.",
   "coreVersion": "^1.8.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["reports", "scans"], "migrations": true },
   "provides": ["security"],
   "consumes": []

package/modules/sessions/module.json

@@ -4,6 +4,7 @@
   "description": "The session-records corpus + its data plane (POST /sessions upload, the Archon-gated cross-builder /sessions/search + /sessions/:id deep-dive), the BFG 'read-the-room' cross-builder scorer (ADR 0026 §6B), and the session-pulse / stale-claim heartbeat helpers. A core-domain module carved out of the GDS core in BV1.R82 (ADR 0093 §1); default-on because every instance records its builders' sessions for the BFG. Like the memory module, sessions registers no port — core never calls back into it: the ship-time digest write is an HTTP POST to the module's own /sessions route, and the only outward dependency is the economy `reward` kernel PORT it resolves (session token reward + sumCreditsForTasks) at upload time.",
   "coreVersion": "^1.10.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["sessions"], "pollers": ["session-reward-reconcile"] },
   "provides": [],
   "consumes": []

package/modules/status-ui/module.json

@@ -4,6 +4,7 @@
   "description": "The public build-status dashboard served at status.<apex> (status.amazonprimea.com) — the live up/down banner, version-progress rollups, cost summary, recent ships, leaderboard, and the ecosystem fingerprint, all polling the read-only /api/gds/public/* surface every 60s. A WEB-SURFACE core-domain module carved out of the GDS core in BV1.R84 (ADR 0093 §1; 02-module-map §6 — a web surface is first-class). default-on: a Cloud Bongos instance ships its status page like it ships its hall. Registers no port and contributes no routes — it declares a webSurface (host prefix + static dir) the loader hands serve-internal, which serves the module's public/ dir on the matching host exactly as it served public-status/ before. The public read endpoints it renders stay SHARED core in routes/public.js (the hall + the off-box mirror read them too).",
   "coreVersion": "^1.11.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": {
     "webSurfaces": [
       { "host": "status.", "dir": "public" }

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.63",
+  "version": "1.19.65",
   "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/module.js

@@ -34,7 +34,10 @@
 //     because a brand-new module is never on the ALLOWLIST until it is
 //     accepted (§6); that omission must not read as "denied content." Also
 //     requires the manifest to declare an AGPL-3.0 license (inbound = outbound,
-//     ADR 0107 §4 — no CLA). On a pass, `--sign-off "Name <email>"` records a
+//     ADR 0107 §4 — no CLA) and a `maintenance` posture (ADR 0107 §7 / ADR
+//     0166 — core-maintained, or maintained by a named maintainer; a module
+//     already deprecated/orphaned cannot be submitted INTO the catalog).
+//     On a pass, `--sign-off "Name <email>"` records a
 //     lightweight DCO-style affirmation (own work, licensed AGPL-3.0 — never a
 //     copyright-assignment CLA) to modules/<key>/.upstream-signoff.json.
 //
@@ -54,7 +57,8 @@ const path = require('node:path');
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const MODULES_DIR = path.join(REPO_ROOT, 'modules');
 
-const { validateManifest, assertValidManifest, KEY_RE } = require('../../src/module-loader/manifest-schema');
+const { validateManifest, assertValidManifest, KEY_RE, SUNSET_STATUSES } = require('../../src/module-loader/manifest-schema');
+const { parseVersion, cmp } = require('../../src/module-loader/semver');
 const loader = require('../../src/module-loader/loader');
 const { resolveModules, MODULE_REGISTRY, NEUTRAL_PATH, INSTANCE_PATH } = require('../../src/modules');
 // The public-mirror publish boundary (ADR 0098) — REUSED, never re-typed, for
@@ -115,6 +119,11 @@ function buildManifest(key, { core = coreVersion() } = {}) {
     origin: 'TODO: the instance/project this module was built in',
     license: 'AGPL-3.0',
     maintainer: 'TODO: who to credit/contact if this module is upstreamed',
+    // Upkeep posture (ADR 0107 §7 / ADR 0166). Scaffolded as `maintained`
+    // because a brand-new module's author IS its maintainer — the honest
+    // default. Change it to `core-maintained` only if the core team has agreed
+    // to own it, and to `deprecated`/`orphaned` (with a path) when that changes.
+    maintenance: { status: 'maintained' },
     contributes: { routes: [key] },
   };
 }
@@ -191,13 +200,51 @@ kernel seams (\`api.registerProvider\` / \`api.resolve\` / \`api.on\` / \`api.em
 `;
 }
 
+// Has the core advanced past a deprecated module's declared removal version?
+// `removeAfter: "1.12.0"` means "may be deleted once core is ABOVE 1.12.0".
+function isPastRemoveAfter(maintenance, core) {
+  const after = maintenance && maintenance.removeAfter;
+  const a = parseVersion(after);
+  const c = parseVersion(core);
+  return !!(a && c && cmp(c, a) > 0);
+}
+
+// One line of "who do I chase about this?" for a row, from its maintenance block
+// (ADR 0166). Shared by cmdUpgrade and upgrade.js's real-bump pre-flight so both
+// surfaces say the same thing about the same module.
+function formatMaintenanceHint(row = {}) {
+  const m = row.maintenance;
+  if (!m || !m.status) {
+    return 'no maintenance declared — nobody is on the hook for this module (ADR 0166: declare a `maintenance` block)';
+  }
+  const parts = [`maintenance: ${m.status}`];
+  if (m.status === 'maintained') parts.push(`maintainer ${row.maintainer || '(unnamed!)'}`);
+  if (m.status === 'core-maintained') parts.push('core-maintained — fixing this is the core\'s job');
+  if (m.successor) parts.push(`superseded by "${m.successor}"`);
+  if (m.removeAfter) parts.push(`removable after core ${m.removeAfter}`);
+  if (m.note) parts.push(m.note);
+  return parts.join('; ');
+}
+
 // Decide compatibility from rows (pure — tests drive it with injected rows).
-// A row: { key, coreVersion, enabled, satisfied }. BLOCKING = an enabled module
-// that does not satisfy the core (fail-closed). A disabled mismatch is a warning.
+// A row: { key, coreVersion, enabled, satisfied, maintenance?, maintainer? }.
+//
+// BLOCKING = an enabled module that does not satisfy the core (fail-closed).
+// WARNINGS = a DISABLED mismatch. These are not cosmetic: an accepted catalog
+// module ships `default: false` (ADR 0107 §6), so EVERY rotted catalog entry
+// lands in this bucket. Dropping warnings on the floor is exactly how "the
+// catalog fills with silently-broken entries" happens (ADR 0107 §7) — every
+// caller must surface them, even though none of them block.
+// DEPRECATIONS = modules whose own manifest says they are on the way out;
+// EXPIRED = deprecated modules the core has already advanced past `removeAfter`
+// (they are due for deletion, not just a label).
 function evaluateUpgrade({ rows = [], errors = [], core } = {}) {
   const blocking = rows.filter((r) => r.enabled && !r.satisfied);
   const warnings = rows.filter((r) => !r.enabled && !r.satisfied);
-  return { ok: blocking.length === 0, blocking, warnings, rows, errors, core };
+  const deprecations = rows.filter((r) => r.maintenance && SUNSET_STATUSES.includes(r.maintenance.status));
+  const expired = deprecations.filter((r) => isPastRemoveAfter(r.maintenance, core));
+  const undeclared = rows.filter((r) => !r.maintenance || !r.maintenance.status);
+  return { ok: blocking.length === 0, blocking, warnings, deprecations, expired, undeclared, rows, errors, core };
 }
 
 // ---------------------------------------------------------------------------
@@ -261,12 +308,20 @@ function gatherUpgrade({ modulesDir = MODULES_DIR, core = coreVersion(), env = p
   try { enabled = resolveModules({ neutral, instance, env, envPrefix: prefix, registry }); }
   catch { /* a malformed config shouldn't crash the pre-check; treat all as disabled */ }
 
+  // Maintenance posture travels with the row (ADR 0166) so both the pre-check
+  // printout and the real bump can say WHO owns a module that no longer fits —
+  // an incompatibility with no owner named is the orphaning failure itself.
+  const upkeep = (manifest) => ({
+    maintenance: (manifest && manifest.maintenance) || null,
+    maintainer: (manifest && manifest.maintainer) || null,
+  });
+
   const rows = [];
   for (const { key, manifest } of loaded) {
-    rows.push({ key, coreVersion: manifest.coreVersion, enabled: enabled[key] === true, satisfied: true });
+    rows.push({ key, coreVersion: manifest.coreVersion, enabled: enabled[key] === true, satisfied: true, ...upkeep(manifest) });
   }
   for (const { key, manifest, reason } of skippedFull) {
-    rows.push({ key, coreVersion: manifest ? manifest.coreVersion : null, enabled: enabled[key] === true, satisfied: false, reason });
+    rows.push({ key, coreVersion: manifest ? manifest.coreVersion : null, enabled: enabled[key] === true, satisfied: false, reason, ...upkeep(manifest) });
   }
   rows.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
   return { rows, errors, core };
@@ -320,6 +375,29 @@ function checkModulePublishability(key, { modulesDir = MODULES_DIR } = {}) {
           'AGPL-3.0 (inbound = outbound, ADR 0107 §4)',
       });
     }
+
+    // ADR 0107 §7 / ADR 0166 — the maintenance gate. Acceptance into the shared
+    // catalog is a commitment to keep the module true as the core advances, so
+    // the module must SAY who is committing before it can be filed for review.
+    // The shape is already schema-validated above (a `maintained` module must
+    // name a maintainer; a sunset one must state its path); what this adds is
+    // that the block cannot simply be absent. Refusing here — at submit time —
+    // is what keeps the catalog from filling with entries nobody owns.
+    const maint = manifestRaw.maintenance;
+    if (!maint || !maint.status) {
+      findings.push({
+        kind: 'maintenance',
+        detail: 'module.json declares no `maintenance.status` — an upstreamed module must state its upkeep ' +
+          'posture (ADR 0107 §7): "core-maintained" (the core team owns it) or "maintained" with a named ' +
+          '`maintainer`. A module nobody owns rots silently as the core advances.',
+      });
+    } else if (SUNSET_STATUSES.includes(maint.status)) {
+      findings.push({
+        kind: 'maintenance',
+        detail: `module.json declares maintenance.status "${maint.status}" — a module already on its way out ` +
+          'cannot be submitted INTO the catalog. Upstream a maintained module, or its successor.',
+      });
+    }
   }
 
   // Classify every file AS IF it already lived at its canonical modules/<key>/
@@ -428,13 +506,28 @@ function cmdUpgrade(_args, { log = console.log, errlog = console.error, gather =
     const state = r.enabled ? 'enabled' : 'disabled';
     let note = '';
     if (!r.satisfied) {
+      // A DISABLED mismatch is harmless to THIS boot, but it is not harmless to
+      // the catalog — it is a rotted entry with an owner who needs telling
+      // (ADR 0166). Name that owner right here rather than shrugging at it.
       note = `  — coreVersion ${r.coreVersion || '(none)'} not satisfied by core ${verdict.core}` +
-        (r.enabled ? ' — will NOT mount' : ' (disabled, harmless)');
+        (r.enabled ? ' — will NOT mount' : ' — disabled, so it does not block this boot, but it is BROKEN if enabled') +
+        `\n      ↳ ${formatMaintenanceHint(r)}`;
     }
     log(`  ${mark} ${r.key.padEnd(18)} ${String(r.coreVersion || '').padEnd(10)} ${state}${note}`);
   }
   for (const e of data.errors) errlog(`  ! ${e.dir}: ${(e.errors || []).join('; ')}`);
 
+  // Deprecation roll-up (ADR 0166) — separate from compatibility: a module can
+  // satisfy the core perfectly and still be on its way out.
+  for (const d of verdict.deprecations) {
+    const overdue = verdict.expired.includes(d);
+    errlog(`  ${overdue ? '✗' : '!'} ${d.key}: ${d.maintenance.status}${overdue ? ` — PAST removeAfter ${d.maintenance.removeAfter} (core is ${verdict.core}); it is due for removal` : ''}`);
+    errlog(`      ↳ ${formatMaintenanceHint(d)}`);
+  }
+  if (verdict.undeclared.length) {
+    errlog(`  ! ${verdict.undeclared.length} module(s) declare no \`maintenance\` block — nobody is on the hook for them as the core advances (ADR 0166): ${verdict.undeclared.map((r) => r.key).join(', ')}`);
+  }
+
   if (!verdict.ok) {
     errlog(`\nREFUSING: ${verdict.blocking.length} enabled module(s) incompatible with core ${verdict.core}: ${verdict.blocking.map((b) => b.key).join(', ')}.`);
     errlog(`Widen each module's coreVersion to a range that includes ${verdict.core} (or hold the core upgrade) before proceeding.`);
@@ -459,7 +552,7 @@ function cmdCheck(args, { log = console.log, errlog = console.error, check = che
 
   log(`bongos module check — upstreaming pre-check for "${key}"`);
   if (result.ok) {
-    log('  ✓ AGPL/publish pre-check passed — no denied content, license is AGPL-3.0.');
+    log('  ✓ AGPL/publish pre-check passed — no denied content, license is AGPL-3.0, upkeep is declared.');
   } else {
     for (const f of result.findings) errlog(`  ✗ ${f.kind}: ${f.detail}`);
   }
@@ -582,6 +675,7 @@ async function main(argv) {
 module.exports = {
   main, cmdNew, cmdUpgrade, cmdCheck, cmdSubmit, printHelp,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
+  formatMaintenanceHint, isPastRemoveAfter,
   checkModulePublishability, recordSignOff, readSignOff, DCO_STATEMENT,
   listModuleFiles, packageModuleForSubmission,
   routeTemplate, claudeMdTemplate, titleize, camel, coreVersion,

package/scripts/gds/upgrade.js

@@ -141,18 +141,59 @@ function vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs) {
 
 // Lightweight module-compat pre-check reusing module.js against the TARGET core version. Best-effort:
 // a vanilla consumer has no modules/ (trivially OK); any failure downgrades to a warning, never blocks
-// the MVP bump. Returns { ok, blocking:[], note }.
+// the MVP bump. Returns { ok, blocking:[], warnings:[], deprecations:[], expired:[], note }.
+//
+// WARNINGS ARE NOT OPTIONAL OUTPUT (ADR 0166 / task 1001773). This function used to return only
+// `blocking`, so a DISABLED module whose coreVersion the target no longer satisfies vanished from the
+// bump entirely. That is precisely the catalog-rot case ADR 0107 §7 names: an accepted catalog module
+// ships `default: false` (§6), so EVERY rotted catalog entry is disabled by construction and every one
+// of them was invisible here. The bump still doesn't BLOCK on them — a disabled module breaks nothing
+// at boot — but it must SAY so, with the maintainer named, or the incompatibility is discovered by
+// whoever next tries to enable it.
 function preflightModules({ instanceDir, targetVersion }, deps = {}) {
+  const empty = { blocking: [], warnings: [], deprecations: [], expired: [] };
   const modulesDir = path.join(instanceDir, 'modules');
-  if (!fs.existsSync(modulesDir)) return { ok: true, blocking: [], note: 'no modules/ — nothing to pre-check' };
+  if (!fs.existsSync(modulesDir)) return { ok: true, ...empty, note: 'no modules/ — nothing to pre-check' };
   try {
     const mod = deps.moduleLib || require('./module');
     const data = mod.gatherUpgrade({ modulesDir, core: targetVersion });
     const verdict = mod.evaluateUpgrade(data);
-    return { ok: verdict.ok, blocking: verdict.blocking || [], note: verdict.ok ? 'all enabled modules satisfy the target' : 'incompatible enabled module(s)' };
+    const rotted = (verdict.warnings || []).length;
+    const note = !verdict.ok
+      ? 'incompatible enabled module(s)'
+      : rotted
+        ? `all enabled modules satisfy the target, but ${rotted} disabled module(s) do NOT`
+        : 'all enabled modules satisfy the target';
+    return {
+      ok: verdict.ok,
+      blocking: verdict.blocking || [],
+      warnings: verdict.warnings || [],
+      deprecations: verdict.deprecations || [],
+      expired: verdict.expired || [],
+      note,
+    };
   } catch (e) {
-    return { ok: true, blocking: [], note: `module pre-check skipped (${e.message})` };
+    return { ok: true, ...empty, note: `module pre-check skipped (${e.message})` };
+  }
+}
+
+// Print the non-blocking half of the module pre-check: rotted-but-disabled modules and
+// self-declared deprecations, each with its maintenance hint so the reader knows who to chase.
+// Split out of runUpgrade so it is testable without driving a whole bump.
+function reportModulePreflight(mods, targetVersion, { log = console.log, err = console.error, hint } = {}) {
+  const fmt = hint || ((row) => { try { return require('./module').formatMaintenanceHint(row); } catch { return ''; } });
+  const lines = [];
+  for (const w of mods.warnings || []) {
+    lines.push(`  ! module "${w.key}" is DISABLED here, so it does not block this bump — but its coreVersion ${w.coreVersion || '(none)'} is not satisfied by core ${targetVersion}: enabling it would silently fail to mount.`);
+    lines.push(`      ↳ ${fmt(w)}`);
+  }
+  for (const d of mods.deprecations || []) {
+    const overdue = (mods.expired || []).includes(d);
+    lines.push(`  ! module "${d.key}" is ${d.maintenance.status}${overdue ? ` and PAST its removeAfter ${d.maintenance.removeAfter} (core ${targetVersion}) — it is due for removal` : ''}.`);
+    lines.push(`      ↳ ${fmt(d)}`);
   }
+  for (const l of lines) err(l);
+  return lines;
 }
 
 function npmInstall(instanceDir, run = spawnSync) {
@@ -582,6 +623,10 @@ async function runUpgrade(opts, deps = {}) {
   }
   const mods = preflightModules({ instanceDir, targetVersion }, deps);
   log(`  ✓ pre-flight: ${mods.note}`);
+  // Surface the non-blocking findings (rotted-but-disabled + deprecated modules) BEFORE the
+  // blocking check returns, so they are reported on a refused bump too — a refusal is exactly
+  // when someone is reading this output (ADR 0166).
+  (deps.reportModulePreflight || reportModulePreflight)(mods, targetVersion, { log, err });
   if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
 
   // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
@@ -822,7 +867,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
+  vendorTarball, gitTreeClean, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };

package/src/bongos/routes/modules.js

@@ -99,6 +99,10 @@ function listModules() {
       origin: manifest.origin || null,
       license: manifest.license || null,
       maintainer: manifest.maintainer || null,
+      // Upkeep posture (ADR 0107 §7 / ADR 0166) — the catalog's job is to show
+      // who keeps a module true as the core advances, so a deprecated or
+      // unowned entry reads as such instead of looking like any other module.
+      maintenance: manifest.maintenance || null,
     };
   }).sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
 }

package/src/module-api.js

@@ -553,8 +553,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.61 with no explicit bump. run 31552833331. (task 1002620)
 //   1.19.63 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.62 with no explicit bump. run 31553743979. (task 1002620)
+//   1.19.64 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.63 with no explicit bump. run 31560059785. (task 1002620)
+//   1.19.65 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.64 with no explicit bump. run 31562193292. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.63'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.65'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/src/module-loader/manifest-schema.js

@@ -18,6 +18,15 @@
 //     "origin":       "…",              // OPTIONAL. Origin instance/project this module was built in.
 //     "license":      "…",              // OPTIONAL. e.g. "AGPL-3.0" — the license this module is offered under.
 //     "maintainer":   "…",              // OPTIONAL. Who to credit/contact if this module is upstreamed.
+//     "maintenance": {                  // OPTIONAL. Upkeep posture (ADR 0107 §7 / ADR 0166) — who keeps
+//       "status": "maintained",         //   REQUIRED in-block: core-maintained | maintained | deprecated | orphaned.
+//       "since":  "1.8.0",              //   OPTIONAL. Core version the status took effect.
+//       "removeAfter": "1.12.0",        //   OPTIONAL. Core version after which it may be deleted.
+//       "successor":   "econ-v2",       //   OPTIONAL. Module key that replaces it.
+//       "note":        "…"              //   OPTIONAL. The deprecation path in one sentence.
+//     },                                //   this module true as the core advances, and what happens if
+//                                       //   nobody does. `maintained` needs a named `maintainer`;
+//                                       //   `deprecated`/`orphaned` need a `successor` or a `note`.
 //     "contributes": {                  // REQUIRED object (may be empty). What the module mounts:
 //       "routes":      ["box"],         //   route-factory keys (mounted behind kernel-composed auth)
 //       "rooms":       ["WorldRoom"],   //   Colyseus room classes (realtime seam)
@@ -40,7 +49,7 @@
 // validateManifest(obj) -> { valid, errors[], manifest } — pure, no I/O.
 // assertValidManifest(obj) throws on the first failure (loader convenience).
 
-const { isValidRange } = require('./semver');
+const { isValidRange, parseVersion } = require('./semver');
 
 const KEY_RE = /^[a-z][a-z0-9-]*$/;
 
@@ -54,6 +63,23 @@ const ALLOWED_CONTRIBUTES = [...ARRAY_OF_STRING_KEYS, 'webSurfaces', 'migrations
 // Top-level attribution fields (ADR 0107 §2) — optional, portable strings.
 const ATTRIBUTION_KEYS = ['author', 'origin', 'license', 'maintainer'];
 
+// The `maintenance` block (ADR 0107 §7, decided in ADR 0166). A module pinned to
+// an old coreVersion rots as the core advances, so every module states — in the
+// manifest, where the upgrade pre-check can read it — WHO keeps it true and what
+// happens if nobody does. The four statuses are the whole policy:
+//   core-maintained  the core team owns it; a core change that breaks it is the
+//                    core's problem to fix before shipping.
+//   maintained       a named `maintainer` owns it (required — an unnamed owner
+//                    IS the orphaning failure this field exists to prevent).
+//   deprecated       on the way out; needs a path (`successor` and/or `note`),
+//                    optionally a `removeAfter` core version.
+//   orphaned         nobody owns it. Still needs a `note`/`successor` so the
+//                    next reader knows the situation, not just the label.
+const MAINTENANCE_STATUSES = ['core-maintained', 'maintained', 'deprecated', 'orphaned'];
+const MAINTENANCE_KEYS = ['status', 'since', 'removeAfter', 'successor', 'note'];
+// Statuses that describe a module on its way out — these owe a deprecation path.
+const SUNSET_STATUSES = ['deprecated', 'orphaned'];
+
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
 const isStr = (v) => typeof v === 'string' && v.length > 0;
 const isStrArray = (v) => Array.isArray(v) && v.every(isStr);
@@ -93,6 +119,44 @@ function validateManifest(obj) {
     if (k in obj && !isStr(obj[k])) E(`${k}: must be a non-empty string when present`);
   }
 
+  // --- optional maintenance block (ADR 0107 §7 / ADR 0166) ---
+  // Closed key set (like contributes) so a typo'd "removeafter" fails loud rather
+  // than silently declaring no removal date at all.
+  if ('maintenance' in obj) {
+    const m = obj.maintenance;
+    if (!isObj(m)) {
+      E('maintenance: must be an object (e.g. { "status": "maintained" })');
+    } else {
+      for (const k of Object.keys(m)) {
+        if (!MAINTENANCE_KEYS.includes(k)) E(`maintenance.${k}: unknown key (allowed: ${MAINTENANCE_KEYS.join(', ')})`);
+      }
+      if (!isStr(m.status)) E(`maintenance.status: required — one of ${MAINTENANCE_STATUSES.join(', ')}`);
+      else if (!MAINTENANCE_STATUSES.includes(m.status)) {
+        E(`maintenance.status: "${m.status}" is not one of ${MAINTENANCE_STATUSES.join(', ')}`);
+      }
+      for (const k of ['since', 'removeAfter']) {
+        if (k in m && !parseVersion(m[k])) E(`maintenance.${k}: must be an exact core version "X.Y.Z" when present`);
+      }
+      if ('successor' in m && (!isStr(m.successor) || !KEY_RE.test(m.successor))) {
+        E('successor: must be a module key (lowercase kebab-case) when present');
+      }
+      if ('note' in m && !isStr(m.note)) E('maintenance.note: must be a non-empty string when present');
+
+      // The two rules that make the block load-bearing rather than decorative:
+      // a "maintained" module must NAME its maintainer, and a module on its way
+      // out must state the path out. Everything else above is shape-checking.
+      if (m.status === 'maintained' && !isStr(obj.maintainer)) {
+        E('maintenance.status "maintained" requires a named top-level `maintainer` (ADR 0166) — use "orphaned" if nobody owns it');
+      }
+      if (SUNSET_STATUSES.includes(m.status) && !isStr(m.successor) && !isStr(m.note)) {
+        E(`maintenance.status "${m.status}" requires a deprecation path — a "successor" module key and/or a "note" (ADR 0166)`);
+      }
+      if ('removeAfter' in m && !SUNSET_STATUSES.includes(m.status)) {
+        E(`maintenance.removeAfter only applies to a ${SUNSET_STATUSES.join('/')} module (status is "${m.status}")`);
+      }
+    }
+  }
+
   // --- contributes (required object) ---
   if (!isObj(obj.contributes)) {
     E('contributes: required object (use {} if the module contributes nothing)');
@@ -152,4 +216,7 @@ function assertValidManifest(obj, label = 'module.json') {
   return obj;
 }
 
-module.exports = { validateManifest, assertValidManifest, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS };
+module.exports = {
+  validateManifest, assertValidManifest, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS,
+  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES,
+};