@bongos/core 1.20.35 → 1.20.37

package/modules/hall-ui/public/deploy.js

@@ -130,6 +130,178 @@
     return v ? `<span class="ov-mono">${escapeHtml(String(v))}</span>` : '<span class="ps-pill ps-pill--absent">no reading</span>';
   }
 
+  // ---- why a move stopped, in words (task 1004450) ---------------------------
+  //
+  // The runner classifies every failed move (scripts/gds/upgrade-outcome.js) into one of
+  // four kinds, each with a fixed reason code. The page used to show only the runner's raw
+  // output, addressed to someone holding a shell. These are the same reasons in the
+  // owner's words. A code with no entry falls back to a plain "no words for this" rather
+  // than a guess — the raw output is still one click away.
+  const REASON_WORDS = {
+    registry_unreadable: 'the list of published versions could not be read',
+    not_published: 'that version is not published yet',
+    npm_install: 'installing the new core stopped part-way',
+    dirty_tree: 'the project had unsaved file changes on its machine',
+    disk_full: 'the machine ran out of disk space',
+    schema_pending: 'the project’s database was behind its code',
+    outside_channel: 'that version is outside this project’s update rule',
+    shape_not_automated: 'this kind of project is not moved from this page',
+    downgrade: 'that version is older than the one running',
+    artist_gate: 'an artist review has to pass first',
+    module_incompatible: 'a module this project uses is not ready for that core',
+    remedy_did_not_hold: 'the automatic fix was tried once and the same problem came back',
+    remedy_failed: 'the automatic fix itself did not work',
+    health: 'the project did not answer after restarting on the new core',
+    migrate: 'updating the project’s database failed',
+    restart: 'the project would not restart',
+    rollback_failed: 'the new core failed, and putting the old one back failed too',
+    no_target: 'the move did not say which version to go to',
+    bad_slug: 'the project’s name on the machine could not be used',
+    installed_unreadable: 'the version installed on the machine could not be read',
+    served_mismatch: 'the project was not serving the version its machine had installed',
+    already_on: 'the project is already on that version',
+    db_unresolvable: 'the machine could not tell which database belongs to this project',
+    db_identity: 'the project’s database did not match the one the move expected',
+    health_url_missing: 'there was no address to check the project was answering after the move',
+    core_source: 'the new core could not be found to install',
+    integrity_pin: 'the new core did not match the checksum it was published with',
+  };
+  const reasonWords = (f) => (f && REASON_WORDS[f.reason]) || 'the upgrade stopped for a reason this page has no words for yet';
+  // What the runner's one automatic fix (scripts/gds/wedge-remedy.js) did for a known snag.
+  const REMEDY_WORDS = {
+    dirty_tree: 'saved those changes',
+    disk_full: 'cleared out old backups',
+    schema_pending: 'brought the database up to date',
+  };
+
+  // A pending move whose next try is in the FUTURE is waiting out a retry, not moving. The
+  // runner re-queues a failed move as pending with a not_before (task 1004447), so "pending"
+  // alone cannot tell the two apart — and treating a six-hour wait as a move in flight is
+  // how the page used to poll for five minutes and then say "still working".
+  function waitingOf(i) {
+    return !!(i && i.state === 'pending' && i.not_before && new Date(i.not_before).getTime() > Date.now());
+  }
+
+  // "14:05, in about 40 min" — when a waiting move tries again, as a clock time the owner
+  // can hold the page to, and the distance to it.
+  function whenNext(iso) {
+    const t = new Date(iso);
+    const mins = Math.max(1, Math.round((t.getTime() - Date.now()) / 60000));
+    const dist = mins < 90 ? `${mins} min` : `${Math.round(mins / 60)}h`;
+    let clock = '';
+    try { clock = t.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }); } catch (e) { clock = ''; }
+    return clock ? `${clock}, in about ${dist}` : `in about ${dist}`;
+  }
+
+  // A move waiting to try again. The press it offers is the SAME move, sooner: the route
+  // brings a waiting move's retry forward rather than refusing it (enqueueCoreUpgrade).
+  function waitingHtml(p) {
+    const i = p.open_intent;
+    const f = i.failure;
+    const at = escapeHtml(whenNext(i.not_before));
+    const to = escapeHtml(String(i.target_version || ''));
+    let body;
+    if (f && f.class === 'known_wedge') {
+      const did = REMEDY_WORDS[f.reason];
+      body = `<strong>A known snag stopped the move to core ${to}:</strong> ${escapeHtml(reasonWords(f))}.
+        ${did ? `It ${escapeHtml(did)} on its own, and` : 'It'} tries the move once more at ${at}.`;
+    } else if (f && f.class === 'transient') {
+      body = `<strong>Waiting to try core ${to} again at ${at}.</strong> The last try stopped because
+        ${escapeHtml(reasonWords(f))} — that is usually temporary, so it tries again on its own.`;
+    } else {
+      body = `<strong>Waiting to try core ${to} again at ${at}.</strong>`;
+    }
+    return `
+      <div class="dp-settled dp-settled--waiting">
+        <p class="ov-row__sub">${body} Nothing needs doing — this page shows the result when it lands.</p>
+        <div class="ps-controls">
+          <button type="button" class="btn" id="dp-retry-${escapeHtml(String(p.instance_id))}">Try now</button>
+        </div>
+      </div>`;
+  }
+
+  // A move that stopped for good, worded by what KIND of stop it was. Each kind says what
+  // happens next, because that is the question the owner is left with: is anything still
+  // being done about this, and is any of it mine to do?
+  const BLOCKERS_LINK = '<a href="/blockers">the owner’s blockers</a>';
+  function failureHtml(p, m, when, detail) {
+    const f = m.failure;
+    const cls = f && f.class;
+    const id = escapeHtml(String(p.instance_id));
+    const to = escapeHtml(String(m.target_version));
+    const still = `This project is still running core ${escapeHtml(String(p.served_version))}.`;
+    const card = (mod, head, rest, action = '') => `
+        <div class="dp-settled dp-settled--${mod}">
+          <p class="ov-row__sub"><strong>${head}</strong>${rest}</p>
+          ${action}
+          ${detail}
+        </div>`;
+    // A row from before the runner classified failures: the old wording, unchanged.
+    if (!cls) return card('failed', `The move to core ${to} did not land`, ` — attempted${when}. ${still}`);
+    const why = escapeHtml(reasonWords(f));
+    if (f.reason === 'rollback_failed') {
+      return card('failed', `The move to core ${to} failed, and the old core could not be put back`,
+        ` — attempted${when}. This project may be down. A person needs to look; it has been filed in ${BLOCKERS_LINK}.`);
+    }
+    if (cls === 'needs_decision') {
+      let action = '';
+      if (f.reason === 'outside_channel' && p.update_channel !== 'minor') {
+        action = `<div class="ps-controls">
+            <button type="button" class="btn btn--primary" id="dp-allow-${id}">Allow new releases and move to ${to}</button>
+          </div>`;
+      }
+      const next = {
+        outside_channel: action ? ' Allowing new releases changes this project’s update rule, then makes the move.' : ' Change the update rule below, then move again.',
+        artist_gate: ' Approve the artist review, or change the artist gate in this project’s settings, then move again.',
+        downgrade: ' Nothing to do unless you meant to go back to an older core.',
+        module_incompatible: ' Turn that module off in this project’s settings and move again, or wait for a core it works with — the technical detail below names the module.',
+        shape_not_automated: ' Whoever runs this project’s machine moves its core there.',
+      }[f.reason] || '';
+      return card('decision', `Your call: the move to core ${to} is waiting on a decision`,
+        ` — ${why}. Attempted${when}. ${still}${next}`, action);
+    }
+    if (cls === 'transient') {
+      const retry = String(m.target_version) === String(p.recommended_version)
+        ? `<div class="ps-controls"><button type="button" class="btn" id="dp-again-${id}">Try again</button></div>` : '';
+      return card('failed', `The move to core ${to} kept stopping`,
+        ` — ${why}. That is usually temporary, so it tried again on its own over several hours, then gave up${when}. ${still}`, retry);
+    }
+    // NO blockers link here, deliberately: move-escalation.js files one only for an unknown
+    // failure or a failed rollback, so pointing at the list would send the owner to look for
+    // a row that does not exist. The step is named instead.
+    if (cls === 'known_wedge') {
+      return card('failed', `The move to core ${to} hit a known snag it could not fix here`,
+        ` — ${why}. Attempted${when}. ${still} The automatic fix could not be applied on this project’s
+          machine, so whoever runs that machine clears the snag; the technical detail below says what it is.
+          After that, the move can be pressed again.`);
+    }
+    return card('failed', `The move to core ${to} did not land, and nothing automatic can fix it`,
+      ` — ${why}. Attempted${when}. ${still} It has been filed in ${BLOCKERS_LINK} for a person to look at.`);
+  }
+
+  // The project's update rule (task 1004445): how far the runner may move its core. A
+  // RULE, never a move — saving one queues nothing and restarts nothing.
+  const RULES = [
+    ['pinned', 'Stay put', 'no new versions are offered; this project stays on the core it runs'],
+    ['patch', 'Fixes only', 'takes fixes within the release line it is on'],
+    ['minor', 'Fixes and new releases', 'also takes the next release line when one comes out'],
+  ];
+  function ruleHtml(p) {
+    const cur = RULES.find((r) => r[0] === p.update_channel);
+    if (!cur) return '';
+    const id = escapeHtml(String(p.instance_id));
+    const opts = RULES.map(([k, label]) => `<option value="${k}"${k === cur[0] ? ' selected' : ''}>${escapeHtml(label)}</option>`).join('');
+    return `
+      <div class="dp-rule">
+        <p class="ov-row__sub"><strong>Update rule: ${escapeHtml(cur[1])}</strong> — ${escapeHtml(cur[2])}.</p>
+        <div class="ps-controls">
+          <label class="dp-rule__label" for="dp-rule-sel-${id}">Change to</label>
+          <select id="dp-rule-sel-${id}" class="dp-rule__select">${opts}</select>
+          <button type="button" class="btn" id="dp-rule-save-${id}">Save rule</button>
+        </div>
+      </div>`;
+  }
+
   // ---- the states ONE box can be in ----------------------------------------
 
   // Something is already running. The press is not offered at all — offering a button
