@bongos/core 1.19.82 → 1.19.84

package/docs/design/projects-surfaces-redesign-direction.md

@@ -19,6 +19,7 @@ Scope: the three owner-facing project surfaces — the **create wizard** (`publi
 
 1. **Truth model: heartbeat + honest chips.** The platform re-checks liveness on a background cadence and the UI shows verification recency. "Live" becomes a verified claim.
 2. **Visual system: sunrise, tokenized — refined through design iterations.** Keep the sunrise landing brand; extract a shared token + component layer; the final look is nailed down through owner-review loops during implementation (§10), not invented in this doc.
+   > **Amended in Loop 1 (owner, 2026-08-12, during task 1002696):** the iteration loops did their job and moved the look — these surfaces go **all-in on the space backdrop** (the gate's deep-space sky, stars, project orbs), with a **light/dark mode** governing the content cards (light = cream cards on space, dark = deep-navy cards; OS preference honored, manual toggle persisted). The token layer ships as `public-landing/assets/cosmos.css`. Everything else in this doc (truth model, vocabulary, copy rules, flows) is unchanged.
 3. **First-run: designed now, delivered split.** This direction defines the shape-aware surfaces; task 1002696 implements the surface parts, and runner/infra hardening stays in its parallel lane (tasks 1002717–1002722).
 4. **Deliverable: this direction doc.** Owner sign-off on this doc is the task's done condition.
 
@@ -113,7 +114,7 @@ Beats stay **Name · Home · Address · Create** — the flow shape survives; th
 |---|---|---|
 | Done panel promises a runner self-hosts don't have (task 1002717) | Shape-aware plan rendering (§7) | **task 1002696** |
 | `FIRST_ADMIN` invisible — first user bounced to a nonexistent Owner (task 1002717) | A virgin instance's sign-in surface says plainly: "No one is admitted yet — the instance operator names the first admin," and points at the one-line fix (env var / branding field) | copy surface with task 1002696 where it lives in core UI; self-host docs + recipe with the **1002717 lane** |
-| Newborn instance greets its founder with "your art coverage has ended" (idea 1000701) | §5.6 welcome + nag suppression until first-run completes | **task 1002696** if it stays a small `needs`-gating change; otherwise spun out as its own task |
+| Newborn instance greets its founder with "your art coverage has ended" (idea 1000701) | §5.6 welcome + nag suppression until first-run completes | **Spun out as task 1002739** (decided during task 1002696: it lives on the CHILD instance's hall + needs roster, not on the control-plane surfaces this task owns — the "otherwise" branch of the split below) |
 | `/create` + `/projects` unreachable on single-origin self-hosts (task 1002717) | Out of this direction's hands — a mounting/architecture question | **1002717 lane** |
 | Runner assumes the founder's box six ways; founder-identity hardcodes (tasks 1002718, 1002719) | Not a surface concern | **hardening lane** |
 | Refuse-unknown dispatch + runner-drift gate (task 1002722) | Not a surface concern | **hardening lane** |
@@ -133,7 +134,7 @@ Beats stay **Name · Home · Address · Create** — the flow shape survives; th
 
 ## 11. Scope boundaries
 
-**In (task 1002696 implements):** the three surfaces rebuilt on the shared token/component layer; heartbeat sweep + two columns + API exposure; chip overlay + per-flow strips; owner-voice copy pass incl. error categories + disclosures; address-step collapse (task 1002704); repo-visibility statements; Bring-it-back + Try-again actions; nav doors (gate, done panel); shape-aware done panel; newborn welcome/nag suppression (if small).
+**In (task 1002696 implements):** the three surfaces rebuilt on the shared token/component layer; heartbeat sweep + two columns + API exposure; chip overlay + per-flow strips; owner-voice copy pass incl. error categories + disclosures; address-step collapse (task 1002704); repo-visibility statements; Bring-it-back + Try-again actions; nav doors (gate, done panel); shape-aware done panel. **Not** the newborn welcome — that landed as task 1002739 (see §9).
 
 **Parallel (hardening lane, already seeded):** provision-time healthz gating, no-hook attach honesty, teardown-vs-dropdb reality, manifest race + spent-code fix (task 1002720); self-host reachability + FIRST_ADMIN recipe (task 1002717); runner assumptions (task 1002718); founder-identity hardcodes (task 1002719); dispatch/drift gates (task 1002722).
 

package/modules/lifecycle/github-push.js

@@ -492,6 +492,87 @@ async function getPublishStatus({ branch }, deps = {}) {
   };
 }
 
+// probeDeployVisibility (task 1002733) — can this instance's publish credential READ
+// the Actions API at all?
+//
+// WHY THIS EXISTS. getPublishStatus's deploy probe answers a question about ONE
+// workflow, and on a private repo GitHub deliberately blurs "not there" and "not
+// yours" — both can surface as 404. So a single call cannot distinguish "this repo
+// has no deploy-prod.yml" (fine; the merge is the land, ADR 0108) from "this token
+// cannot see Actions" (a silent misconfiguration that made task 1002695 strand at
+// confirmed across 4 sweeps on 2026-08-12). Until task 1002724 there was no way to
+// tell them apart without a shell on the host and a hand-run of the API.
+//
+// The fix is a CONTROL call: list the repo's workflows. If that succeeds we can read
+// Actions, so a 404 on deploy-prod.yml genuinely means the file is absent. If the
+// list itself is refused, the credential is blind and every deploy verdict it gives
+// is meaningless.
+//
+// ADR 0055 specifies this credential as Contents rw + Pull requests rw + Actions:
+// read. NOTE resolveToken precedence is deps.token > App installation token > PAT, so
+// an instance runs on ONE of them and the other is irrelevant: a correctly-scoped PAT
+// can be masked by a narrower App grant, and equally an App that was never configured
+// means the PAT is live no matter what the ADR's history says. cloudbongos.com is the
+// second case — checked 2026-08-12, web.env sets GITHUB_PUSH_TOKEN and no GITHUB_APP_*.
+// The remediation string below resolves which one is live rather than guessing.
+async function probeDeployVisibility(deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) {
+    return { state: 'no_credential', http: null, detail: 'no push credential configured (GITHUB_PUSH_TOKEN / App)', remediation: null };
+  }
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) {
+    return { state: 'no_repo_info', http: null, detail: 'repo owner/name could not be resolved', remediation: null };
+  }
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const api = `https://api.github.com/repos/${owner}/${repo}`;
+  // Name the credential that is ACTUALLY live, so the remediation points at the right
+  // one. resolveToken() prefers the App and falls back to GITHUB_PUSH_TOKEN, so an
+  // instance can be on either — and cloudbongos.com is on the PAT despite ADR 0055's
+  // history saying the App replaced it (task 1002733).
+  const live = appConfigured() ? 'the GitHub App (GITHUB_APP_* are set — it wins over any PAT)' : 'the PAT in GITHUB_PUSH_TOKEN (no GITHUB_APP_* configured)';
+  const GRANT = `Grant 'Actions: read' on ${owner}/${repo} to ${live} (ADR 0055).`;
+
+  let listRes;
+  try {
+    listRes = await doFetch(`${api}/actions/workflows?per_page=1`, { headers: ghHeaders(token) });
+  } catch (e) {
+    return { state: 'unknown', http: null, detail: `workflows list threw: ${e && e.message}`, remediation: null };
+  }
+  if (!listRes.ok) {
+    return {
+      state: 'blind',
+      http: listRes.status,
+      detail: `cannot list workflows (HTTP ${listRes.status}) — every deploy verdict from this credential is unreliable`,
+      remediation: GRANT,
+    };
+  }
+
+  // Actions is readable. Now the specific workflow: present, or genuinely absent?
+  let runsRes;
+  try {
+    runsRes = await doFetch(`${api}/actions/workflows/deploy-prod.yml/runs?branch=main&per_page=1`, { headers: ghHeaders(token) });
+  } catch (e) {
+    return { state: 'unknown', http: null, detail: `workflow-runs threw: ${e && e.message}`, remediation: null };
+  }
+  if (runsRes.ok) {
+    return { state: 'readable', http: runsRes.status, detail: 'Actions readable; deploy-prod.yml present — the deploy gate is real', remediation: null };
+  }
+  if (runsRes.status === 404) {
+    return {
+      state: 'readable_no_workflow', http: 404,
+      detail: 'Actions readable and deploy-prod.yml is genuinely absent — the merge IS the land (ADR 0108 pin-bump publishing)',
+      remediation: null,
+    };
+  }
+  return {
+    state: 'blind', http: runsRes.status,
+    detail: `workflows list succeeded but deploy-prod.yml runs returned HTTP ${runsRes.status}`,
+    remediation: GRANT,
+  };
+}
+
 // task 1547 — does the PR matched by getPublishStatus actually belong to THIS task?
 // The robust land proof is published-tip containment; this is the fallback used when
 // no published tip was recorded (a legacy row, or a publish in flight across the
