agentbox-app 0.1.7 → 0.1.12

package/main/ship-queue.mjs

@@ -0,0 +1,279 @@
+// THE APP SHIPS A TASK; THE AGENT ONLY SAYS IT IS READY (2026-10-02).
+//
+// Agents used to finish by pushing to main and updating the folder the app
+// runs from. Over thirty hours on one Mac, 17 tasks stalled because Claude
+// Code's auto-mode safety check refused one of those steps (a push to a public
+// repo, a fast-forward of another checkout, a rebase), 16 because a folder was
+// left mid-merge or committed into, 6 racing each other's pushes. A refusal is
+// final and asks nobody, so nothing reached the approvals corner; the task
+// just said "the permission check refused it" and waited.
+//
+// So for a project that turns this on, the agent stops at a branch: it commits
+// in its task folder, adds the label `ship` to its row, and ends its turn.
+// This queue then runs the project's own ship script, one task at a time
+// across the whole Mac, so two tasks never race. A failure goes back to the
+// agent that wrote the change, as a reply, with the script's own words.
+//
+// OFF UNLESS A PERSON TURNS IT ON. The setting lives in the app's own data
+// folder (`ship.json`), never in the store or the repo: agents can write
+// project files, and a ship command they could rewrite would be a command the
+// app runs for them outside every check. The script it names is run FROM THE
+// BASE CHECKOUT, which only ever fast-forwards to the remote, so a branch
+// cannot change the code that ships it. With no `ship.json`, nothing here does
+// anything at all.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Name } from '../shared/product-name.mjs';
+
+export const SHIP_LABEL = 'ship';
+const SHIP_MS = 20 * 60 * 1000;
+const KEEP = 4000;
+
+export const shipSettingsFile = (userDir) => path.join(userDir, 'ship.json');
+
+// WHICH "READY" EACH TASK HAS ALREADY BEEN SHIPPED FOR, by the moment its
+// label was written. Taking the label off is not enough: a label the person
+// put on outranks the app on the ledger, so the app's removal is ignored, and
+// on the first real run that shipped a task and then ran it twice more
+// (2026-10-02). A new label carries a new moment and ships again.
+const handledFile = (userDir) => path.join(userDir, 'ship-handled.json');
+const keyOf = (item) => `${item.product}/${item.id}`;
+const markedAt = (item) => item.wrote?.labels?.ts ?? item.updatedAt ?? 0;
+function readHandled(userDir) {
+  try { const raw = JSON.parse(fs.readFileSync(handledFile(userDir), 'utf8')); return raw && typeof raw === 'object' ? raw : {}; } catch { return {}; }
+}
+function writeHandled(userDir, all) {
+  try {
+    const tmp = `${handledFile(userDir)}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(all)}\n`);
+    fs.renameSync(tmp, handledFile(userDir));
+  } catch { /* the label removal still covers the ordinary case */ }
+}
+
+/** `{ [projectSlug]: { script: 'scripts/ship.mjs' } }`, or `{}`. */
+export function readShipSettings(userDir) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(shipSettingsFile(userDir), 'utf8'));
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The script that ships this project, inside its base checkout, or null. */
+export function shipScriptFor(product, settings) {
+  const rel = settings?.[product?.slug]?.script;
+  if (!product?.repoPath || typeof rel !== 'string' || !rel || path.isAbsolute(rel)) return null;
+  const base = path.resolve(product.repoPath);
+  const script = path.resolve(base, rel);
+  if (!script.startsWith(base + path.sep)) return null;
+  return fs.existsSync(script) ? script : null;
+}
+
+const labelsOf = (item) => (Array.isArray(item?.labels) ? item.labels : []);
+export const wantsShipping = (item) => labelsOf(item).includes(SHIP_LABEL);
+export const withoutShipLabel = (item) => labelsOf(item).filter((l) => l !== SHIP_LABEL);
+
+/**
+ * The next task to ship, oldest ask first, or null.
+ *
+ * Only a row of a project that ships, marked `ship`, with no session on it
+ * (an agent still working may yet commit), and with a task folder to ship from.
+ */
+export function nextToShip(items, products, settings, { isLive = () => false, folderFor, handled = {} }) {
+  const bySlug = new Map(products.map((p) => [p.slug, p]));
+  const ready = items
+    .filter((i) => wantsShipping(i) && i.status !== 'done' && !isLive(i) && !(markedAt(i) <= (handled[keyOf(i)] ?? -1)))
+    .map((item) => {
+      const product = bySlug.get(item.product);
+      const script = product ? shipScriptFor(product, settings) : null;
+      const cwd = script ? folderFor(item, product) : null;
+      return script && cwd && fs.existsSync(cwd) ? { item, product, script, cwd } : null;
+    })
+    .filter(Boolean);
+  ready.sort((a, b) => markedAt(a.item) - markedAt(b.item));
+  return ready[0] ?? null;
+}
+
+/** The commit the script reports, from its own `ship: shipped <sha>.` line. */
+export function shippedSha(output) {
+  return String(output ?? '').match(/ship: shipped ([0-9a-f]{7,40})\./)?.[1] ?? null;
+}
+
+// A LINE VITEST TICKED GREEN IS NEVER WHY A SHIP FAILED (w-c121bd85e6).
+//
+// Test files here are named after the behaviour they cover, so plenty of them
+// carry "failed", "error" or "refused" inside the name, with a hyphen either
+// side. A hyphen is a word boundary, so even the whole-word guard below
+// matches inside "a-failed-hook-is-visible-while-the-agent-continues". On
+// 2026-10-04 a ship that DIED was reported as that file, which had passed in
+// 51 milliseconds. Vitest ticks every file it ran green, so the tick is the
+// one reliable way to rule a line out.
+const TICKED_GREEN = /^[✓✔]/;
+// WHOLE WORDS (w-7ec8553e23): without \b, "red" matched inside "configured"
+// and a harmless warning the tests print was shown as why a ship failed.
+const NAMES_A_FAILURE = /\b(CONFLICT|error|red|refused|failed|FAIL)\b/i;
+// Vitest's heading over the list of failures, "⎯⎯⎯ Failed Tests 3 ⎯⎯⎯". It
+// carries the count and names nothing, and the FAIL lines that DO name
+// something are printed directly under it, so taking the first match showed
+// the heading and sent whoever read it to the GitHub run to find out which
+// three (w-c121bd85e6, this branch's own first ship). Passed over while there
+// is anything better, and still offered when it is all there is.
+const ONLY_A_COUNT = /^⎯+ .* ⎯+$/;
+// A LINE VITEST QUOTED IS NOT THE SCRIPT SPEAKING (w-560647d4db, five
+// bounces). A failing text assertion prints the file's own text as a diff, so
+// any source line carrying one of those words becomes a candidate — and the
+// diff is printed long before the runner's list of failures. Twice the note
+// read "+               than deleted: a bare corner here reads as a control
+// that failed", which is a pre-existing code comment in a file the branch
+// touched. It names no fault, and the real cause was three failing tests the
+// note never mentioned. Both shapes of quotation are skipped: a diff line
+// (`+`/`-`) and a code frame (`34|   expect(...)`).
+const QUOTED_SOURCE = /^([+-]|\d+\|)/;
+// THE RUNNER'S OWN FAILURES OUTRANK A LOOSE WORD MATCH. These two name a
+// file: `FAIL  tests/x.test.mjs > ...` and `❯ tests/x.test.mjs (3 tests | 3
+// failed)`. Anything else matching the words above — the script's closing
+// line, a merge message, a warning — says less, wherever it sits in the
+// output.
+const NAMES_A_RED_TEST = /^(FAIL\b|❯ .*\|\s*\d+ failed)/;
+// Vitest's totals, "Tests  3 failed | 1920 passed (1923)", and its heading
+// "⎯⎯⎯ Failed Tests 3 ⎯⎯⎯". Not "Test Files  1 failed", which counts files.
+const HOW_MANY = [/^Tests\s+(\d+) failed/, /Failed Tests\s+(\d+)/];
+
+const DIED = 'the test run died without naming a failing test';
+
+/**
+ * Why the branch did not ship, out of the script's own output.
+ *
+ * A run that went RED says so somewhere. A run that DIED — killed on a busy
+ * Mac, or cut off — leaves output with no failure in it at all, and the two
+ * have to be told apart: offering the nearest line instead sends whoever
+ * reads it after a fault that is not there.
+ *
+ * @returns {{ died: boolean, why: string|null, last: string|null, failed: number|null }}
+ */
+export function whyItDidNotShip(output) {
+  const lines = String(output ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const said = lines.filter((l) => !TICKED_GREEN.test(l) && !QUOTED_SOURCE.test(l));
+  const named = said.filter((l) => NAMES_A_FAILURE.test(l));
+  const red = named.find((l) => NAMES_A_RED_TEST.test(l));
+  const why = red ?? named.find((l) => !ONLY_A_COUNT.test(l)) ?? named[0] ?? null;
+  // The count goes with a line that names ONE test, so that it reads as the
+  // first of several rather than as the whole story. On a line that is not a
+  // test — a conflict, a refused push — a number beside it would read as that
+  // line's own count, so it is left off.
+  const counted = red ? Number(said.map((l) => HOW_MANY.map((re) => re.exec(l)?.[1]).find(Boolean)).find(Boolean)) : NaN;
+  return { died: !why, why, last: said.at(-1) ?? null, failed: Number.isFinite(counted) ? counted : null };
+}
+
+/** "3 tests failed, the first is FAIL tests/…", or just the line. */
+function diagnosis({ why, failed }) {
+  if (!why || !failed) return why;
+  return `${failed} test${failed === 1 ? '' : 's'} failed, the first is ${why}`;
+}
+
+/** What the agent is told when its branch did not ship. */
+export function failureReply(output) {
+  const tail = String(output ?? '').trim().slice(-KEEP);
+  const { died, ...rest } = whyItDidNotShip(output);
+  return [
+    `${Name} tried to ship your branch and it did not go out. Nothing was pushed.`,
+    // THE SAME DIAGNOSIS THE THREAD SHOWS, above the tail (w-560647d4db). The
+    // tail holds everything, which is why two sessions read a quoted code
+    // comment in it as the fault. One line naming how many tests failed and
+    // which file is where to start.
+    ...(died ? [] : ['', `It went red: ${diagnosis(rest)}`]),
+    ...(died ? [
+      '',
+      'Its test run DIED rather than going red: nothing it printed names a failing',
+      'test. Look for what killed the run. This computer runs a dozen agents at once, so',
+      'a worker that was starved or timed out is likelier than a bug in your change.',
+      'Run the tests for your change again before you go looking for one.',
+    ] : []),
+    '',
+    'Fix what the script says below in your task folder, commit, then add the label',
+    `\`${SHIP_LABEL}\` to this row again and end your turn. Do not push or touch any`,
+    'other folder yourself; the app ships it.',
+    '',
+    '```',
+    tail,
+    '```',
+  ].join('\n');
+}
+
+/** The line the thread shows: the app's own, short, and the first error in it. */
+export function failureNote(output) {
+  const { died, last, ...rest } = whyItDidNotShip(output);
+  const said = died ? `${DIED}. It last said: ${last ?? 'nothing at all'}` : diagnosis(rest);
+  return `It did not ship, and it went back to its agent: ${said.slice(0, 300)}`;
+}
+
+export function runScript(script, cwd, { timeout = SHIP_MS, env = process.env } = {}) {
+  const node = env.npm_node_execpath && fs.existsSync(env.npm_node_execpath) ? env.npm_node_execpath : 'node';
+  return new Promise((resolve) => {
+    let out = '';
+    let child;
+    try {
+      child = spawn(node, [script], { cwd, env: { ...env, GIT_TERMINAL_PROMPT: '0' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ code: 1, out: String(e?.message ?? e) });
+      return;
+    }
+    const keep = (b) => { out = (out + b).slice(-64 * 1024); };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const timer = setTimeout(() => { keep('\nship: stopped after 20 minutes.'); child.kill('SIGTERM'); }, timeout);
+    child.on('error', (e) => keep(`\n${e.message}`));
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code: code ?? 1, out }); });
+  });
+}
+
+/**
+ * One task at a time, for the whole Mac. `tick` is called from the
+ * supervisor's own tick and returns at once; the run happens beside it.
+ */
+export class ShipQueue {
+  constructor({ store, userDir, folderFor, isLive, handBack = () => {}, run = runScript, afterShip = () => {}, log = console }) {
+    Object.assign(this, { store, userDir, folderFor, isLive, handBack, run, afterShip, log });
+    this.busy = null;
+  }
+
+  tick(items, products) {
+    if (this.busy) return null;
+    const settings = readShipSettings(this.userDir);
+    if (!Object.keys(settings).length) return null;
+    const next = nextToShip(items, products, settings, { isLive: this.isLive, folderFor: this.folderFor, handled: readHandled(this.userDir) });
+    if (!next) return null;
+    // Marked handled only once the run has ENDED, pass or fail. Marked before
+    // it, a run cut off by an app restart was never tried again
+    // (w-f37a34def6, 2026-10-04). Within one app, `busy` already stops a
+    // second start; across a restart, trying again is the point.
+    const done = () => writeHandled(this.userDir, { ...readHandled(this.userDir), [keyOf(next.item)]: markedAt(next.item) });
+    this.busy = this.ship(next).then(done, done).finally(() => { this.busy = null; });
+    return this.busy;
+  }
+
+  async ship({ item, product, script, cwd }) {
+    this.log.info?.(`zero: shipping ${item.id} from ${cwd}`);
+    const { code, out } = await this.run(script, cwd);
+    try {
+      // Already on main: there is nothing to fix, so nobody is woken.
+      const already = /There is nothing to ship/.test(out);
+      if (code === 0 || already) {
+        this.store.shipped(product.slug, item.id, { sha: shippedSha(out), labels: withoutShipLabel(item) });
+        this.afterShip();
+      } else {
+        this.store.shipFailed(product.slug, item.id, { note: failureNote(out), labels: withoutShipLabel(item) });
+        // Straight back to the session that wrote the change. Not through the
+        // reply on the row: that field is hers, and the app's words written
+        // there would be drawn as hers and could not replace hers anyway.
+        this.handBack(item, failureReply(out));
+      }
+    } catch (e) {
+      this.log.warn?.(`zero: could not record the ship of ${item.id}:`, e.message);
+    }
+    return { code };
+  }
+}

