@assuredloop/orca-bot-kit 0.4.0 → 0.5.0

package/README.md

@@ -443,10 +443,23 @@ What it looks for:
   go, and a link with nothing at the end of it;
 - **a session the book knows that Orca does not**: its tab was closed, or the
   machine was restarted, and `obk up` brings it back;
+- **a session whose tab is open and whose harness is gone**: only the tab's
+  shell is in front, because the harness quit or crashed. `obk up` leaves an
+  open tab alone, so the finding names the `obk restart … --session` that
+  brings it back; when the book names no conversation for it, restart would
+  refuse, and the finding says to close the tab in Orca and run
+  `obk up … --session`. A tab the kit cannot read is never called down;
 - **leftovers no book owns**: an Orca project inside your bots folder with no
   bot in it, a tab in a bot's project that the book does not name, a start
   prompt written for a session that has gone, a clone of a skills source you no
   longer list, and the conversations the kit found and would not assign;
+- **a session running on something other than its bot asks for**: a model,
+  effort, context or approval level that the harness's own record of the
+  conversation says differs from `bot.yaml`, and a session that started before
+  its bot's `AGENTS.md` last changed, with what brings it up to date. Beside the
+  findings, each running session gets a line saying, for each setting, whether
+  it matches, differs, was not asked for, or cannot be told from the record;
+  cannot be told is never taken for a match;
 - **Orca's own default launch arguments**. Orca adds these to the agents it
   launches, relaunches and resumes, so when they carry a permission bypass every
   session runs in that mode whatever the kit asked for. The kit never sets that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/obk-bot-building/SKILL.md

@@ -302,7 +302,10 @@ it started, so a change to a bot's `AGENTS.md` may not reach one that is
 already up even when a skill change would, and a session's model, effort or
 approval only changes when it is started again (`obk restart`, on the user's
 word, and then read its tabs as above). Say which you changed, and what that
-means for the sessions running now. Where everything needs restarting, remind
+means for the sessions running now. `obk health` names each running session
+still on the older rules or on other settings, and what brings it up to date: on
+Claude Code a `/clear` reads the rules again, and a start does on both harnesses.
+Where everything needs restarting, remind
 them to do it from Bot Father's ops tab.
 
 And tell them. A bot's sessions share its rules and its skills, so a change

package/src/book.js

@@ -25,6 +25,9 @@ const HEADER = `# What Orca calls this bot on this machine, and where each of it
 # and kept, because an address that is a tab dies with the tab. \`address\` is what
 # a Claude session is called, which is what another Claude session writes to.
 #
+# \`rules\` is a stamp of the bot's AGENTS.md as the session last read it, so a
+# change to it after the session started can be told apart.
+#
 # \`retired\` holds what the book knew about each session \`obk retire\` took off
 # the bot, with when, so the conversations it had are still accounted for.
 `;

package/src/cli.js

