context-carwash 0.2.0 → 0.2.2

package/src/wash/hooks.mjs

@@ -1,44 +1,60 @@
 import { existsSync, writeFileSync } from 'node:fs';
 import { packageVersion } from '../install/install.mjs';
 import { startNotice, versionLine } from '../install/notice.mjs';
+import { isNewer } from '../install/update.mjs';
 import { DEFAULT_LEVEL, capFor, estimateTokens, isLevel } from '../levels.mjs';
 import { installRecordPath, welcomedPath } from '../paths.mjs';
-import { recordDelivery, recordWash, refreshLedger, totals } from '../stats/ledger.mjs';
-import { statsReport } from '../stats/report.mjs';
-import { budgetNote, composeContext, describe, helpMessage, loadedMessage, parseReply, pointerMessage, readyMessage, retryNote, stalenessLine, welcomeMessage } from './brief.mjs';
+import { recordDelivery, recordWash, refreshLedger } from '../stats/ledger.mjs';
+import { colorDepth } from '../statusline/color.mjs';
+import { currentTotals, statsReport } from '../stats/report.mjs';
+import { budgetNote, composeContext, describe, helpMessage, loadedMessage, parseReply, pointerMessage, readyMessage, replyMeterMessage, retryNote, stalenessLine, welcomeMessage } from './brief.mjs';
+import { isTool, toolInfo, toolOf } from '../tools.mjs';
 import { repoState, worktreeRoot } from './git.mjs';
-import { currentProcess, isRunning, sameProcess } from './process.mjs';
+import { codexProcess, codexUnattended, currentProcess, isRunning, sameProcess } from './process.mjs';
+import { readCodexReplyUsage, readCodexUsage, readCodexVersion } from './rollout.mjs';
 import { currentWash, endWash, loadUsage, startWash } from './session.mjs';
 import { AUTO_LOAD_MS, addRecord, claim, findRecords, purge, readyRecords, removeRecord, reopen, updateRecord } from './store.mjs';
 
-// Carwash's three Claude Code hooks:
+// Carwash's three hooks, in Claude Code and in Codex:
 //
-//   UserPromptExpansion  /wash was typed. A level starts a wash and tells
-//                        Claude the size limit; discard, load, stats and help are
-//                        handled here and never reach Claude.
-//   Stop                 Claude finished replying. If that reply is the brief,
-//                        save it.
+//   UserPromptExpansion  /wash was typed (Claude Code). In Codex, where $wash
+//   UserPromptSubmit     is a skill, every prompt comes through
+//                        UserPromptSubmit and only one starting with $wash is
+//                        ours. A level starts a wash and tells the model the
+//                        size limit; discard, load, stats and help are handled
+//                        here and never reach the model.
+//   Stop                 The model finished replying. If that reply is the
+//                        brief, save it. Otherwise, in Codex, show the meter.
 //   SessionStart         A session began. If a brief is meant for it, hand the
 //                        brief over. The first one after install says hello.
 //                        It also starts the daily update check, in the
 //                        background, and passes on what the last one found.
 //
-// Each handler returns the JSON to print for Claude Code, or null to stay out
-// of the way. None of them ever clears, restarts, or runs anything.
+// Each handler returns the JSON to print for the tool, or null to stay out of
+// the way. None of them ever clears, restarts, or runs anything. Both tools
+// read the same JSON fields here, apart from how a Stop asks for another try.
 
-const USAGE = 'Usage: /wash [light | mid | detailed], /wash discard [id], /wash load [id], /wash stats, /wash help';
+const usageLine = (tool) => {
+  const wash = toolInfo(tool).wash;
+  return `Usage: ${wash} [light | mid | detailed], ${wash} discard [id], ${wash} load [id], ${wash} stats, ${wash} help`;
+};
 
 // How many times to ask for a shorter brief before keeping an oversized one.
 const MAX_REWRITES = 2;
 
