@bongos/core 1.21.126 → 1.21.128

package/modules/onboarding/howto-state.js

@@ -0,0 +1,108 @@
+// modules/onboarding/howto-state.js — each person's read/unread state for the how-to steps (task 1004634)
+//
+// WHY. The how-to guide (howto-guide.js, task 1004627) is shown one step at a time
+// at the moment it is useful, and a step once read must never be shown again — on
+// this computer or any other, in Claude or another AI tool. So the read marks live in
+// Bongos, per person (owner decision 2026-10-08), in `onboarding_howto_reads`
+// (migrations/onboarding_001_howto_reads.sql): one row per step read, unread = no row.
+//
+// Three operations, served by routes/onboarding.js under /me/howto:
+//   • readState  — every step with read / skipped / unread, the count, and the next unread
+//   • markRead   — mark steps read (or skipped); `all: true` skips the whole guide
+//   • reset      — forget some steps, or all of them, so they show again
+// Step ids are checked against the guide: an id it does not name is refused, so a
+// typo cannot store a mark nothing will ever read. Marking is idempotent and keeps the
+// FIRST read time (a re-mark does not move it), except that reading a step you had
+// skipped upgrades it to read.
+//
+// Pure of core require(): the pool comes from the doorway, or is injected (tests).
+
+'use strict';
+
+const guide = require('./howto-guide');
+
+const HOWS = Object.freeze(['read', 'skipped']);
+
+function poolFor(deps) {
+  if (deps && deps.pool) return deps.pool;
+  return require('../../src/module-api').pool;
+}
+
+// Validate a list of step ids against the guide. Returns { ok, ids } or { ok:false, unknown }.
+function checkSteps(ids) {
+  const list = [...new Set((Array.isArray(ids) ? ids : [ids]).map((s) => String(s || '').trim()).filter(Boolean))];
+  const unknown = list.filter((id) => !guide.stepById(id));
+  return unknown.length ? { ok: false, unknown } : { ok: true, ids: list };
+}
+
+// Pure: shape stored rows into the API answer, in guide order.
+function shapeState(rows) {
+  const byId = new Map((rows || []).map((r) => [r.step_id, r]));
+  const steps = guide.STEPS.map((s) => {
+    const r = byId.get(s.id);
+    return {
+      id: s.id, moment: s.moment, title: s.title,
+      state: r ? (r.how === 'skipped' ? 'skipped' : 'read') : 'unread',
+      read_at: r ? new Date(r.read_at).toISOString() : null,
+    };
+  });
+  const done = steps.filter((s) => s.state !== 'unread');
+  const next = guide.nextUnread(done.map((s) => s.id));
+  return {
+    steps,
+    total: steps.length,
+    read: steps.filter((s) => s.state === 'read').length,
+    skipped: steps.filter((s) => s.state === 'skipped').length,
+    unread: steps.length - done.length,
+    next_unread: next ? next.id : null,
+  };
+}
+
+async function readState(builderId, deps = {}) {
+  const pool = poolFor(deps);
+  const { rows } = await pool.query(
+    'SELECT step_id, how, read_at FROM onboarding_howto_reads WHERE builder_id = $1',
+    [builderId],
+  );
+  return shapeState(rows);
+}
+
+// { steps: [...] } or { all: true }; how = 'read' | 'skipped'.
+async function markRead(builderId, { steps, all = false, how = 'read' } = {}, deps = {}) {
+  if (!HOWS.includes(how)) return { ok: false, reason: 'bad_how' };
+  let ids;
+  if (all) ids = guide.STEPS.map((s) => s.id);
+  else {
+    const c = checkSteps(steps);
+    if (!c.ok) return { ok: false, reason: 'unknown_step', unknown: c.unknown };
+    if (!c.ids.length) return { ok: false, reason: 'no_steps' };
+    ids = c.ids;
+  }
+  const pool = poolFor(deps);
+  // One statement: first read time is kept; a 'skipped' row becomes 'read' when the
+  // step is read for real, never the other way round.
+  await pool.query(
+    `INSERT INTO onboarding_howto_reads (builder_id, step_id, how)
+     SELECT $1, s, $3 FROM unnest($2::text[]) AS s
+     ON CONFLICT (builder_id, step_id) DO UPDATE
+       SET how = 'read'
+       WHERE onboarding_howto_reads.how = 'skipped' AND EXCLUDED.how = 'read'`,
+    [builderId, ids, how],
+  );
+  return { ok: true, state: await readState(builderId, deps) };
+}
+
+// { steps: [...] } forgets those; no steps (or all: true) forgets every mark.
+async function reset(builderId, { steps, all = false } = {}, deps = {}) {
+  const pool = poolFor(deps);
+  if (all || steps == null || (Array.isArray(steps) && steps.length === 0)) {
+    await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id = $1', [builderId]);
+  } else {
+    const c = checkSteps(steps);
+    if (!c.ok) return { ok: false, reason: 'unknown_step', unknown: c.unknown };
+    await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id = $1 AND step_id = ANY($2::text[])', [builderId, c.ids]);
+  }
+  return { ok: true, state: await readState(builderId, deps) };
+}
+
+module.exports = { HOWS, checkSteps, shapeState, readState, markRead, reset };