@@ -451,11 +451,12 @@ const commands = {
 
   health(bots, values) {
     refuseWhenOrcaIsDown();
-    const found = checkHealth(bots, { bot: values.bot });
+    const { found, sessions } = checkHealth(bots, { bot: values.bot });
     return {
-      answer: { bots, found },
+      answer: { bots, found, sessions },
       lines: [
         ...foundLines(found),
+        ...sessions.map(settingsLine),
         found.length === 0
           ? `Nothing to report: everything the kit keeps is where it should be. Your bots folder: ${bots}`
           : `${found.length} thing${found.length === 1 ? '' : 's'} to look at above. What to do about each is yours to decide. Your bots folder: ${bots}`,
@@ -956,12 +957,15 @@ function usageLines(usage, bots) {
     lines.push(`${'bot'.padEnd(9)}  ${entry.bot}`);
     for (const session of entry.sessions) {
       lines.push(`${'session'.padEnd(9)}  ${session.name}`);
+      const notCounted = notCountedLine(session.not_counted);
       lines.push(...session.conversations.map(conversationLine));
-      if (session.conversations.length === 0) lines.push('             nothing on record');
+      if (session.conversations.length === 0 && notCounted.length === 0) lines.push('             nothing on record');
+      lines.push(...notCounted);
     }
-    if (entry.unclaimed.length > 0) {
+    if (entry.unclaimed.length > 0 || notCountedLine(entry.unclaimed_not_counted).length > 0) {
       lines.push(`${'unclaimed'.padEnd(9)}  ${entry.bot}: no session of this bot claims these`);
       lines.push(...entry.unclaimed.map(conversationLine));
+      lines.push(...notCountedLine(entry.unclaimed_not_counted));
     }
   }
 
@@ -971,6 +975,19 @@ function usageLines(usage, bots) {
   return lines;
 }
 
+/** What could not be counted, as one line, or no line when everything was. */
+function notCountedLine(gaps) {
+  const said = [
+    [gaps.unreadable_transcripts, 'transcript', 'transcripts', 'unreadable'],
+    [gaps.broken_lines, 'line', 'lines', 'broken'],
+    [gaps.records_without_numbers, 'record', 'records', 'with no usable number'],
+    [gaps.records_without_time, 'record', 'records', 'with no time'],
+  ]
+    .filter(([count]) => count > 0)
+    .map(([count, one, many, why]) => `${count} ${count === 1 ? one : many} ${why}`);
+  return said.length === 0 ? [] : [`             not counted: ${said.join(', ')}`];
+}
+
 /** One conversation: what it is, what it ran as, and what it used. */
 function conversationLine(one) {
   const ran = [...one.models, ...one.efforts].join(' ');
@@ -1128,6 +1145,25 @@ function toldLine(bot, { session, harness, state, read, blocked, trouble }) {
 const foundLines = (found) =>
   found.flatMap((one) => [`${one.kind.padEnd(9)}  ${one.where}`, `             ${one.says}`]);
 
+/**
+ * What one running session runs on, in a line: each setting's state, with what
+ * was asked for and what the harness recorded, and its rules.
+ */
+function settingsLine({ bot, session, running, settings, rules }) {
+  const each = Object.entries(settings).map(([name, one]) => {
+    const values = [
+      ...(one.configured === undefined ? [] : [`asked ${one.configured}`]),
+      ...(one.observed === undefined ? [] : [`runs ${one.observed}`]),
+    ];
+    return `${name} ${one.state}${values.length === 0 ? '' : ` (${values.join(', ')})`}`;
+  });
+  // A session whose harness the kit cannot see in its tab is not called running.
+  const [word, who] = running === 'yes'
+    ? ['running', `${bot} ${session}`]
+    : ['unsure', `${bot} ${session}  cannot tell whether its harness is running:`];
+  return `${word.padEnd(9)}  ${who}  ${each.join('  ')}  rules ${rules.state}`;
+}
+
 function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], projects = [], found = [] }, summary) {
   const lines = [
     ...created.map((entry) => `created    ${entry}`),
@@ -1177,6 +1213,7 @@ function harnessLines(tab, bots) {
       '             the harness was typed in, and no session came up in the tab.',
       `             Look at it:  ${lookAt(tab.terminal)}`,
       ...ANSWER_IT,
+      ...promptLines(tab),
     ];
   }
 
@@ -1198,14 +1235,21 @@ function harnessLines(tab, bots) {
       ...ANSWER_IT,
     ];
 
-  if (tab.promptSent === true) lines.push('             the start prompt was typed in.');
-  if (tab.promptSent === false) {
-    lines.push('             the start prompt was not typed in: the tab was not ready for it.');
-  }
+  lines.push(...promptLines(tab));
   if (tab.unclaimed !== undefined) lines.push(...unclaimedLines(tab, bots));
   return lines;
 }
 
+/**
+ * Whether the session got its start prompt, as its own record has it (#274):
+ * received, or not confirmed yet. Nothing for a session that was told nothing.
+ */
+function promptLines(tab) {
+  if (tab.promptReceived === true) return ['             the start prompt was received: the session\'s own record holds it.'];
+  if (tab.promptReceived === false) return ['             the start prompt is not confirmed: the session\'s own record does not hold it yet.'];
+  return [];
+}
+
 try {
   process.exitCode = await run(process.argv.slice(2));
 } catch (error) {

package/src/conversations.js

@@ -32,12 +32,17 @@ const codexDir = () => path.join(homedir(), '.codex', 'sessions');
  * then that it does not know, which is the honest one.
  */
 export function conversationsIn(harness, home, since) {
-  return transcriptsIn(harness, home, since).map((one) => ({ id: one.id, at: one.at }));
+  // A subagent's conversation ran in the folder too, but no session had it: the
+  // harness says it is a helper's, so it is never offered to one to claim.
+  return transcriptsIn(harness, home, since)
+    .filter((one) => !one.subagent)
+    .map((one) => ({ id: one.id, at: one.at }));
 }
 
 /**
  * The same conversations, each with the file the harness keeps it in, for a
- * caller that has to read what is inside one rather than only know it is there.
+ * caller that has to read what is inside one rather than only know it is there,
+ * and whether the harness marks it as a subagent's.
  */
 export function transcriptsIn(harness, home, since) {
   const from = since === undefined ? 0 : Date.parse(since);
@@ -45,7 +50,47 @@ export function transcriptsIn(harness, home, since) {
   return found
     .filter((one) => Number.isNaN(from) || one.at >= from)
     .sort((left, right) => left.at - right.at)
-    .map((one) => ({ id: one.id, at: new Date(one.at).toISOString(), file: one.file }));
+    .map((one) => ({ id: one.id, at: new Date(one.at).toISOString(), file: one.file, subagent: one.subagent === true }));
+}
+
+/**
+ * Whether a conversation's own record holds `text` as a turn of the user's:
+ * what the harness itself wrote down as said to it, not a screen that was up.
+ *
+ * Only the user's turns count. Claude Code writes them as `user` lines, and its
+ * own meta lines and tool results in that same shape are not the user's. Codex
+ * writes each as a `user` message item; its `user_message` event is missing
+ * from many rollouts, and the item is in every one (tech notes, section 3).
+ * Its AGENTS.md goes in as a `user` item too, and cannot be the text asked about.
+ */
+export function heldAsUserTurn(harness, file, text) {
+  let lines;
+  try {
+    lines = readFileSync(file, 'utf8').split('\n');
+  } catch {
+    return false;
+  }
+  const wanted = text.trim();
+  return lines.some((line) => userTexts(harness, line).some((said) => said.trim() === wanted));
+}
+
+/** The texts of one record line, when it is a turn of the user's. */
+function userTexts(harness, line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return [];
+  }
+  if (harness === 'claude') {
+    if (parsed?.type !== 'user' || parsed.isMeta === true) return [];
+    const content = parsed.message?.content;
+    if (typeof content === 'string') return [content];
+    return Array.isArray(content) ? content.filter((block) => block?.type === 'text').map((block) => String(block.text)) : [];
+  }
+  const item = parsed?.type === 'response_item' ? parsed.payload : undefined;
+  if (item?.type !== 'message' || item.role !== 'user' || !Array.isArray(item.content)) return [];
+  return item.content.filter((block) => block?.type === 'input_text').map((block) => String(block.text));
 }
 
 function claudeConversations(home) {
@@ -87,7 +132,7 @@ function codexConversations(home, from) {
     .flatMap((file) => {
       const meta = sessionMeta(file);
       return meta?.cwd === home && typeof meta.id === 'string'
-        ? [{ id: meta.id, at: Date.parse(meta.timestamp ?? '') || startedAt(file) || 0, file }]
+        ? [{ id: meta.id, at: Date.parse(meta.timestamp ?? '') || startedAt(file) || 0, file, subagent: isSubagent(meta) }]
         : [];
     });
 }
@@ -113,6 +158,15 @@ function sessionMeta(file) {
   }
 }
 
+/**
+ * Codex marks a conversation it ran as a subagent under `source`: its own
+ * auto-review is `{ subagent: { other: 'guardian' } }`, and one a session spawned
+ * is `{ subagent: { thread_spawn: … } }`. A session's own is a plain word, such as
+ * `cli` or `exec` (tech notes, section 3).
+ */
+const isSubagent = (meta) =>
+  meta.source !== null && typeof meta.source === 'object' && 'subagent' in meta.source;
+
 /** When a file was last written, for leaving out what is plainly too old. */
 function lastTouched(file) {
   try {

package/src/health.js

@@ -21,13 +21,14 @@
 import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
-import { bookFile, readBook, tabIdsIn } from './book.js';
+import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { bypassFlags, harnessOf, HARNESSES, sessionTrouble } from './launch.js';
-import { orcaDefaultArgs, projects, tabs } from './orca.js';
-import { agentsTrouble } from './rules.js';
+import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, shellWord } from './launch.js';
+import { frontOfTab, orcaDefaultArgs, projects, tabs } from './orca.js';
+import { agentsTrouble, rulesStamp } from './rules.js';
+import { settingsInUse } from './settings.js';
 import { skillsTrouble } from './skills.js';
 import { readSources, sourcesDir } from './sources.js';
 import { BOT_FATHER, botsNamed, promptPath } from './up.js';
@@ -37,14 +38,18 @@ import { BOT_FATHER, botsNamed, promptPath } from './up.js';
  * settings do to every session, what is lying about that no book owns, and then
  * each bot in name order. `bot` narrows the per-bot checks to one; what the
  * whole fleet lives under is reported whichever bot was named.
+ *
+ * Beside the list, `sessions`: each running session the book knows, with what
+ * it runs on against what its bot asks for now, good news included.
  */
 export function checkHealth(bots, { bot: onlyBot } = {}) {
   const names = botsNamed(bots, onlyBot);
   const setups = projects();
 
   const found = [...orcaSettingFindings(), ...leftInOrca(bots, setups), ...leftBeside(bots)];
-  for (const name of names) found.push(...aboutBot(bots, name, setups));
-  return found;
+  const sessions = [];
+  for (const name of names) found.push(...aboutBot(bots, name, setups, sessions));
+  return { found, sessions };
 }
 
 /** One finding, as the report and the `--json` answer carry it. */
@@ -165,8 +170,8 @@ function leftBeside(bots) {
   return found;
 }
 
-/** Everything wrong with one bot. */
-function aboutBot(bots, name, setups) {
+/** Everything wrong with one bot. Its running sessions are added to `sessions`. */
+function aboutBot(bots, name, setups, sessions) {
   const home = botDir(bots, name);
 
   let bot;
@@ -185,7 +190,7 @@ function aboutBot(bots, name, setups) {
     ...agentsTrouble(bots, home, bot).map(said('config')),
     ...hooksOf(bots, home, bot).map(said('config')),
     ...skillsTrouble(bots, home, bot).map(said('skill')),
-    ...inOrca(home, bot, setups),
+    ...inOrca(bots, home, bot, setups, sessions),
   ];
 }
 
@@ -206,12 +211,97 @@ const hooksOf = (bots, home, bot) => [...new Set(bot.sessions.map((session) => h
   .map((harness) => hookTrouble(home, harness, { bots, bot: bot.name }))
   .filter((trouble) => trouble !== undefined);
 
+/**
+ * Each session of this bot running in a tab Orca has, with what it runs on set
+ * beside what the bot asks for now, added to `sessions`; a finding for each
+ * one that runs on something else (#271, #272); and a finding for each one
+ * whose tab is open with its harness gone from it (#300).
+ *
+ * Two questions, each answered from where the answer is written. The settings
+ * from the harness's own record of the conversation the session is in now,
+ * which is what the harness really used. The rules from the stamp the kit noted
+ * in the book when the session last read them, against `AGENTS.md` now: nothing
+ * the harness writes says which instructions it read.
+ *
+ * Only a mismatch and older rules are findings. What cannot be read is said as
+ * unknown in `sessions`, and never taken for agreement.
+ */
+function runningOn(bots, home, bot, book, handles, sessions) {
+  const real = realpathOf(home) ?? home;
+  const records = new Map();
+  const recordOf = (harness, id) => {
+    if (!HARNESSES.includes(harness) || id === null) return undefined;
+    if (!records.has(harness)) records.set(harness, new Map(transcriptsIn(harness, real).map((one) => [one.id, one.file])));
+    return records.get(harness).get(id);
+  };
+
+  const stamp = rulesStamp(home);
+  const found = [];
+  for (const session of bot.sessions) {
+    const entry = book.sessions[session.name];
+    // Running is a tab Orca still has, with the session's harness in front of
+    // it. A session whose tab is gone is not running whatever its record says,
+    // and the missing tab is said already.
+    if (bot.paused === true || session.paused === true || entry === null || typeof entry !== 'object') continue;
+    const handle = handles.get(entry.tab);
+    if (handle === undefined) continue;
+
+    // A harness can quit to the tab's shell and leave the tab open (#232), so
+    // the tab alone is not the answer: who holds its terminal is, asked the way
+    // the kit asks before it types into a tab. The shell in front is a session
+    // that is not running, and a finding: `up` finds the tab open and types
+    // nothing into it, so only a restart brings it back (#300). Anything else
+    // that is not its own harness, or a front that cannot be read, leaves it
+    // unsaid, and nothing unsaid is a finding.
+    const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
+    const front = frontOfTab(handle);
+    if (front.front === 'shell') {
+      // Restart refuses a live tab whose conversation the book cannot name, and
+      // there may be none to name: the harness can quit before it has one. Its
+      // harness is gone, so closing the tab ends nothing, and `up` then starts
+      // the session again as it does any closed tab with no conversation.
+      const up = `${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
+      const back = typeof entry.session === 'string'
+        ? `${restart} does`
+        : `nor does obk restart, which refuses to close a tab whose conversation the book does not name, and the book names none for it. Its harness has already quit, so close the tab in Orca yourself; then ${up} starts it again, with a new conversation and its duty. Any conversation it left in this bot's folder is noted in the book as unclaimed, for health to list`;
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} is not running: its tab ${entry.tab} is open with only the tab's shell in front, so its harness quit or crashed. obk up finds the tab open and types nothing into it, so it does not bring the session back; ${back}.`, bot.name));
+      continue;
+    }
+    const harness = harnessOf(session, bot.harness);
+    const running = front.front === 'program' && front.command === harness ? 'yes' : 'unknown';
+    const conversation = typeof entry.session === 'string' ? entry.session : null;
+    const file = recordOf(harness, conversation);
+    const settings = settingsInUse(harness, session, file, typeof entry.launched === 'string' ? entry.launched : undefined);
+    const rules = { state: typeof entry.rules !== 'string' ? 'unknown' : entry.rules === stamp ? 'current' : 'older' };
+    sessions.push({ bot: bot.name, session: session.name, harness, running, conversation, settings, rules });
+    if (running !== 'yes') continue;
+
+    const off = Object.entries(settings).filter(([, one]) => one.state === 'mismatch');
+    if (off.length > 0) {
+      const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+      found.push(finding('session', file, `${bot.name}'s session ${session.name} does not run on what ${path.join(home, 'bot.yaml')} asks for. ${parts}. That is what the harness's own record of its conversation ${conversation} says. A session takes these when it starts, so if bot.yaml changed after it started, ${restart} starts it on them; if not, something else set them, such as a default of the harness's own or a change made inside the session.`, bot.name));
+    }
+
+    if (rules.state === 'older') {
+      const agents = path.join(home, 'AGENTS.md');
+      // A clear on Claude Code reads the instructions again, as a start does
+      // (tech notes, section 2); whether a new conversation on Codex does is
+      // not established, so a start is all that is offered there.
+      const how = harness === 'claude'
+        ? `A Claude Code session reads it again at a /clear in its tab, or when it starts: ${restart}`
+        : `A Codex session reads it when it starts: ${restart}`;
+      found.push(finding('session', agents, `${bot.name}'s session ${session.name} is running on older rules: ${agents} has changed since the kit noted which version this session read. ${how}`, bot.name));
+    }
+  }
+  return found;
+}
+
 /**
  * What Orca has of this bot against what the book says it should have: a
  * session whose tab is gone, a conversation nobody claims, and a tab in the
  * bot's project that the book does not name.
  */
-function inOrca(home, bot, setups) {
+function inOrca(bots, home, bot, setups, sessions) {
   // The book is read where it is read, and a book nothing can parse is a
   // finding like any other: it says which tab each session is in and which
   // conversation it is running, so without it nothing else here can be asked —
@@ -236,19 +326,26 @@ function inOrca(home, bot, setups) {
   // what paused means rather than something lost.
   const closed = new Set(bot.sessions.filter((session) => bot.paused === true || session.paused === true).map((session) => session.name));
 
+  // What the harness has on record in this bot's folder, read once: it is a walk
+  // through every conversation on the machine.
+  const onRecord = recordIn(real ?? home, bot);
+  // A conversation the harness marks as a subagent's was never a session's, so a
+  // note that holds one is not a loose end for it (#287). The note stays as it is.
+  const helpers = new Set(onRecord.filter((one) => one.subagent).map((one) => one.id));
+
   const found = [];
   for (const [name, entry] of Object.entries(book.sessions)) {
     if (typeof entry?.tab === 'string' && !there.has(entry.tab) && !closed.has(name)) {
       found.push(finding('session', entry.tab, `${bot.name}'s session ${name} is in the book with tab ${entry.tab}, and Orca has no tab of that id: the tab was closed, or the machine was restarted. The conversation is in the book, and obk up opens a tab and brings it back.`, bot.name));
     }
 
-    const unclaimed = Array.isArray(entry?.unclaimed) ? entry.unclaimed : [];
+    const unclaimed = (Array.isArray(entry?.unclaimed) ? entry.unclaimed : []).filter((id) => !helpers.has(id));
     if (unclaimed.length > 0) {
       found.push(finding('leftover', bookFile(home), `The book notes conversations under ${bot.name}'s session ${name} that no session of this bot claims: ${unclaimed.join(', ')}. They ran in this bot's folder, and the kit will not say whose they were. To give one back, write it into ${bookFile(home)} under ${name} as  session: <id>  and run obk up again.`, bot.name));
     }
   }
 
-  found.push(...offTheBook(real ?? home, bot, book));
+  found.push(...offTheBook(real ?? home, bot, book, onRecord));
 
   // A tab outside the book is somebody else's, and in Bot Father's project it
   // is the ops tab: the one tab the kit deliberately keeps no record of, so it
@@ -260,6 +357,7 @@ function inOrca(home, bot, setups) {
     }
   }
 
+  found.push(...runningOn(bots, home, bot, book, new Map(live.map((tab) => [tab.tabId, tab.handle])), sessions));
   return found;
 }
 
@@ -269,27 +367,30 @@ function inOrca(home, bot, setups) {
  * fails it fails quietly (ADR 0020), so this is where a stale book shows: the
  * harness's own record set beside it (ADR 0012).
  */
-function offTheBook(home, bot, book) {
-  const named = new Set();
+function offTheBook(home, bot, book, onRecord) {
+  // A retired session's conversations are in the book too, under `retired`.
+  const named = sessionIdsIn(book);
   for (const entry of Object.values(book.sessions)) {
-    if (typeof entry?.session === 'string') named.add(entry.session);
-    for (const was of Array.isArray(entry?.history) ? entry.history : []) named.add(was?.session);
     for (const id of Array.isArray(entry?.unclaimed) ? entry.unclaimed : []) named.add(id);
   }
 
-  // Every harness any of its sessions runs on, as `obk usage` reads them.
-  const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
-  if (harnesses.size === 0) harnesses.add(bot.harness);
-  const stray = [...harnesses]
-    .filter((harness) => HARNESSES.includes(harness))
-    .flatMap((harness) => transcriptsIn(harness, home))
-    .filter((one) => !named.has(one.id));
+  // A subagent's conversation is no session's, so the book has no reason to name it.
+  const stray = onRecord.filter((one) => !one.subagent && !named.has(one.id));
   if (stray.length === 0) return [];
 
   const listed = stray.map((one) => `${one.id} (begun ${one.at})`).join(', ');
   return [finding('session', bookFile(home), `The harness has conversations on record in ${bot.name}'s folder that the book does not name: ${listed}. The kit's hook may have missed them: a clear it did not record, or a Codex hooks file trusted late. To give one to a session, write it into ${bookFile(home)} under that session as  session: <id>  and run obk up again.`, bot.name)];
 }
 
+/** Every conversation on record in the bot's folder, from every harness any of its sessions runs on, as `obk usage` reads them. */
+function recordIn(home, bot) {
+  const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
+  if (harnesses.size === 0) harnesses.add(bot.harness);
+  return [...harnesses]
+    .filter((harness) => HARNESSES.includes(harness))
+    .flatMap((harness) => transcriptsIn(harness, home));
+}
+
 /** What a directory holds, and nothing at all when there is no directory. */
 function namesIn(dir) {
   try {

package/src/orca.js

@@ -312,6 +312,21 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   return { handle: live.handle, agent: seen.agent };
 }
 
+/**
+ * Who holds the terminal of the tab `handle`, as `frontOf` answers, without
+ * waiting on the tab: for a caller that asks about every tab and has nothing
+ * to type. Orca refusing is an answer that cannot be read, not an error.
+ */
+export function frontOfTab(handle) {
+  let shown;
+  try {
+    shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
+  } catch (error) {
+    return { unreadable: `Orca would not show the tab: ${error.message}` };
+  }
+  return frontOf(shown?.ptyId);
+}
+
 /** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
 const psCli = () => process.env.OBK_PS || '/bin/ps';
 

package/src/record.js

@@ -17,6 +17,7 @@ import { forgetClaimed, readBook, rememberSession, sessionIdsIn, updateBook, wit
 import { botDir, readBot } from './bot.js';
 import { conversationsIn } from './conversations.js';
 import { harnessOf, SHELL_ENV, startPrompt, workDirOf } from './launch.js';
+import { rulesStamp } from './rules.js';
 
 /** Where Orca says which tab a program is running in (tech notes, section 1). */
 export const TAB_ENV = 'ORCA_TAB_ID';
@@ -79,6 +80,11 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
   // this bot's folder, which every session of the bot shares — so it can say
   // that a conversation nobody claims exists, and never whose it is.
   const unclaimed = unclaimedFor(readBook(home), home, bot, tabId, id);
+  // A clear on Claude Code reads the bot's instructions again, as a start does
+  // (tech notes, section 2), so the book notes which ones it read. Codex has no
+  // word for its clear, and whether its new conversation reads them again is
+  // not established, so nothing is noted for it.
+  const rules = said.source === CLEARED ? rulesStamp(home) : undefined;
 
   let cleared = false;
   let told;
@@ -100,7 +106,8 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
     const uncertain = was.session === undefined && unclaimed.length > 0;
     told = session;
 
-    book.sessions[session] = withUnclaimed(rememberSession(was, id, said.source), unclaimed);
+    const now = rememberSession(was, id, said.source);
+    book.sessions[session] = withUnclaimed(rules === undefined ? now : { ...now, rules }, unclaimed);
     forgetClaimed(book);
     if (uncertain) cleared = true;
     return book;

package/src/rules.js

@@ -406,3 +406,18 @@ function sameFile(one, other) {
     return false;
   }
 }
+
+/**
+ * A stamp of a bot's `AGENTS.md` as it is now, or undefined when there is none
+ * to read. It is what a session read when it started, noted in the book at that
+ * moment, so that health can tell a session running on older rules from one on
+ * the current ones. The whole file, not only the build's block: what the user
+ * wrote below the end marker is part of what the session reads.
+ */
+export function rulesStamp(home) {
+  try {
+    return checksum(readFileSync(path.join(home, AGENTS), 'utf8'));
+  } catch {
+    return undefined;
+  }
+}

package/src/settings.js

@@ -0,0 +1,158 @@
+// What a running session really runs with, set beside what its bot.yaml asks for.
+//
+// A session can run on settings other than the ones bot.yaml asks for: it
+// started before a change, a default of the user's own leaked in, or a flag was
+// dropped. Each harness writes down what it used (tech notes, sections 2 and 3),
+// so the two can be put side by side. Read only: these are the harness's files.
+//
+// Four answers, and only one of them is good news. A record that cannot be read,
+// or that does not carry the setting, is not agreement: it is `unknown`. A
+// setting the session never asked for is not a disagreement either, whatever the
+// harness chose: it is `not-asked-for`.
+
+import { DEFAULT_APPROVAL } from './launch.js';
+import { lines } from './usage.js';
+
+export const SETTINGS = ['model', 'effort', 'context', 'approval'];
+
+/**
+ * Each setting of `session` as `{ state, configured?, observed? }`, judged
+ * against `file`, the harness's record of the conversation the session is in
+ * now, from `since`, when the kit last started it. No file is no record, and
+ * every setting asked for is then unknown.
+ */
+export function settingsInUse(harness, session, file, since) {
+  const used = file === undefined ? {} : (harness === 'claude' ? fromClaude : fromCodex)(sinceStart(lines(file), since));
+  return Object.fromEntries(SETTINGS.map((name) => [name, judged(harness, name, asked(session, name), used[name])]));
+}
+
+/**
+ * What the record says since the kit last started the session. A start resumes
+ * the conversation it had, so the file still holds what the process before it
+ * wrote, and that says what that process ran with, not this one. Everything
+ * from the first line written at or after the start counts, a line with no time
+ * of its own included. With no start to go by, no line can be shown to be this
+ * process's, so none counts.
+ */
+function sinceStart(entries, since) {
+  const from = Date.parse(since ?? '');
+  if (Number.isNaN(from)) return [];
+  const first = entries.findIndex((entry) => Date.parse(entry.timestamp ?? '') >= from);
+  return first === -1 ? [] : entries.slice(first);
+}
+
+/** What the session asks for, as bot.yaml has it, or undefined when it asks for nothing. */
+function asked(session, name) {
+  const value = session[name];
+  const set = value !== undefined && value !== null && String(value).trim() !== '';
+  // The kit puts an approval level on every launch line, so a session always
+  // asks for one: the default, when it names none (ADR 0015).
+  if (name === 'approval') return set ? String(value).trim() : DEFAULT_APPROVAL;
+  return set ? String(value).trim() : undefined;
+}
+
+function judged(harness, name, configured, observed) {
+  const shown = observed === undefined ? {} : { observed: said(name, observed) };
+  if (configured === undefined) return { state: 'not-asked-for', ...shown };
+  const verdict = same(harness, name, configured, observed);
+  if (verdict === undefined) return { state: 'unknown', configured, ...shown };
+  return { state: verdict ? 'match' : 'mismatch', configured, ...shown };
+}
+
+/** Whether the record says what was asked for; undefined when it cannot say. */
+function same(harness, name, configured, observed) {
+  if (observed === undefined) return undefined;
+  if (name === 'model') return sameModel(configured, observed);
+  // Codex reports the window it was given at 95%, rounded down (tech notes,
+  // section 3): 200000 comes back as 190000.
+  if (name === 'context') return Number(observed) === Math.floor(Number(configured) * 0.95);
+  if (name === 'approval') return harness === 'claude' ? observed === CLAUDE_MODES[configured] : sameCodexApproval(configured, observed);
+  return observed === configured;
+}
+
+/**
+ * A model named without a dash is an alias, `sonnet`, and the harness writes the
+ * id it stands for, `claude-sonnet-5`: it matches an id it is one part of. A
+ * model with a dash is an id already, and has to be the one that ran. The
+ * context window Claude Code carries on the model name, `sonnet[1m]`, is not
+ * part of what it writes down.
+ */
+function sameModel(configured, observed) {
+  const model = configured.replace(/\[[^\]]*\]$/, '');
+  return model.includes('-') ? observed === model : observed.split('-').includes(model);
+}
+
+/** The permission mode Claude Code records for each level (tech notes, section 2). */
+const CLAUDE_MODES = { auto: 'auto', ask: 'default', 'dangerously-skip': 'bypassPermissions' };
+
+/**
+ * What Codex records for each level, and only the words that level decides: at
+ * `ask` the kit passes only the approval policy, so the sandbox is the user's
+ * own (ADR 0015), and at `dangerously-skip` nothing is reviewed (tech notes,
+ * section 3).
+ */
+const CODEX_WORDS = {
+  auto: { policy: 'on-request', reviewer: 'auto_review', sandbox: 'workspace-write' },
+  ask: { policy: 'on-request', reviewer: 'user' },
+  'dangerously-skip': { policy: 'never', sandbox: 'danger-full-access' },
+};
+
+function sameCodexApproval(configured, observed) {
+  const wanted = CODEX_WORDS[configured];
+  if (wanted === undefined) return false;
+  const pairs = Object.entries(wanted);
+  // A word the level decides and the record does not carry leaves it unsaid.
+  if (pairs.some(([key]) => observed[key] === undefined)) return undefined;
+  return pairs.every(([key, word]) => observed[key] === word);
+}
+
+/** A value the record carried, as the report shows it. */
+function said(name, observed) {
+  if (name !== 'approval' || typeof observed === 'string') return String(observed);
+  return [
+    `approval_policy ${observed.policy}`,
+    ...(observed.reviewer === undefined ? [] : [`approvals_reviewer ${observed.reviewer}`]),
+    ...(observed.sandbox === undefined ? [] : [`sandbox ${observed.sandbox}`]),
+  ].join(', ');
+}
+
+/**
+ * What a Claude Code transcript says it runs with, the latest of each: the
+ * model and effort on its replies, the permission mode wherever it is noted.
+ * Claude Code writes nothing that shows the context window.
+ */
+function fromClaude(entries) {
+  const used = {};
+  for (const entry of entries) {
+    if (entry.type === 'assistant' && entry.isSidechain !== true) {
+      const model = entry.message?.model;
+      if (typeof model === 'string' && model !== '<synthetic>') used.model = model;
+      if (typeof entry.effort === 'string') used.effort = entry.effort;
+    }
+    if (typeof entry.permissionMode === 'string') used.approval = entry.permissionMode;
+  }
+  return used;
+}
+
+/** What a Codex rollout says it runs with: its latest turn, and its latest count. */
+function fromCodex(entries) {
+  const used = {};
+  for (const entry of entries) {
+    const payload = entry.payload;
+    if (payload === null || typeof payload !== 'object') continue;
+    if (entry.type === 'turn_context') {
+      if (typeof payload.model === 'string') used.model = payload.model;
+      if (typeof payload.effort === 'string') used.effort = payload.effort;
+      if (typeof payload.approval_policy === 'string') {
+        used.approval = {
+          policy: payload.approval_policy,
+          reviewer: typeof payload.approvals_reviewer === 'string' ? payload.approvals_reviewer : undefined,
+          sandbox: typeof payload.sandbox_policy?.type === 'string' ? payload.sandbox_policy.type : undefined,
+        };
+      }
+    }
+    const window = payload.info?.model_context_window;
+    if (entry.type === 'event_msg' && payload.type === 'token_count' && typeof window === 'number') used.context = window;
+  }
+  return used;
+}

package/src/up.js

@@ -6,14 +6,15 @@
 
 import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { setTimeout as pause } from 'node:timers/promises';
 
 import { forgetClaimed, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, readBot } from './bot.js';
-import { conversationsIn } from './conversations.js';
+import { conversationsIn, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isShortPrompt, launchCommand, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
 import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, tellWindow, typeIntoTab, useMailbox } from './orca.js';
-import { buildAgents } from './rules.js';
+import { buildAgents, rulesStamp } from './rules.js';
 import { linkSkills } from './skills.js';
 
 /** The one bot with a tab beside its sessions: the ops tab (PRD 6.2). */
@@ -300,12 +301,17 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // started a harness in it, and a conversation taken over from the harness's
   // own record are new.
   const launched = new Date().toISOString();
+  // Which instructions it is about to read: the AGENTS.md this run has just
+  // built, noted so that health can say when the file moves on and the session
+  // does not (#272).
+  const rules = rulesStamp(home);
   await updateBook(home, (current) => {
     // What the harness has in this folder that nobody claims goes on the record,
     // for a person or Bot Father to settle — added to whatever was already noted,
     // because this run's scan cannot see what an earlier one found. The kit never
     // settles it itself.
-    const entry = { ...current.sessions[session.name], tab: made.tabId, launched };
+    const entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
+    if (rules === undefined) delete entry.rules;
     current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
     forgetClaimed(current);
   });
@@ -334,24 +340,54 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   const tui = first.running ? lookFor(made.handle, SECOND_LOOK_MS) : first;
 
   // The start prompt went in with that line, as the harness's own prompt
-  // argument, so it is the harness that holds it until it is ready — through
-  // its folder-trust question and its update offer. What is still worth saying
-  // is whether the line took at all: a shell that swallowed it swallowed the
-  // duty with it, and nobody has been told anything.
-  const promptSent = prompt === undefined ? undefined : tui.running === true;
+  // argument, and a harness running in the tab is not yet a session told its
+  // duty: one held on a first-run screen, or one that refused the argument, has
+  // been told nothing. So it is received only when the session's own record
+  // holds it as a user turn, and otherwise not confirmed (#274).
+  const promptReceived = prompt === undefined
+    ? undefined
+    : await heldInRecord(home, session.name, harness, prompt, { launched, running: tui.running === true });
 
   return entry(made, {
     bot: bot.name,
     name: session.name,
     created: true,
     ...tui,
-    promptSent,
+    promptReceived,
     promptFile,
     resumed: resume !== undefined,
     unclaimed: which.unclaimed,
   });
 }
 
+/**
+ * How long a running harness's own record is given to show the start prompt.
+ * Seen live (Claude Code 2.1.282, a trusted folder): the hook's id and the
+ * user turn landed about as the second look ended, so one read there comes a
+ * moment too early. A harness held on a first-run screen costs the whole wait.
+ */
+const RECORD_MS = 5000;
+const RECORD_ASK_MS = 250;
+
+/**
+ * Whether the conversation the book names for this session holds `prompt` as a
+ * user turn in the harness's own record. The name comes from the session's own
+ * hook, so a harness that has not reported one — held on a first-run screen,
+ * say — has no record to be read, and the answer is that it is not confirmed.
+ * Another conversation in the same folder is never asked: it may be a sister
+ * session told the same words.
+ */
+async function heldInRecord(home, name, harness, prompt, { launched, running }) {
+  const until = Date.now() + (running ? RECORD_MS : 0);
+  for (;;) {
+    const id = readBook(home).sessions[name]?.session;
+    const record = typeof id === 'string' ? transcriptsIn(harness, home, launched).find((one) => one.id === id) : undefined;
+    if (record !== undefined && heldAsUserTurn(harness, record.file, prompt)) return true;
+    if (Date.now() >= until) return false;
+    await pause(RECORD_ASK_MS);
+  }
+}
+
 /**
  * One look at a tab the kit just typed a launch line into: whether a harness
  * is running there, and what it is waiting on if Orca says.
@@ -490,7 +526,7 @@ const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, cha
 export const promptPath = (bots, bot, session) =>
   path.join(`${bots}.prompts`, `${encodeURIComponent(bot)}.${encodeURIComponent(session)}.txt`);
 
-function entry(tab, { bot, name, created, running = false, blockedReason, promptSent, promptFile, resumed, unclaimed }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, unclaimed }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // Whether this run picked the session up where it was or started a new one.
   // Only for a tab this run opened: a tab that was already there was left alone.
@@ -502,7 +538,7 @@ function entry(tab, { bot, name, created, running = false, blockedReason, prompt
   // claims: the caller is told, because the kit will not pick one.
   if (unclaimed !== undefined && unclaimed.length > 0) made.unclaimed = unclaimed;
   // Only for a session this run started that had something to be told.
-  if (promptSent !== undefined) made.promptSent = promptSent;
+  if (promptReceived !== undefined) made.promptReceived = promptReceived;
   // And the file it was told it out of, when it was too long for the line.
   if (promptFile !== undefined) made.promptFile = promptFile;
   return made;

package/src/usage.js

@@ -41,6 +41,21 @@ import { harnessOf } from './launch.js';
 /** The kinds a call's tokens are reported in, the same on either harness. */
 const KINDS = ['input', 'output', 'cache_read', 'cache_write', 'reasoning'];
 
+/**
+ * What could not be counted, by why. A figure that quietly leaves something out
+ * reads as complete, so what is left out is said, and the totals cover only what
+ * was counted: nothing missing is guessed at, nor taken as zero, nor placed in a
+ * window it has no time to be placed in.
+ */
+const GAPS = ['unreadable_transcripts', 'broken_lines', 'records_without_numbers', 'records_without_time'];
+
+const noGaps = () => Object.fromEntries(GAPS.map((gap) => [gap, 0]));
+
+const addGaps = (into, more) => {
+  for (const gap of GAPS) into[gap] += more[gap];
+  return into;
+};
+
 /**
  * What each bot's sessions have used. `since` counts the calls made at or after
  * that moment rather than the conversations begun after it: a conversation that
@@ -99,20 +114,28 @@ function forBot(bots, name, onlySession, window) {
 
   const sessions = bot.sessions
     .filter((session) => onlySession === undefined || session.name === onlySession)
-    .map((session) => ({
-      name: session.name,
-      conversations: idsIn(book.sessions[session.name] ?? {})
-        .filter((id) => onRecord.has(id))
-        .map((id) => counted(onRecord.get(id), window))
-        .filter((one) => one !== undefined),
-    }));
-
-  const unclaimed = [...onRecord.values()]
-    .filter((one) => !claimed.has(one.id))
-    .map((one) => counted(one, window))
-    .filter((one) => one !== undefined);
-
-  return { bot: name, home, sessions, unclaimed };
+    .map((session) => {
+      const { conversations, gaps } = all(
+        idsIn(book.sessions[session.name] ?? {}).filter((id) => onRecord.has(id)).map((id) => onRecord.get(id)),
+        window,
+      );
+      return { name: session.name, conversations, not_counted: gaps };
+    });
+
+  const unclaimed = all([...onRecord.values()].filter((one) => !claimed.has(one.id)), window);
+
+  return { bot: name, home, sessions, unclaimed: unclaimed.conversations, unclaimed_not_counted: unclaimed.gaps };
+}
+
+/** Some conversations counted, and what all of them together could not count. */
+function all(transcripts, window) {
+  const gaps = noGaps();
+  const conversations = transcripts.flatMap((one) => {
+    const { row, gaps: its } = counted(one, window);
+    addGaps(gaps, its);
+    return row === undefined ? [] : [row];
+  });
+  return { conversations, gaps };
 }
 
 /** The conversations a book entry names: the one it is in, then the ones before. */
@@ -122,9 +145,10 @@ const idsIn = (entry) => [
 ];
 
 /**
- * One conversation, counted. A conversation that spent nothing in the window is
- * left out rather than reported as a row of zeroes: it is not part of what has
- * happened since, and a page of zeroes is harder to read than a shorter page.
+ * One conversation, counted, and what in it could not be. A conversation that
+ * spent nothing in the window has no row rather than a row of zeroes: it is not
+ * part of what has happened since, and a page of zeroes is harder to read than a
+ * shorter page. What it could not count is still said.
  */
 function counted(one, window) {
   const read = one.harness === 'claude' ? fromClaude : fromCodex;
@@ -139,12 +163,16 @@ function counted(one, window) {
     byModel: new Map(),
     first: undefined,
     last: undefined,
+    gaps: noGaps(),
   };
 
-  read(lines(one.file), window, tally);
-  if (tally.calls === 0 && KINDS.every((kind) => tally.tokens[kind] === 0)) return undefined;
+  const { entries, unreadable, broken } = transcript(one.file);
+  tally.gaps.unreadable_transcripts = unreadable;
+  tally.gaps.broken_lines = broken;
+  read(entries, window, tally);
+  if (tally.calls === 0 && KINDS.every((kind) => tally.tokens[kind] === 0)) return { gaps: tally.gaps };
 
-  return {
+  return { gaps: tally.gaps, row: {
     id: one.id,
     calls: tally.calls,
     tokens: tally.tokens,
@@ -154,7 +182,7 @@ function counted(one, window) {
     compactions: tally.compactions,
     first: new Date(tally.first).toISOString(),
     last: new Date(tally.last).toISOString(),
-  };
+  } };
 }
 
 /**
@@ -175,6 +203,13 @@ function counted(one, window) {
  * start. A transcript only grows, so one run's end is the next run's start and
  * the runs add up to the whole, with a call still being written at a boundary
  * charged once, part to each side (#169).
+ *
+ * A record with no time, or with a figure missing, is left out whole and said to
+ * be; the call it belongs to is counted from its other records, if it has any.
+ * But when the record last written before the window's start is one of those,
+ * what the call had grown to by then is not known, and what it grew by inside
+ * the window cannot be told apart from what it grew by before. So the call is
+ * not counted in that window, and is said to be.
  */
 function fromClaude(entries, window, tally) {
   const byCall = new Map();
@@ -182,25 +217,34 @@ function fromClaude(entries, window, tally) {
   for (const entry of entries) {
     const when = Date.parse(entry.timestamp ?? '');
     if (entry.type === 'system' && entry.subtype === 'compact_boundary') {
-      if (inside(when, window)) tally.compactions += 1;
+      if (Number.isNaN(when)) tally.gaps.records_without_time += 1;
+      else if (inside(when, window)) tally.compactions += 1;
       continue;
     }
     if (entry.type !== 'assistant') continue;
 
     const usage = entry.message?.usage;
     if (usage === undefined || usage === null) continue;
+    if (Number.isNaN(when)) {
+      tally.gaps.records_without_time += 1;
+      continue;
+    }
+    const broken = !complete(usage, CLAUDE_FIELDS);
+    if (broken && inside(when, window)) tally.gaps.records_without_numbers += 1;
     const call = `${entry.requestId}\u0000${entry.message?.id}`;
     if (!byCall.has(call)) byCall.set(call, []);
-    byCall.get(call).push({ entry, when });
+    byCall.get(call).push({ entry, when, broken });
   }
 
   for (const records of byCall.values()) {
     const made = records[0].when;
-    // A record with no time of its own says nothing about being outside, as in
-    // `inside`: it counts as written before the end and not before the start.
-    const atEnd = records.findLast(({ when }) => Number.isNaN(when) || when < window.to);
+    const atEnd = records.findLast(({ when, broken }) => !broken && when < window.to);
     if (atEnd === undefined) continue;
-    const atStart = records.findLast(({ when }) => !Number.isNaN(when) && when < window.from);
+    const atStart = records.findLast(({ when }) => when < window.from);
+    if (atStart?.broken) {
+      if (inside(atEnd.when, window)) tally.gaps.records_without_numbers += 1;
+      continue;
+    }
 
     const now = figures(atEnd.entry);
     const was = atStart === undefined ? undefined : figures(atStart.entry);
@@ -212,6 +256,9 @@ function fromClaude(entries, window, tally) {
   }
 }
 
+/** The figures Claude Code writes on every call, all of which a record needs to be counted. */
+const CLAUDE_FIELDS = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'];
+
 /** What one Claude Code record says its call used so far. */
 function figures(entry) {
   const usage = entry.message.usage;
@@ -252,11 +299,23 @@ const CODEX_FIELDS = [
  *
  * The running total is followed through events outside the window as well, since
  * what a call added can only be measured against the event before it.
+ *
+ * An event whose running total has a figure missing is left out and said to be,
+ * and after it the running total is not known, so neither is what the next
+ * complete event added. Measured against the event before the broken one, it
+ * would take in what the broken one used, at its own time and perhaps in
+ * another window; taken by its own per-call figure, it may be the broken one
+ * written down again. Telling those apart is guessing, so it is not counted
+ * either, and is said to be; the running total follows on from it. A call whose
+ * figure is needed and has something missing is not counted, and is said to
+ * be; nothing missing is taken as zero.
  */
 function fromCodex(entries, window, tally) {
   let model;
   let effort;
   let running;
+  // Whether a running total with something missing came since the last complete one.
+  let broken = false;
 
   for (const entry of entries) {
     const when = Date.parse(entry.timestamp ?? '');
@@ -269,48 +328,73 @@ function fromCodex(entries, window, tally) {
       continue;
     }
     if (entry.type === 'compacted') {
-      if (inside(when, window)) tally.compactions += 1;
+      if (Number.isNaN(when)) tally.gaps.records_without_time += 1;
+      else if (inside(when, window)) tally.compactions += 1;
       continue;
     }
     if (entry.type !== 'event_msg' || entry.payload?.type !== 'token_count') continue;
 
+    // No `info` is a note about rate limits, not a record of usage.
     const info = entry.payload?.info;
     if (info === undefined || info === null) continue;
 
-    const used = spent(running, info);
-    if (info.total_token_usage !== undefined && info.total_token_usage !== null) {
-      running = info.total_token_usage;
+    const total = info.total_token_usage ?? undefined;
+    let used;
+    if (total === undefined) {
+      // Nothing to measure against: the per-call figure is all there is. After a
+      // broken running total it may be the broken one written again, so it is
+      // not counted either until a complete running total says where things are.
+      used = broken ? null : perCall(info);
+    } else if (!complete(total, CODEX_READ)) {
+      used = null;
+      broken = true;
+    } else {
+      used = broken ? null : spent(running, total, info);
+      running = total;
+      broken = false;
     }
+
     // A repeat is not a call, whether or not it is inside the window.
     if (used === undefined) continue;
+    if (Number.isNaN(when)) {
+      tally.gaps.records_without_time += 1;
+      continue;
+    }
     if (!inside(when, window)) continue;
+    if (used === null) {
+      tally.gaps.records_without_numbers += 1;
+      continue;
+    }
 
     count(tally, used, model, effort, when);
   }
 }
 
+/** The fields Codex itself writes; it has no cache writes to report. */
+const CODEX_READ = CODEX_FIELDS.filter((field) => field !== 'cache_write_input_tokens').concat('total_tokens');
+
 /**
- * What one Codex event says its call used, measured against the event before it.
- * `undefined` where the event is the one before written down again.
+ * What one Codex event says its call used, measured against the running total
+ * before it: `undefined` where the event is the one before written down again,
+ * and `null` where what it used cannot be known.
  */
-function spent(running, info) {
-  const total = info.total_token_usage;
-  if (total === undefined || total === null) {
-    // Nothing to measure against: the per-call figure is all there is.
-    return info.last_token_usage === undefined ? undefined : kindsOf(info.last_token_usage);
-  }
+function spent(running, total, info) {
   if (running === undefined) return kindsOf(total);
 
-  const moved = number(total.total_tokens) - number(running.total_tokens);
+  const moved = total.total_tokens - running.total_tokens;
   if (moved === 0) return undefined;
   // A fall is a new window, and the running total is counting again from there.
-  if (moved < 0) return kindsOf(info.last_token_usage ?? total);
+  if (moved < 0) return perCall(info);
 
   return kindsOf(Object.fromEntries(
     CODEX_FIELDS.map((field) => [field, number(total[field]) - number(running[field])]),
   ));
 }
 
+/** A Codex event's own per-call figure, or `null` when something in it is missing. */
+const perCall = (info) =>
+  complete(info.last_token_usage, CODEX_READ) ? kindsOf(info.last_token_usage) : null;
+
 /**
  * One Codex figure in the kinds this command reports. The cached tokens sit
  * inside `input_tokens` here and outside it on Claude Code, so they come out of
@@ -351,24 +435,32 @@ function count(tally, used, model, effort, when, calls = 1) {
 }
 
 /** The lines of a transcript that are readable JSON; the rest say nothing. */
-function lines(file) {
+export const lines = (file) => transcript(file).entries;
+
+/**
+ * The lines of a transcript that are JSON records, and how many were not. A
+ * transcript that cannot be read is said to be, rather than a run that stops.
+ */
+function transcript(file) {
   let text;
   try {
     text = readFileSync(file, 'utf8');
   } catch {
-    // A transcript that cannot be read is a conversation the kit knows nothing
-    // about, which is the honest answer rather than a run that stops.
-    return [];
+    return { entries: [], unreadable: 1, broken: 0 };
   }
-  return text.split('\n').flatMap((line) => {
+  let broken = 0;
+  const entries = text.split('\n').flatMap((line) => {
     if (line.trim() === '') return [];
     try {
       const entry = JSON.parse(line);
-      return entry !== null && typeof entry === 'object' ? [entry] : [];
+      if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) return [entry];
     } catch {
-      return [];
+      // Counted below with any other line that is not a record.
     }
+    broken += 1;
+    return [];
   });
+  return { entries, unreadable: 0, broken };
 }
 
 /** A bot home as the file system knows it, or as it was given when it is not there. */
@@ -382,20 +474,23 @@ function realHome(home) {
 
 const number = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
 
+/** Whether a figure has every field it should, each a number. */
+const complete = (figure, fields) =>
+  figure !== undefined && figure !== null
+  && fields.every((field) => typeof figure[field] === 'number' && Number.isFinite(figure[field]));
+
 const add = (set, value) => {
   if (typeof value === 'string' && value !== '') set.add(value);
 };
 
 /**
  * Whether a moment is in the window: at or after its start, before its end. A
- * record with no time of its own is counted, as it always has been: nothing
- * says it is outside.
+ * record with no time of its own is in no window; it is left out and said to be.
  */
-const inside = (when, { from, to }) => Number.isNaN(when) || (when >= from && when < to);
+const inside = (when, { from, to }) => when >= from && when < to;
 
 /** When the first and the last counted call of this conversation were. */
 function mark(tally, when) {
-  if (Number.isNaN(when)) return;
   if (tally.first === undefined || when < tally.first) tally.first = when;
   if (tally.last === undefined || when > tally.last) tally.last = when;
 }