agentbox-app 0.1.6

package/main/menu.mjs

@@ -0,0 +1,177 @@
+// The application menu. The app is keyboard-first, so the menu's job is mostly
+// to make the OS-level chords real: zoom, copy/paste, window management.
+// Zoom targets the content the keystroke arrived on, which matters because an
+// open document is a webview with its own zoom.
+
+import { app, BrowserWindow, Menu, webContents } from 'electron';
+import { zoomTarget } from './zoom-keys.mjs';
+import { zoomPercentFor } from './zoom-readout.mjs';
+
+// Approval hotkeys live in the MENU, not the renderer: a child web contents
+// owns the keyboard whenever one is up, so a renderer listener never hears
+// anything while she is inside one. Menu accelerators fire regardless of what
+// has focus.
+
+// TWO ROUTES TO ONE STEP. ⌘=, ⌘- and ⌘0 all did nothing. The menu accelerator
+// was the only route, and this file already knows what that is worth: the note
+// below ⌘R records that accelerators here "do not fire while a child web
+// contents owns the keyboard", which is why ⌘R, ⌘Y and ⌘N were all moved into
+// before-input-event in the main process. Zoom was left behind, on a chord she
+// cannot work around, because Chromium persists the zoom level per page URL
+// and hands it back after every reload.
+//
+// So the chords are now handled in main.mjs as well, and this stays for the
+// menu's label and for a click. On macOS the two are exclusive (AppKit eats a
+// key equivalent before the page can see it); the guard below is what keeps
+// that an assumption rather than a load-bearing one, exactly like the reload
+// debounce in main.mjs.
+let lastZoomAt = 0;
+let lastZoomDelta = null;
+
+/**
+ * Move the zoom one step. `target` is the web contents the caller named: the
+ * one a keystroke arrived on, or the window a menu click was chosen from. When
+ * nobody names one it falls back to whatever is focused, and then to the app's
+ * own window. That last fallback is the fix for her second report: focus can be
+ * nowhere, and a target of null was a silent no-op.
+ */
+export function applyZoom(delta, target = null) {
+  const now = Date.now();
+  if (delta === lastZoomDelta && now - lastZoomAt < 40) return;
+  lastZoomAt = now;
+  lastZoomDelta = delta;
+  const contents = zoomTarget({
+    named: target,
+    focused: webContents.getFocusedWebContents(),
+    appWindow: appWindowContents(),
+  });
+  if (!contents) return;
+  if (delta === 0) contents.setZoomLevel(0);
+  else contents.setZoomLevel(Math.max(-6, Math.min(6, contents.getZoomLevel() + delta)));
+  announceZoom(contents.getZoomLevel());
+}
+
+// The number is worked out here, where the level actually changes, and the
+// page only draws what it is handed.
+//
+// It always goes to the APP window, even when the level that moved belongs to
+// the junk browser's guest: the guest is a page inside her window, and a
+// browser puts its own readout in its own corner rather than in the page.
+function announceZoom(level) {
+  const percent = zoomPercentFor(level);
+  if (percent === null) return;
+  const target = appWindowContents();
+  if (!target || target.isDestroyed?.()) return;
+  target.send?.('zero:zoom-percent', { percent });
+}
+
+// ⌘F, ⌘G AND ⇧⌘G. The app finds its own words (renderer/src/find-in-page.ts
+// says why it is not Chromium's findInPage), so all this does is tell the page
+// which one was pressed: 0 opens the box, 1 and -1 walk the matches.
+//
+// Two routes again, the menu and before-input-event in main.mjs, for the reason
+// zoom has two, and the same guard keeps one press from arriving twice.
+let lastFindAt = 0;
+let lastFindStep = null;
+
+export function requestFind(step) {
+  const now = Date.now();
+  if (step === lastFindStep && now - lastFindAt < 40) return;
+  lastFindAt = now;
+  lastFindStep = step;
+  const target = appWindowContents();
+  if (!target || target.isDestroyed?.()) return;
+  target.send?.('zero:find', { step });
+}
+
+function appWindowContents() {
+  const window = BrowserWindow.getFocusedWindow() ?? BrowserWindow.getAllWindows()[0];
+  return window && !window.isDestroyed() ? window.webContents : null;
+}
+
+export function installMenu({ onApproval, onReload, onZoom } = {}) {
+  // A CLICK NAMES ITS WINDOW.after the chords were fixed. Electron hands a menu
+  // click the window it was chosen from, so the click stops asking what is
+  // focused, which is the question that was coming back null. main.mjs decides
+  // the keystroke's target from where the event arrived: inside the junk
+  // browser it is the guest, which carries its own zoom.
+  const zoom = (delta, window) => {
+    const target = window && !window.isDestroyed() ? (window.webContents ?? null) : null;
+    return onZoom ? onZoom(delta, target) : applyZoom(delta, target);
+  };
+
+  const template = [
+    {
+      label: app.name,
+      submenu: [
+        { role: 'about' },
+        { type: 'separator' },
+        { role: 'hide' },
+        { role: 'hideOthers' },
+        { role: 'unhide' },
+        { type: 'separator' },
+        { role: 'quit' },
+      ],
+    },
+    {
+      label: 'Edit',
+      submenu: [
+        { role: 'undo' },
+        { role: 'redo' },
+        { type: 'separator' },
+        { role: 'cut' },
+        { role: 'copy' },
+        { role: 'paste' },
+        { role: 'selectAll' },
+        { type: 'separator' },
+        { label: 'Find…', accelerator: 'CommandOrControl+F', click: () => requestFind(0) },
+        { label: 'Find Next', accelerator: 'CommandOrControl+G', click: () => requestFind(1) },
+        { label: 'Find Previous', accelerator: 'Shift+CommandOrControl+G', click: () => requestFind(-1) },
+      ],
+    },
+    {
+      label: 'View',
+      submenu: [
+        { label: 'Zoom In', accelerator: 'CommandOrControl+=', click: (_item, window) => zoom(0.5, window) },
+        { label: 'Zoom In (numpad)', accelerator: 'CommandOrControl+Plus', click: (_item, window) => zoom(0.5, window), visible: false, acceleratorWorksWhenHidden: true },
+        { label: 'Zoom Out', accelerator: 'CommandOrControl+-', click: (_item, window) => zoom(-0.5, window) },
+        { label: 'Actual Size', accelerator: 'CommandOrControl+0', click: (_item, window) => zoom(0, window) },
+        { type: 'separator' },
+        // ⌘R PUTS THE BUILT RENDERER ON SCREEN, which is the only thing anyone
+        // ever presses it for here.
+        //
+        // The main document has exactly the same problem and it is worse
+        // there, because index.html names a CONTENT-HASHED bundle: one cached
+        // index.html hands back the old filename, so the old renderer loads
+        // and every change is invisible. ⇧⌘R was added as the workaround
+        // rather than the fix.
+        //
+        // Both chords now ignore the cache, and both go through the app's own
+        // window rather than "whatever is focused", so a webview holding focus
+        // cannot turn the key into a no-op either.
+        { label: 'Reload', accelerator: 'CommandOrControl+R', click: () => onReload?.() },
+        { label: 'Force Reload', accelerator: 'Shift+CommandOrControl+R', click: () => onReload?.() },
+        { role: 'toggleDevTools' },
+        { type: 'separator' },
+        { role: 'togglefullscreen' },
+      ],
+    },
+    {
+      label: 'Agents',
+      submenu: [
+        { label: 'Allow Pending Approval', accelerator: 'Command+Y', click: () => onApproval?.(true) },
+        { label: 'Deny Pending Approval', accelerator: 'Command+N', click: () => onApproval?.(false) },
+      ],
+    },
+    {
+      label: 'Window',
+      submenu: [
+        { role: 'minimize' },
+        { role: 'zoom' },
+        { type: 'separator' },
+        { role: 'front' },
+      ],
+    },
+  ];
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}

