agentbox-app 0.1.12 → 0.1.13

package/main/memory-gate-history.mjs

@@ -8,10 +8,15 @@
 // measured using, here, the last few times it ran.
 //
 // THE ONE RULE THAT IS NOT NEGOTIABLE: missing evidence never makes a command
-// light. Light means "seen light, more than once, and never heavy since". One
-// heavy run is enough to make that exact command heavy. A program that has been
-// light every time across many different arguments lends that to an argument
-// it has not seen, and stops the moment one of its runs is not light.
+// light. Light means "measured light, more than once, and never heavy since".
+// One heavy run is enough to make that exact command heavy. A program that has
+// been light every time it was measured, across many different arguments, lends
+// that to an argument it has not seen, and stops the moment one of its runs is
+// measured as anything else.
+//
+// AND MISSING EVIDENCE DOES NOT MAKE A COMMAND HEAVY EITHER (w-b689e9fc0c). A
+// run nothing measured is filed as `?` and read as nothing at all, rather than
+// as a run that might have been big: see `measured` below for what that cost.
 //
 // A RUN THAT ENDED INSIDE 2 SECONDS AND WAS NEVER SEEN BIG COUNTS AS LIGHT.
 // Measured on 2026-10-04 across 30 recent agent sessions (2006 commands): the
