@bongos/core 1.20.37 → 1.20.39

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

@@ -22,6 +22,7 @@ const REAP_EVERY_MS = 60 * 1000;
 const PROGRAMS = Object.freeze({
   npm: (args, o) => spawn('npm', args, o),
   dropdb: (args, o) => spawn('dropdb', args, o),
+  psql: (args, o) => spawn('psql', args, o),
   createdb: (args, o) => spawn('createdb', args, o),
   pg_dump: (args, o) => spawn('pg_dump', args, o),
   pg_restore: (args, o) => spawn('pg_restore', args, o),
@@ -49,27 +50,60 @@ function runCommand({ cmd, args, env, cwd }) {
   });
 }
 
-/** Does something answer /healthz on the loopback port? */
-function probeHealth(port) {
+/** GET one loopback path: { status, body } (body capped), or { error } when nothing answered. */
+function getLoopback(port, urlPath) {
   return new Promise((resolve) => {
-    const req = http.get({ host: '127.0.0.1', port, path: '/healthz', timeout: 2000 }, (res) => {
-      res.resume();
-      resolve(res.statusCode === 200);
+    const req = http.get({ host: '127.0.0.1', port, path: urlPath, timeout: 3000, headers: { accept: 'application/json' } }, (res) => {
+      let body = '';
+      res.on('data', (d) => { if (body.length < 16384) body += d; });
+      res.on('end', () => resolve({ status: res.statusCode, body }));
+      res.on('error', (e) => resolve({ error: e.message }));
     });
-    req.on('error', () => resolve(false));
-    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.on('error', (e) => resolve({ error: e.message }));
+    req.on('timeout', () => { req.destroy(); resolve({ error: 'timed out' }); });
   });
 }
 
+/**
+ * Can the preview SERVE DATA? Not just "does something answer": /healthz touches no database,
+ * and on the first live run a preview that answered it 200 returned 500 on every page.
+ *
+ *   1. /healthz answers 200 (the process is up).
+ *   2. /version's schemaPending is not null. It is computed from a read of schema_migrations,
+ *      and is null exactly when that read fails — so this proves the copy is reachable. A
+ *      version too old to carry the field at all is passed on to step 3 instead.
+ *   3. a database-backed route is not a server error: /api/bongos/me answers 401 or 200 when
+ *      the database and auth path work, and 500 when they do not.
+ *
+ * Returns { ok, reason }; the reason is shown to the owner, so it names the failing step.
+ */
+async function probeHealth(port, get = getLoopback) {
+  const h = await get(port, '/healthz');
+  if (h.error || h.status !== 200) return { ok: false, reason: h.error ? `/healthz: ${h.error}` : `/healthz answered ${h.status}` };
+  const v = await get(port, '/version');
+  if (v.error || v.status !== 200) return { ok: false, reason: v.error ? `/version: ${v.error}` : `/version answered ${v.status}` };
+  let info = null;
+  try { info = JSON.parse(v.body); } catch { /* not JSON: handled below */ }
+  if (!info || typeof info !== 'object') return { ok: false, reason: '/version did not answer with JSON' };
+  if ('schemaPending' in info && info.schemaPending === null) {
+    return { ok: false, reason: '/version reports schemaPending null: the database copy could not be read' };
+  }
+  const me = await get(port, '/api/bongos/me');
+  if (me.error || me.status >= 500) {
+    return { ok: false, reason: me.error ? `/api/bongos/me: ${me.error}` : `a database-backed read (/api/bongos/me) answered ${me.status}` };
+  }
+  return { ok: true };
+}
+
 /**
  * Build the production supervisor: the port from NPM_RELEASE_PREVIEW_PORT (default 3190,
  * loopback only), installs cached under ~/.cache/bongos-preview, and a timer that stops
  * an idle preview and a hook that stops it when this process does.
  */
-function createRuntime({ liveDb, log, env = process.env } = {}) {
+function createRuntime({ liveDb, log, env = process.env, instanceRoot = null } = {}) {
   const port = Number(env.NPM_RELEASE_PREVIEW_PORT) || DEFAULT_PORT;
   const supervisor = createSupervisor({
-    run: runCommand, spawn, probe: probeHealth, liveDb, log, port, env,
+    run: runCommand, spawn, probe: probeHealth, liveDb, log, port, env, instanceRoot,
     cacheRoot: path.join(os.homedir(), '.cache', 'bongos-preview'),
   });
   const timer = setInterval(() => {

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

@@ -1,29 +1,44 @@
 'use strict';
 
 // modules/npm-release/preview/supervisor.js — starts, watches and stops the ONE version
-// preview this hall may run (task 1004300, ADR 0349).
+// preview this hall may run (task 1004300, ADR 0349; hardened by task 1004465).
 //
 // 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
+// wait until it can serve data. 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.
+//
+// THREE THINGS task 1004465 ADDED, each from the first live run:
+//   * the child's output is kept (redacted, capped) and shown when a start fails;
+//   * "running" means the child can serve DATA, not merely that it answers /healthz;
+//   * a stop waits for the child to exit and really drops the copy, or says it could not.
 
 const os = require('node:os');
 const fs = require('node:fs');
 const path = require('node:path');
-const { buildPreviewEnv } = require('./env');
+const { buildPreviewEnv, PREVIEW_DB } = require('./env');
 const cmds = require('./commands');
+const { createChildLog, redact, secretValues } = require('./childlog');
 
 const IDLE_MS = 20 * 60 * 1000;
 const DEFAULT_PORT = 3190;
 const HEALTH_TRIES = 40;
 const HEALTH_INTERVAL_MS = 1500;
+// How long a stopping child gets to exit on SIGTERM before SIGKILL, and how long after that.
+const KILL_WAIT_MS = 5000;
+const KILL_FINAL_WAIT_MS = 2000;
+
+// The ONLY files of the live instance's config/ copied into the preview's scratch instance:
+// the identity and switch packs a hall reads at boot. An allow-list, like the environment
+// (env.js): a deny-list forgets the next credential file someone adds, an allow-list cannot.
+// Anything else in config/ (go-live.json, key files, whatever comes next) stays behind.
+const CONFIG_COPY = /^(branding|modules|government|ideas|design-tokens)(\.neutral)?\.json$/;
 
 // How far behind the running version a preview may reach, counted in PUBLISHED versions.
 const WINDOW = 30;
@@ -52,43 +67,123 @@ function previewable(version, { published, running, window = WINDOW } = {}) {
   return { ok: true };
 }
 
+/**
+ * Copy the live instance's host content the child needs to boot as an instance rather than
+ * as a bare install: config/ (branding, module switches, government) and migrations/instance/.
+ * A source that is absent is skipped; any other failure fails the start. Only the allow-listed
+ * pack files of config/ are copied (CONFIG_COPY).
+ */
+function copyInstance({ fsImpl, from, to }) {
+  const parts = [
+    // The directory itself always passes the filter; files are copied only when allow-listed.
+    ['config', (src) => path.basename(src) === 'config' || CONFIG_COPY.test(path.basename(src))],
+    [path.join('migrations', 'instance'), () => true],
+  ];
+  for (const [rel, filter] of parts) {
+    const src = path.join(from, rel);
+    try {
+      if (!fsImpl.existsSync(src)) continue;
+      fsImpl.mkdirSync(path.dirname(path.join(to, rel)), { recursive: true });
+      fsImpl.cpSync(src, path.join(to, rel), { recursive: true, filter });
+    } catch (e) {
+      throw new Error(`could not copy the instance ${rel} into the preview: ${e && e.message}`);
+    }
+  }
+}
+
 /**
  * @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 {Function} o.probe  (port) => Promise of boolean | { ok, reason } — can the preview serve data
  * @param {string} o.liveDb   the live database name (the source of the copy)
  * @param {string} o.cacheRoot  where versions are installed
+ * @param {string} [o.instanceRoot]  the live instance's root; its config/ and migrations/instance/
+ *                           are copied into the preview's scratch instance directory
  * @param {object} [o.env]    the live environment (read by buildPreviewEnv only)
  */
 function createSupervisor({
-  run, spawn, probe, liveDb, cacheRoot,
-  env = process.env, port = DEFAULT_PORT,
+  run, spawn, probe, liveDb, cacheRoot, instanceRoot = null,
+  env = process.env, port = DEFAULT_PORT, killWaitMs = KILL_WAIT_MS,
   now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
   fsImpl = fs, tmpdir = os.tmpdir(), idleMs = IDLE_MS,
   log = { info() {}, warn() {}, error() {} },
+  copy = copyInstance,
 } = {}) {
+  // The one database a drop may ever name is the fixed copy. If the live database WERE that
+  // name, every stop would drop the live hall's data, so refuse to be built at all.
+  if (liveDb === PREVIEW_DB) throw new Error(`the live database cannot be named ${PREVIEW_DB}: that name is the preview's copy and is dropped on every stop`);
+
   let state = { state: 'idle', version: null, stage: null, error: null, startedAt: null, lastTouch: null };
   let child = null;
   let workDir = null;
+  let childLog = null;     // the running or just-stopped child's output
+  let keptTail = [];       // its tail, kept after the scratch directory is gone
+  let secrets = secretValues(env);
+  let exitInfo = null;     // { code } once the child has exited
+  let exited = Promise.resolve();
 
   const set = (patch) => { state = { ...state, ...patch }; };
-  const status = () => ({ ...state, port, idle_ms: idleMs });
+  const status = () => ({ ...state, port, idle_ms: idleMs, log_tail: childLog ? childLog.tail() : keptTail });
 
   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)}` : '';
+      const tail = r && r.stderr ? `: ${redact(String(r.stderr).trim().slice(-300), secrets)}` : '';
       throw new Error(`${stage} failed (exit ${r ? r.code : '?'})${tail}`);
     }
   }
 
+  // Run a command only if it can touch nothing but the copy. Never throws for a failed command.
+  async function runDrop(command) {
+    if (!cmds.targetsOnlyPreviewDb(command)) throw new Error(`refusing a database command that does not name only ${PREVIEW_DB}`);
+    try { return (await run(command)) || { code: -1, stderr: 'no result' }; } catch (e) { return { code: -1, stderr: e && e.message }; }
+  }
+
+  /**
+   * Drop the copy, really. dropdb --force first (it ends stray connections itself); if that
+   * is refused, end the copy's connections — the copy's alone — and drop plainly. Returns
+   * null when the copy is gone, else a sentence saying it is not.
+   */
+  async function dropCopy() {
+    const first = await runDrop(cmds.dropDbCommand());
+    if (first.code === 0) return null;
+    await runDrop(cmds.terminateBackendsCommand());
+    const second = await runDrop(cmds.dropDbPlainCommand());
+    if (second.code === 0) return null;
+    const why = redact(String(second.stderr || first.stderr || '').trim().slice(-200), secrets);
+    return `the copy database ${PREVIEW_DB} could not be dropped (exit ${second.code})${why ? `: ${why}` : ''}`;
+  }
+
+  // Ask the child to stop and WAIT for it, then insist. The drop that follows needs the
+  // child's database connections gone; killing without waiting is what left the copy behind.
+  async function stopChild(c) {
+    if (exitInfo) return;
+    try { c.kill('SIGTERM'); } catch (e) { log.warn(`preview child would not stop: ${e && e.message}`); }
+    await Promise.race([exited, sleep(killWaitMs)]);
+    if (exitInfo) return;
+    try { c.kill('SIGKILL'); } catch { /* already gone */ }
+    await Promise.race([exited, sleep(KILL_FINAL_WAIT_MS)]);
+  }
+
   // Everything a start or a stop leaves behind: the child, the copy, the scratch directory.
+  // Returns null when all of it is gone, else the sentence saying the copy is not.
   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}`); }
+    const c = child;
+    child = null;
+    if (c) await stopChild(c);
+    if (childLog) { keptTail = childLog.tail(); childLog.close(); childLog = null; }
+    const dropError = await dropCopy();
+    if (dropError) log.error(`preview: ${dropError}`);
     if (workDir) { try { fsImpl.rmSync(workDir, { recursive: true, force: true }); } catch { /* best effort */ } workDir = null; }
+    return dropError;
+  }
+
+  // A few of the child's last lines, to sit in the error message itself.
+  function withTail(message, lg) {
+    const lines = lg ? lg.tail(5) : [];
+    return lines.length ? `${message}. Its last output: ${lines.join(' | ')}`.slice(0, 900) : message;
   }
 
   async function launch(version) {
@@ -97,41 +192,78 @@ function createSupervisor({
       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 });
+
+      // The child's working directory is a scratch INSTANCE: the live instance's config/ and
+      // migrations/instance/, copied. Run from the bare install directory it had no config/
+      // at all (no branding, no module switches) and was not shaped like a hall.
+      let instanceDir;
+      let prefix;
+      if (instanceRoot) {
+        instanceDir = path.join(workDir, 'instance');
+        fsImpl.mkdirSync(instanceDir, { recursive: true });
+        copy({ fsImpl, from: instanceRoot, to: instanceDir });
+        try { prefix = JSON.parse(fsImpl.readFileSync(path.join(instanceDir, 'config', 'branding.json'), 'utf8')).envPrefix; } catch { /* no branding pack: the default prefix */ }
+      }
+      const childEnv = buildPreviewEnv({ env, port, scratchHome: home, instanceRoot: instanceDir, envPrefix: prefix });
+      secrets = secretValues(env, childEnv);
+      keptTail = [];
+      childLog = createChildLog({ secrets, fsImpl, file: path.join(workDir, 'preview.log') });
+      exitInfo = null;
 
       await step('install', { ...cmds.installCommand({ cacheRoot, version }), env: childEnv });
-      await step('drop-old-copy', cmds.dropDbCommand());
+      set({ stage: 'drop-old-copy' });
+      const leftover = await dropCopy();
+      if (leftover) throw new Error(leftover);
       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 }));
+      await step('migrate', cmds.migrateCommand({ cacheRoot, version, env: childEnv, instanceDir }));
 
       set({ stage: 'launch' });
-      child = spawn(process.execPath, [cmds.entryPath(cacheRoot, version)], {
-        cwd: cmds.versionDir(cacheRoot, version), env: childEnv, stdio: 'ignore',
+      // The child's output is kept (redacted, capped): its errors used to go nowhere.
+      const mine = childLog;
+      const spawned = spawn(process.execPath, [cmds.entryPath(cacheRoot, version)], {
+        cwd: instanceDir || cmds.versionDir(cacheRoot, version), env: childEnv, stdio: ['ignore', 'pipe', 'pipe'],
       });
-      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();
-        }
+      child = spawned;
+      exited = new Promise((resolve) => {
+        spawned.on('exit', (code) => {
+          exitInfo = { code };
+          resolve();
+          // A child that dies on its own must not leave a copy behind or a page waiting on it.
+          if (child === spawned && state.state === 'running') {
+            log.warn(`preview of ${version} exited (${code})`);
+            set({ state: 'failed', stage: 'exited', error: withTail(`the preview process exited (${code})`, mine) });
+            cleanup().then((err) => { if (err) set({ error: `${state.error}; ${err}` }); });
+          }
+        });
       });
+      for (const stream of [spawned.stdout, spawned.stderr]) {
+        if (stream && typeof stream.on === 'function') stream.on('data', (d) => mine.append(String(d)));
+      }
 
       set({ stage: 'health' });
+      // READY MEANS IT CAN SERVE DATA. The probe must see the database and the auth path work,
+      // not just the process answer (probeHealth in runtime.js); a preview that cannot is
+      // failed here, with why, rather than reported running.
       let up = false;
+      let why = 'it did not answer';
       for (let i = 0; i < HEALTH_TRIES && !up; i++) {
-        up = await probe(port);
-        if (!up) await sleep(HEALTH_INTERVAL_MS);
+        if (exitInfo) throw new Error(withTail(`the preview process exited (${exitInfo.code}) before it could serve data`, mine));
+        const r = await probe(port);
+        up = r === true || !!(r && r.ok);
+        if (!up) {
+          if (r && r.reason) why = r.reason;
+          await sleep(HEALTH_INTERVAL_MS);
+        }
       }
-      if (!up) throw new Error('the preview did not answer in time');
+      if (!up) throw new Error(withTail(`the preview started but could not serve data (${why})`, mine));
       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();
+      set({ state: 'failed', error: redact(e && e.message ? e.message : String(e), secrets) });
+      const dropError = await cleanup();
+      if (dropError) set({ error: `${state.error}; ${dropError}` });
     }
   }
 
