agentbox-app 0.1.13 → 0.1.16

package/main/leftovers.mjs

@@ -26,9 +26,11 @@
 //      leftovers and no record at all is recorded as ended when this app, whose
 //      store it is in, has no session for it; the clock starts then, never
 //      back-dated.
-//   4. ITS PROGRAMS STOP `idleMs` (2 h) AFTER THE RUN ENDED, or `tightIdleMs`
-//      (10 min) while memory is tight or critical, and never sooner than that
-//      long after the switch went on.
+//   4. ITS PROGRAMS STOP `closeGraceMs` (2 min) AFTER THE TASK IS CLOSED, so a
+//      Z that reopens it keeps them. While memory is tight or critical, also
+//      `tightIdleMs` (10 min) after the run ended, one task per look, the one
+//      whose run ended longest ago first. Never sooner than that long after
+//      the switch went on.
 //   5. NOTHING PROTECTED IS EVER STOPPED: AGENTBOX_KEEP=1 in its environment,
 //      an executable inside an installed app or the system (Docker Desktop and
 //      its VM, a browser an agent opened), an executable that cannot be read,
@@ -49,10 +51,10 @@
 // (main/supervisor.mjs) and everything it starts inherits it; all 40 leftovers
 // that morning carried it, Docker's backend included. The id is read only from
 // the ENVIRONMENT, which is the part of `ps -E` after the arguments `ps` prints
-// without it, and only when both looks agree it is the same process; a tag in a
-// command's own words counts for nothing. A program that renames itself
-// (next-server) hides its environment, so a process under a tagged one belongs
-// to the same task. Codex threads share one app-server and their commands carry
+// without it, and only when both looks agree it is the same process;
+// /proc/<pid>/environ on Linux. A tag in a command's own words counts for
+// nothing. A program that renames itself (next-server) hides its environment
+// from `ps`, so a process under a tagged one belongs to the same task. Codex threads share one app-server and their commands carry
 // no task id yet, so a Codex task's leftovers are not found: coverage is
 // incomplete and the switch says so.
 
@@ -151,8 +153,69 @@ export function applyExecutables(procs, lsofText) {
   return procs;
 }
 
