@bongos/core 1.19.354 → 1.19.356

package/modules/provisioning/routes/provisioning.js

@@ -659,6 +659,17 @@ module.exports = function provisioningRoutes() {
   // Body: any subset of the known keys; strict validation refuses unknown keys
   // and off-vocabulary values. rank: any authenticated builder (own resource;
   // archon may change any — the override is audited via the event's actor).
+  // The platform's row is updated first; then, for an ACTIVE instance on a shape
+  // the runner can reach, a 'settings-apply' intent is enqueued (task 1003140):
+  // the control-plane runner patches the instance's web.env in place and
+  // RESTARTS it, because the branding pack is memoized for the process lifetime.
+  // A save that changes nothing neither writes nor restarts. The response is a
+  // request receipt — `saved` is what the platform now stores, and `push`
+  // { queued, restart, reachable, message } says whether a restart was queued
+  // and when the value takes effect — never a claim the instance already runs
+  // it; a client reads that back from the instance's own public GET /instance
+  // manifest (brand.project). 409 intent_conflict (details.recorded: true) when
+  // the open slot is held by other work — the change IS saved.
   router.patch('/provisioning/instances/:id/settings', auth.requireBuilder, async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
@@ -677,13 +688,70 @@ module.exports = function provisioningRoutes() {
     try {
       const inst = await provisioning.getInstanceById(pool, id);
       if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
-      const updated = await provisioning.updateInstanceSettings(pool, id, patch);
-      await provisioning.recordEvent(pool, {
-        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'settings',
-        detail: `settings changed: ${Object.entries(patch).map(([k, v]) => `${k}=${v}`).join(', ')}`,
-        actor: String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : 'api:archon',
-      }).catch(() => {});
-      res.json({ ok: true, settings: provisioning.effectiveSettings(updated) });
+      // The archon override carries WHICH archon (the force-teardown convention) on
+      // both the event and the intent it may enqueue below.
+      const actor = String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : `api:archon:${req.builder.id}`;
+      // A save that changes nothing writes nothing and restarts nothing — a
+      // whole-form save or a retried request must not bounce a live project. The
+      // one exception is the owner re-kick (the domain route's F19 shape): the same
+      // values re-sent while a retired push left its error_note re-queue the push.
+      const before = provisioning.effectiveSettings(inst);
+      const changed = Object.entries(patch).some(([k, v]) => before[k] !== v);
+      const updated = changed ? await provisioning.updateInstanceSettings(pool, id, patch) : inst;
+      if (changed) {
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'settings',
+          detail: `settings changed: ${Object.entries(patch).map(([k, v]) => `${k}=${v}`).join(', ')}`,
+          actor,
+        }).catch(() => {});
+      }
+      // The push (task 1003140). The row is now the platform's truth, but a
+      // RUNNING instance reads its settings from web.env through a pack memoized
+      // for the process lifetime — so an ACTIVE instance on a reachable shape gets
+      // a 'settings-apply' intent (web.env patched in place + RESTART, drained by
+      // the runner; the web tier holds no tokens, ADR 0111 §2). The owner decided
+      // the restart is acceptable and that the surface must SAY so plainly. Every
+      // other state stores the value and says when it takes effect. One receipt
+      // shape on every branch — `restart` = a restart is what applies it,
+      // `reachable` = the platform can perform that restart — and state-only
+      // sentences throughout (the F16 rule): no wall-clock promises.
+      const reachable = provisioning.SETTINGS_APPLY_SHAPES.has(inst.hosting_shape);
+      const receipt = (fields) => ({ reachable, ...fields });
+      let push;
+      if (!changed && !inst.error_note) {
+        push = receipt({ queued: false, restart: false, message: 'No change — this project already has these settings.' });
+      } else if (!provisioning.SETTINGS_APPLY_FROM.has(inst.status)) {
+        const offline = inst.status === 'torn_down' || inst.status === 'tearing_down';
+        push = receipt({ queued: false, restart: false, message: offline
+          ? 'Saved. This project is offline, so there is nothing to apply it to yet — it takes effect if the project is brought back.'
+          : inst.status === 'error'
+            ? 'Saved. This project’s standup stopped partway, so nothing is applying changes right now — it takes effect the next time the project is stood up.'
+            : 'Saved. It takes effect when the project finishes standing up.' });
+      } else if (!reachable) {
+        // A dedicated droplet has no runner write path — refuse the push honestly
+        // rather than queue one that never lands (the runner refuses it too).
+        push = receipt({ queued: false, restart: true, message:
+          'Saved on the platform. This project runs on a machine the platform doesn’t manage, so it can’t be restarted from here — whoever runs that machine has to apply it there.' });
+      } else {
+        let r = null;
+        try { r = await provisioning.enqueueSettingsApply(pool, id, actor); }
+        catch (err) {
+          // The value IS saved — say so; a 500 here would deny a durable write.
+          log.error('[provisioning] PATCH /provisioning/instances/:id/settings enqueue', err);
+          push = receipt({ queued: false, restart: true, message: 'Saved, but the restart could not be queued just now — send it again to apply it.' });
+        }
+        if (r && r.conflict) {
+          return res.fail('intent_conflict', { status: 409,
+            message: `The change was saved, but a '${r.intent.action}' run is currently ${r.intent.state} for this project — send it again once that settles to apply it.`,
+            details: { action: r.intent.action, state: r.intent.state, recorded: true } });
+        }
+        if (r) {
+          push = receipt({ queued: r.created, restart: true, message: r.created
+            ? 'Saved. Your project will restart to pick this up — until then it keeps its current setting.'
+            : 'Saved. A restart is already queued for this project and will carry this change.' });
+        }
+      }
+      res.json({ ok: true, saved: provisioning.effectiveSettings(updated), push });
     } catch (err) {
       log.error('[provisioning] PATCH /provisioning/instances/:id/settings', err);
       res.fail('settings_update_failed', { status: 500, message: 'internal error' });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.354",
+  "version": "1.19.356",
   "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/public-landing/projects.html

@@ -3407,7 +3407,8 @@ summary{min-height:24px;padding:3px 0;}
     var PROG_FLOWS = {
       standup: { names: ['Request filed', 'Standing it up', 'Live'], cls: '' },
       revive: { names: ['Revive queued', 'Standing it up', 'Back live'], cls: '' },
-      teardown: { names: ['Teardown queued', 'Winding down', 'Torn down'], cls: 'flowDown' }
+      teardown: { names: ['Teardown queued', 'Winding down', 'Torn down'], cls: 'flowDown' },
+      settings: { names: ['Change saved', 'Restarting to apply it', 'Applied'], cls: '' }
     };
     /* No live-region attributes here: this strip is destroyed and rebuilt on
        every 5s tick, and a live region that is itself replaced never announces.
@@ -3459,6 +3460,13 @@ summary{min-height:24px;padding:3px 0;}
           setProgress(progressMarkup(0, 0, 'A teardown is queued — this panel updates when it starts.', '', 'teardown'));
           return false;
         }
+        /* task 1003140: a settings change restarts the project — the panel says so, by state */
+        if (oi.action === 'settings-apply') {
+          setProgress(oi.state === 'running'
+            ? progressMarkup(1, 1, 'Applying a settings change — the project restarts to pick it up.', '', 'settings')
+            : progressMarkup(0, 0, 'A settings change is queued — this panel updates when it starts.', '', 'settings'));
+          return false;
+        }
       }
       if (s === 'requested') {
         setProgress(progressMarkup(0, 0, 'Filed — waiting for the platform to pick it up. This updates the moment it starts.', '', revive ? 'revive' : 'standup'));
@@ -3897,7 +3905,8 @@ summary{min-height:24px;padding:3px 0;}
     standup: { names: ['Request filed', 'Standing it up', 'Live'], cls: '' },
     revive: { names: ['Revive queued', 'Standing it up', 'Back live'], cls: '' },
     teardown: { names: ['Teardown queued', 'Winding down', 'Torn down'], cls: 'flowDown' },
-    address: { names: ['Address queued', 'Wiring the address', 'Answering there'], cls: '' }
+    address: { names: ['Address queued', 'Wiring the address', 'Answering there'], cls: '' },
+    settings: { names: ['Change saved', 'Restarting to apply it', 'Applied'], cls: '' }
   };
   function stripMarkup(flow, stageNow, stagesDone, note) {
     var f = FLOWS[flow];
@@ -3930,6 +3939,10 @@ summary{min-height:24px;padding:3px 0;}
       var a = inst.open_intent.action;
       if (a === 'teardown') return stripMarkup('teardown', 0, 0, 'A teardown is queued — this card updates when it starts.');
       if (a === 'domain-attach') return stripMarkup('address', 1, 1, 'Setting up DNS and the secure connection' + (inst.domain ? ' for <strong>' + esc(inst.domain) + '</strong>' : '') + '.');
+      /* task 1003140: a settings change is pushed by restarting the project — say so, plainly */
+      if (a === 'settings-apply') return inst.open_intent.state === 'running'
+        ? stripMarkup('settings', 1, 1, 'Applying a settings change — the project restarts to pick it up.')
+        : stripMarkup('settings', 0, 0, 'A settings change is queued — this card updates when it starts.');
       if (a === 'provision') return stripMarkup(s === 'torn_down' ? 'revive' : 'standup', 0, 0, (s === 'torn_down' ? 'A revive is queued' : 'A standup is queued') + ' — this card updates when it starts.');
       return stripMarkup('standup', 2, 2, 'A ' + esc(a) + ' run is queued — this card updates when it lands.');
     }

package/scripts/gds/provision-units.js

@@ -237,6 +237,60 @@ function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
   return path.posix.join(etcBase, inst.slug, 'web.env');
 }
 