@@ -1145,6 +1226,7 @@ module.exports = {
   GATE_OWNER_APPROVED_CONTEXT,
   landConfirmed,
   deployProbeBlind,
+  probeDeployVisibility,
   landProvenForTask,
   prReferencesTask,
   findTaskPullRequest,

package/modules/provisioning/migrations/provisioning_006_liveness.sql

@@ -0,0 +1,30 @@
+-- provisioning_006_liveness.sql — the VERIFICATION OVERLAY on an instance's
+-- lifecycle (task 1002696; docs/design/projects-surfaces-redesign-direction.md §3).
+--
+-- WHY. `status` records what the RUNNER did, not what the instance actually does:
+-- once a standup script finished, a row stays 'active' forever and no later
+-- observation can ever correct it. The projects surfaces then assert "live" for an
+-- instance nobody has spoken to since the day it was created — the walk's core
+-- truthfulness failure. These two columns record what a probe actually SAW, so the
+-- UI can carry recency ("live · checked 2m ago") and say "unreachable" when the
+-- platform knows better.
+--
+-- OVERLAY, NOT A STATE. Verification never becomes a seventh lifecycle status: the
+-- runner's six states are untouched, an unreachable instance is still 'active', and
+-- nothing in the heartbeat path writes `status`. Both columns are NULLABLE with no
+-- default on purpose — NULL means "never probed", which is a different claim from
+-- last_verified_up=false ("probed, and it did not answer"), and the display contract
+-- renders those differently (live? vs unreachable).
+--
+-- Adding nullable columns is ADDITIVE: no existing row changes, nothing is lost, and
+-- every row correctly backfills to "never probed" (it never was). Safe under the
+-- module-owned-migration rule (ADR 0083 §Decision #5). Idempotent: safe to re-run.
+
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS last_verified_at timestamptz;
+
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS last_verified_up boolean;
+
+INSERT INTO schema_migrations (version) VALUES ('provisioning_006_liveness')
+  ON CONFLICT (version) DO NOTHING;

package/modules/provisioning/module.json

@@ -11,7 +11,8 @@
   "maintenance": { "status": "core-maintained" },
   "contributes": {
     "routes": ["provisioning"],
-    "migrations": true
+    "migrations": true,
+    "pollers": ["liveness-sweep"]
   },
   "provides": ["provisioning.instanceState"],
   "consumes": []

package/modules/provisioning/onboard-plan.js

@@ -21,19 +21,29 @@
 // hall address when the renderer knows the domain, and falls back to the `bongos dev`
 // local-hall one-liner when it doesn't — the hall is the point of creating a project,
 // so the sequence must end there, not at brand.
+//
+// `shapes` (task 1002696; direction §7 — a surface renders only steps somebody real
+// will perform on THIS instance's shape). The control-plane shapes (standalone /
+// co-tenant / dedicated) have the platform's runner performing every 'auto' leg;
+// 'self-host' has no runner, so the runner-performed legs are absent from its plan —
+// a self-host form must never promise them (QA walk finding, task 1002717). Steps
+// with no `shapes` apply everywhere. Filter with stepsForShape().
+const CONTROL_PLANE_SHAPES = ['standalone', 'co-tenant', 'dedicated'];
+const ALL_SHAPES = [...CONTROL_PLANE_SHAPES, 'self-host'];
+
 function onboardPlan(mode = 'greenfield', opts = {}) {
   const adopt = mode === 'adopt';
   const domain = typeof opts.domain === 'string' && opts.domain.trim() ? opts.domain.trim() : null;
   return [
     { key: 'name-address', kind: 'auto', label: 'Decide name + address (interview)' },
     { key: 'github-repo', kind: 'human', label: adopt ? 'Use your EXISTING GitHub repository' : 'Create the empty GitHub repository' },
-    { key: 'dns-preflight', kind: 'auto', label: 'DNS token preflight — before the address step (task 1980)' },
+    { key: 'dns-preflight', kind: 'auto', shapes: CONTROL_PLANE_SHAPES, label: 'DNS token preflight — before the address step (task 1980)' },
     { key: 'init', kind: 'auto', label: adopt ? 'bongos init --adopt — LAYER onto the existing repo (pre-flight + accept)' : 'bongos init — scaffold the instance config' },
     { key: 'scaffold', kind: 'auto', label: adopt ? 'Layer config + pinned @bongos/core onto the existing repo (no clobber)' : 'Scaffold the standalone repo (own repo + pinned @bongos/core)' },
-    { key: 'provision', kind: 'auto', label: 'Provision core + DB + address + service (standalone, task 1978)' },
+    { key: 'provision', kind: 'auto', shapes: CONTROL_PLANE_SHAPES, label: 'Provision core + DB + address + service (standalone, task 1978)' },
     { key: 'seed-version', kind: 'auto', label: 'Seed the first version (V1) so the instance can take tasks immediately (task 2119)' },
     { key: 'oauth-app', kind: 'human', label: 'Wire GitHub sign-in — one-click GitHub App (task 2080), or a manual OAuth app' },
-    { key: 'oauth-place', kind: 'auto', label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
+    { key: 'oauth-place', kind: 'auto', shapes: CONTROL_PLANE_SHAPES, label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
     { key: 'first-sign-in', kind: 'human', label: 'First sign-in (seats the founding Archon)' },
     { key: 'verify', kind: 'auto', label: 'Verify /healthz auth_configured' },
     { key: 'brand', kind: 'auto', label: 'Brand the instance look' },
@@ -43,4 +53,10 @@ function onboardPlan(mode = 'greenfield', opts = {}) {
   ];
 }
 
-module.exports = { onboardPlan };
+// A step with no `shapes` occurs on every shape; otherwise the list is exhaustive.
+function stepsForShape(steps, shape) {
+  if (!shape || !ALL_SHAPES.includes(shape)) return steps;
+  return steps.filter((s) => !s.shapes || s.shapes.includes(shape));
+}
+
+module.exports = { onboardPlan, stepsForShape, ALL_SHAPES, CONTROL_PLANE_SHAPES };

package/modules/provisioning/pollers/liveness-sweep.js

@@ -0,0 +1,266 @@
+'use strict';
+
+// modules/provisioning/pollers/liveness-sweep.js — the heartbeat behind the
+// VERIFICATION OVERLAY (task 1002696; docs/design/projects-surfaces-redesign-
+// direction.md §3). The loader's startModulePollers requires this file and calls
+// start(deps) at boot / stop() at shutdown, for the ENABLED module only — the
+// platform-identity code-sweep / lifecycle publish-reconciler poller shape.
+//
+// WHY. `status` records what the RUNNER did. Once its script finished, a row sits
+// at 'active' forever and no later observation can correct it, so the projects
+// surfaces assert "live" for instances nobody has spoken to since creation. This
+// sweep knocks on every active instance's /healthz and records what it actually
+// saw, so the UI can carry recency and say "unreachable" when the platform knows
+// better.
+//
+// THE ONE RULE: it NEVER writes `status`. Verification is an overlay on lifecycle,
+// not a new lifecycle state — an unreachable instance is still 'active' (its
+// teardown/revive story is unchanged), and only the runner authors lifecycle. The
+// narrowness is enforced downstream too: recordLivenessProbe touches exactly the
+// two overlay columns.
+//
+// Best-effort throughout: a probe failure IS the signal (down), and a DB/network
+// hiccup logs and waits for the next sweep. Timers are unref'd so the heartbeat
+// never holds the process open.
+
+const dns = require('node:dns').promises;
+const { Agent: UndiciAgent } = require('undici');
+const api = require('../../../src/module-api');
+const provisioning = require('../provisioning');
+
+// ~5-minute cadence — matches the display contract's "fresh ≤ 2 cadences" window
+// and is cheap: one HTTP GET per active instance. Override for tests/ops.
+const INTERVAL_MS = Number(process.env.PROVISIONING_LIVENESS_MS) || 5 * 60_000;
+// Jitter so a fleet of control planes (and a restarted one) never lands its probes
+// on the same wall-clock second forever.
+const JITTER_MS = Number(process.env.PROVISIONING_LIVENESS_JITTER_MS) || 30_000;
+// A first sweep a few seconds after boot: a freshly-restarted control plane should
+// not show a 5-minute-stale overlay on every card.
+const FIRST_SWEEP_DELAY_MS = Number(process.env.PROVISIONING_LIVENESS_FIRST_MS) || 8_000;
+// Short: a healthy instance answers /healthz in milliseconds, and a slow one is
+// indistinguishable from down to the owner staring at the card.
+const PROBE_TIMEOUT_MS = Number(process.env.PROVISIONING_LIVENESS_TIMEOUT_MS) || 5_000;
+// Runaway guard, not an expected limit.
+const SWEEP_LIMIT = 200;
+// Keep the one-line account readable on a big fleet.
+const MAX_REASONS_SHOWN = 8;
+
+let timer = null;
+let started = false;
+
+// Where the heartbeat knocks. The public address when the instance has one — that
+// IS what an owner's "live" claim means — else the recorded loopback port on this
+// box (a co-tenant/standalone instance not yet addressed). normalizeHostname keeps
+// a junk domain from producing a bogus URL. null ⇒ unprobeable: the sweep leaves
+// such a row's overlay untouched rather than recording a verdict it never observed.
+function healthzUrl({ domain, port } = {}) {
+  const host = provisioning.normalizeHostname(domain);
+  if (host) return `https://${host}/healthz`;
+  const p = Number(port);
+  return Number.isInteger(p) && p > 0 && p < 65536 ? `http://127.0.0.1:${p}/healthz` : null;
+}
+
+// ── SSRF guard (grader blocker, 2026-08-12). `domain` is builder-settable with
+// syntax-only validation, and this sweep fetches it from the control plane's
+// network position on a cadence — without a gate, a builder could point their
+// instance at 169.254.169.254 (cloud metadata), 127.0.0.1, or an internal host
+// and read the live/unreachable chip as a blind SSRF confirmation oracle.
+// The gate: IP-literal domains and hostnames that RESOLVE to a private/reserved
+// range are never probed and get NO verdict (constant behavior ⇒ no oracle).
+// An unresolvable hostname still probes — the fetch's own ENOTFOUND records an
+// honest "down", the common real-world case (a domain whose DNS isn't set up).
+// Rebinding-proof: the gate returns the address it vetted and the probe PINS its
+// connection to it (undici connect.lookup) — a builder-run nameserver answering
+// differently per query cannot re-aim the fetch at a private target.
+function isIpLiteral(host) {
+  return /^\d+\.\d+\.\d+\.\d+$/.test(host) || String(host).includes(':');
+}
+// Loopback, RFC1918, link-local/metadata, CGNAT, benchmarking, unspecified —
+// plus v6 loopback/link-local/ULA and v4-mapped forms. Junk parses as private.
+function isPrivateAddress(addr) {
+  const a = String(addr || '').toLowerCase();
+  if (a.includes(':')) {
+    if (a === '::' || a === '::1') return true;
+    if (a.startsWith('fe80:') || a.startsWith('fc') || a.startsWith('fd')) return true;
+    const mapped = a.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    return mapped ? isPrivateAddress(mapped[1]) : false;
+  }
+  const p = a.split('.').map(Number);
+  if (p.length !== 4 || p.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  if (p[0] === 0 || p[0] === 10 || p[0] === 127) return true;
+  if (p[0] === 100 && p[1] >= 64 && p[1] <= 127) return true;
+  if (p[0] === 169 && p[1] === 254) return true;
+  if (p[0] === 172 && p[1] >= 16 && p[1] <= 31) return true;
+  if (p[0] === 192 && p[1] === 168) return true;
+  if (p[0] === 198 && (p[1] === 18 || p[1] === 19)) return true;
+  return false;
+}
+// allowed:false ⇒ do not probe (and record nothing). Only ip-literal and
+// private-resolving hosts are refused; resolution failure falls through to the
+// probe so ENOTFOUND stays an honest "down".
+async function domainProbeGate(host, { lookup } = {}) {
+  if (isIpLiteral(host)) return { allowed: false, reason: 'ip-literal' };
+  try {
+    const addrs = await (lookup || dns.lookup)(host, { all: true, verbatim: true });
+    const list = Array.isArray(addrs) ? addrs.filter((x) => x && x.address) : [];
+    if (list.some((x) => isPrivateAddress(x.address))) return { allowed: false, reason: 'private-address' };
+    // hand back the vetted address so the probe can pin to it (no re-resolution)
+    return list.length ? { allowed: true, pin: list[0] } : { allowed: true };
+  } catch (e) {
+    return { allowed: true }; // unresolvable — the probe itself records the honest down
+  }
+}
+
+// Pin the connection to the address the gate vetted. undici resolves via this
+// lookup instead of the OS resolver, so the fetch cannot land anywhere else —
+// closing the resolve-then-fetch rebinding window (grader round 2).
+function pinnedDispatcher(pin, timeoutMs) {
+  const family = pin.family === 6 ? 6 : 4;
+  return new UndiciAgent({
+    connect: {
+      timeout: timeoutMs,
+      // undici calls this with { all: true }, which wants the array form;
+      // honor both so the shim is correct either way.
+      lookup: (_hostname, opts, cb) => (opts && opts.all
+        ? cb(null, [{ address: pin.address, family }])
+        : cb(null, pin.address, family)),
+    },
+  });
+}
+
+// The owner-facing shorthand for why a probe failed — a connection code
+// ('ECONNREFUSED'), 'timeout', or the HTTP status. Only ever a log detail.
+function probeReason(err) {
+  if (!err) return 'error';
+  if (err.name === 'TimeoutError' || err.name === 'AbortError') return 'timeout';
+  const code = (err.cause && err.cause.code) || err.code;
+  if (code) return String(code);
+  return err.message ? String(err.message).slice(0, 40) : 'error';
+}
+
+// Knock once. Any 2xx = up; everything else (non-2xx, refused, DNS, TLS, timeout)
+// = down with a reason. Never throws — a probe result is the whole point.
+async function probeHealthz(url, { timeoutMs = PROBE_TIMEOUT_MS, fetchImpl, pin } = {}) {
+  const doFetch = fetchImpl || globalThis.fetch;
+  const dispatcher = pin && !fetchImpl ? pinnedDispatcher(pin, timeoutMs) : null;
+  try {
+    const res = await doFetch(url, {
+      method: 'GET',
+      // manual: a redirect must never re-aim the probe (SSRF pivot) — and a
+      // healthz that redirects isn't answering anyway.
+      redirect: 'manual',
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: { accept: 'application/json, text/plain;q=0.9, */*;q=0.8' },
+      ...(dispatcher ? { dispatcher } : {}),
+    });
+    if (res.status >= 200 && res.status < 300) return { up: true };
+    return { up: false, reason: `http ${res.status}` };
+  } catch (e) {
+    return { up: false, reason: probeReason(e) };
+  } finally {
+    if (dispatcher) dispatcher.close().catch(() => {});
+  }
+}
+
+// The per-sweep disposition line (the publish-reconciler's one-line account).
+// PURE, so its wording is unit-tested without a sweep:
+//   [liveness] swept 6 active: 4 up · 2 down (mercury:ECONNREFUSED, swag:timeout)
+function formatSweepLine({ swept = 0, up = 0, down = 0, unprobeable = 0, blocked = 0, blockedReasons = [], reasons = [] } = {}) {
+  const shown = reasons.slice(0, MAX_REASONS_SHOWN).join(', ');
+  const more = reasons.length > MAX_REASONS_SHOWN ? `, +${reasons.length - MAX_REASONS_SHOWN} more` : '';
+  const detail = reasons.length ? ` (${shown}${more})` : '';
+  const unaddressed = unprobeable ? ` · ${unprobeable} unaddressed` : '';
+  const blockedPart = blocked
+    ? ` · ${blocked} blocked${blockedReasons.length ? ` (${blockedReasons.slice(0, MAX_REASONS_SHOWN).join(', ')})` : ''}`
+    : '';
+  return `[liveness] swept ${swept} active: ${up} up · ${down} down${detail}${unaddressed}${blockedPart}`;
+}
+
+// One tick: probe every active instance and record what was seen. Exported +
+// dependency-injected (pool, fetchImpl, timeoutMs, log) so it is driven directly
+// by the tests — the timer is only a schedule.
+async function sweepOnce(deps = {}) {
+  const db = deps.pool || api.pool;
+  const log = deps.log || console.log;
+  const rows = await provisioning.listActiveInstancesForLiveness(db, { limit: SWEEP_LIMIT });
+
+  const results = await Promise.all(rows.map(async (row) => {
+    const url = healthzUrl(row);
+    if (!url) return { row, probed: false };
+    // domain probes pass the SSRF gate first; a blocked row gets NO verdict —
+    // its overlay simply never advances (constant behavior, no oracle). The
+    // gate's vetted address is PINNED into the probe so DNS cannot change
+    // under us between the check and the connection.
+    let pin = null;
+    if (url.startsWith('https://')) {
+      const gate = await domainProbeGate(new URL(url).hostname, { lookup: deps.lookup });
+      if (!gate.allowed) return { row, probed: false, blocked: true, reason: gate.reason };
+      pin = gate.pin || null;
+    }
+    const probe = await probeHealthz(url, { timeoutMs: deps.timeoutMs, fetchImpl: deps.fetchImpl, pin });
+    await provisioning.recordLivenessProbe(db, row.id, probe.up);
+    return { row, probed: true, ...probe };
+  }));
+
+  const probed = results.filter((r) => r.probed);
+  const downs = probed.filter((r) => !r.up);
+  const blocked = results.filter((r) => r.blocked);
+  const out = {
+    swept: rows.length,
+    up: probed.length - downs.length,
+    down: downs.length,
+    unprobeable: results.length - probed.length - blocked.length,
+    blocked: blocked.length,
+    blockedReasons: blocked.map((r) => `${r.row.slug}:${r.reason}`),
+    reasons: downs.map((r) => `${r.row.slug}:${r.reason || 'error'}`),
+  };
+  // Nothing active ⇒ nothing to say. A vanilla control plane would otherwise emit
+  // an empty account every five minutes forever.
+  if (rows.length) log(formatSweepLine(out));
+  return out;
+}
+
+// Start the periodic sweep. Idempotent (a second call is a no-op). Kill-switched by
+// PROVISIONING_LIVENESS_DISABLED=1. Self-rescheduling rather than setInterval so
+// each tick can carry its own jitter and a slow sweep never overlaps itself.
+function start(deps = {}) {
+  if (process.env.PROVISIONING_LIVENESS_DISABLED === '1') {
+    console.log('[liveness] disabled (PROVISIONING_LIVENESS_DISABLED=1)');
+    return;
+  }
+  if (started) return;
+  started = true;
+  arm(deps, FIRST_SWEEP_DELAY_MS);
+  console.log(
+    `[liveness] started — verifying active instances every ~${Math.round(INTERVAL_MS / 1000)}s (${Math.round(PROBE_TIMEOUT_MS / 1000)}s probe timeout)`
+  );
+}
+
+function arm(deps, delay) {
+  timer = setTimeout(() => {
+    sweepOnce(deps)
+      .catch((e) => console.error(`[liveness] 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 stop() {
+  started = false; // an in-flight sweep must not re-arm after this
+  if (timer) { clearTimeout(timer); timer = null; }
+}
+
+module.exports = {
+  start,
+  stop,
+  // exported for tests
+  sweepOnce,
+  probeHealthz,
+  healthzUrl,
+  formatSweepLine,
+  isPrivateAddress,
+  isIpLiteral,
+  domainProbeGate,
+  INTERVAL_MS,
+  PROBE_TIMEOUT_MS,
+};

package/modules/provisioning/provisioning.js

@@ -146,6 +146,12 @@ function publicInstance(row) {
     // thing you need when diagnosing a standup (task 1002562). Coalesced for rows read
     // before provisioning_004 added the column.
     onboard_mode: row.onboard_mode || 'greenfield',
+    // The verification overlay (task 1002696, redesign direction §3): what the
+    // heartbeat last OBSERVED, which is NOT what `status` claims. null = never
+    // probed — a different claim from last_verified_up=false, and the UI renders
+    // them differently ("live?" vs "unreachable"). Never collapse the two.
+    last_verified_at: row.last_verified_at || null,
+    last_verified_up: row.last_verified_up == null ? null : !!row.last_verified_up,
     cost_estimate_usd: Number(row.cost_estimate_usd || 0),
     error_note: row.error_note || null,
     created_at: row.created_at,
@@ -285,6 +291,41 @@ async function updateInstanceDomain(db, id, domain) {
   return rows[0] || null;
 }
 
+// ── Verification overlay (task 1002696, redesign direction §3) ──────────────
+// Liveness is an OVERLAY on the lifecycle, never a seventh state. These two
+// functions are the whole DB surface of the heartbeat: read what is worth
+// probing, record what the probe saw. NEITHER writes `status` — the runner stays
+// the only author of lifecycle, and an unreachable instance is still 'active'.
+
+// The instances a sweep probes: the ACTIVE ones. Anything earlier has nothing
+// standing up yet and anything later is being (or has been) reclaimed, so a probe
+// against it would only ever record a false "down". `limit` is a runaway guard.
+async function listActiveInstancesForLiveness(db, { limit = 500 } = {}) {
+  const { rows } = await db.query(
+    `SELECT id, slug, domain, port FROM provisioning_instances
+      WHERE status = 'active'
+      ORDER BY id
+      LIMIT $1`,
+    [Math.min(Math.max(Number(limit) || 500, 1), 2000)]
+  );
+  return rows;
+}
+
+// Record ONE probe observation. Deliberately narrow: it writes the two overlay
+// columns and nothing else — not `status`, and not `updated_at` either, so a
+// 5-minute heartbeat can never reshuffle the owner's updated_at-ordered card list
+// or fake activity on an instance nobody touched.
+async function recordLivenessProbe(db, id, up) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances
+        SET last_verified_at = now(), last_verified_up = $2
+      WHERE id = $1
+      RETURNING id, last_verified_at, last_verified_up`,
+    [id, !!up]
+  );
+  return rows[0] || null;
+}
+
 // The caller's own instances, newest first.
 async function listInstancesForOwner(db, ownerBuilderId) {
   const { rows } = await db.query(
@@ -610,6 +651,8 @@ module.exports = {
   // data access
   isProvisionedHostname,
   getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,
+  // data access — verification overlay (task 1002696)
+  listActiveInstancesForLiveness, recordLivenessProbe,
   createInstance, setInstanceStatus, updateInstanceDomain,
   enqueueIntent, enqueueTeardown, getOpenIntent, claimNextIntent, resolveIntent,
   recordEvent, instanceStateForSlug, costLedger,

package/modules/provisioning/routes/provisioning.js

@@ -32,7 +32,7 @@ const api = require('../../../src/module-api');
 const auth = api;
 const { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
-const { onboardPlan } = require('../onboard-plan');
+const { onboardPlan, stepsForShape } = require('../onboard-plan');
 const { makeAskRateLimiter } = require('../rate-limit');
 
 // How long a GitHub-App-Manifest `state` token is valid — the owner must click the
@@ -622,7 +622,11 @@ module.exports = function provisioningRoutes() {
   router.get('/provisioning/onboard-plan', (req, res) => {
     const mode = req.query.mode === 'adopt' ? 'adopt' : 'greenfield';
     const domain = provisioning.normalizeHostname(req.query.domain) || null;
-    res.json({ mode, steps: onboardPlan(mode, { domain }) });
+    // ?shape= filters to the steps that actually occur on that hosting shape
+    // (direction §7 — a self-host form must never promise the runner's legs);
+    // unknown/absent shape returns the full canonical sequence unchanged.
+    const shape = typeof req.query.shape === 'string' ? req.query.shape : null;
+    res.json({ mode, steps: stepsForShape(onboardPlan(mode, { domain }), shape) });
   });
 
   // GET /provisioning/tls-check?domain=<host> — the Caddy on-demand-TLS ALLOW-LIST