agentbox-app 0.1.12 → 0.1.16

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,9 +157,40 @@ 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 !== '?');
+
+/**
+ * Light, however it was learned: `l` measured on its own, `c` only as part of
+ * a chain. Read the same everywhere, so `c` changes no verdict; it is there to
+ * be counted. Pinned by
+ * tests/the-record-says-whether-it-learned-light-from-a-chain.test.mjs.
+ */
+const isLight = (o) => o === 'l' || o === 'c';
+
 /**
  * The learned record. Each key and each program keeps its last ten
- * observations as letters: l light, m in between, h heavy, ? not measured.
+ * observations as letters: l light, c light but learned only inside a chain,
+ * m in between, h heavy, ? not measured. A build that predates `c` drops it on
+ * load, which costs those runs as evidence and holds a little more than it
+ * needs to; it cannot call anything light that is not.
  * Both maps are kept in least-recently-seen-first order so the oldest falls off
  * first when either passes `maxKeys`.
  */
@@ -167,27 +203,50 @@ 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;
+      // And only as a chain: the early return above means these records only
+      // ever hear about the chains that came out light, so they drift light.
+      // `c` marks that weaker evidence so it can be counted. It is read as `l`
+      // everywhere, so nothing is classified differently yet.
+      for (const key of keys) {
+        this._push(this.keys, key, 'c');
+        this._push(this.programs, programOf(key), 'c');
+      }
+      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. */
@@ -199,23 +258,29 @@ export class CommandHistory {
       if (v === 'heavy' || verdict === 'heavy') verdict = 'heavy';
       else if (v === 'unknown') verdict = 'unknown';
     };
-    if (keys.length > 1 || opaque) {
-      const chain = this.keys.get(chainKey(keys, opaque));
-      if (chain?.slice(-5).includes('h')) return 'heavy';
-      if (opaque) worse('unknown');
-    }
+    // A command's own record outranks the records of its parts: it is the only
+    // reading that covered everything the command starts, and the parts drift
+    // light (see `record`). The key is coarser than the command, so an old
+    // heavy run also holds back cheap variants that share it; that is the
+    // price. A middling run only keeps the command out of the light lane, where
+    // `lightLane` of them would start together, and `_holdsSlot` hands the slot
+    // back once a run measures small.
+    const own = measured(this.keys.get(keys.length > 1 || opaque ? chainKey(keys, opaque) : keys[0]));
+    if (own.includes('h')) return 'heavy';
+    if (own.includes('m')) worse('unknown');
+    if (opaque) worse('unknown');
     for (const key of keys) worse(this._classifyKey(key));
     return verdict;
   }
 
   _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.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';
+    if (recent.length >= 2 && recent.every(isLight)) return 'light';
+    if (recent.some((o) => !isLight(o))) return 'unknown';
+    const prog = measured(this.programs.get(programOf(key))?.slice(-10));
+    if (prog.length >= 5 && prog.every(isLight)) return 'light';
     return 'unknown';
   }
 
@@ -239,7 +304,7 @@ export class CommandHistory {
       if (!Array.isArray(entries)) return;
       for (const e of entries) {
         if (Array.isArray(e) && typeof e[0] === 'string' && Array.isArray(e[1])) {
-          map.set(e[0], e[1].filter((o) => ['l', 'm', 'h', '?'].includes(o)).slice(-10));
+          map.set(e[0], e[1].filter((o) => ['l', 'c', 'm', 'h', '?'].includes(o)).slice(-10));
         }
       }
     };

package/main/memory-gate-server.mjs

@@ -95,6 +95,11 @@ export class MemoryGateServer {
     socketPath = defaultSocketPath(),
     historyFile = null,
     history = null,
+    // One appended line per grant, so what the slots cost can be read later.
+    // Without it the only duration anywhere is a transcript's, which is waiting
+    // and running added together and cannot be separated.
+    grantLogFile = null,
+    grantLogMaxBytes = 4 * 1024 * 1024,
     gate = {},
     scoreFor = null,
     // WHOSE CODEX THREAD IS THIS (w-e5225b62ba). A Claude worker carries its row
@@ -104,6 +109,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,18 +122,28 @@ 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 = () => {},
   } = {}) {
     this.socketPath = socketPath;
     this.historyFile = historyFile;
+    this.grantLogFile = grantLogFile;
+    this.grantLogMaxBytes = grantLogMaxBytes;
     this.history = history ?? loadHistory(historyFile);
     this.clock = clock;
     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 +311,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 +344,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;
@@ -324,6 +362,10 @@ export class MemoryGateServer {
         res.end('');
       } else {
         this.counts.refused++;
+        this._writeGrant({
+          refused: true, cls: decision.cls, waitMs: decision.waitedMs, ranMs: null, peakMb: null,
+          pressure: decision.pressure, command,
+        });
         res.end(denyOutput(decision.reason));
       }
     });