package/modules/onboarding/migrations/onboarding_001_howto_reads.sql

@@ -0,0 +1,33 @@
+-- onboarding_001_howto_reads.sql — which how-to steps each person has read (task 1004634).
+--
+-- The in-session how-to guide (modules/onboarding/howto-guide.js, task 1004627) is
+-- walked one step at a time, and a step once read must never be shown again. The
+-- owner's call (2026-10-08): the read state is PER PERSON and lives in Bongos, so it
+-- follows them across computers and AI tools.
+--
+-- One row per (builder, step) that has been read. Unread = no row, so a step added to
+-- the guide later is unread for everyone with no backfill, and a reset is a DELETE.
+-- `step_id` is the guide's stable id; it is not constrained here because the guide is
+-- code — the API refuses an id the guide does not name, and a row for a step the guide
+-- later retires is simply ignored on read. `how` records whether the person read the
+-- step or skipped it (task 1004636's "skip the tutorial"), so progress can tell them
+-- apart.
+--
+-- ADDITIVE, module-owned (ADR 0083 §Decision #5). Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS onboarding_howto_reads (
+  builder_id  bigint      NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  step_id     text        NOT NULL,
+  how         text        NOT NULL DEFAULT 'read',
+  read_at     timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (builder_id, step_id),
+  CONSTRAINT onboarding_howto_reads_how_chk CHECK (how IN ('read', 'skipped')),
+  CONSTRAINT onboarding_howto_reads_step_chk CHECK (step_id ~ '^[a-z][a-z0-9_]{2,39}$')
+);
+
+INSERT INTO schema_migrations (version) VALUES ('onboarding_001_howto_reads')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/modules/onboarding/module.json

@@ -6,7 +6,7 @@
   "coreVersion": "^1.19.532",
   "default": true,
   "maintenance": { "status": "core-maintained" },
-  "contributes": { "routes": ["onboarding"] },
+  "contributes": { "routes": ["onboarding"], "migrations": true },
   "provides": ["onboarding"],
   "consumes": []
 }

package/modules/onboarding/routes/onboarding.js

@@ -37,6 +37,7 @@ const buildAccessRequestsRouter = require('./access-requests');
 const foundingBuilders = require('../founding-builders');
 const genesis = require('../genesis-home');
 const foundingBirth = require('../founding-birth');
+const howtoState = require('../howto-state');
 
 // Register the `onboarding` kernel PORT. See the header + port.js for the full
 // consumer list and the graceful-degradation contract.
