@bongos/core 1.19.355 → 1.19.357

package/modules/provisioning/provisioning.js

@@ -42,7 +42,11 @@ const PROJECT_TYPES = ['game', 'research', 'business', 'non-profit', 'not-sure']
 // 'domain-attach' (task 1002692, migration provisioning_005): re-assert the
 // domain-dependent standup legs for an already-ACTIVE instance that was just
 // given its address via POST /provisioning/instances/:id/domain.
-const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach'];
+// 'settings-apply' (task 1003140, migration provisioning_010): push a changed
+// per-project setting to an already-ACTIVE instance — patch its web.env settings
+// lines in place + restart, since the branding pack is memoized for the process
+// lifetime (task 1003139 built only the standup leg).
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply'];
 // Every state a teardown can be asked for — i.e. everything except the one
 // state where there is provably nothing left to release. DERIVED from
 // INSTANCE_STATES on purpose (task 1003042, walk finding N5): the old hand-kept
@@ -69,6 +73,17 @@ const PROVISION_ENQUEUE_FROM = new Set(['requested', 'provisioning', 'error', 't
 // 'requested'/'error' only record it — the (re)provision run wires the domain
 // itself. Mid-flight or torn-down states refuse truthfully.
 const DOMAIN_ATTACH_FROM = new Set(['requested', 'error', 'active']);
+// The ONE state a settings push is meaningful from (task 1003140). A pre-active
+// instance needs no push — standup writes the same values from the same
+// effectiveSettings() row — and a torn-down one has nothing to restart. The
+// provision intent cannot stand in for it: PROVISION_ENQUEUE_FROM deliberately
+// excludes 'active' (task 1002691).
+const SETTINGS_APPLY_FROM = new Set(['active']);
+// The hosting shapes the runner has a write path to. A 'dedicated' instance is
+// its own droplet, stood up by cloud-init — the runner has no post-hoc exec path
+// to it (the placeManifestCreds refusal) — so the route refuses the push HONESTLY
+// rather than queue one that never lands.
+const SETTINGS_APPLY_SHAPES = new Set(['co-tenant', 'standalone']);
 
 // Per-project settings (task 1003040, goal 1000058): the known keys + their
 // vocabularies, enforced at the API layer — the jsonb `settings` column
@@ -244,31 +259,39 @@ function publicGithubApp(manifestRow) {
   return { status: String(manifestRow.status), app_slug: manifestRow.app_slug || null };
 }
 
-// The instance's EFFECTIVE settings: the defaults overlaid with the stored,
-// on-vocabulary keys. An off-vocabulary or unknown stored value falls back to
-// its default rather than leaking into the read surface. PURE.
-// The web.env lines that carry this instance's settings, as the runner writes them
-// at standup (task 1003139). PURE (row + prefix in, string out) and owned HERE, next
-// to SETTINGS_VOCAB, rather than in provision.js — the vocabulary and the thing that
+// The env variables that carry this instance's settings, as the instance reads
+// them: { <PREFIX>_PLATFORM_VISIBILITY, <PREFIX>_JOINABILITY } (task 1003139 /
+// 1003140). PURE (row + prefix in, object out) and owned HERE, next to
+// SETTINGS_VOCAB, rather than in provision.js — the vocabulary and the thing that
 // transmits it must not be able to drift. Values come from effectiveSettings, so a
 // row with no stored settings emits today's behavior EXPLICITLY rather than nothing:
-// an instance must never have to infer a policy from an absent variable.
-//
-// This is the standup leg only. Changing a setting on an ALREADY-RUNNING instance
-// needs a push (re-write web.env + restart, since the branding pack is memoized for
-// the process lifetime) — that is the 'settings-apply' intent, still to be built.
-function settingsEnvLines(row, prefix) {
+// an instance must never have to infer a policy from an absent variable. BOTH legs
+// derive from this one function — the standup write (settingsEnvLines → webEnvBody)
+// and the live push (the runner's settings-apply leg patches exactly these lines).
+function settingsEnvVars(row, prefix) {
   const s = effectiveSettings(row);
+  return Object.fromEntries(Object.keys(SETTINGS_VOCAB).map((key) => [`${prefix}_${key.toUpperCase()}`, s[key]]));
+}
+
+// The web.env block the runner writes at STANDUP (task 1003139): a comment that
+// tells the truth about where the values come from, then the settingsEnvVars
+// lines. Changing one on an ALREADY-RUNNING instance is the 'settings-apply'
+// intent (task 1003140): the runner re-writes these lines in place and restarts
+// the service, because the branding pack is memoized for the process lifetime.
+function settingsEnvLines(row, prefix) {
+  const lines = Object.entries(settingsEnvVars(row, prefix)).map(([k, v]) => `${k}=${v}`).join('\n');
   return `# Per-project policy the platform decides and this instance obeys (task
 # 1003139). Written at standup from the platform's provisioning_instances.settings;
-# src/branding.js ENV_OVERRIDES maps these onto project.*. Changing one on a RUNNING
-# instance still needs a push (re-write + restart) — not built yet, so today a change
-# takes effect on the next provision run.
-${prefix}_PLATFORM_VISIBILITY=${s.platform_visibility}
-${prefix}_JOINABILITY=${s.joinability}
+# src/branding.js ENV_OVERRIDES maps these onto project.*. When the owner changes
+# one, the platform's 'settings-apply' run (task 1003140) re-writes these lines in
+# place and restarts this service — the pack is read once per process.
+${lines}
 `;
 }
 
+// The instance's EFFECTIVE settings: the defaults overlaid with the stored,
+// on-vocabulary keys. An off-vocabulary or unknown stored value falls back to
+// its default rather than leaking into the read surface. PURE.
 function effectiveSettings(row) {
   const stored = row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings)
     ? row.settings : {};
@@ -607,7 +630,9 @@ async function enqueueIntent(db, instanceId, action, requestedBy) {
 // blind enqueue collided with such an intent and the API falsely said "teardown
 // already queued" — the instance leaked). A pending provision is flipped to 'error'
 // (the state CHECK has no 'superseded'; last_error says why) so the runner never
-// stands it up. A RUNNING provision is mid-flight infra work and is never yanked —
+// stands it up. A PENDING settings push is superseded the same way (task 1003140):
+// a push into a project about to be torn down is dead work, and letting it hold the
+// delete hostage would repeat 1002691. A RUNNING intent is mid-flight and never yanked —
 // the caller gets { conflict: 'open_intent' } with the blocking intent so the route
 // can answer truthfully. Each statement is atomic and the index stays the arbiter:
 // any interleaving with the runner or a concurrent enqueue lands on one of these
@@ -617,7 +642,7 @@ async function enqueueTeardown(db, instanceId, requestedBy) {
     `UPDATE provisioning_intents
         SET state = 'error', last_error = 'superseded: teardown requested',
             updated_at = now(), resolved_at = now()
-      WHERE instance_id = $1 AND action = 'provision' AND state = 'pending'
+      WHERE instance_id = $1 AND action IN ('provision', 'settings-apply') AND state = 'pending'
       RETURNING id`,
     [instanceId]
   );
@@ -627,6 +652,22 @@ async function enqueueTeardown(db, instanceId, requestedBy) {
   return { intent, created: false, superseded: false, conflict: 'open_intent' };
 }
 
+// Queue a settings push for an ACTIVE instance (task 1003140). The runner reads
+// the row's CURRENT settings when it runs, so a change that lands while an
+// identical intent is still PENDING simply rides that intent — idempotent, and
+// truthfully "already queued". Anything else holding the open slot — other work,
+// or a settings push already RUNNING (which may have read the row before this
+// write) — is reported as { conflict: 'open_intent' } so the route can say so
+// instead of claiming a push that will not carry the change. The state gate and
+// the shape gate are the ROUTE's job (SETTINGS_APPLY_FROM / _SHAPES); this only
+// arbitrates the open slot, like enqueueTeardown.
+async function enqueueSettingsApply(db, instanceId, requestedBy) {
+  const { intent, created } = await enqueueIntent(db, instanceId, 'settings-apply', requestedBy);
+  if (created) return { intent, created: true };
+  if (intent.action === 'settings-apply' && intent.state === 'pending') return { intent, created: false };
+  return { intent, created: false, conflict: 'open_intent' };
+}
+
 // The instance's currently-open (pending|running) intent, if any.
 async function getOpenIntent(db, instanceId) {
   const { rows } = await db.query(
@@ -817,8 +858,9 @@ async function costLedger(db, { limit = 500 } = {}) {
 module.exports = {
   // constants
   INSTANCE_STATES, HOSTING_SHAPES, ONBOARD_MODES, PROJECT_TYPES, INTENT_ACTIONS, TEARDOWN_FROM,
-  settingsEnvLines,
-  PROVISION_ENQUEUE_FROM, DOMAIN_ATTACH_FROM, TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
+  settingsEnvLines, settingsEnvVars,
+  PROVISION_ENQUEUE_FROM, DOMAIN_ATTACH_FROM, SETTINGS_APPLY_FROM, SETTINGS_APPLY_SHAPES,
+  TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
   SETTINGS_VOCAB, DEFAULT_SETTINGS,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
@@ -831,7 +873,7 @@ module.exports = {
   // data access — verification overlay (task 1002696)
   listActiveInstancesForLiveness, recordLivenessProbe, recordDnsNote, clearErrorNote,
   createInstance, setInstanceStatus, updateInstanceDomain, updateInstanceSettings,
-  enqueueIntent, enqueueTeardown, getOpenIntent, claimNextIntent, resolveIntent,
+  enqueueIntent, enqueueTeardown, enqueueSettingsApply, getOpenIntent, claimNextIntent, resolveIntent,
   recordEvent, instanceStateForSlug, costLedger,
   // data access — GitHub App Manifest attempts (task 2080)
   createOAuthManifest, getOAuthManifestByState, attachManifestCode,

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.355",
+  "version": "1.19.357",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.355",
+      "version": "1.19.357",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.355",
+  "version": "1.19.357",
   "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)