@@ -152,6 +157,26 @@ function basename(p) {
 
 const programOf = (key) => key.split(' ')[0];
 
+/**
+ * The observations that are evidence, which is all of them but `?`.
+ *
+ * `?` IS THE ABSENCE OF EVIDENCE AND IS READ AS NOTHING AT ALL (w-b689e9fc0c).
+ * It used to count against a command: `git branch` stood at "lllll?llll", nine
+ * light runs and one that nothing measured, and the single `?` inside the last
+ * five made every `git branch` command `unknown` — and because the command's own
+ * record had answered, the `git` program record, ten light runs with nothing else
+ * in it, was never reached. On a 16 GB M4 on 2026-10-07 that put
+ * `git fetch -q origin | tail -2; git branch -r --contains <sha> | head -3`
+ * behind one of two slots for 89 seconds to use 0 MB. One unmeasured run held
+ * that command back for its next nine, and a loaded Mac is precisely where runs
+ * go unmeasured, so the gate made itself hold more and more.
+ *
+ * The rule it must not break is the one above: missing evidence never makes a
+ * command light. It cannot, because a `?` is dropped rather than counted, and
+ * what is left still has to be light and still has to be more than one run.
+ */
+const measured = (list) => (list ?? []).filter((o) => o !== '?');
+
 /**
  * The learned record. Each key and each program keeps its last ten
  * observations as letters: l light, m in between, h heavy, ? not measured.
@@ -167,27 +192,41 @@ export class CommandHistory {
     this.programs = new Map();
   }
 
-  /** What one finished run tells us. `peakMb` null means it was never sampled. */
-  record(command, { peakMb = null, durationMs = null, background = false } = {}) {
+  /**
+   * What one finished run tells us. `peakMb` null means it was never sampled.
+   * Answers whether anything was filed.
+   *
+   * `onlyIfLight` is for a run whose memory reading belonged to several
+   * commands at once: one `codex app-server` serves every Codex thread of a
+   * login, so two Codex commands running together are measured together
+   * (w-5601e99977). How long each took is still its own, so a quick one is
+   * light on that alone — and anything else from such a run is dropped rather
+   * than filed as "not measured", because that would un-learn a command this
+   * app has seen light before, and missing evidence must never move a command
+   * either way.
+   */
+  record(command, { peakMb = null, durationMs = null, background = false, onlyIfLight = false } = {}) {
     const { keys, opaque } = commandSegments(command);
-    if (!keys.length) return;
+    if (!keys.length) return false;
     let obs;
     if (typeof peakMb === 'number' && Number.isFinite(peakMb)) {
       obs = peakMb >= this.heavyMb ? 'h' : peakMb < this.lightMb ? 'l' : 'm';
     } else {
       obs = !background && typeof durationMs === 'number' && durationMs < QUICK_MS ? 'l' : '?';
     }
+    if (onlyIfLight && obs !== 'l') return false;
     // A chain's memory belongs to the chain: `git status && npm test` measured
     // heavy says nothing bad about `git status`. Only a light chain vouches for
     // each of its parts.
     if (keys.length > 1 || opaque) {
       this._push(this.keys, chainKey(keys, opaque), obs);
-      if (obs !== 'l') return;
+      if (obs !== 'l') return true;
     }
     for (const key of keys) {
       this._push(this.keys, key, obs);
       this._push(this.programs, programOf(key), obs);
     }
+    return true;
   }
 
   /** 'light' | 'unknown' | 'heavy' for a command about to run. */
@@ -210,12 +249,12 @@ export class CommandHistory {
 
   _classifyKey(key) {
     const own = this.keys.get(key);
-    const recent = own?.slice(-5) ?? [];
+    const recent = measured(own?.slice(-5));
     if (recent.includes('h')) return 'heavy';
-    if (own && own.length >= 2 && recent.every((o) => o === 'l')) return 'light';
+    if (recent.length >= 2 && recent.every((o) => o === 'l')) return 'light';
     if (recent.some((o) => o !== 'l')) return 'unknown';
-    const prog = this.programs.get(programOf(key));
-    if (prog && prog.length >= 5 && prog.slice(-10).every((o) => o === 'l')) return 'light';
+    const prog = measured(this.programs.get(programOf(key))?.slice(-10));
+    if (prog.length >= 5 && prog.every((o) => o === 'l')) return 'light';
     return 'unknown';
   }
 

package/main/memory-gate-server.mjs

@@ -104,6 +104,10 @@ export class MemoryGateServer {
     // the app-server's own `thread.id`. Answering null means "not this app's",
     // and such a command is let straight through.
     ownerOf = null,
+    // IS THIS ROW HER URGENT ONE (w-713aba0c89), asked live on every command so
+    // a row raised to Urgent counts at once. Only the app answers it: nothing in
+    // a worker's own request can make its command urgent.
+    urgentFor = null,
     readPressure = readMacPressure,
     sampleProcesses = listProcesses,
     pollMs = 2_000,
@@ -113,6 +117,12 @@ export class MemoryGateServer {
     lockPort = DEFAULT_LOCK_PORT,
     idleReleaseMs = 30_000,
     maxGrantMs = 3 * 60 * 60_000,
+    // How long a grant may hold a slot when its end can never be observed,
+    // because its memory reading is shared with another command on the same
+    // agent process. Null means the longest the gate will make anything wait:
+    // a grant nobody can see the end of must not outlive the wait it causes,
+    // or a queue is refused one by one while a phantom holds the slot.
+    sharedGrantMs = null,
     clock = Date.now,
     log = () => {},
   } = {}) {
@@ -123,8 +133,10 @@ export class MemoryGateServer {
     this.idleReleaseMs = idleReleaseMs;
     this.maxGrantMs = maxGrantMs;
     this.gate = new MemoryGate({ ...gate, history: this.history, clock });
+    this.sharedGrantMs = Number.isFinite(sharedGrantMs) ? sharedGrantMs : this.gate.maxWaitMs;
     this.scoreFor = scoreFor;
     this.ownerOf = ownerOf;
+    this.urgentFor = urgentFor;
     this.readPressure = readPressure;
     this.sampleProcesses = sampleProcesses;
     this.pollMs = pollMs;
@@ -292,7 +304,24 @@ export class MemoryGateServer {
     let owner;
     try { owner = this.ownerOf(session); } catch { return null; }
     if (!owner?.item) return null;
-    return { item: String(owner.item), product: owner.product ?? null };
+    return { item: String(owner.item), product: owner.product ?? null, session };
+  }
+
+  /**
+   * A CODEX THREAD'S TURN IS OVER: LET GO OF EVERY GRANT IT STILL HOLDS
+   * (w-713aba0c89). Codex sends no "after" report for a command that failed, so
+   * such a grant outlives its command, and on a shared app-server nothing else
+   * ever sees it end. A turn that has ended is waiting on none of its commands.
+   * Only grants that named this thread are touched: a Claude worker's names its
+   * row, and goes when its own process does.
+   */
+  releaseSession(session) {
+    if (typeof session !== 'string' || !session) return;
+    for (const r of [...this.gate.running.values()]) {
+      if (r.session !== session) continue;
+      this.grants.delete(r.id);
+      this.gate.finish(r.id);
+    }
   }
 
   _pre(body, req, res) {
@@ -308,10 +337,12 @@ export class MemoryGateServer {
     const id = String(hook.tool_use_id || `${body.ppid}-${Date.now()}-${Math.random()}`);
     const live = typeof this.scoreFor === 'function' ? this.scoreFor(whose.product, whose.item) : null;
     const score = Number.isFinite(live) ? live : Number(body.score) || 0;
+    let urgent = false;
+    try { urgent = typeof this.urgentFor === 'function' && this.urgentFor(whose.product, whose.item) === true; } catch { urgent = false; }
     this.counts.asked++;
     let answered = false;
     this.gate.submit({
-      id, command, score, item: whose.item, product: whose.product,
+      id, command, score, urgent, item: whose.item, product: whose.product, session: whose.session ?? null,
       background: !!hook?.tool_input?.run_in_background,
     }, (decision) => {
       answered = true;
@@ -341,13 +372,20 @@ export class MemoryGateServer {
     this.grants.delete(id);
     const was = this.gate.finish(id);
     if (!was) return;
-    if (grant?.ambiguous) return;
-    this.history.record(was.command, {
-      peakMb: was.peakMb,
+    // A SHARED READING IS NOT NO READING (w-5601e99977). Every Codex thread of
+    // a login runs under one `codex app-server`, so two Codex commands at once
+    // are measured together and neither may claim the figure. How long each
+    // took is its own, though, and a run that was over inside QUICK_MS counts
+    // as light on that alone, so `onlyIfLight` files that verdict and nothing
+    // else. Before this, Codex taught the history almost nothing and rode on
+    // what Claude workers taught it.
+    const filed = this.history.record(was.command, {
+      peakMb: grant?.ambiguous ? null : was.peakMb,
       durationMs: Number(hook.duration_ms) || null,
       background: was.background,
+      onlyIfLight: !!grant?.ambiguous,
     });
-    this.dirty = true;
+    if (filed) this.dirty = true;
   }
 
   /* ------------------------------ measuring ------------------------------ */
@@ -374,7 +412,8 @@ export class MemoryGateServer {
    * One look at every process. Each grant finds the agent process it belongs to
    * (the nearest `claude` or `codex` above the hook), and is measured as the
    * new processes under that agent since it was granted. Two grants on one
-   * agent at once share what they find and teach the history nothing.
+   * agent at once share what they find, so neither claims that figure; each
+   * still teaches the history how long it took (`_post`).
    */
   _sample(procs) {
     const byPid = new Map(procs.map((p) => [p.pid, p]));
@@ -387,9 +426,23 @@ export class MemoryGateServer {
     const now = this.clock();
     for (const grant of this.grants.values()) {
       if (!this.gate.running.has(grant.id)) { this.grants.delete(grant.id); continue; }
-      // The last resort, for a grant whose agent could never be found: no
-      // report back and nothing to measure for three hours is over.
-      if (!grant.anchor && now - grant.startedAt >= this.maxGrantMs) {
+      // THE BACKSTOPS THAT DO NOT DEPEND ON WHAT IS RUNNING (w-5601e99977).
+      // Both of the other releases need a reading of the grant's own
+      // processes, and a Codex grant never gets one: its anchor is the shared
+      // app-server, where a sibling thread's work keeps the reading above zero
+      // for good. So a grant that was ever measured together with another
+      // (`ambiguous`, which nothing clears) is let go after `sharedGrantMs`,
+      // and no grant at all outlives `maxGrantMs`. This used to be checked
+      // only while no anchor had been found, so a Codex command whose "after"
+      // report was lost held one of two heavy slots until the app-server was
+      // replaced.
+      //
+      // LETTING A SLOT GO IS NOT LETTING GO OF THE MACHINE. Nothing is
+      // stopped, and if the command really is still running and really is big,
+      // the kernel's own pressure reading holds the next heavy command back
+      // anyway.
+      const held = now - grant.startedAt;
+      if (held >= this.maxGrantMs || (grant.ambiguous && held >= this.sharedGrantMs)) {
         this.grants.delete(grant.id);
         this.gate.finish(grant.id);
         continue;
@@ -427,7 +480,10 @@ export class MemoryGateServer {
         stack.push(...(children.get(p.pid) ?? []));
       }
       for (const g of grants) {
-        if (grants.length > 1) g.ambiguous = true;
+        if (grants.length > 1) {
+          g.ambiguous = true;
+          this.gate.share(g.id, anchorPid);
+        }
         this.gate.observe(g.id, Math.round(mb));
         // NOTHING RUNNING UNDER IT FOR A WHILE: its "after" report was lost
         // (the hook was killed, the agent crashed mid-call). Every running

package/main/memory-gate.mjs

@@ -33,6 +33,15 @@
 //     trips its own time limits, and stays frozen forever if the app dies.
 //   - No command waits forever. After `maxWaitMs` the agent is told no, with a
 //     reason it can act on, and the hook's own time limit sits above that.
+//   - AN URGENT ROW DOES NOT QUEUE (w-713aba0c89). Her only Urgent row on
+//     2026-10-07 was first in line for 34 minutes while no slot came free, so
+//     first in line bought nothing. Its commands now run whatever the slots and
+//     whatever "tight" says, and wait only while memory is critical. They still
+//     take a slot while they run, so everything else waits behind them.
+//   - COMMANDS MEASURED AS ONE FIGURE HOLD ONE SLOT (w-713aba0c89). Every Codex
+//     thread runs under one app-server, so two Codex commands at once read as
+//     the same number, and a `cat` beside a test run used to hold a slot of its
+//     own off the test run's gigabyte. A command known heavy still holds its own.
 
 import { CommandHistory, HEAVY_MB } from './memory-gate-history.mjs';
 import { NAME } from '../shared/product-name.mjs';
@@ -66,11 +75,23 @@ export const DEFAULTS = {
   agingMs: 5 * 60_000,
 };
 
-export function refusal(waitedMs) {
+/**
+ * IT SAYS WHICH OF THE TWO REASONS IT WAS (w-8386b3fd47). This sentence is the
+ * only account an agent ever gets of why its command did not run, and it used to
+ * blame memory either way. Two sessions were refused ordinary file reads while
+ * the coordinator itself reported normal pressure and 42% free, read the
+ * sentence, believed the machine was out of memory and spent their turns looking
+ * for a fault that was not there. A queue behind heavier work and a computer that
+ * is genuinely short are different things to be told.
+ */
+export function refusal(waitedMs, pressure = 'normal') {
   const minutes = Math.max(1, Math.round(waitedMs / 60_000));
-  return `This computer is short of memory, so ${NAME} held this command for ${minutes} minute${minutes === 1 ? '' : 's'} `
-    + 'while heavier work ran, and it still cannot start it. Do not retry it straight away. Carry on with anything '
-    + 'that does not need it, or end your turn and say you are waiting for memory.';
+  const held = `${NAME} held this command for ${minutes} minute${minutes === 1 ? '' : 's'}`;
+  const why = pressure === 'normal'
+    ? `${held} behind heavier work that has not finished, and it still cannot start it.`
+    : `This computer is short of memory, so ${held} while heavier work ran, and it still cannot start it.`;
+  return `${why} Do not retry it straight away. Carry on with anything that does not need it, `
+    + 'or end your turn and say what you are waiting for.';
 }
 
 export class MemoryGate {
@@ -109,6 +130,8 @@ export class MemoryGate {
       product: req.product ?? null,
       command: String(req.command ?? ''),
       score: Number.isFinite(Number(req.score)) ? Number(req.score) : 0,
+      urgent: req.urgent === true,
+      session: req.session ?? null,
       background: !!req.background,
       cls: this.history.classify(req.command),
       arrived: this.clock(),
@@ -133,6 +156,17 @@ export class MemoryGate {
     r.peakMb = Math.max(r.peakMb ?? 0, mb);
   }
 
+  /**
+   * This running command's memory reading is shared with others on the same
+   * agent process (`group`), so it is not its own figure. Nothing clears it.
+   */
+  share(id, group) {
+    const r = this.running.get(String(id));
+    if (!r || r.shared === group) return;
+    r.shared = group;
+    this._pump();
+  }
+
   tick() { this._pump(); }
 
   snapshot() {
@@ -172,18 +206,25 @@ export class MemoryGate {
     for (const w of [...this.waiting.values()]) {
       if (now - w.arrived >= this.maxWaitMs) {
         this.waiting.delete(w.id);
-        for (const r of w.replies) r({ allow: false, reason: refusal(now - w.arrived) });
+        for (const r of w.replies) r({ allow: false, reason: refusal(now - w.arrived, this.pressure) });
       }
     }
     if (this.pressure === 'critical') return;
     let slotsUsed = 0;
     let lightUsed = 0;
+    const sharedGroups = new Set();
     for (const r of this.running.values()) {
-      if (this._holdsSlot(r, now)) slotsUsed++;
-      else if (r.cls === 'light') lightUsed++;
+      if (this._holdsSlot(r, now)) {
+        if (r.shared != null && r.cls !== 'heavy') {
+          if (sharedGroups.has(r.shared)) continue;
+          sharedGroups.add(r.shared);
+        }
+        slotsUsed++;
+      } else if (r.cls === 'light') lightUsed++;
     }
     let blocked = false;
     for (const w of this._ordered(now)) {
+      if (w.urgent) { this._admit(w, now); slotsUsed++; continue; }
       if (w.cls === 'light') {
         if (lightUsed < this.lightLane) { this._admit(w, now); lightUsed++; }
         continue;
@@ -199,7 +240,7 @@ export class MemoryGate {
     this.waiting.delete(w.id);
     this.running.set(w.id, {
       id: w.id, item: w.item, product: w.product, command: w.command, cls: w.cls,
-      background: w.background, startedAt: now, peakMb: null,
+      urgent: w.urgent, session: w.session, background: w.background, startedAt: now, peakMb: null, shared: null,
     });
     for (const r of w.replies) r({ allow: true, cls: w.cls });
   }

package/main/memory-log.mjs

@@ -0,0 +1,124 @@
+// A LINE A MINUTE: HOW SHORT MEMORY IS, AND WHICH TASK IS HOLDING IT (w-ec27ff1a51).
+//
+// 2026-10-11 the Mac ran out of memory with Agentbox at 22 GB. By the time
+// anyone looked it had calmed down, and nothing had been written down, so which
+// task had been holding the memory could only be guessed. This writes one JSON
+// line a minute to `memory-<day>.jsonl` in the app's own folder, kept a week:
+// the kernel's reading, the agents running and the limit, whether new agents
+// were being held (main/start-hold.mjs), the app's own processes, every task's
+// programs with what they hold, and the biggest programs that are not ours.
+//
+// It stays on this computer. Nothing here is sent anywhere.
+//
+// A program belongs to the task of the nearest process at or above it that
+// carries ZERO_ITEM (main/leftovers.mjs reads the tag), which is what catches a
+// dev server that renamed itself and hid its environment.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { listProcesses } from './leftovers.mjs';
+import { readMacPressure } from './memory-gate-server.mjs';
+import { pressureFrom } from './memory-gate.mjs';
+
+/** Days of files kept, today included. */
+export const KEEP_DAYS = 7;
+const FILE = /^memory-(\d{4}-\d{2}-\d{2})\.jsonl$/;
+
+const name = (exe) => String(exe ?? '').split('/').filter(Boolean).pop() || String(exe ?? '');
+const top = (list, n) => [...list].sort((a, b) => b.mb - a.mb).slice(0, n).map((p) => ({ name: name(p.exe), mb: Math.round(p.mb) }));
+
+/** One minute's line, from one listing. Pure. */
+export function summarizeMemory(procs, { appPid = process.pid, at = Date.now(), reading = {} } = {}) {
+  const byPid = new Map(procs.map((p) => [p.pid, p]));
+  const owner = new Map();
+  const ownerOf = (p) => {
+    if (owner.has(p.pid)) return owner.get(p.pid);
+    let found = null;
+    const seen = new Set();
+    for (let q = p; q && !seen.has(q.pid); q = byPid.get(q.ppid)) {
+      seen.add(q.pid);
+      if (q.item) { found = { item: q.item, product: q.product ?? null }; break; }
+      if (q.pid === appPid) { found = 'app'; break; }
+    }
+    owner.set(p.pid, found);
+    return found;
+  };
+  const tasks = new Map();
+  const app = [];
+  const others = [];
+  for (const p of procs) {
+    const o = ownerOf(p);
+    if (o === 'app') app.push(p);
+    else if (o) {
+      const t = tasks.get(o.item) ?? { item: o.item, product: o.product, list: [] };
+      t.product ??= o.product;
+      t.list.push(p);
+      tasks.set(o.item, t);
+    } else others.push(p);
+  }
+  const sum = (list) => Math.round(list.reduce((n, p) => n + (Number(p.mb) || 0), 0));
+  const level = Number.isFinite(reading?.level) ? reading.level : null;
+  const freePct = Number.isFinite(reading?.freePct) ? reading.freePct : null;
+  return {
+    at: new Date(at).toISOString(),
+    pressure: level === null && freePct === null ? null : pressureFrom({ level, freePct }),
+    level,
+    freePct,
+    totalMb: sum(procs),
+    app: { mb: sum(app), procs: app.length },
+    tasks: [...tasks.values()]
+      .map((t) => ({ item: t.item, product: t.product, mb: sum(t.list), procs: t.list.length, top: top(t.list, 3) }))
+      .sort((a, b) => b.mb - a.mb),
+    others: top(others, 5),
+  };
+}
+
+const dayOf = (ms) => {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+};
+
+export class MemoryLog {
+  constructor({
+    dir, appPid = process.pid, list = listProcesses, readPressure = readMacPressure,
+    now = Date.now, facts = () => ({}), keepDays = KEEP_DAYS,
+  }) {
+    Object.assign(this, { dir, appPid, list, readPressure, now, facts, keepDays });
+    this._pruned = null;
+  }
+
+  /** Writes this minute's line. Never throws: a log that breaks the app is worse than a gap in the log. */
+  async tick() {
+    if (this._busy) return;
+    this._busy = true;
+    try {
+      const [procs, reading] = await Promise.all([
+        Promise.resolve().then(() => this.list()).catch(() => []),
+        Promise.resolve().then(() => this.readPressure()).catch(() => ({})),
+      ]);
+      const at = this.now();
+      let facts = {};
+      try { facts = this.facts() ?? {}; } catch { /* the line goes without them */ }
+      const line = { ...summarizeMemory(procs, { appPid: this.appPid, at, reading }), ...facts };
+      fs.mkdirSync(this.dir, { recursive: true });
+      fs.appendFileSync(path.join(this.dir, `memory-${dayOf(at)}.jsonl`), `${JSON.stringify(line)}\n`);
+      this._prune(at);
+    } catch (err) {
+      console.warn('zero: memory log:', err.message);
+    } finally {
+      this._busy = false;
+    }
+  }
+
+  /** Once a day: removes this log's own files older than `keepDays`, and nothing else. */
+  _prune(at) {
+    const today = dayOf(at);
+    if (this._pruned === today) return;
+    this._pruned = today;
+    const oldest = dayOf(new Date(at).setDate(new Date(at).getDate() - (this.keepDays - 1)));
+    for (const f of fs.readdirSync(this.dir)) {
+      const m = f.match(FILE);
+      if (m && m[1] < oldest) fs.rmSync(path.join(this.dir, f), { force: true });
+    }
+  }
+}

package/main/notify.mjs

@@ -13,16 +13,46 @@
 // AND ONCE, NOT TWENTY TIMES. One at a time is not once. `spoke` below is the
 // fix, and shared/notify-rules.mjs carries the rule.
 
+import path from 'node:path';
 import { atTheApp, banner, shouldSpeak } from '../shared/notify-rules.mjs';
 import { NAME } from '../shared/product-name.mjs';
 
+// THE MARK THE BANNER WEARS, and why it is a png and not the .icns every other
+// part of this repo uses.
+//
+// macOS draws the app's OWN bundle icon down the left of a banner, and no app
+// can override that. From a source checkout the bundle being asked is the
+// Electron.app in node_modules, which scripts/brand-electron.mjs renames and
+// re-icons, and macOS still drew a generic grey square: "it shows a plain
+// placeholder", looking at a real one, 2026-10-07.
+//
+// An image handed to the notification is the half we DO control; macOS attaches
+// it to the banner. Measured the same day in the Electron the app runs from:
+// nativeImage.createFromPath on build/icon.icns comes back empty, 0x0, so the
+// icns is not a candidate however convenient it would be. The png beside it,
+// drawn from the same art, reads 256x256.
+//
+// AN EMPTY IMAGE IS NOT A MARK. createFromPath answers a missing or unreadable
+// file with an empty image rather than an error, so "it returned something" is
+// the wrong question, and handing that something to macOS is how this goes
+// quietly back to a grey square. Returns null when there is nothing to show,
+// and the banner then looks exactly as it did before any of this.
+export const MARK_FILE = path.join('build', 'notification-icon.png');
+
+export function markFor({ root, createFromPath }) {
+  try {
+    const img = createFromPath(path.join(root, MARK_FILE));
+    return img && !img.isEmpty() ? img : null;
+  } catch { return null; }
+}
+
 // A BURST IS ONE PIECE OF NEWS. Four workers finishing inside the same
 // supervisor tick is the ordinary case, and it arrives as four pushes over a
 // second or two. Waiting a beat before speaking turns that into one banner
 // with one sound instead of four rewrites and four chimes.
 const COALESCE_MS = 1500;
 
-export function createNotifier({ window, Notification, powerMonitor, coalesceMs = COALESCE_MS }) {
+export function createNotifier({ window, Notification, powerMonitor, icon = null, coalesceMs = COALESCE_MS }) {
   // Everything she has not seen since she last had the window, keyed by id so
   // a repeated push is idempotent. Insertion order is arrival order.
   const unseen = new Map();
@@ -81,6 +111,9 @@ export function createNotifier({ window, Notification, powerMonitor, coalesceMs
         title: say.title,
         body: say.body,
         silent: false,
+        // Omitted rather than passed empty when there is nothing to show, so a
+        // banner with no mark is byte for byte the banner that shipped before.
+        ...(icon ? { icon } : {}),
       });
     } catch { return; }
     // A banner she can act on. Clicking it brings Agentbox forward and opens the
@@ -138,18 +171,28 @@ export function createNotifier({ window, Notification, powerMonitor, coalesceMs
   };
 }
 
-export function installNotifier({ app, window, Notification, powerMonitor, ipcMain }) {
+// `onArrivals` hears every arrival too, for the phone's alerts
+// (main/phone-link.mjs), which make their own call about speaking.
+export function installNotifier({ app, window, Notification, powerMonitor, ipcMain, nativeImage, onArrivals = () => {} }) {
   if (Notification.isSupported && !Notification.isSupported()) {
+    ipcMain.handle('zero:notify', (_e, payload = {}) => { try { onArrivals(Array.isArray(payload.arrivals) ? payload.arrivals : []); } catch {} });
     return { add() {}, seen() {} };
   }
-  const notifier = createNotifier({ window, Notification, powerMonitor });
+  // app.getAppPath() is the repo from source and the asar inside the bundle
+  // when it is packaged, and the mark sits at the same place in both.
+  const icon = nativeImage
+    ? markFor({ root: app.getAppPath(), createFromPath: (p) => nativeImage.createFromPath(p) })
+    : null;
+  const notifier = createNotifier({ window, Notification, powerMonitor, icon });
   window.on('focus', () => notifier.seen());
   // Unlocking with Agentbox already the front app never fires 'focus' (it never
   // lost it), so without this the banner that fired while the screen was
   // locked would sit in Notification Center after she is back at the row.
   try { powerMonitor.on('unlock-screen', () => { if (window.isFocused()) notifier.seen(); }); } catch {}
   ipcMain.handle('zero:notify', (_e, payload = {}) => {
-    notifier.add(Array.isArray(payload.arrivals) ? payload.arrivals : []);
+    const arrivals = Array.isArray(payload.arrivals) ? payload.arrivals : [];
+    try { onArrivals(arrivals); } catch {}
+    notifier.add(arrivals);
   });
   return notifier;
 }