@bongos/core 1.25.16 → 1.25.18

package/scripts/bongos/provision-render-sandbox.js

@@ -0,0 +1,171 @@
+'use strict';
+// provision-render-sandbox.js — the project's SANDBOX on Render: set it up beside the app,
+// and remove it at teardown (task 1005289; ADR 0406, ADR 0327).
+//
+// WHY. Every project whose app runs on Render gets a second, free app from the same
+// repository that follows `main` on every merge, so finished work reaches a test copy
+// first and the live site moves only when a person promotes (ADR 0406 §2). This file is
+// the runner half; the web tier queues it (modules/provisioning/render-sandbox.js) and the
+// standup leg calls it after the app (provision-render.js), with the same borrowed key.
+//
+// THREE STAGES, kept apart so one failing never takes the others down:
+//   1. BUILD — the app's own build settings: what the owner gave (new app), or read off
+//      their existing service (a linked one).
+//   2. DATABASE — never Render's free database (it expires, one per workspace: ADR 0406
+//      §4). When the app has a PAID database we created, a second database is made INSIDE
+//      that server with plain SQL (Render's docs: "Adding multiple databases to a single
+//      instance" — there is no API call for it). No app database → no sandbox database.
+//      A failure here leaves the sandbox running with NO database and says why; it never
+//      falls back to buying one — that is the owner's call (ADR 0406 §6 choice 1).
+//   3. SERVICE — a free web service named `<slug>-sandbox`, auto-deploying from `main`,
+//      with BONGOS_SANDBOX=1. Found by name first, so a re-run never makes a second one.
+//
+// The live service is not touched here: switching it to manual deploys belongs with the
+// promote button that replaces them (task 1005290).
+//
+// TEARDOWN removes the sandbox service and the sandbox database only — never the live app
+// or its data (ADR 0406 §7). It needs the owner's key; without one the sandbox is
+// forgotten and the owner is told exactly what to delete.
+
+const payload = require('./render-payload.js');
+const { parseTargetRef } = require('./provision-repo-auth.js');
+
+async function recordSandbox(db, instId, patch) {
+  await db.query(
+    `UPDATE provisioning_instances
+        SET app_host = COALESCE(app_host, '{}'::jsonb)
+                       || jsonb_build_object('sandbox', COALESCE(app_host->'sandbox', '{}'::jsonb) || $2::jsonb)
+      WHERE id = $1`,
+    [instId, JSON.stringify({ ...patch, updatedAt: new Date().toISOString() })]);
+}
+
+// Run SQL against the app's database SERVER from the runner. Uses the server's external
+// address (the runner is outside Render's network). Injected in tests: no real database.
+async function defaultSqlRunner(connectionString, statements) {
+  const { Client } = require('pg');
+  const c = new Client({ connectionString, ssl: { rejectUnauthorized: true }, connectionTimeoutMillis: 15000 });
+  await c.connect();
+  try {
+    const out = [];
+    for (const s of statements) out.push(await c.query(s.text, s.values || []));
+    return out;
+  } finally { await c.end().catch(() => {}); }
+}
+
+// The same connection string pointed at another database on the same server.
+function withDatabase(connectionString, dbName) {
+  const u = new URL(connectionString);
+  u.pathname = `/${dbName}`;
+  return u.toString();
+}
+
+// Stage 2. Returns { state: 'ready', name, url } | { state: 'none' | 'failed', note }.
+async function sandboxDatabase(api, inst, host, deps) {
+  if (!host.postgresId) {
+    return { state: 'none', note: host.mode === 'adopt'
+      ? 'Bongos did not create your app’s database, so the sandbox has none. It runs your app without data.'
+      : 'Your app has no database, so its sandbox has none either.' };
+  }
+  try {
+    const pg = await api.getPostgres(host.postgresId);
+    if (pg.plan === 'free') return { state: 'none', note: 'Your app’s database is on Render’s free plan, which cannot hold a sandbox database, so the sandbox has none.' };
+    const conn = await api.postgresConnectionInfo(pg.id);
+    const ext = conn && conn.externalConnectionString;
+    const int = conn && conn.internalConnectionString;
+    if (!ext || !int) throw new Error('Render gave no connection address for your database');
+    const name = payload.sandboxDbName(inst);
+    const run = deps.sqlRunner || defaultSqlRunner;
+    const [exists] = await run(ext, [{ text: 'SELECT 1 FROM pg_database WHERE datname = $1', values: [name] }]);
+    if (!(exists && exists.rows && exists.rows.length)) await run(ext, [{ text: `CREATE DATABASE "${name}"` }]);
+    return { state: 'ready', name, url: withDatabase(int, name) };
+  } catch (e) {
+    return { state: 'failed', note: `The sandbox’s own database could not be made, so the sandbox runs with no data: ${String((e && e.message) || e).split('\n')[0].slice(0, 200)}` };
+  }
+}
+
+// Stages 1-3. Never throws: a sandbox failure is recorded on the sandbox and never fails
+// the app it sits beside. Returns { ok, error? }.
+async function standupSandbox(api, inst, host, deps) {
+  const { db, log } = deps;
+  try {
+    const repo = parseTargetRef(inst.target_ref);
+    if (!repo) throw new Error('the project has no GitHub repository for the sandbox to build from');
+    // 1. build settings
+    let build, region = host.region || payload.DEFAULTS.region;
+    if (host.mode === 'adopt') {
+      const live = await api.getService(host.serviceId);
+      build = payload.buildFromService(live);
+      if (!build) throw new Error('Render did not say how your linked service is built, so the sandbox could not copy it');
+      region = (live.serviceDetails && live.serviceDetails.region) || region;
+    } else {
+      build = payload.buildFor(host);
+    }
+    await recordSandbox(db, inst.id, { state: 'creating', error: null });
+    // 2. database — its own stage; its failure is the sandbox's note, not its end
+    const sb = host.sandbox || {};
+    const dbStage = await sandboxDatabase(api, inst, host, deps);
+    await recordSandbox(db, inst.id, { database: dbStage.state, dbName: dbStage.name || null, dbNote: dbStage.note || null });
+    log(`  [render] sandbox database: ${dbStage.state}${dbStage.name ? ` (${dbStage.name})` : ''}`);
+    // 3. the free service, found before created
+    const name = payload.resourceName(inst, 'sandbox');
+    let svc = sb.serviceId ? await api.getService(sb.serviceId).catch(() => null) : null;
+    if (!svc) svc = await api.findServiceByName(name);
+    if (!svc) {
+      const created = await api.createService(payload.sandboxServicePayload(inst, {
+        ownerId: api.ownerId, repoUrl: `https://github.com/${repo.owner}/${repo.name}`, region, build,
+        dbUrl: dbStage.state === 'ready' ? dbStage.url : null,
+      }));
+      svc = created.service;
+      log(`  [render] created sandbox service ${svc.id} (free, follows main)`);
+    }
+    const url = (svc.serviceDetails && svc.serviceDetails.url) || null;
+    await recordSandbox(db, inst.id, { state: 'deploying', serviceId: svc.id, serviceUrl: url, error: null });
+    return { ok: true };
+  } catch (e) {
+    const error = `The sandbox could not be set up: ${String((e && e.message) || e).split('\n')[0].slice(0, 240)}`;
+    await recordSandbox(db, inst.id, { state: 'failed', error }).catch(() => {});
+    log(`  ✖ [render] ${inst.slug} sandbox: ${error}`);
+    return { ok: false, error };
+  }
+}
+
+// Teardown's half for the sandbox. `api` is a Render client built from the key the owner
+// lent with the teardown, or null when they lent none.
+async function removeSandbox(inst, { db, log, apply, sqlRunner }, api) {
+  const host = inst.app_host || {};
+  const sb = host.sandbox;
+  if (host.platform !== 'render' || !sb || (!sb.serviceId && !sb.dbName)) return { removed: false, reason: 'none' };
+  if (!api) {
+    const what = [sb.serviceId && `the service ${payload.resourceName(inst, 'sandbox')}`, sb.dbName && `the database ${sb.dbName} inside your app’s database`].filter(Boolean).join(' and ');
+    log(`  [render] sandbox left on Render (no key lent with the teardown): ${what}`);
+    if (apply) await recordSandbox(db, inst.id, { state: 'left', error: `No Render key came with the teardown, so the sandbox is still on your Render account: remove ${what} there.` });
+    return { removed: false, reason: 'no_key' };
+  }
+  const notes = [];
+  let dbGone = !sb.dbName;
+  if (sb.serviceId) {
+    if (apply) await api.deleteSandboxService(sb.serviceId);
+    notes.push(`service ${sb.serviceId}`);
+  }
+  if (sb.dbName && host.postgresId && payload.SANDBOX_DB_RE.test(sb.dbName)) {
+    try {
+      const conn = await api.postgresConnectionInfo(host.postgresId);
+      if (apply && conn && conn.externalConnectionString) {
+        await (sqlRunner || defaultSqlRunner)(conn.externalConnectionString, [{ text: `DROP DATABASE IF EXISTS "${sb.dbName}" WITH (FORCE)` }]);
+      }
+      notes.push(`database ${sb.dbName}`);
+      dbGone = true;
+    } catch (e) {
+      log(`  (sandbox database ${sb.dbName} not dropped: ${e && e.message})`);
+    }
+  }
+  log(`  [render] ${apply ? 'removed' : 'would remove'} the sandbox (${notes.join(' and ')}); the live app is untouched`);
+  if (apply) {
+    await recordSandbox(db, inst.id, dbGone
+      ? { state: 'removed', serviceId: null, serviceUrl: null, dbName: null, error: null }
+      : { state: 'removed', serviceId: null, serviceUrl: null, error: `The sandbox app was removed, but its database ${sb.dbName} is still inside your app’s database server.` });
+  }
+  return { removed: true };
+}
+
+module.exports = { standupSandbox, removeSandbox, sandboxDatabase, recordSandbox, withDatabase };

