agentbox-app 0.1.7 → 0.1.12

package/main/main.mjs

@@ -1,7 +1,13 @@
 // The app: the agent inbox. Electron shell around a keyboard-first renderer, a
 // file-derived store, and a supervisor of headless sessions.
 
-import { app, BrowserWindow, Menu, Notification, clipboard, crashReporter, dialog, ipcMain, nativeImage, net, powerMonitor, protocol, screen as electronScreen, shell, session } from 'electron';
+import { app, BrowserWindow, Menu, Notification, clipboard, crashReporter, dialog, ipcMain, nativeImage, net, powerMonitor, protocol, screen as electronScreen, shell, session, safeStorage } from 'electron';
+import * as workItemsDisk from './store/work-items.mjs';
+import { createTeamService, teamStateFile } from './team/index.mjs';
+import { loadCloudConfig, supabaseSession } from './team/session.mjs';
+// MY WORKSPACE IS NOT A TEAM FEATURE ANY MORE (w-f8d123be62), even though it
+// still lives in the team folder next to the sharing rules it has to obey.
+import { ensurePersonalProject } from './team/projects.mjs';
 import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -15,19 +21,22 @@ import { storeRootEnv } from './store/home.mjs';
 import { Supervisor } from './supervisor.mjs';
 import { startCodexWatch } from './codex-watch.mjs';
 import { registerIpc } from './ipc.mjs';
-import { carryHerBriefsAcross, joinMessageRules } from './instruction-settings.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';
 import { runningAsAFreshUser } from '../shared/fresh-user-home.mjs';
 import { openFreshUser } from './fresh-user.mjs';
 import { installCrashReports, reportFromRenderer, pending as pendingCrashes, setTransport } from './crash-report.mjs';
-import { createAnalytics } from './analytics.mjs';
+import { createAnalytics, createDailyCount } from './analytics.mjs';
 import { createUpdater } from './updater.mjs';
+import { createSourceUpdater } from './source-updater.mjs';
 import { installNotifier } from './notify.mjs';
 import { DOC_SCHEMES, DocGrants, docPath } from './doc-scheme.mjs';
-import { IMG_SCHEMES, imgPath, servable } from './img-scheme.mjs';
+import { quietTheFramesScrollbars } from './frame-scrollbars.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';
 import { IS_SHE_TYPING_IN_THE_PAGE, theAppKeepsThisInput, theAppKeepsThisLetterInAPage } from '../shared/artifact-keys.mjs';
 import { NAME, Name, WAS } from '../shared/product-name.mjs';
 
@@ -99,6 +108,15 @@ const appDir = path.join(__dirname, '..');
 // live. This has to happen before ANYTHING reads a path, because everything
 // downstream keys off app.getName, the single-instance lock at the foot of
 // this file included.
+// THE TEAM VERSION RUNS BESIDE THE ONE IN USE TODAY (2026-10-01). Run from
+// source, this checkout is named exactly like the solo app, so it would read
+// her data folder, take her single-instance lock and quit on the spot. A
+// profile (`AGENTBOX_PROFILE=team npx electron .`) gives it a name of its own,
+// and with the name a data folder and a lock of its own. Letters, digits and
+// dashes only, and never a space: "agentbox team" reads as a side build, and
+// side builds share the real data folder on purpose.
+const PROFILE = String(process.env.AGENTBOX_PROFILE ?? '').trim().replace(/[^a-z0-9-]/gi, '');
+if (PROFILE) app.setName(`${NAME}-${PROFILE}`);
 if (dataFolderName(app.getName()) !== app.getName()) app.setName(dataFolderName(app.getName()));
 
 // "ASTRAL NEW USER" IS A STRANGER EVERY TIME IT OPENS.
