@bongos/core 1.21.175 → 1.21.177

package/tests/session_reward_reconcile.mjs

@@ -10,8 +10,9 @@
 //
 // Same DB-free harness as session_reward_on_land.mjs: patch api.withTx to hand the
 // fn a SQL-aware fake client, register the REAL economy `reward` port so the real
-// awardSessionTokenReward SQL runs against the fake, and a guarded real-DB block
-// proves the partial-unique index enforces exactly-once end-to-end.
+// awardSessionTokenReward SQL runs against the fake. The real-DB half (the
+// partial-unique index enforcing exactly-once end-to-end) lives in
+// tests/session_reward_reconcile_db.mjs (INTEGRATION set; task 1004861).
 //
 // Run:  node tests/session_reward_reconcile.mjs
 
@@ -137,93 +138,10 @@ await test('reconcile: limit is clamped to [1, 1000]', async () => {
 });
 
 // =========================================================================
-// (5) real-DB — proves the sweep books once, is idempotent (partial index),
-//     and NEVER pays a task that is only 'confirmed' (ADR 0120 pay-on-land).
-//     Requires DATABASE_URL; skipped cleanly otherwise.
+// The REAL-DB cases moved to tests/session_reward_reconcile_db.mjs (task 1004861) — an
+// INTEGRATION-set file, so a database lane runs them and a setup failure reds
+// instead of reading as SKIP. This file stays DB-free and in the unit gate.
 // =========================================================================
 
-if (process.env.DATABASE_URL) {
-  const pool = api.pool;
-  const suffix = `srr_${Date.now()}_${Math.floor(Math.random() * 1e6)}`;
-  const ctx = { builderId: null, versionId: `ver_${suffix}`, shippedTaskId: null, confirmedTaskId: null };
-  let setupOk = false;
-  try {
-    const b = await pool.query(
-      `INSERT INTO builders (github_id, github_login, display_name) VALUES ($1,$2,$3) RETURNING id`,
-      [`gh_${suffix}`, `login_${suffix}`, `Test ${suffix}`]
-    );
-    ctx.builderId = Number(b.rows[0].id);
-    await pool.query(
-      `INSERT INTO versions (id, name, track, status) VALUES ($1,$2,'internal','planning')`,
-      [ctx.versionId, `V ${suffix}`]
-    );
-    const shipped = await pool.query(
-      `INSERT INTO tasks (version_id, title, status) VALUES ($1,$2,'shipped') RETURNING id`,
-      [ctx.versionId, `shipped ${suffix}`]
-    );
-    ctx.shippedTaskId = Number(shipped.rows[0].id);
-    const confirmed = await pool.query(
-      `INSERT INTO tasks (version_id, title, status) VALUES ($1,$2,'confirmed') RETURNING id`,
-      [ctx.versionId, `confirmed ${suffix}`]
-    );
-    ctx.confirmedTaskId = Number(confirmed.rows[0].id);
-    setupOk = true;
-  } catch (e) {
-    console.log(`  SKIP  real-DB block (setup failed: ${e.message})`);
-  }
-
-  if (setupOk) {
-    const rewardRows = (sessionId) => pool.query(
-      `SELECT delta FROM credit_log WHERE session_id = $1 AND reason = 'session.token_reward'`,
-      [sessionId]
-    );
-    const sidShipped = `sess-recon-shipped-${suffix}`;
-    const sidConfirmed = `sess-recon-confirmed-${suffix}`;
-    try {
-      await test('real-DB: reconcile books a stranded shipped session once, idempotently', async () => {
-        // A session whose task is shipped but which never booked (the out-of-band case).
-        await pool.query(
-          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
-           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
-          [sidShipped, ctx.builderId, ctx.shippedTaskId, 5000, JSON.stringify(MODEL_USAGE)]
-        );
-        assert.equal((await rewardRows(sidShipped)).rows.length, 0, 'precondition: no reward yet');
-
-        const first = await db.reconcileUnbookedSessionRewards();
-        assert.ok(first.awarded >= 1, 'the sweep booked at least the shipped session');
-        assert.equal((await rewardRows(sidShipped)).rows.length, 1, 'exactly one reward row for the shipped session');
-
-        const second = await db.reconcileUnbookedSessionRewards();
-        // second sweep may scan 0 (already booked) — the invariant is no double-pay.
-        assert.equal((await rewardRows(sidShipped)).rows.length, 1, 'still exactly one — the partial index held');
-        assert.ok(second.awarded === 0 || second.scanned === 0, 're-sweep never double-pays');
-      });
-
-      await test('real-DB: reconcile NEVER pays a task that is only confirmed (pay-on-land)', async () => {
-        await pool.query(
-          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
-           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
-          [sidConfirmed, ctx.builderId, ctx.confirmedTaskId, 5000, JSON.stringify(MODEL_USAGE)]
-        );
-        await db.reconcileUnbookedSessionRewards();
-        assert.equal((await rewardRows(sidConfirmed)).rows.length, 0,
-          'a confirmed-only task is never paid — the reward waits for a genuine shipped');
-      });
-    } finally {
-      try {
-        await pool.query(`DELETE FROM credit_log WHERE builder_id = $1`, [ctx.builderId]);
-        await pool.query(`DELETE FROM session_records WHERE builder_id = $1`, [ctx.builderId]);
-        await pool.query(`DELETE FROM tasks WHERE version_id = $1`, [ctx.versionId]);
-        await pool.query(`DELETE FROM versions WHERE id = $1`, [ctx.versionId]);
-        await pool.query(`DELETE FROM builders WHERE id = $1`, [ctx.builderId]);
-      } catch (e) {
-        console.log(`  WARN  real-DB teardown left rows (${e.message})`);
-      }
-    }
-  }
-} else {
-  console.log('  SKIP  real-DB block (no DATABASE_URL)');
-}
-
 // -------------------------------------------------------------------------
 summary();

