@bongos/core 1.24.26 → 1.24.28

package/modules/hall-ui/public/update-pill.js

@@ -0,0 +1,623 @@
+// update-pill.js — the hall's Update pill: a newer core, taken in place (task 1005041).
+//
+// The owner, 2026-11-03: upgrading Bongos from a project's hall was "way too obstructing and
+// not obvious what to do", and it should feel like the Claude app, which just tells you to
+// restart. Before this, a hosted project's owner met a full-width banner, went to Settings,
+// pressed Update, landed on the hub's deploy door on another site, pressed Check, then
+// Confirm, then waited there. Now it is one control in the top bar, in four faces:
+//   ready    "Update". Pressing it opens a small card: what the update brings, how long it
+//            takes, that it puts itself back if it goes wrong, and one Update now button.
+//   running  "Updating…", and the card says where it has got to.
+//   done     "Reload". The Claude moment: the new version is running, this page is not.
+//   held     the newest version was tried here and rolled back; the card says so plainly.
+//
+// TWO STEPS, STILL (ADR 0293 D4). Opening the card is step one: it names the version that
+// would go in. Update now is step two and sends THAT version. `offered` is read off the
+// reading the card was drawn from, so a release that lands while the card is open cannot
+// change what the press does.
+//
+// WHERE THE ACT HAPPENS IS UNCHANGED (ADR 0293 D1, ADR 0339 D3). The server names this
+// project's door (GET /software-update `door`), and doorPlan() reads it:
+//   local  this hall runs the door (the platform): it calls its own core-upgrade route.
+//   hub    a hosted project: the act stays on the hub. A small hub window opens on the door
+//          with &handoff=1, this page tells it the version over postMessage, and the hub
+//          posts the move with the owner's OWN hub session (deploy-handoff.js). This
+//          project's server gains no capability; the only thing that crosses is a version.
+//   ask    a hosted project the hub's operator runs: "Ask for this update" (task 1004595).
+//   cli    a self-hosted instance: no button; the card names the command.
+//
+// PROGRESS IS READ, NEVER GUESSED (deploy.js's rule). The page watches its own public
+// /version: still the old version is "starting", no answer is "restarting", the new one is
+// done. A rollback is the server's upgrade hold naming the version (GET /core-update `held`).
+// The run is remembered in this browser, so it follows the owner from page to page and a
+// reload in the middle picks it up again.
+//
+// Its own file, loaded by shell.js only when there is something to say (shell.js is at its
+// 1,500-line ratchet), and by settings.html, whose Update button runs the same flow.
+// Node-require-safe (github-chip.js's tail), so the tests run the pure half without a page.
+(function (root) {
+  'use strict';
+
+  var RUN_KEY = 'bongos.update.run';
+  var MSG = 'bongos-update'; // the tag deploy-handoff.js answers to; both sides check it
+  var VERSION_RE = /^\d+\.\d+\.\d+$/;
+  // A hub door as the server words it (core-update.js HUB_UPGRADE_URL_RE's shape): an
+  // origin and /deploy?project=<slug>, nothing else. Anything else draws no button.
+  var HUB_DOOR_RE = /^(https?:\/\/[^\s"'<>/]+)\/deploy\?project=[A-Za-z0-9._%-]+$/;
+  var SETTINGS_HREF = '/settings#software-update';
+  var HIGHLIGHTS = 3;
+  var LINE_MAX = 120;
+  // The runner drains on a two-minute tick, then installs, migrates, restarts and checks
+  // health. Past SLOW_MS the card says it is taking longer than usual; past GIVE_UP_MS a
+  // remembered run is forgotten (the Settings history still has it).
+  var SLOW_MS = 8 * 60 * 1000;
+  var GIVE_UP_MS = 45 * 60 * 1000;
+  // How long a closed hub window is given to show that the update started anyway, for the
+  // case where the window could not talk back (its own one-press fallback was used).
+  var UNHEARD_MS = 4 * 60 * 1000;
+  var HOLD_EVERY = 5; // the hold is asked for on every fifth look, /version on every one
+  function num(v, dflt) { return typeof v === 'number' && isFinite(v) ? v : dflt; }
+  // A harness drives the loop without sleeping through it (deploy.js's __deployPollMs).
+  var POLL_MS = num(root && root.__updatePollMs, 4000);
+
+  // ---------- the pure half ----------
+
+  function isVersion(v) { return typeof v === 'string' && VERSION_RE.test(v); }
+
+  // Voice rule V4 (docs/voice.md): a release-note line is quoted ledger data, so its dashes
+  // become commas at render, the way settings-software-update.js does it.
+  function unDash(raw) {
+    return String(raw == null ? '' : raw).replace(/\s*[—–]\s*/g, ', ').replace(/,\s*,/g, ',').trim();
+  }
+  function clip(s) {
+    if (s.length <= LINE_MAX) return s;
+    var cut = s.slice(0, LINE_MAX - 1);
+    var space = cut.lastIndexOf(' ');
+    return (space > LINE_MAX / 2 ? cut.slice(0, space) : cut).replace(/[,;:.\s]+$/, '') + '…';
+  }
+
+  /** What the update brings, from GET /software-update's `whats_new`: the first few lines,
+   *  newest first, and how many there are. `more` is true when older versions were left out
+   *  of the reading, so the count is a floor. */
+  function highlights(whatsNew, n) {
+    var w = whatsNew || {};
+    var versions = Array.isArray(w.versions) ? w.versions : [];
+    var lines = [];
+    var count = 0;
+    for (var i = 0; i < versions.length; i++) {
+      var entries = versions[i] && Array.isArray(versions[i].entries) ? versions[i].entries : [];
+      for (var j = 0; j < entries.length; j++) {
+        var t = unDash(entries[j] && entries[j].text);
+        if (!t) continue;
+        count++;
+        if (lines.length < n) lines.push(clip(t));
+      }
+    }
+    return { lines: lines, count: count, more: !!w.more, read: w.ok !== false && versions.length > 0 };
+  }
+
+  /** Where Update now goes, from GET /software-update. Same rules as the Settings panel:
+   *  no button for a viewer the door would refuse, and only a known door shape is used. */
+  function doorPlan(sw) {
+    if (!sw || sw.can_update !== true) return { kind: 'none' };
+    var door = sw.door || {};
+    var ask = sw.ask || {};
+    if (door.kind === 'local' && door.url === '/deploy') return { kind: 'local' };
+    if (door.kind === 'hub') {
+      var m = HUB_DOOR_RE.exec(String(door.url || ''));
+      if (!m) return ask.available ? { kind: 'ask' } : { kind: 'none' };
+      return { kind: 'hub', url: door.url, origin: m[1] };
+    }
+    if (door.kind === 'cli') return ask.available ? { kind: 'ask' } : { kind: 'cli' };
+    return { kind: 'none' };
+  }
+
+  /** The run this browser remembers: { to, from, at, via }, or null. Every touch is guarded,
+   *  because storage throws in a private window and is absent in a vm. */
+  function readRun(storage, now) {
+    var run = null;
+    try { run = JSON.parse((storage && storage.getItem(RUN_KEY)) || 'null'); } catch (e) { run = null; }
+    if (!run || !isVersion(run.to) || !isFinite(run.at)) return null;
+    if (now - run.at > GIVE_UP_MS) { forgetRun(storage); return null; }
+    return run;
+  }
+  function keepRun(storage, run) {
+    try { if (storage) storage.setItem(RUN_KEY, JSON.stringify(run)); } catch (e) { /* this page still watches */ }
+  }
+  function forgetRun(storage) {
+    try { if (storage) storage.removeItem(RUN_KEY); } catch (e) { /* best-effort */ }
+  }
+
+  /** Which face the pill shows when a page loads, from GET /core-update and the remembered
+   *  run. A run whose version this server already runs has landed (the page that loaded IS
+   *  the new version), so there is nothing to say; the one-time what's-new note says it. */
+  function pillState(o) {
+    var u = (o && o.update) || {};
+    var run = o && o.run;
+    var held = o && o.held;
+    if (run) return u.running === run.to ? 'landed' : 'running';
+    if (held && isVersion(held.version) && held.version === u.latest) return 'held';
+    // "Behind" is said only from an answer (shell.js's old banner rule): a registry that did
+    // not answer is not "up to date", and it is not "update ready" either.
+    if (u.reading === 'ok' && u.behind && isVersion(u.latest)) return 'ready';
+    return 'none';
+  }
+
+  /** One look folded into the run's stage. `look.version` is what /version said, or null
+   *  when the server did not answer; `look.held` is the held version when it was asked. */
+  function stageOf(run, look, now) {
+    if (look.version === run.to) return 'done';
+    if (look.held && look.held === run.to) return 'failed';
+    var slow = now - run.at > SLOW_MS;
+    if (look.version === null || run.down) return slow ? 'slow' : 'restarting';
+    return slow ? 'slow' : 'starting';
+  }
+
+  // ---------- the page half ----------
+
+  var state = {
+    api: null, update: null, held: null, sw: null, swAsked: null, swError: null, ended: null, note: null,
+    face: 'none', stage: null, run: null, error: null, pill: null, card: null,
+    popup: null, plan: null, offered: null, looks: 0, timer: null, popupTimer: null, listening: false,
+  };
+
+  function doc() { return root && root.document; }
+  function store() { try { return root && root.localStorage; } catch (e) { return null; } }
+  function now() { return Date.now(); }
+  function esc(s) { return root.OTB.escapeHtml(String(s == null ? '' : s)); }
+  function mono(v) { return '<span class="upd-ver">' + esc(v) + '</span>'; }
+
+  var DOT = '<span class="upd-pill__dot" aria-hidden="true"></span>';
+  var SPIN = '<span class="upd-pill__spin" aria-hidden="true"></span>';
+  var FACES = {
+    ready: { label: 'Update', title: 'A new version of Bongos is ready', lead: DOT },
+    held: { label: 'Update held', title: 'The newest version did not go in here', lead: DOT },
+    running: { label: 'Updating…', title: 'Bongos is updating', lead: SPIN },
+    done: { label: 'Reload', title: 'Bongos is updated. Reload to use it', lead: DOT },
+  };
+
+  function drawPill() {
+    var d = doc();
+    var face = FACES[state.face];
+    if (!d || !face) { if (state.pill) state.pill.remove(); state.pill = null; return; }
+    var side = d.querySelector && d.querySelector('#app-topbar .topbar-side');
+    if (!state.pill) {
+      if (!side) return;
+      var b = d.createElement('button');
+      b.type = 'button';
+      b.id = 'upd-pill';
+      b.className = 'upd-pill';
+      b.setAttribute('aria-haspopup', 'dialog');
+      b.setAttribute('aria-expanded', 'false');
+      b.setAttribute('aria-controls', 'upd-card');
+      b.addEventListener('click', function () {
+        if (state.face === 'done') { reload(); return; }
+        toggleCard();
+      });
+      side.insertBefore(b, side.firstChild);
+      state.pill = b;
+    }
+    state.pill.setAttribute('data-face', state.face);
+    state.pill.title = face.title;
+    state.pill.setAttribute('aria-label', face.title);
+    state.pill.innerHTML = face.lead + '<span class="upd-pill__label">' + face.label + '</span>';
+  }
+
+  function cardHtml(face) {
+    var u = state.update || {};
+    var close = '<button type="button" class="upd-card__close" id="upd-close" aria-label="Close">×</button>';
+    var run = state.run || state.ended;
+    var from = run ? run.from : u.running;
+    var to = run ? run.to : state.offered;
+    var versions = isVersion(from) && isVersion(to) ? '<p class="upd-card__ver">' + mono(from) + ' → ' + mono(to) + '</p>' : '';
+    var err = (state.error ? '<p class="upd-card__err" role="alert">' + esc(state.error) + '</p>' : '') +
+      (state.note ? '<p role="status">' + esc(state.note) + '</p>' : '');
+
+    if (face === 'held') {
+      var msg = (state.held && state.held.message) || ('Version ' + (state.held && state.held.version) + ' was tried on this project and rolled back. It is still on ' + (u.running || 'its current version') + ' and working.');
+      return close + '<h2 class="upd-card__h" id="upd-card-h">The newest version did not go in</h2>' +
+        '<p>' + esc(msg) + '</p><p class="upd-card__note">Nothing needs doing. The next version will be offered here when it is out.</p>' +
+        '<div class="upd-card__actions"><a class="upd-btn" href="' + SETTINGS_HREF + '">Details</a></div>';
+    }
+    if (face === 'running') {
+      var words = {
+        starting: 'Starting. The update begins within two minutes.',
+        restarting: 'Installing and restarting. This hall may stop answering for a moment.',
+        slow: 'This is taking longer than usual. It keeps going on its own.',
+        unheard: 'Checking that the update started…',
+      };
+      return close + '<h2 class="upd-card__h" id="upd-card-h">Updating Bongos</h2>' +
+        '<div class="upd-track" aria-hidden="true"><span></span></div>' +
+        '<p role="status">' + esc(words[state.stage] || words.starting) + '</p>' + versions +
+        '<p class="upd-card__note">You can keep working or close this card. The button up top says when it is done.</p>' +
+        (state.stage === 'slow' ? '<div class="upd-card__actions"><a class="upd-btn" href="' + SETTINGS_HREF + '">See where it got to</a></div>' : '');
+    }
+    if (face === 'done') {
+      return close + '<h2 class="upd-card__h" id="upd-card-h">Bongos is updated</h2>' +
+        '<p role="status">Reload to start using version ' + esc(to) + '.</p>' +
+        '<div class="upd-card__actions"><button type="button" class="upd-btn upd-btn--go" id="upd-reload">Reload</button></div>';
+    }
+    if (face === 'failed') {
+      return close + '<h2 class="upd-card__h" id="upd-card-h">The update did not go in</h2>' +
+        '<p role="status">The new version was not healthy, so this project went back to ' + esc(from) + '. It is working.</p>' +
+        '<div class="upd-card__actions"><a class="upd-btn" href="' + SETTINGS_HREF + '">Details</a></div>';
+    }
+    // ready
+    if (!state.sw) {
+      return close + '<h2 class="upd-card__h" id="upd-card-h">A new version of Bongos is ready</h2>' +
+        (state.swError ? '<p class="upd-card__err" role="alert">Could not read what it brings: ' + esc(state.swError) + '.</p>'
+          : '<p class="upd-card__note" role="status">Reading what it brings…</p>') + versions;
+    }
+    var h = highlights((state.sw.update || {}).whats_new, HIGHLIGHTS);
+    var brings = '';
+    if (h.lines.length) {
+      var lead = h.count > h.lines.length ? (h.more ? 'More than ' : '') + h.count + ' improvements, including:' : (h.count === 1 ? 'One improvement:' : h.count + ' improvements:');
+      brings = '<p>' + esc(lead) + '</p><ul class="upd-card__list">' + h.lines.map(function (l) { return '<li>' + esc(l) + '</li>'; }).join('') + '</ul>';
+    }
+    var plan = doorPlan(state.sw);
+    var action = '';
+    var note = '';
+    if (plan.kind === 'local' || plan.kind === 'hub') {
+      var host = '';
+      if (plan.kind === 'hub') { try { host = new URL(plan.origin).host; } catch (e) { host = ''; } }
+      note = '<p class="upd-card__note">Takes a few minutes. The project restarts once, and goes back to the version it runs now on its own if the new one is not healthy.' +
+        (host ? ' A small window from ' + esc(host) + ' opens for a moment to start it.' : '') + '</p>';
+      action = '<button type="button" class="upd-btn upd-btn--go" id="upd-go">Update now</button>';
+    } else if (plan.kind === 'ask') {
+      var ask = state.sw.ask || {};
+      var team = ask.hub_host ? 'the team at ' + ask.hub_host : 'the team that runs this project\'s server';
+      var asked = ask.requested && ask.requested.version === state.offered;
+      note = '<p class="upd-card__note">' + esc(asked ? 'You asked ' + team + ' for this update. This shows the new version once it is installed.'
+        : 'This project runs on a server that ' + team + ' looks after, so they install its updates.') + '</p>';
+      if (!asked) action = '<button type="button" class="upd-btn upd-btn--go" id="upd-ask">Ask for this update</button>';
+    } else if (plan.kind === 'cli') {
+      note = '<p class="upd-card__note">This project is updated on the server that runs it: <code>bongos upgrade</code> there takes this version, and puts the old one back if it fails.</p>';
+    } else {
+      note = '<p class="upd-card__note">Only the people allowed to update this project can start it.</p>';
+    }
+    return close + '<h2 class="upd-card__h" id="upd-card-h">A new version of Bongos is ready</h2>' + brings + note + versions + err +
+      '<div class="upd-card__actions">' + action + '<a class="upd-btn" href="' + SETTINGS_HREF + '">What\'s new</a></div>';
+  }
+
+  // The card's own face: the pill's, except a rollback seen on this page, which the card
+  // tells as what just happened while the pill settles on "Update held".
+  function cardFace() { return state.face === 'held' && state.stage === 'failed' ? 'failed' : state.face; }
+
+  function drawCard() {
+    if (!doc() || !state.card) return;
+    state.card.innerHTML = cardHtml(cardFace());
+    wireCard();
+  }
+
+  function wireCard() {
+    var c = state.card;
+    var on = function (id, fn) { var el = c.querySelector('#' + id); if (el) el.addEventListener('click', fn); };
+    on('upd-close', closeCard);
+    on('upd-go', function () { updateNow(); });
+    on('upd-ask', function (e) { askForIt(e.currentTarget); });
+    on('upd-reload', reload);
+    on('upd-open', function () { updateNow(); });
+  }
+
+  // Under the pill, its left edge on the pill's, pulled in where that would run off the
+  // right of the window. On a phone the sheet's own rule (16px each side) wins.
+  function placeCard() {
+    if (!state.card || !state.pill || !state.pill.getBoundingClientRect) return;
+    var r = state.pill.getBoundingClientRect();
+    var s = state.card.style;
+    s.top = Math.round(r.bottom + 8) + 'px';
+    var vw = root.innerWidth || 0;
+    if (vw <= 640) { s.left = ''; s.right = ''; return; }
+    var width = Math.min(360, vw - 32);
+    s.left = Math.round(Math.max(16, Math.min(r.left, vw - width - 16))) + 'px';
+    s.right = 'auto';
+  }
+
+  function openCard() {
+    var d = doc();
+    if (!d) return;
+    if (!state.card) {
+      var c = d.createElement('div');
+      c.id = 'upd-card';
+      c.className = 'upd-card';
+      c.setAttribute('role', 'dialog');
+      c.setAttribute('aria-labelledby', 'upd-card-h');
+      d.body.appendChild(c);
+      state.card = c;
+      if (root.addEventListener) root.addEventListener('resize', function () { if (state.card && !state.card.hidden) placeCard(); });
+      d.addEventListener('keydown', function (e) { if (e.key === 'Escape' && state.card && !state.card.hidden) { closeCard(); if (state.pill) state.pill.focus(); } });
+      d.addEventListener('click', function (e) {
+        if (!state.card || state.card.hidden) return;
+        var t = e.target;
+        if (state.card.contains(t) || (state.pill && state.pill.contains(t))) return;
+        closeCard();
+      });
+    }
+    state.card.hidden = false;
+    if (state.pill) state.pill.setAttribute('aria-expanded', 'true');
+    placeCard();
+    drawCard();
+    var first = state.card.querySelector('.upd-btn--go') || state.card.querySelector('#upd-close');
+    if (first && first.focus) first.focus();
+    if (state.face === 'ready') readSoftwareUpdate();
+  }
+  function closeCard() {
+    if (state.card) state.card.hidden = true;
+    if (state.pill) state.pill.setAttribute('aria-expanded', 'false');
+  }
+  function toggleCard() { if (state.card && !state.card.hidden) closeCard(); else openCard(); }
+
+  function setFace(face) {
+    state.face = face;
+    drawPill();
+    if (state.card && !state.card.hidden) drawCard();
+  }
+
+  // The card's details, read on first open: an update's notes come out of the newer
+  // package's download, and most page loads never open the card.
+  function readSoftwareUpdate() {
+    if (state.sw || state.swAsked) return state.swAsked;
+    state.swError = null;
+    state.swAsked = state.api.request('GET', '/api/bongos/software-update').then(function (res) {
+      if (!res || !res.ok || !res.data) throw new Error((res && res.data && res.data.error && res.data.error.message) || 'HTTP ' + (res && res.status));
+      takeReading(res.data);
+    }).then(null, function (e) {
+      state.swAsked = null;
+      state.swError = String((e && e.message) || 'no answer').replace(/\.$/, '');
+      if (state.card && !state.card.hidden) drawCard();
+    });
+    return state.swAsked;
+  }
+  function takeReading(sw) {
+    state.sw = sw;
+    var u = sw && sw.update;
+    // The version this card offers is the Settings reading's own `offered` (the same channel
+    // rule the banner read applies), and only ever one the server named.
+    if (u && u.reading === 'ok' && isVersion(u.offered)) state.offered = u.offered;
+    if (state.card && !state.card.hidden) drawCard();
+  }
+
+  function fail(message) {
+    state.error = message;
+    if (state.face === 'running' && !state.run) state.face = 'ready';
+    setFace(state.face);
+    if (!state.card || state.card.hidden) openCard();
+  }
+
+  /** Step two. Synchronous up to window.open, which a browser allows only inside the press. */
+  function updateNow(sw) {
+    if (sw) takeReading(sw);
+    state.error = null;
+    state.note = null;
+    var to = state.offered;
+    var plan = doorPlan(state.sw);
+    if (!isVersion(to) || (plan.kind !== 'local' && plan.kind !== 'hub')) return false;
+    state.plan = plan;
+    if (plan.kind === 'hub') {
+      var w = root.open(plan.url + '&handoff=1', 'bongos-update', 'popup=yes,width=460,height=620');
+      if (!w) {
+        state.error = 'Your browser blocked the update window.';
+        if (!state.card || state.card.hidden) openCard(); else drawCard();
+        var go = state.card && state.card.querySelector('#upd-go');
+        if (go) { go.id = 'upd-open'; go.textContent = 'Open the update window'; wireCard(); }
+        return false;
+      }
+      state.popup = w;
+      listen();
+      state.stage = 'starting';
+      setFace('running');
+      watchPopup();
+      return true;
+    }
+    state.stage = 'starting';
+    setFace('running');
+    startLocal(to);
+    return true;
+  }
+
+  // The platform's own hall runs the door itself: the same two calls deploy.js makes, with
+  // the version this card showed. A preview that names a different version (a release landed
+  // in between, or the door's own reading is a few minutes behind the registry's) is never
+  // sent: the card names the door's version instead, and the next press takes THAT one, as
+  // the hub's window does. Shown, then confirmed; never swapped under the owner.
+  function startLocal(to) {
+    var api = state.api;
+    api.request('GET', '/api/bongos/provisioning/control-plane').then(function (res) {
+      var p = res && res.ok && res.data && res.data.preview;
+      if (!p || !p.instance_id) throw new Error(errorOf(res, 'This platform has no update door yet.'));
+      if (p.recommended_version !== to) {
+        if (!isVersion(p.recommended_version)) throw new Error('This platform\'s update door has no version to offer just now.');
+        state.offered = p.recommended_version;
+        state.note = 'The update door offers version ' + p.recommended_version + ', not the one shown before. Update now takes ' + p.recommended_version + '.';
+        state.face = 'ready';
+        setFace('ready');
+        if (!state.card || state.card.hidden) openCard();
+        return null;
+      }
+      return api.request('POST', '/api/bongos/provisioning/instances/' + encodeURIComponent(p.instance_id) + '/core-upgrade', { body: { to: to } });
+    }).then(function (res) {
+      if (res === null) return;
+      if (!res || !res.ok) throw new Error(errorOf(res, 'The update could not be started.'));
+      begin(to);
+    }).then(null, function (e) { fail(String((e && e.message) || 'The update could not be started.')); });
+  }
+  // The server's own sentence when it wrote one; its refusals say what to do instead.
+  function errorOf(res, fallback) {
+    var err = (res && res.data && res.data.error) || {};
+    return err.message && err.message !== err.code ? err.message : (res && res.status ? fallback + ' (' + res.status + ')' : fallback);
+  }
+
+  // ---------- the hub window ----------
+
+  function listen() {
+    if (state.listening || !root.addEventListener) return;
+    state.listening = true;
+    root.addEventListener('message', onMessage);
+  }
+  /** Only the window this page opened, on the hub's origin, speaking this protocol. */
+  function onMessage(e) {
+    var plan = state.plan;
+    if (!plan || plan.kind !== 'hub' || !state.popup || e.source !== state.popup || e.origin !== plan.origin) return;
+    var m = e.data;
+    if (!m || m.tag !== MSG) return;
+    if (m.step === 'ready') {
+      state.popup.postMessage({ tag: MSG, step: 'go', to: state.offered }, plan.origin);
+    } else if (m.step === 'started' && m.to === state.offered) {
+      begin(state.offered);
+    } else if (m.step === 'refused') {
+      stopPopupWatch();
+      fail(typeof m.message === 'string' && m.message ? m.message.slice(0, 400) : 'The update was refused.');
+    }
+  }
+  // A window closed before it said "started". If it could not talk back at all (a browser
+  // that cuts the link between the two windows), the owner may still have pressed its own
+  // button, so the page watches for a short while before saying it did not start.
+  function watchPopup() {
+    stopPopupWatch();
+    state.popupTimer = root.setInterval(function () {
+      var w = state.popup;
+      if (state.run) { stopPopupWatch(); return; }
+      if (w && !w.closed) return;
+      stopPopupWatch();
+      if (state.face !== 'running') return;
+      state.stage = 'unheard';
+      begin(state.offered, { unheard: true });
+    }, 700);
+  }
+  function stopPopupWatch() {
+    if (state.popupTimer) root.clearInterval(state.popupTimer);
+    state.popupTimer = null;
+  }
+
+  // ---------- watching it go in ----------
+
+  function begin(to, opts) {
+    var u = state.update || {};
+    stopPopupWatch();
+    var unheard = !!(opts && opts.unheard);
+    state.run = { to: to, from: u.running || null, at: now(), via: state.plan ? state.plan.kind : null, unheard: unheard };
+    if (!unheard) keepRun(store(), state.run);
+    state.stage = unheard ? 'unheard' : 'starting';
+    setFace('running');
+    schedule();
+  }
+
+  function schedule() {
+    if (state.timer) root.clearTimeout(state.timer);
+    state.timer = root.setTimeout(look, POLL_MS);
+  }
+
+  function look() {
+    state.timer = null;
+    var run = state.run;
+    if (!run) return;
+    state.looks++;
+    var askHold = state.looks % HOLD_EVERY === 0;
+    var version = root.fetch('/version', { cache: 'no-store', credentials: 'same-origin' }).then(function (r) {
+      return r && r.ok ? r.json().then(function (j) { return j && isVersion(j.coreVersion) ? j.coreVersion : null; }) : null;
+    }).then(null, function () { return null; });
+    var held = askHold ? state.api.request('GET', '/api/bongos/core-update').then(function (res) {
+      return res && res.status === 200 && res.data && res.data.held ? res.data.held.version : null;
+    }, function () { return null; }) : null;
+    Promise.all([version, held]).then(function (got) {
+      if (state.run !== run) return;
+      var v = got[0];
+      if (v === null) run.down = true;
+      var stage = stageOf(run, { version: v, held: got[1] }, now());
+      if (run.unheard) {
+        // Nothing heard from the window: the first sign of movement makes it a real run;
+        // no sign at all inside UNHEARD_MS means it did not start.
+        if (stage === 'starting' || stage === 'slow') {
+          if (now() - run.at > UNHEARD_MS) {
+            state.run = null;
+            fail('The update window closed before the update started.');
+            return;
+          }
+          stage = 'unheard';
+        } else if (stage !== 'done' && stage !== 'failed') {
+          run.unheard = false;
+          keepRun(store(), run);
+        }
+      }
+      state.stage = stage;
+      if (stage === 'done' || stage === 'failed') {
+        forgetRun(store());
+        state.run = null;
+        state.ended = { to: run.to, from: run.from };
+        if (stage === 'failed') {
+          // The hold now names this version, so the pill stays as "Update held" and the
+          // card says what happened, once, without being asked.
+          state.held = { version: run.to };
+          setFace('held');
+          if (!state.card || state.card.hidden) openCard();
+          return;
+        }
+        setFace('done');
+        return;
+      }
+      setFace('running');
+      schedule();
+    });
+  }
+
+  function reload() {
+    forgetRun(store());
+    if (root.location && root.location.reload) root.location.reload();
+  }
+
+  // "Ask for this update" (task 1004595): one press reaches the people who run the server.
+  function askForIt(btn) {
+    btn.disabled = true;
+    btn.textContent = 'Asking…';
+    state.api.request('POST', '/api/bongos/software-update/request', { body: {} }).then(function (res) {
+      var data = (res && res.data) || {};
+      var request = data.request || (data.error && data.error.details && data.error.details.request);
+      if (!((res.ok || res.status === 429) && request)) throw new Error(errorOf(res, 'Could not send the request.'));
+      state.sw.ask = Object.assign({}, state.sw.ask, { requested: request });
+      drawCard();
+    }).then(null, function (e) {
+      state.error = String((e && e.message) || 'Could not send the request.');
+      drawCard();
+    });
+  }
+
+  /** shell.js hands over GET /core-update's answer; the pill decides what, if anything, to show. */
+  function mount(data, opts) {
+    state.api = opts && opts.api;
+    if (!state.api || !root.document) return null;
+    var d = data || {};
+    state.update = d.update || null;
+    state.held = d.held || null;
+    if (state.update && isVersion(state.update.latest) && !state.offered) state.offered = state.update.latest;
+    var run = readRun(store(), now());
+    var face = pillState({ update: state.update, held: state.held, run: run });
+    if (face === 'landed') { forgetRun(store()); face = 'none'; }
+    if (face === 'running') {
+      state.run = run;
+      state.offered = run.to;
+      state.stage = 'starting';
+    }
+    state.face = face;
+    drawPill();
+    if (face === 'running') schedule();
+    return face;
+  }
+
+  var api = {
+    mount: mount,
+    updateNow: function (sw, opts) {
+      if (opts && opts.api) state.api = opts.api;
+      if (!state.api) return false;
+      if (!state.update && sw && sw.update) state.update = { running: sw.update.running, latest: sw.update.offered, reading: sw.update.reading, behind: !!sw.update.offered };
+      if (!state.pill) { state.face = 'ready'; drawPill(); }
+      return updateNow(sw);
+    },
+    // the pure half, for the tests
+    highlights: highlights, doorPlan: doorPlan, pillState: pillState, stageOf: stageOf,
+    readRun: readRun, keepRun: keepRun, forgetRun: forgetRun, isVersion: isVersion,
+    RUN_KEY: RUN_KEY, MSG: MSG, SLOW_MS: SLOW_MS, GIVE_UP_MS: GIVE_UP_MS,
+    _state: state,
+  };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  if (root && !root.OTBUpdatePill) root.OTBUpdatePill = api;
+})(typeof window !== 'undefined' ? window : null);

package/modules/hall-ui/public/watch.html

@@ -168,7 +168,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-10-30-market-watch"></script>
-<script src="/builders/shell.js?v=2026-10-30-github-chip"></script>
+<script src="/builders/shell.js?v=2026-11-03-update-pill"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared component kit (window.OTBKit) — tabs, ledger, pager (task 2166). -->

package/modules/hall-ui/public/work.html

@@ -174,7 +174,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-10-30-market-watch"></script>
-<script src="/builders/shell.js?v=2026-10-30-github-chip"></script>
+<script src="/builders/shell.js?v=2026-11-03-update-pill"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- task 1004727: the ONE karma vote control every task/idea list renders -->