package/main/sign-in-files.mjs

@@ -0,0 +1,39 @@
+// THE FILES A LOGIN WRITES, SO THE APP CAN SEE ONE LAND.
+//
+// A signed-out account used to sit out a fixed half hour, and nothing but a
+// session surviving on it could bring it back, which no session could do while
+// it sat out. So typing /login fixed nothing a person could see: their agents
+// stayed "Queued" until the half hour ran out on its own, and a /login and any
+// "continue" replies in between did nothing.
+//
+// A login rewrites these. Only their modification times are read, never their
+// contents: what is in them is her credentials and is none of our business.
+// A moved time is a reason to TRY again, not proof; the try is the proof.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Where one account's login is written.
+ *  - Claude Code, its default login: `~/.claude.json` (where the CLI keeps the
+ *    account it is signed in as) and the same files inside `~/.claude`.
+ *  - Claude Code, a CLAUDE_CONFIG_DIR: those files inside that folder.
+ *  - Codex: `auth.json` inside its CODEX_HOME.
+ */
+export function signInFiles({ engine = 'claude', folder = null, home }) {
+  if (engine === 'codex') return folder ? [path.join(folder, 'auth.json')] : [];
+  if (!folder) {
+    const dir = path.join(home, '.claude');
+    return [path.join(home, '.claude.json'), path.join(dir, '.claude.json'), path.join(dir, '.credentials.json')];
+  }
+  return [path.join(folder, '.claude.json'), path.join(folder, '.credentials.json')];
+}
+
+/** The newest modification time among them, or 0 when none can be read. */
+export function signInStamp(files, stat = fs.statSync) {
+  let newest = 0;
+  for (const f of files ?? []) {
+    try { newest = Math.max(newest, stat(f).mtimeMs); } catch {}
+  }
+  return newest;
+}