@@ -141,6 +313,7 @@
   // reload, and neither is being watched — so it says what is true instead.
   function busyHtml(p) {
     const i = p.open_intent;
+    if (waitingOf(i)) return waitingHtml(p);
     return `
       <p class="ov-row__sub">A <strong>${escapeHtml(i.action)}</strong> is ${escapeHtml(i.state)} for this box${
         i.target_version ? ` (to core ${escapeHtml(i.target_version)})` : ''}.
@@ -186,7 +359,7 @@
     // verbatim and kept CLOSED: the owner cannot run `sudo -u`, so 30 lines of it (the
     // dirty-tree refusal prints a whole `git status`) is not what a deploy page leads on.
     const detail = m.error
-      ? `<details class="dp-settled__detail"><summary>What the upgrade said</summary>
+      ? `<details class="dp-settled__detail"><summary>Technical detail — what the upgrade said</summary>
           <pre class="dp-preflight__error">${escapeHtml(String(m.error))}</pre></details>`
       : '';
     if (m.state === 'error' && m.superseded) {
@@ -199,14 +372,7 @@
           ${detail}
         </div>`;
     }
-    if (m.state === 'error') {
-      return `
-        <div class="dp-settled dp-settled--failed">
-          <p class="ov-row__sub"><strong>The move to core ${escapeHtml(String(m.target_version))} did not land</strong>
-            — attempted${when}. This project is still running core ${escapeHtml(String(p.served_version))}.</p>
-          ${detail}
-        </div>`;
-    }
+    if (m.state === 'error') return failureHtml(p, m, when, detail);
     // LANDED, BUT GITHUB DID NOT GET IT (task 1004065). The runner pushes a hosted
     // project's new pin to its repo after the move; when it could not, the move is still
     // done — the site runs the new core — and `warning` says why the repo was not updated.
@@ -439,6 +605,7 @@
           : ''}
         ${schemaBehindHtml(p)}
         ${action}
+        ${ruleHtml(p)}
       </div></li>`;
   }
 
@@ -463,6 +630,54 @@
     if (cancel) cancel.addEventListener('click', () => { steps.set(p.instance_id, 'preview'); repaint(); });
     const confirm = $(`dp-confirm-${id}`);
     if (confirm) confirm.addEventListener('click', () => move(p));
+    // Task 1004450: the waiting move, sooner; a stopped temporary one, again; the one-click
+    // answer to an update-rule refusal; and the rule itself.
+    const retry = $(`dp-retry-${id}`);
+    if (retry && p.open_intent) retry.addEventListener('click', () => move(p, p.open_intent.target_version));
+    const again = $(`dp-again-${id}`);
+    if (again && p.last_move) again.addEventListener('click', () => move(p, p.last_move.target_version));
+    const allow = $(`dp-allow-${id}`);
+    if (allow && p.last_move) allow.addEventListener('click', () => allowAndMove(p, p.last_move.target_version, allow));
+    const save = $(`dp-rule-save-${id}`);
+    if (save) save.addEventListener('click', () => saveRule(p, save));
+  }
+
+  // Change the rule, then report the server's own sentence and re-read the row.
+  async function setRule(p, channel) {
+    const r = await sendJson('POST', `/provisioning/instances/${p.instance_id}/update-channel`, { channel });
+    toast(r.message || 'Update rule saved.');
+    return r;
+  }
+
+  async function saveRule(p, btn) {
+    const sel = $(`dp-rule-sel-${p.instance_id}`);
+    const channel = sel && sel.value;
+    if (!channel) return;
+    btn.disabled = true;
+    try {
+      await setRule(p, channel);
+    } catch (e) {
+      if (e && e.kind === '401') return;
+      toast(e.message || 'Could not change the update rule.');
+      btn.disabled = false;
+      return;
+    }
+    await refreshOne(p);
+  }
+
+  // "Allow new releases and move": the rule first, and only if it took, the move — a move
+  // queued under the old rule would be refused the same way again.
+  async function allowAndMove(p, to, btn) {
+    if (btn) { btn.disabled = true; btn.textContent = 'Changing the rule…'; }
+    try {
+      await setRule(p, 'minor');
+    } catch (e) {
+      if (e && e.kind === '401') return;
+      toast(e.message || 'Could not change the update rule.');
+      if (btn) { btn.disabled = false; btn.textContent = `Allow new releases and move to ${to}`; }
+      return;
+    }
+    await move(p, to);
   }
 
   // What the page is currently showing: the ONE box this hall is about, whether that box