package/main/notify.mjs

@@ -0,0 +1,155 @@
+// THE BANNER. Once while she is away, only while she is somewhere else, taken
+// down the moment she comes back.
+//
+// The rule it obeys is in shared/notify-rules.mjs; this file is the live half:
+// the window's focus, the machine's idle clock, and the lifetime of the one
+// notification that is allowed to exist. Nothing decidable lives here, so that
+// what the tests pin is the behaviour and not the wiring.
+//
+// Before this, the renderer called a bare `new Notification.show` per arrival,
+// up to three per batch, with no idea whether she was looking at the app. tell
+// me when I am elsewhere, and never when I am here.
+//
+// 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 { atTheApp, banner, shouldSpeak } from '../shared/notify-rules.mjs';
+import { NAME } from '../shared/product-name.mjs';
+
+// 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 }) {
+  // 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();
+  let live = null;      // the one notification currently on screen, if any
+  let timer = null;
+  // HOW MANY TIMES SHE HAS BEEN INTERRUPTED SINCE SHE LAST HAD THE WINDOW.
+  // Both reset in seen, so a stretch away is the unit. shouldSpeak in
+  // shared/notify-rules.mjs is the rule these two feed; the short version is
+  // once, plus one more if an approval turns up afterwards.
+  let spoke = false;
+  let spokeAsk = false;
+
+  const idleMs = () => {
+    try { return powerMonitor.getSystemIdleTime() * 1000; } catch { return 0; }
+  };
+  const focused = () => {
+    try { return !!window && !window.isDestroyed() && window.isFocused(); } catch { return false; }
+  };
+
+  const takeDown = () => {
+    if (!live) return;
+    try { live.close(); } catch {}
+    live = null;
+  };
+
+  // She is looking at Agentbox, so everything in hand has been seen on the row
+  // it lives on. This is also why arrivals that land while she is here are
+  // dropped rather than banked: showing them later, when she steps away, would
+  // be telling her about work she already watched arrive.
+  const seen = () => {
+    unseen.clear();
+    if (timer) { clearTimeout(timer); timer = null; }
+    spoke = false;
+    spokeAsk = false;
+    takeDown();
+  };
+
+  const speak = () => {
+    timer = null;
+    if (atTheApp({ focused: focused(), idleMs: idleMs() })) return seen();
+    const items = [...unseen.values()];
+    // She has already been told once this stretch. Everything since is banked
+    // on its own row and she will have it the moment she is back; saying it out
+    // loud again is the twenty-chimes-in-a-meeting problem she asked us to fix.
+    if (!shouldSpeak({ spoke, spokeAsk, waiting: items })) return;
+    const say = banner(items);
+    if (!say) return;
+    takeDown();
+    let n;
+    try {
+      // No subtitle. macOS puts that field directly under the title in nearly
+      // the same type, and she read a lone project name there as the title
+      // bleeding over mid-render. The project is in the title now; see
+      // shared/notify-rules.mjs.
+      n = new Notification({
+        title: say.title,
+        body: say.body,
+        silent: false,
+      });
+    } catch { return; }
+    // A banner she can act on. Clicking it brings Agentbox forward and opens the
+    // row it was about, which is the difference between being told and having
+    // to go find it.
+    n.on('click', () => {
+      seen();
+      if (!window || window.isDestroyed()) return;
+      if (window.isMinimized()) window.restore();
+      window.show();
+      window.focus();
+      if (say.open) window.webContents.send('zero:open-item', { id: say.open });
+    });
+    n.on('close', () => { if (live === n) live = null; });
+    // A BANNER macOS REFUSED LOOKS EXACTLY LIKE NO AGENT FINISHING, which is
+    // the shape of failure this codebase keeps paying for. Measured on her
+    // machine 2026-08-20: across 107 apps registered with Notification Center,
+    // neither `ac.astral.app` nor `com.github. Electron` had a record at all, so
+    // there is no evidence a banner from here has ever been delivered. If the
+    // OS is dropping them, this line is what turns that from a silence into a
+    // two-minute diagnosis.
+    n.on('failed', (_e, err) => {
+      live = null;
+      console.warn(`zero: macOS refused the notification (${err}). Check ${NAME} in System Settings > Notifications.`);
+    });
+    live = n;
+    try {
+      n.show();
+      spoke = true;
+      if (items.some((i) => i.kind === 'approval')) spokeAsk = true;
+    } catch { live = null; }
+  };
+
+  return {
+    // Fresh arrivals from the renderer, which owns what counts as news (it is
+    // the only place that knows what the inbox is). Each is
+    // { id, title, product, productName, kind }.
+    add(arrivals) {
+      if (!Array.isArray(arrivals) || !arrivals.length) return;
+      // Asked before banking anything, so that a burst arriving while she is
+      // at the app is dropped rather than saved up for when she leaves.
+      if (atTheApp({ focused: focused(), idleMs: idleMs() })) return seen();
+      for (const a of arrivals) {
+        if (!a || !a.id || unseen.has(a.id)) continue;
+        unseen.set(a.id, a);
+      }
+      if (!unseen.size || timer) return;
+      timer = setTimeout(speak, coalesceMs);
+    },
+    // The window came forward. Whatever was on screen is now behind her.
+    seen,
+    // Tests, and nothing else.
+    _pending: () => [...unseen.values()],
+    _spoken: () => ({ spoke, spokeAsk }),
+  };
+}
+
+export function installNotifier({ app, window, Notification, powerMonitor, ipcMain }) {
+  if (Notification.isSupported && !Notification.isSupported()) {
+    return { add() {}, seen() {} };
+  }
+  const notifier = createNotifier({ window, Notification, powerMonitor });
+  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 : []);
+  });
+  return notifier;
+}

