@assuredloop/orca-bot-kit 0.4.0 → 0.5.1

package/README.md

@@ -350,6 +350,11 @@ conversation it was having, rather than starting a new one. Clear a session —
 keeps the old one, and gives the session its start prompt again, because that
 prompt is what tells one session's duty from another's.
 
+A session paused before its first turn can have an id in the book and no
+conversation behind it: the harness has nothing on record for that id. There is
+nothing to resume, so it starts again with its duty, and the book moves the id
+into its history as `no conversation`.
+
 One tab holds one session: the harness the kit started in it. Anything that
 session runs inside the tab — a `codex exec`, a helper, a subagent's own process
 — is not the session, and never becomes the conversation the kit brings back.
@@ -443,10 +448,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.1",
   "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.
 `;
@@ -266,3 +269,13 @@ export function rememberSession(entry = {}, id, ended) {
   const was = { session: entry.session, ended: ended ?? 'replaced', at: new Date().toISOString() };
   return { ...entry, session: id, history: [...(entry.history ?? []), was] };
 }
+
+/**
+ * The session entry once the id it held has turned out to have no conversation
+ * behind it: the id goes into the history with that reason, and the entry holds
+ * none until the harness names the new one.
+ */
+export function forgetSession(entry, ended) {
+  const { session, ...rest } = entry;
+  return { ...rest, history: [...(entry.history ?? []), { session, ended, at: new Date().toISOString() }] };
+}

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}`,
@@ -891,9 +892,14 @@ function refuseWhenOrcaIsDown() {
 
 /** The same facts as `--json`, as lines, for a person reading along. */
 /** The one line that says which conversation this tab was given, and from where. */
-const howLine = (tab) => (tab.resumed === true
-  ? '             it was told to resume the session the book holds, with its conversation.'
-  : '             it was told to start a new session: the book holds none for this one yet.');
+const howLines = (tab) => {
+  if (tab.resumed === true) return ['             it was told to resume the session the book holds, with its conversation.'];
+  if (tab.noConversation === undefined) return ['             it was told to start a new session: the book holds none for this one yet.'];
+  return [
+    `             it was told to start a new session: the book's conversation ${tab.noConversation} had nothing on record`,
+    "             behind it, so it went into the session's history.",
+  ];
+};
 
 /**
  * What the harness still has in this bot's folder that no session claims. The
@@ -956,12 +962,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 +980,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 +1150,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}`),
@@ -1169,7 +1210,7 @@ function harnessLines(tab, bots) {
   // What the line that was typed in asked for, and where the kit got it: the
   // session the book holds, one the harness itself still had on record, or a new
   // one — and if a new one, whether anything was known about an older one.
-  const how = [howLine(tab)];
+  const how = howLines(tab);
 
   if (!tab.harnessStarted) {
     return [
@@ -1177,6 +1218,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 +1240,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

@@ -10,7 +10,7 @@
 // directory, and every session starts at its bot home. Read only, never
 // written: these are the harness's files (tech notes, sections 2 and 3).
 
-import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 
@@ -32,12 +32,31 @@ 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 }));
+}
+
+/**
+ * Whether the harness has a record of the conversation `id` for this bot home,
+ * which is what its own resume looks for. A session paused before its first
+ * turn has an id the hook reported and nothing written behind it, and Claude
+ * Code answers a resume of it with "No conversation found" (#295).
+ *
+ * Asked of the file names alone, which both harnesses make from the id: nothing
+ * is opened, however many conversations the machine has.
+ */
+export function hasConversation(harness, home, id) {
+  if (harness === 'claude') return existsSync(path.join(claudeDir(home), `${id}.jsonl`));
+  return rollouts(codexDir()).some((file) => path.basename(file).endsWith(`-${id}.jsonl`));
 }
 
 /**
  * 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 +64,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 +146,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 +172,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/message.js

@@ -176,8 +176,8 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
  * Orca fences a Run to one reader, its coordinator. A session whose tab is live
  * is bound to that tab and read as it; one whose tab is down is read as its
  * Run's coordinator, and nothing is bound (issue #249). A read that
- * is not a peek acknowledges the batch it read: that is what makes the next
- * check bring the next one rather than the same again.
+ * is not a peek acknowledges every batch waiting, one after another, so one
+ * check hands over all of it (issue #299).
  */
 export function checkMail(bots, { bot: botName, session: sessionName, tab, peek = false }) {
   const who = sessionName === undefined && botName === undefined
@@ -212,9 +212,16 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
       trouble: `${who.bot}/${who.session} is not up, and its mailbox is bound to no tab, so there is nothing to read it as. Its mail waits until its tab is back: \`up\` brings it back, or \`unpause\` when it is paused.`,
     };
   }
-  const found = readMailbox(who.mailbox, { peek, handle });
-  const messages = (found.messages ?? []).map((message) => asMessage(bots, message));
-  if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId, handle);
+  // Orca hands mail over a batch at a time and replays the oldest until it is
+  // acknowledged; the acknowledgement answers with the next batch. So a read
+  // takes every batch in turn, or newer mail waits behind an older one (#299).
+  const messages = [];
+  let found = readMailbox(who.mailbox, { peek, handle });
+  for (;;) {
+    messages.push(...(found.messages ?? []).map((message) => asMessage(bots, message)));
+    if (peek || !found.deliveryId || (found.messages ?? []).length === 0) break;
+    found = ackMailbox(who.mailbox, found.deliveryId, handle);
+  }
 
   return { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
 }
@@ -335,7 +342,7 @@ function nudge(to, from, subject) {
   if (to.tab === undefined) return { nudged: false };
 
   try {
-    const found = tabToTypeInto(to.home, to.tab, LOOK_MS);
+    const found = lookAt(to);
     if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
     // A line that lands in a shell is run there, with the sender's subject in it.
     if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure };
@@ -356,6 +363,21 @@ function nudge(to, from, subject) {
   }
 }
 
+/**
+ * The look before the nudge. Orca now and then refuses a handle it has just
+ * listed as stale, and a fresh listing hands out one that works (tech notes,
+ * section 1), so that refusal earns one more listing and one more look. Only
+ * one: a second refusal is reported as it is (#294).
+ */
+function lookAt(to) {
+  try {
+    return tabToTypeInto(to.home, to.tab, LOOK_MS);
+  } catch (error) {
+    if (error.code !== 'terminal_handle_stale') throw error;
+    return tabToTypeInto(to.home, to.tab, LOOK_MS);
+  }
+}
+
 /** `<bot>/<session>`, or a bot on its own when it has only the one session. */
 function splitTarget(target) {
   const parts = target.split('/');