@@ -58,15 +59,61 @@ module.exports = function buildOnboardingRouter() {
   // ranks page and the home's founding wall; an empty list on a project that was
   // never founded, so those surfaces render exactly as before. Signed-in, like the
   // hall pages that read it; it carries nothing the roster does not already show.
-  router.get('/founding/builders', api.requireBuilder, async (req, res) => {
+  router.get('/founding/builders', api.requireBuilder, async (_req, res) => {
     const builders = await foundingBuilders.foundingBuildersFor();
     res.set('Cache-Control', 'private, max-age=60');
     res.json({ builders });
   });
   mountGenesisRoutes(router);
+  mountHowtoRoutes(router);
   return router;
 };
 
+// ── the how-to read state (task 1004634) ─────────────────────────────────────
+// Each person's own read/unread marks for the in-session how-to guide. Self-scoped:
+// every route reads and writes only req.builder's rows, so any signed-in builder may
+// call them (the /me/wandering posture). The AI marks a step read after walking the
+// person through it (task 1004635); reopen / continue / skip use the same three calls
+// (task 1004636).
+const HOWTO_REFUSALS = { unknown_step: 422, no_steps: 422, bad_how: 422 };
+
+function mountHowtoRoutes(router) {
+  const handle = (fn) => async (req, res) => {
+    try {
+      const r = await fn(req);
+      if (r && r.ok === false) {
+        return res.status(HOWTO_REFUSALS[r.reason] || 422).json({
+          error: { code: r.reason, message: r.unknown ? `not a how-to step: ${r.unknown.join(', ')}` : r.reason },
+        });
+      }
+      res.set('Cache-Control', 'no-store');
+      res.json(r && r.state ? r.state : r);
+    } catch (err) {
+      api.logger('onboarding').error('[onboarding] howto', err);
+      res.status(500).json({ error: { code: 'howto_failed', message: 'internal error' } });
+    }
+  };
+  // rank: any-builder — the caller's own read state.
+  router.get('/me/howto', api.requireBuilder, handle((req) => howtoState.readState(req.builder.id)));
+  // rank: any-builder — marks the caller's own steps read ({ steps }) or skips the guide ({ all: true, how: 'skipped' }).
+  router.post('/me/howto/read', api.requireBuilder, (req, res, next) => {
+    if (api.validateOrRespond(req, res, {
+      steps: { type: 'array', maxItems: 100 },
+      all: { type: 'boolean' },
+      how: { type: 'string', maxLength: 16 },
+    })) return;
+    next();
+  }, handle((req) => howtoState.markRead(req.builder.id, req.body || {})));
+  // rank: any-builder — forgets the caller's own marks ({ steps }, or everything when none are named).
+  router.post('/me/howto/reset', api.requireBuilder, (req, res, next) => {
+    if (api.validateOrRespond(req, res, {
+      steps: { type: 'array', maxItems: 100 },
+      all: { type: 'boolean' },
+    })) return;
+    next();
+  }, handle((req) => howtoState.reset(req.builder.id, req.body || {})));
+}
+
 // ── the genesis home (task 1004423) ──────────────────────────────────────────
 // Read by any signed-in builder of a founding project (everyone sees where genesis
 // is); every write is the project owner's, behind the same atom that guards the

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.126",
+  "version": "1.21.128",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.126",
+      "version": "1.21.128",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.126",
+  "version": "1.21.128",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9750,5 +9750,21 @@
       "id": "1004738",
       "text": "A goal's page is much shorter now: task dependencies sit in a small card at the top where Conflicts used to be, and the full dependency picture and conflict list are one click away."
     }
+  ],
+  "1.21.127": [
+    {
+      "id": "1004637",
+      "text": "Projects now count each store module's errors per day and send the count to the store, so a module's reliability score comes from real use. It sends with a builder's sign-in on that machine and respects the reporting switch in"
+    },
+    {
+      "id": "1004414",
+      "text": "Each hosted project now has a memory and CPU limit, so one runaway project can no longer slow down every other project or the hub."
+    }
+  ],
+  "1.21.128": [
+    {
+      "id": "1004634",
+      "text": "Bongos now remembers, for each person, which how-to steps they have already seen, so the AI never shows the same tip twice, on any computer."
+    }
   ]
 }

