@bongos/core 1.24.84 → 1.24.86

package/docs/recipes/autobongos-runner-setup.md

@@ -138,6 +138,7 @@ worker decided on its own, what it cost, and where your Claude usage stands.
 | **Resting** for hours | That is your Claude usage limit, and it is working as designed. It resumes at the time on the button. |
 | **Running**, but nothing ships for a long time | The tasks in the goals you chose may all be waiting on something. Run the digest above: it says what is on hold and why. |
 | You added the same device twice | Remove one card. One runner per device. |
+| **Repository not found**, and you *are* signed in to GitHub | You are signed in as more than one GitHub account, and the device is using the wrong one. Run `gh auth switch` and pick the account that can see the project, then paste the setup command again. The setup names the account it used, so you can tell which it picked. |
 
 ## An always-on PC that starts with nobody signed in
 

package/modules/hall-ui/public/craft-mode.js

@@ -472,8 +472,11 @@
   function toolNode(t) { return document.getElementById('craft-tool-' + t.id); }
   // A docked tool has no button: in its mode the panel is docked at the edge,
   // out of it the panel goes. Only a tool already loaded needs closing.
+  // A screen inside the options menu's frame docks nothing: the menu page around
+  // it already docks its own, and a second panel at the frame's edge is a double.
   function applyDocked(mode) {
-    var want = toolsFor(mode);
+    var framed = !!(window.OTBShellGame && window.OTBShellGame.embedded && window.OTBShellGame.embedded());
+    var want = framed ? [] : toolsFor(mode);
     for (var m in TOOLS) TOOLS[m].forEach(function (t) {
       if (!t.docked) return;
       if (want.indexOf(t) !== -1) loadTool(t).then(function (api) { if (api.dock) api.dock(); }, function () { /* the page still works */ });

package/modules/hall-ui/public/options-menu.js

@@ -363,6 +363,10 @@
 
   // Close the menu (game mode's Escape): back where it was opened from.
   function close() {
+    // Opened as the game's options window over a place (shell-game.js): shut the window.
+    var holder = null;
+    try { holder = window.parent !== window ? window.parent.OTBOptionsOverlay : null; } catch (_) { holder = null; }
+    if (holder && holder.isOpen && holder.isOpen()) { holder.close(); return; }
     var to = state.from || closeTo(window.location.search);
     if (to) { window.location.assign(to); return; }
     var ref = '';

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

@@ -129,6 +129,21 @@ html[data-fullscreen="on"] .opt-title { display: block; }
 .opt-embed__frame { display: block; width: 100%; height: calc(100vh - 96px - var(--opt-screen-h)); min-height: 480px; border: 0; border-radius: var(--press-radius); background: transparent; }
 html[data-fullscreen="on"] .opt-embed__frame { height: calc(100vh - 48px - var(--opt-screen-h)); }
 
+/* Inside the game's options window (shell-game.js): the window is the chrome, so the
+   menu sits flush at its top and the open screen fills the rest of it. The page is
+   drawn at the embed zoom (style.css), so a window-high length divides by it. */
+html[data-embed="on"] .settings-layout { --opt-vh: calc(100vh / 0.82); padding: var(--ds-space-md) var(--ds-space-lg) 0 0; }
+html[data-embed="on"] .opt-rail { top: 0; max-height: calc(var(--opt-vh) - var(--ds-space-md)); margin-top: calc(-1 * var(--ds-space-md)); padding-top: var(--ds-space-lg); }
+html[data-embed="on"] .opt-title { display: block; font-size: var(--ds-text-xl); }
+/* the window's glass is the ground, so the menu adds none; and window-sized words */
+html[data-embed="on"] .opt-rail { background: none; }
+html[data-embed="on"] .opt-search input { min-height: 34px; font-size: var(--ds-text-sm-plus); }
+html[data-embed="on"] .opt-link { min-height: 30px; font-size: var(--ds-text-md); }
+html[data-embed="on"] .opt-screen { font-size: var(--ds-text-xl); }
+html[data-embed="on"] .settings-groups { --opt-screen-h: calc(var(--ds-space-lg) + var(--ds-space-md)); }
+html[data-embed="on"] .settings-groups .scroll__h { font-size: var(--ds-text-md); }
+html[data-embed="on"] .opt-embed__frame { height: calc(var(--opt-vh) - var(--opt-screen-h) - var(--ds-space-xl)); min-height: 0; }
+
 @media (max-width: 860px) {
   /* Collapse to one column: the menu sits above the open screen, no longer sticky. */
   .settings-layout { grid-template-columns: minmax(0, 1fr); gap: var(--sp-md); }

package/modules/hall-ui/public/shell-game.js

@@ -406,11 +406,91 @@
       try { e.preventDefault(); } catch (_) { /* already finished */ }
       var host = embedded ? window.parent : window;
       if (host && host.OTBOptions && typeof host.OTBOptions.escape === 'function') { host.OTBOptions.escape(); return; }
+      if (host && host.OTBOptionsOverlay && host.OTBOptionsOverlay.isOpen()) { host.OTBOptionsOverlay.close(); return; }
       if (embedded) return;
-      var here = String(window.location.pathname || '') + String(window.location.search || '') + String(window.location.hash || '');
-      window.location.assign(menuPath() + '?from=' + encodeURIComponent(here));
+      openOverlay();
     }, 0);
   }
+
+  // ---------- the options window (game mode) ----------
+  // In game mode the options menu opens as a window OVER the place you are in, not
+  // as a page of its own, so the place stays drawn behind it and its colours show
+  // through (the owner's call, 2026-11-11: "WoW sizing, an overlay"). The window
+  // is a frame of the menu with ?embed=1; the menu page itself (a plain visit to
+  // /settings) is unchanged. It is the hall's shared dialog (OTBDialog.bind,
+  // hall-dialog.js): Escape, the scrim, the close button, the focus trap and the
+  // focus return are its. The page behind is made inert while it is up, because Tab
+  // leaving the frame's last control lands in the page, past the dialog's own trap.
+  var overlay = null, dialog = null;
+  function overlayOpen() { return !!(dialog && dialog.isOpen()); }
+  function closeOverlay() { if (overlayOpen()) dialog.close(); }
+  function setInert(on) {
+    var kids = document.body && document.body.children ? document.body.children : [];
+    for (var i = 0; i < kids.length; i += 1) {
+      var k = kids[i];
+      if (k === overlay || !k.setAttribute) continue;
+      if (on) { if (!k.hasAttribute('inert')) { k.setAttribute('inert', ''); k.setAttribute('data-opt-inert', ''); } }
+      else if (k.hasAttribute('data-opt-inert')) { k.removeAttribute('inert'); k.removeAttribute('data-opt-inert'); }
+    }
+  }
+  // `rest` is what follows the menu's path: '?open=x#y', '#access', or ''.
+  function openOverlay(rest) {
+    try { buildOverlay(rest || ''); } catch (_) {
+      // No window can be drawn here: the menu's own page, as before the window existed.
+      overlay = null; dialog = null;
+      var here = String(window.location.pathname || '') + String(window.location.search || '') + String(window.location.hash || '');
+      window.location.assign(menuPath() + (rest || '?from=' + encodeURIComponent(here)));
+    }
+  }
+  function buildOverlay(rest) {
+    var src = menuPath() + withEmbed(rest);
+    if (!overlay) {
+      if (!window.OTBDialog || typeof window.OTBDialog.bind !== 'function') throw new Error('no dialog');
+      overlay = document.createElement('div');
+      overlay.className = 'opt-window';
+      overlay.hidden = true;
+      overlay.innerHTML = '<div class="opt-window__box" aria-label="Options">' +
+        '<button type="button" class="opt-window__x" data-dialog-close aria-label="Close options">×</button>' +
+        '<iframe class="opt-window__frame" title="Options"></iframe></div>';
+      document.body.appendChild(overlay);
+      var frame0 = overlay.querySelector('.opt-window__frame');
+      dialog = window.OTBDialog.bind(overlay, {
+        panel: overlay.querySelector('.opt-window__box'),
+        lockClass: 'opt-window-open',
+        initialFocus: function () { return frame0; },
+        onOpen: function () { setInert(true); },
+        onClose: function () { setInert(false); },
+      });
+    }
+    var frame = overlay.querySelector('.opt-window__frame');
+    // A fresh address reloads the menu; the same one keeps it as it was left.
+    if (frame.getAttribute('src') !== src) frame.setAttribute('src', src);
+    dialog.open();
+  }
+  // '?open=x#y' → '?embed=1&open=x#y'; '#y' → '?embed=1#y'.
+  function withEmbed(rest) {
+    var h = rest.indexOf('#'), q = h === -1 ? rest : rest.slice(0, h), frag = h === -1 ? '' : rest.slice(h);
+    q = q.replace(/^\?/, '');
+    return '?embed=1' + (q ? '&' + q : '') + frag;
+  }
+  // The menu's own page never opens the window (nor a page in a frame: see the if below).
+  function overlayHere() { return on() && !(document.body && document.body.getAttribute('data-page') === 'settings'); }
+  if (!embedded) {
+    window.OTBOptionsOverlay = { open: openOverlay, close: closeOverlay, isOpen: overlayOpen };
+    // A link to the menu (the visor's Options row, the profile chip, the start
+    // screen's Options) opens the window in game mode instead of leaving the place.
+    if (document.addEventListener) document.addEventListener('click', function (e) {
+      if (e.defaultPrevented || e.button || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || !overlayHere()) return;
+      var a = e.target && e.target.closest ? e.target.closest('a[href]') : null;
+      if (!a || a.getAttribute('target')) return;
+      var to;
+      try { to = new URL(a.getAttribute('href'), window.location.href); } catch (_) { return; }
+      if (to.origin !== window.location.origin || to.pathname.replace(/\.html$/, '') !== menuPath()) return;
+      e.preventDefault();
+      var q = to.search.replace(/([?&])from=[^&#]*&?/, '$1').replace(/[?&]$/, '');
+      openOverlay(q + to.hash);
+    }, true);
+  }
   if (window.addEventListener) window.addEventListener('keydown', onEscape);
   // Inside the menu, a link to ANOTHER page leaves the menu for it; a link within the page stays.
   if (embedded && document.addEventListener) {

package/modules/hall-ui/public/style.css

@@ -1398,6 +1398,38 @@ html[data-embed="on"] .app-foot,
 html[data-embed="on"] .app-topbar { display: none; }
 html[data-embed="on"] .app-body { margin-left: 0; }
 html[data-embed="on"] .app-content { padding-top: 0; }
+/* An embedded screen is a sub-window, so it reads at window size, not page size
+   (the owner, 2026-11-11: "WoW sizing"): everything in it is drawn smaller, and it
+   has no ground of its own, so the options window's glass and the place behind
+   show through. */
+html[data-embed="on"] { zoom: 0.82; }
+html[data-embed="on"], html[data-embed="on"] body { background: transparent; }
+/* THE OPTIONS WINDOW (shell-game.js openOverlay): in game mode the menu opens over
+   the place you are in. The scrim only darkens a little, so the place stays legible;
+   the window is night glass, so its colours carry through. */
+html.opt-window-open { overflow: hidden; }
+.opt-window { position: fixed; inset: 0; z-index: var(--z-modal); display: grid; place-items: center; }
+.opt-window[hidden] { display: none; }
+/* the scrim is the overlay's own ground, so a click on it lands on the dialog root (OTBDialog closes) */
+.opt-window::before { content: ''; position: absolute; inset: 0; background: var(--scrim); opacity: .33; pointer-events: none; }
+.opt-window__box {
+  position: relative; box-sizing: border-box;
+  width: min(1040px, calc(100vw - 32px)); height: min(720px, calc(100vh - 48px));
+  background: color-mix(in srgb, var(--bg) 48%, transparent);
+  -webkit-backdrop-filter: blur(3px); backdrop-filter: blur(3px);
+  border: var(--line-strong) solid var(--rule);
+  border-radius: var(--press-radius);
+  box-shadow: var(--ds-shadow-pop);
+}
+.opt-window__frame { display: block; width: 100%; height: 100%; border: 0; background: transparent; color-scheme: dark; }
+.opt-window__x {
+  position: absolute; top: var(--ds-space-xs); right: var(--ds-space-xs); z-index: 1;
+  width: 28px; height: 28px; padding: 0; display: grid; place-items: center;
+  font-size: var(--ds-text-2xl); line-height: 1; color: var(--ink-soft);
+  background: transparent; border: var(--line) solid var(--rule-soft); border-radius: var(--press-radius); cursor: pointer;
+}
+.opt-window__x:hover { color: var(--ink); background: var(--glass); }
+.opt-window__x:focus-visible { outline: 0; box-shadow: var(--press-focus); }
 /* Said once on entering, since the choice is remembered and a page can open in it. */
 .fullscreen-hint {
   position: fixed;

package/modules/hall-ui/records/options-menu.md

@@ -24,3 +24,10 @@ The menu is a Helm screen, written from the hall tier's tokens alone (`settings.
 - **Widths:** the panel is `min(--helm-panel-w, 32%)` of the content column; below 860px it stacks above the screen as before. A long label wraps inside its row.
 - **Not built** (the mock shows them on a Controls screen the hall does not have): the key-binding rows, "Reset all keys", and a visible "Back to the city" button. Escape still closes the menu in game mode.
 - **Tests:** `tests/hall_helm.mjs` ("the options menu is a Helm screen"); the kit states in `settings.states.json` render clean at 1440, 390 and 320.
+
+## The options window (owner, 2026-11-11: "WoW sizing, an overlay")
+
+- **In game mode the menu opens over the place, not as a page.** Escape away from the menu, or a click on any link to `/settings` (the visor's Options row, the profile chip), draws one window (`shell-game.js` `openOverlay`, `window.OTBOptionsOverlay`), built on the shared dialog (`OTBDialog.bind`: Escape, scrim, close button, focus trap and return), with the page behind made `inert` while it is up, holding the menu framed with `?embed=1`; the place stays drawn behind it. Escape, the scrim or the × shuts it; `options-menu.js` `close()` shuts the window when it is in one. A page that cannot draw it falls back to the menu page. A plain visit to `/settings` is the page, as before.
+- **Window sized, see-through.** The window is `min(1040px, …) × min(720px, …)` of glass at 48% of the ground with a light blur, over the shared `--scrim` at a third. Every embedded screen is drawn at `zoom: 0.82` with no ground of its own (`style.css`), and the menu inside it takes smaller words (`settings.css`, `html[data-embed="on"]`); a window-high length divides by the zoom (`--opt-vh`).
+- **One review palette.** A framed screen docks no artist palette of its own (`craft-mode.js` `applyDocked`); the page around it has one.
+- **Tests:** `tests/hall_options_menu.mjs` ("away from the menu, Escape opens the options as a window…"), `tests/page_notes_panel.mjs` (the frame docks no panel).

package/package-lock.json

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

package/package.json

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

@@ -11607,5 +11607,17 @@
       "id": "1005195",
       "text": "The in-game visor is now minimal: two thin arcs, the place name, your credits, one salmon button for the current action and a quiet row of key hints. It stays readable over a bright daytime sky as well as at night."
     }
+  ],
+  "1.24.85": [
+    {
+      "id": "1005096",
+      "text": "Autobongos now runs on a Mac for real: the setup command, start, stop and remove all proven on one, and the Mac-only test failures are gone."
+    }
+  ],
+  "1.24.86": [
+    {
+      "id": "1005208",
+      "text": "In game mode, Options now opens as a smaller see-through window over where you are, with smaller text, and the artist palette no longer shows twice."
+    }
   ]
 }

package/scripts/bongos/autobongos-bootstrap.sh

@@ -59,6 +59,28 @@ esac
 
 have() { command -v "$1" >/dev/null 2>&1; }
 
+# github_remedy — what to actually DO when git cannot see the project (task 1005096).
+#
+# THE CIRCLE THIS BREAKS, found on a real Mac. "Sign in to GitHub" is the wrong advice for
+# the commonest way this fails: the person IS signed in — twice — and git picked the other
+# one. git asks its FIRST credential helper, which on a Mac is the login keychain, and that
+# answers with whichever GitHub account is active, not with one that can see this project.
+# A private project then 404s as "Repository not found", which reads as a typo rather than
+# as the wrong account, and `gh auth login` again changes nothing.
+#
+# So when the GitHub CLI is here, name the account that is actually active and the one
+# command that changes it. With no gh, the old advice is still the right advice.
+github_remedy() {
+  if have gh; then
+    active="$(gh auth status --active 2>/dev/null | sed -n 's/.*account \([A-Za-z0-9-]*\).*/\1/p' | head -n 1)"
+    if [ -n "${active:-}" ]; then
+      echo "git is using your '$active' GitHub account, which may not be able to see this project. Switch with  gh auth switch  (it lists the accounts signed in here), then paste the setup command again. If the right account is not listed, add it with  gh auth login  first."
+      return
+    fi
+  fi
+  echo "Sign in to GitHub on this device with an account that can see the project (the GitHub CLI's  gh auth login  is the simplest way), then paste the setup command again."
+}
+
 # The setup command is piped into bash, so the keyboard is /dev/tty, not stdin.
 # OPENED, not just tested: with no terminal at all (CI, a remote command) the
 # device node still exists and reads as readable, and opening it is what fails.
@@ -133,12 +155,12 @@ mkdir -p "$RUNNER_HOME"
 if [ -d "$REPO_DIR/.git" ]; then
   echo "The runner's copy is already here; bringing it up to date..."
   if [ "$HAVE_TTY" = 1 ]; then git -C "$REPO_DIR" fetch --quiet origin main </dev/tty; else git -C "$REPO_DIR" fetch --quiet origin main; fi \
-    || stop_setup "this device could not fetch the project's code from GitHub." "Sign in to GitHub on this device (the GitHub CLI's  gh auth login  is the simplest way), then paste the setup command again."
+    || stop_setup "this device could not fetch the project's code from GitHub." "$(github_remedy)"
   git -C "$REPO_DIR" reset --quiet --hard origin/main
 else
   echo "Making the runner's own copy of the project (GitHub may ask you to sign in)..."
   if [ "$HAVE_TTY" = 1 ]; then git clone --quiet "$REPO" "$REPO_DIR" </dev/tty; else git clone --quiet "$REPO" "$REPO_DIR"; fi \
-    || stop_setup "this device could not copy the project from GitHub." "Sign in to GitHub on this device with an account that can see the project (the GitHub CLI's  gh auth login  is the simplest way), then paste the setup command again."
+    || stop_setup "this device could not copy the project from GitHub." "$(github_remedy)"
 fi
 
 HOST_JS="$REPO_DIR/scripts/bongos/autobongos-host.js"

package/scripts/bongos/autobongos-host.js

@@ -125,6 +125,28 @@ class Stop extends Error {
   constructor(what, fix) { super(what); this.name = 'Stop'; this.fix = fix || null; }
 }
 
+// githubRemedy — what to DO when git cannot see the project (task 1005096). The JS twin of
+// autobongos-bootstrap.sh's github_remedy; the two say the same thing because a person can
+// meet either one, and the bootstrap's own header carries the full reasoning.
+//
+// IN SHORT: "sign in to GitHub" is the wrong advice for the commonest failure. git asks its
+// FIRST credential helper — on a Mac, the login keychain — which answers with whichever
+// GitHub account is ACTIVE, not with one that can see this project. A private project then
+// 404s as "Repository not found", which reads as a typo rather than as the wrong account,
+// and signing in again changes nothing. So name the active account when the GitHub CLI can
+// tell us, and give the one command that changes it.
+const GITHUB_REMEDY_GENERIC = 'Sign in to GitHub on this device with an account that can see the project (the GitHub CLI\'s  gh auth login  is the simplest way), then run the setup command again.';
+function githubRemedy(run = spawnSync) {
+  try {
+    const r = run('gh', ['auth', 'status', '--active'], { encoding: 'utf8', windowsHide: true, timeout: 10000 });
+    const m = /account ([A-Za-z0-9-]+)/.exec(String((r && r.stdout) || '') + String((r && r.stderr) || ''));
+    if (m) {
+      return `git is using your '${m[1]}' GitHub account, which may not be able to see this project. Switch with  gh auth switch  (it lists the accounts signed in here), then run the setup command again. If the right account is not listed, add it with  gh auth login  first.`;
+    }
+  } catch (_) { /* no gh, or it could not answer — the generic line is still right */ }
+  return GITHUB_REMEDY_GENERIC;
+}
+
 // ── the runner's own copy ──────────────────────────────────────────────────
 
 function runnerCopyMarkPath(repoRoot = REPO_ROOT) { return path.join(repoRoot, '.git', RUNNER_COPY_MARK); }
@@ -289,7 +311,14 @@ function git(args, opts = {}) {
 function refreshCheckout(log = () => {}) {
   assertRunnerCopy();
   const f = git(['fetch', '--quiet', 'origin', 'main']);
-  if (f.status !== 0) { log(`git fetch failed — running the code already here (${String(f.stderr || '').trim().slice(0, 200)})`); return false; }
+  if (f.status !== 0) {
+    // The log is the ONLY place this is said (the card reads check-ins, not fetches), so it
+    // carries the remedy too — a fetch that fails for a credential reason fails every loop,
+    // and the runner then works forever on the code it happens to have (task 1005096).
+    log(`git fetch failed — running the code already here (${String(f.stderr || '').trim().slice(0, 200)})`);
+    log(`  if that keeps happening, it is not transient: ${githubRemedy()}`);
+    return false;
+  }
   const r = git(['reset', '--quiet', '--hard', 'origin/main']);
   if (r.status !== 0) { log(`git reset failed (${String(r.stderr || '').trim().slice(0, 200)})`); return false; }
   return true;
@@ -726,7 +755,7 @@ async function setup(argv, { paths = hostPaths(), say = console.log } = {}) {
 
   say('4/5  Checking this device can fetch the project’s code…');
   if (git(['ls-remote', 'origin', 'refs/heads/main'], { timeout: 60000 }).status !== 0) {
-    throw new Stop('This device could not fetch the project’s code from GitHub.', 'Sign in to GitHub on this device (run  git fetch  in the runner’s folder and follow the sign-in), then run the setup command again.');
+    throw new Stop('This device could not fetch the project’s code from GitHub.', githubRemedy());
   }
 
   say('5/5  Starting the runner…');
@@ -895,4 +924,5 @@ module.exports = {
   windowsRunArgv, windowsRunCommand, windowsStartSpawn, legacyBootTaskInstalled, launchdPlist,
   stopRunner, stopReport, exchangeCode, claudeState, waitForCheckIn,
   signIn, cleanBase, install, removeStartEntry, installedState, status, digestArgv,
+  githubRemedy, GITHUB_REMEDY_GENERIC,
 };

package/scripts/bongos/wedge-remedy.js

@@ -90,12 +90,19 @@ function planRemedy(inst, reason, o = {}) {
     if (!SHELL_SAFE_RE.test(backupDir)) return { refused: 'the backup folder is not a path this runner will put in a command' };
     // EXACTLY db-backup-nightly.sh's name, so this never touches a sibling project's dumps
     // (`test` must not prune `test-nk`'s — task 1003948). The timestamp sorts by name, so
-    // `sort | head -n -K` drops all but the newest K. Nothing is deleted when K or fewer exist.
+    // dropping all but the last K leaves the newest K. Nothing is deleted when K or fewer exist.
+    //
+    // ALL-BUT-THE-LAST-K IN POSIX awk, NOT `head -n -K` (task 1005096). `head -n -K` is a GNU
+    // extension: BSD/macOS head answers `illegal line count`, exits 1, and the pipeline then
+    // deletes nothing — and `xargs -r` is GNU-only too. Same family as the `stat -c` sweep
+    // (task 1004170): the command runs on a Linux box, but the test that runs it for real runs
+    // wherever a builder builds, so on a Mac it could never pass. POSIX `xargs` with no input
+    // may still run `rm -f --`, which succeeds with no operands, so `-r` is not needed.
     const D = '[0-9]';
     const glob = `${db}-${D}${D}${D}${D}-${D}${D}-${D}${D}T${D}${D}${D}${D}${D}${D}Z.sql.gz`;
     return {
       reason, cwd: null, env: null,
-      cmd: `find ${backupDir} -maxdepth 1 -type f -name '${glob}' | sort | head -n -${DUMP_KEEP_FLOOR} | xargs -r rm -f --`,
+      cmd: `find ${backupDir} -maxdepth 1 -type f -name '${glob}' | sort | awk -v k=${DUMP_KEEP_FLOOR} '{a[NR]=$0} END{for(i=1;i<=NR-k;i++) print a[i]}' | xargs rm -f --`,
       describe: `pruned ${db}'s old database backups in ${backupDir}, keeping the newest ${DUMP_KEEP_FLOOR}`,
     };
   }

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.84'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.86'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/autobongos_host.mjs

@@ -663,3 +663,36 @@ test('the digest is read from the RUNNER’s run log: bare, the digest CLI looks
   assert.equal(bare.status, 0, 'the digest never fails a morning');
   assert.equal(bare.stdout.includes('424242'), false, 'which is why the guide sends people through the device program');
 });
+
+// --- "sign in to GitHub" is the wrong advice when you already are (task 1005096) -------
+//
+// Found by running the real setup on a real Mac. The device had TWO GitHub accounts signed
+// in through the GitHub CLI; git asks its first credential helper — the login keychain —
+// which answers with whichever is ACTIVE, and that one could not see the private project.
+// git then says "Repository not found", which reads as a typo, and the setup answered
+// "Sign in to GitHub … gh auth login is the simplest way" — advice that changes nothing,
+// because the person is signed in. The remedy has to NAME the account git is using.
+test('githubRemedy names the active GitHub account, and the command that changes it', () => {
+  const said = host.githubRemedy(() => ({ stdout: 'github.com\n  ✓ Logged in to github.com account mcip-labs (keyring)\n', stderr: '' }));
+  assert.match(said, /'mcip-labs'/, 'the account git is actually using must be named, or the advice is a circle');
+  assert.match(said, /gh auth switch/, 'and the one command that changes it');
+  assert.notEqual(said, host.GITHUB_REMEDY_GENERIC);
+});
+
+test('githubRemedy falls back to the plain advice when gh cannot answer', () => {
+  // No GitHub CLI on the device, it failed, or it is signed in to nothing: there is no
+  // account to name, and "sign in" is then exactly the right thing to say.
+  assert.equal(host.githubRemedy(() => ({ stdout: '', stderr: 'command not found' })), host.GITHUB_REMEDY_GENERIC);
+  assert.equal(host.githubRemedy(() => { throw new Error('ENOENT'); }), host.GITHUB_REMEDY_GENERIC);
+  assert.equal(host.githubRemedy(() => ({ stdout: 'You are not logged into any GitHub hosts.\n', stderr: '' })), host.GITHUB_REMEDY_GENERIC);
+});
+
+test('the shell bootstrap gives the same remedy, so either half says the same thing', () => {
+  const sh = readFileSync(fileURLToPath(new URL('../scripts/bongos/autobongos-bootstrap.sh', import.meta.url)), 'utf8');
+  assert.match(sh, /github_remedy\(\)/, 'the bootstrap has the twin');
+  assert.match(sh, /gh auth switch/);
+  // Both clone/fetch stops route through it rather than re-typing the old line.
+  const stops = sh.split('\n').filter((l) => /stop_setup "this device could not (copy|fetch)/.test(l));
+  assert.equal(stops.length, 2, 'the two GitHub stops');
+  for (const l of stops) assert.match(l, /\$\(github_remedy\)/, l.trim());
+});

package/tests/hall_options_menu.mjs

@@ -138,7 +138,7 @@ test('the Settings page IS the menu: one search over the groups, loaded before s
 
 // ---- shell-game.js: the embedded page and game mode's Escape --------------------
 
-function bootGame({ search = '', framed = true, game = false, path: p = '/my-agents' } = {}) {
+function bootGame({ search = '', framed = true, game = false, path: p = '/my-agents', dom = false } = {}) {
   const docListeners = {};
   const winListeners = {};
   const timers = [];
@@ -156,13 +156,40 @@ function bootGame({ search = '', framed = true, game = false, path: p = '/my-age
   win.parent = framed ? parent : win;
   const document = {
     documentElement: root,
-    body: { setAttribute(k, v) { bodyAttrs[k] = v; } },
+    body: { setAttribute(k, v) { bodyAttrs[k] = v; }, getAttribute: (k) => (k in bodyAttrs ? bodyAttrs[k] : null) },
     addEventListener(t, fn) { (docListeners[t] ||= []).push(fn); },
   };
+  // dom: enough of a page for the game's options window to be drawn (createElement,
+  // a sibling the window makes inert, a frame that keeps its src), with OTBDialog.bind
+  // standing in for hall-dialog.js (its trap, Escape and focus return are tested there).
+  const windows = [];
+  const bound = [];
+  const sibling = { attrs: {}, setAttribute(k, v) { this.attrs[k] = v; }, hasAttribute(k) { return k in this.attrs; }, removeAttribute(k) { delete this.attrs[k]; } };
+  if (dom) {
+    document.body.children = [sibling];
+    document.body.appendChild = (el) => { windows.push(el); document.body.children.push(el); return el; };
+    document.createElement = () => {
+      const frameAttrs = {};
+      const frame = { getAttribute: (k) => (k in frameAttrs ? frameAttrs[k] : null), setAttribute: (k, v) => { frameAttrs[k] = v; }, focus() {} };
+      const box = { box: true };
+      return { hidden: false, innerHTML: '', querySelector: (sel) => (sel === '.opt-window__box' ? box : frame), frame, box };
+    };
+    win.OTBDialog = {
+      bind(root, opts) {
+        let open = false;
+        bound.push({ root, opts });
+        return {
+          open() { if (open) return; open = true; root.hidden = false; root.classes = [opts.lockClass]; opts.onOpen(); },
+          close() { if (!open) return; open = false; root.hidden = true; root.classes = []; opts.onClose(); },
+          isOpen: () => open,
+        };
+      },
+    };
+  }
   const ctx = vm.createContext({ window: win, document, URLSearchParams, URL });
   vm.runInContext(read('shell-game.js'), ctx);
   return {
-    root, bodyAttrs, parent, assigned, game: win.OTBShellGame,
+    root, bodyAttrs, parent, assigned, windows, bound, sibling, win, game: win.OTBShellGame,
     press(key, target = { tagName: 'DIV' }) {
       const ev = { key, target, defaultPrevented: false, preventDefault() { this.defaultPrevented = true; } };
       for (const fn of winListeners.keydown || []) fn(ev);
@@ -173,7 +200,7 @@ function bootGame({ search = '', framed = true, game = false, path: p = '/my-age
       const attrs = { href };
       if (target) attrs.target = target;
       const a = { getAttribute: (k) => (k in attrs ? attrs[k] : null), setAttribute: (k, v) => { attrs[k] = v; } };
-      for (const fn of docListeners.click || []) fn({ target: { closest: () => a } });
+      for (const fn of docListeners.click || []) fn({ target: { closest: () => a }, preventDefault() { this.defaultPrevented = true; } });
       return attrs.target || null;
     },
   };
@@ -214,6 +241,38 @@ test('GAME MODE: on the menu itself the last Escape closes it; outside game mode
   assert.deepEqual(off.assigned, [], 'outside game mode the press stays the shell\'s');
 });
 
+test('GAME MODE: away from the menu, Escape opens the options as a window over the place, and Escape again shuts it', () => {
+  const city = bootGame({ game: true, framed: false, path: '/city', dom: true });
+  city.press('Escape');
+  assert.deepEqual(city.assigned, [], 'the place stays: no page change');
+  assert.equal(city.windows.length, 1, 'one window drawn over it');
+  assert.equal(city.windows[0].frame.getAttribute('src'), '/settings?embed=1', 'the menu, framed and chromeless');
+  assert.equal(city.bound.length, 1, 'the window is the shared dialog: OTBDialog.bind owns Escape, the scrim, the focus trap and return');
+  assert.equal(city.bound[0].opts.panel, city.windows[0].box, 'the glass box is the dialog panel');
+  assert.equal(city.bound[0].opts.lockClass, 'opt-window-open', 'the page behind stops scrolling');
+  assert.equal(city.bound[0].opts.initialFocus(), city.windows[0].frame, 'focus goes into the menu');
+  assert.equal(city.sibling.hasAttribute('inert'), true, 'the page behind is inert, so Tab out of the frame cannot reach it');
+  assert.equal(city.win.OTBOptionsOverlay.isOpen(), true);
+  city.press('Escape');
+  assert.equal(city.win.OTBOptionsOverlay.isOpen(), false, 'the second Escape shuts it');
+  assert.equal(city.sibling.hasAttribute('inert'), false, 'and the page behind is live again');
+  city.press('Escape');
+  assert.equal(city.windows.length, 1, 'reopening reuses the one window');
+  assert.equal(city.bound.length, 1, 'bound once');
+  // a link to the menu (the visor's Options row) opens the window at that screen
+  city.win.OTBOptionsOverlay.close();
+  city.click('/settings?from=%2Fcity#access');
+  assert.equal(city.windows[0].frame.getAttribute('src'), '/settings?embed=1#access', 'the screen it named, without ?from=');
+  assert.equal(city.win.OTBOptionsOverlay.isOpen(), true);
+  // outside game mode the link is a link
+  const off = bootGame({ game: false, framed: false, path: '/city', dom: true });
+  off.click('/settings');
+  assert.equal(off.windows.length, 0);
+  // and the menu, closing inside the window, shuts the window rather than leaving the page
+  const om = read('options-menu.js');
+  assert.ok(om.includes('window.parent.OTBOptionsOverlay') && om.includes('holder.close(); return;'), 'close() shuts the window first');
+});
+
 test('options-menu.js gives the menu its Escape: close in game mode, nothing outside it', () => {
   const src = read('options-menu.js');
   assert.match(src, /function escape\(\) \{\s*var game = window\.OTBShellGame;\s*if \(game && game\.on && game\.on\(\)\) close\(\);/);

package/tests/page_notes_panel.mjs

@@ -41,7 +41,7 @@ function node(tag, id, cls) {
 }
 function all(root) { return root.children.flatMap((c) => [c, ...all(c)]); }
 
-function boot({ session = {}, search = '' } = {}) {
+function boot({ session = {}, search = '', embedded = false } = {}) {
   const sidebar = node('NAV', 'app-sidebar');
   const topbar = node('DIV', 'app-topbar');
   const side = topbar.appendChild(node('DIV', '', 'topbar-side'));
@@ -61,6 +61,7 @@ function boot({ session = {}, search = '' } = {}) {
   const mk = (obj) => ({ getItem: (k) => (k in obj ? obj[k] : null), setItem: (k, v) => { obj[k] = String(v); }, removeItem: (k) => { delete obj[k]; } });
   const opened = [];
   const window = { OTB: realOTB(), localStorage: mk({}), sessionStorage: mk(session), matchMedia: () => ({ matches: false }), location: { search } };
+  if (embedded) window.OTBShellGame = { embedded: () => true };
   // "Loading" page-notes.js: record the tag, then define the API it would define.
   head.onAppend = (tag) => {
     loaded.push(tag.src);
@@ -94,6 +95,13 @@ test('THE PANEL: docked at the edge in Artist alone, with no top-bar button, and
   assert.deepEqual(none.loaded, [], 'and nothing loads');
 });
 
+test('a screen in the options menu frame docks no second panel: the menu around it has one', async () => {
+  const p = boot({ session: { 'hall-craft': 'artist' }, embedded: true });
+  await flush();
+  assert.deepEqual(p.opened, [], 'no dock inside the frame');
+  assert.deepEqual(p.loaded, [], 'and the panel script never loads there');
+});
+
 test('the panel script loads once, at the same version as craft-mode.js', async () => {
   const p = boot({ session: { 'hall-craft': 'artist' } });
   await flush();

package/tests/shell_stat_portability.mjs

@@ -47,3 +47,37 @@ test('the rule catches a lone GNU or BSD stat, and passes the paired form and pr
   assert.equal(offending('U=$(stat -c %U "$d" 2>/dev/null || stat -f %Su "$d" 2>/dev/null)').length, 0);
   assert.equal(offending("  # was stat -c '%s', which BSD refuses").length, 0, 'a comment is not a call');
 });
+
+// --- `head -n -K` — the same bug, a different GNU extension (task 1005096) ------------
+//
+// `head -n -K` means "all but the last K" to GNU and is an ERROR to BSD/macOS head
+// ("illegal line count", exit 1). wedge-remedy.js's disk-full prune used it, so on a Mac
+// the pipeline deleted nothing and the test that runs that command for real could never
+// pass. The command itself runs on a Linux box — but a builder builds wherever they are,
+// so a one-dialect idiom still reds their suite. POSIX awk answers it everywhere:
+//   … | sort | awk -v k=K '{a[NR]=$0} END{for(i=1;i<=NR-k;i++) print a[i]}'
+//
+// Scanned in the .js files too, not only *.sh: this one lived inside a shell string a
+// Node script builds, which the stat scan above would never have seen.
+const GNU_HEAD = /(^|[^\w-])head\s+(-n\s*-\d|--lines[\s=]-\d|-\s*-\d)/;
+
+test('no tracked script asks for `head -n -K`, which BSD/macOS head refuses', () => {
+  const files = execFileSync('git', ['ls-files', '*.sh', 'scripts/*.js', 'scripts/**/*.js'], { cwd: ROOT, encoding: 'utf8' })
+    .split('\n').filter(Boolean);
+  assert.ok(files.length > 20, `the scan must see the scripts, got ${files.length}`);
+  const hits = files.flatMap((f) => fs.readFileSync(path.join(ROOT, f), 'utf8')
+    .split('\n').map((l, i) => ({ n: i + 1, l }))
+    .filter(({ l }) => !/^\s*(#|\/\/)/.test(l) && GNU_HEAD.test(l))
+    .map(({ n, l }) => `${f}:${n}: ${l.trim()}`));
+  assert.deepEqual(hits, [], "all but the last K: sort | awk -v k=K '{a[NR]=$0} END{for(i=1;i<=NR-k;i++) print a[i]}'");
+});
+
+test('the head rule catches the GNU forms and leaves an ordinary head alone', () => {
+  const hit = (s) => GNU_HEAD.test(s);
+  assert.equal(hit("… | head -n -7 | xargs rm -f --"), true);
+  assert.equal(hit('… | head -n-7'), true);
+  assert.equal(hit('… | head --lines=-7'), true);
+  assert.equal(hit('… | head -n 7'), false, 'the ordinary form is portable');
+  assert.equal(hit('… | head -7'), false);
+  assert.equal(hit('git log | head -n 20'), false);
+});

package/tests/ship_vendored_instance.mjs

@@ -76,7 +76,11 @@ function writeFile(p, body) {
 
 // Build one fixture. `mainAt`: 'primary' | 'linked' | 'none'.
 function buildFixture(mainAt) {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), `bongos-vendored-${mainAt}-`));
+  // realpath'd (task 1005096): on a Mac os.tmpdir() is /var/folders/…, a symlink to
+  // /private/var/folders/…, and resolveRoots answers with git's own answer — the /private
+  // form. Comparing the two spellings failed on every Mac and passed on CI's Linux, which
+  // has no such link. The fixture names the path the code under test will name.
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `bongos-vendored-${mainAt}-`)));
   const origin = path.join(root, 'origin.git');
   const inst = path.join(root, 'instance');
   git(root, 'init', '--bare', '-b', 'main', origin);