@@ -132,7 +150,8 @@ if (isNewUserBuild(app.getName()) && !runningAsAFreshUser()) {
 // existing user's folder is called the app, not the app, so a bare the app check would
 // have found nothing and handed them an empty Powerup. Whoever renames this app
 // a third time adds one entry here and nothing else.
-try {
+// A profile never falls back to an older folder: an older folder is hers.
+if (!PROFILE) try {
   const named = path.join(app.getPath('appData'), app.getName());
   if (!fs.existsSync(named)) {
     // THESE ARE HISTORY AND NOT COPY. They are the folder names this app has
@@ -184,6 +203,12 @@ try {
   // supervisor exists, so nothing has read the new name yet.
   const joined = joinMessageRules(appDir, userDir);
   if (joined) console.log(`zero: joined the message rules into one file, ${joined.total} characters`);
+  // 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}`);
 }
@@ -235,8 +260,18 @@ function reloadRenderer() {
   // identical build unless something records that it arrived at all.
   console.log(`zero: reload requested, renderer built ${new Date(builtAt()).toLocaleTimeString()}`);
   if (!window || window.isDestroyed()) return;
-  reloadRequested = true;
-  window.webContents.reloadIgnoringCache();
+  // The page may be holding something she did in the last three seconds (a
+  // close, an answer, a reply) for Z to take back. It is written first, or the
+  // reload throws it away and the thread comes back to her inbox
+  // (w-47218417a5). See write-before-reload.mjs.
+  void writeHeldThenReload({
+    webContents: window.webContents,
+    ipcMain,
+    reload: () => {
+      reloadRequested = true;
+      window.webContents.reloadIgnoringCache();
+    },
+  });
 }
 
 async function createWindow() {
@@ -290,6 +325,8 @@ async function createWindow() {
   // died are finally sent, because a report is written while the process is
   // dying and delivery cannot be synchronous.
   const analytics = createAnalytics({ config, version: app.getVersion(), dir: crashDir });
+  // "Used today", once a day, at launch and whenever the window comes forward.
+  const usedToday = createDailyCount((name) => analytics.track(name));
   // The seam is filled whenever there is somewhere to send to. Whether anything
   // actually goes is asked again inside, at every send, so her switch stops it
   // from the moment she moves it rather than at the next launch.
@@ -298,10 +335,23 @@ async function createWindow() {
     const drained = analytics.drainCrashes(pendingCrashes());
     if (drained) console.log(`zero: sent ${drained} crash report(s) from a previous launch`);
     analytics.track('app_opened');
+    usedToday(Date.now());
   } else {
     console.log(`zero: diagnostics is ${analytics.reason}, nothing is sent`);
   }
 
+  // EVERYBODY HAS SOMEWHERE TO SEND A THREAD (w-f8d123be62, approved
+  // 2026-10-05). My Workspace used to be made inside `signedIn()`, so the
+  // single-person app — a Mac with no team cloud, which never builds the team
+  // service at all — opened on no projects whatsoever: the chip read "No
+  // project", Send was off, and nothing said why. It is made HERE, before the
+  // store reads the account root, so the first list of projects already has it
+  // and no second pass is needed. Made once and never remade; a Mac that cannot
+  // write it still starts, and the card now says so out loud rather than
+  // leaving a dead button (renderer/src/compose-says.ts noProjectYet).
+  try {
+    ensurePersonalProject(config.accountRoot);
+  } catch (err) { console.warn(`zero: could not make My Workspace: ${err.message}`); }
   const store = await new Store(config).init();
   // Where the window's own pictures may come from (main/img-scheme.mjs). The
   // account root holds every product's docs, attachments, designs and the
@@ -310,7 +360,42 @@ async function createWindow() {
   // request so a project made after launch is not a folder of broken images.
   imageRoots = () => [config.accountRoot, ...store.listProducts().map((p) => p.repoPath).filter(Boolean)];
   const supervisor = new Supervisor(config, store, appDir, dataDir, userDir);
+  // THAT agents start and stop work (main/analytics.mjs checks the switch).
+  supervisor.count = (name, props) => analytics.track(name, props);
   app.on('before-quit', () => supervisor.killAll());
+  // THE TEAM. Off entirely on a build with no team cloud (the single-person
+  // app). Otherwise it restores whoever was signed in, and from then on every
+  // line this Mac writes says who wrote it and shared projects stay in sync.
+  // Its session file sits beside the store, encrypted with the Mac's own
+  // keychain-backed key, so each store root is its own signed-in person.
+  // THE KEYCHAIN IS ONLY ASKED WHEN THERE IS A TEAM (2026-10-06): asking it at
+  // every launch put a "Agentbox Safe Storage" password prompt in front of the
+  // single-person app, which has no sign-in to keep
+  // (tests/the-installed-app-is-the-single-person-app.test.mjs).
+  const cloudConfig = loadCloudConfig(appDir, { packaged: app.isPackaged });
+  const team = cloudConfig ? createTeamService({
+    session: supabaseSession({
+      cloudConfig,
+      sessionFile: path.join(config.storeRoot, '.team-session'),
+      ...(safeStorage.isEncryptionAvailable()
+        ? { encrypt: (text) => safeStorage.encryptString(text), decrypt: (buf) => safeStorage.decryptString(buf) }
+        : { encrypt: null, decrypt: null }),
+      packaged: app.isPackaged,
+      openExternal: (url) => shell.openExternal(url),
+    }),
+    store,
+    disk: workItemsDisk,
+    accountRoot: config.accountRoot,
+    stateFile: teamStateFile(config.storeRoot),
+    // The window's push is declared further down and wired once the window
+    // exists; until then a change has nobody to tell.
+    onChange: () => { try { pushUpdate(); } catch { /* no window yet */ } },
+    log: (line) => console.log(line),
+  }) : null;
+  if (team) {
+    team.start().then(() => supervisor.wake?.()).catch((err) => console.warn(`team: ${err.message}`));
+    app.on('before-quit', () => team.stop());
+  }
   // 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.
@@ -521,6 +606,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
@@ -542,6 +632,7 @@ async function createWindow() {
     lastScreenDetail = next;
     window.webContents.send('zero:screen-detail', { detail: next });
   };
+  window.on('focus', () => usedToday(Date.now()));
   window.on('move', tellScreenDetail);
   window.on('moved', tellScreenDetail);
   electronScreen.on('display-metrics-changed', tellScreenDetail);
@@ -566,9 +657,17 @@ async function createWindow() {
   // `pushUpdate` is filled in on the next line, because the updater has to
   // exist before the IPC surface that reports it and the IPC surface is what
   // knows how to reach the window.
+  //
+  // 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.
   let pushUpdate = () => {};
-  const updater = createUpdater({
+  const updater = app.isPackaged ? createUpdater({
+    app,
+    onChanged: () => pushUpdate(),
+  }) : createSourceUpdater({
     app,
+    appDir,
     onChanged: () => pushUpdate(),
   });
 
@@ -577,6 +676,7 @@ async function createWindow() {
   const ipc = registerIpc({
     store, supervisor, config, window, analytics, docGrants, updater,
     host: { ipcMain, app, dialog },
+    team,
   });
   pushUpdate = ipc.push;
   // The Agents menu's Allow/Deny, bound to the real door now that there is one.
@@ -584,6 +684,9 @@ async function createWindow() {
   // Codex card.
   answerApproval = ipc.answerApproval;
   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.
+  supervisor.onShipped = () => { try { updater.check?.(); } catch {} };
   app.on('before-quit', () => updater.stop());
 
   // Cmd+Y / Cmd+N answer the oldest approval card from ANYWHERE, including
@@ -713,9 +816,7 @@ async function createWindow() {
   //
   // THIS LINE IS LOAD-BEARING: two tests slice main.mjs from the input handler
   // above to these words to read the chord wiring on its own, so the words at
-  // the start of it are not free to change. It used to read "// The arcade.",
-  // because what stood here was the emulator, its save vault and the shelf that
-  // reached them. All of that is deleted; see decisions.md.
+  // the start of it are not free to change.
 
   store.watch();
   // ZERO_NO_SUPERVISOR: run the inbox without spawning any sessions (UI work,
@@ -802,6 +903,10 @@ async function createWindow() {
     webPreferences.autoplayPolicy = 'document-user-activation-required';
   });
 
+  // A page in the pane hides its scrollbar until you scroll, like the app's own
+  // (frame-scrollbars.mjs). Without it, a mouse on macOS gets a white track.
+  quietTheFramesScrollbars(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) => {
@@ -917,6 +1022,20 @@ 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: '' });
     // Serve a granted file, and nothing else. A page under this scheme is one
     // of ours, but it is written by an agent and read by her, so the check is
     // on every request rather than only on the one the pane asked for.
@@ -930,9 +1049,9 @@ if (!app.requestSingleInstanceLock()) {
         // Nothing is injected into a page any more; see doc-scheme.mjs for the
         // pinch zoom that briefly lived here and why she turned it down.
         //
-        // NO-STORE, OR A REDRAWN PICTURE NEVER REACHES HER. Hers, w-3fc39983be,
-        // 2026-09-28: "the font in the images is STILL not changing. Seems like
-        // a bug". It was. An agent redrew six pictures under the same names;
+        // NO-STORE, OR A REDRAWN PICTURE NEVER REACHES THE READER (w-3fc39983be).
+        // The font in redrawn pictures looked unchanged, and that was a bug.
+        // An agent redrew six pictures under the same names;
         // the page's html came back new and every <img> in it came back from
         // the window's memory, round one's pictures under round two's captions,
         // until a restart. Measured in a hidden probe of this exact setup
@@ -952,7 +1071,11 @@ if (!app.requestSingleInstanceLock()) {
       const file = imgPath(request.url);
       if (!file || !servable(file, imageRoots())) return new Response('Not available.', { status: 403 });
       try {
-        const res = await net.fetch(pathToFileURL(file).toString());
+        // A sound or a film is answered in the piece the player asked for, or
+        // it plays but cannot be moved (mediaResponse, main/img-scheme.mjs).
+        const res = mediaType(file)
+          ? await mediaResponse(file, request.headers.get('range'))
+          : await net.fetch(pathToFileURL(file).toString());
         // The window is allowed to read its own pictures back out, which is
         // what a copy needs. This widens nothing: the two rules above already
         // decided this file may be seen at all, and only this window can ask on

package/main/memory-gate-history.mjs

@@ -0,0 +1,254 @@
+// WHICH COMMANDS ARE HEAVY ON THIS MAC, LEARNED FROM WHAT THEY DID (w-3958c3753d).
+//
+// NOTHING HERE KNOWS WHAT ANY PROGRAM IS. The first proposal for holding heavy
+// work back matched names (npm, pytest, xcodebuild) and the founder turned it
+// down: another package manager, a script run directly, a training job, and a
+// list of names is wrong. So a command is filed under what it is (its program
+// and the first word after it that is not a flag) and judged by what it was
+// 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.
+//
+// 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
+// median command ran 1.3 s, so most finish between two samples and would never
+// be measured at all. A command that short cannot hold memory long enough to
+// starve anything, which is the whole of what this gate is for. A command sent
+// to the background is the exception: its tool call returns at once while its
+// process carries on, so its quickness proves nothing.
+//
+// The five lines of shell knowledge below are about the SHELL, not about any
+// program: builtins start nothing, and time/nice/env/timeout/nohup only run the
+// command after them.
+
+const BUILTINS = new Set(['cd', 'export', 'echo', 'printf', 'true', 'false', 'test', '[', '[[', ']]', 'set', 'unset',
+  'pwd', 'read', 'exit', 'return', 'shift', 'wait', ':', 'alias', 'type', 'local', 'declare', 'pushd', 'popd', 'umask']);
+const WRAPPERS = new Set(['time', 'nice', 'env', 'timeout', 'nohup', 'caffeinate', 'exec', 'command']);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const REDIRECT = /^\d*(>>?|<<?<?|&>>?|>&|<&)/;
+
+/** Light below this many MB at its sampled peak, heavy at or above HEAVY_MB. */
+export const LIGHT_MB = 150;
+export const HEAVY_MB = 400;
+/** A run this short, never seen big, counts as light. */
+export const QUICK_MS = 2_000;
+
+/**
+ * Split a shell command into the programs it starts, as `program firstArg`
+ * keys, without running or fully parsing it. `opaque` is true when part of it
+ * is computed at run time ($(...) or backticks outside single quotes), which
+ * this cannot see into.
+ */
+export function commandSegments(command) {
+  const text = String(command ?? '');
+  const segments = [];
+  let words = [];
+  let word = '';
+  let inWord = false;
+  let quote = null;
+  let opaque = false;
+  const heredocs = [];
+  const endWord = () => {
+    if (inWord) words.push(word);
+    word = ''; inWord = false;
+  };
+  const endSegment = () => { endWord(); if (words.length) segments.push(words); words = []; };
+
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote === "'") {
+      if (c === "'") quote = null; else word += c;
+      continue;
+    }
+    if (c === '\\' && i + 1 < text.length) { word += text[++i]; inWord = true; continue; }
+    if (quote === '"') {
+      if (c === '"') quote = null;
+      else {
+        if (c === '`' || (c === '$' && text[i + 1] === '(')) opaque = true;
+        word += c;
+      }
+      continue;
+    }
+    if (c === "'" || c === '"') { quote = c; inWord = true; continue; }
+    if (c === '`' || (c === '$' && text[i + 1] === '(')) opaque = true;
+    if (c === '<' && text[i + 1] === '<' && text[i + 2] !== '<') {
+      // A here-document: its body is text handed to a program, not commands.
+      endWord();
+      let j = i + 2;
+      if (text[j] === '-') j++;
+      while (text[j] === ' ') j++;
+      let delim = '';
+      while (j < text.length && !/[\s;&|]/.test(text[j])) delim += text[j++];
+      heredocs.push(delim.replace(/^['"]|['"]$/g, ''));
+      i = j - 1;
+      continue;
+    }
+    if (c === '\n') {
+      endSegment();
+      while (heredocs.length) {
+        const delim = heredocs.shift();
+        let end = text.indexOf('\n', i + 1);
+        while (true) {
+          const line = text.slice(i + 1, end === -1 ? text.length : end);
+          i = end === -1 ? text.length : end;
+          if (line.trim() === delim || end === -1) break;
+          end = text.indexOf('\n', i + 1);
+        }
+      }
+      continue;
+    }
+    if (c === ';' || c === '|' || (c === '&' && !/[<>]$/.test(word) && text[i + 1] !== '>')) {
+      endSegment();
+      if ((c === '|' || c === '&') && text[i + 1] === c) i++;
+      continue;
+    }
+    if (c === ' ' || c === '\t') { endWord(); continue; }
+    word += c; inWord = true;
+  }
+  endSegment();
+
+  const keys = [];
+  for (const seg of segments) {
+    const key = keyOf(seg);
+    if (key) keys.push(key);
+  }
+  return { keys, opaque };
+}
+
+function keyOf(segmentWords) {
+  const words = [];
+  for (let i = 0; i < segmentWords.length; i++) {
+    const w = segmentWords[i];
+    if (REDIRECT.test(w)) {
+      // `> out.txt` carries its target as the next word; `>out.txt` does not.
+      if (/^\d*(>>?|<|&>>?)$/.test(w)) i++;
+      continue;
+    }
+    if (w === '(' || w === ')' || w === '{' || w === '}' || w === '!') continue;
+    words.push(w);
+  }
+  let i = 0;
+  while (i < words.length && ASSIGNMENT.test(words[i])) i++;
+  while (i < words.length && WRAPPERS.has(basename(words[i]))) {
+    i++;
+    while (i < words.length && (words[i].startsWith('-') || /^\d+(\.\d+)?[smhd]?$/.test(words[i]) || ASSIGNMENT.test(words[i]))) i++;
+  }
+  if (i >= words.length) return null;
+  const program = basename(words[i]);
+  if (!program || BUILTINS.has(program)) return null;
+  const arg = words.slice(i + 1).find((w) => !w.startsWith('-'));
+  return arg ? `${program} ${arg.slice(0, 80)}` : program;
+}
+
+function basename(p) {
+  const s = String(p);
+  const at = s.lastIndexOf('/');
+  return at === -1 ? s : s.slice(at + 1);
+}
+
+const programOf = (key) => key.split(' ')[0];
+
+/**
+ * The learned record. Each key and each program keeps its last ten
+ * observations as letters: l light, m in between, h heavy, ? not measured.
+ * Both maps are kept in least-recently-seen-first order so the oldest falls off
+ * first when either passes `maxKeys`.
+ */
+export class CommandHistory {
+  constructor({ lightMb = LIGHT_MB, heavyMb = HEAVY_MB, maxKeys = 2_000 } = {}) {
+    this.lightMb = lightMb;
+    this.heavyMb = heavyMb;
+    this.maxKeys = maxKeys;
+    this.keys = new Map();
+    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 } = {}) {
+    const { keys, opaque } = commandSegments(command);
+    if (!keys.length) return;
+    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' : '?';
+    }
+    // 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;
+    }
+    for (const key of keys) {
+      this._push(this.keys, key, obs);
+      this._push(this.programs, programOf(key), obs);
+    }
+  }
+
+  /** 'light' | 'unknown' | 'heavy' for a command about to run. */
+  classify(command) {
+    const { keys, opaque } = commandSegments(command);
+    if (!keys.length && !opaque) return 'light';
+    let verdict = 'light';
+    const worse = (v) => {
+      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');
+    }
+    for (const key of keys) worse(this._classifyKey(key));
+    return verdict;
+  }
+
+  _classifyKey(key) {
+    const own = this.keys.get(key);
+    const recent = 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';
+    return 'unknown';
+  }
+
+  _push(map, key, obs) {
+    const list = map.get(key) ?? [];
+    map.delete(key);
+    list.push(obs);
+    map.set(key, list.slice(-10));
+    while (map.size > this.maxKeys) map.delete(map.keys().next().value);
+  }
+
+  toJSON() {
+    return { v: 1, keys: [...this.keys], programs: [...this.programs] };
+  }
+
+  /** Anything unreadable is an empty history, which only means "unknown". */
+  static fromJSON(raw, opts) {
+    const h = new CommandHistory(opts);
+    if (!raw || raw.v !== 1) return h;
+    const load = (map, entries) => {
+      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));
+        }
+      }
+    };
+    load(h.keys, raw.keys);
+    load(h.programs, raw.programs);
+    return h;
+  }
+}
+
+function chainKey(keys, opaque) {
+  return `${opaque ? '$( ' : ''}${keys.join(' && ')}`;
+}