package/scripts/gds/exec-path-guard.js

@@ -103,7 +103,7 @@ const EXEMPTIONS = [
        + 'absorbed into this check.',
   },
   {
-    at: 'src/module-loader/loader.js:347',
+    at: 'src/module-loader/loader.js:350',
     why: 'The poller twin of the route require at :196 — same DEFAULT_ROOTS bound, same plugin-by-'
        + 'design rationale, same ADR 0107 / task 1003400 follow-on. Listed on its own line so a '
        + 'change to either call re-opens only that one.',

package/scripts/gds/fitness.js

@@ -524,6 +524,7 @@ const KERNEL_FILES = [
   'src/module-loader/loader.js',          // the disk loader (discover → validate → mount)
   'src/module-loader/manifest-schema.js', // the manifest validator
   'src/module-loader/semver.js',          // coreVersion compatibility
+  'src/module-loader/error-tally.js',     // per-module runtime-error counts the loader feeds (task 1004637)
   'src/bongos/module-scope-map.js',          // the module→path registry (it NAMES every module — exempt below)
   // trust primitives (ADR 0091 §1) — the authz boundary + data substrate
   'src/bongos/auth.js',                      // authz gates (requireBuilder/requireRank, ADR 0016)

package/scripts/gds/module-error-report.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/module-error-report.js — send this instance's daily runtime-error
+// count for each store module to the store, with the builder sign-in on this box
+// (task 1004637, follow-up to task 1003793; ADR 0343 D1).
+//
+// WHY. The store scores a module's Reliability from daily error counts, and nothing
+// sent one. The server keeps the tally (src/module-loader/error-tally.js writes
+// module-error-counts.json in the instance config dir); this script sends every
+// finished day it has not sent yet — including a 0, because a clean day is what
+// Reliability measures — and remembers which days went in module-error-sent.json.
+//
+// WHO SENDS (owner, 2026-10-15): a builder's sign-in on this box, because the store's
+// report routes take a builder and no project-to-store credential exists (that option
+// is parked as task 1004740). No sign-in here means nothing is sent, quietly.
+//
+// PRIVACY (owner, 2026-10-01): counts only, on by default, with an opt-out. If the
+// signed-in builder switched reporting off in Settings, nothing is sent and the days
+// are marked done; the store also drops a report from an opted-out holder, so the
+// rule holds whichever client sends.
+//
+// The server runs this every few hours (error-tally.js startDailySend); it is safe to
+// run by hand too:
+//   node scripts/gds/module-error-report.js [--dry-run] [--quiet]
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readTally, utcDay, FILE_NAME } = require('../../src/module-loader/error-tally');
+
+const SENT_FILE = 'module-error-sent.json';
+// The store takes days up to 30 back (module-usage-reports.js ERROR_DAY_WINDOW).
+const WINDOW_DAYS = 30;
+const ENTRY_RE = /^([a-z0-9][a-z0-9-]*)@(\d+\.\d+\.\d+)$/;
+
+function daysAgo(today, n) { return utcDay(Date.parse(`${today}T00:00:00Z`) - n * 86_400_000); }
+
+// The finished days still to send, oldest first. Pure.
+function pendingDays(days, sent, today) {
+  const oldest = daysAgo(today, WINDOW_DAYS);
+  return Object.keys(days || {}).filter((d) => d < today && d >= oldest && !(sent && sent[d])).sort();
+}
+
+// Send what is pending. `call(method, path, { json })` is the store client (module.js
+// storeRequest). Never throws for a store answer: a day is marked done only when
+// every count in it got a final answer — recorded, or refused for good (4xx: the store
+// does not have that version, or this builder does not hold the module). A 5xx or an
+// unreachable store leaves the day for the next run. Returns a summary.
+async function sendPending({ days, sent = {}, today, call, dryRun = false }) {
+  const out = { pending: pendingDays(days, sent, today), sentDays: [], posted: 0, skipped: 0, optedOut: false, retryLater: false };
+  if (!out.pending.length) return out;
+
+  const pref = await call('GET', '/store/usage-reporting');
+  if (!pref.ok) { out.retryLater = true; return out; }
+  if (pref.data && pref.data.enabled === false) {
+    out.optedOut = true;
+    if (!dryRun) out.sentDays = out.pending.slice();
+    return out;
+  }
+
+  const entries = new Set();
+  for (const d of out.pending) for (const e of Object.keys(days[d] || {})) if (ENTRY_RE.test(e)) entries.add(e);
+  const keys = [...new Set([...entries].map((e) => e.match(ENTRY_RE)[1]))];
+  let known = new Set();
+  if (keys.length) {
+    const res = await call('GET', `/store/modules/latest?keys=${keys.map(encodeURIComponent).join(',')}`);
+    if (!res.ok) { out.retryLater = true; return out; }
+    known = new Set(Object.keys((res.data && res.data.latest) || {}));
+  }
+
+  for (const day of out.pending) {
+    let done = true;
+    for (const [e, count] of Object.entries(days[day] || {})) {
+      const m = e.match(ENTRY_RE);
+      if (!m || !known.has(m[1]) || !Number.isInteger(count) || count < 0) { out.skipped += 1; continue; }
+      if (dryRun) { out.posted += 1; continue; }
+      let res;
+      try {
+        res = await call('POST', `/store/modules/${encodeURIComponent(m[1])}/versions/${encodeURIComponent(m[2])}/error-count`, { json: { day, count } });
+      } catch { res = { ok: false, status: 0 }; }
+      if (res.ok) out.posted += 1;
+      else if (res.status >= 400 && res.status < 500) out.skipped += 1;
+      else done = false;
+    }
+    if (done && !dryRun) out.sentDays.push(day);
+    else if (!done) out.retryLater = true;
+  }
+  return out;
+}
+
+function readSent(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && parsed.sent && typeof parsed.sent === 'object' ? parsed.sent : {};
+  } catch { return {}; }
+}
+
+// Record the days sent, dropping any older than the store's window.
+function writeSent(file, sent, newDays, today) {
+  const oldest = daysAgo(today, WINDOW_DAYS + 1);
+  const next = {};
+  for (const d of [...Object.keys(sent), ...newDays]) if (d >= oldest) next[d] = true;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ sent: next }, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+async function main(argv = process.argv.slice(2), {
+  log = console.log, request, tallyFile, sentFile, today = utcDay(),
+} = {}) {
+  const quiet = argv.includes('--quiet');
+  const dryRun = argv.includes('--dry-run');
+  const say = (m) => { if (!quiet) log(m); };
+  const { configPath } = require('../../src/instance-config');
+  const tFile = tallyFile || configPath(FILE_NAME);
+  const sFile = sentFile || configPath(SENT_FILE);
+
+  const days = readTally(tFile);
+  const sent = readSent(sFile);
+  if (!pendingDays(days, sent, today).length) { say('module error counts: nothing to send.'); return 0; }
+
+  let call = request;
+  if (!call) {
+    try { call = require('./module').storeRequest(); }
+    catch { say('module error counts: no Bongos sign-in on this machine, so nothing was sent.'); return 0; }
+  }
+
+  let out;
+  try { out = await sendPending({ days, sent, today, call, dryRun }); }
+  catch (e) { say(`module error counts: the store could not be reached (${e.message}); will try again later.`); return 1; }
+  if (out.sentDays.length) writeSent(sFile, sent, out.sentDays, today);
+
+  if (out.optedOut) say('module error counts: reporting is switched off in your Settings, so nothing was sent.');
+  else say(`module error counts: ${dryRun ? 'would send' : 'sent'} ${out.posted} count(s) for ${out.pending.length} day(s); ${out.skipped} skipped (not a store module you hold)${out.retryLater ? '; some will be retried later' : ''}.`);
+  return out.retryLater ? 1 : 0;
+}
+
+module.exports = { pendingDays, sendPending, main };
+
+if (require.main === module) {
+  // Set the exit code and drain, never a hard exit after a request (task 1002734).
+  Promise.resolve(main()).then(
+    (code) => { process.exitCode = code; },
+    (e) => { console.error(e && e.message ? e.message : e); process.exitCode = 1; },
+  );
+}