package/scripts/bongos/provision-render.js

@@ -34,6 +34,7 @@
 const { RenderApi } = require('./render-api.js');
 const payload = require('./render-payload.js');
 const { parseTargetRef } = require('./provision-repo-auth.js');
+const sandbox = require('./provision-render-sandbox.js');
 
 // A key waiting longer than this was lent for a run that never came. It is refused and
 // cleared rather than spent late.
@@ -147,7 +148,18 @@ async function renderStandupInstance(inst, deps, intent) {
     const owners = await api.listOwners();
     if (!owners.some((o) => o.id === host.ownerId)) return refuse(`this Render key cannot reach workspace ${host.ownerId}`);
 
-    return host.mode === 'adopt' ? await adopt(api, inst, host, deps) : await greenfield(api, inst, host, deps);
+    // An app already up that only asked for its sandbox (render-sandbox.js
+    // enqueueSandboxAdd) is not touched again: the run goes straight to the sandbox.
+    const sandboxOnly = !!(host.sandboxWanted && host.sandbox && host.sandbox.state === 'requested'
+      && host.serviceId && ['deploying', 'linked', 'live'].includes(host.state));
+    const app = sandboxOnly ? { ok: true } : (host.mode === 'adopt' ? await adopt(api, inst, host, deps) : await greenfield(api, inst, host, deps));
+    // The sandbox (ADR 0406, task 1005289): after the app, with the same key. Its failure
+    // is recorded on the sandbox and never fails the app.
+    if (app.ok && host.sandboxWanted) {
+      const fresh = deps.provisioning && deps.provisioning.getInstanceById ? ((await deps.provisioning.getInstanceById(db, inst.id)) || inst) : inst;
+      await sandbox.standupSandbox(api, fresh, { ...host, ...(fresh.app_host || {}) }, deps);
+    }
+    return app;
   } catch (e) {
     return refuse(plainReason(e));
   } finally {
@@ -190,9 +202,32 @@ async function afterProvision(inst, deps, intent, result) {
 // Teardown's half (ADR 0327 §3): forget the Render app, never delete it. The ids stay on
 // the row so an operator can still say which services were the project's; the owner
 // deletes them in their own Render dashboard if they want to stop paying.
-async function forgetRenderApp(inst, { db, log, apply }) {
+//
+// The SANDBOX is the one exception (ADR 0406 §7, task 1005289): the platform made it, so
+// the platform removes it — when the owner lent their key with the teardown (the running
+// teardown intent's borrowed_key_enc). The key is cleared here whatever happens.
+async function forgetRenderApp(inst, deps) {
+  const { db, log, apply } = deps;
   const host = inst.app_host;
   if (!host || host.platform !== 'render') return;
+  if (host.sandbox) {
+    let keyEnc = null, intentId = null;
+    try {
+      const { rows } = await db.query(
+        `SELECT id, borrowed_key_enc FROM provisioning_intents
+          WHERE instance_id = $1 AND action = 'teardown' AND state IN ('pending', 'running') AND borrowed_key_enc IS NOT NULL
+          ORDER BY created_at DESC LIMIT 1`, [inst.id]);
+      if (rows && rows[0]) { keyEnc = rows[0].borrowed_key_enc; intentId = rows[0].id; }
+      const secretBox = deps.secretBox || require('../../src/bongos/secret-box');
+      const api = keyEnc && host.ownerId ? renderApiFor(deps, secretBox.decrypt(keyEnc), host.ownerId) : null;
+      await sandbox.removeSandbox(inst, deps, api);
+    } catch (e) {
+      log(`  (sandbox not removed: ${e && e.message})`);
+      if (apply) await sandbox.recordSandbox(db, inst.id, { state: 'left', error: `The sandbox could not be removed, so it is still on your Render account: ${String((e && e.message) || e).split('\n')[0].slice(0, 200)}` }).catch(() => {});
+    } finally {
+      if (intentId != null) await clearBorrowedKey(db, intentId);
+    }
+  }
   const what = [host.serviceId && `service ${host.serviceId}`, host.postgresId && `database ${host.postgresId}`].filter(Boolean).join(' and ') || 'nothing yet';
   log(`  [render] ${apply ? 'disconnected' : 'would disconnect'} from Render (${what}); nothing on Render is deleted — the owner removes it in their own dashboard`);
   if (apply) await recordAppHost(db, inst.id, { state: 'disconnected' });

package/scripts/bongos/provision-teardown.js

@@ -40,7 +40,7 @@ async function teardownInstance(inst, deps) {
   if (inst.db_name) log(`  (left for the operator: dropdb ${dbName(inst)}, prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz)`);
   parkAddress(inst, { controlExec, log, apply });
   // The app's Render services are the OWNER's: forget them, never delete them (ADR 0327 §3, task 1004183).
-  await require('./provision-render.js').forgetRenderApp(inst, { db, log, apply });
+  await require('./provision-render.js').forgetRenderApp(inst, { ...deps, db, log, apply }); // …except the sandbox, removed when a key came with the teardown (ADR 0406 §7)
   // Revoke the instance's deploy key (ADR 0176) and remove its local halves. The
   // checkout itself is deliberately left in place (data is precious), so the key
   // files must NOT ride along — and a revoke skip must be LOUD: a torn-down project

package/scripts/bongos/publish-manifest.js

@@ -78,6 +78,7 @@ const PUBLISH_ALLOWLIST = [
   'modules/render-deploy/',  // the deploy page of a project whose app deploys through Render (task 1004270). default:false. MUST be here for the npm-release reason: modules/hall-ui/ ships as one subtree, so a released core without it carries deploy.js's loader for #rd-panel with no routes behind it.
   'modules/market-watch/',   // the weekly AI market watch (task 1004935, goal 1000137). default:false and empty for now, but MUST be here: shipped is not enabled, and a released core without it answers "unknown module" to an instance that turns it on; tests/market_watch_module.mjs (publishable) also reads its manifest.
   'modules/ai-studio/',      // AI generation for artists (task 1004916, ADR 0392): keys, prepaid balance, generate. default:false.
+  'modules/app-host/', // where the app runs (task 1004571): the options menu's panel, read from the hub. default:true.
   'modules/front-door-guide/', // the start-a-project guide (task 1005272): a capped AI chat for a signed-out visitor on the platform's key. default:false, hub first; shipped is not enabled.
   'modules/raise/',           // the /raise investor page (task 1004847, ADR 0384) — ships in core, enabled ONLY on the hub, like platform-identity. Owner decision 2026-10-25: the whole page, its copy and starting numbers included, lives in the repo so builders can contribute to it, accepting that it publishes with the core. Secrets never do: the investor password is RAISE_PASSWORD_HASH in the instance env. default:false.
   'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.

package/scripts/bongos/render-api.js

@@ -24,9 +24,13 @@
 // resource through the guard, so nothing is ever sent to or read from a resource whose
 // workspace was not checked.
 //
-// NO DELETE. The platform must not hold the ability to destroy infrastructure in an
-// account it does not own (ADR 0327 §3). There is no delete method, and _req refuses the
-// verb outright, so adding one later is a visible change to this file, not a one-liner.
+// NO DELETE — with ONE narrow exception. The platform must not hold the ability to destroy
+// infrastructure in an account it does not own (ADR 0327 §3), and _req refuses the verb
+// outright. The exception is the project's SANDBOX (ADR 0406 §7, task 1005289): a free
+// service the platform itself created, removed when the owner tears the project down with
+// their key lent. deleteSandboxService reads the service through the guard first and
+// refuses anything not named `…-sandbox` on the free plan, so it can never reach the
+// owner's live app; it is the only path to a DELETE in this file.
 
 'use strict';
 
@@ -133,6 +137,32 @@ class RenderApi extends JsonHttpApi {
     return this._req('PUT', `/services/${encodeURIComponent(serviceId)}/env-vars/${encodeURIComponent(key)}`, { value }, { dryRunResult: { key } });
   }
 
+  // The service of this exact name in this workspace, or null. Lets a re-run find a
+  // sandbox an earlier run created before its id reached the row, instead of making a
+  // second one. Every element of the list is checked through the guard.
+  async findServiceByName(name) {
+    const q = `/services?name=${encodeURIComponent(name)}&ownerId=${encodeURIComponent(this.ownerId)}&limit=20`;
+    const json = await this._req('GET', q, null, { dryRunResult: { items: [] } });
+    const items = Array.isArray(json) ? json : (json && json.items) || [];
+    const found = items.map((e) => (e && e.service) || e).filter((s) => s && typeof s.id === 'string');
+    found.forEach((s) => this.assertOwned(s, `service ${s.id}`));
+    return found.find((s) => s.name === name) || null;
+  }
+
+  // Remove a project's SANDBOX service — and nothing else (see the header). The service is
+  // read through the workspace guard, and refused unless it is named `…-sandbox` AND on
+  // the free plan: the owner's live app is never either.
+  async deleteSandboxService(serviceId) {
+    const svc = await this.getService(serviceId);
+    const plan = svc.serviceDetails && svc.serviceDetails.plan;
+    if (!/-sandbox$/.test(String(svc.name || '')) || plan !== 'free') {
+      throw new RenderApiError(`refusing to delete service ${serviceId}: it is not a free sandbox the platform created (ADR 0406 §7)`);
+    }
+    const path = `/services/${encodeURIComponent(serviceId)}`;
+    if (this.dryRun) { this.log(`[dry-run] Render DELETE ${path}`); return { dryRun: true }; }
+    return super._req('DELETE', path, null);
+  }
+
   async triggerDeploy(serviceId) {
     await this.getService(serviceId);
     return this._req('POST', `/services/${encodeURIComponent(serviceId)}/deploys`, {}, { dryRunResult: { id: null } });

package/scripts/bongos/render-payload.js

@@ -82,4 +82,42 @@ function renderServicePayload(inst, { ownerId, repoUrl, branch, webPlan, region,
   };
 }
 
-module.exports = { DEFAULTS, resourceName, plansFor, buildFor, renderPostgresPayload, renderServicePayload };
+// POST /services, for the project's SANDBOX (ADR 0406, task 1005289): the same repository
+// and build as the app, on Render's FREE plan, following `main` on every merge. It runs
+// with BONGOS_SANDBOX=1 so the app (and the starter's outbound gate, task 1005291) knows
+// it is not the live site. `dbUrl` is the sandbox's OWN database, never the live one.
+const SANDBOX_SUFFIX = 'sandbox';
+function sandboxServicePayload(inst, { ownerId, repoUrl, region, build, dbUrl }) {
+  const p = renderServicePayload(inst, { ownerId, repoUrl, branch: 'main', webPlan: 'free', region, build, dbUrl });
+  p.name = resourceName(inst, SANDBOX_SUFFIX);
+  p.autoDeploy = 'yes';
+  p.envVars = [{ key: 'BONGOS_SANDBOX', value: '1' }, ...p.envVars];
+  return p;
+}
+
+// The sandbox's database name inside the app's own database server: the project's slug
+// with underscores, ending `_sandbox`. Checked against a strict shape because it is put
+// into a CREATE / DROP DATABASE statement as an identifier.
+const SANDBOX_DB_RE = /^[a-z][a-z0-9_]{0,40}_sandbox$/;
+function sandboxDbName(inst) {
+  let base = resourceName(inst).replace(/-/g, '_').replace(/^[^a-z]+/, '').slice(0, 40);
+  if (!base) base = `project_${Number(inst.id) || 0}`;
+  const name = `${base}_sandbox`;
+  if (!SANDBOX_DB_RE.test(name)) throw new Error(`could not make a safe sandbox database name from '${inst.slug}'`);
+  return name;
+}
+
+// How an adopted service is built, read off Render's own answer, so the sandbox copies
+// it (ADR 0406 §7: "the sandbox is a new free service copying its build settings").
+// Returns null when the answer does not say enough to copy.
+function buildFromService(svc) {
+  const d = (svc && svc.serviceDetails) || {};
+  const runtime = d.runtime || d.env;
+  if (!RUNTIMES.includes(runtime)) return null;
+  if (runtime === 'docker') return { runtime: 'docker' };
+  const e = d.envSpecificDetails || {};
+  if (!e.startCommand) return null;
+  return { runtime, buildCommand: e.buildCommand || BUILD_DEFAULTS[runtime], startCommand: e.startCommand };
+}
+
+module.exports = { DEFAULTS, resourceName, plansFor, buildFor, renderPostgresPayload, renderServicePayload, sandboxServicePayload, sandboxDbName, buildFromService, SANDBOX_DB_RE };

package/scripts/bongos/seam-wiring-guard.js

@@ -97,11 +97,12 @@ const SEAM_CONSUMERS = {
   uiSections: {
     // Per-MODULE, not per-entry: hallWidgetScripts looks for one widget file per page
     // however many sections the module names — hall-widget.js for the index, and since
-    // task 1004301 task-widget.js for a task's page. Either one wires the declaration.
+    // task 1004301 task-widget.js for a task's page, and since task 1004571 settings-widget.js
+    // for the options menu. Any one wires the declaration.
     consumer: 'src/module-loader/loader.js hallWidgetScripts',
     kind: 'file',
     artifact: (dir) => path.join(dir, 'public', 'hall-widget.js'),
-    alternates: (dir) => [path.join(dir, 'public', 'task-widget.js')],
+    alternates: (dir) => [path.join(dir, 'public', 'task-widget.js'), path.join(dir, 'public', 'settings-widget.js')],
   },
   skills: {
     // moduleSkillSources resolves a declared name against the module's OWN tree or

package/scripts/gds/first-read.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// scripts/gds/first-read.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/first-read.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'first-read.js');

package/scripts/gds/provision-render-sandbox.js

@@ -0,0 +1,6 @@
+// scripts/gds/provision-render-sandbox.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-render-sandbox.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'provision-render-sandbox.js');

package/scripts/hall-preview/server.js

@@ -457,6 +457,8 @@ for (const key of MODULES_ON) {
   const isOn = (k) => !!(mods.enabled && mods.enabled[k]);
   if (stamped['index.html']) stamped['index.html'] = injectModuleHallWidgets(stamped['index.html'], hallWidgetScripts({ isEnabled: isOn }));
   if (stamped['task.html']) stamped['task.html'] = injectModuleHallWidgets(stamped['task.html'], hallWidgetScripts({ isEnabled: isOn, file: 'task-widget.js' }), 'task');
+  // the options menu's module panels (task 1004571)
+  if (stamped['settings.html']) stamped['settings.html'] = injectModuleHallWidgets(stamped['settings.html'], hallWidgetScripts({ isEnabled: isOn, file: 'settings-widget.js' }), 'settings');
   // ...and their assets, for the same set. The real asset route (serve-internal.js) gates on
   // the instance config's enabled set, which ignores --modules-on, so a widget injected for
   // a module this checkout's config leaves off 404'd and the slot stayed empty (task 1004940).

package/src/bongos/auth-admission.js

@@ -626,8 +626,72 @@ async function notifyHubOfInvite(githubLogin, { invited = true } = {}) {
   }
 }
 
+// WHERE THIS PROJECT'S OWNER TAKES IT OFFLINE OR DISCONNECTS IT (task 1004570). Both
+// controls live on the hub's Projects page for this project — the typed-name confirm and
+// the intent queue are there (ADR 0290) — so the hall only links to them and gains no
+// second delete path. Moved here from routes/core-update.js (task 1004571) so the kernel's
+// readAppStatusFromHub can name the same page; the route re-exports it. The hub origin and
+// this project's client id, which is its slug; null on a self-hosted instance or the hub itself, so the
+// hall shows no section rather than a dead link. The page resolves ?project=<slug>
+// against the visitor's OWN projects, so the link opens nothing for anyone else.
+function hubManageLinks(config) {
+  if (!config || typeof config.origin !== 'string' || !config.clientId) return null;
+  if (!/^https?:\/\/[^\s"'<>]+$/i.test(config.origin)) return null;
+  const origin = config.origin.replace(/\/+$/, '');
+  const page = `${origin}/projects?view=manage&project=${encodeURIComponent(String(config.clientId))}`;
+  let host = origin;
+  try { host = new URL(origin).host; } catch { /* keep the origin as written */ }
+  return { hub_host: host, manage_url: page, offline_url: `${page}#mDelete`, disconnect_url: `${page}#mDisconnect` };
+}
+
+// readAppStatusFromHub() — where THIS project's own app runs, asked of the hub (task
+// 1004571). We host every project's hall; its app runs on the owner's Render account, and
+// that setup's state lives in the hub's provisioning row, not here. So the hall asks, as
+// the project itself (client_id + client_secret, POST /sso/app-status), and the hub answers
+// with modules/provisioning/app-status.js's own shape for this project only.
+//
+// In the kernel beside the other hub calls for readApplicantProfileFromHub's reason: it
+// holds the project's hub client secret, and a module reaches it only through this narrow
+// port — no argument, one project, one direction in.
+//
+// Answers, never throws:
+//   { hub: false }                              — not federated (self-hosted, or the hub)
+//   { hub: true, reachable: false, manage }     — the hub did not answer (down, older hub)
+//   { hub: true, reachable: true, known, app, sandbox, manage }
+// `manage` is the hub's page for this project ({ manage_url, hub_host }, hubManageLinks
+// above), where the owner connects Render; it names an address and grants nothing.
+
+const HUB_APP_STATUS_TIMEOUT_MS = 5000;
+
+async function readAppStatusFromHub() {
+  let idp = null;
+  try { idp = loadIdpConfig(); } catch { idp = null; }
+  if (!idp) return { hub: false };
+  const links = hubManageLinks(idp);
+  const manage = links ? { manage_url: links.manage_url, hub_host: links.hub_host } : null;
+  try {
+    const r = await fetch(`${idp.origin}/api/bongos/sso/app-status`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+      signal: AbortSignal.timeout(HUB_APP_STATUS_TIMEOUT_MS),
+      body: JSON.stringify({ client_id: idp.clientId, client_secret: idp.clientSecret }),
+    });
+    const body = r.ok ? await r.json().catch(() => null) : null;
+    if (!body || body.ok !== true) return { hub: true, reachable: false, manage };
+    const app = body.app && typeof body.app === 'object' ? body.app : null;
+    // The sandbox beside the app (task 1005289); an older hub sends none.
+    const sandbox = body.sandbox && typeof body.sandbox === 'object' ? body.sandbox : null;
+    return { hub: true, reachable: true, known: body.known === true, app, sandbox, manage };
+  } catch (err) {
+    log.info('[auth] hub app-status read failed (non-blocking):', err.message);
+    return { hub: true, reachable: false, manage };
+  }
+}
+
 module.exports = {
   firstAdminLogin,
+  readAppStatusFromHub,
+  hubManageLinks,
   firstTimeAdmissionBlocked,
   instanceNeedsFirstAdmin,
   readApplicantProfileFromHub,

package/src/bongos/auth.js

@@ -57,7 +57,7 @@ const ic = require('../instance-config');
 const { branding, userAgent } = require('../branding');
 
 const { SCOPE, authConfigured, grantedScopeCoversRepos, idpConfigured, idpEnabled, loadIdpConfig, scopeForWebFlow } = require('./auth-config.js');
-const { firstAdminLogin, firstTimeAdmissionBlocked, instanceNeedsFirstAdmin, joinabilityMode, maybeSeatFirstAdmin, membershipKind, notifyHubOfInvite, openEnrollmentEnabled, readApplicantProfileFromHub, readApplicantViewFromHub, webAdmissionStatus } = require('./auth-admission.js');
+const { firstAdminLogin, firstTimeAdmissionBlocked, instanceNeedsFirstAdmin, joinabilityMode, maybeSeatFirstAdmin, membershipKind, notifyHubOfInvite, openEnrollmentEnabled, readAppStatusFromHub, readApplicantProfileFromHub, readApplicantViewFromHub, webAdmissionStatus } = require('./auth-admission.js');
 const { buildAuthorizeUrl, completeWebFlow, pollDeviceFlow, startDeviceFlow } = require('./auth-github.js');
 const { buildIdpAuthorizeUrl, completeDeviceExchange, completeIdpFlow, idpAuthorizeUrl, loadHubPublicKey, logoutTokenJtiSeenAndRecord, readApplicationVouch, verifyHubAssertion, verifyHubLogoutToken } = require('./auth-idp.js');
 const { addDiscordGuildMember, buildDiscordAuthorizeUrl, discordAuthorizeUrl, discordBotConfigured, discordConfigured, exchangeDiscordCode, fetchDiscordUser, isValidDiscordUserId, loadDiscordBotToken, loadDiscordCreds, removeDiscordGuildMember } = require('./auth-discord.js');
@@ -843,6 +843,7 @@ module.exports = {
   joinabilityMode,
   readApplicantProfileFromHub,
   readApplicantViewFromHub,
+  readAppStatusFromHub,
   notifyHubOfInvite,
   readApplicationVouch,
   firstTimeAdmissionBlocked,

package/src/bongos/module-scope-map.js

@@ -193,6 +193,10 @@ const MODULE_GLOBS = {
     'tests/front_door_guide_plan.mjs', 'tests/front_door_guide_db.mjs',
     'tests/front_door_guide_existing.mjs',
   ],
+  // Where the app runs (task 1004571): the options menu's panel on a project's hall.
+  'app-host': [
+    'modules/app-host/', 'tests/app_host.mjs',
+  ],
   // The /raise investor page (task 1004847, ADR 0384): hub-only.
   raise: [
     'modules/raise/',

package/src/bongos/routes/core-update.js

@@ -53,22 +53,9 @@ function hubDeployUrl(config) {
   return `${config.origin.replace(/\/+$/, '')}/deploy?project=${encodeURIComponent(String(config.clientId))}`;
 }
 
-// WHERE THIS PROJECT'S OWNER TAKES IT OFFLINE OR DISCONNECTS IT (task 1004570). Both
-// controls live on the hub's Projects page for this project — the typed-name confirm and
-// the intent queue are there (ADR 0290) — so the hall only links to them and gains no
-// second delete path. Same two inputs as hubDeployUrl (the hub origin and this project's
-// client id, which is its slug); null on a self-hosted instance or the hub itself, so the
-// hall shows no section rather than a dead link. The page resolves ?project=<slug>
-// against the visitor's OWN projects, so the link opens nothing for anyone else.
-function hubManageLinks(config) {
-  if (!config || typeof config.origin !== 'string' || !config.clientId) return null;
-  if (!/^https?:\/\/[^\s"'<>]+$/i.test(config.origin)) return null;
-  const origin = config.origin.replace(/\/+$/, '');
-  const page = `${origin}/projects?view=manage&project=${encodeURIComponent(String(config.clientId))}`;
-  let host = origin;
-  try { host = new URL(origin).host; } catch { /* keep the origin as written */ }
-  return { hub_host: host, manage_url: page, offline_url: `${page}#mDelete`, disconnect_url: `${page}#mDisconnect` };
-}
+// hubManageLinks — the hub's page for THIS project (task 1004570). Lives in the kernel's
+// auth-admission.js since task 1004571, which needs it too and may not import a route file.
+const { hubManageLinks } = require('../auth-admission');
 
 // WHERE THIS PROJECT'S UPDATE BUTTON GOES (task 1004296). The act itself never happens in
 // Settings: it is the deploy door's two-step confirm and auto-rollback (ADR 0293), and that

package/src/bongos/routes/modules.js

@@ -232,9 +232,20 @@ function contributeModuleDesk() {
   seams.contribute('governor.docket', { desk: 'rules.modules', gate: { permission: 'module.enable' }, read: async () => moduleDeskRows(listModules()) });
 }
 
+// The port `modules.catalog` (task 1005281): every module on disk with its words and
+// whether it is on, so a module (the lifecycle's first read-through) can name only real
+// modules without requiring core. Read-only, built per call from listModules().
+function registerModuleCatalogPort() {
+  if (seams.hasProvider('modules.catalog')) return;
+  seams.registerProvider('modules.catalog', () => listModules().map((m) => ({
+    key: m.key, title: m.title || m.key, description: m.description || '', enabled: m.enabled === true,
+  })));
+}
+
 module.exports = function buildModulesRouter() {
   contributeModuleRechecksToDocket();
   contributeModuleDesk();
+  registerModuleCatalogPort();
   // Task 1004399: carry tarballs written inside the installed core package (the old
   // store path) into the instance store before the next upgrade erases them. Async and
   // never fatal; a no-op in a single checkout, where the two paths are one directory.

package/src/bongos/serve-internal.js

@@ -418,15 +418,18 @@ function clientBundleScriptTag() {
 // [{ key, src }]; default reads the live enabled set. Pure + exported for the test.
 function injectModuleHallWidgets(html, scripts = hallWidgetScripts({ isEnabled: isModuleEnabled }), consumer = 'builders') {
   if (!Array.isArray(scripts) || scripts.length === 0) return html;
-  const tags = scripts
-    .map((s) => `<script src="${s.src}" defer></script>`)
-    .join('');
   // Anchor on the consuming page script's <script> (builders.js on the index, task.js on
-  // a task's page — task 1004301) regardless of its ?v= stamp, so the module widgets
-  // always land immediately before the consumer: both are `defer`, so they run in
-  // document order, and a widget's listener exists before the page first announces.
+  // a task's page — task 1004301; settings.js on the options menu — task 1004571)
+  // regardless of its ?v= stamp, so the module widgets always land immediately before the
+  // consumer. A widget loads the way its consumer does: builders.js and task.js are
+  // `defer`, so their widgets are too and run in document order; settings.js is a plain
+  // script, so its widgets are plain too — a deferred one would run after it had mounted.
   const name = /^[a-z-]+$/.test(consumer) ? consumer : 'builders';
   const anchor = html.match(new RegExp(`<script src="\\/builders\\/${name}\\.js[^"]*"[^>]*><\\/script>`));
+  const defer = !anchor || /\sdefer[\s>=]/.test(anchor[0]);
+  const tags = scripts
+    .map((s) => `<script src="${s.src}"${defer ? ' defer' : ''}></script>`)
+    .join('');
   if (anchor) return html.replace(anchor[0], tags + anchor[0]);
   return html.includes('</body>') ? html.replace('</body>', `${tags}</body>`) : html + tags;
 }
@@ -1171,6 +1174,17 @@ function mountInternalSurfaces(app) {
     );
   }
 
+  // task 1004571: the options menu. A module that ships public/settings-widget.js
+  // registers a panel through window.OTB.contributeSettingsPanel; it is loaded just before
+  // settings.js, which mounts every registered panel. With none enabled, nothing changes.
+  if (buildersHtml['settings.html']) {
+    buildersHtml['settings.html'] = injectModuleHallWidgets(
+      buildersHtml['settings.html'],
+      hallWidgetScripts({ isEnabled: isModuleEnabled, file: 'settings-widget.js' }),
+      'settings',
+    );
+  }
+
   // Serve enabled modules' browser assets at /modules/<key>/public/* — the URL the
   // loader's hallWidgetScripts projection points at. Mounted BEFORE the /builders
   // static handler. Gated per-request on the live enabled set so a disabled module's

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.16'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.18'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');
@@ -409,6 +409,11 @@ module.exports = {
   //     1002304). The guild rides only beside a profile, so a null profile is a
   //     null view; an older hub that sends no guild answers guild: null.
   get readApplicantViewFromHub() { return require('./bongos/auth').readApplicantViewFromHub; },
+  // readAppStatusFromHub() — where THIS project's app runs, read from the hub with the
+  //     project's own client credentials (task 1004571). The same narrow-port posture: no
+  //     argument, so a module can neither widen nor re-address it, and the secret stays off
+  //     the doorway. Never throws: { hub: false } | { hub: true, reachable, known?, app?, manage }.
+  get readAppStatusFromHub() { return require('./bongos/auth').readAppStatusFromHub; },
   // notifyHubOfInvite(githubLogin, { invited }) — tell the hub about one of THIS
   //     project's invites (true) or its rescind (false), so the invitee sees it in
   //     My Projects (task 1002818, ADR 0353). The same narrow-port reason as the