package/main/open-source-file.mjs

@@ -0,0 +1,8 @@
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import path from 'node:path';
+const run = promisify(execFile);
+export async function openSourceFile(file, execute = run) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) throw Error('Resolve the source file before opening it.');
+  await execute('/usr/bin/open', ['-t', file], {timeout:10000});
+}

package/main/project-identity.mjs

@@ -0,0 +1,149 @@
+// WHAT A PROJECT IS CALLED, AND THE MARK BESIDE THE NAME. Both of them hers to
+// change, and both written into the project's OWN project.json rather than into
+// her workspace config.
+//
+// WHY project.json AND NOT settings.json. Every other switch on the project
+// screen is a preference about how Agentbox treats a folder, so it belongs to this
+// Mac and lives in her config. A name and a mark are what the project IS. They
+// travel with the folder: a project copied to another machine, or opened by the
+// MCP server, or read by a worker session, is still called the same thing. The
+// slug never moves, so nothing that points at a project by id breaks when the
+// name changes.
+//
+// THE ICON IS COPIED IN, NOT POINTED AT, and that is the one place this departs
+// from what she suggested.
+//
+// She is right that we cannot host it, and nothing here does: the file never
+// leaves the Mac. But a pointer at wherever she found the picture is a pointer
+// into her Downloads folder, and the mark in her rail then disappears the day she
+// empties it. Copying the file into the project's own folder keeps every property
+// she asked for (local, no server, no upload) and drops the one failure she did
+// not ask for. It costs about 20KB per project.
+//
+// It also has to be copied for a second reason that only shows up later: the
+// renderer cannot read an arbitrary path off her disk. Images already render
+// through the product's own roots (`img-scheme.mjs`); a file inside the project
+// folder is reachable by that machinery on the day it is written, and a file in
+// ~/Downloads would need a new grant into a folder Agentbox has no business in.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { patchProjectAt, loadProjectAt } from './store/project.mjs';
+import { NAME } from '../shared/product-name.mjs';
+
+/**
+ * What a project may be called. Long enough for a real product name, short
+ *  enough that the rail and the settings nav still read as a list of names. */
+export const NAME_MAX = 60;
+
+// The picture kinds a mark can be. Deliberately short: these are the four that
+// every Mac can produce, that Chromium draws without a plugin, and that survive
+// being shrunk to a 24px burst-sized square. No svg, because an svg is a
+// document with script in it and this one gets drawn inside her app.
+export const ICON_KINDS = ['.png', '.jpg', '.jpeg', '.webp'];
+
+// The one name a mark is ever stored under, plus its extension. One file per
+// project, so choosing a new mark REPLACES the old rather than leaving her
+// folder collecting every picture she ever tried.
+const ICON_STEM = 'icon';
+
+/**
+ * PURE. The name a project would end up with, or null when the rename should be
+ * refused.
+ *
+ * Refused rather than coerced when it is empty, because a nameless project is a
+ * blank row in her sidebar with no way back: the only handle left to rename it
+ * by is the one that just disappeared. Trimmed and collapsed otherwise, so a
+ * name pasted out of a document does not arrive with a newline in it and push
+ * every row below it down.
+ */
+export function cleanName(value) {
+  const name = String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, NAME_MAX);
+  return name || null;
+}
+
+/** PURE. Whether this file is a picture a mark can be made of. */
+export function isIconKind(file) {
+  return ICON_KINDS.includes(path.extname(String(file ?? '')).toLowerCase());
+}
+
+/**
+ * Rename the project in the folder a caller has already resolved.
+ *
+ * `patchProjectAt` rather than `renameProject`, on the note that function itself
+ * carries: a write that re-derives its folder from an id lands wherever that id
+ * happens to name, and two products can hold the same id.
+ */
+export function setProjectName(dir, value) {
+  const name = cleanName(value);
+  if (!name) throw new Error('a project needs a name');
+  if (!loadProjectAt(dir)) throw new Error('not a project folder');
+  patchProjectAt(dir, { name });
+  return name;
+}
+
+/**
+ * Copy a picture into the project folder and make it the mark.
+ *
+ * Returns the path the renderer should draw, or throws with a sentence she can
+ * read. `source` is whatever the open panel handed back, which is a real file on
+ * her disk and never anything typed.
+ *
+ * THE STORED VALUE IS RELATIVE. `icon.png`, not `/Users/.../agentbox/icon.png`,
+ * for the same reason the name lives here at all: a project.json that names an
+ * absolute path stops being true the moment the folder moves or is opened on
+ * another Mac. The caller joins it to the project's own dir, which it already
+ * has.
+ */
+export function setProjectIcon(dir, source) {
+  if (!loadProjectAt(dir)) throw new Error('not a project folder');
+  if (!isIconKind(source)) throw new Error(`that file is not a picture ${NAME} can draw`);
+  let stat = null;
+  try { stat = fs.statSync(source); } catch { throw new Error('that file could not be read'); }
+  if (!stat.isFile()) throw new Error('that is not a file');
+
+  const ext = path.extname(source).toLowerCase();
+  const name = `${ICON_STEM}${ext}`;
+  // The old mark goes first, and every kind of it, or a project that had a .png
+  // and now has a .webp keeps both on disk and the stale one is what a future
+  // reader trips over.
+  clearIconFiles(dir);
+  fs.copyFileSync(source, path.join(dir, name));
+  patchProjectAt(dir, { logo: name });
+  return name;
+}
+
+/**
+ * Back to the drawn burst. The picture is deleted with the setting: leaving it
+ *  behind means "no icon" and a file called icon.png sitting in her folder, which
+ *  is the kind of thing that gets asked about a month later. */
+export function clearProjectIcon(dir) {
+  if (!loadProjectAt(dir)) throw new Error('not a project folder');
+  clearIconFiles(dir);
+  patchProjectAt(dir, { logo: null });
+  return null;
+}
+
+function clearIconFiles(dir) {
+  for (const ext of ICON_KINDS) {
+    try { fs.rmSync(path.join(dir, `${ICON_STEM}${ext}`), { force: true }); } catch { /* nothing to remove */ }
+  }
+}
+
+/**
+ * The mark's full path for a product the store has already listed, or null.
+ *
+ * CHECKED AGAINST DISK, not merely read off project.json. A `logo` that names a
+ * file which is no longer there would draw a broken image where the burst used
+ * to be, and the burst is a correct answer to "this project has no mark" while a
+ * broken image is not. This is the same rule the attachment chips follow: resolve
+ * before you promise.
+ */
+export function iconPathFor(product) {
+  const rel = typeof product?.logo === 'string' ? product.logo.trim() : '';
+  // Only ever the one file this module writes. A project.json edited by hand to
+  // say `../../../somewhere` must not turn into a read outside the folder.
+  if (!rel || rel !== path.basename(rel) || !isIconKind(rel)) return null;
+  const full = path.join(product.dir, rel);
+  try { return fs.statSync(full).isFile() ? full : null; } catch { return null; }
+}

