agentbox-app 0.1.11 → 0.1.13

package/main/main.mjs

@@ -11,7 +11,7 @@ import { ensurePersonalProject } from './team/projects.mjs';
 import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { configDir, loadConfig } from './config.mjs';
+import { configDir, loadConfig, saveConfig } from './config.mjs';
 import { installMenu, applyZoom, requestFind } from './menu.mjs';
 import { zoomDeltaFor } from './zoom-keys.mjs';
 import { copySelection } from './copy-selection.mjs';
@@ -20,8 +20,14 @@ import { Store } from './store.mjs';
 import { storeRootEnv } from './store/home.mjs';
 import { Supervisor } from './supervisor.mjs';
 import { startCodexWatch } from './codex-watch.mjs';
+import { readCodexThreads } from './codex-threads.mjs';
+import { appSessionFolders } from './agent-homes.mjs';
 import { registerIpc } from './ipc.mjs';
-import { carryHerBriefsAcross, joinMessageRules, setAsideShippedMessageRules } from './instruction-settings.mjs';
+import { createPhoneLink } from './phone-link.mjs';
+import { relayAddress } from './relay-address.mjs';
+import { atTheApp } from '../shared/notify-rules.mjs';
+import { answerWhatOnlyTheWindowAnswered } from './serve.mjs';
+import { carryHerBriefsAcross, joinMessageRules, setAsideShippedMessageRules, unifyAgentInstructions } from './instruction-settings.mjs';
 import * as approvals from './approvals.mjs';
 import { recoveryToast } from '../shared/recovery.mjs';
 import { dataFolderName, isNewUserBuild } from '../shared/side-build.mjs';
@@ -30,10 +36,14 @@ import { openFreshUser } from './fresh-user.mjs';
 import { installCrashReports, reportFromRenderer, pending as pendingCrashes, setTransport } from './crash-report.mjs';
 import { createAnalytics, createDailyCount } from './analytics.mjs';
 import { createUpdater } from './updater.mjs';
+import { createPlace } from '../shared/where-it-runs-from.mjs';
 import { createSourceUpdater } from './source-updater.mjs';
+import { learnShellDataDirs, recoverShellPath } from './shell-path.mjs';
 import { installNotifier } from './notify.mjs';
+import { createCornerTag } from './corner-tag.mjs';
 import { DOC_SCHEMES, DocGrants, docPath } from './doc-scheme.mjs';
 import { quietTheFramesScrollbars } from './frame-scrollbars.mjs';
+import { letLocalAppsShowInThePane } from './local-app-frames.mjs';
 import { IMG_SCHEMES, imgPath, mediaResponse, mediaType, servable } from './img-scheme.mjs';
 import { hotWindowVerdict, storeHasWork } from './dev-window.mjs';
 import { writeHeldThenReload } from './write-before-reload.mjs';
@@ -206,6 +216,9 @@ try {
   // AND A BOX THAT AN OLDER JOIN FILLED WITH ONLY OUR TEXT IS EMPTIED, ONCE
   // (w-3ec9f07978). Kept as a restore point; our rules ride from the checkout.
   if (setAsideShippedMessageRules(appDir, userDir)) console.log('zero: the message rules box held only the shipped rules; set aside as a restore point');
+  // Both kinds of user rules now live in founder.md. Only user content is
+  // appended; the app's message defaults continue to come from the bundle.
+  if (unifyAgentInstructions(appDir, userDir)) console.log('zero: combined the general and writing instructions');
 } catch (err) {
   console.warn(`zero: could not carry her instructions into ${userDir}: ${err.message}`);
 }
@@ -272,6 +285,13 @@ function reloadRenderer() {
 }
 
 async function createWindow() {
+  const shellPath = await recoverShellPath();
+  process.env.PATH = shellPath.path;
+  if (shellPath.error) console.warn('agentbox: could not load your shell PATH; using the inherited PATH:', shellPath.error);
+  // Where the shell says Claude Code and Codex keep their sessions, for the
+  // import only and never into this environment (main/shell-path.mjs). Not
+  // waited for: it lands long before setup reaches its last card.
+  void learnShellDataDirs();
   const config = loadConfig(dataDir);
   // The store modules read the app's own home variable at call time; setting it
   // here points auth session files, sync, and every store path at its root.
@@ -396,7 +416,16 @@ async function createWindow() {
   // HER CODEX CONVERSATIONS ASK TO COME IN. Once a minute: a new one in a
   // folder a project points at gets a row asking yes or no, and the ones she
   // said yes to follow Codex's latest answer.
-  const codexWatch = startCodexWatch({ store });
+  // AND IT IS WHERE A CODEX AGENT IS COUNTED, because it is the one thing that
+  // already reads them (main/codex-watch.mjs). The switch is checked by
+  // `analytics.track` itself, so this hands it over unconditionally.
+  // Every Codex folder on the machine, read fresh each minute so a login made
+  // while the app is open is followed too (main/agent-homes.mjs).
+  const codexWatch = startCodexWatch({
+    store,
+    count: (name, props) => analytics.track(name, props),
+    readThreads: (opts) => readCodexThreads({ ...opts, codexDirs: appSessionFolders({ config, supervisor }).codexDirs }),
+  });
   app.on('before-quit', () => codexWatch.stop());
   // Whatever is still queued goes with the app rather than dying in memory.
   app.on('will-quit', () => { analytics.flush(); });
@@ -603,6 +632,11 @@ async function createWindow() {
     },
   });
 