package/main/source-updater.mjs

@@ -0,0 +1,298 @@
+// A COPY RUN FROM SOURCE KEEPS ITSELF CURRENT TOO (w-7a39dace23, 2026-10-01).
+//
+// Teammates run the team build from a git checkout (docs/team/PLAN.md), and
+// main/updater.mjs cannot help them: electron-updater reads published releases
+// and does nothing at all unpackaged. Their updates are pushes to main, several
+// a day, so this watches the branch instead of a release feed.
+//
+// WHAT IT DOES. A few seconds after launch, and then every half hour, it runs
+// `git fetch` and asks whether the branch's upstream is ahead of the code this
+// process booted from. If it is, the state goes to `ready` and the sidebar
+// shows the "New version ready" card (renderer/src/components/SidebarUpdate.tsx),
+// which names what changed when pointed at.
+// Pressing Restart fast-forwards the folder, reinstalls packages only when
+// package.json or the lockfile changed, rebuilds the screens, and relaunches.
+// Nothing happens until that button is pressed.
+//
+// IT NEVER TOUCHES WORK SOMEBODY HAS NOT PUSHED. Four cases get no offer at
+// all, each stated in `error` so Settings can say why: a folder that is not a
+// checkout, a branch that follows nothing, tracked files with edits in them,
+// and a branch with commits of its own. The founder's own app runs from a
+// local branch with no upstream, so it is untouched by this. Untracked files
+// (zero.config.json, cloud/team.config.json) do not count as edits: they are
+// ignored or new, and a fast-forward cannot overwrite them without failing.
+//
+// "AHEAD OF WHAT IS RUNNING", NOT "AHEAD OF THE FOLDER". The code in memory is
+// what booted, so the folder brought up to date by hand without a restart is
+// still an update waiting, and the row says so.
+//
+// IF THE BUILD FAILS IT DOES NOT RESTART. The row comes back with what went
+// wrong, and pressing Restart again retries from where it stopped. Restarting
+// onto screens that did not build would be the one outcome worse than waiting.
+
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { describe } from './updater.mjs';
+
+const FIRST_CHECK_MS = 20_000;
+const EVERY_MS = 30 * 60 * 1000;
+const FETCH_MS = 60_000;
+const INSTALL_MS = 10 * 60 * 1000;
+const BUILD_MS = 5 * 60 * 1000;
+// How many change titles the row lists. The rest are counted, not named.
+const LISTED = 5;
+
+const SAY = {
+  notRepo: 'This folder is not a git checkout, so it does not update itself.',
+  noUpstream: 'This copy\'s branch does not follow a branch on GitHub, so it does not update itself.',
+  dirty: 'This folder has changes of your own in it, so it does not update itself.',
+  diverged: 'This copy has commits of its own, so it does not update itself.',
+  offline: 'Could not reach GitHub.',
+};
+
+// A FILE THE BUILD WRITES IS NOT AN EDIT OF HERS (2026-10-02). `npm run build`
+// rewrites shared/*.generated.mjs with the version and date of the Claude Code
+// on this Mac, and the restart below runs that build. Counted as her changes,
+// they made every update after the first say "changes of your own" for good
+// (tests/a-build-does-not-stop-the-next-update.test.mjs).
+const isBuildOutput = (file) => /^shared\/[^/]+\.generated\.[cm]?[jt]s$/.test(file);
+// The status code is one or two letters and `gitIn` trims the output, which
+// takes the leading space off the first line, so it is matched, not sliced.
+const changedPaths = (porcelain) => String(porcelain ?? '').split('\n').filter(Boolean).map((l) => l.replace(/^[ MADRCUT?!]{1,2} /, '').replace(/^"|"$/g, ''));
+const theirEdits = (porcelain) => changedPaths(porcelain).filter((f) => !isBuildOutput(f));
+
+function gitIn(appDir) {
+  return (args, { timeout = 30_000 } = {}) => new Promise((resolve) => {
+    execFile('git', args, {
+      cwd: appDir,
+      timeout,
+      // Never a password prompt from a background check. The repository is
+      // public; anything that asks for credentials is a failure to report.
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+      maxBuffer: 4 * 1024 * 1024,
+    }, (err, stdout, stderr) => {
+      resolve({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, out: String(stdout).trim(), err: String(stderr).trim() });
+    });
+  });
+}
+
+function collect(bin, args, { cwd, timeout }) {
+  return new Promise((resolve) => {
+    let out = '';
+    let child;
+    try {
+      child = spawn(bin, args, { cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ code: 1, out: String(e?.message ?? e) });
+      return;
+    }
+    const keep = (b) => { out = (out + b).slice(-64 * 1024); };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const timer = setTimeout(() => { keep('\nerror: timed out'); child.kill('SIGTERM'); }, timeout);
+    child.on('error', (e) => { keep(`\nerror: ${e.message}`); });
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code: code ?? 1, out }); });
+  });
+}
+
+// WHICH npm. Started with `npm start`, the process carries npm's own path in
+// its environment, so that one is used and nvm or a version manager never
+// matters. Started any other way, her login shell is asked, the way
+// main/claude-bin.mjs finds Claude Code. The arguments are fixed strings from
+// this file, never anything read from disk.
+export function defaultNpm(appDir, env = process.env) {
+  return (args) => {
+    const timeout = args[0] === 'install' ? INSTALL_MS : BUILD_MS;
+    const node = env.npm_node_execpath;
+    const cli = env.npm_execpath;
+    if (node && cli && fs.existsSync(node) && fs.existsSync(cli)) {
+      return collect(node, [cli, ...args], { cwd: appDir, timeout });
+    }
+    const shell = env.SHELL || '/bin/zsh';
+    return collect(shell, ['-lic', `npm ${args.join(' ')}`], { cwd: appDir, timeout });
+  };
+}
+
+// The line of a failed build worth showing a person: the first that says
+// error, else the last thing it printed.
+export function failureLine(out) {
+  const lines = String(out ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const named = lines.find((l) => /error/i.test(l));
+  const line = named ?? lines[lines.length - 1] ?? 'it stopped without saying why';
+  return line.length > 160 ? `${line.slice(0, 157)}…` : line;
+}
+
+export function createSourceUpdater({
+  appDir,
+  app = null,
+  log = console,
+  onChanged = () => {},
+  npm = defaultNpm(appDir),
+  relaunch = () => { app?.relaunch(); app?.quit(); },
+} = {}) {
+  const git = gitIn(appDir);
+  // The commit this process booted from. Read once, now, because it is the
+  // code in memory and nothing on disk can change that.
+  let bootHead = null;
+  try {
+    bootHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: appDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch { /* not a checkout; check() says so */ }
+
+  let state = {
+    phase: 'idle',
+    source: true,
+    currentVersion: bootHead ? bootHead.slice(0, 7) : null,
+    newVersion: null,
+    percent: null,
+    error: null,
+    checkedAt: null,
+    readyAt: null,
+    changes: [],
+    behind: null,
+  };
+  let timer = null;
+  let stopped = false;
+  let pending = Promise.resolve();
+
+  const set = (next) => {
+    state = { ...state, ...next };
+    try { onChanged(describe(state)); } catch {}
+  };
+
+  // Everything that has to be true before an update is offered or applied.
+  // Returns the upstream commit, or the sentence saying why not.
+  async function preconditions() {
+    if (!bootHead) return { why: SAY.notRepo };
+    const upstream = await git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+    if (upstream.code !== 0) return { why: SAY.noUpstream };
+    const dirty = await git(['status', '--porcelain', '--untracked-files=no']);
+    if (dirty.code !== 0 || theirEdits(dirty.out).length) return { why: SAY.dirty };
+    const ahead = await git(['merge-base', '--is-ancestor', 'HEAD', '@{u}']);
+    if (ahead.code !== 0) return { why: SAY.diverged };
+    const up = await git(['rev-parse', '@{u}']);
+    if (up.code !== 0 || !up.out) return { why: SAY.noUpstream };
+    return { up: up.out };
+  }
+
+  async function check() {
+    if (stopped) return describe(state);
+    if (state.phase === 'checking' || state.phase === 'installing') return describe(state);
+    if (!bootHead) {
+      set({ phase: 'unsupported', error: SAY.notRepo, checkedAt: Date.now() });
+      return describe(state);
+    }
+    const was = state;
+    set({ phase: 'checking' });
+    // A failed fetch is not the end of the check: what was fetched before is
+    // still on disk, and an update already found stays offered on a plane.
+    const fetched = await git(['fetch', '--quiet'], { timeout: FETCH_MS });
+    if (fetched.code !== 0) log.warn?.('[source-updater] fetch failed:', fetched.err.split('\n')[0]);
+    const ok = await preconditions();
+    if (ok.why) {
+      set({ phase: 'unsupported', error: ok.why, newVersion: null, changes: [], behind: null, readyAt: null, checkedAt: Date.now() });
+      return describe(state);
+    }
+    if (ok.up === bootHead) {
+      set(fetched.code === 0
+        ? { phase: 'current', error: null, newVersion: null, changes: [], behind: null, readyAt: null, checkedAt: Date.now() }
+        : { phase: 'error', error: SAY.offline, checkedAt: Date.now() });
+      return describe(state);
+    }
+    const range = `${bootHead}..${ok.up}`;
+    const titles = await git(['log', '--no-merges', '--format=%s', `-n${LISTED}`, range]);
+    const count = await git(['rev-list', '--no-merges', '--count', range]);
+    const newVersion = ok.up.slice(0, 7);
+    set({
+      phase: 'ready',
+      newVersion,
+      changes: titles.code === 0 && titles.out ? titles.out.split('\n') : [],
+      behind: count.code === 0 ? Number(count.out) || 0 : null,
+      // Stamped when THIS version was first seen, so a recheck does not make
+      // old news young again, and a newer push does.
+      readyAt: was.phase === 'ready' && was.newVersion === newVersion && was.readyAt ? was.readyAt : Date.now(),
+      // A failed earlier restart keeps saying so until the next press.
+      error: was.phase === 'ready' && was.newVersion === newVersion ? was.error : null,
+      checkedAt: Date.now(),
+    });
+    return describe(state);
+  }
+
+  async function apply() {
+    const ok = await preconditions();
+    if (ok.why) {
+      set({ phase: 'unsupported', error: ok.why, newVersion: null, changes: [], behind: null, readyAt: null });
+      return;
+    }
+    const head = await git(['rev-parse', 'HEAD']);
+    // What the last build stamped goes back first, so the fast-forward can
+    // never trip on it. The build below writes it again.
+    const stamped = await git(['status', '--porcelain', '--untracked-files=no']);
+    const buildOutput = stamped.code === 0 ? changedPaths(stamped.out).filter(isBuildOutput) : [];
+    if (buildOutput.length) await git(['checkout', '--', ...buildOutput]);
+    if (head.out !== ok.up) {
+      const merged = await git(['merge', '--ff-only', '--quiet', '@{u}']);
+      if (merged.code !== 0) {
+        set({ phase: 'ready', error: `Could not bring the new code in: ${failureLine(merged.err || merged.out)}` });
+        return;
+      }
+    }
+    // Packages changed when either file's object id moved. Compared by id
+    // rather than by asking git for a diff, which this process does in exactly
+    // one file (tests/the-old-git-diff-screen-stays-gone.test.mjs).
+    let depsMoved = false;
+    for (const file of ['package.json', 'package-lock.json']) {
+      const was = await git(['rev-parse', '--verify', '--quiet', `${bootHead}:${file}`]);
+      const now = await git(['rev-parse', '--verify', '--quiet', `HEAD:${file}`]);
+      if (was.out !== now.out) depsMoved = true;
+    }
+    if (depsMoved) {
+      const installed = await npm(['install', '--no-audit', '--no-fund']);
+      if (installed.code !== 0) {
+        set({ phase: 'ready', error: `The new packages would not install: ${failureLine(installed.out)}` });
+        return;
+      }
+    }
+    const built = await npm(['run', 'build']);
+    if (built.code !== 0) {
+      set({ phase: 'ready', error: `The new code would not build: ${failureLine(built.out)}` });
+      return;
+    }
+    log.info?.('[source-updater] built', state.newVersion, '- relaunching');
+    relaunch();
+  }
+
+  // THE BUTTON. Returns at once; the work takes about a minute and the row
+  // says "Updating" while it runs.
+  function install() {
+    if (stopped || state.phase !== 'ready') return false;
+    set({ phase: 'installing', error: null });
+    pending = apply().catch((e) => {
+      set({ phase: 'ready', error: `The update stopped: ${failureLine(e?.message ?? e)}` });
+    });
+    return true;
+  }
+
+  function start() {
+    if (stopped || timer) return;
+    const tick = () => { void check(); };
+    setTimeout(tick, FIRST_CHECK_MS).unref?.();
+    timer = setInterval(tick, EVERY_MS);
+    timer.unref?.();
+  }
+
+  function stop() {
+    stopped = true;
+    if (timer) clearInterval(timer);
+    timer = null;
+  }
+
+  return {
+    start,
+    stop,
+    check: () => check(),
+    install,
+    state: () => describe(state),
+    // For tests: resolves when a started install has finished, either way.
+    settled: () => pending,
+  };
+}