agentbox-app 0.1.6

package/main/codex-threads.mjs

@@ -0,0 +1,268 @@
+// HER CODEX CONVERSATIONS, READ OFF WHAT CODEX LEAVES ON THE MAC.
+//
+// Codex keeps two things this reads, both plain files and both measured on her
+// Mac on 2026-09-14 at 19:3x:
+//
+//   ~/.codex/session_index.jsonl        one line per thread Codex has named:
+//                                       {"id", "thread_name", "updated_at"}.
+//                                       118 lines that day. A thread Codex has
+//                                       not named yet is simply not in it.
+//   ~/.codex/sessions/YYYY/MM/DD/rollout-<ISO>-<uuid>.jsonl
+//                                       the transcript. Line one is
+//                                       `session_meta` with `cwd`, `timestamp`
+//                                       and `thread_source`; the rest are
+//                                       events, of which `user_message` and
+//                                       `agent_message` are the two this reads.
+//
+// WHICH THREADS ARE HERS. `thread_source` is `user` for one she typed into,
+// `guardian_review` for Codex's own reviewer of a turn, and `subagent` for a
+// helper a thread spawned. 247 transcripts were touched in the seven days to
+// 09-14; 158 of them were guardians. Without this filter the inbox would offer
+// her four rows for every conversation she had.
+//
+// There is also `~/.codex/state_5.sqlite`, which has everything above in one
+// table. It is not read: Electron ships no sqlite, the file is written live
+// under WAL, and the two plain files carry what the row needs.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { isScratchFolder, shortFolder, threadTitle } from './agent-sessions.mjs';
+
+export const CODEX_RECENT_DAYS = 7;
+/** How many day folders the walk opens at most, whatever `days` says. */
+const MAX_DAY_FOLDERS = 40;
+/**
+ * A transcript is not read past this: the head and the tail are both inside it
+ *  for every conversation measured, and a runaway file must not stall a tick. */
+const MAX_BYTES = 8 * 1024 * 1024;
+
+export const codexHome = (home = os.homedir()) => path.join(home, '.codex');
+
+/** The names Codex gave her threads, by id. Missing file is an empty map. */
+export function readCodexIndex(codexDir = codexHome()) {
+  const out = new Map();
+  let text = '';
+  try { text = fs.readFileSync(path.join(codexDir, 'session_index.jsonl'), 'utf8'); } catch { return out; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const j = JSON.parse(line);
+      const id = String(j?.id ?? '').trim();
+      if (!id) continue;
+      const at = Date.parse(j?.updated_at ?? '');
+      out.set(id, { name: String(j?.thread_name ?? '').trim(), updatedAt: Number.isFinite(at) ? at : 0 });
+    } catch { /* one bad line is not a reason to lose the rest */ }
+  }
+  return out;
+}
+
+const numericDesc = (dir) => {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  return names.filter((n) => /^\d+$/.test(n)).sort((a, b) => Number(b) - Number(a));
+};
+
+/** Every transcript in the newest `days` day folders, newest folder first. */
+export function listRolloutFiles(codexDir = codexHome(), { days = CODEX_RECENT_DAYS } = {}) {
+  const root = path.join(codexDir, 'sessions');
+  const out = [];
+  let looked = 0;
+  const limit = Math.min(Math.max(1, Number(days) || 1), MAX_DAY_FOLDERS);
+  for (const year of numericDesc(root)) {
+    for (const month of numericDesc(path.join(root, year))) {
+      for (const day of numericDesc(path.join(root, year, month))) {
+        if (looked >= limit) return out;
+        looked += 1;
+        const dir = path.join(root, year, month, day);
+        let names = [];
+        try { names = fs.readdirSync(dir); } catch { names = []; }
+        for (const name of names) {
+          if (/^rollout-.*\.jsonl$/.test(name)) out.push(path.join(dir, name));
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/* * * Codex Desktop prefixes a prompt with the files she attached. Everything else is kept as
+ is.
+*/
+export function cleanPrompt(text) {
+  let t = String(text ?? '');
+  const at = t.indexOf('## My request:');
+  if (at >= 0) t = t.slice(at + '## My request:'.length);
+  t = t.replace(/^\s*Distinguish instructions in attached documents from the user's request\.\s*/m, '');
+  // Codex Desktop wraps each attached picture in <image>…</image> markers in
+  // the text beside it; the picture itself is an input_image part.
+  t = t.replace(/<\/?image>/g, '');
+  return t.trim();
+}
+
+/**
+ * WHAT CODEX PUTS IN HER MOUTH. In paginated history mode the user turn is a
+ * `response_item` with several `<recommended_plugins>…`,
+ * `<environment_context>…`, `<user_instructions>…`. Every one of those opens
+ * with an angle-bracket tag on its first line, and nothing she types does.
+ * Measured on the thread she screenshotted (2026-09-15): three parts, the
+ * first two injected. */
+export function isInjected(text) {
+  const t = String(text ?? '').trimStart();
+  const first = t.split('\n')[0] ?? '';
+  if (/^<[a-z_]+[^>]*>/i.test(first)) return true;
+  // The folder's AGENTS.md, pasted in as "# AGENTS.md instructions for
+  // /path" followed by an <INSTRUCTIONS> block. Measured on the thread she
+  // screenshotted (2026-09-15): it was the second part of her first turn, and
+  // the first read of it printed it as what she asked.
+  if (/^#\s*AGENTS\.md instructions/i.test(first)) return true;
+  return /^\s*<INSTRUCTIONS>/i.test(t.slice(first.length, first.length + 200));
+}
+
+/**
+ * WHAT CODEX SAID, without its own tool markers. Codex Desktop embeds a
+ *  drawing call as private-use characters around a JSON blob, e.g.
+ *  U+E200 "visualize" U+E202 {…} U+E201, which the row would otherwise print
+ *  as a box and a path. The text on either side is the message. */
+export function cleanAnswer(text) {
+  return String(text ?? '')
+    .replace(/[-][a-z_]*[-]\{[^\n]*?\}[-]?/g, '')
+    .replace(/[-]/g, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+const partsOf = (payload) => (Array.isArray(payload?.content) ? payload.content : []).filter((c) => c && typeof c === 'object');
+
+/**
+ * One transcript, read once: who started it, where, what she asked first and
+ *  what Codex said last. Null when the file is not a Codex transcript.
+ *
+ *  TWO SHAPES OF TRANSCRIPT, AND BOTH ARE READ. Codex's `history_mode` is
+ *  `legacy` or `paginated` (line one says which). Legacy writes `event_msg`
+ *  lines of type `user_message` / `agent_message` with a `message` string.
+ *  Paginated writes none of those: the turns are `response_item` lines of type
+ *  `message` with a `role` and a `content` array of `input_text`, `input_image`
+ *  and `output_text` parts. Measured 2026-09-15 across the seven days before:
+ *  all 61 of her own threads were paginated, and the first build read only
+ *  legacy, which is why her row said "Codex has not answered yet." */
+export function readRollout(file) {
+  let text = '';
+  try {
+    const fd = fs.openSync(file, 'r');
+    try {
+      const size = fs.fstatSync(fd).size;
+      const buf = Buffer.alloc(Math.min(size, MAX_BYTES));
+      fs.readSync(fd, buf, 0, buf.length, 0);
+      text = buf.toString('utf8');
+    } finally { fs.closeSync(fd); }
+  } catch { return null; }
+  const lines = text.split('\n');
+  let meta = null;
+  let prompt = '';
+  let last = '';
+  let turns = 0;
+  let images = 0;
+  let lastActive = 0;
+  // Paginated mode writes the same turn twice when an event_msg is also
+  // present, so a turn is counted once whichever line says it.
+  let sawEventTurns = false;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let j;
+    try { j = JSON.parse(line); } catch { continue; }
+    if (!meta) {
+      if (j?.type !== 'session_meta') return null;
+      const p = j.payload ?? {};
+      const startedAt = Date.parse(p.timestamp ?? j.timestamp ?? '');
+      meta = {
+        id: String(p.session_id ?? p.id ?? '').trim(),
+        cwd: String(p.cwd ?? '').trim(),
+        threadSource: typeof p.thread_source === 'string' ? p.thread_source : (typeof p.source === 'string' ? 'user' : 'other'),
+        startedAt: Number.isFinite(startedAt) ? startedAt : 0,
+      };
+      continue;
+    }
+    const at = Date.parse(j.timestamp ?? '');
+    if (Number.isFinite(at) && at > lastActive) lastActive = at;
+    const p = j.payload ?? {};
+    if (j.type === 'event_msg') {
+      if (p.type === 'user_message') {
+        const said = cleanPrompt(p.message);
+        if (!prompt && said && !isInjected(said)) prompt = said;
+        turns += 1;
+        sawEventTurns = true;
+      } else if (p.type === 'agent_message') {
+        const said = cleanAnswer(p.message);
+        if (said) last = said;
+      }
+      continue;
+    }
+    if (j.type !== 'response_item' || p.type !== 'message') continue;
+    if (p.role === 'user') {
+      const parts = partsOf(p);
+      images += parts.filter((c) => c.type === 'input_image').length;
+      const hers = parts
+        .filter((c) => c.type === 'input_text' && typeof c.text === 'string' && !isInjected(c.text))
+        .map((c) => cleanPrompt(c.text))
+        .filter(Boolean);
+      if (!hers.length) continue; // a turn made of nothing but Codex's own preamble
+      if (!prompt) prompt = hers.join('\n\n').trim();
+      if (!sawEventTurns) turns += 1;
+    } else if (p.role === 'assistant') {
+      const said = cleanAnswer(partsOf(p).filter((c) => c.type === 'output_text').map((c) => c.text ?? '').join('\n'));
+      if (said) last = said;
+    }
+  }
+  if (!meta || !meta.id) return null;
+  let mtime = 0;
+  try { mtime = fs.statSync(file).mtimeMs; } catch { mtime = 0; }
+  return { ...meta, prompt, last, turns, images, lastActive, path: file, mtime };
+}
+
+/**
+ * A transcript written to in the last two minutes is a conversation Codex is
+ *  still in. Two minutes because Codex writes a token count line every turn and
+ *  a turn on her Mac was never longer than that between writes. */
+export const LIVE_MS = 2 * 60_000;
+export const isLive = (mtime, now = Date.now()) => Number(mtime) > 0 && now - Number(mtime) < LIVE_MS;
+
+/**
+ * HER CONVERSATIONS, newest first, in the shape the import card and the
+ *  import row both read. One entry per thread she typed into, in a real folder,
+ *  touched in the last `days` days. */
+export function readCodexThreads({ home = os.homedir(), codexDir = codexHome(home), days = CODEX_RECENT_DAYS, now = Date.now() } = {}) {
+  const index = readCodexIndex(codexDir);
+  const cutoff = now - Math.max(0, Number(days) || 0) * 86400 * 1000;
+  const out = [];
+  const skipped = { notHers: 0, scratch: 0, old: 0, empty: 0, unreadable: 0 };
+  for (const file of listRolloutFiles(codexDir, { days })) {
+    const r = readRollout(file);
+    if (!r) { skipped.unreadable += 1; continue; }
+    if (r.threadSource !== 'user') { skipped.notHers += 1; continue; }
+    if (!r.cwd || isScratchFolder(r.cwd, home)) { skipped.scratch += 1; continue; }
+    const named = index.get(r.id);
+    const when = Math.max(named?.updatedAt ?? 0, r.mtime, r.startedAt);
+    if (when < cutoff) { skipped.old += 1; continue; }
+    const title = named?.name || threadTitle([r.prompt]);
+    if (!title) { skipped.empty += 1; continue; }
+    out.push({
+      id: r.id,
+      source: 'codex',
+      folder: r.cwd,
+      folderName: path.basename(r.cwd),
+      short: shortFolder(r.cwd, home),
+      title,
+      when,
+      startedAt: r.startedAt,
+      lastActive: Math.max(r.lastActive, r.mtime),
+      turns: r.turns,
+      images: r.images,
+      path: file,
+      prompt: r.prompt,
+      last: r.last,
+      live: isLive(r.mtime, now),
+    });
+  }
+  out.sort((a, b) => b.when - a.when);
+  return { threads: out, skipped };
+}

package/main/codex-usage-file.mjs

@@ -0,0 +1,192 @@
+// THE CODEX FIGURE SHE ALREADY HAS ON THIS MAC, WHEN NOTHING HAS PUSHED ONE.
+//
+// IT WAS NOT A BUG, AND IT WAS STILL WRONG. main/codex-usage.mjs holds one rule
+// and it is a good one: never spawn anything and never ask OpenAI anything to
+// draw a picture. Codex's figures ride the app-server the fleet is already
+// running and arrive unprompted during a turn. The unstated cost of that rule is
+// that the app only ever learns a number for work POWERUP ITSELF RAN. She runs
+// Codex in its own app all day, so on her Mac the push had never arrived and the
+// panel was empty while her weekly limit sat at 100% used.
+//
+// SO THERE IS A THIRD SOURCE, AND IT BREAKS NEITHER HALF OF THAT RULE. Codex
+// writes every rate-limit report it receives into its own session log under
+// CODEX_HOME, as a `rate_limits` object on the `token_count` events. Reading it
+// starts no process, sends nothing anywhere, and touches no credential: it is a
+// file on her disk that Codex put there. Measured on her Mac 2026-09-18: 1,140
+// such records across her twenty-five most recent sessions, the newest written
+// the same minute she filed the row.
+//
+// THE PUSH STILL WINS. A live notification is this second's truth and a log is
+// the last thing anybody wrote down, so main/codex-usage.mjs reads this only when
+// it has nothing of its own. Nothing about the existing path changes.
+//
+// IT IS THE SAME ACCOUNT OR IT IS NOT READ. One CODEX_HOME is one login, and the
+// log lives inside the home, so a reading taken from `~/.codex/sessions` is a
+// fact about whoever is signed into `~/.codex` and about nobody else. The home is
+// handed in for exactly that reason, never guessed at here.
+//
+// THE FILES ARE ENORMOUS AND ARE NEVER READ WHOLE. Her newest session log was
+// 791 MB on the day this was written. Only the tail of each is read, newest
+// first, and the answer is cached against the file's own modified time so an idle
+// app re-reads nothing.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * How much of the end of a session log to read. Her records sit roughly 1.6 MB
+ *  apart in the biggest file measured, so this holds several of them; a file
+ *  whose tail has none simply falls through to the next one. */
+const TAIL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * How many session logs to look back through before giving up. A log with no
+ *  rate limits in its tail is ordinary: a session can end on a long tool output.
+ *  Three is enough to cross that and is still three cheap reads. */
+const FILES = 3;
+
+/**
+ * Don't answer out of a log nobody has written to in a fortnight. A stale
+ *  percentage is worse than no percentage, and the panel says how old its reading
+ *  is rather than hiding it, so this only has to catch the absurd cases. */
+const TOO_OLD_MS = 14 * 24 * 60 * 60 * 1000;
+
+const plain = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * A window is only worth having if it says how much is spent. Either spelling,
+ *  because the log is snake_case and the push is camel. */
+const usable = (window) => plain(window)
+  && (Number.isFinite(window.used_percent) || Number.isFinite(window.usedPercent));
+
+/**
+ * THE NEWEST SESSION LOGS UNDER THIS HOME, newest first.
+ *
+ * Codex files them by date (`sessions/2026/09/18/rollout-....jsonl`), so the
+ * walk is three levels of directory and never a full recursive scan of a folder
+ * holding a thousand files. Only the newest day or two is ever opened.
+ */
+function newestLogs(home, limit = FILES) {
+  const root = path.join(home, 'sessions');
+  const found = [];
+  const descend = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    if (depth === 0) {
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+        const file = path.join(dir, entry.name);
+        try { found.push({ file, at: fs.statSync(file).mtimeMs }); } catch { /* it went away */ }
+      }
+      return;
+    }
+    // Newest folder first, and only a couple of them: the name sorts as the date
+    // because Codex names them for the date.
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort().reverse().slice(0, 2);
+    for (const name of dirs) descend(path.join(dir, name), depth - 1);
+  };
+  descend(root, 3);
+  return found.sort((a, b) => b.at - a.at).slice(0, limit);
+}
+
+/** The end of a file, without reading the front of it. */
+function tail(file, bytes = TAIL_BYTES) {
+  let fd = null;
+  try {
+    fd = fs.openSync(file, 'r');
+    const size = fs.fstatSync(fd).size;
+    const take = Math.min(size, bytes);
+    const buffer = Buffer.allocUnsafe(take);
+    fs.readSync(fd, buffer, 0, take, size - take);
+    return { text: buffer.toString('utf8'), whole: take === size };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) { try { fs.closeSync(fd); } catch { /* nothing to do */ } }
+  }
+}
+
+/**
+ * THE LAST RATE LIMITS THIS LOG RECORDS, or null.
+ *
+ * Lines are walked backwards because the last report is the one that is true. A
+ * report carrying no usable window is skipped rather than accepted: Codex emits
+ * an all-null snapshot for limit families that do not apply to the account (her
+ * `premium` family, every field null), and taking one of those would blank a
+ * panel that had a real figure a moment earlier.
+ */
+function lastLimitsIn(file) {
+  const read = tail(file);
+  if (!read) return null;
+  const lines = read.text.split('\n');
+  // The first line is a fragment unless the whole file was read, and a fragment
+  // is not JSON.
+  if (!read.whole) lines.shift();
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (!line || !line.includes('"rate_limits"')) continue;
+    let event = null;
+    try { event = JSON.parse(line); } catch { continue; }
+    const limits = find(event);
+    if (!limits) continue;
+    if (!usable(limits.primary) && !usable(limits.secondary)) continue;
+    const at = Date.parse(event?.timestamp ?? '');
+    return {
+      snapshot: { primary: limits.primary ?? null, secondary: limits.secondary ?? null },
+      at: Number.isFinite(at) ? at : null,
+    };
+  }
+  return null;
+}
+
+/**
+ * `rate_limits` sits a couple of levels inside the event and Codex has moved it
+ *  before, so it is looked for rather than reached for. */
+function find(node, depth = 0) {
+  if (!plain(node) || depth > 6) return null;
+  if (plain(node.rate_limits)) return node.rate_limits;
+  for (const value of Object.values(node)) {
+    const hit = find(value, depth + 1);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * What was read last, so an app nobody is touching re-reads nothing. Keyed by
+ *  home, and thrown away when the newest log is written to again. */
+const remembered = new Map();
+
+/**
+ * THE LAST FIGURE CODEX WROTE DOWN UNDER THIS HOME, or null because it never
+ * wrote one. Null is an ordinary answer on a Mac where Codex has never run.
+ *
+ * @param {string|null} home The CODEX_HOME this reading would belong to.
+ * @returns {{ snapshot: object, at: number }|null}
+ */
+export function loggedCodexLimits(home, { now = Date.now() } = {}) {
+  if (!home) return null;
+  const logs = newestLogs(home);
+  if (!logs.length) return null;
+  if (now - logs[0].at > TOO_OLD_MS) return null;
+
+  const seen = remembered.get(home);
+  if (seen && seen.file === logs[0].file && seen.at === logs[0].at) return seen.reading;
+
+  let reading = null;
+  for (const log of logs) {
+    reading = lastLimitsIn(log.file);
+    if (reading) {
+      // The event's own timestamp when it has one, and the file's otherwise.
+      if (reading.at === null) reading = { ...reading, at: log.at };
+      break;
+    }
+  }
+  remembered.set(home, { file: logs[0].file, at: logs[0].at, reading });
+  return reading;
+}
+
+/** Drop what was remembered. For tests, and for a home that has changed under us. */
+export function forgetLoggedLimits() {
+  remembered.clear();
+}

package/main/codex-usage.mjs

@@ -0,0 +1,149 @@
+// WHAT CODEX HAS ALREADY SAID IS LEFT, AND NOTHING IS SPENT ASKING.
+//
+// The pure half is shared/codex-usage.mjs: the payload in, the limits out. This
+// is the half that holds what a running app-server reported, and the whole of
+// its shape is two rules.
+//
+// NEVER SPAWN ANYTHING TO DRAW A PICTURE. main/claude-usage.mjs is built around
+// the opposite fact -- `claude -p /usage` costs a child process and twenty-five
+// seconds, so it is a cache with a background refresh and a thirty-minute
+// backoff after a miss. None of that applies here and none of it is copied.
+// Codex's figures ride the `codex app-server` THE FLEET IS ALREADY RUNNING:
+// they arrive unprompted as `account/rateLimits/updated` during a turn.
+//
+// AND NEVER ASK FOR ONE EITHER (the founder, 2026-09-05). This reader briefly
+// also sent an explicit rate-limits read down that pipe whenever its figure
+// went stale. It is deliberately gone, and this paragraph is here so the next
+// reader does not put it back as an obvious improvement.
+//
+//   IT IS NOT A LOCAL LOOKUP. Measured on this Mac 2026-09-05 against a real
+//   `codex app-server` 0.148.0 in a scratch CODEX_HOME with no credentials, that
+//   read answered `{"error":{"code":-32600,"message":"codex account
+//   authentication required to read rate limits"}}` -- an auth demand, not an
+//   empty snapshot. A call served out of state the app-server already holds does
+//   not need an account token; one that has to SEND that token does. The binary
+//   agrees: `app-server/src/request_processors/account_processor.rs` reaches
+//   `backend-client/src/client/rate_limit_resets.rs`, and the strings beside it
+//   are `/api/codex/usage`, `https://chatgpt.com/backend-api`, `failed to fetch
+//   codex rate limits: no snapshots returned` and `rate limit reset credit
+//   detail request timed out`. Local state does not time out, and has no
+//   snapshots to fail to return.
+//
+//   SO IT IS A NEW NETWORK CALL, and CLAUDE.md's rule on those is not
+//   negotiable: "Anything that leaves the machine... a new network call of any
+//   kind" means `legal/privacy.html` and `legal/terms.html` are edited IN THE
+//   SAME SESSION. Those pages live in the founder's store rather than in this
+//   repo, so that obligation cannot be discharged from a session working here,
+//   and shipping the call without it would break a stated law rather than bend
+//   one.
+//
+//   THE COST OF LIVING WITHOUT IT WAS MEASURED AND IS SMALL. The push is free
+//   and already arrives, so the corner fills a beat later -- once a Codex turn
+//   starts pushing -- rather than being asked for. And a workspace set to Codex
+//   with nothing running drew no corner either way, because there was no
+//   app-server there to ask.
+//
+// SO THERE IS NO READING AT ALL UNTIL A TURN REPORTS ONE, AND THAT IS A NORMAL
+// TUESDAY rather than a failure. On a Mac where no Codex work has run the corner
+// draws nothing, and nothing was spent finding that out. That is the honest
+// answer and the one the dashboard law asks for: a limit nobody has read is not
+// a limit at nothing, and it may never be drawn as a zero.
+//
+// A READING OUTLIVES THE PROCESS THAT GAVE IT, deliberately. The app-server
+// goes down with the last worker; the figures it reported are still the last
+// true thing anybody knows, and the panel already says how old they are.
+//
+// AND A READING BELONGS TO THE LOGIN THAT GAVE IT. There is one app-server per
+// CODEX_HOME since a second Codex login became real (`_codexServer` in
+// main/supervisor.mjs), and CODEX_HOME is the variable that names which account
+// pays. A reading taken under one home is not a fact about another, so it is
+// dropped rather than redrawn when the home moves. Showing login A's percentage
+// over login B's work is exactly the defect this whole slice is fixing, one
+// level down.
+
+import { codexLimits, mergeRateLimits } from '../shared/codex-usage.mjs';
+import { loggedCodexLimits } from './codex-usage-file.mjs';
+
+export class CodexUsage {
+  /**
+   * @param {object} how @param { => string|null} how.home Which CODEX_HOME the
+   * current login is, so a reading taken under another one is dropped rather
+   * than redrawn. @param { => void} [how.onChange] Told when the figures move,
+   * so the window redraws. Never called for an update that changed nothing.
+   */
+  constructor({ home = () => null, onChange = () => {}, now = () => Date.now(), readLog = loggedCodexLimits } = {}) {
+    this._home = home;
+    this._onChange = onChange;
+    this._now = now;
+    /** Handed in so a test can answer without a session log on disk. */
+    this._readLog = readLog;
+    /** @type {{ primary: object|null, secondary: object|null }|null} */
+    this._snapshot = null;
+    this._at = 0;
+    this._takenUnder = null;
+  }
+
+  /**
+   * THE LAST THING CODEX REPORTED, INSTANTLY AND WITHOUT ASKING ANYBODY.
+   *
+   * Null until the first push lands, which on most Macs is for ever, because
+   * most Macs never run a Codex worker. The corner draws nothing then rather
+   * than a bar full of zeroes: a limit nobody has read is not a limit at
+   * nothing.
+   */
+  read() {
+    if (this._takenUnder !== null && this._takenUnder !== this._home()) this._forget();
+    const limits = codexLimits(this._snapshot);
+    if (limits.length) return { limits, at: this._at };
+    // NOTHING HAS PUSHED, SO ASK WHAT CODEX ALREADY WROTE DOWN. This is the
+    // whole of: the push only ever arrives for work the app itself ran, and she
+    // runs Codex in its own app, so on her Mac the panel stayed empty while her
+    // weekly limit was full. main/codex-usage-file.mjs is a read of a file
+    // under this same CODEX_HOME. It starts no process and sends nothing
+    // anywhere, so neither rule above is bent.
+    return this._logged();
+  }
+
+  /**
+   * The last figure in Codex's own session log under this home, shaped exactly
+   *  like a pushed one. Null on a Mac where Codex has never run. */
+  _logged() {
+    const reading = this._readLog(this._home(), { now: this._now() });
+    const limits = codexLimits(reading?.snapshot);
+    return limits.length ? { limits, at: reading.at } : null;
+  }
+
+  /**
+   * A NOTIFICATION OFF THE APP-SERVER'S LOOSE CHANNEL, AND THE ONLY WAY A FIGURE
+   * EVER GETS IN HERE. Everything that belongs to no thread arrives on it
+   * (main/codex-app-server.mjs `onNotification`), so this is handed every one of
+   * them and keeps the one it is about.
+   *
+   * IT MERGES. The update is documented sparse -- see shared/codex-usage.mjs for
+   * the schema's own wording -- so a notification carrying only the five hour
+   * window must not take the week away with it.
+   */
+  saw(method, params, home = this._home()) {
+    if (method !== 'account/rateLimits/updated') return false;
+    // A login that is not the one the corner is about has nothing to say about
+    // it. There is one app-server per home and they all report through here.
+    if (home !== this._home()) return false;
+    return this._keep(mergeRateLimits(this._snapshot, params?.rateLimits), home);
+  }
+
+  _keep(snapshot, home) {
+    const before = JSON.stringify(this._snapshot);
+    this._snapshot = snapshot;
+    this._at = this._now();
+    this._takenUnder = home;
+    if (JSON.stringify(snapshot) === before) return false;
+    this._onChange();
+    return true;
+  }
+
+  _forget() {
+    this._snapshot = null;
+    this._at = 0;
+    this._takenUnder = null;
+  }
+}

package/main/codex-watch.mjs

@@ -0,0 +1,35 @@
+// THE WATCH THAT NOTICES A CODEX CONVERSATION AND ASKS.
+//
+// Her pick on 19:53: "ask first". So every minute this reads the conversations
+// she had in Codex this week, and for each one that runs in a folder one of her
+// projects points at and has no row anywhere yet, it files the asking row in
+// that project. It also keeps the rows she said yes to current: when Codex
+// writes another answer, the row's result follows it.
+//
+// A conversation in a folder no project points at gets no row here. It is
+// still on the ⌘K import card, under a section that makes the project on the
+// press, which is the card's own way of handling a new folder.
+import { readCodexThreads } from './codex-threads.mjs';
+
+export const CODEX_POLL_MS = 60_000;
+
+export function scanCodex({ store, readThreads = readCodexThreads, now = Date.now() } = {}) {
+  let threads = [];
+  try { ({ threads } = readThreads({ now })); } catch { return { asked: 0, refreshed: 0, retold: 0, threads: 0 }; }
+  const asked = store.askAboutCodexThreads(threads, { now });
+  const refreshed = store.refreshCodexMirrors(threads, { now });
+  const retold = store.refreshCodexAsks(threads, { now });
+  return { asked, refreshed, retold, threads: threads.length };
+}
+
+export function startCodexWatch({ store, readThreads = readCodexThreads, pollMs = CODEX_POLL_MS, firstDelayMs = 8_000 } = {}) {
+  const run = () => {
+    try { scanCodex({ store, readThreads }); } catch (e) { console.warn('codex watch:', e?.message ?? e); }
+  };
+  const first = setTimeout(run, firstDelayMs);
+  const timer = setInterval(run, pollMs);
+  return {
+    scanNow: run,
+    stop: () => { clearTimeout(first); clearInterval(timer); },
+  };
+}