@bongos/core 1.19.763 → 1.19.765

package/modules/provisioning/capacity.js

@@ -0,0 +1,162 @@
+// modules/provisioning/capacity.js — how many projects a shared box can hold, and
+// whether one more fits (ADR 0285, task 1003927).
+//
+// ADR 0285 measured the live control plane and priced a project at its WARM size:
+// ~80 MB (a 70 MB process plus one busy Postgres backend), on top of a fixed base
+// the box pays whatever the project count (~750 MB with the control plane on it,
+// ~630 MB on an overflow box). The ceiling is `floor((usable MiB − fixed) / 80)`,
+// which reproduces the ADR's table from the box's own MemTotal — 15 on today's
+// s-1vcpu-2gb, 39 on an s-2vcpu-4gb control plane, 41 on a 4 GB overflow box — so
+// a resize (task 1003923) raises the ceiling by itself, with no knob to remember.
+//
+// Two walls, asked in order, both honest refusals rather than a silent overcommit:
+//   1. the CEILING, counted against the rows the runner has placed or is placing
+//      on that box (`provisioning` + `active`). Not `error`: those rows hold no
+//      running unit (verified on the live fleet, 2026-09-16), and a re-provision
+//      runs this same check for itself.
+//   2. a live MemAvailable FLOOR, because the ledger cannot see a stray unit or a
+//      project that grew — the rows say how many, the kernel says how much is left.
+//
+// PURE except the two I/O helpers at the bottom (`countPlaced` runs one query on
+// the db it is handed; `readLocalMeminfo` reads this host's /proc/meminfo, for the
+// web tier and the CLI, which run ON the control plane). The runner reads the same
+// file through its box executor instead, so an overflow box is measured where the
+// project will actually run (scripts/gds/provision-capacity.js). No module-api, no
+// express, no pool of its own — this file is the shared arithmetic, not a surface.
+'use strict';
+
+const fs = require('node:fs');
+
+// ADR 0285 §1–§2. PROJECT_MB is the warm unit; FIXED_MB is the box's own overhead
+// by role; DEFAULT_CEILING is the ADR's smallest-tier number, used ONLY when the box
+// cannot be measured (dry-run, a fake executor, an unreadable /proc) — refusing
+// conservatively beats guessing generously. RESIZE_AT is the ADR's "resize at 12 of
+// 15" trigger. The floor is two warm projects plus margin, per the task's brief.
+const PROJECT_MB = 80;
+const FIXED_MB = Object.freeze({ 'control-plane': 750, overflow: 630 });
+const DEFAULT_CEILING = 15;
+const DEFAULT_MEM_FLOOR_MB = 256;
+const RESIZE_AT = 0.8;
+// The states that hold (or are about to hold) a slot on the box.
+const PLACED_STATES = Object.freeze(['provisioning', 'active']);
+
+function numEnv(name, dflt) {
+  const v = process.env[name];
+  if (v == null || v === '') return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+// The two knobs, read at call time so a test can set them per case. Both live in
+// the runner's box.env; the web tier's copy (web.env) must match if the override
+// is used — deriving from MemTotal is what makes the two agree with no knob at all.
+function envOverrides() {
+  return { override: numEnv('PROVISION_BOX_CEILING', null), floorMb: numEnv('PROVISION_MEM_FLOOR_MB', DEFAULT_MEM_FLOOR_MB) };
+}
+
+// parseMeminfo — MemTotal / MemAvailable out of /proc/meminfo text, in MiB.
+// Null for a field that is absent, so "unmeasured" stays distinguishable from 0.
+function parseMeminfo(text) {
+  const grab = (key) => {
+    const m = new RegExp(`^${key}:\\s+(\\d+)\\s*kB`, 'm').exec(String(text || ''));
+    return m ? Math.floor(Number(m[1]) / 1024) : null;
+  };
+  return { memTotalMb: grab('MemTotal'), memAvailableMb: grab('MemAvailable') };
+}
+
+// placementBox — WHICH box a shape lands on, and therefore which rows share its
+// ceiling and which fixed base applies. A standalone always runs control-plane-
+// local (task 2074); a co-tenant runs on the remote co-hosting box only when the
+// runner is in remote-exec mode (ADR 0130), else here. A dedicated droplet is its
+// own box and has no shared ceiling → null (no preflight).
+function placementBox(hostingShape, { remoteHost = null } = {}) {
+  if (hostingShape === 'dedicated') return null;
+  if (hostingShape === 'co-tenant' && remoteHost) {
+    return { box: 'overflow', shapes: ['co-tenant'], fixedMb: FIXED_MB.overflow };
+  }
+  return { box: 'control-plane', shapes: remoteHost ? ['standalone'] : ['standalone', 'co-tenant'], fixedMb: FIXED_MB['control-plane'] };
+}
+
+// ceilingFor — the slot count for a box: an explicit override wins, else the ADR
+// 0285 formula over the measured MemTotal, else the conservative default. `source`
+// says which, so every surface can show where its number came from.
+function ceilingFor({ override = null, memTotalMb = null, fixedMb = FIXED_MB['control-plane'] } = {}) {
+  if (Number.isFinite(override) && override > 0) return { ceiling: Math.floor(override), source: 'env' };
+  if (Number.isFinite(memTotalMb) && memTotalMb > fixedMb) {
+    return { ceiling: Math.floor((memTotalMb - fixedMb) / PROJECT_MB), source: 'measured' };
+  }
+  return { ceiling: DEFAULT_CEILING, source: 'default' };
+}
+
+// placementVerdict — may ONE more project be placed? Ceiling first (the ledger's
+// answer), then the live floor (the kernel's). The reason is written for the
+// owner's card, not the journal: what is full, that nothing was placed, and the
+// two ways out. An unmeasured MemAvailable cannot fail the floor — the ceiling is
+// the wall that always applies, and a missing reading is logged by the caller.
+function placementVerdict({ placed, ceiling, memAvailableMb = null, floorMb = DEFAULT_MEM_FLOOR_MB }) {
+  if (placed >= ceiling) {
+    return { ok: false, wall: 'ceiling', reason: `The shared box is full: ${placed} of ${ceiling} project slots are taken (ADR 0285). Nothing was placed. Free a slot by tearing down a project, or resize the box (task 1003923), then request again.` };
+  }
+  if (Number.isFinite(memAvailableMb) && memAvailableMb < floorMb) {
+    return { ok: false, wall: 'memory', reason: `The shared box has only ${memAvailableMb} MB of memory free, under the ${floorMb} MB a new project needs to start safely (${placed} of ${ceiling} slots taken). Nothing was placed. Free memory or a slot, or resize the box (task 1003923), then request again.` };
+  }
+  return { ok: true, wall: null, reason: null };
+}
+
+// capacitySummary — the one shape every reader gets: the fleet API, the runner
+// log, the CLI status. `resize_due` is the ADR's 80% trigger, so the resize is
+// scheduled at 12 of 15 rather than discovered at 15.
+function capacitySummary({ box, placed, ceiling, source, memAvailableMb = null, floorMb = DEFAULT_MEM_FLOOR_MB }) {
+  const verdict = placementVerdict({ placed, ceiling, memAvailableMb, floorMb });
+  return {
+    box, placed, ceiling, source,
+    remaining: Math.max(0, ceiling - placed),
+    resize_at: Math.ceil(ceiling * RESIZE_AT),
+    resize_due: placed >= Math.ceil(ceiling * RESIZE_AT),
+    mem_available_mb: memAvailableMb,
+    mem_floor_mb: floorMb,
+    verdict,
+  };
+}
+
+// countPlaced — rows holding a slot on the box: the given shapes in PLACED_STATES.
+// `excludeId` keeps a row from counting itself when a reconcile re-runs its own
+// provision (it is already 'provisioning' then). Fail-soft on a fake db that
+// answers with no rows.
+async function countPlaced(db, shapes, { excludeId = null } = {}) {
+  const params = [shapes, PLACED_STATES];
+  let where = 'hosting_shape = ANY($1) AND status = ANY($2)';
+  if (excludeId != null) { params.push(excludeId); where += ` AND id <> $${params.length}`; }
+  const { rows } = await db.query(`SELECT count(*)::int AS n FROM provisioning_instances WHERE ${where}`, params);
+  return Number((rows && rows[0] && rows[0].n) || 0);
+}
+
+// readLocalMeminfo — THIS host's /proc/meminfo, for the surfaces that run on the
+// control plane itself. Null (not a throw) where it does not exist, e.g. a dev box
+// that is not Linux — the summary then reads 'default' and says so.
+function readLocalMeminfo() {
+  try { return fs.readFileSync('/proc/meminfo', 'utf8'); } catch { return null; }
+}
+
+// fleetCapacity — the control-plane box's summary for the fleet API and the CLI:
+// its rows against its ceiling, measured from this host. `meminfo` is injectable
+// for tests; `remoteHost` mirrors the runner's PROVISION_REMOTE_HOST so the two
+// count the same shapes (set it in web.env too if co-tenants ever run remotely).
+async function fleetCapacity(db, { meminfo = readLocalMeminfo(), remoteHost = process.env.PROVISION_REMOTE_HOST || null } = {}) {
+  const target = placementBox('standalone', { remoteHost });
+  const { override, floorMb } = envOverrides();
+  const mem = parseMeminfo(meminfo);
+  const { ceiling, source } = ceilingFor({ override, memTotalMb: mem.memTotalMb, fixedMb: target.fixedMb });
+  const placed = await countPlaced(db, target.shapes);
+  return capacitySummary({ box: target.box, placed, ceiling, source, memAvailableMb: mem.memAvailableMb, floorMb });
+}
+
+// The constants a caller needs to reason about a verdict, plus the helpers the
+// runner preflight and the fleet API compose. PROJECT_MB / FIXED_MB / RESIZE_AT
+// and the two env readers stay private: nothing outside asks them separately from
+// the summary they produce, and an export nobody consumes is one more thing to
+// keep true (the paid-shape-gate precedent).
+module.exports = {
+  DEFAULT_CEILING, DEFAULT_MEM_FLOOR_MB, PLACED_STATES,
+  parseMeminfo, placementBox, ceilingFor, placementVerdict, capacitySummary,
+  countPlaced, fleetCapacity,
+};

package/modules/provisioning/routes/provisioning.js

@@ -25,7 +25,7 @@
 //     POST   /provisioning/instances/:id/teardown  — request teardown of one's own
 //     GET    /provisioning/instances/:id/invite-suggestions — who is worth inviting (R28, ADR 0251)
 //   Archon-scoped (requireRank('archon') — the fleet, the /boxes precedent):
-//     GET    /provisioning/fleet                    — the full instance roster
+//     GET    /provisioning/fleet                    — the full instance roster + the box's slot `capacity` (ADR 0285)
 //     GET    /provisioning/fleet/cost-ledger        — per-instance + total cost estimate
 //     POST   /provisioning/instances/:id/force-teardown — tear down ANY instance
 //   public:
@@ -44,8 +44,7 @@
 const crypto = require('node:crypto');
 const express = require('express');
 const api = require('../../../src/module-api');
-const auth = api;
-const { pool, validateOrRespond, parseId } = api;
+const auth = api, { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const { onboardPlan, stepsForShape } = require('../onboard-plan');
 const { ALWAYS_ON_CORE, OPTIONAL_MODULES, starterBundleAnswerTable, optionalModules, effectiveModules } = require('../starter-bundles');
@@ -54,6 +53,7 @@ const { makeAskRateLimiter, clientIp } = require('../rate-limit');
 const { requireAuthorityForMeteredShape } = require('../paid-shape-gate');
 const { adoptCredentialFault } = require('../credential-preflight');
 const catalogBridge = require('../catalog-bridge');
+const capacity = require('../capacity');   // the box's slot ceiling (ADR 0285, task 1003927)
 const { callbackPage } = require('./callback-page');
 // the LOUD body validators (task 1003504) — lifted out when this file hit the size ratchet
 const { badProjectDetail, badModuleSelection, badProjectType } = require('./body-validators');
@@ -223,7 +223,7 @@ module.exports = function provisioningRoutes() {
     try {
       const status = req.query.status || undefined;
       const rows = await provisioning.listAllInstances(pool, { status });
-      res.json({ instances: rows.map(fleetInstance) });
+      res.json({ instances: rows.map(fleetInstance), capacity: await capacity.fleetCapacity(pool).catch(() => null) });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/fleet', err);
       res.fail('fleet_failed', { status: 500, message: 'internal error' });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.763",
+  "version": "1.19.765",
   "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/scripts/gds/provision-capacity.js

@@ -0,0 +1,74 @@
+// scripts/gds/provision-capacity.js — the runner's BOX-CAPACITY preflight
+// (ADR 0285, task 1003927): before a standalone / co-tenant project is placed on a
+// shared box, ask whether it fits, and refuse with an owner-readable reason when it
+// does not. Nothing enforced the ceiling before this — the runner stood up project
+// N+1 on a full box and swap hid the overcommit until a reboot or a fleet upgrade
+// woke every project at once.
+//
+// The arithmetic and the two walls (row ceiling, live MemAvailable floor) live in
+// modules/provisioning/capacity.js, shared with the fleet API so both surfaces show
+// one number. This file is the runner-side composition: it reads /proc/meminfo
+// through the BOX executor — the control plane for a standalone (task 2074), the
+// remote co-hosting box for a co-tenant under remote-exec (ADR 0130) — so an
+// overflow box is measured where the project will actually run. A sibling of
+// provision-config / -repo / -units / -net; provision.js requires it back.
+'use strict';
+
+const { CONFIG } = require('./provision-config.js');
+const capacity = require('../../modules/provisioning/capacity.js');
+
+// The kernel's own two lines, kept small so the journal stays readable. allowFail:
+// a box without procfs (never, on Linux) reads as "unmeasured", and the ceiling
+// then falls to ADR 0285's conservative default rather than aborting the standup.
+const MEMINFO_CMD = "grep -E '^Mem(Total|Available):' /proc/meminfo";
+
+// capacityPreflight — { ok:true, …summary } when the project fits (or the shape has
+// no shared box), { ok:false, error, …summary } when it does not. The refusal is a
+// RETURN, never a throw: the drain loop retries it (a teardown may free a slot), and
+// on retirement writes `error` onto the instance's card without flipping its status
+// — so a project that was never placed is never labelled broken. Dry-run measures
+// and reports but refuses nothing, since it places nothing either way.
+async function capacityPreflight(inst, deps) {
+  const { db, provisioning, exec, log, apply } = deps;
+  const target = capacity.placementBox(inst.hosting_shape, { remoteHost: CONFIG.remoteHost });
+  if (!target) return { ok: true, skipped: 'dedicated' };
+  const boxExec = target.box === 'control-plane' ? (deps.controlExec || exec) : exec;
+  let res = null;
+  try { res = boxExec(MEMINFO_CMD, { allowFail: true }); } catch { res = null; }
+  const mem = capacity.parseMeminfo(res && res.stdout);
+  const { ceiling, source } = capacity.ceilingFor({ override: CONFIG.boxCeiling, memTotalMb: mem.memTotalMb, fixedMb: target.fixedMb });
+  const placed = await capacity.countPlaced(db, target.shapes, { excludeId: inst.id });
+  const floorMb = CONFIG.memFloorMb || capacity.DEFAULT_MEM_FLOOR_MB;
+  const summary = capacity.capacitySummary({ box: target.box, placed, ceiling, source, memAvailableMb: mem.memAvailableMb, floorMb });
+  const free = mem.memAvailableMb != null ? `${mem.memAvailableMb} MB free` : 'memory unmeasured';
+  const where = `${target.box} box at ${placed} of ${ceiling} slots (${source}, ${free})`;
+  if (!apply) {
+    log(`  [preflight] ${where} — would refuse if full (dry-run measures nothing and places nothing)`);
+    return { ok: true, dryRun: true, ...summary };
+  }
+  if (source === 'default') log(`  [preflight] ⚠ could not measure the box — using ADR 0285's smallest-tier ceiling (${ceiling}); set PROVISION_BOX_CEILING to override`);
+  if (!summary.verdict.ok) {
+    log(`  ✖ [preflight] ${where} — refusing to place ${inst.slug} (${summary.verdict.wall} wall)`);
+    if (provisioning && provisioning.recordEvent) {
+      await provisioning.recordEvent(db, {
+        instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'placement-refused',
+        detail: summary.verdict.reason, actor: 'runner',
+      }).catch(() => {});
+    }
+    return { ok: false, error: summary.verdict.reason, ...summary };
+  }
+  log(`  [preflight] ${where} ✓${summary.resize_due ? ' — at or past 80%: schedule the resize (task 1003923) or open the next box' : ''}`);
+  return { ok: true, ...summary };
+}
+
+// statusCapacityLine — the "box at N of M" line `provision.js status` prints, read
+// from this host (the CLI runs on the control plane), so the resize is scheduled
+// at 80% rather than discovered at the ceiling.
+async function statusCapacityLine(db) {
+  const c = await capacity.fleetCapacity(db);
+  const free = c.mem_available_mb != null ? `, ${c.mem_available_mb} MB free` : '';
+  const due = c.resize_due ? ' — at or past 80%: resize or open the next box (ADR 0285, task 1003923)' : '';
+  return `  ${c.box} box: ${c.placed} of ${c.ceiling} project slots taken (${c.source}${free})${due}`;
+}
+
+module.exports = { MEMINFO_CMD, capacityPreflight, statusCapacityLine };

package/scripts/gds/provision-config.js

@@ -123,6 +123,17 @@ const CONFIG = {
   // fails fast (never hangs on a prompt); accept-new pins the host key on first
   // connect (the operator can pre-seed known_hosts for strict pinning).
   sshOpts: process.env.PROVISION_SSH_OPTS || '-o BatchMode=yes -o StrictHostKeyChecking=accept-new',
+  // ── Box capacity (ADR 0285, task 1003927) ─────────────────────────────────
+  // How many projects the box the runner places on may hold. UNSET (default)
+  // derives it from that box's own MemTotal by the ADR's formula (15 on today's
+  // s-1vcpu-2gb, 39 after the resize), so a resize raises it with no knob to
+  // remember; set it only to pin a number the measurement should not decide (a box
+  // that also hosts something the ledger cannot see). The floor is the live
+  // MemAvailable a placement must still find — two warm projects plus margin
+  // (modules/provisioning/capacity.js holds the default). Both live in box.env;
+  // mirror an override into web.env so the fleet API reports the same number.
+  boxCeiling: numEnv('PROVISION_BOX_CEILING', null),
+  memFloorMb: numEnv('PROVISION_MEM_FLOOR_MB', null),
 };
 
 // task 1002757 — the provisioner's git identity resolves from the instance's own

package/scripts/gds/provision.js

@@ -53,6 +53,7 @@ const { CONFIG, MANIFEST_UA, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES,
 const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, shouldFederate, zoneForDomain } = require('./provision-net.js');
+const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
 
 function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
   // `shown` (task 1003140): what to LOG in place of the command text — for a command
@@ -258,7 +259,8 @@ async function provisionInstance(inst, deps) {
       log(`  [preflight] would verify the Cloudflare token can reach zone ${zoneForDomain(inst.domain)} before the address step`);
     }
   }
-
+  const room = await capacityPreflight(inst, deps);   // box capacity (ADR 0285, task 1003927): an honest refusal BEFORE the status flip — never a silent oversubscribe
+  if (room.ok === false) return room;
   if (apply) await provisioning.setInstanceStatus(db, inst.id, 'provisioning');
   const patch = {};
 
@@ -1358,7 +1360,7 @@ async function cmdStatus(deps) {
     monthly += Number(r.cost_estimate_usd || 0);
     log(`  ${String(r.slug).padEnd(20)} ${String(r.status).padEnd(13)} ${r.hosting_shape.padEnd(10)} port=${r.port || '-'} @${r.github_login} $${Number(r.cost_estimate_usd || 0).toFixed(2)}/mo  ${r.domain || ''}`);
   }
-  log(`\n  estimated run-rate: ~$${monthly.toFixed(2)}/mo`);
+  log(`\n  estimated run-rate: ~$${monthly.toFixed(2)}/mo\n${await statusCapacityLine(db)}`);   // + "box at N of M" (ADR 0285, task 1003927)
   return { count: rows.length };
 }
 

package/scripts/hall-preview/live-identity.js

@@ -29,6 +29,7 @@ const ME_SCOPED_PATHS = [
   'me/profile-nudge',
   'me/render',
   'me/wandering',
+  'me/interaction',
   'me/skill-prefs',
   'me/sound-prefs',
   'me/event-sound-prefs',

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.763'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.765'; // 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('dev-box'); log.info('mounted');

package/tests/conductor.mjs

@@ -130,6 +130,42 @@ test('wandering: lowest priority — emitted after methodology/status advisories
   assert.equal(a[a.length - 1].id, 'wandering', 'wandering is emitted last');
 });
 
+// ---------- evaluateTriggers: interaction profile (task 2010, delivered 1002514) ----------
+//
+// This branch shipped with task 2010 and had NO coverage here, which is part of
+// why the profile could be believed to have no consumer at all. It relays only —
+// interaction-prefs.js resolves — so these pin the relay, plus the one end-to-end
+// fact clause 1 of `accessibility-fluency-profile` turns on.
+
+test('interaction: a profile with inject:true emits the pitch contract', () => {
+  const a = conductor.evaluateTriggers({
+    interaction: { inject: true, contract: 'Interaction profile for this builder — pitch replies accordingly:' },
+  });
+  const i = a.find((x) => x.id === 'interaction');
+  assert.ok(i, 'expected an interaction advisory');
+  assert.match(i.text, /pitch replies accordingly/);
+});
+
+test('interaction: inject:false, an empty contract, or a null knob emit nothing', () => {
+  assert.ok(!ids(conductor.evaluateTriggers({ interaction: { inject: false, contract: 'x' } })).includes('interaction'));
+  assert.ok(!ids(conductor.evaluateTriggers({ interaction: { inject: true, contract: '' } })).includes('interaction'));
+  assert.ok(!ids(conductor.evaluateTriggers({ interaction: null })).includes('interaction'));
+  assert.ok(!ids(conductor.evaluateTriggers({})).includes('interaction'));
+});
+
+// The clause-1 proof, run against the REAL resolver rather than a hand-written
+// payload: the accessible DEFAULT profile — the one a builder who never opens
+// Settings has — must reach a session. Before task 1002514 every default field
+// carried an empty fragment, so describeForApi({}) came back inject:false and
+// this advisory was never emitted for the builder it was written for.
+test('interaction: the DEFAULT profile reaches a session end to end', () => {
+  const interactionPrefs = require('../modules/builder-settings/interaction-prefs.js');
+  const a = conductor.evaluateTriggers({ interaction: interactionPrefs.describeForApi({}) });
+  const i = a.find((x) => x.id === 'interaction');
+  assert.ok(i, 'a builder on all defaults must still be described to the session');
+  assert.match(i.text, /non-technical/);
+});
+
 // The nudge says "your claim's", singular, so it is measured against the claim
 // bound to THIS worktree (task 1003837). These three carry a worktree_name and a
 // matching `worktree` for that reason; the four below pin what changed.

package/tests/hall_settings_world.mjs

@@ -160,6 +160,55 @@ test('the wandering pick is a radio row, wired on change', () => {
   assert.match(radio, /height:\s*24px/, 'a native radio is 13px; the floor is 24');
 });
 
+// ---- the interaction panel (task 1002514) ----------------------------------
+//
+// Three facts a browser is silent about: the panel is rendered by a script that
+// is not settings.js, so the wiring between the two halves is the thing that can
+// silently break; and the carve exists because settings.js is against the
+// 1500-line ratchet, which is a fact a reader will otherwise undo.
+
+test('the interaction panel is wired end to end across its two files', () => {
+  const html = read('settings.html');
+  const panelJs = read('settings-interaction.js');
+
+  // The markup half lives in settings.html and must join a group that already
+  // exists — the rail renders groups, so a section in an unknown data-group is
+  // markup nothing ever shows.
+  const section = html.match(/<section class="scroll" id="interaction-scroll"[^>]*>/);
+  assert.ok(section, 'the panel has a section');
+  assert.match(section[0], /data-group="preferences"/, 'it joins a group the rail already renders');
+  assert.match(section[0], /\bhidden\b/, 'hidden until its own read succeeds, like every other panel');
+  assert.match(html, /<script src="\/builders\/settings-interaction\.js/, 'the page loads the panel script');
+
+  // The script half self-boots and reveals the section. If it stopped doing
+  // either, the panel would simply never appear and no test would notice.
+  assert.match(panelJs, /\$\('#interaction-scroll'\)\.hidden = false/, 'the script reveals its own section');
+  assert.match(panelJs, /setup\(\);/, 'it self-boots — settings.js does not call it');
+
+  // settings.js keeps ONLY the anchor entry, so /settings#interaction activates
+  // the group before the panel paints.
+  assert.match(settingsJs, /'interaction': 'interaction-scroll'/, 'the deep-link anchor stays in settings.js');
+  assert.doesNotMatch(settingsJs, /function renderInteraction\(/, 'the renderer moved out and must not come back inline');
+});
+
+test('the interaction panel stays out of settings.js, which is against the size ratchet', () => {
+  // Not style: inlining this panel put settings.js at 1601 lines and regressed
+  // oversized_file_count 0→1 and excess_lines_total 0→102 (fitness-ratchets.js,
+  // OVERSIZE_LINES = 1500). The settings-sessions.js precedent, same reason.
+  const lines = settingsJs.split('\n').length;
+  assert.ok(lines < 1500, `settings.js is ${lines} lines — at or over the 1500 ratchet; carve the next panel out too`);
+});
+
+test('a default value is named once, by the API, not twice by the row', () => {
+  // The first render read "Non-technical (default) · DEFAULT": interaction-prefs.js
+  // already ends every default value's LABEL with "(default)", and the row also
+  // carried the wandering picker's .prow__tag. One source for the word.
+  const panelJs = read('settings-interaction.js');
+  const render = panelJs.match(/function render\([\s\S]*?\n  \}\n/);
+  assert.ok(render, 'render is a whole function');
+  assert.doesNotMatch(render[0], /prow__tag/, 'the row must not re-state "default" beside a label that already says it');
+});
+
 test('.craft-pref is a 24px target with a 14px drawn box — it was 13x13, the smallest control in the hall', () => {
   const box = ruleOf(panelCss, '.craft-pref');
   assert.ok(box, '.craft-pref has a rule');

package/tests/interaction_prefs.mjs

@@ -6,19 +6,47 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const ip = require('../modules/builder-settings/interaction-prefs.js');
 
-test('defaults: unset prefs → all field defaults, empty contract, no inject', () => {
+test('defaults: unset prefs → all field defaults', () => {
   const eff = ip.effectiveProfile({});
   assert.equal(eff.technical_level, 'non_technical');
   assert.equal(eff.toolchain_familiarity, 'new');
   assert.equal(eff.verbosity, 'concise');
-  assert.equal(ip.contractFor({}), '', 'all-default profile injects nothing');
-  assert.equal(ip.shouldInject({}), false);
 });
 
-test('null / missing behaviorPrefs is safe', () => {
+// task 1002514, clause 1 of `accessibility-fluency-profile`. This REPLACES an
+// assertion that the all-default profile injected nothing. That was correct while
+// CLAUDE.md §2 carried the posture as prose, and it meant the accessible-by-
+// default builder — the one who most needs the posture and least likely to open
+// Settings — was the only builder the profile said nothing about.
+test('the DEFAULT profile injects the accessible posture (it is a posture, not an absence)', () => {
+  const c = ip.contractFor({});
+  assert.notEqual(c, '', 'the accessible default must not be the silent one');
+  assert.equal(ip.shouldInject({}), true);
+  assert.match(c, /non-technical/, 'the vocabulary posture must arrive');
+  assert.match(c, /define a term the first time/);
+  assert.match(c, /cost, time and what the end user will see/, 'the framing posture must arrive');
+  assert.match(c, /step by step/, 'the toolchain posture must arrive');
+  assert.match(c, /concise/, 'the length posture must arrive');
+});
+
+test('null / missing behaviorPrefs is safe, and still resolves to the default posture', () => {
   assert.deepEqual(ip.storedProfile(null), {});
-  assert.equal(ip.contractFor(null), '');
-  assert.equal(ip.shouldInject(undefined), false);
+  assert.equal(ip.contractFor(null), ip.contractFor({}), 'absent prefs resolve exactly like empty prefs');
+  assert.equal(ip.shouldInject(undefined), true);
+});
+
+// The criterion's hard constraint: "an expert's terse experience is never
+// degraded to help a newcomer." The expert contract must not merely differ from
+// the newcomer one — it must be SHORTER, and it must tell the agent to skip.
+test('an expert profile stays terse where a non-technical one is explained to', () => {
+  const beginner = ip.contractFor({});
+  const expert = ip.contractFor({
+    interaction: { technical_level: 'engineer', toolchain_familiarity: 'comfortable' },
+  });
+  assert.ok(expert.length < beginner.length, 'the expert contract must be shorter, not just different');
+  assert.match(expert, /skip basic explanations/);
+  assert.doesNotMatch(expert, /do not assume software-engineering vocabulary/);
+  assert.doesNotMatch(expert, /walk local tooling/);
 });
 
 test('a non-default field produces an injected contract', () => {
@@ -76,10 +104,21 @@ test('describeForApi exposes catalog + effective + contract + inject', () => {
 // The SURFACE half of the profile: how much of the work behind a reply gets
 // narrated. Default `show` keeps every existing builder on today's behavior.
 
-test('machinery defaults to show and injects nothing', () => {
+// The assertion here used to be `contractFor({machinery:'show'}) === ''`, which
+// measured the WHOLE contract's emptiness to prove one field contributed nothing.
+// That conflated "this field is silent" with "every field is silent", so once the
+// other defaults gained text (task 1002514) it would have gone red for a reason
+// that had nothing to do with machinery. Same intent, pointed at the actual claim:
+// adding `show` changes nothing, and `show` never names itself.
+test('machinery defaults to show and contributes nothing to the contract', () => {
   assert.equal(ip.defaultValue('machinery'), 'show');
   assert.equal(ip.effectiveProfile({}).machinery, 'show');
-  assert.equal(ip.contractFor({ interaction: { machinery: 'show' } }), '', 'the default must never spend session context');
+  assert.equal(
+    ip.contractFor({ interaction: { machinery: 'show' } }),
+    ip.contractFor({}),
+    'an explicit `show` must read identically to leaving it unset',
+  );
+  assert.doesNotMatch(ip.contractFor({}), /Machinery/, 'the default must never spend session context');
 });
 
 test('machinery=quiet injects an outcomes-not-mechanism contract', () => {