@@ -146,13 +278,20 @@ function createSupervisor({
       if (state.version === version) return { ok: true, already: true, status: status(), done: Promise.resolve() };
       return { ok: false, code: 'preview_busy', status: status() };
     }
+    keptTail = [];
     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();
+    const dropError = await cleanup();
+    // A copy that is still there is NOT idle: say so, where the deploy page will show it.
+    if (dropError) {
+      set({ state: 'failed', stage: 'drop', error: dropError, startedAt: null, lastTouch: null });
+      return status();
+    }
+    keptTail = [];
     set({ state: 'idle', version: null, stage: null, error: null, startedAt: null, lastTouch: null });
     return status();
   }
@@ -172,4 +311,4 @@ function createSupervisor({
   return { start, stop, status, touch, reapIdle };
 }
 
-module.exports = { createSupervisor, previewable, IDLE_MS, DEFAULT_PORT, WINDOW };
+module.exports = { createSupervisor, previewable, copyInstance, IDLE_MS, DEFAULT_PORT, WINDOW };

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

@@ -6,3 +6,6 @@
 /* A stage's sentence sits under its head (work.js says why) and needs air before the first
    row, which drops its own top rule and padding in oversight.css. */
 #nr-work .ov-group > .ov-row__sub { margin: 8px 0 6px; }
+
+/* the preview process output shown under a failed preview (task 1004465) */
+.ov-log { max-height: 16rem; overflow: auto; margin: 0.5rem 0 0; padding: 0.5rem 0.75rem; font: 12px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre-wrap; word-break: break-word; background: rgba(127, 127, 127, 0.12); border-radius: 6px; }

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

@@ -192,7 +192,12 @@
       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>`;
+      // What the preview process itself printed (secrets already removed on the server), so a
+      // failed preview can be diagnosed here without a shell on the box (task 1004465).
+      const lines = Array.isArray(preview.log_tail) ? preview.log_tail : [];
+      const output = lines.length ? `<details open><summary>What the preview printed</summary><pre class="ov-log">${escapeHtml(lines.join('\n'))}</pre></details>` : '';
+      const headline = preview.stage === 'drop' ? `The copy of the data for ${v} could not be removed.` : `The preview of ${v} did not start.`;
+      return `<div class="ov-note ov-note--warn"><p><strong>${headline}</strong> ${escapeHtml(preview.error || '')}</p>${output}<button type="button" class="ov-toggle" data-preview-stop>${preview.stage === 'drop' ? 'Try again' : '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>

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

@@ -55,6 +55,7 @@ module.exports = function buildNpmReleasePreviewRouter({
   const router = express.Router();
   const sup = supervisor || lazySupervisor(() => require('../preview/runtime').createRuntime({
     liveDb: process.env.PGDATABASE || api.instanceDbName(),
+    instanceRoot: api.resolveInstanceRoot(),
     log,
   }));
   const mayPreview = api.requirePermission('core.pin.move');

package/modules/platform-identity/instance-feedback.js

@@ -0,0 +1,142 @@
+'use strict';
+
+// modules/platform-identity/instance-feedback.js — feedback about Bongos ITSELF,
+// relayed up from a federated project to the hub (task 1004462).
+//
+// A builder on a hosted project runs `bongos feedback "…"`. Their OWN instance
+// stamps who sent it and which core it runs, and relays it here over the
+// hub-federation client credential (ADR 0141) — the same server-to-server channel
+// as the activity rollup. This file turns that relay into a filing on the hub:
+//
+//   kind 'bug'  → a task in the building version's MAINTENANCE goal, at 'backlog'
+//                 (ADR 0262's homeless-bug home, reached through the
+//                 'instance-feedback' routing vector).
+//   kind 'idea' → an idea_inbox row for /idea-triage, exactly as any goal-less
+//                 idea lands — a suggestion is not a defect, and the maintenance
+//                 goal is for defects.
+//
+// ALWAYS 'backlog', never 'ready' — the owner's decision (2026-09-30). Anyone on
+// any tenant project can send this, so an approval stands between a report and
+// paid agent work. That is enforced by passing NO filer rank: decideLanding reads
+// an absent rank as untrusted, so even the owner's own feedback waits for the nod
+// rather than inheriting a hub rank the instance never vouched for.
+//
+// THE ATTRIBUTION IS THE HUB'S, NOT THE INSTANCE'S. Client credentials prove WHICH
+// PROJECT is calling and nothing about WHO sent it, so the sender must hold a
+// membership on that project carrying the hub's own sign-in witness
+// (membershipBacksRollup — the ADR 0205 rule the rollup uses). The login printed
+// on the task is then read from the hub's account row, never from the body.
+
+const FEEDBACK_KINDS = Object.freeze({ bug: 'bug', idea: 'feature' });
+const MESSAGE_MAX = 4000;
+const TITLE_MAX = 120;
+
+// Per-hour caps, counted in memory on this hub process. Two, because they stop
+// different things: one noisy builder, and one project relaying for many.
+const FEEDBACK_WINDOW_MS = 60 * 60 * 1000;
+const PER_SENDER_LIMIT = 10;
+const PER_PROJECT_LIMIT = 30;
+
+// makeFeedbackLimiter — a sliding-window counter keyed by project and sender.
+// `take` records a filing only when BOTH caps have room, so a refusal on one cap
+// never spends the other.
+function makeFeedbackLimiter({ now = Date.now } = {}) {
+  const buckets = new Map(); // key -> timestamp[]
+  function prune(key, t) {
+    const arr = buckets.get(key);
+    if (!arr) return [];
+    while (arr.length && arr[0] <= t - FEEDBACK_WINDOW_MS) arr.shift();
+    if (arr.length === 0) buckets.delete(key);
+    return arr;
+  }
+  function take(clientId, githubId) {
+    const t = now();
+    const checks = [
+      [`p:${clientId}`, PER_PROJECT_LIMIT, 'project'],
+      [`s:${clientId}:${githubId}`, PER_SENDER_LIMIT, 'sender'],
+    ];
+    for (const [key, limit, scope] of checks) {
+      const arr = prune(key, t);
+      if (arr.length >= limit) {
+        const retryAfter = Math.max(1, Math.ceil((arr[0] + FEEDBACK_WINDOW_MS - t) / 1000));
+        return { ok: false, scope, retryAfter };
+      }
+    }
+    for (const [key] of checks) {
+      if (!buckets.has(key)) buckets.set(key, []);
+      buckets.get(key).push(t);
+    }
+    return { ok: true };
+  }
+  return { take, _buckets: buckets };
+}
+
+// A version stamp from the instance: short, and only the characters a version
+// string or an OS name uses, so it cannot carry markdown or links into the task.
+function cleanStamp(v) {
+  if (typeof v !== 'string') return null;
+  const s = v.trim().slice(0, 40);
+  return /^[\w.+\- ]+$/.test(s) ? s : null;
+}
+
+// The task title: the first non-empty line, trimmed to fit.
+function feedbackTitle(message) {
+  const first = String(message).split('\n').map((l) => l.trim()).find(Boolean) || 'Feedback';
+  const title = first.length > TITLE_MAX ? `${first.slice(0, TITLE_MAX - 1)}…` : first;
+  return `Feedback: ${title}`;
+}
+
+function feedbackBody({ message, client, account, githubId, context = {} }) {
+  const who = account && account.github_login ? `@${account.github_login}` : `GitHub user ${githubId}`;
+  const project = client.name ? `${client.name} (${client.origin || client.client_id})` : (client.origin || client.client_id);
+  const stamps = [
+    ['Core', cleanStamp(context.core_version)],
+    ['CLI', cleanStamp(context.cli_version)],
+    ['OS', cleanStamp(context.os)],
+  ].filter(([, v]) => v).map(([k, v]) => `${k} ${v}`).join(' · ');
+  // The hub's own attribution comes FIRST and the sender's words follow as a
+  // quote, so text they type can never pose as the footer a reviewer trusts.
+  const quoted = String(message).trim().split('\n').map((l) => `> ${l}`).join('\n');
+  return [
+    'Sent from a managed project with `bongos feedback`.',
+    `- Project: ${project}`,
+    `- Sent by: ${who}`,
+    ...(stamps ? [`- Running: ${stamps}`] : []),
+    '',
+    quoted,
+  ].join('\n');
+}
+
+// fileInstanceFeedback — file one relayed report. `deps.capture` is the
+// `ideas.capture` port; `deps.getAccount` and `deps.hubBuilderId` read the hub's
+// own rows for the sender. Returns the landing the CLI prints.
+async function fileInstanceFeedback({ client, githubId, message, kind, context }, deps) {
+  const account = await deps.getAccount(githubId).catch(() => null);
+  const capturedBy = await deps.hubBuilderId(githubId).catch(() => null);
+  const idea = await deps.capture({
+    title: feedbackTitle(message),
+    bodyMd: feedbackBody({ message, client, account, githubId, context }),
+    kind: FEEDBACK_KINDS[kind],
+    capturedBy,
+    filerRank: null, // untrusted by design — see the header
+    filedVia: 'api',
+    vector: 'instance-feedback',
+    suggestedPriority: 3,
+  });
+  const routing = (idea && idea.routing) || {};
+  return routing.routed
+    ? { landed: 'task', task_id: String(routing.task_id), goal_id: String(routing.goal_id), status: routing.status, idea_id: String(idea.id) }
+    : { landed: 'inbox', idea_id: String(idea.id) };
+}
+
+module.exports = {
+  FEEDBACK_KINDS,
+  MESSAGE_MAX,
+  PER_SENDER_LIMIT,
+  PER_PROJECT_LIMIT,
+  FEEDBACK_WINDOW_MS,
+  makeFeedbackLimiter,
+  feedbackTitle,
+  feedbackBody,
+  fileInstanceFeedback,
+};

package/modules/platform-identity/module.json

@@ -16,5 +16,5 @@
     "pollers": ["code-sweep", "visibility-pull", "guild-totals"]
   },
   "provides": ["platform-identity.hub", "project.publishGate", "project.catalog"],
-  "consumes": []
+  "consumes": ["ideas.capture"]
 }

package/modules/platform-identity/routes/sso.js

@@ -26,6 +26,10 @@ const hubDevice = require('../hub-device');
 // The D7 applicant-profile read (task 1002972) and the echo that gates it.
 const applicantProfile = require('../applicant-profile');
 const applicationEcho = require('../application-echo');
+const instanceFeedback = require('../instance-feedback');
+
+// One limiter per hub process for POST /sso/feedback (task 1004462).
+const feedbackLimiter = instanceFeedback.makeFeedbackLimiter();
 
 // Per-IP cap for POST /sso/applicant-profile — DEFENCE IN DEPTH behind the echo
 // gate, not the gate itself (task 1002972 grade advisory). The echo already
@@ -692,5 +696,63 @@ module.exports = function ssoRoutes() {
     }
   });
 