-// Stops the command before it reaches Claude: no model turn, no cost. Claude
-// Code shows the reason under "operation blocked by hook", so it names us.
+// Stops the command before it reaches the model: no model turn, no cost.
+// Claude Code shows the reason under "operation blocked by hook", Codex under
+// "Blocked by hook", so it names us.
 const block = (reason) => ({ decision: 'block', reason: `Carwash: ${reason}` });
 
 // A `claude -p` run or other unattended session has nobody to carry on a
 // conversation, so it must not use up a brief meant for a person.
 const unattended = (env) => env.CLAUDE_CODE_SESSION_ATTENDED === '0' || /^sdk/.test(env.CLAUDE_CODE_ENTRYPOINT ?? '');
 
+// Claude Code gives each prompt an id that every Stop of its turn repeats;
+// Codex does the same with its turn id.
+const promptIdOf = (payload) => payload.prompt_id ?? payload.turn_id ?? null;
+
 // The savings ledger is bookkeeping: if it fails, the brief still has to work.
 function quietly(ctx, fn) {
   try {
@@ -48,33 +64,55 @@ function quietly(ctx, fn) {
   }
 }
 
+// A question asked at most once per hook call.
+const once = (ask) => {
+  let answer;
+  return () => (answer ??= ask());
+};
+
 const cwdOf = (payload) => (typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd());
 
 // --- /wash ---------------------------------------------------------------
 
 function onExpansion(payload, ctx) {
   if (String(payload.command_name ?? '').replace(/^\//, '') !== 'wash') return null;
-  const [verb = DEFAULT_LEVEL, ref] = String(payload.command_args ?? '').trim().toLowerCase().split(/\s+/).filter(Boolean);
-  if (isLevel(verb)) return begin(payload, verb, ctx);
+  return washCommand(payload, payload.command_args, 'UserPromptExpansion', ctx);
+}
+
+// Codex runs this for every prompt, so anything that is not $wash returns at
+// once, before any file or process is looked at.
+const DOLLAR_WASH = /^\s*\$wash(?![\w-])([\s\S]*)$/;
+
+function onPromptSubmit(payload, ctx) {
+  const found = typeof payload.prompt === 'string' ? DOLLAR_WASH.exec(payload.prompt) : null;
+  return found ? washCommand(payload, found[1], 'UserPromptSubmit', ctx) : null;
+}
+
+function washCommand(payload, args, event, ctx) {
+  const [verb = DEFAULT_LEVEL, ref] = String(args ?? '').trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (isLevel(verb)) return begin(payload, verb, event, ctx);
   if (verb === 'discard') return block(discard(payload, ref, ctx));
   if (verb === 'load') return block(load(payload, ref, ctx));
-  if (verb === 'stats') return block(statsReport(totals(refreshLedger(ctx.env, { now: ctx.now, force: true }), ctx.now), { inClaude: true }));
-  if (verb === 'help') return block(helpMessage(loadUsage(ctx.env, payload.session_id)?.used ?? null, versionLine(ctx.version, ctx.env)));
-  return block(`/wash does not know "${verb}". ${USAGE}`);
+  if (verb === 'stats') return block(statsReport(currentTotals(ctx.env, ctx.now), { inClaude: true }));
+  if (verb === 'help') return block(helpMessage(ctx.usage(payload)?.used ?? null, versionLine(ctx.version, ctx.env), ctx.tool));
+  return block(`${toolInfo(ctx.tool).wash} does not know "${verb}". ${usageLine(ctx.tool)}`);
 }
 
-function begin(payload, level, { env, now }) {
-  const usage = loadUsage(env, payload.session_id);
+function begin(payload, level, event, ctx) {
+  const { env, now } = ctx;
+  const usage = ctx.usage(payload);
   const used = usage?.used ?? null;
   const cap = capFor(level, used);
-  startWash(env, payload.session_id, { promptId: payload.prompt_id ?? null, level, cap, used, size: usage?.size ?? null, startedAt: now, rewrites: 0 });
-  return { hookSpecificOutput: { hookEventName: 'UserPromptExpansion', additionalContext: budgetNote(level, cap, used) } };
+  startWash(env, payload.session_id, { promptId: promptIdOf(payload), level, cap, used, size: usage?.size ?? null, startedAt: now, rewrites: 0 });
+  return { hookSpecificOutput: { hookEventName: event, additionalContext: budgetNote(level, cap, used) } };
 }
 
-// Briefs waiting for the folder this session is in, other than its own.
-function waitingHere(payload, { env, now, me }) {
+// Briefs waiting for the folder this session is in, other than its own. Only
+// ones written in the same tool: a brief from the other one is used only when
+// asked for by its id.
+function waitingHere(payload, { env, now, me, tool }) {
   const here = worktreeRoot(cwdOf(payload));
-  return readyRecords(env, now).filter((record) => record.source?.worktree === here && !sameProcess(record.owner, me));
+  return readyRecords(env, now).filter((record) => record.source?.worktree === here && toolOf(record) === tool && !sameProcess(record.owner, me));
 }
 
 function discard(payload, ref, ctx) {
@@ -93,7 +131,7 @@ function discard(payload, ref, ctx) {
     return `discarded brief ${describe(mine[0], now)}. /clear is a normal clear again.`;
   }
   const others = waitingHere(payload, ctx);
-  const hint = others.length ? ` Waiting for this folder: ${others.map((record) => describe(record, now)).join(' · ')}. To drop one: /wash discard <id>.` : '';
+  const hint = others.length ? ` Waiting for this folder: ${others.map((record) => describe(record, now)).join(' · ')}. To drop one: ${toolInfo(ctx.tool).wash} discard <id>.` : '';
   return `no brief is ready in this session, so there was nothing to discard.${hint}`;
 }
 
@@ -119,49 +157,72 @@ function load(payload, ref, ctx) {
   } else {
     const others = waitingHere(payload, ctx);
     if (!others.length) return 'no briefs are waiting for this folder.';
-    if (others.length > 1) return `more than one brief is waiting for this folder: ${others.map((record) => describe(record, now)).join(' · ')}. Pick one: /wash load <id>.`;
+    if (others.length > 1) return `more than one brief is waiting for this folder: ${others.map((record) => describe(record, now)).join(' · ')}. Pick one: ${toolInfo(ctx.tool).wash} load <id>.`;
     match = { record: others[0], consumed: false };
   }
   const record = match.consumed ? reopen(env, match.record) : match.record;
   if (!record) return `brief ${match.record.id} could not be loaded: another session took it just now.`;
   const owned = adopt(record, payload, ctx);
   const elsewhere = owned.source?.worktree && owned.source.worktree !== worktreeRoot(cwdOf(payload)) ? ` Note: it was written in a different folder, ${owned.source.worktree}.` : '';
-  return `brief ${describe(owned, now)} is ready ✓ Type /clear to start fresh with it.${elsewhere}`;
+  return `brief ${describe(owned, now)} is ready ✓ ${toolInfo(ctx.tool).afterClear}${elsewhere}`;
 }
 
 // --- Stop ----------------------------------------------------------------
 
+// Where the status line cannot show the meter (Codex), it follows each reply
+// instead. It goes to the user only, never to the model, so it costs nothing.
+function replyMeter(payload, ctx) {
+  if (!toolInfo(ctx.tool).replyMeter) return null;
+  const usage = ctx.replyUsage(payload);
+  if (!usage) return null;
+  const depth = codexShowsColor(ctx.codexVersion(payload)) ? colorDepth(ctx.env) : 'none';
+  return { systemMessage: replyMeterMessage(usage, ctx.tool, depth) };
+}
+
+// Codex draws colour codes in a hook's message from 0.162.0 on (openai/codex
+// #50359). Before that they would show as stray characters, so an unknown
+// version gets plain text.
+const COLOR_SINCE = '0.162.0';
+const codexShowsColor = (version) => /^\d+\.\d+\.\d+$/.test(version ?? '') && !isNewer(COLOR_SINCE, version);
+
 function onStop(payload, ctx) {
   const { env, now, me } = ctx;
   const sessionId = payload.session_id;
   const wash = currentWash(env, sessionId, now);
-  if (!wash) return null;
+  if (!wash) return replyMeter(payload, ctx);
 
-  // Claude Code gives a prompt and every Stop of its turn the same id. A Stop
-  // for some other prompt means the wash turn ended without one of its own:
-  // it was interrupted.
-  if (wash.promptId && payload.prompt_id && wash.promptId !== payload.prompt_id) {
+  // Claude Code gives a prompt and every Stop of its turn the same id, and
+  // Codex its turn id, including the Stops after asking for a shorter brief. A
+  // Stop for some other prompt means the wash turn ended without one of its
+  // own: it was interrupted.
+  const promptId = promptIdOf(payload);
+  if (wash.promptId && promptId && wash.promptId !== promptId) {
     endWash(env, sessionId);
-    return null;
+    return replyMeter(payload, ctx);
   }
 
   const reply = parseReply(payload.last_assistant_message);
   if (!reply) {
     endWash(env, sessionId);
-    return { systemMessage: 'Carwash: that reply was not a brief, so nothing was saved. Run /wash again to retry.' };
+    return { systemMessage: `Carwash: that reply was not a brief, so nothing was saved. Run ${toolInfo(ctx.tool).wash} again to retry.` };
   }
 
   const tokens = estimateTokens(reply.text);
   const overCap = Boolean(wash.cap) && tokens > wash.cap;
   if (overCap && wash.rewrites < MAX_REWRITES) {
     startWash(env, sessionId, { ...wash, rewrites: wash.rewrites + 1 });
-    return { hookSpecificOutput: { hookEventName: 'Stop', additionalContext: retryNote(wash.level, wash.cap, tokens) } };
+    const note = retryNote(wash.level, wash.cap, tokens);
+    // Codex continues the turn with a Stop's block reason as the next prompt.
+    if (ctx.tool === 'codex') return { decision: 'block', reason: note };
+    return { hookSpecificOutput: { hookEventName: 'Stop', additionalContext: note } };
   }
 
   const cwd = cwdOf(payload);
   const record = addRecord(
     env,
     {
+      // Briefs from Claude Code carry no tool, as before Codex support.
+      ...(ctx.tool === 'claude' ? {} : { tool: ctx.tool }),
       level: wash.level,
       title: reply.title,
       tokens,
@@ -192,10 +253,10 @@ function deliver(record, payload, ctx) {
   const { env, now } = ctx;
   // Another session may have taken it between the listing and now.
   if (!claim(env, record, payload.session_id, now)) return null;
-  quietly(ctx, () => recordDelivery(env, record, payload, now));
+  quietly(ctx, () => recordDelivery(env, record, payload, now, ctx.tool));
   const stale = stalenessLine(record.source, repoState(cwdOf(payload)));
   return {
-    systemMessage: loadedMessage(record, now, stale),
+    systemMessage: loadedMessage(record, now, stale, ctx.tool),
     hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: composeContext(record, now, stale) },
   };
 }
@@ -204,22 +265,27 @@ function deliver(record, payload, ctx) {
 // marker is the claim, so two sessions starting together cannot both say it.
 // Uninstall deletes the marker with the rest of ~/.carwash, so a reinstall
 // says it again. Without an install record there is nobody to welcome.
-function welcome({ env, now }) {
-  if (!existsSync(installRecordPath(env))) return null;
+function welcome(ctx) {
+  const { env, now, tool } = ctx;
+  if (!existsSync(installRecordPath(env)) || existsSync(welcomedPath(env, tool))) return null;
+  if (ctx.unattended()) return null;
   try {
-    writeFileSync(welcomedPath(env), `${new Date(now).toISOString()}\n`, { flag: 'wx', mode: 0o600 });
+    writeFileSync(welcomedPath(env, tool), `${new Date(now).toISOString()}\n`, { flag: 'wx', mode: 0o600 });
   } catch {
     // Already shown, or nowhere to note it: better silent than said every time.
     return null;
   }
-  return { systemMessage: welcomeMessage() };
+  return { systemMessage: welcomeMessage(tool) };
 }
 
 function onSessionStart(payload, ctx) {
   // Only a brand-new conversation gets a brief; a resumed, compacted or
   // forked one already has its own history.
   if (payload.source !== 'startup' && payload.source !== 'clear') return null;
-  if (unattended(ctx.env)) return null;
+  // Claude Code says in its environment whether anyone is there. Codex has to
+  // be asked through its command line, which on Windows takes a PowerShell
+  // run, so it is asked only once a brief or the welcome is at stake.
+  if (ctx.tool === 'claude' && ctx.unattended()) return null;
   // The welcome waits for a start that has nothing else to say.
   const result = briefAtStart(payload, ctx) ?? welcome(ctx);
   quietly(ctx, () => ctx.checkUpdates?.());
@@ -241,7 +307,7 @@ function briefAtStart(payload, ctx) {
     const named = ready.find((record) => record.id === env.CARWASH_PENDING);
     return named ? deliver(named, payload, ctx) : null;
   }
-  if (!ready.length) return null;
+  if (!ready.length || ctx.unattended()) return null;
 
   if (payload.source === 'clear') {
     // /clear keeps the process, so the brief this terminal asked for is the
@@ -261,46 +327,63 @@ function briefAtStart(payload, ctx) {
 
   // A new process picks up a brief left for its folder, but only when there is
   // no doubt which one is meant. Otherwise it says what is waiting and loads
-  // nothing: the wrong context is worse than none.
+  // nothing: the wrong context is worse than none. A brief written in the other
+  // tool is not picked up this way.
   const here = worktreeRoot(cwdOf(payload));
-  const waiting = ready.filter((record) => record.source?.worktree === here);
+  const waiting = ready.filter((record) => record.source?.worktree === here && toolOf(record) === ctx.tool);
   if (!waiting.length) return null;
   let why = null;
   if (waiting.length > 1) why = 'there is more than one';
   else if (now - Date.parse(waiting[0].createdAt) > AUTO_LOAD_MS) why = 'it is over 12 hours old';
   else if (ctx.isRunning(waiting[0].owner)) why = 'the session that wrote it is still open';
-  return why ? { systemMessage: pointerMessage(waiting, now, why) } : deliver(waiting[0], payload, ctx);
+  return why ? { systemMessage: pointerMessage(waiting, now, why, ctx.tool) } : deliver(waiting[0], payload, ctx);
 }
 
 // --- entry point -----------------------------------------------------------
 
-// Handle one hook call. `input` is the JSON Claude Code sends on stdin.
+// Handle one hook call. `input` is the JSON the tool sends on stdin, and
+// `tool` says which tool that is: 'claude' (Claude Code) or 'codex'.
 //
 // `checkUpdates` starts the daily update check. Only the real command passes
-// it, so tests never go online.
-export function runHook({ input, env = process.env, platform = process.platform, now = Date.now(), me, running, onError, checkUpdates, version = packageVersion() } = {}) {
+// it, so tests never go online. `unattended` and `usage` stand in for asking
+// the system, in tests.
+export function runHook({ input, tool = 'claude', env = process.env, platform = process.platform, now = Date.now(), me, running, onError, checkUpdates, version = packageVersion(), unattended: isUnattended, usage, replyUsage } = {}) {
   let payload;
   try {
     payload = JSON.parse(input);
   } catch {
     return null;
   }
-  if (!payload || typeof payload !== 'object') return null;
+  if (!payload || typeof payload !== 'object' || !isTool(tool)) return null;
+  const codex = tool === 'codex';
+  const self = me ?? (codex ? codexProcess(platform) : currentProcess(env, platform));
   const ctx = {
+    tool,
     env,
     now,
-    me: me ?? currentProcess(env, platform),
+    me: self,
     isRunning: running ?? ((owner) => isRunning(owner, platform)),
     onError,
     checkUpdates,
     version,
+    unattended: once(isUnattended ?? (() => (codex ? codexUnattended(self.args) : unattended(env)))),
+    // How much context the session is using. Claude Code's status line notes
+    // it as it draws the meter; Codex writes it into its session file.
+    usage: usage ?? ((p) => (codex ? readCodexUsage(p.transcript_path) : loadUsage(env, p.session_id))),
+    // The same once a reply has ended, waiting briefly for Codex to note it.
+    replyUsage: replyUsage ?? ((p) => readCodexReplyUsage(p.transcript_path)),
+    codexVersion: (p) => readCodexVersion(p.transcript_path),
   };
-  switch (payload.hook_event_name) {
-    case 'UserPromptExpansion':
+  switch (`${tool}:${payload.hook_event_name}`) {
+    case 'claude:UserPromptExpansion':
       return onExpansion(payload, ctx);
-    case 'Stop':
+    case 'codex:UserPromptSubmit':
+      return onPromptSubmit(payload, ctx);
+    case 'claude:Stop':
+    case 'codex:Stop':
       return onStop(payload, ctx);
-    case 'SessionStart':
+    case 'claude:SessionStart':
+    case 'codex:SessionStart':
       return onSessionStart(payload, ctx);
     default:
       return null;

package/src/wash/process.mjs

@@ -40,6 +40,117 @@ export function currentProcess(env = process.env, platform = process.platform) {
   };
 }
 
+// A process's parent and its command line, or null where it cannot be told or
+// the process has gone. On macOS the arguments come back joined by spaces, so
+// an argument that contains a space reads as several.
+export function processInfo(pid, platform = process.platform) {
+  try {
+    if (platform === 'win32') return windowsInfo(pid);
+    if (platform === 'linux') {
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const ppid = Number.parseInt(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1], 10);
+      const args = readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean);
+      return Number.isInteger(ppid) ? { ppid, args } : null;
+    }
+    const result = spawnSync('ps', ['-o', 'ppid=,args=', '-p', String(pid)], { encoding: 'utf8', timeout: 1000 });
+    const found = result.status === 0 && /^\s*(\d+)\s+(.*\S)/.exec(result.stdout);
+    return found ? { ppid: Number(found[1]), args: found[2].split(/\s+/) } : null;
+  } catch {
+    return null;
+  }
+}
+
+// Windows has no quick `ps`, so one PowerShell run reads a process and the
+// few above it, and the answers are kept for the rest of this hook call. It is
+// slow, so Codex's hooks only ask when a brief is at stake.
+const windowsSeen = new Map();
+function windowsInfo(pid) {
+  if (windowsSeen.has(pid)) return windowsSeen.get(pid);
+  windowsSeen.set(pid, null);
+  // [wmi] reads straight from WMI, without loading the CIM cmdlets first.
+  const script =
+    `$p=${Number(pid)};$o=@();for($i=0;$i -lt 4 -and $p;$i++){` +
+    'try{$w=[wmi]"Win32_Process.Handle=\'$p\'"}catch{break};' +
+    '$o+=[pscustomobject]@{pid=[int]$p;ppid=[int]$w.ParentProcessId;name=[string]$w.Name;cmd=[string]$w.CommandLine};$p=$w.ParentProcessId};' +
+    'ConvertTo-Json -Compress -InputObject @($o)';
+  // A cold PowerShell can take seconds; the hooks allow 20.
+  const result = spawnSync('powershell', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script], { encoding: 'utf8', timeout: 10_000, windowsHide: true });
+  if (result.status !== 0) return null;
+  for (const row of [JSON.parse(result.stdout)].flat()) {
+    if (!Number.isInteger(row?.pid)) continue;
+    // The program, then the words after it; the program's path may be quoted.
+    const rest = String(row.cmd ?? '').replace(/^\s*("[^"]*"|\S+)\s*/, '');
+    windowsSeen.set(row.pid, { ppid: row.ppid, args: [row.name || 'unknown', ...rest.split(/\s+/).filter(Boolean)] });
+  }
+  return windowsSeen.get(pid);
+}
+
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'mksh', 'fish', 'tcsh', 'csh', 'nu', 'pwsh', 'powershell', 'cmd']);
+const isShell = (program) => SHELLS.has(String(program ?? '').split(/[\\/]/).pop().replace(/^-/, '').replace(/\.exe$/i, '').toLowerCase());
+
+// The Codex process a hook is running under. Like Claude Code, it keeps one
+// process across /clear. Codex starts each hook through a shell: on macOS and
+// Linux the user's, which usually hands over to the command, so Codex is the
+// parent; on Windows cmd.exe, which stays in between. Where a shell is the
+// parent, Codex is the shell's parent. Nothing is looked up until it is asked
+// for: the hook that runs on every prompt mostly never needs it. Claude Code's
+// CLAUDE_PID is ignored, since Codex may have been started from a terminal
+// inside Claude Code.
+export function codexProcess(platform = process.platform, lookup = processInfo) {
+  let pid;
+  let info;
+  let start;
+  const resolve = () => {
+    if (pid !== undefined) return;
+    pid = process.ppid;
+    info = lookup(pid, platform);
+    for (let hops = 0; hops < 2 && info && isShell(info.args[0]) && info.ppid > 1; hops++) {
+      pid = info.ppid;
+      info = lookup(pid, platform);
+    }
+  };
+  return {
+    get pid() {
+      resolve();
+      return pid;
+    },
+    // Its command line, when it could be read.
+    get args() {
+      resolve();
+      return info?.args ?? null;
+    },
+    get start() {
+      if (start === undefined) start = processStart(this.pid, platform);
+      return start;
+    },
+  };
+}
+
+// Codex options that take a value, so the word after one is not a subcommand.
+const CODEX_VALUE_OPTIONS = new Set(['-c', '--config', '--enable', '--disable', '--remote', '--remote-auth-token-env', '-i', '--image', '-m', '--model', '--local-provider', '-p', '--profile', '-s', '--sandbox', '-a', '--ask-for-approval', '-C', '--cd', '--add-dir']);
+
+// The first word of a Codex command line that is not an option: a subcommand
+// such as `exec`, or the opening prompt.
+export function codexSubcommand(args) {
+  for (let i = 1; i < (args?.length ?? 0); i++) {
+    const arg = args[i];
+    if (arg === '--') return null;
+    if (arg.startsWith('-')) {
+      if (!arg.includes('=') && CODEX_VALUE_OPTIONS.has(arg)) i++;
+      continue;
+    }
+    return arg;
+  }
+  return null;
+}
+
+// Whether a Codex command line is a script's run (`codex exec`, `codex
+// review`) rather than a person's session. Unknown counts as a person.
+export function codexUnattended(args) {
+  const command = codexSubcommand(args);
+  return command === 'exec' || command === 'e' || command === 'review';
+}
+
 // Whether a brief's owner is this very process.
 export function sameProcess(owner, me) {
   if (!owner || owner.pid !== me.pid) return false;

package/src/wash/rollout.mjs

@@ -0,0 +1,111 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+
+// Codex keeps each session in a "rollout" file: one JSON object per line. Codex
+// says the format is not a stable interface, so everything here reads it
+// defensively and anything unexpected is simply not counted.
+//
+// After each request to the model Codex writes a token_count event, whose
+// last_token_usage.input_tokens is everything that request sent: the context
+// in use at that point. The status line gives Claude Code's equivalent.
+
+// Only the end of a long session file is read for the latest reading.
+const TAIL_BYTES = 4 * 1024 * 1024;
+
+// { used, size } from one rollout line, or null if it is not a token reading.
+export function tokenReading(line) {
+  const payload = line?.type === 'event_msg' ? line.payload : null;
+  if (payload?.type !== 'token_count') return null;
+  const used = payload.info?.last_token_usage?.input_tokens;
+  if (!Number.isFinite(used) || used <= 0) return null;
+  const size = payload.info.model_context_window;
+  return { used, size: Number.isFinite(size) && size > 0 ? size : null };
+}
+
+// The session file opens with a session_meta line, which can be long: it holds
+// the model's base instructions.
+const META_BYTES = 1024 * 1024;
+
+// The version of Codex that wrote a session file (its cli_version), or null.
+export function readCodexVersion(file) {
+  if (typeof file !== 'string' || !file) return null;
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const buffer = Buffer.alloc(Math.min(fstatSync(fd).size, META_BYTES));
+    readSync(fd, buffer, 0, buffer.length, 0);
+    const first = buffer.toString('utf8').split('\n', 1)[0];
+    const line = JSON.parse(first);
+    const version = line?.type === 'session_meta' ? line.payload?.cli_version : null;
+    return typeof version === 'string' ? version : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+// Whether a rollout line is a finished reply from the model.
+function isReply(line) {
+  const payload = line?.payload;
+  if (line?.type === 'event_msg') return payload?.type === 'item_completed' && payload.item?.type === 'AgentMessage';
+  return line?.type === 'response_item' && payload?.type === 'message' && payload.role === 'assistant';
+}
+
+// The latest token reading and whether it came after the latest reply, or null.
+function latestReading(file, tailBytes) {
+  if (typeof file !== 'string' || !file) return null;
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const { size } = fstatSync(fd);
+    const length = Math.min(size, tailBytes);
+    const buffer = Buffer.alloc(length);
+    readSync(fd, buffer, 0, length, size - length);
+    const lines = buffer.toString('utf8').split('\n');
+    let afterReply = true;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const text = lines[i];
+      const maybeReading = text.includes('token_count');
+      if (!maybeReading && !(afterReply && (text.includes('AgentMessage') || text.includes('"assistant"')))) continue;
+      let line;
+      try {
+        line = JSON.parse(text);
+      } catch {
+        continue;
+      }
+      const reading = maybeReading ? tokenReading(line) : null;
+      if (reading) return { reading, afterReply };
+      if (isReply(line)) afterReply = false;
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+// How much context a Codex session is using, from its latest token reading, or
+// null when it has none yet (or the file cannot be read).
+export function readCodexUsage(file, { tailBytes = TAIL_BYTES } = {}) {
+  return latestReading(file, tailBytes)?.reading ?? null;
+}
+
+// The reading for the reply that just ended, for the meter Codex shows after
+// it. Codex writes that reply's token_count a few milliseconds before its Stop
+// hook runs, close enough that the file may not have it yet. Until a reading
+// follows the reply, it is read again, briefly; after that the older reading
+// is used, which is only one request behind.
+const SETTLE_MS = 250;
+const RETRY_MS = 25;
+
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+export function readCodexReplyUsage(file, { tailBytes = TAIL_BYTES, settleMs = SETTLE_MS, wait = pause } = {}) {
+  let latest = latestReading(file, tailBytes);
+  for (let waited = 0; latest && !latest.afterReply && waited < settleMs; waited += RETRY_MS) {
+    wait(RETRY_MS);
+    latest = latestReading(file, tailBytes);
+  }
+  return latest?.reading ?? null;
+}