+// The settings env vars the runner pushes to a RUNNING instance (task 1003140):
+// the module's settingsEnvVars under the prefix the instance actually resolves —
+// the same pair webEnvBody writes at standup, so standup and push cannot drift.
+function settingsEnvVarsFor(inst) {
+  const { settingsEnvVars } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
+  return settingsEnvVars(inst, provisionedEnvPrefix());
+}
+
+// The instance's own public manifest — the settings read-back ADR 0190 names
+// (GET /api/gds/instance → brand.project). Sibling of provision-net's healthzCmd:
+// same loopback + timeout, a different question ("did you READ it?").
+function instanceManifestCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/api/gds/instance`;
+}
+
+// Did the restarted instance CONSUME the pushed settings? Compares each key of
+// effectiveSettings(inst) against the manifest's brand.project (camelCase — the
+// src/branding.js ENV_OVERRIDES targets). true = every key matches; false = it
+// answers with a different value; null = unknown — the manifest carries no
+// project block (a core that predates task 1003139) or did not parse. PURE.
+function settingsConsumed(stdout, inst) {
+  const { effectiveSettings } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
+  let j;
+  try { j = JSON.parse(String(stdout || '').trim()); } catch { return null; }
+  const project = j && j.brand && j.brand.project;
+  if (!project || typeof project !== 'object') return null;
+  const camel = (k) => k.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+  return Object.entries(effectiveSettings(inst)).every(([k, v]) => project[camel(k)] === v);
+}
+
+// Upsert KEY=VALUE lines into an env-file body IN PLACE (task 1003140): an
+// existing `KEY=` line is replaced where it stands, a missing one is appended at
+// the end — every other line (creds, origins, the federation block, comments) is
+// untouched. This is how a setting reaches a RUNNING instance: the full-template
+// re-write webEnvBody produces would BLANK the OAuth creds placeManifestCreds
+// placed (this leg has no way to know them), so a live file is patched, never
+// regenerated. The oauth-secret.js fillOAuthEnv shape. PURE; keys are matched at
+// line start, exactly (a KEY that is a prefix of another never collides).
+function upsertEnvVars(body, vars) {
+  const esc = (k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  let text = String(body == null ? '' : body);
+  const missing = [];
+  for (const [key, value] of Object.entries(vars || {})) {
+    const re = new RegExp(`^${esc(key)}=.*$`, 'm');
+    if (re.test(text)) text = text.replace(re, () => `${key}=${value}`);
+    else missing.push(`${key}=${value}`);
+  }
+  if (missing.length) {
+    if (text.length && !text.endsWith('\n')) text += '\n';
+    text += `${missing.join('\n')}\n`;
+  }
+  return text;
+}
+
 // ── Cross-site identity: federate a hosted instance's sign-in through the hub ───
 // (ADR 0141 §4, task #1002109). The control plane IS the hub (cloudbongos.com), so
 // registration is a direct in-process call against the hub pool — no HTTP hop.
@@ -254,9 +308,13 @@ module.exports = {
   backupTimer,
   backupTimerPath,
   backupUnitName,
+  instanceManifestCmd,
   provisionedEnvPrefix,
   serviceUnit,
   serviceUnitPath,
+  settingsConsumed,
+  settingsEnvVarsFor,
+  upsertEnvVars,
   webEnvBody,
   webEnvPath,
 };

package/scripts/gds/provision.js

@@ -51,11 +51,14 @@ const crypto = require('node:crypto');
 
 const { CONFIG, MANIFEST_UA, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
 const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, dbCreateCmd, dbName, 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, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath } = require('./provision-units.js');
+const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, shouldFederate, zoneForDomain } = require('./provision-net.js');
 
 function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
-  return function run(cmd, { allowFail = false, cwd, env } = {}) {
+  // `shown` (task 1003140): what to LOG in place of the command text — for a command
+  // that carries a secret (a remote file placement embeds the base64 body), so the
+  // journal records "write <path> (N bytes)" and never the payload.
+  return function run(cmd, { allowFail = false, cwd, env, shown: shownAs } = {}) {
     // Extra env is passed to the child (not interpolated into the command), so
     // values like a hostname/IP never need shell quoting. It's shown in the dry-run
     // plan for transparency — DNS env (BOX_HOSTNAME/BOX_IP/CLOUDFLARE_ZONE) is not
@@ -71,28 +74,37 @@ function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = nul
       const wd = cwd || remoteCwd;
       const script = `${wd ? `cd ${wd} && ` : ''}${envPrefix}${cmd}`;
       const sshCmd = `ssh ${sshOpts} ${remoteHost} bash -s`;
-      const shown = `[ssh ${remoteHost}] ${script}`;
+      const shown = `[ssh ${remoteHost}] ${shownAs || script}`;
       if (!apply) { log(`    would run: ${shown}`); return { dryRun: true, ok: true, stdout: '' }; }
       try {
         const stdout = cp.execSync(sshCmd, { input: script, stdio: ['pipe', 'pipe', 'pipe'], env: process.env }).toString();
         log(`    ✓ ${shown}`);
         return { ok: true, stdout };
       } catch (e) {
-        if (allowFail) { log(`    ~ ${shown} (non-fatal: ${(e.stderr || e.message || '').toString().trim().slice(0, 120)})`); return { ok: true, stdout: '', softFailed: true }; }
+        // The script rides STDIN, so e.message names only the ssh hop — but a
+        // `shown` call site is secret-bearing by declaration: log the exit status
+        // alone, never stderr (a remote shell may echo the failing line back).
+        const why = shownAs ? `exit status ${e && e.status != null ? e.status : '?'}` : (e.stderr || e.message || '').toString().trim().slice(0, 120);
+        if (allowFail) { log(`    ~ ${shown} (non-fatal: ${why})`); return { ok: true, stdout: '', softFailed: true }; }
         log(`    ✖ ${shown}`);
         throw e;
       }
     }
     // Local step (control plane / today's behavior). cwd defaults to REPO_ROOT.
-    const shown = `${envPrefix}${cmd}`;
+    const shown = shownAs || `${envPrefix}${cmd}`;
+    const label = shownAs || cmd;
     if (!apply) { log(`    would run: ${shown}`); return { dryRun: true, ok: true, stdout: '' }; }
     try {
       const stdout = cp.execSync(cmd, { cwd: cwd || REPO_ROOT, stdio: ['ignore', 'pipe', 'pipe'], env: env ? { ...process.env, ...env } : process.env }).toString();
-      log(`    ✓ ${cmd}`);
+      log(`    ✓ ${label}`);
       return { ok: true, stdout };
     } catch (e) {
-      if (allowFail) { log(`    ~ ${cmd} (non-fatal: ${(e.stderr || e.message || '').toString().trim().slice(0, 120)})`); return { ok: true, stdout: '', softFailed: true }; }
-      log(`    ✖ ${cmd}`);
+      // With `shown` set the command text is considered secret-bearing, so the
+      // non-fatal line carries only the exit status — never e.message, whose
+      // "Command failed: <cmd>" would echo the command back into the journal.
+      const why = shownAs ? `exit status ${e && e.status != null ? e.status : '?'}` : (e.stderr || e.message || '').toString().trim().slice(0, 120);
+      if (allowFail) { log(`    ~ ${label} (non-fatal: ${why})`); return { ok: true, stdout: '', softFailed: true }; }
+      log(`    ✖ ${label}`);
       throw e;
     }
   };
@@ -121,12 +133,15 @@ function makeWriteFile({ apply, privileged = false, exec, log = console.log, rem
       ];
       if (mode) steps.push(`${sp}chmod ${mode.toString(8)} ${p}`);
       const cmd = steps.join(' && ');
+      // The command text embeds the (base64) body — a web.env carries the OAuth
+      // secret and the App private key — so the exec logs THIS instead (task 1003140).
+      const shown = `write ${p} (${body.length} bytes${mode ? `, mode ${mode.toString(8)}` : ''})`;
       if (!apply) {
         log(`    would write ${p} (${body.length} bytes${mode ? `, mode ${mode.toString(8)}` : ''}) on ${remoteHost}`);
-        if (exec) exec(cmd);
+        if (exec) exec(cmd, { shown });
         return { dryRun: true };
       }
-      exec(cmd);
+      exec(cmd, { shown });
       log(`    ✓ wrote ${p} (on ${remoteHost})`);
       return { ok: true };
     }
@@ -139,7 +154,8 @@ function makeWriteFile({ apply, privileged = false, exec, log = console.log, rem
         if (exec) exec(installCmd);
         return { dryRun: true };
       }
-      fs.writeFileSync(tmp, body);
+      // Owner-only while staged: the destination is 0600 and the body may carry secrets.
+      fs.writeFileSync(tmp, body, { mode: 0o600 });
       try { exec(installCmd); } finally { fs.rmSync(tmp, { force: true }); }
       log(`    ✓ wrote ${p} (via sudo install)`);
       return { ok: true };
@@ -642,6 +658,116 @@ async function domainAttachInstance(inst, deps) {
   return { ok: true };
 }
 
+// ---------------------------------------------------------------------------
+// Push a changed per-project setting to an ALREADY-ACTIVE instance (task
+// 1003140 — the live-push half of the platform→instance settings channel; task
+// 1003139 built the standup half). The branding pack is memoized + deep-frozen
+// for the process lifetime, so a change reaches a running instance only by
+// re-writing its web.env and RESTARTING the service: the domain-attach shape
+// minus the DNS legs. The settings lines are patched IN PLACE (upsertEnvVars) —
+// a template re-write via webEnvBody would blank the OAuth creds that
+// placeManifestCreds placed, which this leg has no way to know. EVERY expected
+// failure — an unreadable file, a refused write, a restart that exits non-zero —
+// RETURNS { ok:false } instead of throwing: the drain loop's catch flips the
+// instance to 'error', which must never happen to a healthy ACTIVE instance over
+// a settings push (ADR 0190).
+// ---------------------------------------------------------------------------
+async function settingsApplyInstance(inst, deps) {
+  const { db, provisioning, exec, writeFile, log, apply, privileged } = deps;
+  // Same box routing as domainAttachInstance: a standalone runs control-plane-local.
+  const standalone = inst.hosting_shape === 'standalone';
+  const boxExec = standalone ? (deps.controlExec || exec) : exec;
+  const boxWriteFile = standalone ? (deps.controlWriteFile || writeFile) : writeFile;
+  const sudoP = privileged ? 'sudo ' : '';
+  const vars = settingsEnvVarsFor(inst);
+  const shown = Object.entries(vars).map(([k, v]) => `${k}=${v}`).join(' ');
+  log(`settings-apply ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status}): ${shown}`);
+
+  // Pre-active states get these values at standup from the same row; post-active
+  // ones have nothing to restart. A clean no-op (not an error) so a raced
+  // teardown never burns the intent's retry budget.
+  if (inst.status !== 'active') {
+    log(`  instance is '${inst.status}' — nothing to push now (standup writes the same values)`);
+    return { ok: true, noop: true };
+  }
+  // A dedicated droplet is stood up by cloud-init and the runner has no post-hoc
+  // exec path to it (the placeManifestCreds refusal) — say so rather than report a
+  // push that never landed. The route refuses to enqueue for this shape too.
+  if (inst.hosting_shape === 'dedicated') {
+    return { ok: false, error: `settings push is not automated for a dedicated droplet — set ${shown} in its ${webEnvPath(inst)} and restart the ${inst.slug} service there` };
+  }
+
+  // Read the file as it stands so ONLY the settings lines change. Dry-run runs no
+  // command, so it has no file to patch — it PLANS the patch instead of writing a
+  // synthetic two-line body (which would read as the exact overwrite this leg
+  // exists to avoid). An unreadable or empty file is refused, never "patched":
+  // writing two lines over a missing PORT/PGDATABASE would take the instance down.
+  const read = boxExec(`${sudoP}cat ${webEnvPath(inst)}`, { allowFail: true });
+  const current = String((read && read.stdout) || '');
+  if (!apply) {
+    log(`  [config] would patch ${Object.keys(vars).join(', ')} in ${webEnvPath(inst)} in place (every other line untouched)`);
+    boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+    boxExec(healthzCmd(inst), { allowFail: true });
+    log(`  ✓ would restart ${inst.slug} with the new settings (dry-run — nothing ran)`);
+    return { ok: true, healthy: null, consumed: null };
+  }
+  if (!read || read.softFailed || !current.trim()) {
+    return { ok: false, error: `cannot read ${webEnvPath(inst)} — nothing to patch (was this instance provisioned by the runner?)` };
+  }
+  try {
+    log('  [config] patch the settings lines of web.env in place (creds + origins untouched)');
+    boxWriteFile(webEnvPath(inst), upsertEnvVars(current, vars), { mode: 0o600, sudo: true });
+    log('  [service] restart so the memoized branding pack re-reads them');
+    boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+  } catch (e) {
+    // ok:false, never a throw: the retry re-reads the file (the upsert is
+    // idempotent) and restarts again; the instance's status is left alone.
+    return { ok: false, error: `could not apply the settings on ${inst.slug}: ${(e && e.message) || e}` };
+  }
+
+  // Verify it came back. PATIENT (the F23 lesson — the manifest probe's budget):
+  // the child must boot before it can answer, and a false "down" here is not
+  // cosmetic — it arms the owner's re-kick paths. Silence after the WHOLE budget
+  // is a verdict on any shape and is recorded immediately (provisionInstance step
+  // 7's rule); a loopback PASS proves the process, not the address — the
+  // domain-scoped sweep earns that claim.
+  log('  [healthz] verify the instance answers after the restart');
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let healthy = false;
+  for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
+    const res = boxExec(healthzCmd(inst), { allowFail: true });
+    if (res && !res.softFailed) { healthy = true; break; }
+    if (i < MANIFEST_VERIFY_TRIES - 1) await sleep(MANIFEST_VERIFY_INTERVAL_MS);
+  }
+  // Answering is not the same as having READ the new values: a core that predates
+  // task 1003139 restarts fine and ignores them. Ask the instance's own manifest
+  // (the read-back ADR 0190 names) and record what it says — never a success it
+  // did not earn. null = the manifest carries no project block (unknown).
+  let consumed = null;
+  if (healthy) {
+    const m = boxExec(instanceManifestCmd(inst), { allowFail: true });
+    consumed = settingsConsumed(m && m.stdout, inst);
+  }
+  const outcome = !healthy ? 'restarted, but not answering /healthz yet'
+    : consumed === true ? 'restarted and reads the new values'
+    : consumed === false ? 'restarted, but still reports the OLD values — its core may predate the settings channel'
+    : 'restarted; its core does not publish its settings yet (pin predates task 1003139), so whether it reads them is unknown';
+  const probeIsVerdict = healthy === false || (healthy === true && !inst.domain);
+  if (probeIsVerdict && provisioning.recordLivenessProbe) await provisioning.recordLivenessProbe(db, inst.id, healthy).catch(() => {});
+  // Release the F19 latch: this run SUCCEEDED, so a "we stopped trying" note
+  // from an earlier retired push must not outlive its own recovery.
+  if (provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id).catch(() => {});
+  await provisioning.recordEvent(db, {
+    instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'settings-applied',
+    detail: `settings pushed (${shown}) — web.env patched in place; ${outcome}`,
+    actor: 'runner',
+  }).catch(() => {});
+  log(healthy && consumed !== false
+    ? `  ✓ ${inst.slug} ${outcome}`
+    : `  ⚠ ${inst.slug} ${outcome}${healthy ? '' : ' — its card will read "unreachable"'}`);
+  return { ok: true, healthy, consumed };
+}
+
 // ---------------------------------------------------------------------------
 // Teardown one instance (reverse the runbook; idempotent).
 // ---------------------------------------------------------------------------
@@ -922,6 +1048,7 @@ async function cmdRunIntents(deps) {
       if (intent.action === 'provision') result = await provisionInstance(inst, deps);
       else if (intent.action === 'teardown') result = await teardownInstance(inst, deps);
       else if (intent.action === 'domain-attach') result = await domainAttachInstance(inst, deps);
+      else if (intent.action === 'settings-apply') result = await settingsApplyInstance(inst, deps);
       else result = { ok: false, error: `unknown intent action '${intent.action}' — refusing to guess` };
       if (result && result.ok === false) {
         if (intent.attempts >= MAX_INTENT_ATTEMPTS) {
@@ -998,7 +1125,8 @@ Usage:
 
 Commands:
   run-intents            drain provisioning_intents (the systemd-timer entry point):
-                         execute each pending provision/teardown intent
+                         execute each pending provision / teardown / domain-attach /
+                         settings-apply intent
   provision <slug>       provision one instance by slug (composes the standup runbook)
   teardown <slug>        tear down one instance by slug
   reconcile              re-enqueue instances stuck mid-flight with no open intent
@@ -1108,6 +1236,8 @@ module.exports = {
   // executors + orchestration (injectable deps for tests)
   makeExec, makeWriteFile, allocatePort, boundLocalPorts, provisionInstance, teardownInstance,
   domainAttachInstance, cmdRunIntents, cmdReconcile, cmdStatus,
+  // live settings push (task 1003140) + the in-place env patch + read-back it rides on
+  settingsApplyInstance, upsertEnvVars, settingsEnvVarsFor, settingsConsumed, instanceManifestCmd,
   // GitHub App Manifest flow (task 2080, ADR 0133)
   convertManifestCode, placeManifestCreds, drainOAuthManifests, MANIFEST_UA,
   // cross-site identity federation (ADR 0141 §4, task #1002109)

package/src/bongos/serve-internal.js

@@ -169,7 +169,8 @@ function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOri
   const tagline = (brand.copy && brand.copy.tagline) || '';
   const cur = (brand.currency && brand.currency.label) || 'credits';
   const Cur = cur ? cur.charAt(0).toUpperCase() + cur.slice(1) : cur;
-  return String(html == null ? '' : html)
+  const hall = hallOrigin || origin || '';
+  return dropEmptyHrefLinks(String(html == null ? '' : html), { publicOrigin: origin || '', buildersOrigin: hall, sourceRepoUrl: sourceRepo || '' })
     .split('{{worldName}}').join(esc(world))
     .split('{{productName}}').join(esc(product))
     .split('{{Currency}}').join(esc(Cur))
@@ -178,10 +179,23 @@ function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOri
     .split('{{publicOrigin}}').join(esc(origin || ''))
     // a pack that names no hall of its own resolves to its OWN apex — never to
     // whichever instance authored the file
-    .split('{{buildersOrigin}}').join(esc(hallOrigin || origin || ''))
+    .split('{{buildersOrigin}}').join(esc(hall))
     .split('{{sourceRepoUrl}}').join(esc(sourceRepo || ''))
     .split('{{instanceBase}}').join(esc(instanceBase || ''));
 }
+// A link whose href is a BARE origin token that resolves empty is dropped whole,
+// server-side (task 1003242; the branding contract): a pack that names no domains
+// would otherwise stamp `href=""` — a dead hall pill on every page carrying one,
+// and only index.html scrubs those client-side. Exact-token hrefs only: a token
+// inside a longer URL still stamps (an empty prefix leaves a relative path).
+function dropEmptyHrefLinks(html, values) {
+  let out = html;
+  for (const [token, value] of Object.entries(values)) {
+    if (value) continue;
+    out = out.replace(new RegExp(`<a\\b[^>]*\\bhref="\\{\\{${token}\\}\\}"[^>]*>[\\s\\S]*?<\\/a>`, 'g'), '');
+  }
+  return out;
+}
 // Every token lands in HTML — as element text, or inside a double-quoted
 // attribute (href/content). Escaping is defence in depth, not a live fix: the
 // only source is config/branding.json, which is committed, code-reviewed and

package/src/branding.js

@@ -204,6 +204,17 @@ function clientBranding(b = branding()) {
     },
     rankLabels: b.rankLabels || {},
     reward: clientReward(),
+    // Per-project policy the platform pushes (tasks 1003139 / 1003140). PUBLIC by
+    // nature — a gated project's gate says "sign in", an invite-only one's door
+    // says so — and the READ-BACK a manage page needs: a settings PATCH on the
+    // platform is only a request until this instance restarts with the value, so
+    // the honest place to learn what it RESOLVED from its environment is its own
+    // GET /instance manifest. Resolved, not enforced: enforcement lands with
+    // tasks 1003043 (visibility) and 1003044 (joinability).
+    project: {
+      platformVisibility: b.project?.platformVisibility || 'public',
+      joinability: b.project?.joinability || 'apply',
+    },
   };
 }
 

package/src/module-api.js

@@ -1138,8 +1138,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.352 with no explicit bump. run 32851392269. (task 1002620)
 //   1.19.354 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.353 with no explicit bump. run 32852045058. (task 1002620)
+//   1.19.355 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.354 with no explicit bump. run 32853063015. (task 1002620)
+//   1.19.356 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.355 with no explicit bump. run 32861072779. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.354'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.356'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/currency_label.mjs

@@ -47,6 +47,14 @@ test('R57: clientBranding exposes theme.ui (web), NOT theme.palette (server-only
   assert.ok(c.theme.colors && c.theme.favicon, 'the WEB theme is what ships');
 });
 
+test('clientBranding exposes project policy — the settings read-back (task 1003140), defaulting to today\'s behavior', () => {
+  assert.deepEqual(clientBranding({}).project, { platformVisibility: 'public', joinability: 'apply' });
+  assert.deepEqual(
+    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only' } }).project,
+    { platformVisibility: 'gated', joinability: 'invite_only' },
+    'what the instance actually resolved (env override included) is what it publishes');
+});
+
 test('clientBranding is a SMALL allow-list — no server-only field leaks to the browser', () => {
   const projected = clientBranding({
     ...OTB_ISH,
@@ -59,7 +67,10 @@ test('clientBranding is a SMALL allow-list — no server-only field leaks to the
   // reward POLICY, so a builder on a cost-plus-only instance isn't shown a per-task
   // estimate that will never pay. The allow-list was not updated with it, so this guard
   // had been failing since that landed (task 1002470).
-  assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'rankLabels', 'reward', 'theme']);
+  // `project` joined the allow-list in task 1003140: the per-project policy is public
+  // by nature and is the settings read-back a manage page needs (see clientBranding).
+  assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'project', 'rankLabels', 'reward', 'theme']);
+  assert.deepEqual(Object.keys(projected.project).sort(), ['joinability', 'platformVisibility']);
   for (const leak of ['domains', 'repo', 'db', 'envPrefix', 'llmProjectName']) {
     assert.equal(projected[leak], undefined, `${leak} must not reach the client`);
   }

package/tests/instance_manifest.mjs

@@ -19,6 +19,8 @@ const BRAND_OTB = {
   theme: { colors: {}, fonts: { display: '', body: '', links: [] }, favicon: '', backdrop: '' },
   copy: { tagline: 'Straight off the boats', hallName: 'Builders’ Hall', notFound: 'Page not found.' },
   rankLabels: { xenos: 'Xenos', thetes: 'Thetes', metic: 'Metic', archon: 'Archon' },
+  // the per-project policy the platform pushes (task 1003140) — the settings read-back
+  project: { platformVisibility: 'gated', joinability: 'invite_only' },
 };
 const BRAND_VANILLA = {
   identity: { productName: 'Cloud Bongos', worldName: 'Cloud Bongos', company: { name: '' } },
@@ -45,6 +47,12 @@ test('manifest: schema id + headline name + embedded brand', () => {
   assert.deepEqual(m.modules, MODULES_OTB);
 });
 
+test('manifest: brand.project rides the manifest — the settings read-back a manage page needs (task 1003140 / ADR 0190)', () => {
+  const m = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  assert.deepEqual(m.brand.project, { platformVisibility: 'gated', joinability: 'invite_only' },
+    'a client reads what the instance RESOLVED from here, never from the platform PATCH response');
+});
+
 test('manifest: rank ladder ordered entry→top, labelled from brand', () => {
   const m = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
   assert.deepEqual(m.ranks.map((r) => r.key), ['xenos', 'thetes', 'metic', 'archon']);

package/tests/landing_page.mjs

@@ -142,6 +142,24 @@ test('an unstamped link is removed, not left dangling', () => {
   assert.ok(out.length > 0);
 });
 
+test('a pack with NO domains drops the hall pill server-side rather than stamping href="" (task 1003242)', () => {
+  // the hub has no client scrubber, so an empty token must never reach it as a dead link
+  const HUB = fs.readFileSync(path.join(ROOT, 'public-landing', 'projects.html'), 'utf8');
+  assert.match(HUB, /data-link-hall href="\{\{buildersOrigin\}\}"/, 'the hub pill is token-stamped');
+  const none = applyBrandTokens(HUB, BRAND, '', '');
+  assert.doesNotMatch(none, /href=""/, 'no empty href survives the stamp');
+  assert.doesNotMatch(none, /data-link-hall/, 'the pill element is omitted whole, not left dead');
+  assert.doesNotMatch(none, /\{\{[a-zA-Z]+\}\}/, 'every other token still stamps');
+  const apexOnly = applyBrandTokens(HUB, BRAND, 'https://spike-harbor.example', '');
+  assert.match(apexOnly, /data-link-hall href="https:\/\/spike-harbor\.example"/, 'an apex alone keeps the pill, pointed at the apex');
+  const both = applyBrandTokens(HUB, BRAND, 'https://spike-harbor.example', 'https://builders.spike-harbor.example');
+  assert.match(both, /data-link-hall href="https:\/\/builders\.spike-harbor\.example"/);
+  // the landing page too — its client-side scrubber is no longer the only guard
+  assert.doesNotMatch(applyBrandTokens(HTML, BRAND, '', ''), /<a\b[^>]*href=""/);
+  // a token INSIDE a longer href is a relative path once stamped empty, not a dead link — left alone
+  assert.equal(applyBrandTokens('<a href="{{publicOrigin}}/docs">Docs</a>', BRAND, '', ''), '<a href="/docs">Docs</a>');
+});
+
 // ── the branding cascade + portability ─────────────────────────────────────
 
 test('the page declares no :root — a page-local one defeats re-branding (C1)', () => {