@bongos/core 1.19.126 → 1.19.128

package/scripts/gds/provision.js

@@ -169,6 +169,14 @@ const CONFIG = {
 
 const MAX_INTENT_ATTEMPTS = numEnv('PROVISION_INTENT_MAX_ATTEMPTS', 3);
 
+// Manifest-placement verification budget (task 1002720 / QA-walk F23): a child
+// instance is a full Node boot away from reporting auth_configured=true, and the
+// old 10×1s poll routinely lost that race — recording a failure for a setup that
+// succeeded, then burning the SINGLE-USE manifest code on the retry. ~3 min of
+// patience; the poll runs after the intent loop, so it delays nothing.
+const MANIFEST_VERIFY_TRIES = numEnv('PROVISION_MANIFEST_VERIFY_TRIES', 90);
+const MANIFEST_VERIFY_INTERVAL_MS = numEnv('PROVISION_MANIFEST_VERIFY_INTERVAL_MS', 2000);
+
 // ---------------------------------------------------------------------------
 // Lazy dep load (so --help / arg errors need no Postgres) — the box.js pattern.
 // ---------------------------------------------------------------------------
@@ -1503,9 +1511,21 @@ async function provisionInstance(inst, deps) {
       // only on the control plane — it must never run on the (token-free) co-hosting
       // box even when the box-mutating steps above went there over SSH (task 2065).
       controlExec(CONFIG.dnsHook, { env: dnsEnv });
+      // The clear half of the birth-path note (F16): a revive after the operator
+      // configured the hook must retire the stale "point your A record" sentence.
+      if (apply && provisioning.recordDnsNote) {
+        await provisioning.recordDnsNote(db, inst.id, null).catch(() => {});
+      }
     }
   } else {
     log('  [dns] skipped (no domain, or BOX_DNS_HOOK unset)');
+    // Birth-path twin of the domain-attach note (F16): a domain with no hook is
+    // the same silent skip here, so the owner card gets the same sentence.
+    if (apply && inst.domain) {
+      if (provisioning.recordDnsNote) await provisioning.recordDnsNote(db, inst.id,
+        `Automatic DNS isn't set up on this platform — point ${inst.domain}'s A record at ${recordIp || 'your server'}, and this card will show when it answers.`
+      ).catch(() => {});
+    }
   }
 
   // ── step 6: Caddy per-instance site snippet + reload ──────────────────────
@@ -1520,17 +1540,55 @@ async function provisionInstance(inst, deps) {
   } else { log('    (Caddy on the droplet via cloud-init)'); }
 
   // ── step 7: healthz ───────────────────────────────────────────────────────
+  // The probe RESULT is recorded, not discarded (task 1002720 / QA-walk F15: a
+  // refused connection used to ride silently into 'active' and the card said
+  // live). Bounded retry so a slow first boot is not slandered — the
+  // placeManifestCreds loop shape. Still ok:true either way: a failed probe
+  // must not flip the intent to failed (cmdRunIntents would burn the 3-attempt
+  // budget on an instance that may simply be slow); the liveness overlay is
+  // what tells the owner the truth.
   log('  [healthz] verify the instance answers');
-  if (local) boxExec(healthzCmd(inst), { allowFail: true });
-  else log('    (verified post-boot)');
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let healthy = null;                     // null = not observed (dry-run / dedicated)
+  if (local) {
+    const tries = apply ? 10 : 1;
+    for (let i = 0; i < tries; i++) {
+      const res = boxExec(healthzCmd(inst), { allowFail: true });
+      if (!apply) break;                  // dry-run: exactly one plan line
+      if (res && !res.softFailed) { healthy = true; break; }
+      healthy = false;
+      if (i < tries - 1) await sleep(1000);
+    }
+  } else log('    (verified post-boot)');
 