@@ -341,13 +383,30 @@ 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,
+    this._writeGrant({
+      refused: false,
+      cls: was.cls,
+      waitMs: was.waitedMs ?? 0,
+      ranMs: this.clock() - was.startedAt,
+      peakMb: grant?.ambiguous ? null : was.peakMb,
+      shared: !!grant?.ambiguous,
+      pressure: was.pressureAt,
+      command: was.command,
+    });
+    // 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 +433,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 +447,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 +501,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
@@ -444,6 +521,47 @@ export class MemoryGateServer {
     this.lastPids = new Set(procs.map((p) => p.pid));
   }
 
+  /**
+   * One line per grant: what it was, how long it queued, how long it ran and
+   * its measured peak. `shared` says the peak is null because two commands on
+   * one agent process were measured together, without which a week of this
+   * reads as two commands where there was one.
+   *
+   * Every shell command on the Mac waits on this path, so a write that fails
+   * is logged and swallowed rather than returned to the agent.
+   */
+  _writeGrant({ refused, cls, waitMs, ranMs, peakMb, shared = false, pressure = null, command }) {
+    if (!this.grantLogFile) return;
+    try {
+      if (this.grantBytes === undefined) {
+        try { this.grantBytes = fs.statSync(this.grantLogFile).size; } catch { this.grantBytes = 0; }
+      }
+      // Bounded, and the one before it is kept, so a week is still readable
+      // across the two even when a busy day fills one.
+      if (this.grantBytes >= this.grantLogMaxBytes) {
+        fs.renameSync(this.grantLogFile, `${this.grantLogFile}.1`);
+        this.grantBytes = 0;
+      }
+      const line = `${JSON.stringify({
+        t: this.clock(),
+        cls: cls ?? null,
+        waitMs: Number.isFinite(waitMs) ? waitMs : null,
+        ranMs: Number.isFinite(ranMs) ? ranMs : null,
+        peakMb: Number.isFinite(peakMb) ? peakMb : null,
+        // Only a wait that happened while this was `normal` is evidence about
+        // the slot count; under `tight` nothing heavy starts whatever it is.
+        pressure: pressure ?? null,
+        ...(shared ? { shared: true } : {}),
+        ...(refused ? { refused: true } : {}),
+        cmd: String(command ?? '').slice(0, 300),
+      })}\n`;
+      fs.appendFileSync(this.grantLogFile, line);
+      this.grantBytes += Buffer.byteLength(line);
+    } catch (err) {
+      this.log(`memory gate: could not write the grant log: ${err.message}`);
+    }
+  }
+
   _saveHistory() {
     if (!this.historyFile || !this.dirty) return;
     try {

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,33 @@ 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({
+            reason: refusal(now - w.arrived, this.pressure),
+            allow: false,
+            cls: w.cls,
+            waitedMs: now - w.arrived,
+            pressure: 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 +248,12 @@ 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,
+      // Only the coordinator reads these, to write down what the grant cost.
+      // The pressure is what makes the wait mean anything: under `normal` only
+      // full slots can hold a command back, so the wait is evidence about
+      // `slots`; under `tight` nothing heavy starts whatever the count is.
+      waitedMs: now - w.arrived, pressureAt: this.pressure,
     });
     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/menu.mjs

@@ -159,8 +159,10 @@ export function installMenu({ onApproval, onReload, onZoom } = {}) {
     {
       label: 'Agents',
       submenu: [
-        { label: 'Allow Pending Approval', accelerator: 'Command+Y', click: () => onApproval?.(true) },
-        { label: 'Deny Pending Approval', accelerator: 'Command+N', click: () => onApproval?.(false) },
+        // CommandOrControl like every other accelerator here: Command alone
+        // left the approval card's hint naming two dead keys on Linux.
+        { label: 'Allow Pending Approval', accelerator: 'CommandOrControl+Y', click: () => onApproval?.(true) },
+        { label: 'Deny Pending Approval', accelerator: 'CommandOrControl+N', click: () => onApproval?.(false) },
       ],
     },
     {