+  // POST /sso/feedback — a federated project relays one builder's feedback about
+  // Bongos itself (task 1004462). A bug becomes a 'backlog' task in the building
+  // version's maintenance goal; an idea becomes an inbox row. Why always backlog,
+  // and why the sender must be a witnessed member: ../instance-feedback.js.
+  //
+  // rank: public — authenticated by client_id + client_secret, not a builder rank.
+  // The per-project and per-sender caps run after the client check, so an
+  // unauthenticated caller cannot spend a real project's allowance.
+  router.post('/sso/feedback', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      client_id: { required: true, type: 'string', maxLength: 200 },
+      client_secret: { required: true, type: 'string', maxLength: 512 },
+      github_id: { required: true },
+      message: { required: true, type: 'string', maxLength: instanceFeedback.MESSAGE_MAX },
+      kind: { type: 'string', enum: Object.keys(instanceFeedback.FEEDBACK_KINDS) },
+      context: {},
+    })) return;
+    const b = req.body || {};
+    try {
+      const client = await pi.getClient(b.client_id, { pool });
+      if (!client || client.status !== 'active' || !pi.clientSecretValid(client, b.client_secret)) {
+        return res.fail('invalid_client', 401);
+      }
+      if (!pi.isNumericGithubId(b.github_id)) return res.fail('invalid_github_id', 400);
+      if (!String(b.message).trim()) return res.fail('message_required', 400);
+      const membership = await pi.getMembership(client.client_id, b.github_id, { pool });
+      if (!pi.membershipBacksRollup(membership)) return res.fail('membership_required', 409);
+      const allowed = feedbackLimiter.take(client.client_id, String(b.github_id));
+      if (!allowed.ok) {
+        res.set('Retry-After', String(allowed.retryAfter));
+        return res.fail('rate_limited', 429, { scope: `feedback-${allowed.scope}`, retry_after_seconds: allowed.retryAfter });
+      }
+      const landing = await instanceFeedback.fileInstanceFeedback({
+        client,
+        githubId: String(b.github_id),
+        message: b.message,
+        kind: b.kind || 'bug',
+        context: b.context && typeof b.context === 'object' ? b.context : {},
+      }, {
+        capture: (...a) => api.resolve('ideas.capture')(...a),
+        getAccount: (id) => pi.getAccount(id, { pool }),
+        hubBuilderId: async (id) => {
+          const { rows } = await pool.query('SELECT id FROM builders WHERE github_id = $1 LIMIT 1', [id]);
+          return rows[0] ? rows[0].id : null;
+        },
+      });
+      res.status(201).json({ ok: true, ...landing });
+    } catch (err) {
+      // No building version / no maintenance goal: the hub cannot take a bug right
+      // now. Say so rather than 500, so the CLI can tell the builder to retry later.
+      if (err && (err.code === 'NO_BUILDING_VERSION' || err.code === 'NO_MAINTENANCE_GOAL')) {
+        return res.fail('feedback_unavailable', 503, { reason: err.code });
+      }
+      log.error('[platform-identity] /sso/feedback', err);
+      res.fail('feedback_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };