agentbox-app 0.1.6 → 0.1.11

package/main/settings.mjs

@@ -15,7 +15,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { saveConfig } from './config.mjs';
+import { codexChoiceToOpen, saveConfig } from './config.mjs';
 import { resolveClaudeBin, forgetClaudeBin, INSTALL_URL } from './claude-bin.mjs';
 import { AGENT_MODES } from '../shared/agents.mjs';
 import { analyticsKey, diagnosticsOn } from './analytics.mjs';
@@ -23,7 +23,9 @@ import { CLAUDE_PERMISSION_MODES } from '../shared/work-items.mjs';
 import { accountSentence, engineTroubleNote } from '../shared/spawn-trouble.mjs';
 import { readPlan } from './claude-plan.mjs';
 import { effectiveProfiles } from './account-discovery.mjs';
-import { machineSlots, machineNote, MAX_SLOTS } from './machine.mjs';
+import { machineSlots, machineNote, autoAgents, MAX_SLOTS } from './machine.mjs';
+import { NAME } from '../shared/product-name.mjs';
+import { autoSlots } from './memory-gate.mjs';
 import { accountIdentity, claudeLoginCommand, duplicateAccountNote, linkAccountTooling, makeClaudeHome } from './account-tooling.mjs';
 import { isEngine } from '../shared/engines.mjs';
 import { codexAccount, codexLoginCommand, makeCodexHome } from './codex-account.mjs';
@@ -270,6 +272,10 @@ export function recheckClaude(config) {
   // has just found Claude Code updates it rather than leaving the rest of the
   // app pointing at where it used to not be.
   if (state.claudeFound && state.claudeBin) config.claudeBin = state.claudeBin;
+  // And whether it is here at all, which is what decides that a Mac with only
+  // Codex runs on Codex (`Supervisor#_enginesFound`). Only a certain answer
+  // moves it, so an unsure search never takes Claude Code away from anybody.
+  if (state.claudeFound || state.claudeCertain) config.claudeFound = state.claudeFound;
   return state;
 }
 
@@ -319,6 +325,12 @@ export function codexState(config, where = {}) {
   };
 }
 