package/tests/session_reward_reconcile_db.mjs

@@ -0,0 +1,132 @@
+// tests/session_reward_reconcile_db.mjs — the REAL-DATABASE half of tests/session_reward_reconcile.mjs (task 1004861).
+//
+// reconcileUnbookedSessionRewards against a real database: books a stranded shipped session
+// once, idempotently, and NEVER pays a task that is only confirmed.
+//
+// The DB-free half (fake client: books, no-op, race, limit clamp) stays in
+// session_reward_reconcile.mjs.
+//
+// WHY ITS OWN FILE. These cases used to sit at the bottom of session_reward_reconcile.mjs behind a
+// DATABASE_URL guard, and ANY setup error was reported as "SKIP" — so when the fixture
+// started colliding with versions_one_planning_idx (the seeds already hold the one
+// 'planning' slot) the block went silent instead of red, and the file was in no lane
+// that supplies a database anyway. Split out, it sits in the INTEGRATION set; the
+// DB-free half stays in the unit gate. It SKIPS only when no Postgres is reachable —
+// a reachable database whose setup then fails is a FAIL.
+//
+// Run:  DATABASE_URL=... node tests/session_reward_reconcile_db.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const api = require('../src/module-api.js');
+const db = require('../modules/sessions/db.js');
+
+const { test, summary } = makeRunner();
+
+// Opus 110k input tokens → $0.55 true cost → $0.55 × 1.20 = 1 drachma. A non-zero
+// payout is what lets the idempotency SELECT + INSERT run at all.
+const MODEL_USAGE = { 'claude-opus-4-8': { input: 110_000 } };
+
+const pool = api.pool;
+try {
+  if (!process.env.DATABASE_URL) throw Object.assign(new Error('no DATABASE_URL'), { code: 'NO_DATABASE_URL' });
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`session_reward_reconcile_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const suffix = `srr_${Date.now()}_${Math.floor(Math.random() * 1e6)}`;
+const ctx = { builderId: null, versionId: `ver_${suffix}`, shippedTaskId: null, confirmedTaskId: null };
+let setupOk = false;
+
+await test('real-DB: fixture setup', async () => {
+  // The version is 'building', not 'planning': at most one version may plan
+  // (versions_one_planning_idx, core_233) and the seeds already hold that slot.
+  const b = await pool.query(
+    `INSERT INTO builders (github_id, github_login, display_name) VALUES ($1,$2,$3) RETURNING id`,
+    [`gh_${suffix}`, `login_${suffix}`, `Test ${suffix}`]
+  );
+  ctx.builderId = Number(b.rows[0].id);
+  await pool.query(
+    `INSERT INTO versions (id, name, track, status) VALUES ($1,$2,'internal','building')`,
+    [ctx.versionId, `V ${suffix}`]
+  );
+  const shipped = await pool.query(
+    `INSERT INTO tasks (version_id, title, status, discipline) VALUES ($1,$2,'shipped','engineer') RETURNING id`,
+    [ctx.versionId, `shipped ${suffix}`]
+  );
+  ctx.shippedTaskId = Number(shipped.rows[0].id);
+  const confirmed = await pool.query(
+    `INSERT INTO tasks (version_id, title, status, discipline) VALUES ($1,$2,'confirmed','engineer') RETURNING id`,
+    [ctx.versionId, `confirmed ${suffix}`]
+  );
+  ctx.confirmedTaskId = Number(confirmed.rows[0].id);
+  setupOk = true;
+});
+
+{ // its own block so the teardown below runs even when setup failed halfway
+  const rewardRows = (sessionId) => pool.query(
+    `SELECT delta FROM credit_log WHERE session_id = $1 AND reason = 'session.token_reward'`,
+    [sessionId]
+  );
+  const sidShipped = `sess-recon-shipped-${suffix}`;
+  const sidConfirmed = `sess-recon-confirmed-${suffix}`;
+  try {
+    if (setupOk) {
+      await test('real-DB: reconcile books a stranded shipped session once, idempotently', async () => {
+        // A session whose task is shipped but which never booked (the out-of-band case).
+        await pool.query(
+          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
+           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
+          [sidShipped, ctx.builderId, ctx.shippedTaskId, 5000, JSON.stringify(MODEL_USAGE)]
+        );
+        assert.equal((await rewardRows(sidShipped)).rows.length, 0, 'precondition: no reward yet');
+
+        const first = await db.reconcileUnbookedSessionRewards();
+        assert.ok(first.awarded >= 1, 'the sweep booked at least the shipped session');
+        assert.equal((await rewardRows(sidShipped)).rows.length, 1, 'exactly one reward row for the shipped session');
+
+        const second = await db.reconcileUnbookedSessionRewards();
+        // second sweep may scan 0 (already booked) — the invariant is no double-pay.
+        assert.equal((await rewardRows(sidShipped)).rows.length, 1, 'still exactly one — the partial index held');
+        assert.ok(second.awarded === 0 || second.scanned === 0, 're-sweep never double-pays');
+      });
+
+      await test('real-DB: reconcile NEVER pays a task that is only confirmed (pay-on-land)', async () => {
+        await pool.query(
+          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
+           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
+          [sidConfirmed, ctx.builderId, ctx.confirmedTaskId, 5000, JSON.stringify(MODEL_USAGE)]
+        );
+        await db.reconcileUnbookedSessionRewards();
+        assert.equal((await rewardRows(sidConfirmed)).rows.length, 0,
+          'a confirmed-only task is never paid — the reward waits for a genuine shipped');
+      });
+    }
+  } finally {
+    // FK-safe teardown (credit_log + session_records → builder; tasks → version).
+    if (ctx.builderId != null) {
+      try {
+        await pool.query(`DELETE FROM credit_log WHERE builder_id = $1`, [ctx.builderId]);
+        await pool.query(`DELETE FROM session_records WHERE builder_id = $1`, [ctx.builderId]);
+        await pool.query(`DELETE FROM tasks WHERE version_id = $1`, [ctx.versionId]);
+        await pool.query(`DELETE FROM versions WHERE id = $1`, [ctx.versionId]);
+        await pool.query(`DELETE FROM builders WHERE id = $1`, [ctx.builderId]);
+      } catch (e) {
+        console.log(`  WARN  real-DB teardown left rows (${e.message})`);
+      }
+    }
+  }
+}
+
+await pool.end().catch(() => {});
+summary();

package/tests/session_transcript.mjs

@@ -25,7 +25,7 @@ const economySeams = require('../src/module-seams.js');
 if (!economySeams.hasProvider('reward')) economySeams.registerProvider('reward', require('../modules/economy/reward.js'));
 const buildSessionsRouter = require('../modules/sessions/routes/sessions.js');
 const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
-const { buildSessionTranscript, MAX_FIELD_CHARS } = require('../scripts/gds/session-transcript-build.js');
+const { buildSessionTranscript, MAX_FIELD_CHARS } = require('../scripts/bongos/session-transcript-build.js');
 
 let passed = 0; let failed = 0;
 async function t(name, fn) {

package/tests/sessions_kit_pager.mjs

@@ -306,7 +306,8 @@ await test('a missing kit degrades to a named failure, not a blank page', async
   const h = harness({ total: 320, dropKit: true });
   await tick(); await tick();
   assert.equal(h.searches().length, 0, 'no corpus request without a pager to place it');
-  assert.match(h.getEl('ledger-sub').textContent, /could not be loaded/);
+  // in the page body: the head that used to carry it is hidden (task 1004829)
+  assert.match(h.getEl('gate-body').textContent, /could not be loaded/);
 });
 
 await test('the rank gate still runs before any corpus request', async () => {

package/tests/setup_device_flow_fallback.mjs

@@ -35,11 +35,11 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
-const setup = require('../scripts/gds/setup.js');
+const setup = require('../scripts/bongos/setup.js');
 const ic = require('../src/instance-config.js');
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const SETUP_JS = path.join(REPO_ROOT, 'scripts', 'gds', 'setup.js');
+const SETUP_JS = path.join(REPO_ROOT, 'scripts', 'bongos', 'setup.js');
 
 let passed = 0, failed = 0;
 const t = (name, fn) => {

package/tests/setup_smoke.mjs

@@ -1,4 +1,4 @@
-// Smoke test for scripts/gds/setup.js — verifies a "fresh user" on a different
+// Smoke test for scripts/bongos/setup.js — verifies a "fresh user" on a different
 // machine can run /builder-setup end-to-end without hitting hardcoded paths or
 // names. We simulate that by spawning setup.js with HOME pointed at a throw-
 // away tmp dir, so os.homedir() returns that dir instead of the real one.
@@ -10,8 +10,9 @@
 //
 //   1. The script doesn't crash when no pre-existing session is present.
 //   2. The script resolves every path from $HOME (no /Users/larskristensen leak).
-//   3. The path it would write to is ~/.config/otb/gds-session.json under
-//      whatever HOME points at, not under the developer's real home.
+//   3. The path it would write to is the instance's session file
+//      (~/.config/<configDir>/bongos-session.json) under whatever HOME points
+//      at, not under the developer's real home.
 //   4. The script has no filesystem side effects in --dry-run (no dir created,
 //      no file written, no socket opened against the real GDS).
 //
@@ -23,9 +24,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const SETUP_JS = path.join(REPO_ROOT, 'scripts/gds/setup.js');
+const SETUP_JS = path.join(REPO_ROOT, 'scripts/bongos/setup.js');
+// The session file's WRITE location, derived from the same module setup.js reads it from.
+// It was a literal ~/.config/otb/gds-session.json here, which went stale the day the file
+// was renamed to bongos-session.json under the instance's own config dir (task 1004865).
+const ic = createRequire(import.meta.url)('../src/instance-config.js');
+const sessionWritePath = (home) => path.join(home, '.config', ic.configDirName(), ic.SESSION_FILENAMES[0]);
 
 const tests = [];
 const test = (name, fn) => tests.push({ name, fn });
@@ -54,7 +61,7 @@ test('--dry-run with fresh HOME exits 0 and writes nothing', () => {
     // The session-path message must reference the fake HOME, proving the code
     // resolves the path from os.homedir() and not from a hardcoded literal.
     assert.ok(
-      r.stdout.includes(path.join(fakeHome, '.config/otb/gds-session.json')),
+      r.stdout.includes(sessionWritePath(fakeHome)),
       `expected session path under ${fakeHome} in stdout, got:\n${r.stdout}`,
     );
     // No filesystem side effects: ~/.config/otb should not have been created.

package/tests/setup_status_facts.mjs

@@ -74,6 +74,7 @@ after(() => server.close());
 // ── a small DOM: nodes, text, attributes, and the few selectors the painter asks ────────
 class Node {
   constructor(tag, doc) { this.tagName = String(tag).toUpperCase(); this.doc = doc; this.childNodes = []; this.parentNode = null; this.attrs = {}; this.className = ''; this.hidden = false; this._text = ''; this.writes = 0; this.id = ''; }
+  get classList() { return { add() {}, remove() {}, toggle: (c, on) => { this.classes = this.classes || new Set(); if (on) this.classes.add(c); else this.classes.delete(c); } }; }
   get children() { return this.childNodes.filter((n) => n instanceof Node); }
   get lastChild() { return this.childNodes[this.childNodes.length - 1] || null; }
   get textContent() { return this._text + this.childNodes.map((n) => (n instanceof Node ? n.textContent : n.data)).join(''); }
@@ -115,9 +116,16 @@ function makeDom() {
   el('donePartT', 'span', panel); el('ghState', 'span', panel);
   const bodyEl = el('doneBody', 'div', panel);
   el('setupNow', 'p', bodyEl);
-  el('homeFacts', 'div', bodyEl); el('ghFacts', 'div', bodyEl);
+  // each facts list sits in its group, whose heading is the list's sibling (as the page bakes it)
+  const homeGrp = el('homeGrp', 'div', bodyEl), ghGrp = el('ghGrp', 'div', bodyEl);
+  el('homeFactsH', 'h3', homeGrp); el('homeFacts', 'div', homeGrp);
+  el('ghFactsH', 'h3', ghGrp); el('ghFacts', 'div', ghGrp);
+  el('doneSub', 'p', panel);
   const pick = el('aaPick', 'div', bodyEl); pick.hidden = true;
-  el('hopLink', 'button', bodyEl);
+  const acts = el('doneActs', 'div', bodyEl);
+  el('installBtn', 'a', acts).hidden = true; el('hopLink', 'button', acts);
+  el('wizTip', 'aside', panel); el('wizTipH', 'b', panel); el('wizTipT', 'span', panel); el('wizTipX', 'button', panel);
+  el('setDone', 'ul', panel);
   const alive = el('doneAlive', 'div', bodyEl); alive.hidden = true;
   el('done-h', 'h2', alive); el('enterGenesis', 'a', alive);
   Object.assign(doc, {
@@ -131,7 +139,7 @@ function makeDom() {
 // ── one page, booted on one project, reading the real route ─────────────────────────────
 async function page({ clockShift = 0 } = {}) {
   const dom = makeDom();
-  const calls = { invite: [], arrive: 0, pick: [] };
+  const calls = { invite: [], arrive: 0, pick: [], timers: [] };
   const inflight = [];
   const sandbox = {
     API: '/api/bongos', $: dom.$, document: dom.doc, root: { addEventListener() {}, contains: () => true },
@@ -139,7 +147,7 @@ async function page({ clockShift = 0 } = {}) {
     state: { step: 2, name: 'Kestrel', slug: 'kestrel', owner: 'you', repo: 'kestrel', domain: 'kestrel.cloudbongos.com', noAddress: false },
     resolvedDomain: () => 'kestrel.cloudbongos.com', apexBase: () => 'cloudbongos.com',
     wizPollActive: () => true, wizPollDelay: (ms) => ms,
-    setTimeout: () => 1, clearTimeout() {}, setInterval: () => 1, clearInterval() {},
+    setTimeout: (fn, ms) => { calls.timers.push(ms); return calls.timers.length; }, clearTimeout() {}, setInterval: () => 1, clearInterval() {},
     rememberManifest() {}, syncAppPick: (on) => calls.pick.push(on), paintInviteGate: (on) => calls.invite.push(on), hopArrive: () => { calls.arrive += 1; },
     fetch: (p, init) => { const r = fetch(ORIGIN + p, init); inflight.push(r.then((x) => x.clone().text()).catch(() => null)); return r; },
     Date: class extends Date { static now() { return Date.now() + clockShift; } },
@@ -154,6 +162,7 @@ async function page({ clockShift = 0 } = {}) {
   const read = () => {
     const facts = dom.body.querySelectorAll('[data-fact]').map((f) => ({
       key: f.getAttribute('data-fact'),
+      hidden: f.hidden === true,
       state: f.className.replace(/^setFact /, ''),
       title: f.querySelector('.t')._text,
       sub: (f.querySelector('small') || { textContent: '' }).textContent,
@@ -165,7 +174,9 @@ async function page({ clockShift = 0 } = {}) {
       facts, byKey: Object.fromEntries(facts.map((f) => [f.key, f.state])),
       title: dom.$('donePartT').textContent, count: dom.$('ghState').textContent, said: dom.$('setupNow').textContent,
       aliveHidden: dom.$('doneAlive').hidden, aliveH: dom.$('done-h').textContent, genesis: dom.$('enterGenesis').getAttribute('href'),
-      hopLinkHidden: dom.$('hopLink').hidden, pickInApprove: !!dom.body.querySelector('[data-fact="approve"] .acts') && dom.body.querySelector('[data-fact="approve"] .acts').contains(dom.$('aaPick')),
+      hopLinkHidden: dom.$('hopLink').hidden,
+      installBtn: { hidden: dom.$('installBtn').hidden, href: dom.$('installBtn').getAttribute('href') },
+      setDone: dom.$('setDone').children.map((li) => li.textContent), tipHidden: dom.$('wizTip').hidden, pickInApprove: !!dom.body.querySelector('[data-fact="approve"] .acts') && dom.body.querySelector('[data-fact="approve"] .acts').contains(dom.$('aaPick')),
     };
   };
   const again = async () => { vm.runInContext('progressKick()', sandbox); await settle(); };
@@ -185,19 +196,19 @@ const SCENARIOS = {
     rows: { inst: inst({ status: 'provisioning', created_at: ago(1), provisioned_at: null, last_verified_at: null, last_verified_up: null, dns_resolved_at: null }), intent: { action: 'provision', state: 'running' }, manifest: null, events: [] },
     count: '1 of 6 done',
     states: { address: 'done', server: 'now', answers: 'todo', approve: 'you', install: 'todo', sign_in: 'todo', device_flow: 'todo' },
-    said: 'Setting up its home. You can connect GitHub now; nothing waits on you otherwise.',
+    said: 'Your project is starting. Nothing to do yet. We will ask for your next step here as soon as it is ready.',
   },
   'Waiting on GitHub': {
     rows: { inst: inst({ last_verified_at: null, last_verified_up: null, dns_resolved_at: null }), intent: null, manifest: attempt({ status: 'pending', attempts: 0, created_at: ago(1), expires_at: soon(29) }), events: [] },
     count: '2 of 6 done',
     states: { address: 'done', server: 'done', answers: 'now', approve: 'you', install: 'todo', sign_in: 'todo', device_flow: 'todo' },
-    said: 'Your turn on GitHub: approve the app in the tab that opened. This page ticks on its own when you do, on any device.',
+    said: 'Your turn: approve the app in the GitHub tab that just opened. This page updates by itself when you do.',
   },
   Installing: {
     rows: { inst: inst(), intent: null, manifest: attempt({ status: 'converting', app_id: 5, app_slug: 'kestrel-cloudbongos-com', updated_at: ago(1) }), events: [] },
     count: '4 of 6 done',
     states: { address: 'done', server: 'done', answers: 'done', approve: 'done', install: 'you', sign_in: 'now', device_flow: 'todo' },
-    said: 'Your turn on GitHub: confirm the install on you/kestrel. The repo is already picked.',
+    said: 'Your turn: press “Install it on your repo” below and confirm you/kestrel. Seeing a 404 on GitHub? Sign in as the account that approved the app, or open the install page from the app’s settings.',
   },
   Stopped: {
     rows: { inst: inst(), intent: null, manifest: attempt({ status: 'done', app_id: 5, app_slug: 'kestrel-cloudbongos-com', created_at: ago(300), resolved_at: ago(290), updated_at: ago(290) }), events: [] },
@@ -209,7 +220,7 @@ const SCENARIOS = {
     rows: { inst: inst(), intent: null, manifest: attempt({ status: 'done', app_id: 5, app_slug: 'kestrel-cloudbongos-com', resolved_at: ago(12), updated_at: ago(12) }), events: [installed] },
     count: 'ready ✓',
     states: { address: 'done', server: 'done', answers: 'done', approve: 'done', install: 'done', sign_in: 'done', device_flow: 'todo' },
-    said: 'Kestrel is ready. Command-line sign-in is optional; it ticks itself whenever you turn it on.',
+    said: 'Kestrel is ready. You and your team can now manage your project from here, in its builders hall.',
   },
 };
 const ORDER = ['address', 'server', 'answers', 'approve', 'install', 'sign_in', 'device_flow'];
@@ -239,7 +250,14 @@ for (const name of Object.keys(SCENARIOS)) {
     // Connect GitHub and the account choice sit inside the Approve fact while it is offered
     const approve = v.facts.find((f) => f.key === 'approve');
     assert.equal(approve.acts.includes('manifest-start'), name === 'Just created');
-    assert.equal(v.pickInApprove, name === 'Just created', 'the account select is inside the Approve fact only while Connect is offered');
+    assert.equal(v.pickInApprove, false, 'the account select waits outside until GitHub is shown: the project\'s home has to be up first');
+    // only what is live is shown: working (now), stopped (bad), or the founder's turn with something to press — and no GitHub fact while the home is still starting
+    const homeKeys = ['address', 'server', 'answers'];
+    const homeUp = homeKeys.every((k) => want.states[k] === 'done');
+    const shown = Object.entries(want.states)
+      .filter(([k, st]) => (st === 'now' || st === 'bad' || (st === 'you' && (k === 'install' || v.facts.find((f) => f.key === k).labels.length > 0))) && (homeUp || homeKeys.includes(k)))
+      .map(([k]) => k);
+    assert.deepEqual(v.facts.filter((f) => !f.hidden).map((f) => f.key), shown, 'a step shows only while it is under way, stopped, or the founder\'s turn with a link');
     // a stopped fact carries the one fix
     for (const f of v.facts.filter((x) => x.state === 'bad')) assert.equal(f.acts.filter((a) => a === 'pick-up').length, 1, `${f.key}: one "Pick up where it stopped"`);
     // "is alive", the invite and Enter Genesis only when every required fact is done
@@ -252,6 +270,30 @@ for (const name of Object.keys(SCENARIOS)) {
   });
 }
 
+// ── 1b. the bottom row, the "what was set up" list and the tips ───────────────────────
+test('the install button shows only on the founder\'s turn to install, the set-up list only when ready, the tips only while waiting', async () => {
+  const waiting = (await scenario('Installing')).read();
+  assert.equal(waiting.installBtn.hidden, false, 'it is their turn to install: the button is there');
+  assert.match(waiting.installBtn.href, /^https:\/\/github\.com\/apps\/kestrel-cloudbongos-com\/installations\/new/, 'and opens this app\'s own install page');
+  assert.deepEqual(waiting.setDone, [], 'nothing is listed as set up yet');
+  const early = (await scenario('Just created')).read();
+  assert.equal(early.installBtn.hidden, true, 'no install button while the project is still starting');
+  const done = (await scenario('All done')).read();
+  assert.equal(done.installBtn.hidden, true, 'nor once it is installed');
+  assert.deepEqual(done.setDone, [
+    'Your project is running at kestrel.cloudbongos.com.',
+    'Your code lives in you/kestrel on GitHub.',
+    'Builders can sign in with their GitHub account.',
+    'You and your team can now manage your project from here (its builders hall).',
+  ], 'the checklist gives way to what was set up');
+  // tips: the first one is queued after six seconds while waiting, never once ready
+  const w = await scenario('Installing');
+  assert.ok(w.calls.timers.includes(6000), 'a waiting page queues its first tip');
+  const r = await scenario('All done');
+  assert.ok(!r.calls.timers.includes(6000), 'a ready page queues none');
+  assert.equal(r.read().tipHidden, true, 'and shows none');
+});
+
 // ── 2. every fact's state is a server field ────────────────────────────────────────────
 test('moving the clock moves nothing but the right-hand "when": no fact\'s state is a timer', async () => {
   for (const name of Object.keys(SCENARIOS)) {
@@ -372,7 +414,7 @@ test('the sentence is the one live region, written only when its words change',
   db.manifest = attempt({ status: 'converting', app_id: 5, app_slug: 'kestrel-cloudbongos-com', updated_at: ago(0.2) });
   await p.again();
   assert.ok(line.writes > writes, 'the founder\'s turn moving on is announced');
-  assert.equal(p.read().said, 'Your turn on GitHub: confirm the install on you/kestrel. The repo is already picked.');
+  assert.equal(p.read().said, 'Your turn: press “Install it on your repo” below and confirm you/kestrel. Seeing a 404 on GitHub? Sign in as the account that approved the app, or open the install page from the app’s settings.');
 });
 
 test('a fact\'s buttons are rebuilt only when the fact changes, so a poll never steals the focus', async () => {
@@ -415,7 +457,7 @@ for (const [label, manifest] of Object.entries(elsewhereCases)) {
     const v = (await page()).read();
     assert.deepEqual(v.byKey, { address: 'done', server: 'done', answers: 'done', approve: 'done', install: 'done', sign_in: 'done', device_flow: 'todo' });
     assert.equal(v.count, 'ready ✓');
-    assert.equal(v.said, 'Kestrel is ready. Command-line sign-in is optional; it ticks itself whenever you turn it on.');
+    assert.equal(v.said, 'Kestrel is ready. You and your team can now manage your project from here, in its builders hall.');
     const approve = v.facts.find((f) => f.key === 'approve');
     assert.equal(approve.sub, 'Not needed. Sign-in was set up another way.', 'says why a step it skipped is done');
     assert.deepEqual(approve.acts, [], 'no Connect, Reopen or Pick up for a step that is not needed');

package/tests/ship_autolinkify.mjs

@@ -15,7 +15,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const { isLinkifiableDocPath } = require('../scripts/gds/ship.js');
+const { isLinkifiableDocPath } = require('../scripts/bongos/ship.js');
 
 let passed = 0;
 let failed = 0;
@@ -38,7 +38,7 @@ t('docs/** markdown is in-domain', () => {
 // Out of domain — these must be left alone so the auto-commit can never touch
 // a file the builder didn't change in a doc sense (no scanner-drift surprise).
 t('code files are out of domain', () => {
-  assert.equal(isLinkifiableDocPath('scripts/gds/ship.js'), false);
+  assert.equal(isLinkifiableDocPath('scripts/bongos/ship.js'), false);
   assert.equal(isLinkifiableDocPath('src/bongos/routes/tasks.js'), false);
 });
 t('non-docs markdown outside the roots is out of domain', () => {

package/tests/ship_automerge_injection.mjs

@@ -27,7 +27,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const ship = require('../scripts/gds/ship.js');
+const ship = require('../scripts/bongos/ship.js');
 
 let passed = 0;
 let failed = 0;

package/tests/ship_base_flag.mjs

@@ -11,7 +11,7 @@ import { test } from 'node:test';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const ship = require('../scripts/gds/ship.js');
+const ship = require('../scripts/bongos/ship.js');
 const { resolveBaseRef, computeGraderBaseline, baseRefShipGuard } = ship;
 
 test('resolveBaseRef: rejects empty / whitespace-only refs before touching git', () => {

package/tests/ship_broadcast_routing.mjs

@@ -23,7 +23,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const ship = require('../scripts/gds/ship.js');
+const ship = require('../scripts/bongos/ship.js');
 
 let passed = 0;
 let failed = 0;

package/tests/ship_broadcast_server.mjs

@@ -8,7 +8,7 @@
 //      publish-status reconcile fires. Proves: it routes by the same security
 //      rule, fails CLOSED on an indeterminate flag, skips a no-summary task, and
 //      is best-effort (a throwing webhook never propagates).
-//   2. scripts/gds/ship.js broadcastHandledByServer — the client-side gate that
+//   2. scripts/bongos/ship.js broadcastHandledByServer — the client-side gate that
 //      makes ship.js DEFER to the server on the server path (so the box neither
 //      double-posts nor fails silently), while the laptop keeps posting locally.
 //
@@ -173,7 +173,7 @@ await atest('best-effort: a failing #ship-feed does not cost a feature its #ship
 // Set the env BEFORE requiring ship.js is unnecessary — resolveDeployMode +
 // pushVia read env at CALL time. Requiring ship.js does NOT run main (guarded by
 // require.main===module), so this is side-effect-free.
-const ship = require('../scripts/gds/ship.js');
+const ship = require('../scripts/bongos/ship.js');
 
 function withEnv(env, fn) {
   const saved = {};

package/tests/ship_builder_model.mjs

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const ship = require('../scripts/gds/ship.js');
+const ship = require('../scripts/bongos/ship.js');
 
 let passed = 0;
 let failed = 0;