@bongos/core 1.19.1081 → 1.20.1

package/modules/npm-release/preview/supervisor.js

@@ -0,0 +1,175 @@
+'use strict';
+
+// modules/npm-release/preview/supervisor.js — starts, watches and stops the ONE version
+// preview this hall may run (task 1004300, ADR 0349).
+//
+// A preview is a second Bongos process, running an installed copy of an older core against
+// a COPY of the live database, reached through the live hall's own address (divert.js). This
+// file owns its lifecycle and nothing else: install → copy the database → migrate → launch →
+// wait until it answers. Every outward step goes through an injected function (run for a
+// command, spawn for the long-lived child, probe for the health check, sleep, now), which is
+// what lets the whole lifecycle be tested without a process, a database or a network.
+//
+// ONE AT A TIME, STOPPED WHEN IDLE. A second preview is refused, not queued; a running one
+// that nothing has touched for IDLE_MS is stopped and its copy of the database dropped. That
+// bound is what keeps a preview from becoming a permanent second tenant of the droplet.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+const { buildPreviewEnv } = require('./env');
+const cmds = require('./commands');
+
+const IDLE_MS = 20 * 60 * 1000;
+const DEFAULT_PORT = 3190;
+const HEALTH_TRIES = 40;
+const HEALTH_INTERVAL_MS = 1500;
+
+// How far behind the running version a preview may reach, counted in PUBLISHED versions.
+const WINDOW = 30;
+
+function compare(a, b) {
+  const x = a.split('.').map(Number);
+  const y = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+/**
+ * Is this version one a preview may open? Published versions only, and no older than
+ * `window` published versions before the one this hall runs. Newer than the running
+ * version is fine — it is how a release is tried before it is adopted.
+ *
+ * @returns {{ok:true}|{ok:false, reason:string, oldest?:string}}  oldest names the earliest version still allowed
+ */
+function previewable(version, { published, running, window = WINDOW } = {}) {
+  if (!cmds.VERSION_RE.test(String(version))) return { ok: false, reason: 'not_a_version' };
+  const list = Object.keys(published || {}).filter((v) => cmds.VERSION_RE.test(v)).sort(compare);
+  if (!list.includes(version)) return { ok: false, reason: 'not_published' };
+  const at = running && list.includes(running) ? list.indexOf(running) : list.length - 1;
+  const floor = Math.max(0, at - window);
+  if (list.indexOf(version) < floor) return { ok: false, reason: 'too_old', oldest: list[floor] };
+  return { ok: true };
+}
+
+/**
+ * @param {object} o
+ * @param {Function} o.run    (command) => Promise of { code, stderr } — runs one command to the end
+ * @param {Function} o.spawn  node:child_process spawn (the long-lived child)
+ * @param {Function} o.probe  (port) => Promise of boolean — does the preview answer its health check
+ * @param {string} o.liveDb   the live database name (the source of the copy)
+ * @param {string} o.cacheRoot  where versions are installed
+ * @param {object} [o.env]    the live environment (read by buildPreviewEnv only)
+ */
+function createSupervisor({
+  run, spawn, probe, liveDb, cacheRoot,
+  env = process.env, port = DEFAULT_PORT,
+  now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  fsImpl = fs, tmpdir = os.tmpdir(), idleMs = IDLE_MS,
+  log = { info() {}, warn() {}, error() {} },
+} = {}) {
+  let state = { state: 'idle', version: null, stage: null, error: null, startedAt: null, lastTouch: null };
+  let child = null;
+  let workDir = null;
+
+  const set = (patch) => { state = { ...state, ...patch }; };
+  const status = () => ({ ...state, port, idle_ms: idleMs });
+
+  async function step(stage, command) {
+    set({ stage });
+    const r = await run(command);
+    if (!r || r.code !== 0) {
+      const tail = r && r.stderr ? `: ${String(r.stderr).trim().slice(-300)}` : '';
+      throw new Error(`${stage} failed (exit ${r ? r.code : '?'})${tail}`);
+    }
+  }
+
+  // Everything a start or a stop leaves behind: the child, the copy, the scratch directory.
+  async function cleanup() {
+    if (child) { try { child.kill(); } catch (e) { log.warn(`preview child would not stop: ${e && e.message}`); } child = null; }
+    try { await run(cmds.dropDbCommand()); } catch (e) { log.warn(`preview copy could not be dropped: ${e && e.message}`); }
+    if (workDir) { try { fsImpl.rmSync(workDir, { recursive: true, force: true }); } catch { /* best effort */ } workDir = null; }
+  }
+
+  async function launch(version) {
+    try {
+      workDir = fsImpl.mkdtempSync(path.join(tmpdir, 'bongos-preview-'));
+      const home = path.join(workDir, 'home');
+      fsImpl.mkdirSync(home, { recursive: true });
+      const dumpFile = path.join(workDir, 'live.dump');
+      const childEnv = buildPreviewEnv({ env, port, scratchHome: home });
+
+      await step('install', { ...cmds.installCommand({ cacheRoot, version }), env: childEnv });
+      await step('drop-old-copy', cmds.dropDbCommand());
+      await step('create-copy', cmds.createDbCommand());
+      await step('dump', cmds.dumpCommand({ liveDb, dumpFile }));
+      await step('restore', cmds.restoreCommand({ dumpFile }));
+      await step('migrate', cmds.migrateCommand({ cacheRoot, version, env: childEnv }));
+
+      set({ stage: 'launch' });
+      child = spawn(process.execPath, [cmds.entryPath(cacheRoot, version)], {
+        cwd: cmds.versionDir(cacheRoot, version), env: childEnv, stdio: 'ignore',
+      });
+      child.on('exit', (code) => {
+        // A child that dies on its own must not leave a copy behind or a page waiting on it.
+        if (child && state.state === 'running') {
+          log.warn(`preview of ${version} exited (${code})`);
+          child = null;
+          set({ state: 'failed', stage: 'exited', error: `the preview process exited (${code})` });
+          cleanup();
+        }
+      });
+
+      set({ stage: 'health' });
+      let up = false;
+      for (let i = 0; i < HEALTH_TRIES && !up; i++) {
+        up = await probe(port);
+        if (!up) await sleep(HEALTH_INTERVAL_MS);
+      }
+      if (!up) throw new Error('the preview did not answer in time');
+      set({ state: 'running', stage: null, startedAt: now(), lastTouch: now() });
+    } catch (e) {
+      log.error(`preview of ${version} failed: ${e && e.message}`);
+      set({ state: 'failed', error: e && e.message ? e.message : String(e) });
+      await cleanup();
+    }
+  }
+
+  /**
+   * Begin previewing a version. Returns straight away with ok, status and done: the long
+   * steps run behind it (done settles when they finish, for tests), and callers follow
+   * along with status().
+   */
+  function start(version) {
+    if (!cmds.VERSION_RE.test(String(version))) return { ok: false, code: 'not_a_version', status: status() };
+    if (state.state === 'starting' || state.state === 'running') {
+      if (state.version === version) return { ok: true, already: true, status: status(), done: Promise.resolve() };
+      return { ok: false, code: 'preview_busy', status: status() };
+    }
+    set({ state: 'starting', version, stage: 'queued', error: null, startedAt: null, lastTouch: now() });
+    return { ok: true, status: status(), done: launch(version) };
+  }
+
+  /** Stop the preview and drop its copy. Safe to call at any point. */
+  async function stop() {
+    await cleanup();
+    set({ state: 'idle', version: null, stage: null, error: null, startedAt: null, lastTouch: null });
+    return status();
+  }
+
+  /** Note that someone used the preview: every forwarded request calls this. */
+  function touch() { if (state.state === 'running') set({ lastTouch: now() }); }
+
+  /** Stop a running preview nobody has touched for the idle window. */
+  async function reapIdle() {
+    if (state.state !== 'running') return false;
+    if (now() - state.lastTouch < idleMs) return false;
+    log.info(`preview of ${state.version} idle, stopping`);
+    await stop();
+    return true;
+  }
+
+  return { start, stop, status, touch, reapIdle };
+}
+
+module.exports = { createSupervisor, previewable, IDLE_MS, DEFAULT_PORT, WINDOW };

package/modules/npm-release/public/work.js

@@ -166,11 +166,69 @@
           <span class="ov-group__name ov-key">${escapeHtml(v.version)}</span>
           <span class="ov-group__n">${v.entries ? v.entries.length : '?'}</span>
           <span class="ov-group__note">${escapeHtml(note)}</span>
+          <button type="button" class="ov-toggle" data-preview="${escapeHtml(v.version)}"${preview && preview.state !== 'idle' && preview.state !== 'failed' ? ' disabled' : ''}>View</button>
         </div>
         ${body}
       </div>`;
   }
 
+  // ---- previewing a version (task 1004300, ADR 0349) -----------------------------------
+  // The server owns the state (idle, starting, running, failed); this only shows it and
+  // asks for changes. One preview at a time, so one panel above the version list.
+  let preview = null;
+  let previewErr = '';
+  let pollTimer = null;
+  const PREVIEW_STEP = {
+    queued: 'getting ready', install: 'installing that version', 'drop-old-copy': 'clearing the old copy',
+    'create-copy': 'making a copy of the data', dump: 'copying the live data', restore: 'loading the copy',
+    migrate: 'running its migrations on the copy', launch: 'starting it', health: 'waiting for it to answer',
+  };
+
+  function previewHtml() {
+    if (previewErr) return `<div class="ov-note ov-note--warn"><p>${escapeHtml(previewErr)}</p></div>`;
+    if (!preview || preview.state === 'idle') return '';
+    const v = escapeHtml(preview.version || '');
+    if (preview.state === 'starting') {
+      return `<div class="ov-note"><p><strong>Preparing a preview of ${v}</strong> — ${escapeHtml(PREVIEW_STEP[preview.stage] || 'working')}. This can take a few minutes.</p></div>`;
+    }
+    if (preview.state === 'failed') {
+      return `<div class="ov-note ov-note--warn"><p><strong>The preview of ${v} did not start.</strong> ${escapeHtml(preview.error || '')}</p><button type="button" class="ov-toggle" data-preview-stop>Clear</button></div>`;
+    }
+    return `<div class="ov-note"><p><strong>Preview of ${v} is running</strong> on a copy of this hall's data. Nothing done there reaches the live hall. It stops by itself after ${Math.round((preview.idle_ms || 0) / 60000)} minutes unused.</p>
+      <a class="ov-toggle" href="${API}/npm-release/preview/enter?v=${encodeURIComponent(preview.version)}">Open the preview</a>
+      <button type="button" class="ov-toggle" data-preview-stop>Stop it</button></div>`;
+  }
+
+  async function previewCall(method, body) {
+    const res = await client.request(method, `${API}/npm-release/preview`, body ? { body } : {});
+    if (!res.ok) {
+      const err = (res.data && res.data.error) || {};
+      throw new Error(err.message || `preview → ${res.status}`);
+    }
+    return res.data;
+  }
+
+  function followPreview() {
+    if (pollTimer) return;
+    pollTimer = setInterval(async () => {
+      try {
+        preview = (await previewCall('GET')).preview;
+      } catch (e) { previewErr = e.message || String(e); }
+      if (!preview || preview.state !== 'starting') { clearInterval(pollTimer); pollTimer = null; }
+      paint();
+    }, 3000);
+  }
+
+  async function previewAct(fn) {
+    previewErr = '';
+    try {
+      const d = await fn();
+      preview = d.preview;
+      if (preview && preview.state === 'starting') followPreview();
+    } catch (e) { previewErr = e.message || String(e); }
+    paint();
+  }
+
   let data = null;
   let history = [];
   let hasMore = false;
@@ -193,6 +251,7 @@
     if (vers) {
       vers.innerHTML = `
         <h2 class="scroll__h" id="nr-versions-h">Versions</h2>
+        ${previewHtml()}
         <p class="scroll__lede">What each version carried, newest first — the task each merge named, in the words its ship wrote.</p>
         ${history.map(versionHtml).join('')}
         ${hasMore ? `<button type="button" class="ov-toggle" id="nr-older"${loadingMore ? ' disabled' : ''}>${loadingMore ? 'Loading…' : 'Show older versions'}</button>` : ''}`;
@@ -231,6 +290,8 @@
       history = d.history.versions;
       hasMore = d.history.more;
       paint();
+      // A quiet first read: a preview already running (or half started) shows at once.
+      previewCall('GET').then((r) => { preview = r.preview; if (preview.state === 'starting') followPreview(); paint(); }).catch(() => {});
     } catch (e) {
       work.innerHTML = `<h2 class="scroll__h">Where the work is</h2>
         <div class="ov-note ov-note--warn"><p><strong>Could not read where the work is.</strong> ${escapeHtml(e.message || String(e))}</p></div>`;
@@ -259,7 +320,10 @@
     if (!(t instanceof Element)) return;
     const ex = t.closest('[data-expand]');
     if (ex) { expanded.add(ex.getAttribute('data-expand')); paint(); return; }
-    if (t.closest('#nr-older')) loadOlder();
+    if (t.closest('#nr-older')) { loadOlder(); return; }
+    const pv = t.closest('[data-preview]');
+    if (pv) { previewAct(() => previewCall('POST', { version: pv.getAttribute('data-preview') })); return; }
+    if (t.closest('[data-preview-stop]')) previewAct(() => previewCall('DELETE'));
   });
 
   load();

package/modules/npm-release/routes/preview.js

@@ -0,0 +1,133 @@
+'use strict';
+
+// modules/npm-release/routes/preview.js — start, watch, enter, leave and stop a version
+// preview from the deploy page (task 1004300, ADR 0349).
+//
+//   GET    /npm-release/preview           what is running, and how far a start has got
+//   POST   /npm-release/preview           start one { version }
+//   DELETE /npm-release/preview           stop it and drop its copy of the database
+//   GET    /npm-release/preview/enter?v=  set the steering cookie, go to the hall inside it
+//   GET    /npm-release/preview/exit      clear the cookie, come back to the deploy page
+//
+// EVERY ROUTE IS GATED ON core.pin.move, the permission /deploy itself needs (an atom, not
+// a rank — tests/government_require_permission.mjs). Starting a preview runs a
+// published package and copies the live database, so it is no wider than moving the pin.
+//
+// This file also registers this module's provider for the kernel's request.divert seam:
+// the hook that lets the platform hand a request to divert.js before anything else answers.
+// An instance that does not have this module on never registers it, and the kernel's seam
+// call then falls straight through.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { createDivert, clearCookie } = require('../preview/divert');
+const { createProxy, COOKIE_NAME } = require('../preview/proxy');
+const { previewable } = require('../preview/supervisor');
+const { VERSION_RE, PACKAGE } = require('../preview/commands');
+
+const log = api.logger('npm-release');
+
+// Published versions of the core, from the registry the deploy page already reads.
+async function publishedVersions() {
+  const { registry } = await api.readPackageRegistry({ pkg: PACKAGE, haveNotesFor: () => true });
+  return registry.ok ? registry.published : null;
+}
+
+// The real supervisor is built on first use, so a boot that never previews anything starts
+// no timer and touches no process. Until then it reads as idle, which is what it is.
+function lazySupervisor(make) {
+  let real = null;
+  const get = () => { if (!real) real = make(); return real; };
+  return {
+    status: () => (real ? real.status() : { state: 'idle', version: null, stage: null, error: null, port: null }),
+    touch: () => { if (real) real.touch(); },
+    start: (v) => get().start(v),
+    stop: async () => (real ? real.stop() : undefined),
+  };
+}
+
+module.exports = function buildNpmReleasePreviewRouter({
+  supervisor = null,
+  listPublished = publishedVersions,
+  runningVersion = () => api.CORE_VERSION,
+  registerDivert = true,
+} = {}) {
+  const router = express.Router();
+  const sup = supervisor || lazySupervisor(() => require('../preview/runtime').createRuntime({
+    liveDb: process.env.PGDATABASE || api.instanceDbName(),
+    log,
+  }));
+  const mayPreview = api.requirePermission('core.pin.move');
+
+  if (registerDivert && !api.hasProvider('request.divert')) {
+    const forward = createProxy({
+      port: () => sup.status().port,
+      banner: () => ({ viewing: sup.status().version || '?', running: runningVersion() }),
+      exitHref: '/api/bongos/npm-release/preview/exit',
+    });
+    api.registerProvider('request.divert', createDivert({
+      supervisor: sup,
+      forward,
+      requireBuilder: api.requireBuilder,
+      requirePermission: api.requirePermission,
+    }));
+  }
+
+  const failure = (res, status, code, message) => res.status(status).json({ error: { code, message } });
+  const view = () => ({ preview: sup.status(), running: runningVersion() });
+
+  router.get('/npm-release/preview', api.requireBuilder, mayPreview, (req, res) => res.json(view()));
+
+  router.post('/npm-release/preview', api.requireBuilder, mayPreview, async (req, res) => {
+    if (api.validateOrRespond(req, res, { version: { required: true, type: 'string', maxLength: 32 } })) return;
+    const version = req.body.version;
+    if (!VERSION_RE.test(version)) return failure(res, 400, 'not_a_version', 'That is not a version number.');
+    try {
+      const published = await listPublished();
+      if (!published) return failure(res, 502, 'registry_unreadable', 'The list of published versions could not be read, so nothing was started.');
+      const verdict = previewable(version, { published, running: runningVersion() });
+      if (!verdict.ok) {
+        const why = verdict.reason === 'too_old'
+          ? `That version is older than previews reach back. The oldest you can preview now is ${verdict.oldest}; pick that one or a newer one.`
+          : 'That version has not been published. Pick one from the list below.';
+        return failure(res, 400, verdict.reason, why);
+      }
+      const r = sup.start(version);
+      if (!r.ok) return failure(res, 409, r.code, 'A preview of another version is already running. Stop it first.');
+      log.info(`preview of ${version} requested by builder ${req.builder && req.builder.id}`);
+      return res.status(202).json(view());
+    } catch (e) {
+      log.error(`preview start failed: ${e && e.message}`);
+      return failure(res, 500, 'preview_start_failed', 'Could not start the preview.');
+    }
+  });
+
+  router.delete('/npm-release/preview', api.requireBuilder, mayPreview, async (req, res) => {
+    try {
+      await sup.stop();
+      res.json(view());
+    } catch (e) {
+      log.error(`preview stop failed: ${e && e.message}`);
+      failure(res, 500, 'preview_stop_failed', 'Could not stop the preview.');
+    }
+  });
+
+  router.get('/npm-release/preview/enter', api.requireBuilder, mayPreview, (req, res) => {
+    const v = typeof req.query.v === 'string' ? req.query.v : '';
+    const st = sup.status();
+    if (!VERSION_RE.test(v) || st.state !== 'running' || st.version !== v) {
+      return failure(res, 409, 'preview_not_running', 'That preview is not running.');
+    }
+    const secure = req.secure ? '; Secure' : '';
+    res.append('Set-Cookie', `${COOKIE_NAME}=${v}; Path=/; HttpOnly; SameSite=Lax${secure}`);
+    sup.touch();
+    return res.redirect(302, '/');
+  });
+
+  router.get('/npm-release/preview/exit', api.requireBuilder, mayPreview, (req, res) => {
+    res.append('Set-Cookie', clearCookie());
+    res.redirect(302, '/deploy');
+  });
+
+  return router;
+};

package/modules/provisioning/app-status.js

@@ -0,0 +1,83 @@
+// modules/provisioning/app-status.js — what the owner is told about their app's setup on
+// Render (task 1004353; ADR 0327, ADR 0345, ADR 0348).
+//
+// The setup runs in the runner and can take minutes, often after the wizard has closed,
+// and the key is gone once it has run. So the owner needs one honest answer, from the row
+// alone: where the setup is, the app's address once it answers, the way to Render, and —
+// on a failure — the sentence that says what went wrong, with a retry that is theirs to
+// start (a retry needs the key again; the platform never retries by itself).
+//
+// Nothing here calls Render or holds a key. The address check that moves `deploying` to
+// `live` is the poller beside this file (pollers/app-liveness.js): a plain GET of the
+// app's own public address, the same credential-free pull ADR 0252 made for halls.
+'use strict';
+
+// The one dashboard the owner is sent to. Service ids are checked before they are put in
+// a link, so a stored value can never shape one.
+const DASHBOARD = 'https://dashboard.render.com';
+const SERVICE_ID_RE = /^srv-[a-z0-9]{8,64}$/;
+// Render gives a web service a https://<name>.onrender.com address. Only that shape is
+// shown as the app's address or probed by the poller — a stored value can never point
+// either at something else.
+const RENDER_URL_RE = /^https:\/\/[a-z0-9-]{1,63}\.onrender\.com\/?$/;
+
+// The stages the owner sees, in order. `failed` is not a stage: it is the setup stopping.
+const STAGES = ['creating', 'building', 'live'];
+const STAGE_OF = { requested: 'creating', creating: 'creating', deploying: 'building', linked: 'building', live: 'live' };
+
+function serviceLinks(serviceId) {
+  if (!SERVICE_ID_RE.test(String(serviceId || ''))) return null;
+  const base = `${DASHBOARD}/web/${serviceId}`;
+  return { service: base, env: `${base}/env` };
+}
+
+function appUrl(url) { return RENDER_URL_RE.test(String(url || '')) ? String(url).replace(/\/+$/, '') : null; }
+
+// The owner's view of app_host: the stage, the address, the links, the failure sentence,
+// and the answers a retry re-sends (never the key — there is none to send).
+function appStatus(appHost, { keyWaiting = false } = {}) {
+  const h = appHost || null;
+  if (!h || h.platform !== 'render') return null;
+  if (h.state === 'disconnected') return { platform: 'render', state: 'disconnected', stage: null };
+  const failed = h.state === 'failed';
+  return {
+    platform: 'render',
+    state: h.state || 'requested',
+    stage: failed ? null : (STAGE_OF[h.state] || 'creating'),
+    // an intent that still holds the lent key has not run yet, so the owner waits rather
+    // than retries
+    waiting: !!keyWaiting,
+    mode: h.mode === 'adopt' ? 'adopt' : 'greenfield',
+    workspace: h.ownerId || null,
+    url: appUrl(h.serviceUrl),
+    links: serviceLinks(h.serviceId),
+    error: failed ? oneSentence(h.error) : null,
+    retry: failed ? retryAnswers(h) : null,
+  };
+}
+
+// A runner's reason, as one sentence the owner can read: its first line, capped, ending
+// in a full stop. The reasons are the leg's own words (provision-render.js), already
+// written for the owner.
+function oneSentence(err) {
+  const s = String(err || 'The setup stopped without saying why.').split('\n')[0].trim().slice(0, 300);
+  const first = s.charAt(0).toUpperCase() + s.slice(1);
+  return /[.!?]$/.test(first) ? first : first + '.';
+}
+
+// What the owner already answered, so a retry asks only for the key again.
+function retryAnswers(h) {
+  const r = { owner_id: h.ownerId || null, mode: h.mode === 'adopt' ? 'adopt' : 'greenfield' };
+  if (r.mode === 'adopt') { r.service_id = h.serviceId || null; return r; }
+  r.runtime = h.runtime || null;
+  if (h.runtime !== 'docker') {
+    if (h.startCommand) r.start_command = h.startCommand;
+    if (h.buildCommand) r.build_command = h.buildCommand;
+  }
+  if (h.webPlan) r.web_plan = h.webPlan;
+  r.database = h.database === true;
+  if (r.database && h.dbPlan) r.db_plan = h.dbPlan;
+  return r;
+}
+
+module.exports = { appStatus, appUrl, serviceLinks, oneSentence, retryAnswers, STAGES, RENDER_URL_RE, SERVICE_ID_RE };

package/modules/provisioning/module.json

@@ -24,7 +24,8 @@
     "migrations": true,
     "pollers": [
       "liveness-sweep",
-      "catalog-backfill"
+      "catalog-backfill",
+      "app-liveness"
     ]
   },
   "provides": [

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

@@ -0,0 +1,110 @@
+'use strict';
+
+// modules/provisioning/pollers/app-liveness.js — when an app the platform set up on its
+// owner's Render account starts answering, say so (task 1004353). The loader's
+// startModulePollers requires this file and calls start(deps) at boot, for the ENABLED
+// module only — the liveness-sweep shape.
+//
+// WHY. The runner creates the service and hands the rest to Render, which builds and
+// deploys on its own; the key is gone by then (ADR 0327 §2), so the platform cannot ask
+// Render how the build went. What it CAN do is what ADR 0252 does for halls: knock on the
+// app's own public address. While Render is still building, that address answers 502
+// with `x-render-routing: no-deploy` (measured by the pilot, task 1004142); once any
+// deploy is live, it answers whatever the app answers.
+//
+// SO:
+//   - only rows whose app is `deploying` (a new app) or `linked` (an existing one) are
+//     knocked on, and only at a https://<name>.onrender.com address — a stored value can
+//     never aim the probe anywhere else (app-status.js RENDER_URL_RE), and redirects are
+//     never followed;
+//   - any answer below 500 that is not Render's no-deploy page is `live`. A 404 at the
+//     root is still an app answering;
+//   - the write is compare-and-set on the state it read, so it can never overwrite what
+//     the runner wrote since (a retry that failed, a disconnect);
+//   - a GET with no credential of any kind. Nothing here calls Render's API.
+//
+// Best-effort: a failed knock is simply "not yet", and the next tick asks again.
+
+const api = require('../../../src/module-api');
+const { RENDER_URL_RE } = require('../app-status');
+
+const logger = api.logger('provisioning');
+
+const INTERVAL_MS = Number(process.env.PROVISIONING_APP_LIVENESS_MS) || 60_000;
+const FIRST_DELAY_MS = 20_000;
+const PROBE_TIMEOUT_MS = 10_000;
+const SWEEP_LIMIT = 50;
+const CONCURRENCY = 5;
+
+let timer = null;
+let started = false;
+
+// One knock. Returns true when the app answers as deployed.
+async function appAnswers(url, { fetchImpl, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  if (!RENDER_URL_RE.test(String(url || ''))) return false;
+  try {
+    const res = await (fetchImpl || globalThis.fetch)(url, {
+      method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs),
+      headers: { accept: 'text/html, application/json;q=0.9, */*;q=0.8' },
+    });
+    const routing = res.headers && typeof res.headers.get === 'function' ? res.headers.get('x-render-routing') : null;
+    if (routing && /no-deploy/i.test(routing)) return false;
+    return res.status < 500;
+  } catch (_) {
+    return false;
+  }
+}
+
+async function sweepOnce(deps = {}) {
+  const db = deps.pool || api.pool;
+  const log = deps.log || ((m) => logger.info(m));
+  const { rows } = await db.query(
+    `SELECT id, slug, app_host FROM provisioning_instances
+      WHERE app_host->>'platform' = 'render' AND app_host->>'state' IN ('deploying', 'linked')
+        AND status <> 'torn_down'
+      ORDER BY id LIMIT ${SWEEP_LIMIT}`);
+  let live = 0;
+  // a few at a time, so one app timing out never holds the others up for its full timeout
+  const answers = [];
+  for (let i = 0; i < rows.length; i += CONCURRENCY) {
+    const batch = rows.slice(i, i + CONCURRENCY);
+    answers.push(...(await Promise.all(batch.map((r) => appAnswers((r.app_host || {}).serviceUrl, { fetchImpl: deps.fetchImpl, timeoutMs: deps.timeoutMs })))));
+  }
+  for (const [i, r] of rows.entries()) {
+    const h = r.app_host || {};
+    if (!answers[i]) continue;
+    const { rowCount } = await db.query(
+      `UPDATE provisioning_instances
+          SET app_host = app_host || jsonb_build_object('state', 'live', 'liveAt', now()::text, 'error', NULL)
+        WHERE id = $1 AND app_host->>'state' = $2`,
+      [r.id, h.state]);
+    if (rowCount) { live++; log(`[app-liveness] ${r.slug}: its app answers at ${h.serviceUrl} — live`); }
+  }
+  return { checked: rows.length, live };
+}
+
+function start(deps = {}) {
+  if (process.env.PROVISIONING_APP_LIVENESS_DISABLED === '1') {
+    logger.info('[app-liveness] disabled (PROVISIONING_APP_LIVENESS_DISABLED=1)');
+    return;
+  }
+  if (started) return;
+  started = true;
+  arm(deps, FIRST_DELAY_MS);
+}
+
+function arm(deps, delay) {
+  timer = setTimeout(() => {
+    sweepOnce(deps)
+      .catch((e) => logger.error(`[app-liveness] sweep failed: ${e && e.message ? e.message : e}`))
+      .then(() => { if (started) arm(deps, INTERVAL_MS); });
+  }, delay);
+  if (timer.unref) timer.unref();
+}
+
+function stop() {
+  started = false;
+  if (timer) { clearTimeout(timer); timer = null; }
+}
+
+module.exports = { start, stop, sweepOnce, appAnswers, INTERVAL_MS };