+/** `codexState` under the names the walk's last card reads beside Claude's. */
+export function codexFoundState(config, where = {}) {
+  const state = codexState(config, where);
+  return { codexFound: state.found, codexCertain: state.certain, codexInstallUrl: state.url };
+}
+
 /**
  * LOOK AGAIN, PROPERLY, for the second engine. The twin of `recheckClaude`
  *  above, and it earns its place for a sharper reason: finding Codex here is
@@ -329,6 +341,10 @@ export function recheckCodex(config) {
   forgetCodexBin();
   const state = codexState(config);
   config.codexBin = state.found ? state.bin : null;
+  // Found while the app is open, by this button or the plan setup: the choice
+  // opens now, as it would have at the next launch (main/config.mjs).
+  const opened = codexChoiceToOpen(config, state.found);
+  if (opened && config.appDir) saveConfig(config, { engineChoice: opened });
   return state;
 }
 
@@ -366,9 +382,9 @@ export function readSettings({ config, supervisor, store }) {
     const trouble = troubles[profile] ?? null;
     const resting = (supervisor._profileCooldown?.[profile] ?? 0) >= now;
     // WHOSE SUBSCRIPTION THIS ROW IS, not merely which folder it lives in.
-    // The page named its rows after folders, so nothing on it could tell her
-    // that her work account had been replaced by her personal one;
-    // main/account-tooling.mjs has the morning that cost. Null when the
+    // The page named its rows after folders, so nothing on it could tell a
+    // person that one of their accounts had been replaced by the other;
+    // main/account-tooling.mjs has how that happens. Null when the
     // folder holds no login, and then the row reads as it always did.
     const identity = accountIdentity(profile === 'default' ? null : profile);
     return {
@@ -421,9 +437,8 @@ export function readSettings({ config, supervisor, store }) {
       // THE MARK, already a drawable url or null, resolved once by listProducts.
       logo: product.logo,
       // ONE SWITCH A PROJECT STILL HAS (w-d19d6d387c, 2026-09-22). It had five
-      // controls. Hers, on a picture of them: "I still don't actually
-      // understand what those toggles do, even after reading them... I would
-      // lean towards just having project-level instructions." The drive, the
+      // controls, and what they did was not clear even after reading their
+      // labels, so project-level instructions replace them. The drive, the
       // per-project pause and personal mode are gone from the app entirely.
       // `permission` stays readable because `projectSessionArgs` is still
       // honoured for anyone who sets one in the config by hand, and the page
@@ -439,10 +454,31 @@ export function readSettings({ config, supervisor, store }) {
     };
   });
 
+  // ARCHIVED PROJECTS, only so the Projects page can bring one back. Name and
+  // folder, the two things that tell three projects called Daydream apart.
+  let archivedProjects = [];
+  try {
+    archivedProjects = store.listProducts({ includeArchived: true })
+      .filter((p) => p.archived === true)
+      .map((p) => ({ slug: p.slug, name: p.name, dir: p.dir }));
+  } catch {}
+
   return {
+    archivedProjects,
     workspace: {
       agentsRunning: !supervisor.paused,
       sessionsAtOnce: config.maxConcurrentSessions,
+      // AUTOMATIC, AND WHAT IT WORKS OUT TO (w-e5225b62ba). `agentsAuto` is who
+      // is deciding; `agentsTotal` is what the whole Mac is running at once,
+      // which is the number the page shows, because the per-account one is
+      // arithmetic nobody should have to do. `agentsNudge` is how many steps
+      // down "Something felt slow" has taken it.
+      agentsAuto: !!config.agentsAuto,
+      agentsTotal: status.capacity,
+      agentsNudge: Math.max(0, Math.round(Number(config.agentsNudge) || 0)),
+      // What Automatic would say right now, so a manual number can be compared
+      // with it without turning Automatic back on to find out.
+      agentsAutoTotal: autoAgents({ gated: !!config.memoryGate, nudge: config.agentsNudge }),
       // THE PLAN THAT SET THE NUMBER ABOVE, when a plan set it. Null in the
       // ordinary case: she picked the number herself, or it is the three every
       // install has always had. It is only ever filled in when somebody would
@@ -457,6 +493,8 @@ export function readSettings({ config, supervisor, store }) {
       slotsSuggested: slotsHere.slots,
       slotsMax: MAX_SLOTS,
       machineNote: machineNote(slotsHere, config.maxConcurrentSessions),
+      memoryGate: memoryGateSettings({ config, supervisor }),
+      leftovers: leftoverSettings({ config, supervisor }),
       capacity: status.capacity,
       running: sessions.length,
       model: parseSessionArgs(workspaceArgs).model,
@@ -509,6 +547,10 @@ export function readSettings({ config, supervisor, store }) {
       // Someone who reads "install it, then open this screen again" and does
       // exactly that has to see it turn found, without restarting the app.
       ...claudeState(config),
+      // AND WHETHER CODEX IS, because the app needs one of the two and not
+      // both: the last card of the walk only shuts the inbox when neither is
+      // here (renderer/src/App.tsx).
+      ...codexFoundState(config),
       // AND WHAT THIS MAC'S CLAUDE CODE CALLS ITS MODELS.
       //
       // In the same trip, and for the same reason the line above is looked up
@@ -577,21 +619,26 @@ function engineSettings(supervisor, config) {
   // and that stopped being true somewhere between codex-cli versions.
   // main/codex-account.mjs holds the measurement. Null when nobody is signed
   // in, and the card then reads exactly as it always did.
-  const codex = supervisor.engineChoiceOpened()
-    ? {
-      ...codexState(config),
-      trouble: engineTroubleFor(supervisor, 'codex'),
-      account: codexAccount(supervisor._codexHome()),
-      // EVERY CODEX LOGIN ON THE MAC, NOT JUST THE FIRST. The supervisor has
-      // run one app-server per CODEX_HOME since a second login became real;
-      // what never existed was a screen that could see them. One entry per
-      // `codexProfiles` word, resolved through the supervisor's own mapping so
-      // the card and the fleet cannot disagree about which folder a name
-      // means.
-      accounts: codexAccountRows(supervisor),
-    }
-    : null;
-  if (choices.length < 2) {
+  // A Mac that runs on Codex alone has asked about it by having nothing else.
+  //
+  // AND THE PAGE IS DRAWN ON EVERY MAC NOW (w-d5d632e503). A tester who only
+  // uses Codex looked for it in Settings, found nothing, and had no way to
+  // tell "not installed" from "not offered". Not found, the page says so and
+  // links the install, which is the question that person had.
+  const codexIsHome = engine === 'codex';
+  const codex = {
+    ...codexState(config),
+    trouble: engineTroubleFor(supervisor, 'codex'),
+    account: codexAccount(supervisor._codexHome()),
+    // EVERY CODEX LOGIN ON THE MAC, NOT JUST THE FIRST. The supervisor has
+    // run one app-server per CODEX_HOME since a second login became real;
+    // what never existed was a screen that could see them. One entry per
+    // `codexProfiles` word, resolved through the supervisor's own mapping so
+    // the card and the fleet cannot disagree about which folder a name
+    // means.
+    accounts: codexAccountRows(supervisor),
+  };
+  if (choices.length < 2 && !codexIsHome) {
     return { engine, engineChoices: choices, codex, codexModels: [], codexModelDefault: null, codexModel: null };
   }
   const home = supervisor._codexHome();
@@ -754,8 +801,8 @@ export function addCodexAccount({ config, supervisor }) {
  * accounting while this was a product we sold. She withdrew that on
  * w-3498e0cad2 ("we're no longer offering this as a commercially viable
  * product... the rules have changed so I think you should allow
- * multi-accounting"), and this is the door that decision asked for. Her reason
- * for wanting it is the ordinary one: a work login and a personal login, both
+ * multi-accounting"), and this is the door that decision asked for. The
+ * ordinary reason for wanting it: a work login and a personal login, both
  * live, on one Mac.
  *
  * Everything else is the Codex flow exactly. Main makes the folder and
@@ -781,19 +828,143 @@ export function addClaudeAccount({ config, supervisor }) {
   return { home: made.home, profile: made.profile, command: claudeLoginCommand(made.home) };
 }
 
+/**
+ * The Agents page's memory rows: the switch, the number of heavy commands at
+ * once (null is Auto), what Auto works out to here, and one sentence about
+ * right now while it is on.
+ */
+export function memoryGateSettings({ config, supervisor }) {
+  const on = !!config.memoryGate;
+  const slots = Number.isFinite(config.memoryGateSlots) ? config.memoryGateSlots : null;
+  // What Auto works out to on this Mac, whether or not somebody picked.
+  const slotsAuto = autoSlots(os.totalmem());
+  let now = null;
+  if (on) {
+    let s = null;
+    try { s = supervisor.memoryGateStatus?.() ?? null; } catch {}
+    if (s?.role === 'standby') now = `Another ${NAME} on this Mac is coordinating.`;
+    else if (s) {
+      const heavy = (s.running ?? []).filter((r) => r.holdsSlot).length;
+      const waiting = (s.waiting ?? []).length;
+      const mem = s.pressure === 'critical' ? 'Memory is very short.' : s.pressure === 'tight' ? 'Memory is tight.' : 'Memory is fine.';
+      const run = heavy ? `${heavy} heavy command${heavy === 1 ? '' : 's'} running` : 'Nothing heavy running';
+      now = `${mem} ${run}${waiting ? `, ${waiting} waiting` : ''}.`;
+    }
+  }
+  return { on, slots, slotsAuto, slotsMax: MAX_SLOTS, now, reading: memoryReading({ config, supervisor }) };
+}
+
+/**
+ * THE FIGURES THE RUNNING PAGE LEADS WITH (w-e5225b62ba), rather than the same
+ * facts tacked onto the end of three grey paragraphs: "6 running now", "Holding
+ * 3 commands now", "Nothing running now".
+ *
+ * Every field is null when it is not known, and the page leaves out what is
+ * null. A figure invented to fill a slot is worse than a gap: this card's whole
+ * job is to be the one place on the screen that is measured.
+ *
+ * `usedPct` is the kernel's own `kern.memorystatus_level` turned round, which is
+ * what the gate already polls, so the bar and the word above it cannot disagree.
+ */
+export function memoryReading({ config, supervisor }) {
+  const out = { heavy: null, waiting: null, pressure: null, usedPct: null, asked: null, waited: null, refused: null };
+  if (!config.memoryGate) return out;
+  let s = null;
+  try { s = supervisor.memoryGateStatus?.() ?? null; } catch { return out; }
+  if (!s || s.role === 'standby') return out;
+  out.heavy = (s.running ?? []).filter((r) => r.holdsSlot).length;
+  out.waiting = (s.waiting ?? []).length;
+  out.pressure = s.pressure ?? null;
+  if (Number.isFinite(s.freePct)) out.usedPct = Math.max(0, Math.min(100, 100 - s.freePct));
+  const c = s.counts ?? {};
+  if (Number.isFinite(c.asked)) out.asked = c.asked;
+  if (Number.isFinite(c.waited)) out.waited = c.waited;
+  if (Number.isFinite(c.refused)) out.refused = c.refused;
+  return out;
+}
+
+/**
+ * The Agents page's leftovers row: the switch, and one sentence about what
+ * finished agents have left running while it is on.
+ */
+export function leftoverSettings({ config, supervisor }) {
+  const on = !!config.cleanupLeftovers;
+  let now = null;
+  let s = null;
+  try { s = supervisor.leftoverStatus?.() ?? null; } catch {}
+  const list = s?.leftovers ?? [];
+  const stoppable = list.reduce((n, l) => n + (l.programs ?? 0), 0);
+  const kept = list.reduce((n, l) => n + (l.kept ?? 0), 0);
+  const total = stoppable + kept;
+  // OFF, IT SAYS WHAT TURNING IT ON WOULD STOP, before anybody does: the
+  // consent is to these programs too, not only to future ones (agreed with
+  // Codex, 2026-10-05).
+  if (!on) {
+    if (total && stoppable) {
+      now = `Right now finished agents have left ${total} program${total === 1 ? '' : 's'} running; turning this on stops ${stoppable === total ? (total === 1 ? 'it' : 'them') : `${stoppable} of them`}, two hours from then.`;
+    }
+    return { on, now };
+  }
+  {
+    if (!total) now = 'Nothing left running by finished agents.';
+    else {
+      const next = list.filter((l) => l.programs && l.stopsAt).map((l) => l.stopsAt).sort((a, b) => a - b)[0];
+      const when = (ms) => {
+        const m = Math.max(1, Math.round((ms - Date.now()) / 60_000));
+        return m >= 60 ? `${Math.floor(m / 60)} h${m % 60 ? ` ${m % 60} m` : ''}` : `${m} m`;
+      };
+      now = `Finished agents have left ${total} program${total === 1 ? '' : 's'} running.`;
+      if (stoppable) now += ` ${stoppable} ${next && next > Date.now() ? `stop in ${when(next)}` : 'are stopping'}`;
+      if (kept) now += `${stoppable ? ';' : ''} ${kept} ${kept === 1 ? 'is' : 'are'} kept`;
+      now += '.';
+      const survivors = s?.survivors?.length ?? 0;
+      if (survivors) now += ` ${survivors} did not stop when asked.`;
+    }
+  }
+  return { on, now };
+}
+
 export function setWorkspaceSetting({ config, supervisor }, { key, value }) {
   switch (key) {
     case 'agentsRunning':
       supervisor.paused = !value;
       supervisor.onChange?.();
       break;
+    // WHO DECIDES THE NUMBER (w-e5225b62ba). Turning Automatic on does not
+    // throw away the number somebody set: it stays in the file, unread, so
+    // turning Automatic off again gives them their own number back rather than
+    // a fresh guess.
+    case 'agentsAuto':
+      saveConfig(config, { agentsAuto: !!value });
+      supervisor.wake?.();
+      supervisor.onChange?.();
+      break;
+    // SOMETHING FELT SLOW. The one lever a person has that no reading can
+    // replace: they are sitting in front of the Mac and the app is not. It only
+    // ever subtracts, and main/machine.mjs refuses to take it below one.
+    case 'agentsFeltSlow': {
+      const now = Math.max(0, Math.round(Number(config.agentsNudge) || 0));
+      saveConfig(config, { agentsNudge: value === 'reset' ? 0 : now + 1 });
+      supervisor.wake?.();
+      supervisor.onChange?.();
+      break;
+    }
     case 'sessionsAtOnce': {
       // THE MACHINE DOES NOT CLAMP THIS, and for one round it did. These are
       // developers using the tool as they want, so the range is the control's
       // own range, the same on every Mac. What the hardware does is SUGGEST a
       // starting number, one row up.
       const n = Math.max(1, Math.min(MAX_SLOTS, Math.round(Number(value) || 1)));
-      saveConfig(config, { maxConcurrentSessions: n });
+      // Setting a number by hand IS taking the decision back, so the page never
+      // shows a stepper that the supervisor is quietly ignoring.
+      saveConfig(config, { maxConcurrentSessions: n, agentsAuto: false });
+      // An explicit choice replaces the startup plan suggestion for BOTH
+      // engines. Leaving this marker set makes Codex ignore the new number
+      // until loadConfig runs again at restart. It is derived, not persisted.
+      config.planSlotsFrom = null;
+      // Fill newly available slots through the usual queue and its guards.
+      // Lowering the cap leaves existing work running and gates new starts.
+      supervisor.wake?.();
       break;
     }
     // Written as an opt-OUT (`diagnostics: false`) so that on is what a config
@@ -801,6 +972,32 @@ export function setWorkspaceSetting({ config, supervisor }, { key, value }) {
     // see in her own file. `saveConfig` mutates the live config too, and
     // main/analytics.mjs reads the switch at every send, so off takes effect
     // from the moment she moves it and not at the next launch.
+    // HOLD HEAVY WORK WHEN MEMORY IS SHORT (w-3958c3753d). Takes effect now:
+    // the coordinator starts or stops this moment, and workers spawned from
+    // here on carry the check or do not. A worker already running keeps the
+    // hooks it was started with; with the switch off its hook finds no socket
+    // and lets every command straight through.
+    case 'memoryGate':
+      saveConfig(config, { memoryGate: !!value });
+      supervisor.setMemoryGate?.(!!value)?.catch?.((e) => console.warn('zero: memory gate:', e.message));
+      supervisor.onChange?.();
+      break;
+    // STOP WHAT FINISHED AGENTS LEAVE RUNNING (main/leftovers.mjs). Turning it
+    // on records the moment, which is the earliest the clock may start from.
+    case 'cleanupLeftovers':
+      saveConfig(config, value ? { cleanupLeftovers: true, cleanupLeftoversSince: Date.now() } : { cleanupLeftovers: false });
+      supervisor.setLeftoverCleanup?.(!!value)?.catch?.((e) => console.warn('zero: leftovers:', e.message));
+      supervisor.onChange?.();
+      break;
+    case 'memoryGateSlots': {
+      const n = value === null || value === undefined || value === 'auto'
+        ? null
+        : Math.max(1, Math.min(MAX_SLOTS, Math.round(Number(value) || 1)));
+      saveConfig(config, { memoryGateSlots: n });
+      if (config.memoryGate) supervisor.setMemoryGate?.(true)?.catch?.(() => {});
+      supervisor.onChange?.();
+      break;
+    }
     case 'diagnostics':
       saveConfig(config, { diagnostics: !!value });
       break;

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 Mac 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 };
+  }
+}