package/main/provider-commands.mjs

@@ -0,0 +1,32 @@
+// Small adapters over provider operations. The supervisor owns routing, locks,
+// account selection and persistence; these operations never start a fake prompt.
+import { NAME } from '../shared/product-name.mjs';
+export async function runCodexCommand({server,threadId,cwd,name,args=''}) {
+ if(['skills','mcp','status','copy'].includes(name)&&args)throw new Error(`Run /${name} on its own. Your draft has been kept.`);
+ if(name==='goal') {
+  if(!args){const {goal}=await server.request('thread/goal/get',{threadId});return goal?`${goal.objective}\nStatus: ${goal.status}\nTokens used: ${goal.tokensUsed}`:'This conversation has no goal.';}
+  if(args==='clear'){await server.request('thread/goal/clear',{threadId});return 'Goal cleared.';}
+  if(args!=='pause')throw new Error(`Setting or resuming a Codex goal is not connected to ${NAME}’s worker lifecycle yet. Your draft has been kept.`);
+  await server.request('thread/goal/set',{threadId,status:'paused'});
+  return 'Goal paused.';
+ }
+ if(name==='skills') {
+  const result=await server.request('skills/list',{cwds:[cwd],forceReload:true});
+  return result.data?.flatMap(d=>[...(d.skills??[]).map(s=>`${s.name}${s.enabled===false?' (disabled)':''}: ${s.description??''}`),...(d.errors??[]).map(e=>`Could not read ${e.path}: ${e.message}`)]).join('\n')||'No skills found in this project.';
+ }
+ if(name==='mcp') {
+  const rows=[];let cursor;
+  do {const result=await server.request('mcpServerStatus/list',{threadId,...(cursor?{cursor}:{})});rows.push(...(result.data??[]));cursor=result.nextCursor;}while(cursor);
+  return rows.map(s=>`${s.name}: ${Object.keys(s.tools??{}).length} tools; authentication ${s.authStatus??'unknown'}`).join('\n')||'No MCP servers are connected to this conversation.';
+ }
+ if(name==='status'||name==='copy') {
+  const {thread}=await server.request('thread/read',{threadId,includeTurns:true});
+  if(name==='copy') {
+   const messages=(thread.turns??[]).filter(t=>t.status==='completed').flatMap(t=>t.items??[]).filter(i=>i.type==='agentMessage'&&i.text);
+   if(!messages.length)throw new Error('There is no assistant response to copy yet.');
+   return messages.at(-1).text;
+  }
+  return `Conversation: ${thread.id}\nStatus: ${thread.status?.type??'unknown'}\nFolder: ${thread.cwd??cwd}\nTurns: ${thread.turns?.length??0}`;
+ }
+ throw new Error(`/${name} is not available through ${NAME}’s Codex connection yet. Your draft has been kept.`);
+}