-  // Mark active.
+  // Mark active. error_note: null — a stale note from an earlier failed run
+  // must not ride into the active state (F15's second half; the co-tenant +
+  // standalone paths never cleared it). The runner hands its own observation
+  // to the liveness overlay so the card gets an honest verdict immediately
+  // instead of waiting ~5 min for the first sweep.
   if (apply) {
-    await provisioning.setInstanceStatus(db, inst.id, 'active', { ...patch, provisioned_at: new Date().toISOString() });
-    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'active', detail: `provisioned (${inst.hosting_shape}, port ${inst.port || '-'})`, actor: 'runner' });
+    await provisioning.setInstanceStatus(db, inst.id, 'active', { ...patch, error_note: null, provisioned_at: new Date().toISOString() });
+    // The overlay column is DOMAIN-scoped when a domain exists (the sweep
+    // probes https://<domain>; loopback only when there is none), and the card
+    // renders up=true as "Answering at <domain>". This probe is loopback, so:
+    // a FAILURE is a verdict on any shape (a dead process answers nowhere),
+    // but a PASS proves only the process — for a domain-bearing instance the
+    // address claim stays "not checked yet" until the sweep earns it.
+    const probeIsVerdict = healthy === false || (healthy === true && !inst.domain);
+    if (probeIsVerdict && provisioning.recordLivenessProbe) {
+      await provisioning.recordLivenessProbe(db, inst.id, healthy).catch(() => {});
+    }
+    await provisioning.recordEvent(db, {
+      instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'active',
+      detail: `provisioned (${inst.hosting_shape}, port ${inst.port || '-'})` +
+              (healthy === false ? ' — not answering /healthz yet' : ''),
+      actor: 'runner',
+    });
   }
-  log(`  ✓ ${inst.slug} provisioned`);
-  return { ok: true, port: inst.port };
+  log(healthy === false
+    ? `  ⚠ ${inst.slug} provisioned, but it is not answering /healthz yet — its card will read "unreachable"`
+    : `  ✓ ${inst.slug} provisioned`);
+  return { ok: true, port: inst.port, healthy };
 }
 
 // The cloud-init user-data for a dedicated droplet: run the co-tenant standup