+  // THE MENU IS A BAR INSIDE THE WINDOW on Linux and Windows. On macOS it is
+  // the system menu, so it stays. The menu itself stays everywhere: the Ctrl
+  // chords are bound to it, and taking the menu out would take them with it.
+  if (process.platform !== 'darwin') window.setMenuBarVisibility(false);
+
   // WHICH PICTURE SET THIS WINDOW IS ON, and a shout when it changes.
   // main/screen-detail.mjs has the rule and the reasoning; this is the wiring.
   // The initial answer rides bootInfo rather than being pushed, for the same
@@ -653,9 +687,16 @@ async function createWindow() {
   // AND A COPY RUN FROM SOURCE watches its git branch instead of a release
   // feed (main/source-updater.mjs), because that is how teammates run the team
   // build and their updates are pushes to main, not releases.
+  //
+  // AND WHERE THIS COPY IS RUNNING FROM (shared/where-it-runs-from.mjs). An
+  // app run out of the disk image, or out of a read-only copy macOS made of
+  // it, can never update itself, and until 2026-10-12 nothing in the app said
+  // so: two installs sat on 0.1.11 for a week. The fact rides the updater's
+  // state so the Settings row, the sidebar card and ⌘K all read one answer.
   let pushUpdate = () => {};
   const updater = app.isPackaged ? createUpdater({
     app,
+    place: createPlace({ app }),
     onChanged: () => pushUpdate(),
   }) : createSourceUpdater({
     app,
@@ -665,9 +706,25 @@ async function createWindow() {
 
   // The desktop door. `main/serve.mjs` is the other one and hands over plain
   // Node stand-ins for these three; everything else about the call is the same.
+  // THE PHONE DOOR (main/phone-link.mjs) answers with these same handlers, so
+  // each one is filed in a Map as Electron gets it. And every push the window
+  // gets is handed to the phones' event streams too.
+  const phoneChannels = new Map();
+  const phoneListeners = new Set();
+  const filingIpcMain = {
+    handle(channel, fn) { ipcMain.handle(channel, fn); phoneChannels.set(channel, fn); },
+  };
+  const filingHost = { ipcMain: filingIpcMain, app, dialog };
+  const sendToWindow = window.webContents.send.bind(window.webContents);
+  window.webContents.send = (channel, ...args) => {
+    sendToWindow(channel, ...args);
+    for (const send of phoneListeners) {
+      try { send({ channel, args }); } catch { /* a closed phone is not an error */ }
+    }
+  };
   const ipc = registerIpc({
     store, supervisor, config, window, analytics, docGrants, updater,
-    host: { ipcMain, app, dialog },
+    host: filingHost,
     team,
   });
   pushUpdate = ipc.push;
@@ -675,6 +732,33 @@ async function createWindow() {
   // See the `installMenu` call above for what writing the file instead did to a
   // Codex card.
   answerApproval = ipc.answerApproval;
+  // What the window answers itself (badge, boot info) a phone gets the plain
+  // stand-ins for, as a browser tab does.
+  answerWhatOnlyTheWindowAnswered({ handle: (channel, fn) => { if (!phoneChannels.has(channel)) phoneChannels.set(channel, fn); } });
+  const phone = createPhoneLink({
+    file: path.join(userDir, 'phone-link.json'),
+    channels: phoneChannels,
+    listeners: phoneListeners,
+    dist: path.join(appDir, 'renderer', 'dist'),
+    // Pictures and design pages, under the same two rules the window's own
+    // schemes use below: a page the pane was granted, and a picture inside a
+    // root the app owns (main/serve.mjs answerFile).
+    files: { allows: (kind, f) => (kind === 'doc' ? docGrants.allows(f) : servable(f, imageRoots())) },
+    // "Anywhere": the relay a phone reaches this Mac through from any network
+    // (main/relay-client.mjs). None until it is deployed, and then no choice.
+    relayUrl: relayAddress({ appDir }),
+    onChange: () => { if (!window.isDestroyed()) sendToWindow('zero:phone-changed'); },
+    // The phone stays quiet while she is at the desktop app, by the same rule
+    // the desktop's own notifications use (shared/notify-rules.mjs).
+    atDesk: () => {
+      try { return atTheApp({ focused: !window.isDestroyed() && window.isFocused(), idleMs: powerMonitor.getSystemIdleTime() * 1000 }); } catch { return false; }
+    },
+  });
+  window.on('focus', () => phone.seen());
+  // Settings' own channel, on the window only: a phone does not get to turn
+  // the phone door off or hand out its key.
+  ipcMain.handle('zero:phone-link', (_e, payload) => phone.act(payload ?? {}));
+  app.on('before-quit', () => phone.close());
   updater.start();
   // A task the app just shipped moved main: look now rather than in half an
   // hour, so the restart is offered while she still remembers the task.
@@ -847,6 +931,7 @@ async function createWindow() {
   // Unread badge + notification on new inbox arrivals are driven by the
   // renderer (it owns the definition of "inbox"), through the badge API.
   ipcMain.handle('zero:badge', (_e, count) => {
+    phone.count(count);
     if (process.platform === 'darwin') app.dock.setBadge(count > 0 ? String(count) : '');
   });
   // WHETHER to speak, and what to say, is not the renderer's call: only this
@@ -855,7 +940,21 @@ async function createWindow() {
   // a locked screen all read the same from in there). The renderer says what
   // arrived; main/notify.mjs decides. tell me when I am in another app, never
   // while I am in Agentbox.
-  installNotifier({ app, window, Notification, powerMonitor, ipcMain });
+  installNotifier({ app, window, Notification, powerMonitor, ipcMain, nativeImage, onArrivals: (arrivals) => phone.arrivals(arrivals) });
+  // THE CORNER TAG (w-dafae58a23): what is ready for her, floating over
+  // whatever app she is in. Its page is built beside the app's own, and comes
+  // from the dev server only when the app's own page does.
+  createCornerTag({
+    BrowserWindow, screen: electronScreen, ipcMain, Menu, powerMonitor, config, saveConfig, mainWindow: window,
+    preload: path.join(appDir, 'main', 'corner-tag-preload.cjs'),
+    // `part` is the tag itself or the list beside it, one page drawn twice.
+    load: (tagWindow, part) => {
+      const devTag = process.env.ZERO_DEV_URL;
+      const builtTag = path.join(appDir, 'renderer', 'dist', 'corner-tag.html');
+      if (devTag && !fs.existsSync(builtTag)) tagWindow.loadURL(`${devTag.replace(/\/$/, '')}/corner-tag.html?part=${part}`);
+      else tagWindow.loadFile(builtTag, { search: `part=${part}` });
+    },
+  });
   // Asked for once by the renderer as it mounts, rather than pushed on
   // did-finish-load, which races the first effects and would drop the very
   // message it exists to deliver.
@@ -899,6 +998,11 @@ async function createWindow() {
   // (frame-scrollbars.mjs). Without it, a mouse on macOS gets a white track.
   quietTheFramesScrollbars(window.webContents);
 
+  // A local app a worker names (http://localhost:3006) draws in the pane even
+  // when it refuses to be framed, and its sign-in cookie sticks there
+  // (main/local-app-frames.mjs).
+  letLocalAppsShowInThePane(window.webContents);
+
   // Escape must ALWAYS leave the junk browser, even when the guest page has
   // focus and would otherwise swallow the key. Intercept it below the page.
   app.on('web-contents-created', (_event, contents) => {
@@ -1014,6 +1118,17 @@ if (!app.requestSingleInstanceLock()) {
     }
   });
   app.whenReady().then(() => {
+    // A from-source Linux launch keeps the launcher command installed. The
+    // entry runs that command; this only refreshes where it points. A packaged
+    // build ships its own entry and must not write one from here.
+    // LOADED HERE AND NOT AT THE TOP: scripts/ is not in the packaged app or the
+    // npx package, and a static import of it stopped main.mjs loading at all,
+    // on every Mac (tests/the-mac-app-ships-every-file-it-starts-with).
+    if (process.platform === 'linux' && !app.isPackaged) {
+      import('../scripts/linux-launcher.mjs')
+        .then(({ installLinuxLauncher }) => installLinuxLauncher({ appDir, env: process.env }))
+        .catch(() => { /* a launcher is never a reason to stop a launch */ });
+    }
     // THE ABOUT BOX SAYS AGENTBOX AND ITS OWN VERSION (w-db6f5e331e). Run from
     // source it read the bundle's, which is Electron's: "Electron 43.0.0".
     app.setAboutPanelOptions({ applicationName: NAME, applicationVersion: app.getVersion(), version: '' });

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