package/main/rail-note.mjs

@@ -0,0 +1,74 @@
+// THE NOTE SHE KEEPS IN THE SIDEBAR, and the file it lives in.
+//
+// THE NOTE IS A REAL MARKDOWN FILE IN THE PRODUCT'S OWN FOLDER, `pinned.md`,
+// and that is the whole design decision here. It could have been a row in some
+// settings blob, which would have been fewer lines. It is a file because every
+// agent on this product can already read the product's folder, so a priority
+// she types into the sidebar is a priority a worker can be pointed at, and
+// because a file survives this app being reinstalled, rebuilt, or replaced.
+//
+// It is NOT `notes.md`. That name is taken on at least one product by a map an
+// agent wrote in round one, and loading somebody else's stale page into her
+// sidebar the first time she opens it is the one failure this file could have
+// that she would never think to report.
+//
+// ONE NOTE PER PRODUCT, because the panel it draws in is per product: the rail
+// re-orients her on the thing she just opened, and a single note shared across
+// twenty products would be answering a question about some other product, which
+// is the exact fault the agents list had before it was narrowed (Rail.tsx).
+//
+// Pure of Electron on purpose, like doc-file.mjs beside it: the IPC layer hands
+// in the product record, and these two functions are the whole of the disk
+// access. The path is DERIVED from the product, never passed in, so there is no
+// path to traverse and nothing to validate.
+import fsDefault from 'node:fs';
+import path from 'node:path';
+
+export const NOTE_NAME = 'pinned.md';
+
+// Far past anything a sidebar column can hold, and still small enough that a
+// runaway paste cannot fill her disk. A note that hits this is refused rather
+// than truncated: half her words written back is worse than none.
+export const MAX_NOTE_BYTES = 200_000;
+
+/** The file this product's sidebar note lives in, or null if it has no folder. */
+export function notePath(prod) {
+  return prod?.dir ? path.join(prod.dir, NOTE_NAME) : null;
+}
+
+/**
+ * What she has written on this product. A note that has never been started is
+ *  empty text, not an error: the sidebar draws its placeholder from that. */
+export function readNote({ product, fs = fsDefault }) {
+  const file = notePath(product);
+  if (!file) return { ok: false, error: 'That project has no folder to keep a note in.' };
+  try {
+    const stat = fs.statSync(file);
+    if (stat.size > MAX_NOTE_BYTES) {
+      return { ok: false, error: 'That note is too long for the sidebar to open.' };
+    }
+    return { ok: true, text: fs.readFileSync(file, 'utf8'), mtime: stat.mtimeMs };
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { ok: true, text: '', mtime: 0 };
+    return { ok: false, error: 'That note could not be read.' };
+  }
+}
+
+/**
+ * Her note, written back. The file is CREATED on the first keystroke rather
+ *  than at install time, so a product she never writes on never grows a file. */
+export function writeNote({ product, text, fs = fsDefault }) {
+  const file = notePath(product);
+  if (!file) return { ok: false, error: 'That project has no folder to keep a note in.' };
+  const out = typeof text === 'string' ? text : '';
+  if (Buffer.byteLength(out, 'utf8') > MAX_NOTE_BYTES) {
+    return { ok: false, error: 'That note is too long to save.' };
+  }
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, out, 'utf8');
+    return { ok: true, mtime: fs.statSync(file).mtimeMs };
+  } catch {
+    return { ok: false, error: 'That note could not be saved.' };
+  }
+}