@@ -491,11 +706,12 @@
     if (view.box) wire(view.box);
   }
 
-  async function move(p) {
+  // `to` defaults to the version the owner was SHOWN; the retry buttons pass the move they
+  // are retrying, which is also a version on screen.
+  async function move(p, to = p.recommended_version) {
     const btn = $(`dp-confirm-${p.instance_id}`);
     if (btn) { btn.disabled = true; btn.textContent = 'Queueing…'; }
     const id = String(p.instance_id);
-    const to = p.recommended_version;
     try {
       // `p.recommended_version` — the version this owner was SHOWN for THIS box, not
       // whatever is newest at the moment of the click.
@@ -532,6 +748,10 @@
       // that "done" would drop the row out of its in-flight state early.
       if (!now.open_intent && now.served_version === to) { settled = true; break; }
       if (!now.open_intent && now.last_move && now.last_move.state === 'error') { settled = true; break; }
+      // WAITING IS SETTLED TOO (task 1004450). A pending move whose next try is minutes or
+      // hours away is not in flight; the row says when it tries again, and watching it for
+      // five minutes would end in a "still working" toast about a move that is not running.
+      if (waitingOf(now.open_intent)) { settled = true; break; }
     }
     moving.delete(p.instance_id);
     repaint();

package/modules/hall-ui/public/project-settings.css

@@ -186,3 +186,31 @@
   padding: 0.35rem 0;
   min-height: 24px;
 }
+
+/* Why a move stopped, by kind (task 1004450). WAITING is the accent, like a move in
+   flight — something is still being done, on its own clock. A DECISION is the warn mark:
+   nothing is broken, and the next step is the owner's. */
+.dp-settled--waiting {
+  border-left: 3px solid var(--accent);
+  padding-left: 0.7rem;
+}
+.dp-settled--decision {
+  border-left: 3px solid var(--warn);
+  padding-left: 0.7rem;
+}
+.dp-settled .ps-controls { margin: 0.4rem 0 0.2rem; }
+
+/* The project's update rule (task 1004445) — a quiet setting under the move, set apart by
+   a hairline so it does not read as part of whichever state sits above it. */
+.dp-rule {
+  margin: 0.9rem 0 0;
+  padding-top: 0.7rem;
+  border-top: 1px solid var(--rule-soft);
+}
+.dp-rule .ps-controls { align-items: center; gap: 0.5rem; }
+.dp-rule__label { font-size: 0.86rem; color: var(--ink-soft); }
+.dp-rule__select { min-height: 32px; }
+/* A link inside a stopped move's sentence ("the owner's blockers") is a control and owes
+   the 24px floor: the prose-link recipe buys the height with padding and hands it back
+   with an equal negative margin, so the line does not re-space. */
+.dp-settled .ov-row__sub a { display: inline-block; min-height: 24px; padding: 3px 0; margin: -3px 0; }

package/modules/provisioning/core-upgrade.js

@@ -348,7 +348,10 @@ function previewFromSnapshot(inst, snap, openIntent, lastMove) {
     preflight_at: pf && recommended && pf.target === recommended ? (snap.preflight_at || null) : null,
     // not_before: a failed move waiting out its retry backoff (task 1004447) — the page can
     // say "trying again at …" instead of an unexplained "pending" for up to six hours.
-    open_intent: openIntent ? { action: openIntent.action, state: openIntent.state, target_version: openIntent.target_version || null, not_before: openIntent.not_before || null, last_error: openIntent.not_before && openIntent.last_error ? String(openIntent.last_error).slice(0, 600) : null } : null,
+    open_intent: openIntent ? { action: openIntent.action, state: openIntent.state, target_version: openIntent.target_version || null, not_before: openIntent.not_before || null, last_error: openIntent.not_before && openIntent.last_error ? String(openIntent.last_error).slice(0, 600) : null,
+      // WHY it is waiting (task 1004450): a transient retry and a known snag the runner just
+      // fixed wait the same way, and the page words them differently. Only on a waiting row.
+      failure: openIntent.not_before && openIntent.failure_class ? { class: openIntent.failure_class, reason: openIntent.failure_reason || null } : null } : null,
     // THE LAST MOVE, WHATEVER BECAME OF IT (task 1004145).
     //
     // `open_intent` is `state IN ('pending','running')` — by the index's own definition.

package/package-lock.json

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

package/package.json

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

package/release-notes.json

@@ -8297,5 +8297,21 @@
       "id": "1004457",
       "text": "The project setup wizard now offers Render's Free plan for your app, with a plain note that a free app sleeps when idle and takes about a minute to wake. Starter stays the default. The build and start command boxes no longer l"
     }
+  ],
+  "1.20.36": [
+    {
+      "id": "1004450",
+      "text": "The deploy page now explains why an update stopped in plain words, says when it will try again, and offers a one-click fix when the only thing in the way is your own update setting. You can also see and change how far a projec"
+    }
+  ],
+  "1.20.37": [
+    {
+      "id": "1003791",
+      "text": "A module's own tests can now be run and scored: the store records what share of them pass, and a module with no tests shows as 'no data yet' instead of failing."
+    },
+    {
+      "id": "1004406",
+      "text": "The unattended runner stops restarting every time anyone merges: it now updates its code in place and only restarts when its own code has changed."
+    }
   ]
 }