@@ -1616,6 +1674,7 @@ async function domainAttachInstance(inst, deps) {
 
   // DNS A-record UPSERT — mirrors provisionInstance step 5 (control-plane exec only:
   // the hook needs the Cloudflare token, which never leaves the control plane).
+  let dnsSkipped = false;
   if (CONFIG.dnsHook) {
     if (!recordIp) {
       const ipEnvHint = standalone ? 'PROVISION_CONTROL_PLANE_IP (standalone)' : 'PROVISION_PUBLIC_IP (co-tenant)';
@@ -1627,7 +1686,11 @@ async function domainAttachInstance(inst, deps) {
       controlExec(CONFIG.dnsHook, { env: dnsEnv });
     }
   } else {
-    log('  [dns] skipped (BOX_DNS_HOOK unset) — point the A record manually');
+    // Still ok:true below — an unset hook is unretryable, and ok:false would
+    // burn the intent's retry budget on it. The skip is surfaced to the OWNER
+    // via dns_note (F16), not just this operator log line.
+    dnsSkipped = true;
+    log(`  [dns] skipped (BOX_DNS_HOOK unset) — point ${inst.domain}'s A record at ${recordIp || 'this server'} manually`);
   }
 
   log('  [caddy] write site snippet + reload');
@@ -1638,12 +1701,24 @@ async function domainAttachInstance(inst, deps) {
   boxExec(healthzCmd(inst), { allowFail: true });
 
   if (apply) {
+    // Written BOTH ways so a later successful attach clears a stale note.
+    if (provisioning.recordDnsNote) await provisioning.recordDnsNote(db, inst.id, dnsSkipped
+      ? `Automatic DNS isn't set up on this platform — point ${inst.domain}'s A record at ${recordIp || 'your server'}, and this card will show when it answers.`
+      : null).catch(() => {});
+    // Release the F19 latch: this run SUCCEEDED, so a "we stopped trying" note
+    // from an earlier retired attach must not outlive its own recovery.
+    if (provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id).catch(() => {});
     await provisioning.recordEvent(db, {
       instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'domain-attached',
-      detail: `domain ${inst.domain} wired (env + DNS + caddy re-asserted)`, actor: 'runner',
+      detail: dnsSkipped
+        ? `domain ${inst.domain} wired (env + caddy); DNS SKIPPED — no hook configured`
+        : `domain ${inst.domain} wired (env + DNS + caddy re-asserted)`,
+      actor: 'runner',
     }).catch(() => {});
   }
-  log(`  ✓ ${inst.slug} addressed as ${inst.domain}`);
+  log(dnsSkipped
+    ? `  ✓ ${inst.slug} configured for ${inst.domain} — DNS still needs your A record`
+    : `  ✓ ${inst.slug} addressed as ${inst.domain}`);
   return { ok: true };
 }
 
@@ -1750,11 +1825,14 @@ async function placeManifestCreds(inst, mrow, deps) {
 
   // 2) validate the returned creds BEFORE writing (catch a malformed GitHub response —
   //    the same length/charset guard oauth-secret.js uses against silent truncation).
+  // From here on the single-use manifest code is SPENT (the conversion POST
+  // consumed it) — every return carries codeSpent:true so the drain never
+  // resets the row for a retry that would re-convert a burned code and 404.
   const idV = oauthSecret.validateClientId(creds.clientId);
   const secV = oauthSecret.validateClientSecret(creds.clientSecret);
   if (!idV.ok || !secV.ok) {
     const why = [!idV.ok ? `id: ${idV.reason}` : null, !secV.ok ? `secret: ${secV.reason}` : null].filter(Boolean).join('; ');
-    return { ok: false, error: `GitHub returned unusable creds (${why})` };
+    return { ok: false, codeSpent: apply, error: `GitHub returned unusable creds (${why})` };
   }
 
   // 3) rewrite web.env with the creds + restart the unit (never logs the secret — the
@@ -1764,21 +1842,24 @@ async function placeManifestCreds(inst, mrow, deps) {
   boxExec(`${sudoP}systemctl restart ${inst.slug}`);
 
   // 4) verify /healthz reports auth_configured=true (only meaningful under --apply).
+  //    PATIENT (F23): the child must boot before it can answer; losing this race
+  //    used to record a failure for a setup that had succeeded.
   if (apply) {
+    const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
     let authConfigured = false;
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
       const out = boxExec(healthzCmd(inst), { allowFail: true });
       if (oauthSecret.parseHealthzAuth(out && out.stdout).authConfigured) { authConfigured = true; break; }
-      await new Promise((r) => setTimeout(r, 1000));
+      await sleep(MANIFEST_VERIFY_INTERVAL_MS);
     }
     if (!authConfigured) {
-      return { ok: false, error: 'placed creds but /healthz still reports auth_configured=false — sign-in not live yet' };
+      return { ok: false, codeSpent: true, error: 'the credentials are placed, but the project did not report sign-in ready in time' };
     }
     log('  [oauth-manifest] ✓ /healthz auth_configured=true — sign-in is live');
   } else {
     log('  [oauth-manifest] would probe /healthz for auth_configured after restart');
   }
-  return { ok: true, appId: creds.appId, appSlug: creds.appSlug };
+  return { ok: true, codeSpent: apply, appId: creds.appId, appSlug: creds.appSlug };
 }
 
 // Drain provisioning_oauth_manifests rows awaiting conversion (status 'code_received').
@@ -1820,11 +1901,17 @@ async function drainOAuthManifests(deps) {
       if (!inst) { await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: 'instance row vanished' }); errors++; continue; }
       const result = await placeManifestCreds(inst, mrow, deps);
       if (result && result.ok === false) {
-        if (mrow.attempts >= MAX_INTENT_ATTEMPTS) await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: result.error });
+        // A SPENT code is terminal, always (F23): GitHub's manifest code is
+        // single-use, so resetting the row to 'code_received' guarantees the
+        // next tick re-converts a burned code and 404s forever. Only failures
+        // that happened BEFORE the conversion stay retryable.
+        if (result.codeSpent) await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: result.error, github_code: null });
+        else if (mrow.attempts >= MAX_INTENT_ATTEMPTS) await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: result.error });
         else await provisioning.resolveOAuthManifest(db, mrow.id, 'code_received', { last_error: result.error });
         errors++; log(`  ✖ oauth-manifest #${mrow.id}: ${result.error}`);
       } else {
-        await provisioning.resolveOAuthManifest(db, mrow.id, 'done', { app_id: result.appId, app_slug: result.appSlug });
+        // github_code: null on done too — a finished row holds no re-convertible code.
+        await provisioning.resolveOAuthManifest(db, mrow.id, 'done', { app_id: result.appId, app_slug: result.appSlug, github_code: null });
         await provisioning.recordEvent(db, {
           instanceId: inst.id, ownerBuilderId: mrow.requested_by, event: 'oauth-manifest-done',
           detail: `sign-in wired via GitHub App Manifest (app ${result.appSlug || result.appId || '?'})`, actor: 'runner',
@@ -1880,8 +1967,17 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'domain-attach') result = await domainAttachInstance(inst, deps);
       else result = { ok: false, error: `unknown intent action '${intent.action}' — refusing to guess` };
       if (result && result.ok === false) {
-        if (intent.attempts >= MAX_INTENT_ATTEMPTS) await provisioning.resolveIntent(db, intent.id, 'error', result.error || 'op failed');
-        else await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed']);
+        if (intent.attempts >= MAX_INTENT_ATTEMPTS) {
+          await provisioning.resolveIntent(db, intent.id, 'error', result.error || 'op failed');
+          // A retired intent stops silently otherwise (F19): record the reason
+          // on the instance WITHOUT changing its lifecycle status — passing the
+          // CURRENT status makes the status write a no-op, so a healthy active
+          // instance is never marked broken over a domain hiccup, but the card
+          // can say why the work stopped.
+          await provisioning.setInstanceStatus(db, intent.instance_id, inst.status, { error_note: result.error || 'op failed' }).catch(() => {});
+        } else {
+          await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed']);
+        }
         errors++;
       } else { await provisioning.resolveIntent(db, intent.id, 'done', null); ok++; }
     } catch (e) {

package/src/bongos/db-kernel.js

@@ -62,6 +62,20 @@ async function getBuilderById(id) {
   return rows[0] ?? null;
 }
 
+// getFoundingBuilder — the instance's first admitted HUMAN builder (task
+// 1002739): the founding owner a newborn instance greets, and the anchor of
+// the builder-needs founding-grace window. system_role IS NULL is load-bearing:
+// core migrations 065/067 seed the BFG + Discord-bot system principals into
+// builders on EVERY instance before anyone can sign in, so the lowest ids on a
+// newborn DB are not the founder. First human row by id, regardless of status —
+// the founder stays the founder even if later deactivated.
+async function getFoundingBuilder() {
+  const { rows } = await pool.query(
+    `SELECT id, created_at FROM builders WHERE system_role IS NULL ORDER BY id ASC LIMIT 1`
+  );
+  return rows[0] ?? null;
+}
+
 // listActiveBuilders — the minimal, any-builder-readable roster (task 1877): an
 // invite-picker needs a real name of every builder to invite, not just the
 // leaderboard's top-100-by-credits window. Deliberately narrow columns — no
@@ -337,6 +351,7 @@ module.exports = {
   withTx,
   sessionPermsSelect,
   getBuilderById,
+  getFoundingBuilder,
   listActiveBuilders,
   insertAuditLog,
   LIVE_RANK_LADDER,

package/src/bongos/db.js

@@ -38,7 +38,7 @@ const seams = require('../module-seams');
 // published doorway resolves through. Re-exported below so every caller is
 // byte-identical; db-kernel depends only on ./pool, never ./db (one-way).
 const {
-  withTx, getBuilderById, listActiveBuilders, insertAuditLog, LIVE_RANK_LADDER,
+  withTx, getBuilderById, getFoundingBuilder, listActiveBuilders, insertAuditLog, LIVE_RANK_LADDER,
   // Auth/identity/admission + the rank vocabulary carved to db-kernel (ADR 0102,
   // finishing ADR 0091 §1). Re-exported below so db.js's other importers + its own
   // internal uses (setBuilderRank's RANKS.indexOf, etc.) stay byte-identical.
@@ -978,6 +978,7 @@ module.exports = {
   upsertBuilder,
   seatFirstAdminIfUnclaimed,
   getBuilderById,
+  getFoundingBuilder,
   listActiveBuilders,
   linkAnthropicAccount,
   getBuilderByGithubId,

package/src/bongos/routes/me.js

@@ -83,7 +83,7 @@ module.exports = function buildMeRouter() {
     const [
       builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
-      behaviorPrefs, geminiKeyRow, needsRebaseTasks,
+      behaviorPrefs, geminiKeyRow, needsRebaseTasks, foundingBuilder,
     ] = await Promise.all([
       db.getBuilderById(req.builder.id),
       lc().getActiveClaimsForBuilder(req.builder.id),
@@ -144,6 +144,10 @@ module.exports = function buildMeRouter() {
       // without a follow-up call. Through the `lifecycle` port; [] on a
       // lifecycle-less instance (guarded — the port is resolveOptional).
       lc() ? lc().needsRebaseTasksForBuilder(req.builder.id) : [],
+      // task 1002739: the instance's first admitted builder — anchors the
+      // builder-needs founding-grace window (a newborn instance's founder gets a
+      // welcome, not a nag). Best-effort: null just means no grace.
+      db.getFoundingBuilder().catch(() => null),
     ]);
     // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
     // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
@@ -274,6 +278,12 @@ module.exports = function buildMeRouter() {
         rank: builder?.rank,
         ownKeySet: !!(geminiKeyRow && geminiKeyRow.enc),
         sharedKeyConfigured: artSharedKeyConfigured(),
+        // founding grace (task 1002739 / direction §5.6): a newborn instance's
+        // founder gets a welcome roster, not a coverage nag. The module owns the
+        // policy (window length, copy); we pass the raw facts.
+        isFoundingOwner: !!(foundingBuilder && String(foundingBuilder.id) === String(req.builder.id)),
+        founderCreatedAt: foundingBuilder ? foundingBuilder.created_at : null,
+        projectName: (() => { try { return branding().identity?.productName || null; } catch { return null; } })(),
       }) : [],
     };
     // Module→core contribution seam (BV1.R42, ADR 0083). Let each enabled module

package/src/module-api.js

@@ -679,8 +679,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.124 with no explicit bump. run 31849445746. (task 1002620)
 //   1.19.126 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.125 with no explicit bump. run 31853055269. (task 1002620)
+//   1.19.127 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.126 with no explicit bump. run 31854730552. (task 1002620)
+//   1.19.128 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.127 with no explicit bump. run 31857842473. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.126'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.128'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/builder_needs.mjs

@@ -95,5 +95,119 @@ t('missing rank fails safe — not action_needed without an explicit rank', () =
   assert.ok(['covered', 'action_needed', 'satisfied'].includes(n.state));
 });
 
+console.log('founding grace (task 1002739, direction §5.6):');
+
+const DAY = 24 * 60 * 60 * 1000;
+const bornNow = new Date().toISOString();
+
+t('newborn founder: welcome item first, greeting by project name', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false,
+    isFoundingOwner: true, founderCreatedAt: bornNow, projectName: 'Mercury',
+  });
+  assert.equal(r.items[0].id, 'founding_welcome');
+  assert.match(r.items[0].title, /Mercury/);
+  assert.equal(r.items[0].state, 'covered');
+  assert.equal(r.items[0].action, null);
+});
+
+t('newborn founder: zero action_needed — every nag is suppressed', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: bornNow,
+  });
+  assert.equal(r.has_action_needed, false);
+  assert.equal(r.action_needed_count, 0);
+  for (const n of r.items) assert.notEqual(n.state, 'action_needed');
+});
+
+t('a suppressed nag keeps its identity but loses the demand', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: bornNow,
+  });
+  const artItem = r.items.find((n) => n.id === 'art_key');
+  assert.ok(artItem, 'the art_key item must still be listed, not hidden');
+  assert.equal(artItem.state, 'covered');
+  assert.equal(artItem.action, null);
+  assert.doesNotMatch(artItem.message, /coverage has ended/i);
+});
+
+t('the grace window is seven days — the policy number is pinned, not self-referential', () => {
+  // A fixed injected clock, and 7 written as a literal on both sides: mutating
+  // FOUNDING_GRACE_DAYS (a "tune", a bad merge) must fail here, not slide.
+  assert.equal(needs.FOUNDING_GRACE_DAYS, 7);
+  const born = Date.parse('2026-01-01T00:00:00Z');
+  const ctx = { rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: '2026-01-01T00:00:00Z' };
+  const inWindow = needs.computeNeeds({ ...ctx, nowMs: born + 7 * DAY - 60_000 });
+  assert.equal(inWindow.has_action_needed, false);
+  assert.equal(inWindow.items[0].id, 'founding_welcome');
+  const expired = needs.computeNeeds({ ...ctx, nowMs: born + 7 * DAY + 60_000 });
+  assert.equal(expired.has_action_needed, true);
+  assert.ok(!expired.items.find((n) => n.id === 'founding_welcome'));
+});
+
+t('grace expires: past FOUNDING_GRACE_DAYS the founder is nagged like anyone (real clock)', () => {
+  const old = new Date(Date.now() - (needs.FOUNDING_GRACE_DAYS * DAY + 60_000)).toISOString();
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: old,
+  });
+  assert.equal(r.has_action_needed, true);
+  assert.ok(!r.items.find((n) => n.id === 'founding_welcome'));
+});
+
+t('a non-founder on a newborn instance is not suppressed', () => {
+  const r = needs.computeNeeds({
+    rank: 'thetes', ownKeySet: false, isFoundingOwner: false, founderCreatedAt: bornNow,
+  });
+  assert.equal(r.has_action_needed, true);
+  assert.ok(!r.items.find((n) => n.id === 'founding_welcome'));
+});
+
+t('satisfied stays satisfied during grace — no fake downgrades', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: true, isFoundingOwner: true, founderCreatedAt: bornNow,
+  });
+  assert.equal(r.items.find((n) => n.id === 'art_key').state, 'satisfied');
+});
+
+t('no founder facts at all → no grace, no welcome (vanilla ctx unchanged)', () => {
+  const r = needs.computeNeeds({ rank: 'thetes', ownKeySet: false });
+  assert.equal(r.has_action_needed, true);
+  assert.ok(!r.items.find((n) => n.id === 'founding_welcome'));
+});
+
+console.log('the producing side (DB-free source pins — the policy is only as real as its facts):');
+
+// The seven policy cases above hand computeNeeds its ctx. These pin the two
+// places that PRODUCE that ctx, because both were wrong-or-unverified once:
+// the founder query returned the migration-seeded BFG system principal (ids 1-2
+// on every newborn DB — review panel, 2026-08-15), and a key rename in me.js
+// would silently disable the grace while every policy case stayed green. A
+// DB-backed newborn-instance test can't run in the unit gate, so the source is
+// the checkable artifact.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+t('getFoundingBuilder skips the seeded system principals (system_role IS NULL)', () => {
+  const src = readFileSync(path.join(ROOT, 'src/bongos/db-kernel.js'), 'utf8');
+  const fn = src.slice(src.indexOf('function getFoundingBuilder'));
+  const sql = fn.slice(0, fn.indexOf('return'));
+  assert.match(sql, /FROM builders/);
+  assert.match(sql, /system_role IS NULL/,
+    'the founder query must exclude system principals — migrations 065/067 seed them at the lowest ids on every instance');
+  assert.match(sql, /ORDER BY id ASC/);
+});
+
+t('the /me aggregator feeds computeNeeds the founder facts under their contract names', () => {
+  const src = readFileSync(path.join(ROOT, 'src/bongos/routes/me.js'), 'utf8');
+  const call = src.slice(src.indexOf('computeNeeds({'), src.indexOf('}) : []'));
+  for (const key of ['isFoundingOwner', 'founderCreatedAt', 'projectName']) {
+    assert.match(call, new RegExp(`${key}\\s*:`),
+      `me.js must pass ${key} into computeNeeds — a rename silently disables the founding grace`);
+  }
+  assert.match(src, /getFoundingBuilder\(\)/, 'me.js must resolve the founder row');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);