package/scripts/gds/module.js

@@ -1350,6 +1350,7 @@ async function main(argv) {
 
 module.exports = {
   main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
+  storeRequest,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, gatherUpdates, evaluateUpdates, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,

package/scripts/gds/provision-caps.js

@@ -0,0 +1,63 @@
+// scripts/gds/provision-caps.js — the resource caps every hosted project's service carries
+// (task 1004414). A cloud-host project runs its owner's code on the box that also serves the
+// hub, and ADR 0354 lets any signed-in builder host one, so a runaway project must not be
+// able to starve the others or the hub.
+//
+// The numbers are the owner's (2026-10-15), sized from ADR 0285's measurement: a project
+// idles at ~45-70 MB and peaks at 118-134 MB at boot (page cache included), and uses a
+// fraction of a percent of one core. MemoryHigh throttles and reclaims before MemoryMax
+// kills; a killed project comes back through the unit's Restart=always. Too tight a cap
+// takes a healthy project down, so change these only as a decision.
+//
+// A NEW unit renders them (serviceUnit). An EXISTING unit takes them with `systemctl
+// set-property`, which applies live and persists a drop-in under /etc/systemd/system.control/,
+// so nothing restarts and no unit file is rewritten — rewriting would move a project made
+// before the per-instance accounts (task 1003369) onto an account that does not exist.
+// systemd only: the supervisord image has no cgroups to cap.
+
+'use strict';
+
+const RESOURCE_CAPS = Object.freeze({
+  MemoryHigh: '160M',
+  MemoryMax: '256M',
+  CPUQuota: '50%',
+  TasksMax: '256',
+});
+
+function capDirectives() {
+  return Object.entries(RESOURCE_CAPS).map(([key, value]) => `${key}=${value}`);
+}
+
+// The slug is interpolated into a root shell command, so it is held to the create route's
+// charset here too rather than trusted from the row.
+const SAFE_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+function setCapsCmd(inst, { sudoP = '' } = {}) {
+  if (!SAFE_SLUG.test(String(inst.slug))) throw new Error(`refusing to cap an unsafe slug: ${JSON.stringify(inst.slug)}`);
+  return `${sudoP}systemctl set-property ${inst.slug}.service ${capDirectives().join(' ')}`;
+}
+
+// `provision.js apply-caps [--apply]` — cap every running hosted project now. A cloud-host
+// always runs on the control plane (capacity.placementBox), so this uses controlExec. One
+// project that refuses never stops the rest; the result names it.
+async function cmdApplyCaps(deps) {
+  const { db, log, privileged } = deps;
+  const exec = deps.controlExec || deps.exec;
+  const sudoP = privileged ? 'sudo ' : '';
+  const { rows } = await db.query(
+    `SELECT slug FROM provisioning_instances
+      WHERE hosting_shape = 'cloud-host' AND status = 'active'
+      ORDER BY slug`);
+  const capped = [], failed = [];
+  for (const { slug } of rows) {
+    // makeExec answers an allowFail'd failure ok:true + softFailed:true (softFailResult)
+    let r;
+    try { r = exec(setCapsCmd({ slug }, { sudoP }), { allowFail: true }); } catch { r = null; }
+    (!r || r.ok === false || r.softFailed ? failed : capped).push(slug);
+  }
+  log(`${deps.apply ? 'capped' : 'would cap (dry-run — add --apply)'} ${capped.length} of ${rows.length} active hosted project(s) at ${capDirectives().join(' ')}`);
+  if (failed.length) log(`  ✖ could not cap: ${failed.join(', ')} — re-run once each unit is loaded`);
+  return { ok: failed.length === 0, capped, failed };
+}
+
+module.exports = { RESOURCE_CAPS, capDirectives, setCapsCmd, cmdApplyCaps };

package/scripts/gds/provision-process.js

@@ -59,6 +59,9 @@ const systemd = {
     exec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
     exec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
     exec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
+    // the caps drop-in `provision.js apply-caps` wrote (task 1004414, provision-caps.js)
+    exec(`${sudoP}rm -f /etc/systemd/system.control/${inst.slug}.service.d/50-*.conf`, { allowFail: true });
+    exec(`${sudoP}rmdir /etc/systemd/system.control/${inst.slug}.service.d`, { allowFail: true });
     exec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
     exec(`${sudoP}systemctl reset-failed ${inst.slug}.service ${backupUnitName(inst)}.service`, { allowFail: true });
   },

package/scripts/gds/provision-units.js

@@ -12,6 +12,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { CONFIG, REPO_ROOT } = require('./provision-config.js');
 const { CORE_PKG_DIR, appUser, dbName, instanceDbRole, instanceStateDir, instanceUser, parseTargetRef, standaloneRoot } = require('./provision-repo.js');
+const { capDirectives } = require('./provision-caps.js');
 
 function serviceUnit(inst, { etcBase = CONFIG.etcBase } = {}) {
   const envFile = path.posix.join(etcBase, inst.slug, 'web.env');
@@ -61,6 +62,8 @@ ProtectSystem=strict
 ProtectHome=read-only
 PrivateTmp=true
 ReadWritePaths=${stateDir} -${workDir}/config
+# Resource caps (task 1004414; the numbers and their reasons are in provision-caps.js).
+${capDirectives().join('\n')}
 
 [Install]
 WantedBy=multi-user.target

package/scripts/gds/provision.js

@@ -1348,6 +1348,7 @@ Commands:
   teardown <slug>        tear down one instance by slug
   reconcile              re-enqueue instances stuck mid-flight with no open intent
   status                 list provisioned instances + estimated run-rate
+  apply-caps             cap every active hosted project's memory/CPU/tasks live (task 1004414)
   dns-check <domain>     PREFLIGHT: verify the control-plane Cloudflare token can reach
                          the domain's zone BEFORE the address step (network-only, no DB)
 
@@ -1397,7 +1398,7 @@ async function main() {
     process.exit(1);
   }
 
-  const known = ['run-intents', 'provision', 'teardown', 'reconcile', 'status'];
+  const known = ['run-intents', 'provision', 'teardown', 'reconcile', 'status', 'apply-caps'];
   if (!known.includes(cmd)) { console.error(`unknown command: ${cmd}\n`); usage(); process.exit(2); }
   const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
   if ((cmd === 'provision' || cmd === 'teardown') && !slug) { console.error(`${cmd} needs a <slug>`); process.exit(2); }
@@ -1432,6 +1433,7 @@ async function main() {
     else if (cmd === 'teardown') { const inst = await provisioning.getInstanceBySlug(pool, slug); if (!inst) { console.error(`no instance with slug '${slug}'`); await pool.end().catch(() => {}); process.exit(1); } result = await teardownInstance(inst, deps); }
     else if (cmd === 'reconcile') result = await cmdReconcile(deps);
     else if (cmd === 'status') result = await cmdStatus(deps);
+    else if (cmd === 'apply-caps') result = await require('./provision-caps.js').cmdApplyCaps(deps);
   } catch (e) {
     console.error('fatal:', e && e.message ? e.message : e);
     await pool.end().catch(() => {});

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.126'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.128'; // 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');