@bongos/core 1.20.60 → 1.20.62

package/docs/recipes/upgrading-the-core.md

@@ -90,7 +90,7 @@ The sections above are the *manual* `bongos upgrade`. The **subscription** runs
 
 A **major** is never automatic; prereleases are never auto-targeted.
 
-**Where the channel comes from** ([ADR 0357](../adr/0357-the-update-rule-set-on-deploy-is-the-one-the-sweep-follows.md), task [1004468](https://cloudbongos.com/builders#/task/1004468)): the rule set on **/deploy** (`provisioning_instances.update_channel`) wins for any roster entry whose `slug` matches a project row. The roster's `channel` below is only the fallback, used when no row matches or the sweep can't read the database. The sweep reads the control plane's DB from its own `DATABASE_URL` / `PGDATABASE`, so the unit needs one of them set. Every run prints each entry's channel and its source.
+**Where the channel comes from** ([ADR 0357](../adr/0357-the-update-rule-set-on-deploy-is-the-one-the-sweep-follows.md), task [1004468](https://cloudbongos.com/builders#/task/1004468)): the rule set on **/deploy** (`provisioning_instances.update_channel`) wins for any roster entry whose `slug` matches a project row. The roster's `channel` below is only the fallback, used when no row matches or the sweep can't read the database. The sweep reads the control plane's DB from `UPDATE_CHANNEL_DB` (a db name or connection string), else `DATABASE_URL` / `PGDATABASE`. On a control plane, set `UPDATE_CHANNEL_DB`, never `PGDATABASE`: the sweep's env reaches every upgrade it spawns, so a tenant entry with no database of its own would migrate against the control plane's. Every run prints each entry's channel and its source.
 
 **Enrolling an instance** — add it to `config/update-subscriptions.json` (instance-side) (ships empty). `env` carries per-instance vars merged into the upgrade child — set `PGDATABASE` so `migrate` hits the right DB (see the Gotchas):
 
@@ -118,6 +118,35 @@ Each subscribed instance: read its installed core → ask the registry (`npm vie
 
 **Triple-gated, so nothing moves by accident:** the `core-update-subscription` routine is `requiresAutonomy: true` + **default OFF** in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), the roster ships empty, and every upgrade is health-gated. Arm it by enabling the routine's timer on the control plane once autonomy is on.
 
+#### Run the sweep from the installed core (task 1004307)
+
+The sweep's body is `scripts/gds/update-sweep.js`, which ships in every core release.
+`.claude/scheduled-tasks/core-update-subscription/subscribe.js` is only a shim. A control plane
+should run the body **straight from the core it installs**, so each upgrade brings the next sweep
+current code. A sweep run from a checkout is only as new as that checkout, and on cloudbongos.com
+one sat frozen for a month while every fix to the lane went inert. The roster stays where it is;
+`--instance` names it.
+
+```ini
+# /etc/systemd/system/<instance>-core-update-subscription.service.d/run-from-core.conf
+[Service]
+ExecStart=
+ExecStart=/usr/bin/node <served-root>/node_modules/@bongos/core/scripts/gds/update-sweep.js --apply --instance <roster-root>
+Environment=UPDATE_CHANNEL_DB=<control-plane-db>
+```
+
+`<served-root>` is the root the sweep keeps current (the roster entry for the control plane itself);
+`<roster-root>` is where `config/update-subscriptions.json` lives. Prove it with a dry run as the
+unit's user before restarting anything. Its first line names the core doing the sweeping, and each
+entry's line names its channel and source:
+
+```bash
+sudo -u <user> env UPDATE_CHANNEL_DB=<control-plane-db> node <served-root>/node_modules/@bongos/core/scripts/gds/update-sweep.js --instance <roster-root>
+```
+
+Every run prints `update-sweep · running from <core dir> (core <version>) · roster <root>`, so
+`journalctl -u <instance>-core-update-subscription.service` answers "is the box running current code?".
+
 #### How often it sweeps — the lag knob (task 1003674)
 
 **This timer's period IS the delay between a builder's merge and the live site

package/modules/autonomy/db.js

@@ -162,11 +162,11 @@ async function disallowGoal(goalId) {
 // recordRunnerHeartbeat — upsert one host's check-in. ON CONFLICT so the normal
 // case is one write, and `host` is the key so a second runner appears as a second
 // row rather than silently overwriting the first.
-async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt = null, mode = null, consecutiveFailures = null, lastEvent = null, workingTaskId = null, workingGoalId = null }) {
+async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt = null, mode = null, consecutiveFailures = null, lastEvent = null, workingTaskId = null, workingGoalId = null, head = null, diskHead = null, mainHead = null, claudeAccount = null }) {
   const { rows } = await pool.query(
     `INSERT INTO autonomy_runner_heartbeat
-       (builder_id, host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, last_seen_at, updated_at)
-     VALUES ($8, $1, $2, $3, $4, $5, $6, $7, $9, now(), now())
+       (builder_id, host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, head, disk_head, main_head, claude_account, last_seen_at, updated_at)
+     VALUES ($8, $1, $2, $3, $4, $5, $6, $7, $9, $10, $11, $12, $13, now(), now())
      ON CONFLICT (builder_id, host) DO UPDATE SET
        pid = EXCLUDED.pid,
        started_at = COALESCE(EXCLUDED.started_at, autonomy_runner_heartbeat.started_at),
@@ -175,10 +175,16 @@ async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt =
        last_event = EXCLUDED.last_event,
        working_task_id = EXCLUDED.working_task_id,
        working_goal_id = EXCLUDED.working_goal_id,
+       -- Overwritten, never COALESCEd (task 1004407): a fresh process that cannot
+       -- read its own commit must say "unknown", not inherit the last process's.
+       head = EXCLUDED.head,
+       disk_head = EXCLUDED.disk_head,
+       main_head = EXCLUDED.main_head,
+       claude_account = EXCLUDED.claude_account,
        last_seen_at = now(),
        updated_at = now()
-     RETURNING host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, last_seen_at`,
-    [String(host).toLowerCase().slice(0, 255), pid, startedAt, mode, consecutiveFailures, lastEvent, workingTaskId, builderId, workingGoalId]
+     RETURNING host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, head, disk_head, main_head, claude_account, last_seen_at`,
+    [String(host).toLowerCase().slice(0, 255), pid, startedAt, mode, consecutiveFailures, lastEvent, workingTaskId, builderId, workingGoalId, head, diskHead, mainHead, claudeAccount]
   );
   return rows[0] || null;
 }
@@ -193,7 +199,8 @@ async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt =
 // liveness view entirely (grader finding, task 1003905).
 async function readRunnerHeartbeats(builderId) {
   const { rows } = await pool.query(
-    `SELECT host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, last_seen_at
+    `SELECT host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id,
+            head, disk_head, main_head, claude_account, last_seen_at
        FROM autonomy_runner_heartbeat
       WHERE builder_id = $1
       ORDER BY last_seen_at DESC

package/modules/autonomy/migrations/autonomy_004_runner_identity.sql

@@ -0,0 +1,30 @@
+-- autonomy_004_runner_identity.sql — what the runner card can say about a runner
+-- (task 1004407).
+--
+-- Owner ruling, 2026-10-01: the gate page must show which code each runner is
+-- running, whether it is live or restarting, which always-on PC it is on, and
+-- which Claude account its workers spend. `host` already names the PC
+-- (autonomy_002); these four columns carry the rest.
+--
+--   head          the commit the supervisor process is RUNNING (40-char hex)
+--   disk_head     the commit on disk, when the checkout was refreshed in place
+--                 past what is running (task 1004406) — null otherwise
+--   main_head     the newest main the runner has seen, so the card can say
+--                 "behind main" without the server reaching GitHub
+--   claude_account a LABEL for the Claude login its workers use (an email, or
+--                 "API key" / "Claude token" when one is set). Never a token or
+--                 a key: the route caps it at 200 characters and the runner only
+--                 ever sends the label.
+--
+-- Nullable, no defaults: a runner that predates this reports nothing, and the
+-- card says nothing rather than guessing. Additive and idempotent.
+
+BEGIN;
+
+ALTER TABLE autonomy_runner_heartbeat
+  ADD COLUMN IF NOT EXISTS head text,
+  ADD COLUMN IF NOT EXISTS disk_head text,
+  ADD COLUMN IF NOT EXISTS main_head text,
+  ADD COLUMN IF NOT EXISTS claude_account text;
+
+COMMIT;

package/modules/autonomy/routes/autonomy.js

@@ -52,6 +52,11 @@ function runsLimit(raw) {
   return Math.min(RUNS_MAX_LIMIT, Math.max(1, n));
 }
 
+// commitOrNull — a full lowercase commit sha, or null (task 1004407).
+function commitOrNull(v) {
+  return typeof v === 'string' && /^[0-9a-f]{40}$/.test(v) ? v : null;
+}
+
 module.exports = function buildAutonomyRouter() {
   const router = express.Router();
 
@@ -219,6 +224,11 @@ module.exports = function buildAutonomyRouter() {
       last_event: { type: 'string', maxLength: 64 },
       working_task_id: { type: 'number' },
       working_goal_id: { type: 'number' },
+      // What the runner card says about the runner (task 1004407).
+      head: { type: 'string', maxLength: 40 },
+      disk_head: { type: 'string', maxLength: 40 },
+      main_head: { type: 'string', maxLength: 40 },
+      claude_account: { type: 'string', maxLength: 200 },
     })) return;
     const b = req.body || {};
     try {
@@ -234,6 +244,12 @@ module.exports = function buildAutonomyRouter() {
         lastEvent: b.last_event || null,
         workingTaskId: Number.isInteger(b.working_task_id) ? b.working_task_id : null,
         workingGoalId: Number.isInteger(b.working_goal_id) ? b.working_goal_id : null,
+        // A commit is stored only if it IS one: anything that is not 40 hex
+        // characters is dropped to null rather than rendered as a version.
+        head: commitOrNull(b.head),
+        diskHead: commitOrNull(b.disk_head),
+        mainHead: commitOrNull(b.main_head),
+        claudeAccount: typeof b.claude_account === 'string' && b.claude_account.trim() ? b.claude_account.trim() : null,
       });
       res.json({ ok: true, heartbeat: row });
     } catch (err) {

package/modules/autonomy/runner-health.js

@@ -19,6 +19,11 @@
 //     exactly what it is for, and crying dead every time it works is worse than
 //     saying nothing.
 //   · dead       — quiet longer than any legitimate explanation.
+//   · restarting — its last word was "exiting to pick up new code" (upgrade_exit,
+//     task 1004406), and that was recently. The wrapper fetches, resets and
+//     relaunches, which takes a minute or two, and the owner ruled that a restart
+//     must read as a restart, never as a death (task 1004407). Past RESTART_S the
+//     relaunch has failed and it is dead again — with a detail that says so.
 
 // Reasoned from the runner's own numbers, not picked. The loop beats at the top of
 // every pass and again on each poll inside a wait (every 60s), so a healthy runner
@@ -28,6 +33,43 @@ const ALIVE_S = 15 * 60;
 // worker holds the loop for its whole run. Two hours is that ceiling plus room for
 // the ship, the grade and the verify that follow it.
 const LATE_S = 2 * 60 * 60;
+// A relaunch is fetch + reset + boot + the first beat. Ten minutes is several
+// times that, so a slow fetch is not called a death, and short enough that a
+// relaunch which never happened is noticed the same evening.
+const RESTART_S = 10 * 60;
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+const sha = (v) => (typeof v === 'string' && SHA_RE.test(v) ? v : null);
+
+// describeCode — what the card says about the code a runner is on (task 1004407).
+// `behind` is true only when BOTH sides are known and differ: the runner reports
+// the newest main it has seen, and an unknown is never drawn as "out of date".
+// A checkout refreshed in place counts by what is on disk, because that is what
+// every worker and child process runs (task 1004406).
+function describeCode(hb) {
+  const head = sha(hb && hb.head);
+  if (!head) return null;
+  const disk = sha(hb.disk_head);
+  const main = sha(hb.main_head);
+  const current = disk || head;
+  return {
+    head, short: head.slice(0, 8),
+    diskShort: disk && disk !== head ? disk.slice(0, 8) : null,
+    mainShort: main ? main.slice(0, 8) : null,
+    behind: main ? main !== current : null,
+  };
+}
+
+// What the runner was last doing, in words. Keyed on the run-log event names the
+// runner sends as last_event; an unknown event says nothing rather than guessing.
+const ACTIVITY = {
+  boot: 'just started',
+  waiting: 'waiting for work',
+  code_refreshed: 'updated its code in place',
+  nothing_claimable: 'waiting — nothing to claim',
+  fenced: 'held by the fence',
+  hold: 'pausing',
+};
 
 function ageS(lastSeenAt, nowMs) {
   const t = Date.parse(lastSeenAt || '');
@@ -68,19 +110,38 @@ function describeRunner(heartbeat, { nowMs = Date.now(), aliveS = ALIVE_S, lateS
   const mode = heartbeat.mode === 'probing' ? 'probing' : (heartbeat.mode === 'full' ? 'full' : null);
   const working = heartbeat.working_task_id ? String(heartbeat.working_task_id) : null;
   const where = host ? ` on ${host}` : '';
+  const ident = {
+    host, mode, workingTaskId: working,
+    account: typeof heartbeat.claude_account === 'string' && heartbeat.claude_account ? heartbeat.claude_account : null,
+    code: describeCode(heartbeat),
+  };
+
+  if (heartbeat.last_event === 'upgrade_exit') {
+    if (age <= RESTART_S) {
+      return {
+        state: 'restarting', ok: true, ageS: age, age: humanAge(age), ...ident,
+        detail: `restarting${where} to pick up new code`,
+      };
+    }
+    return {
+      state: 'dead', ok: false, ageS: age, age: humanAge(age), ...ident,
+      detail: `exited${where} ${humanAge(age)} ago to restart on new code and has not come back`,
+    };
+  }
 
   if (age <= aliveS) {
+    const doing = ACTIVITY[heartbeat.last_event];
     return {
-      state: 'alive', ok: true, ageS: age, age: humanAge(age), host, mode, workingTaskId: working,
+      state: 'alive', ok: true, ageS: age, age: humanAge(age), ...ident,
       detail: working
         ? `working task ${working}${where}`
-        : `${mode === 'probing' ? 'probing after failures' : 'running'}${where}`,
+        : `${mode === 'probing' ? 'probing after failures' : (doing || 'running')}${where}`,
     };
   }
 
   if (age <= lateS) {
     return {
-      state: 'late', ok: true, ageS: age, age: humanAge(age), host, mode, workingTaskId: working,
+      state: 'late', ok: true, ageS: age, age: humanAge(age), ...ident,
       // Deliberately NOT an alarm. This is what a runner doing its job looks like.
       detail: working
         ? `quiet for ${humanAge(age)} — expected while task ${working} builds`
@@ -89,9 +150,9 @@ function describeRunner(heartbeat, { nowMs = Date.now(), aliveS = ALIVE_S, lateS
   }
 
   return {
-    state: 'dead', ok: false, ageS: age, age: humanAge(age), host, mode, workingTaskId: working,
+    state: 'dead', ok: false, ageS: age, age: humanAge(age), ...ident,
     detail: `no check-in for ${humanAge(age)}${where} — longer than any worker takes, so the runner is not running`,
   };
 }
 
-module.exports = { ALIVE_S, LATE_S, ageS, humanAge, describeRunner };
+module.exports = { ALIVE_S, LATE_S, RESTART_S, ageS, humanAge, describeRunner };

package/modules/hall-ui/public/gate.js

@@ -358,7 +358,7 @@
   // exist here, resolved to inherited grey, and drew a dead runner in exactly the
   // same colour as a healthy one. Named classes cannot fail that way silently —
   // a missing class is visible in the stylesheet, a missing var is not.
-  const HEALTH_CLASS = { alive: 'fact-pill--ok', late: 'fact-pill--warn', dead: 'fact-pill--danger', never_seen: 'fact-pill--info' };
+  const HEALTH_CLASS = { alive: 'fact-pill--ok', late: 'fact-pill--warn', dead: 'fact-pill--danger', never_seen: 'fact-pill--info', restarting: 'fact-pill--info' };
 
   async function loadRunners() {
     const el = document.getElementById('fence-runner');
@@ -384,13 +384,29 @@
       // NOT the word "running": the switch below already uses it for a different
       // thing (allowed to work), and the two lines sit one above the other. A
       // reader should never have to work out which sense is meant.
-      const label = { dead: 'Not checking in', late: 'Quiet', alive: 'Checking in' }[h.state] || 'Unknown';
-      return `<p class="ov-foot" style="display:flex;align-items:baseline;gap:10px;flex-wrap:wrap;">
-        <span class="fact-pill ${cls}">${escapeHtml(label)}</span>
-        <span>${escapeHtml(h.detail || '')}</span>
-        ${r.working_goal_id ? `<span class="ov-fact">from goal ${escapeHtml(String(r.working_goal_id))}</span>` : ''}
-        <span class="ov-fact">last check-in ${escapeHtml(h.age || 'unknown')} ago</span>
-      </p>`;
+      const label = { dead: 'Not checking in', late: 'Quiet', alive: 'Checking in', restarting: 'Restarting' }[h.state] || 'Unknown';
+      // Which PC, which Claude account, which code (task 1004407). Each line is
+      // drawn only when the runner reported it, so an older runner shows less
+      // rather than a guess.
+      const facts = [];
+      if (h.host) facts.push(`<span class="ov-fact">PC <strong>${escapeHtml(h.host)}</strong></span>`);
+      if (h.account) facts.push(`<span class="ov-fact">Claude account ${escapeHtml(h.account)}</span>`);
+      if (h.code) {
+        const c = h.code;
+        const status = c.behind === true ? ` — behind main (${escapeHtml(c.mainShort)})`
+          : c.behind === false ? ' — up to date' : '';
+        const disk = c.diskShort ? `, updated in place to ${escapeHtml(c.diskShort)}` : '';
+        facts.push(`<span class="ov-fact">code <code>${escapeHtml(c.short)}</code>${disk}${status}</span>`);
+      }
+      return `<div class="ov-foot">
+        <p style="display:flex;align-items:baseline;gap:10px;flex-wrap:wrap;margin:0;">
+          <span class="fact-pill ${cls}">${escapeHtml(label)}</span>
+          <span>${escapeHtml(h.detail || '')}</span>
+          ${r.working_goal_id ? `<span class="ov-fact">from goal ${escapeHtml(String(r.working_goal_id))}</span>` : ''}
+          <span class="ov-fact">last check-in ${escapeHtml(h.age || 'unknown')} ago</span>
+        </p>
+        ${facts.length ? `<p style="display:flex;gap:14px;flex-wrap:wrap;margin:4px 0 0;">${facts.join('')}</p>` : ''}
+      </div>`;
     }).join('');
   }
 

package/modules/provisioning/demo.js

@@ -0,0 +1,176 @@
+'use strict';
+
+// modules/provisioning/demo.js — THE DEMO ROUTE: training wheels, a soft time box, and
+// "keep your planet?" (task 1004420 / BV2.PS09, goal 1000121; spec
+// docs/specs/bongos-v2-project-startup.md D3 + D9; design of record
+// docs/design/mocks/project-startup/DemoSetup|DemoReady|DemoKeep.dc.html).
+//
+// A DEMO IS A NORMAL PROJECT MARKED "DEMO" (D9). It is created by the same POST
+// /provisioning/instances as any project, with one more field, and it builds in the
+// normal hall. What makes it a demo is the `demo` jsonb column (provisioning_035):
+//   { people, hours_each, started_at, ends_at, outcome, settled_at, warned_at, offline_at }
+// and the defaults the demo picks for its founder: Monarchy / BDFL is already every new
+// project's government (the government module's default board), so the demo adds only
+// "no rewards" and "all managed" as answers (`detail`), and "private to the team" as
+// settings (the map door closed, joinable by invite only). Everyone uses their own AI
+// plan, which is how every project already works.
+//
+// THE TIME BOX IS SOFT (D3). `ends_at` is the start plus the hours each person said they
+// have, and it only ever drives a countdown and the "keep your planet?" question. Nothing
+// reads it to block or freeze work.
+//
+// A DEMO NOBODY KEEPS GOES OFFLINE AFTER 30 DAYS (D9). The demo-archive poller takes
+// it offline through the existing teardown path, so it is restorable the way any
+// torn-down project is ("bring it back"), with the repo, database and backups kept. The
+// owner is told first: its own project page shows the date from the start, and from
+// three days before it says plainly that the demo is about to go offline. "Carry it over" makes it a real project and the clock never applies again;
+// "keep it as a demo" settles the question but leaves the 30-day rule in place.
+//
+// No route or SQL lives here beyond the small reads and writes the demo needs, so the
+// two oversized files (provisioning.js, routes/provisioning.js) each gain a line, not a
+// feature.
+
+const DEMO_LIMITS = Object.freeze({ people: Object.freeze([1, 12]), hours_each: Object.freeze([1, 40]) });
+const DEMO_OFFLINE_DAYS = 30;
+const DEMO_WARN_DAYS = 3;
+const DAY_MS = 86400000;
+// The demo's picked answers (DemoReady): no rewards, all managed by Bongos. An owner's
+// own answer to either always wins.
+const DEMO_DETAIL = Object.freeze({ reward_intents: Object.freeze([]), framing: 'managed' });
+// Private to the team: off the public map, and joinable by invite only.
+const DEMO_SETTINGS = Object.freeze({ visibility: 'private', joinability: 'invite_only' });
+const OUTCOMES = Object.freeze(['carried', 'kept']);
+
+const intIn = (v, [lo, hi]) => Number.isInteger(v) && v >= lo && v <= hi;
+
+// parseDemo(raw) — PURE. The create request's `demo` field, or why it is refused.
+function parseDemo(raw) {
+  if (raw === undefined || raw === null) return { ok: true, demo: null };
+  if (typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, reason: 'demo must be an object: { people, hours_each }.' };
+  const extra = Object.keys(raw).filter((k) => !['people', 'hours_each'].includes(k));
+  if (extra.length) return { ok: false, reason: `Unknown demo field "${extra[0]}": a demo takes people and hours_each.` };
+  if (!intIn(raw.people, DEMO_LIMITS.people)) return { ok: false, reason: 'people is a whole number from 1 to 12, you included.' };
+  if (!intIn(raw.hours_each, DEMO_LIMITS.hours_each)) return { ok: false, reason: 'hours_each is a whole number from 1 to 40.' };
+  return { ok: true, demo: { people: raw.people, hours_each: raw.hours_each } };
+}
+
+// fitCheck(people, hours) — PURE. The setup screen's first read: builder-hours and what
+// fits in them. The wizard carries a copy of these sentences, held equal by test.
+function fitCheck(people, hours) {
+  const total = people * hours;
+  const verdict = total < 8 ? 'tight' : total < 20 ? 'small' : 'plenty';
+  const sentence = {
+    tight: 'Too tight for this idea. Try one list with voting only, or add hours.',
+    small: 'Enough for a small version. Trim it to one shared list, voting and a winner reveal; accounts and notifications will not fit.',
+    plenty: 'Plenty for this idea, with room for one extra feature.',
+  }[verdict];
+  return { total, verdict, sentence };
+}
+
+// withDemoDetail(detail) — PURE. The demo's picked answers under the owner's own.
+function withDemoDetail(detail) {
+  const own = detail && typeof detail === 'object' && !Array.isArray(detail) ? detail : {};
+  return { ...DEMO_DETAIL, reward_intents: [], ...own };
+}
+
+// demoRecord(demo, now) — PURE. What the column holds at the start.
+function demoRecord(demo, now = new Date()) {
+  return {
+    people: demo.people,
+    hours_each: demo.hours_each,
+    started_at: now.toISOString(),
+    ends_at: new Date(now.getTime() + demo.hours_each * 3600000).toISOString(),
+    outcome: null,
+  };
+}
+
+const ms = (v) => { const t = v ? new Date(v).getTime() : NaN; return Number.isFinite(t) ? t : NaN; };
+
+// demoView(row, now) — PURE. The demo as an owner read shows it, or null for a project
+// that is not one (or was carried over: it is a real project now).
+function demoView(row, now = new Date()) {
+  const d = row && row.demo;
+  if (!d || typeof d !== 'object' || d.outcome === 'carried') return null;
+  const start = ms(d.started_at);
+  const end = ms(d.ends_at);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+  const offline = start + DEMO_OFFLINE_DAYS * DAY_MS;
+  return {
+    people: d.people,
+    hours_each: d.hours_each,
+    builder_hours: fitCheck(d.people, d.hours_each).total,
+    started_at: d.started_at,
+    ends_at: d.ends_at,
+    remaining_seconds: Math.max(0, Math.round((end - now.getTime()) / 1000)),
+    time_up: now.getTime() >= end,
+    outcome: OUTCOMES.includes(d.outcome) ? d.outcome : null,
+    offline_on: new Date(offline).toISOString(),
+    offline_soon: now.getTime() >= offline - DEMO_WARN_DAYS * DAY_MS,
+  };
+}
+
+// The writes. `db` is the pool (or a client); every write is one statement on the row.
+async function startDemo(db, instanceId, demo, now = new Date()) {
+  await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [instanceId, JSON.stringify(demoRecord(demo, now))]);
+}
+
+// startDemoProject — right after the create files a demo's row: mark it, and make it
+// private to the team. Returns the updated row, so the catalog projection that follows
+// sees the closed door rather than the public default for a moment. `provisioning` is
+// passed in (this file must not require it: provisioning.js requires this one).
+async function startDemoProject(db, provisioning, instanceId, demo, now = new Date()) {
+  await startDemo(db, instanceId, demo, now);
+  return provisioning.updateInstanceSettings(db, instanceId, { ...DEMO_SETTINGS });
+}
+
+// settleDemo — the "keep your planet?" answer. Carry it over: the marker's outcome says
+// so and the project is a real one from here on. Keep it as a demo: the question is
+// settled and the 30-day rule still applies. Answered once; a second answer is refused.
+async function settleDemo(db, inst, outcome, now = new Date()) {
+  if (!OUTCOMES.includes(outcome)) return { ok: false, reason: 'bad_outcome' };
+  const d = inst && inst.demo;
+  if (!d || typeof d !== 'object') return { ok: false, reason: 'not_a_demo' };
+  if (d.outcome) return { ok: false, reason: 'already_settled' };
+  const next = { ...d, outcome, settled_at: now.toISOString() };
+  await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [inst.id, JSON.stringify(next)]);
+  return { ok: true, demo: next };
+}
+
+// sweepDemos — the demo-archive poller's tick. For every demo nobody carried over that
+// is still up: stamp the warning three days before (the project page says it is about to go),
+// and at 30 days take it offline through the existing teardown path.
+async function sweepDemos(db, { enqueueTeardown, recordEvent, now = new Date() } = {}) {
+  const { rows } = await db.query(
+    `SELECT id, owner_builder_id, demo, status FROM provisioning_instances
+      WHERE demo IS NOT NULL
+        AND COALESCE(demo->>'outcome', '') <> 'carried'
+        AND demo->>'offline_at' IS NULL
+        AND status NOT IN ('tearing_down', 'torn_down')`,
+  );
+  const out = { warned: 0, offline: 0 };
+  for (const row of rows) {
+    const start = ms(row.demo.started_at);
+    if (!Number.isFinite(start)) continue;
+    const offlineAt = start + DEMO_OFFLINE_DAYS * DAY_MS;
+    if (now.getTime() >= offlineAt) {
+      await enqueueTeardown(db, row.id, null);
+      const next = { ...row.demo, offline_at: now.toISOString() };
+      await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [row.id, JSON.stringify(next)]);
+      if (recordEvent) {
+        await recordEvent(db, { instanceId: row.id, ownerBuilderId: row.owner_builder_id, event: 'demo-offline',
+          detail: { days: DEMO_OFFLINE_DAYS }, actor: 'system:demo-archive' }).catch(() => {});
+      }
+      out.offline += 1;
+    } else if (now.getTime() >= offlineAt - DEMO_WARN_DAYS * DAY_MS && !row.demo.warned_at) {
+      const next = { ...row.demo, warned_at: now.toISOString() };
+      await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [row.id, JSON.stringify(next)]);
+      out.warned += 1;
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  DEMO_LIMITS, DEMO_OFFLINE_DAYS, DEMO_WARN_DAYS, DEMO_DETAIL, DEMO_SETTINGS, OUTCOMES,
+  parseDemo, fitCheck, withDemoDetail, demoRecord, demoView, startDemo, startDemoProject, settleDemo, sweepDemos,
+};

package/modules/provisioning/migrations/provisioning_035_demo.sql

@@ -0,0 +1,26 @@
+-- provisioning_035_demo.sql — the demo marker on a project (task 1004420, BV2.PS09; goal
+-- 1000121, spec docs/specs/bongos-v2-project-startup.md D3 + D9).
+--
+-- WHY THIS EXISTS. The front door's "Try the demo" route creates a normal project marked
+-- "demo" (D9): a small team tries Bongos in a few hours and keeps what they made. The mark
+-- has to live on the project row, because the hub reads it for the countdown and the
+-- "keep your planet?" question, and the demo-archive poller reads it to take a demo
+-- nobody kept offline after 30 days.
+--
+-- WHAT IT ADDS.
+--   provisioning_instances.demo — NULL for every ordinary project. For a demo:
+--     { people, hours_each, started_at, ends_at, outcome, settled_at, warned_at, offline_at }
+--     written at create (modules/provisioning/demo.js demoRecord), then by the "keep your
+--     planet?" answer (outcome 'carried' | 'kept') and by the poller (warned_at, offline_at).
+--
+-- A column and not a `detail` key: detail is what the OWNER said, editable and
+-- un-answerable by them; this is platform state an owner must not be able to erase to
+-- dodge the archive. Nullable, no backfill: no project before this was a demo.
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_instances ADD COLUMN IF NOT EXISTS demo jsonb;
+
+COMMIT;

package/modules/provisioning/module.json

@@ -1,7 +1,7 @@
 {
   "key": "provisioning",
   "title": "Instance provisioning",
-  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state \u2014 it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
+  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state — it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
   "version": "1.0.0",
   "coreVersion": "^1.14.0",
   "default": false,
@@ -20,13 +20,15 @@
       "env-manifest",
       "repo-private",
       "render-standup",
-      "look"
+      "look",
+      "demo"
     ],
     "migrations": true,
     "pollers": [
       "liveness-sweep",
       "catalog-backfill",
-      "app-liveness"
+      "app-liveness",
+      "demo-archive"
     ]
   },
   "provides": [

package/modules/provisioning/pollers/demo-archive.js

@@ -0,0 +1,61 @@
+'use strict';
+
+// modules/provisioning/pollers/demo-archive.js — a demo nobody kept goes offline after 30
+// days, and its owner is told first (task 1004420, BV2.PS09; spec D9).
+//
+// One sweep an hour over the demo-marked projects (demo.js sweepDemos): from three days
+// before, a demo carries its offline date on its own card (the warning); at 30 days it is
+// taken offline through the existing teardown intent, so it is restorable the way any
+// torn-down project is. A demo carried over is a real project and is never swept.
+// Kill-switched by PROVISIONING_DEMO_ARCHIVE_DISABLED=1; the liveness sweep's shape
+// (self-rescheduling, jittered, unref'd, idempotent start).
+
+const api = require('../../../src/module-api');
+const provisioning = require('../provisioning');
+const demo = require('../demo');
+
+const log = api.logger('provisioning');
+
+const INTERVAL_MS = 60 * 60 * 1000;
+const FIRST_SWEEP_DELAY_MS = 5 * 60 * 1000;
+const JITTER_MS = 5 * 60 * 1000;
+
+let started = false;
+let timer = null;
+
+async function sweepOnce(deps = {}) {
+  const db = deps.pool || api.pool;
+  const out = await demo.sweepDemos(db, {
+    enqueueTeardown: deps.enqueueTeardown || provisioning.enqueueTeardown,
+    recordEvent: deps.recordEvent || provisioning.recordEvent,
+    now: deps.now,
+  });
+  if (out.warned || out.offline) log.info(`[demo-archive] warned ${out.warned}, took ${out.offline} offline`);
+  return out;
+}
+
+function arm(deps, delay) {
+  timer = setTimeout(() => {
+    sweepOnce(deps)
+      .catch((e) => log.error(`[demo-archive] sweep crashed: ${e && e.message ? e.message : e}`))
+      .then(() => { if (started) arm(deps, INTERVAL_MS + Math.floor(Math.random() * JITTER_MS)); });
+  }, delay);
+  if (timer.unref) timer.unref();
+}
+
+function start(deps = {}) {
+  if (process.env.PROVISIONING_DEMO_ARCHIVE_DISABLED === '1') {
+    log.info('[demo-archive] disabled (PROVISIONING_DEMO_ARCHIVE_DISABLED=1)');
+    return;
+  }
+  if (started) return;
+  started = true;
+  arm(deps, FIRST_SWEEP_DELAY_MS);
+}
+
+function stop() {
+  started = false;
+  if (timer) { clearTimeout(timer); timer = null; }
+}
+
+module.exports = { start, stop, sweepOnce, INTERVAL_MS };

package/modules/provisioning/provisioning.js

@@ -23,7 +23,7 @@ const { normalizeModuleSelection, effectiveModules } = require('./starter-bundle
 // pure declarations beside this file, for the same reason: storage and the read
 // projection both have to read them.
 const { PLANET_PHYSICS_QUESTIONS, canonicalAnswer } = require('./planet-physics');
-const { softLimitsFor } = require('./soft-limits');
+const { softLimitsFor } = require('./soft-limits'); const { demoView } = require('./demo');   // the demo marker's owner view (task 1004420)
 const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look');
 
 // ---------------------------------------------------------------------------
@@ -450,7 +450,7 @@ function publicInstance(row) {
     detail,
     // Which startup options those answers hide, grey or annotate, each with its reason
     // (BV2.PS02, spec D6). Advice only — `enforced: false` says so on every read.
-    soft_limits: softLimitsFor(detail),
+    soft_limits: softLimitsFor(detail), demo: demoView(row),   // null unless a demo nobody carried over (task 1004420, ./demo.js)
     // The creation picker's module set (task 1002339): the always-on core, what
     // the owner ends up with, and whether that came from their own toggles or
     // from the type's starter bundle because they never answered. Resolved, not