package/scripts/gds/autobongos-run.js

@@ -359,7 +359,7 @@ const MAX_CLAIM_ATTEMPTS = 5;
 const LIMIT_UNKNOWN_RESET_MS = 30 * 60 * 1000;
 
 function newRunnerState() {
-  return { setAside: new Map(), queueGate: null, limitUntil: null };
+  return { setAside: new Map(), queueGate: null, limitUntil: null, diskHead: null };
 }
 const RUNNER_STATE = newRunnerState();
 
@@ -666,13 +666,16 @@ function heartbeatPath() {
 // output, reddening `unit` on main and blocking every PR. Use a regular FILE as the
 // parent directory instead: mkdir under it is ENOTDIR immediately, everywhere, and it
 // does not depend on the caller's permissions.
-function writeHeartbeat(now = Date.now()) {
+function writeHeartbeat(now = Date.now(), runnerState = RUNNER_STATE) {
   try {
     const p = heartbeatPath();
     fs.mkdirSync(path.dirname(p), { recursive: true });
     // `head` is what this process is RUNNING, not what is on disk (task 1004374).
     // Alive and alive-on-stale-code look identical from a check-in age alone.
-    fs.writeFileSync(p, JSON.stringify({ pid: process.pid, at: now, head: LOADED_HEAD }));
+    // `disk_head` appears only when the checkout was refreshed in place past what
+    // is running (task 1004406): "up to date on disk, old supervisor" is visible.
+    const disk = runnerState && runnerState.diskHead && runnerState.diskHead !== LOADED_HEAD ? runnerState.diskHead : undefined;
+    fs.writeFileSync(p, JSON.stringify({ pid: process.pid, at: now, head: LOADED_HEAD, ...(disk ? { disk_head: disk } : {}) }));
     return true;
   } catch (_) { return false; }
 }
@@ -851,10 +854,79 @@ async function codeDrifted(deps = {}) {
   // the comparison untestable in isolation.
   const mine = deps.loadedHead ? await deps.loadedHead(deps) : await loadedHead(deps);
   if (!mine) return null;
+  // Measured from what is on DISK once the checkout has been refreshed in place
+  // (task 1004406), or every loop after a refresh would see the same drift again.
+  const base = ((deps.state || RUNNER_STATE).diskHead) || mine;
   let tip = null;
   try { tip = await runFetchHead(deps); } catch (_) { return null; }
   if (!tip) return null;
-  return tip !== mine ? { from: mine.slice(0, 8), to: String(tip).slice(0, 8) } : false;
+  return tip !== base ? { from: base.slice(0, 8), to: String(tip).slice(0, 8) } : false;
+}
+
+// ── pull always, restart rarely (task 1004406) ──────────────────────────────
+//
+// Owner-approved 2026-09-30. Main moves every time ANY session lands, and a
+// relaunch per merge meant a busy day of restarts (four in fourteen minutes on
+// 2026-09-29). But a restart only refreshes code THIS process holds in memory:
+// every worker, and every claim.js / worktree.js / release.js the loop shells
+// out to, is a fresh process that runs whatever is on disk. So on drift the
+// checkout is updated in place, and the process exits for the wrapper only when
+// a change touches code it has actually loaded.
+//
+// SUPERVISOR_PATH_RES catch the supervisor's own files even before they are
+// required (autobongos-verify.js is loaded lazily on the first ship), so a change
+// to a file the loop is ABOUT to load cannot mix old callers with a new callee.
+const SUPERVISOR_PATH_RES = [/^scripts\/gds\/autobongos-[^/]+$/, /^modules\/autonomy\//];
+
+// The repo files this process has loaded, repo-relative with forward slashes.
+function loadedFiles() {
+  const root = REPO_ROOT + path.sep;
+  const nm = path.sep + 'node_modules' + path.sep;
+  return Object.keys(require.cache)
+    .filter((p) => p.startsWith(root) && !p.includes(nm))
+    .map((p) => path.relative(REPO_ROOT, p).split(path.sep).join('/'));
+}
+
+// The changed files that force a restart: ones this process holds, or ones under
+// the supervisor's own paths. Everything else is picked up by the next child.
+function supervisorTouched(changed = [], loaded = loadedFiles()) {
+  const held = new Set(loaded);
+  return changed.filter((f) => held.has(f) || SUPERVISOR_PATH_RES.some((re) => re.test(f)));
+}
+
+// refreshCheckout — the wrapper's fetch + reset, done from inside the process.
+//
+// THE MAIN CHECKOUT ONLY. It runs `git reset --hard`, and a linked worktree is a
+// claim somebody is building in; resetting one would destroy their work. The
+// check compares git-dir to git-common-dir, which are equal only in the main
+// checkout. Armed only by main() (`opts.refreshInPlace`), so a test driving
+// forever() can never reach it — in CI that reset would wipe the code under test.
+//
+// The diff is from the LOADED commit, not the last refresh, so a supervisor
+// change that landed several refreshes ago still forces the restart it needs.
+async function refreshCheckout(deps = {}) {
+  const runCmd = deps.run || run;
+  const git = (args) => runCmd('git', args, { cwd: REPO_ROOT });
+  try {
+    const [gd, cd] = await Promise.all([git(['rev-parse', '--git-dir']), git(['rev-parse', '--git-common-dir'])]);
+    if (!gd.ok || !cd.ok) return { ok: false, reason: 'could not tell which checkout this is' };
+    if (path.resolve(REPO_ROOT, String(gd.stdout).trim()) !== path.resolve(REPO_ROOT, String(cd.stdout).trim())) {
+      return { ok: false, reason: 'not the main checkout — refusing to reset a linked worktree' };
+    }
+    const loaded = deps.loadedHead ? await deps.loadedHead(deps) : await loadedHead(deps);
+    if (!loaded) return { ok: false, reason: 'the running commit is unknown' };
+    if (!(await git(['fetch', '--quiet', 'origin', 'main'])).ok) return { ok: false, reason: 'fetch failed' };
+    const fh = await git(['rev-parse', 'FETCH_HEAD']);
+    const to = fh.ok ? String(fh.stdout).trim() : '';
+    if (!/^[0-9a-f]{40}$/.test(to)) return { ok: false, reason: 'could not read the fetched commit' };
+    const diff = await git(['diff', '--name-only', loaded, to]);
+    if (!diff.ok) return { ok: false, reason: 'could not diff the running commit against main' };
+    if (!(await git(['reset', '--quiet', '--hard', to])).ok) return { ok: false, reason: 'reset failed' };
+    const changed = String(diff.stdout).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    return { ok: true, to, changed };
+  } catch (e) {
+    return { ok: false, reason: e && e.message ? e.message : String(e) };
+  }
 }
 
 // The head of origin/main, or null. `git ls-remote` rather than `fetch`: it moves
@@ -932,7 +1004,9 @@ async function forever(opts, deps = {}) {
   // reports itself anyway: the hall reads the AGE of the last check-in, so a
   // failed beat shows up as silence, which is the signal.
   const beat = async (fields) => {
-    try { beatFile(); } catch (_) { /* a runner that cannot write its file still runs */ }
+    // The runner state is passed, not defaulted: the file names `disk_head` from
+    // it (task 1004406), and an injected state must reach the beat that reports it.
+    try { beatFile(Date.now(), deps.state || RUNNER_STATE); } catch (_) { /* a runner that cannot write its file still runs */ }
     try { await beatServer(fields, deps); } catch (_) { /* and one that cannot reach the instance still runs */ }
   };
   // The running commit, read ONCE, BEFORE the first beat (task 1004397). It used
@@ -993,14 +1067,35 @@ async function forever(opts, deps = {}) {
     // spends nearly all of its time and an upgrade should not sit behind it.
     const upMs = (deps.now ? deps.now() : Date.now()) - Date.parse(RUNNER_STARTED_AT);
     const mayUpgrade = upMs >= MIN_UPTIME_BEFORE_UPGRADE_MS;
-    const drift = mayUpgrade
+    let drift = mayUpgrade
       ? (deps.codeDrifted ? await deps.codeDrifted(deps) : await codeDrifted(deps))
       : false;
     if (drift) {
-      log({ event: 'upgrade_exit', from: drift.from, to: drift.to,
-        reason: `main moved from ${drift.from} to ${drift.to} — exiting so the wrapper can relaunch on the new code` });
-      await beat({ mode: state.mode, last_event: 'upgrade_exit' });
-      return UPGRADE_EXIT_CODE;
+      // Pull always, restart rarely (task 1004406). Only main() arms the refresh.
+      let why = 'exiting so the wrapper can relaunch on the new code';
+      if (opts.refreshInPlace) {
+        const refreshed = await (deps.refreshCheckout || refreshCheckout)(deps);
+        if (refreshed && refreshed.ok) {
+          const touched = supervisorTouched(refreshed.changed, deps.loadedFiles ? deps.loadedFiles() : loadedFiles());
+          if (!touched.length) {
+            (deps.state || RUNNER_STATE).diskHead = refreshed.to;
+            log({ event: 'code_refreshed', from: drift.from, to: refreshed.to.slice(0, 8), changed: refreshed.changed.length,
+              reason: `main moved from ${drift.from} to ${refreshed.to.slice(0, 8)} — checkout updated in place; none of the ${refreshed.changed.length} changed file(s) is code this process runs, so no restart` });
+            await beat({ mode: state.mode, last_event: 'code_refreshed' });
+            drift = null;
+          } else {
+            const more = touched.length > 5 ? `, +${touched.length - 5} more` : '';
+            why = `it changed code this process runs (${touched.slice(0, 5).join(', ')}${more}) — exiting so the wrapper can relaunch on it`;
+          }
+        } else {
+          why = `the in-place refresh did not run (${(refreshed && refreshed.reason) || 'no result'}) — exiting so the wrapper's own refresh can`;
+        }
+      }
+      if (drift) {
+        log({ event: 'upgrade_exit', from: drift.from, to: drift.to, reason: `main moved from ${drift.from} to ${drift.to} — ${why}` });
+        await beat({ mode: state.mode, last_event: 'upgrade_exit' });
+        return UPGRADE_EXIT_CODE;
+      }
     }
 
     const { waited, jumped } = await wait(state.waitS, { ...deps, beat }, opts.cadence);
@@ -1015,7 +1110,7 @@ async function main(argv) {
   // it lived on the machine being fenced; the database owns that now, and an empty
   // `--goal` means "every allowlisted goal" rather than "anything claimable". The
   // refusal did not disappear — it moved somewhere the runner host cannot edit.
-  if (opts.forever) return forever(opts);
+  if (opts.forever) return forever({ ...opts, refreshInPlace: true });
 
   // The one-shot path, kept for an operator running a single task by hand. It
   // still reconciles first: a leftover claim is a leftover claim whoever is
@@ -1043,5 +1138,5 @@ module.exports = {
   worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX, codeDrifted, loadedHead, UPGRADE_EXIT_CODE, MIN_UPTIME_BEFORE_UPGRADE_MS,
   heartbeatPath, writeHeartbeat, readHeartbeat, pidAlive, anotherRunnerIsAlive, HEARTBEAT_STALE_MS,
   isRunnerTree, RUNNER_TREE_RE, postHeartbeat, RUNNER_STARTED_AT, failureReason,
-  newRunnerState, LIMIT_UNKNOWN_RESET_MS, QUEUE_GATED_EXIT, CLAIM_SET_ASIDE_MS, MAX_CLAIM_ATTEMPTS, owedTaskIds,
+  newRunnerState, loadedFiles, supervisorTouched, refreshCheckout, LIMIT_UNKNOWN_RESET_MS, QUEUE_GATED_EXIT, CLAIM_SET_ASIDE_MS, MAX_CLAIM_ATTEMPTS, owedTaskIds,
 };