-/** Every process on the Mac, tagged with its task where it can be. About 100 ms. */
-export async function listProcesses() {
+/** /proc counts in USER_HZ, which the kernel fixes at 100 whatever its own tick is. */
+const USER_HZ = 100;
+
+/** When this computer booted, which /proc/<pid>/stat counts a start time from. */
+function bootSeconds(root) {
+  const stat = fs.readFileSync(path.join(root, 'stat'), 'utf8').match(/^btime (\d+)$/m);
+  if (stat) return +stat[1];
+  const up = Number(String(fs.readFileSync(path.join(root, 'uptime'), 'utf8')).split(/\s+/)[0]);
+  return Math.floor(Date.now() / 1000 - up);
+}
+
+/**
+ * The same record the Mac's three `ps` listings give, read from /proc, because
+ * `-E` is BSD's and Linux's procps refuses it (w-bd1806285e).
+ *
+ * `exe` is the real executable even for a program that renamed itself, so
+ * nothing here needs lsof. A process that ends mid-read is left out; one
+ * belonging to somebody else keeps an empty executable and no environment,
+ * which is what leaves it protected.
+ */
+export function readLinuxProcesses({ root = '/proc', hz = USER_HZ, btime = null } = {}) {
+  const boot = btime ?? bootSeconds(root);
+  const out = [];
+  for (const name of fs.readdirSync(root)) {
+    if (!/^\d+$/.test(name)) continue;
+    const dir = path.join(root, name);
+    let stat;
+    try { stat = fs.readFileSync(path.join(dir, 'stat'), 'utf8'); } catch { continue; }
+    const close = stat.lastIndexOf(')');
+    if (close < 0) continue;
+    const comm = stat.slice(stat.indexOf('(') + 1, close);
+    // The fields after the command, which is the only one that can hold spaces
+    // and brackets: state, the parent, and on to the start time.
+    const rest = stat.slice(close + 2).split(' ');
+    const read = (f) => { try { return fs.readFileSync(path.join(dir, f), 'utf8'); } catch { return null; } };
+    const words = (text) => String(text ?? '').split('\0').filter(Boolean);
+    const env = new Map(words(read('environ')).map((s) => {
+      const eq = s.indexOf('=');
+      return eq < 0 ? [s, ''] : [s.slice(0, eq), s.slice(eq + 1)];
+    }));
+    const argv = words(read('cmdline')).join(' ');
+    const rss = (read('status') ?? '').match(/^VmRSS:\s+(\d+) kB$/m);
+    let exe = '';
+    try { exe = fs.readlinkSync(path.join(dir, 'exe')).replace(/ \(deleted\)$/, ''); } catch {}
+    const item = env.get('ZERO_ITEM');
+    out.push({
+      pid: +name,
+      ppid: +rest[1],
+      mb: rss ? +rss[1] / 1024 : 0,
+      start: boot + Math.floor(+rest[19] / hz),
+      exe,
+      cmd: (argv || `[${comm}]`).slice(0, 300),
+      item: /^w-[0-9a-f]+$/.test(item ?? '') ? item : null,
+      product: env.get('ZERO_PRODUCT')?.split(/\s/)[0] || null,
+      keep: env.get('AGENTBOX_KEEP') === '1',
+    });
+  }
+  return out;
+}
+
+/** Every process, tagged with its task where it can be: `ps` on a Mac (about 100 ms), /proc on Linux. */
+export async function listProcesses(platform = process.platform) {
+  if (platform !== 'darwin') return readLinuxProcesses();
   const [base, argv, full] = await Promise.all([
     ps(['-axo', 'pid=,ppid=,rss=,lstart=,comm=']),
     ps(['-ww', '-axo', 'pid=,lstart=,command=']),
@@ -170,7 +233,7 @@ export async function listProcesses() {
   return procs;
 }
 
-async function readMacPressureWord() {
+export async function readMacPressureWord() {
   const out = await new Promise((resolve) => {
     execFile('/usr/sbin/sysctl', ['-n', 'kern.memorystatus_vm_pressure_level', 'kern.memorystatus_level'], { timeout: 5_000 },
       (err, stdout) => resolve(err ? '' : stdout));
@@ -215,7 +278,9 @@ export class LeftoverCleaner {
     enabledSince = Date.now(),
     live = () => false,
     owns = () => false,
-    idleMs = 2 * 60 * 60_000,
+    // When the task was closed, or null while it is open.
+    closedAt = () => null,
+    closeGraceMs = 2 * 60_000,
     tightIdleMs = 10 * 60_000,
     confirmMs = 60_000,
     settleMs = 30_000,
@@ -225,8 +290,9 @@ export class LeftoverCleaner {
     enabled = true,
     log = () => {},
   } = {}) {
-    Object.assign(this, { list, kill, clock, readPressure, file, enabledSince, live, owns, idleMs, tightIdleMs, confirmMs, settleMs, home, enabled, log });
+    Object.assign(this, { list, kill, clock, readPressure, file, enabledSince, live, owns, closedAt, closeGraceMs, tightIdleMs, confirmMs, settleMs, home, enabled, log });
     this.firstSeen = new Map();
+    this.withPrograms = new Set();
     this.lastStatus = { leftovers: [], survivors: [], stopped: null, pressure: 'normal' };
     const saved = this._load();
     this.runs = saved.runs;
@@ -274,6 +340,9 @@ export class LeftoverCleaner {
 
   status() { return this.lastStatus; }
 
+  /** Whether the last look found programs of this task's that could be stopped. */
+  hasPrograms(item) { return this.withPrograms.has(item); }
+
   /** Stop signalling from this moment, even in a look already under way. */
   disable() { this.enabled = false; }
 
@@ -308,6 +377,7 @@ export class LeftoverCleaner {
       return this.lastStatus;
     }
     const view = this._view(procs, now);
+    this.withPrograms = new Set([...view.tasks.values()].filter((t) => t.procs.length).map((t) => t.item));
     this._reconcileRuns(view, now);
     this._trackStopping(view, now);
     const due = this._due(view, now, pressure);
@@ -407,31 +477,53 @@ export class LeftoverCleaner {
     }
   }
 
-  _stopsAt(item, pressure) {
+  /** When this task's programs stop, or null while nothing says they should. */
+  _stopsAt(item, product, pressure) {
     const run = this.runs[item];
     if (!run || run.state !== 'ended') return null;
     const from = Math.max(run.endedAt, this.enabledSince);
-    return from + (pressure === 'normal' ? this.idleMs : this.tightIdleMs);
+    let closed = null;
+    try { closed = this.closedAt(item, product); } catch { closed = null; }
+    const times = [];
+    if (Number.isFinite(closed)) times.push(Math.max(from, closed) + this.closeGraceMs);
+    if (pressure !== 'normal') times.push(from + this.tightIdleMs);
+    return times.length ? Math.min(...times) : null;
   }
 
-  /** Programs whose time has come and that have been seen long enough. */
+  /**
+   * Programs whose time has come and that have been seen long enough: every
+   * closed task's, and while memory is short, one more task's, the one whose
+   * run ended longest ago.
+   */
   _due(view, now, pressure) {
     const due = [];
     if (!this.enabled) return due;
+    let short = null;
     for (const t of view.tasks.values()) {
       if (this._alive(t)) continue;
-      const at = this._stopsAt(t.item, pressure);
+      const closed = this._stopsAt(t.item, t.product, 'normal');
+      if (closed !== null && now >= closed) { due.push(...this._ready(t, now)); continue; }
+      const at = pressure === 'normal' ? null : this._stopsAt(t.item, t.product, pressure);
       if (at === null || now < at) continue;
-      for (const p of t.procs) {
-        const id = idOf(p);
-        if (this.stopping[id]) continue;
-        if (now - (this.firstSeen.get(id) ?? now) < this.confirmMs) continue;
-        due.push({ item: t.item, id, pid: p.pid });
-      }
+      const ready = this._ready(t, now);
+      const ended = this.runs[t.item].endedAt;
+      if (ready.length && (!short || ended < short.ended)) short = { ended, ready };
     }
+    if (short) due.push(...short.ready);
     return due;
   }
 
+  _ready(t, now) {
+    const out = [];
+    for (const p of t.procs) {
+      const id = idOf(p);
+      if (this.stopping[id]) continue;
+      if (now - (this.firstSeen.get(id) ?? now) < this.confirmMs) continue;
+      out.push({ item: t.item, id, pid: p.pid });
+    }
+    return out;
+  }
+
   /** One fresh look, every rule again, then SIGTERM to what still passes. */
   async _stop(due, pressure) {
     let procs;
@@ -448,8 +540,8 @@ export class LeftoverCleaner {
       const t = view.tasks.get(d.item);
       if (!t || !t.procs.includes(p)) continue; // protected now, or no longer this task's
       if (this._alive(t)) continue;
-      const at = this._stopsAt(d.item, pressure);
-      if (at === null || now < at) continue; // a run started meanwhile
+      const at = this._stopsAt(d.item, t.product, pressure);
+      if (at === null || now < at) continue; // a run started, or the task reopened, meanwhile
       // Switched off while this look was under way: nothing more is signalled.
       if (!this.enabled) break;
       try { this.kill(p.pid, 'SIGTERM'); } catch { continue; }
@@ -477,7 +569,7 @@ export class LeftoverCleaner {
         kept: t.guarded.length,
         mb: all.reduce((n, p) => n + (p.mb ?? 0), 0),
         oldest: Math.min(...all.map((p) => p.start * 1000)),
-        stopsAt: t.procs.length ? this._stopsAt(t.item, pressure) : null,
+        stopsAt: t.procs.length ? this._stopsAt(t.item, t.product, pressure) : null,
       });
     }
     return out.sort((a, b) => a.oldest - b.oldest);

package/main/liquid-glass.mjs

@@ -0,0 +1,26 @@
+// The Mac's own Liquid Glass for a window, or null where there is none: not a
+// Mac, a macOS before 26, or a build that could not compile main/native
+// (scripts/build-liquid-glass.mjs). Null means the page draws its own glass.
+import { createRequire } from 'node:module';
+
+export function loadLiquidGlass({ mac = process.platform === 'darwin', load = createRequire(import.meta.url) } = {}) {
+  if (!mac) return null;
+  let native;
+  try {
+    native = load('./native/liquid-glass/build/liquid-glass.node');
+    if (!native.available()) return null;
+  } catch {
+    return null;
+  }
+  const handle = (win) => win.getNativeWindowHandle();
+  return {
+    // tone: 'light' or 'dark' holds the glass that way; leave it out and the
+    // glass decides from what is behind it. style: 'clear' for the Mac's clear
+    // glass, which lets a light page through; otherwise the regular glass.
+    set: (win, rect, { radius, tone, style } = {}) => native.set(handle(win), rect, {
+      radius, ...(tone ? { tone } : {}), ...(style ? { style } : {}),
+    }),
+    clear: (win) => native.clear(handle(win)),
+    tone: (win) => native.tone(handle(win)),
+  };
+}

package/main/live-replies.mjs

@@ -15,9 +15,11 @@ import { TURN_CLOSED } from './claude-input.mjs';
 // is the result, so without this it has every reason to save the answer for an
 // ending the person is not waiting through.
 //
-// Their words go LAST, as in `replyBrief`: the newest thing they said is the
-// newest thing in its context, and nothing of ours is written after it.
-export function liveReplyBrief(answer) {
+// Their words go LAST: the newest thing they said is the newest thing in its
+// context, and nothing of ours is written after it. `files` is the supervisor's
+// `attachmentBlock` for this reply: the pictures in it by absolute path, which
+// is also what a cloud run reads to send them up (main/cloud/run.mjs).
+export function liveReplyBrief(answer, files = '') {
   return [
     'This arrived in your thread just now, while you work, and they are watching',
     'for a reply. Do what it asks. If it asks you anything, or says it did not',
@@ -25,6 +27,7 @@ export function liveReplyBrief(answer) {
     'you go back to what you were doing: the sentences you write while you work',
     'are what they read, so an answer saved for the end reads as no answer at all.',
     'Then carry on.',
+    ...(files ? [files] : []),
     '',
     'What they said:',
     '',
@@ -49,7 +52,10 @@ export function submitReply(supervisor, payload, commit) {
     // A held Remote Control conversation is sitting idle rather than working,
     // and the slash commands it takes stop being commands once prose is wrapped
     // round them. Both reach it exactly as typed.
-    const taken = session.child.steer(session.remoteIdle ? answer : liveReplyBrief(answer));
+    const files = session.remoteIdle ? null : supervisor.replyFiles?.(product, answer, session.engine, id);
+    const taken = session.remoteIdle
+      ? session.child.steer(answer)
+      : session.child.steer(liveReplyBrief(answer, files?.block), files?.pictures ?? []);
     // SENT NOW: her words go in line first, then the step is cut, in the same
     // tick, so the cut turn's result can never close the input ahead of them.
     // A cut that fails leaves the message waiting its turn, which is still sent.

package/main/main-went-red.mjs

@@ -0,0 +1,330 @@
+// MAIN GOES RED ON GITHUB AND ONE TASK SAYS WHICH TESTS (w-3836800002).
+//
+// Main was red on GitHub from 2026-10-09 to 2026-10-13 and nobody noticed. The
+// `tests` workflow takes about five minutes, which is after the agent that
+// shipped has already ended its turn, and `scripts/ship.mjs` signs off by
+// printing "check the run" to a terminal nobody is reading. So the one gate
+// that runs the WHOLE suite on both machines had no reader at all.
+//
+// The app ships the branch (main/ship-queue.mjs), so the app is the thing still
+// running when that cross appears. After every successful ship it waits for
+// that commit's run and files ONE task when main turns red: which tests, which
+// machine each failed on, and the commit that did it.
+//
+// NOTHING BLOCKS ON THIS. No ship waits for it, no agent is held, and every
+// failure here is silent: a machine without `gh`, or signed out of it, or
+// without access to the repository, does nothing at all. A watcher that
+// interrupted shipping to report on shipping would be worse than the gap it
+// closes.
+//
+// ONE BREAKAGE IS ONE ROW. While main stays red, further ships file nothing:
+// a row per red commit would be a dozen rows about one mistake. The green
+// again lands on that same row as a note, so the row that told them reads as
+// finished where they are already looking.
+
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** How often to ask GitHub, and how long before giving up on a run. */
+export const POLL_MS = 60 * 1000;
+export const GIVE_UP_MS = 30 * 60 * 1000;
+
+const STATE = 'main-tests.json';
+const WORKFLOW = 'tests';
+const LOG_BYTES = 16 * 1024 * 1024;
+
+/** `gh`, with its own words back and never a throw. */
+export function runGh(args, { cwd, timeout = 60 * 1000 } = {}) {
+  return new Promise((resolve) => {
+    execFile('gh', args, { cwd, encoding: 'utf8', timeout, maxBuffer: LOG_BYTES }, (error, stdout, stderr) => {
+      if (error) resolve({ code: error.code ?? 1, out: `${stdout ?? ''}${stderr ?? ''}${error.message ?? ''}` });
+      else resolve({ code: 0, out: String(stdout ?? '') });
+    });
+  });
+}
+
+/**
+ * The run for the commit that was just shipped, or null while GitHub has not
+ * made one yet.
+ *
+ * `scripts/ship.mjs` reports the SHORT sha and GitHub answers with the full
+ * forty, so either may be the prefix of the other.
+ */
+export function runFor(runs, sha) {
+  const want = String(sha ?? '').trim().toLowerCase();
+  if (!want) return null;
+  return (runs ?? []).find((run) => {
+    const head = String(run?.headSha ?? '').toLowerCase();
+    return head && (head.startsWith(want) || want.startsWith(head));
+  }) ?? null;
+}
+
+/**
+ * What that run says: `waiting`, `passing`, `failing`, or `ignore`.
+ *
+ * `cancelled` is IGNORED because a second push to main cancels the first
+ * (the `concurrency` block in .github/workflows/tests.yml), so a cancelled run
+ * is not a verdict on anything; the newer push's own watch carries it.
+ * `startup_failure` is ignored because it is a GitHub ACCOUNT problem rather
+ * than a test: for three weeks every run here ended that way, and the answer
+ * was a payment method, not a commit (the head of that workflow file says so).
+ * A row per push during a spell like that is noise with no fix in it.
+ */
+export function verdict(run) {
+  if (!run || run.status !== 'completed') return 'waiting';
+  const how = String(run.conclusion ?? '');
+  if (how === 'success') return 'passing';
+  if (how === 'failure' || how === 'timed_out') return 'failing';
+  return 'ignore';
+}
+
+/** Which machine a job ran on, by the label the workflow asked for. */
+export function machineOf(job) {
+  const labels = (job?.labels ?? []).join(' ').toLowerCase();
+  const name = String(job?.name ?? '');
+  if (/ubuntu|linux/.test(`${labels} ${name}`)) return 'Linux';
+  if (/macos/.test(`${labels} ${name}`)) return 'macOS';
+  if (/windows/.test(`${labels} ${name}`)) return 'Windows';
+  return name || 'that machine';
+}
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+// A job log is one timestamped line per line of output, and GitHub's own
+// lines carry a kind in front of them.
+const STAMP = /^\S+Z\s/;
+const GITHUB_SAYS = /^##\[[a-z]+\]/;
+const clean = (raw) => String(raw).replace(ANSI, '').replace(STAMP, '').replace(GITHUB_SAYS, '').trim();
+// Vitest's own `FAIL  tests/x.test.mjs > suite > case`, and ONLY at the start
+// of the line. A LINE VITEST QUOTED IS NOT THE RUNNER SPEAKING: the ship queue
+// learned that three times over (w-560647d4db). A failing text assertion
+// prints the file's own source as a diff (`+`/`-`) and as a code frame
+// (`34|  ...`), and this repo's test files are sentences, so plenty of them
+// carry "failed" or "FAIL" inside a name. Anchoring at FAIL rules all of that
+// out, and the tick vitest puts on a file it ran green rules out the rest.
+const NAMES_A_RED_TEST = /^FAIL\s+(\S+?\.(?:test|spec)\.[a-z]+)(?:\s|$)/;
+
+/** Every test file the runner printed a FAIL for, once each, in order. */
+export function failedTestsIn(log) {
+  const found = [];
+  for (const raw of String(log ?? '').split('\n')) {
+    const name = NAMES_A_RED_TEST.exec(clean(raw))?.[1];
+    if (name && !found.includes(name)) found.push(name);
+  }
+  return found;
+}
+
+// VITEST EXITS 1 FOR THINGS THAT ARE NOT A FAILING TEST, and none of them
+// print FAIL: an error thrown after a file's tests have passed, a collection
+// that never started, a worker that died. The row used to stop at "names no
+// failing test" with the log it had already fetched left unread.
+//
+// A banner is matched along with the rule vitest draws it in, because a line
+// vitest QUOTED is not the runner speaking. The plural heading over the whole
+// section is not one of these, and the three lines of advice are about
+// unhandled errors in general rather than about this run.
+const UNHANDLED = /^⎯+\s*Unhandled (?:Error|Rejection)\s*⎯*$/;
+const NAMES_A_BREAKAGE = /^(?:No test files found|FATAL ERROR:)/;
+const ADVICE = /^(?:Vitest caught|This might cause|Serialized Error)/;
+const SAID_AT_MOST = 5;
+
+/** What the runner itself said, for a row that can name no failing test. */
+export function whatTheRunnerSaid(log) {
+  const lines = String(log ?? '').split('\n').map(clean);
+  const said = [];
+  const keep = (line) => {
+    if (line && !ADVICE.test(line) && !said.includes(line)) said.push(line);
+  };
+  lines.forEach((line, i) => {
+    if (UNHANDLED.test(line)) keep(lines.slice(i + 1, i + 8).find((l) => l && !ADVICE.test(l)));
+    else if (NAMES_A_BREAKAGE.test(line)) keep(line);
+  });
+  return said.slice(0, SAID_AT_MOST);
+}
+
+const shortSha = (sha) => String(sha ?? '').slice(0, 7);
+const NOTHING_NAMED = 'nothing in its log names a failing test';
+// A log `gh` could not hand over says nothing about the run, and a row that
+// reported it as "names no failing test" would be making that up.
+const NOT_READ = 'its log could not be read from here';
+const unread = (machines) => machines.length > 0 && machines.every((m) => m.read === false);
+/** The first thing any machine said, cut to something a title can hold. */
+const firstWords = (machines, max) => {
+  const said = machines.flatMap((m) => m.said ?? []).find(Boolean);
+  if (!said) return '';
+  return said.length > max ? `${said.slice(0, max - 1).trimEnd()}…` : said;
+};
+
+/** The row's title: the one test, or the count and the machines. */
+export function redTitle(machines) {
+  const names = [...new Set(machines.flatMap((m) => m.tests))];
+  if (names.length === 1) return `main went red on GitHub: ${names[0]}`;
+  if (!names.length) {
+    const said = firstWords(machines, 58);
+    if (said) return `main went red on GitHub: ${said}`;
+    if (unread(machines)) return `main went red on GitHub, and ${NOT_READ}`;
+    return 'main went red on GitHub, and its log names no failing test';
+  }
+  const where = machines.filter((m) => m.tests.length).map((m) => m.machine);
+  return `main went red on GitHub: ${names.length} tests, on ${where.join(' and ')}`;
+}
+
+/** The row's Context: what a reader gets before they open anything. */
+export function redContext({ sha, machines }) {
+  const names = [...new Set(machines.flatMap((m) => m.tests))];
+  const where = machines.filter((m) => m.tests.length).map((m) => m.machine);
+  if (!names.length) {
+    const said = firstWords(machines, 110);
+    let how = NOTHING_NAMED;
+    if (said) how = `no test failed and the runner said "${said}"`;
+    else if (unread(machines)) how = NOT_READ;
+    return `main's tests run went red on GitHub at ${shortSha(sha)}, and ${how}. The run itself is in the task.`;
+  }
+  return [
+    `main's tests run went red on GitHub at ${shortSha(sha)}, on ${where.join(' and ')}.`,
+    `${names.length === 1 ? 'The failing test' : `The ${names.length} failing tests`}: ${names.join(', ')}.`,
+    'Which machine each failed on, and the run, are in the task.',
+  ].join(' ');
+}
+
+/** The whole row: what failed, where, and the commit that did it. */
+export function redRow({ sha, subject, url, machines }) {
+  return {
+    title: redTitle(machines),
+    problem: redContext({ sha, machines }),
+    body: [
+      "main's `tests` run went red on GitHub, at this commit:",
+      '',
+      `    ${shortSha(sha)}  ${subject || 'no title'}`,
+      '',
+      ...machines.flatMap(({ machine, tests, said, read }) => [
+        `${machine}:`,
+        ...(tests.length ? tests.map((t) => `- ${t}`) : [
+          `- ${read === false ? NOT_READ : NOTHING_NAMED}${said?.length ? ', and the runner said:' : ''}`,
+          ...(said ?? []).map((line) => `  ${line}`),
+        ]),
+        '',
+      ]),
+      ...(url ? [`The whole run: ${url}`, ''] : []),
+      'That run finishes about five minutes after the agent that shipped has',
+      'already ended, so nobody is watching it: main was red here from',
+      '2026-10-09 to 2026-10-13 and nothing said so. This is the only row filed',
+      'while main stays red, and a note lands here when it goes green again.',
+    ].join('\n'),
+  };
+}
+
+/** What that row hears when main comes back. */
+export function greenAgain({ sha, subject }) {
+  return `main's tests are green again on GitHub, as of ${shortSha(sha)}${subject ? ` (${subject})` : ''}.`;
+}
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms).unref?.(); });
+
+/**
+ * The watch itself: one per successful ship, and never anything a person waits
+ * on.
+ *
+ * WHETHER MAIN IS KNOWN RED LIVES IN THE APP'S OWN DATA FOLDER, beside the
+ * ship settings, because it is a fact about this Mac's watching rather than
+ * about anyone's work. With no file, main counts as fine, so the FIRST red run
+ * this ever sees files a row: requiring a green first would have kept it silent
+ * through exactly the four days that put this here.
+ */
+export class MainTests {
+  constructor({ store, userDir, gh = runGh, wait = sleep, now = Date.now, log = console } = {}) {
+    Object.assign(this, { store, userDir, gh, wait, now, log });
+    this.stopped = false;
+  }
+
+  stop() { this.stopped = true; }
+
+  stateFile() { return path.join(this.userDir, STATE); }
+
+  read() {
+    try {
+      const raw = JSON.parse(fs.readFileSync(this.stateFile(), 'utf8'));
+      return raw && typeof raw === 'object' ? raw : {};
+    } catch { return {}; }
+  }
+
+  write(state) {
+    try {
+      const tmp = `${this.stateFile()}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, `${JSON.stringify(state)}\n`);
+      fs.renameSync(tmp, this.stateFile());
+    } catch (e) { this.log.warn?.(`main-tests: could not record where main stands: ${e.message}`); }
+  }
+
+  /** gh's JSON, or null if this machine cannot ask. */
+  async ask(args, cwd) {
+    const { code, out } = await this.gh(args, { cwd });
+    if (code !== 0) return null;
+    try { return JSON.parse(out); } catch { return null; }
+  }
+
+  async watch({ product, sha } = {}) {
+    const cwd = product?.repoPath;
+    if (!cwd || !sha || !fs.existsSync(cwd)) return null;
+    const until = this.now() + GIVE_UP_MS;
+    while (!this.stopped) {
+      const runs = await this.ask(
+        ['run', 'list', '--branch', 'main', '--workflow', WORKFLOW, '-L', '20',
+          '--json', 'databaseId,headSha,status,conclusion,displayTitle,url'],
+        cwd,
+      );
+      // No gh, signed out, or no access to this repository: nothing, quietly.
+      if (!runs) return null;
+      const run = runFor(runs, sha);
+      const says = verdict(run);
+      if (says === 'ignore') return null;
+      if (says === 'passing') return this.wentGreen(product, run);
+      if (says === 'failing') return this.wentRed(product, run, cwd);
+      if (this.now() >= until) {
+        this.log.info?.(`main-tests: ${shortSha(sha)}'s run has not finished in half an hour; leaving it.`);
+        return null;
+      }
+      await this.wait(POLL_MS);
+    }
+    return null;
+  }
+
+  /** One row, and only while main was not already known red. */
+  async wentRed(product, run, cwd) {
+    const state = this.read();
+    if (state.red) return null;
+    const jobs = (await this.ask(['api', `repos/{owner}/{repo}/actions/runs/${run.databaseId}/jobs`, '--paginate'], cwd))?.jobs ?? [];
+    const machines = [];
+    for (const job of jobs) {
+      if (String(job?.conclusion ?? '') !== 'failure') continue;
+      const { code, out } = await this.gh(['api', `repos/{owner}/{repo}/actions/jobs/${job.id}/logs`], { cwd });
+      const read = code === 0;
+      const tests = read ? failedTestsIn(out) : [];
+      machines.push({ machine: machineOf(job), tests, read, said: read && !tests.length ? whatTheRunnerSaid(out) : [] });
+    }
+    const row = redRow({ sha: run.headSha, subject: run.displayTitle, url: run.url, machines });
+    let filed = null;
+    try {
+      filed = this.store.fileItem(product.slug, { ...row, kind: 'task' });
+    } catch (e) {
+      this.log.warn?.(`main-tests: could not file the red main: ${e.message}`);
+      return null;
+    }
+    this.write({ ...state, red: { product: product.slug, id: filed.id, sha: run.headSha } });
+    this.log.info?.(`main-tests: main went red at ${shortSha(run.headSha)}; filed ${filed.id}.`);
+    return filed;
+  }
+
+  /** The green again, on the row that reported the red. */
+  wentGreen(product, run) {
+    const state = this.read();
+    if (!state.red) return null;
+    try {
+      this.store.noteItem(state.red.product, state.red.id, greenAgain({ sha: run.headSha, subject: run.displayTitle }));
+    } catch (e) {
+      this.log.warn?.(`main-tests: could not say main is green again: ${e.message}`);
+    }
+    this.write({ ...state, red: null });
+    return null;
+  }
+}