@assuredloop/orca-bot-kit 0.11.0 → 0.12.0

package/README.md

@@ -587,10 +587,11 @@ The tests come in two layers, and every test file belongs to one of them.
 
 `npm test` is `test/*.test.js`: unit tests and end-to-end runs of the CLI in a
 throwaway folder, with a fake `orca` on PATH. It needs nothing but Node, so
-[GitHub Actions](.github/workflows/ci.yml) runs it on every pull request and on
-every push to `main`: on Node 25.8.0, the current line, and again on 24.21.0,
-the floor `engines.node` promises users, with only the kit's own dependencies
-installed.
+[GitHub Actions](.github/workflows/ci.yml) runs it on every pull request, split
+into shards that run side by side, on Node 25.8.0, the current line. A release
+runs every shard on 25.8.0 and again on 24.21.0, the floor `engines.node`
+promises users, with only the kit's own dependencies installed, before anything
+is published.
 
 `npm run test:system` is `test/system/*.test.js`: the real `obk` against the
 real Orca and the real harnesses on your own machine. No CI runner can do that,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,6 +24,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
+    "test:shard": "node --test --test-shard=$SHARD test/*.test.js",
     "test:system": "node scripts/test-system.js",
     "mutate": "node scripts/mutate.js"
   },

package/rules/limits.md

@@ -18,5 +18,5 @@ When something you were told to use is missing (a model, a tool, a file), say
 so and ask. Quietly using a different one hides the change.
 
 Permission rules in a harness's settings or rules files are the kit's to write,
-after the user's yes to the exact rules: `obk bot change --allow <rule>` records
-and writes them. Never edit them into such a file yourself, Bot Father included.
+after the user's yes to the exact rules: `obk bot change --allow <rule>` or
+`--disallow <rule>`. Never edit one in or out yourself, Bot Father included.

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

@@ -226,9 +226,12 @@ such as an `Edit` rule or one exact command.
 Show the user the list word for word, with a line on what each lets the bot do,
 and only after their yes run `obk bot change --allow`, once per rule they said
 yes to. On a no, run nothing. `obk bot change --charter` names the rules the
-bot is allowed now; say which of them the new charter no longer grants, and
-that they stay allowed until the user takes them out, since the kit takes none
-out. Keep
+bot is allowed now; say which of them the new charter no longer grants, show
+each word for word, and ask whether to take it back. Only after their yes run
+`obk bot change --disallow`, once per rule, which takes it out of `bot.yaml`
+and the bot's settings or Codex rules; on a no, run nothing, and it stays
+allowed. A rule the user added to a settings file by hand is theirs to take
+out; the kit refuses it. Keep
 each rule narrow: a program and what it does. The kit refuses a rule that lets
 the bot run any command, a program with any arguments, or a shell or
 interpreter with any arguments; a user who wants one for a bot adds it to that

package/src/book.js

@@ -191,12 +191,17 @@ function lockOn(file, waitMs) {
  * is nobody's to sweep, and the user can see it and delete it.
  *
  * One folder per bots folder, so two bots folders each holding an api-bot cannot
- * take each other's turn.
+ * take each other's turn. Resolved first, as the mailbox's is: one writer reaches
+ * the bots folder through a link and another by its real path, and two paths
+ * would be two locks for one book (#375).
  */
-const lockFile = (home) => path.join(
-  `${path.dirname(path.dirname(home))}.locks`,
-  `${encodeURIComponent(path.basename(home))}.lock`,
-);
+const lockFile = (home) => {
+  const real = realpathSync(home);
+  return path.join(
+    `${path.dirname(path.dirname(real))}.locks`,
+    `${encodeURIComponent(path.basename(real))}.lock`,
+  );
+};
 
 /**
  * One session's turn at its mailbox (#321): held by `session mailbox` for its

package/src/bot.js

@@ -254,14 +254,14 @@ export function changeBot(bots, bot, { charter }) {
 }
 
 /**
- * The bot's `allow` list as it is, after refusing what `allowRules` would refuse:
- * an empty rule, or a list already there that is not a list of rules. Asked
- * before anything is written, so a refused `bot change` changes nothing, its
- * charter included.
+ * The bot's `allow` list as it is, after refusing what `allowRules` or
+ * `disallowRules` would refuse: an empty rule, or a list already there that is
+ * not a list of rules. Asked before anything is written, so a refused `bot
+ * change` changes nothing, its charter included.
  */
-export function allowedNow(bots, bot, rules) {
+export function allowedNow(bots, bot, rules, flag = '--allow') {
   if (rules.some((rule) => rule.trim() === '')) {
-    throw new Error('--allow is empty. Give it the exact permission rule the user said yes to, such as Bash(git add:*).');
+    throw new Error(`${flag} is empty. Give it the exact permission rule the user said yes to, such as Bash(git add:*).`);
   }
   const home = existingBot(bots, bot);
   const was = readBot(home, bot).allow ?? [];
@@ -289,6 +289,21 @@ export function allowRules(bots, bot, rules) {
   return { bot, home, allow, added };
 }
 
+/**
+ * Take the permission rules the user said yes to taking back, `rules`, out of
+ * the bot's `allow` (#360). Returns { bot, home, allow, disallowed }: the whole
+ * list now, and what this call took out. The caller has refused a rule `allow`
+ * does not hold, and takes them out of the harness's files first. With `write`
+ * false it only refuses what the edit would refuse, and writes nothing.
+ */
+export function disallowRules(bots, bot, rules, { write = true } = {}) {
+  const { home, was } = allowedNow(bots, bot, rules, '--disallow');
+  const disallowed = [...new Set(rules)];
+  const allow = was.filter((rule) => !disallowed.includes(rule));
+  editBot(bots, bot, `take back ${disallowed.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
+  return { bot, home, allow, disallowed };
+}
+
 /**
  * Change the settings of the session `name` of the bot `bot`. Returns
  * { bot, home, session } — the session as it now reads.
@@ -387,9 +402,10 @@ function editSession(bots, bot, index, session, what) {
 
 /**
  * Make one edit to a bot's `bot.yaml` through the YAML library, and write it
- * only if exactly the change `expected` describes is what came out.
+ * only if exactly the change `expected` describes is what came out, and
+ * `write` is not false.
  */
-function editBot(bots, bot, what, edit, expected) {
+function editBot(bots, bot, what, edit, expected, write = true) {
   const file = path.join(existingBot(bots, bot), BOT_YAML);
   const source = readFileSync(file, 'utf8');
   const doc = parseDocument(source);
@@ -398,7 +414,7 @@ function editBot(bots, bot, what, edit, expected) {
   if (!changesExactly(source, text, expected)) {
     throw new Error(`${file} cannot be changed to ${what} without changing something else in it, so nothing was written. Make the change by hand.`);
   }
-  if (text !== source) writeFileSync(file, text);
+  if (write && text !== source) writeFileSync(file, text);
 }
 
 /** A bot that is there, by its home, or the refusal a caller who named another is owed. */

package/src/cli.js

@@ -12,14 +12,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
-import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
+import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, disallowRules, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
 import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
 import { checkMail, lookUp, noMailboxYet, sendMessage } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
-import { allowCommand, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, writePermissions } from './permissions.js';
+import { allowCommand, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -56,13 +56,17 @@ Usage:
                             as ours: --prompt='- a bullet', and
                             --extra-arg=--search, once per extra argument.
   obk bot change --bots <path> --bot <bot> [--charter <text>]
-                 [--allow <rule> ...]
+                 [--allow <rule> ... | --disallow <rule> ...]
                             Give a bot a new charter and rebuild its AGENTS.md.
                             A running session reads it when it next starts.
                             --allow records a permission rule the user said
                             yes to, once per rule, and writes it into the bot's
                             Claude settings. A broad rule, such as Bash(gh:*),
                             is refused and nothing is written.
+                            --disallow takes back a rule the bot was allowed,
+                            once the user has said yes to that, from bot.yaml
+                            and the bot's settings. A rule the user added by
+                            hand is not the kit's, and is refused.
   obk session change --bots <path> --bot <bot> --session <session>
                   [--model <m>] [--effort <e>] [--context <c>]
                   [--approval ${APPROVALS.join('|')}]
@@ -184,14 +188,15 @@ Usage:
                             only while its tab is up in Orca.
   obk usage --bots <path> [--bot <bot>] [--session <name>] [--since <time>] [--until <time>]
                             Say what your sessions have used: the conversations
-                            each one had, their calls and tokens, the models and
-                            efforts they ran at, and how often they were
-                            compacted. --since counts the calls made from that
-                            moment on, and --until the calls made before that
-                            one: a daily run asks from the last run's end up to
-                            its own, and the next starts where it stopped, so no
-                            call is counted twice. It counts tokens and never
-                            money: what a token costs is looked up live by
+                            each one had, their calls and tokens (their
+                            subagents' included, and how many were theirs), the
+                            models and efforts they ran at, and how often they
+                            were compacted. --since counts the calls made from
+                            that moment on, and --until the calls made before
+                            that one: a daily run asks from the last run's end
+                            up to its own, and the next starts where it stopped,
+                            so no call is counted twice. It counts tokens and
+                            never money: what a token costs is looked up live by
                             whoever is asking.
   obk session record --bots <path> --bot <bot>
                             For the kit's own hook, not for typing: it reads
@@ -307,6 +312,7 @@ async function run(argv) {
       peek: { type: 'boolean' },
       charter: { type: 'string' },
       allow: { type: 'string', multiple: true },
+      disallow: { type: 'string', multiple: true },
       ...Object.fromEntries(SETTINGS.map(([flag]) => [flag, { type: 'string' }])),
       'extra-arg': { type: 'string', multiple: true },
       json: { type: 'boolean' },
@@ -604,8 +610,11 @@ const commands = {
     if (values.harness !== undefined) {
       throw new Error(`bot change does not change a bot's harness: its sessions' conversations belong to the harness they ran on. To move to ${values.harness}, give it a session on ${values.harness} with obk session add, or retire the bot with obk retire and create a new one.`);
     }
-    if (values.charter === undefined && values.allow === undefined) {
-      throw new Error('bot change needs --charter <text> or --allow <rule>: what to change.');
+    if (values.charter === undefined && values.allow === undefined && values.disallow === undefined) {
+      throw new Error('bot change needs --charter <text>, --allow <rule> or --disallow <rule>: what to change.');
+    }
+    if (values.allow !== undefined && values.disallow !== undefined) {
+      throw new Error('bot change takes --allow or --disallow, not both at once, so nothing was changed. Run one, then the other.');
     }
     // Refused before anything is written, so a bad rule, or a bad list already
     // there, leaves the charter as it was too.
@@ -614,6 +623,12 @@ const commands = {
       refuseBroad(home, values.allow);
       refuseNoCodexForm(readBot(home, values.bot), values.allow);
     }
+    let takeBackFrom;
+    if (values.disallow !== undefined) {
+      const { home } = allowedNow(bots, values.bot, values.disallow, '--disallow');
+      takeBackFrom = takeBack(bots, home, readBot(home, values.bot), values.disallow);
+      disallowRules(bots, values.bot, values.disallow, { write: false });
+    }
 
     const answer = { bots, bot: values.bot, home: botDir(bots, values.bot) };
     const lines = [];
@@ -637,7 +652,7 @@ const commands = {
       // An allow list that is not a list is named by rules build and health,
       // and a charter already written is not undone for it.
       const bot = readBot(changed.home, changed.bot);
-      if (values.allow === undefined && (runsOnClaude(bot) || runsOnCodex(bot))) {
+      if (values.allow === undefined && values.disallow === undefined && (runsOnClaude(bot) || runsOnCodex(bot))) {
         try {
           answer.beyondDefaults = beyondDefaults(bots, changed.home, bot);
           lines.push(...charterRulesLines(bots, bot, answer.beyondDefaults));
@@ -664,6 +679,23 @@ const commands = {
           : `${allowed.bot}'s allow list in ${path.join('bots', allowed.bot, 'bot.yaml')} holds the user's yes.`,
       );
     }
+    if (values.disallow !== undefined) {
+      // The harness's files first, bot.yaml last: a write that fails leaves the
+      // rules in `allow`, so the same command can take them back again (#360).
+      const permissions = takeBackFrom();
+      const taken = disallowRules(bots, values.bot, values.disallow);
+      Object.assign(answer, { allow: taken.allow, disallowed: taken.disallowed, permissions });
+      const codex = permissions.find((entry) => entry.unwritten !== undefined);
+      lines.push(
+        ...taken.disallowed.map((rule) => `${'took back'.padEnd(9)}  ${rule}`),
+        ...permissions.filter((entry) => entry.removed?.length > 0).map((entry) => `${'wrote'.padEnd(9)}  ${path.relative(bots, entry.file)}  ${entry.removed.length} permission rule${entry.removed.length === 1 ? '' : 's'} taken out`),
+        ...permissionsLines(permissions, bots),
+        ...(codex === undefined || codex.removed.length === 0 ? [] : [
+          `Codex reads ${codex.file} when a session starts: a Codex session of ${taken.bot} that is running now keeps ${codex.removed.length === 1 ? 'this rule' : 'these rules'} until its next start (obk restart).`,
+        ]),
+        `${taken.bot}'s allow list in ${path.join('bots', taken.bot, 'bot.yaml')} no longer holds ${taken.disallowed.length === 1 ? 'it' : 'them'}.`,
+      );
+    }
     return { answer, lines, code: trouble ? 1 : 0 };
   },
 
@@ -1053,7 +1085,7 @@ function usageLines(usage, bots) {
   for (const entry of usage) {
     lines.push(`${'bot'.padEnd(9)}  ${entry.bot}`);
     for (const session of entry.sessions) {
-      lines.push(`${'session'.padEnd(9)}  ${session.name}`);
+      lines.push(`${'session'.padEnd(9)}  ${session.name}${'retired' in session ? `  retired ${session.retired}` : ''}`);
       const notCounted = notCountedLine(session.not_counted);
       lines.push(...session.conversations.map(conversationLine));
       if (session.conversations.length === 0 && notCounted.length === 0) lines.push('             nothing on record');
@@ -1093,6 +1125,7 @@ function conversationLine(one) {
     .map(([kind, count]) => `${kind} ${count}`)
     .join('  ');
   return `             ${one.id}  ${one.calls} call${one.calls === 1 ? '' : 's'}`
+    + `${one.subagent_calls > 0 ? `  of which subagents: ${one.subagent_calls} call${one.subagent_calls === 1 ? '' : 's'}` : ''}`
     + `${ran === '' ? '' : `  ${ran}`}`
     + `${used === '' ? '' : `  ${used}`}`
     + `${one.compactions > 0 ? `  compacted ${one.compactions}` : ''}`;
@@ -1264,7 +1297,7 @@ function charterRulesLines(bots, bot, rules) {
   return [
     `${name} is allowed these permission rules beyond the kit's defaults, from before this change:`,
     ...rules.map((rule) => `             ${rule}`),
-    `They stay allowed, whatever the user answers, until the user takes one out of ${path.join('bots', name, 'bot.yaml')}${settings}${codex}; the kit takes none out. ${until}`,
+    `They stay allowed, whatever the user answers, until the user says yes to taking one back out of ${path.join('bots', name, 'bot.yaml')}${settings}${codex}. For one the new charter no longer grants, ask the user, and only after their yes run  ${shellWord(ownCli())} bot change --bots ${shellWord(bots)} --bot ${shellWord(name)} --disallow <rule>. ${until}`,
   ];
 }
 

package/src/conversations.js

@@ -59,6 +59,30 @@ export function hasConversation(harness, home, id) {
  */
 export const claudeTranscript = (home, id) => path.join(claudeDir(home), `${id}.jsonl`);
 
+/**
+ * The transcripts of the subagents a Claude Code conversation started, given the
+ * file the conversation is in. They sit beside it, in a folder named by its id,
+ * one `agent-<name>.jsonl` each, with a `.meta.json` beside each that is not a
+ * transcript (tech notes, section 2).
+ *
+ * No folder is a conversation that started no subagent. A folder that is there
+ * and cannot be listed is `unreadable`: what is in it cannot be counted, and
+ * taking it as empty would say nothing of that.
+ */
+export function claudeSubagentTranscripts(file) {
+  const dir = path.join(file.slice(0, -'.jsonl'.length), 'subagents');
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (error) {
+    return { files: [], unreadable: error.code === 'ENOENT' ? 0 : 1 };
+  }
+  return {
+    files: names.filter((name) => name.endsWith('.jsonl')).sort().map((name) => path.join(dir, name)),
+    unreadable: 0,
+  };
+}
+
 /**
  * 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,

package/src/permissions.js

@@ -12,13 +12,14 @@
 // editing the file by hand may get the format wrong; code does not.
 //
 // The kit owns only the entries `allow` holds. Any other entry in the file is
-// left where it is, and health names it.
+// left where it is, and health names it. A rule the user says yes to taking
+// back leaves `allow` and the files through `bot change --disallow` (#360).
 //
 // A bot on Codex gets the same yes in Codex's own form (#354, ADR 0028): each
 // `Bash(<words>:*)` becomes a `prefix_rule` of those words in
 // `.codex/rules/obk.rules`, a file the kit owns whole and rewrites from `allow`.
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { leadsOutside } from './bot.js';
@@ -304,6 +305,98 @@ function writeClaude(bots, home, bot) {
   return { ...answer, written: missing };
 }
 
+/**
+ * Take the rules the user said yes to taking back out of the files of the
+ * harnesses the bot runs on (#360): from its Claude settings every entry of
+ * that exact text and nothing else, and its Codex rules rewritten from what
+ * `allow` still holds. Only rules `allow` holds are taken back; one it does not
+ * hold is refused, since the kit did not write it (ADR 0029).
+ *
+ * Everything is checked before anything is written, a file the kit could not
+ * write included, bot.yaml too. What comes back writes the files: one entry per file,
+ * Claude's first, with `removed` the rules taken out of it. The caller takes
+ * them out of `allow` after, so a write that fails leaves them there to take
+ * back again.
+ */
+export function takeBack(bots, home, bot, rules) {
+  const allowed = allowOf(home, bot);
+  const foreign = rules.find((rule) => !allowed.includes(rule));
+  if (foreign !== undefined) throw new Error(notAllowed(home, bot, foreign));
+  const after = { ...bot, allow: allowed.filter((rule) => !rules.includes(rule)) };
+  const taken = [...new Set(rules)];
+  // bot.yaml is written last, and a harness file taken out of step with it
+  // would leave nothing to say a running Codex session still has the rule.
+  refuseUnwritable(path.join(home, 'bot.yaml'));
+
+  const file = path.join(home, FILE);
+  let claude;
+  if (runsOnClaude(bot)) {
+    refuseOutside(home, file);
+    const settings = readSettings(file, 'the permission rules the user allowed');
+    const present = presentIn(settings, file);
+    claude = { settings, present, removed: taken.filter((rule) => present.includes(rule)) };
+    if (claude.removed.length > 0) refuseUnwritable(file);
+  }
+  const codex = path.join(home, CODEX_FILE);
+  let before = [];
+  if (runsOnCodex(bot)) {
+    refuseOutside(home, codex);
+    if (existsSync(codex)) {
+      before = ruleLines(readFileSync(codex, 'utf8'));
+      refuseUnwritable(codex);
+    }
+  }
+
+  return () => {
+    const entries = [];
+    if (claude !== undefined) {
+      const { settings, present, removed } = claude;
+      if (removed.length > 0) {
+        const allow = present.filter((rule) => !removed.includes(rule));
+        writeFileSync(file, `${JSON.stringify({ ...settings, permissions: { ...settings.permissions, allow } }, null, 2)}\n`);
+      }
+      entries.push({ bot: bot.name, file, written: [], removed, waiting: waitingFor(bots, home, after, 'claude') });
+    }
+    if (runsOnCodex(after)) {
+      const entry = writeCodex(bots, home, after);
+      // A line goes only when no rule still allowed gives it.
+      const kept = [...codexOf(home, after).lines.keys()];
+      const removed = taken.filter((rule) => {
+        const { line } = codexForm(rule);
+        return line !== undefined && before.includes(line) && !kept.includes(line);
+      });
+      entries.push({ ...entry, written: [], removed });
+    }
+    return entries;
+  };
+}
+
+/** A refusal, before anything is written, of a file the kit could not write. */
+function refuseUnwritable(file) {
+  try {
+    accessSync(file, constants.W_OK);
+  } catch (error) {
+    throw new Error(`${file} cannot be written (${error.code ?? error.message}), so nothing was changed. Let the kit write it, then run the command again.`);
+  }
+}
+
+/** Why `--disallow` refuses a rule `allow` does not hold, and where one of that text is. */
+function notAllowed(home, bot, rule) {
+  const yaml = path.join(home, 'bot.yaml');
+  const file = path.join(home, FILE);
+  let byHand = false;
+  try {
+    byHand = runsOnClaude(bot) && leadsOutside(home, file) === undefined
+      && presentIn(readSettings(file), file).includes(rule);
+  } catch {
+    // A file the kit cannot read holds nothing it would take out.
+  }
+  const where = byHand
+    ? ` ${file} allows it, which the user added by hand, not the kit: it stays theirs, to take out themselves.`
+    : '';
+  return `--disallow ${rule} is not in the allow list in ${yaml}, so it is not the kit's to take back, and nothing was changed.${where} The kit takes back only rules that list holds, spelled exactly as they are there.`;
+}
+
 /**
  * The Codex form of what the bot is allowed: the file's rule lines, each once,
  * with the rules that gave them, and the rules Codex has no form for.

package/src/usage.js

@@ -9,7 +9,9 @@
 //
 // Which conversation belongs to which session is the book's to say and is never
 // guessed, as everywhere else in the kit (ADR 0012). A session's conversations
-// are the one the book names for it now and the ones in its history. One in the
+// are the one the book names for it now and the ones in its history. A session
+// since retired keeps a block of its own, marked retired, so a window that spans
+// a retirement loses nothing (#379). One in the
 // bot's folder that no session claims is reported under the bot instead, with
 // its figures, so that what it spent is visible rather than quietly dropped.
 //
@@ -29,14 +31,17 @@
 //      uncached input on both. Taken as written, one is many times the other for
 //      the same work, and the cached tokens get priced at full rate.
 //   3. Claude Code writes the same call down more than once, so a call counts
-//      once per `requestId` and `message.id`.
+//      once per `requestId` and `message.id`. A subagent's calls are in a file
+//      of their own beside the conversation that started it, and belong to it;
+//      the same call can be in more than one of those files, so a call counts
+//      once across all of a conversation's files together (#371).
 
 import { readFileSync, realpathSync } from 'node:fs';
 
 import { botDir, botNames, readBot } from './bot.js';
 import { readBook, sessionIdsIn } from './book.js';
-import { transcriptsIn } from './conversations.js';
-import { harnessOf } from './launch.js';
+import { claudeSubagentTranscripts, transcriptsIn } from './conversations.js';
+import { HARNESSES, 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'];
@@ -98,6 +103,9 @@ function forBot(bots, name, onlySession, window) {
   // them runs on is asked. The bot's own is the answer when it has no sessions.
   const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
   if (harnesses.size === 0) harnesses.add(bot.harness);
+  // The book does not say which harness a retired session ran on, so any is.
+  const retired = Array.isArray(book.retired) ? book.retired : [];
+  if (retired.length > 0) for (const harness of HARNESSES) harnesses.add(harness);
 
   const onRecord = new Map();
   for (const harness of harnesses) {
@@ -112,15 +120,22 @@ function forBot(bots, name, onlySession, window) {
 
   const claimed = sessionIdsIn(book);
 
-  const sessions = bot.sessions
-    .filter((session) => onlySession === undefined || session.name === onlySession)
-    .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 };
-    });
+  // Two entries can name the same conversation, one resumed after its session
+  // was retired, and one entry can name it twice, now and in its history: it is
+  // counted once, in the first block asked for that names it.
+  const taken = new Set();
+  const block = (entry) => {
+    const ids = [...new Set(idsIn(entry))].filter((id) => onRecord.has(id) && !taken.has(id));
+    for (const id of ids) taken.add(id);
+    const { conversations, gaps } = all(ids.map((id) => onRecord.get(id)), window);
+    return { conversations, not_counted: gaps };
+  };
+  const sessions = [
+    ...bot.sessions.map((session) => ({ name: session.name, entry: book.sessions[session.name] ?? {} })),
+    ...retired.map((entry) => ({ name: entry?.name, retired: entry?.retired, entry: entry ?? {} })),
+  ]
+    .filter(({ name }) => onlySession === undefined || name === onlySession)
+    .map(({ name, entry, ...was }) => ({ name, ...('retired' in was ? { retired: was.retired } : {}), ...block(entry) }));
 
   const unclaimed = all([...onRecord.values()].filter((one) => !claimed.has(one.id)), window);
 
@@ -151,9 +166,9 @@ const idsIn = (entry) => [
  * shorter page. What it could not count is still said.
  */
 function counted(one, window) {
-  const read = one.harness === 'claude' ? fromClaude : fromCodex;
   const tally = {
     calls: 0,
+    subagentCalls: 0,
     compactions: 0,
     tokens: Object.fromEntries(KINDS.map((kind) => [kind, 0])),
     models: new Set(),
@@ -166,15 +181,25 @@ function counted(one, window) {
     gaps: noGaps(),
   };
 
-  const { entries, unreadable, broken } = transcript(one.file);
-  tally.gaps.unreadable_transcripts = unreadable;
-  tally.gaps.broken_lines = broken;
-  read(entries, window, tally);
+  // A Claude Code conversation's subagents wrote their calls to files of their
+  // own, and what they spent is the conversation's.
+  const subagents = one.harness === 'claude' ? claudeSubagentTranscripts(one.file) : { files: [], unreadable: 0 };
+  tally.gaps.unreadable_transcripts += subagents.unreadable;
+  const sources = [one.file, ...subagents.files]
+    .map((file, index) => {
+      const { entries, unreadable, broken } = transcript(file);
+      tally.gaps.unreadable_transcripts += unreadable;
+      tally.gaps.broken_lines += broken;
+      return { entries, subagent: index > 0 };
+    });
+  if (one.harness === 'claude') fromClaude(sources, window, tally);
+  else fromCodex(sources[0].entries, window, tally);
   if (tally.calls === 0 && KINDS.every((kind) => tally.tokens[kind] === 0)) return { gaps: tally.gaps };
 
   return { gaps: tally.gaps, row: {
     id: one.id,
     calls: tally.calls,
+    subagent_calls: tally.subagentCalls,
     tokens: tally.tokens,
     by_model: [...tally.byModel].map(([model, its]) => ({ model, calls: its.calls, tokens: its.tokens })),
     models: [...tally.models],
@@ -204,6 +229,15 @@ function counted(one, window) {
  * the runs add up to the whole, with a call still being written at a boundary
  * charged once, part to each side (#169).
  *
+ * A call is one `requestId` and `message.id` across the main transcript and its
+ * subagents' files together, since the same call can be in more than one of
+ * them, and its records are taken in the order of their times. Copies written
+ * at the very same moment are taken smallest first, since a call's figures only
+ * grow: the largest is the latest. One with a figure missing may be the latest
+ * of them, so it is taken as that, and what it hides is said rather than
+ * measured past it. It is a subagent's when the main transcript has no record
+ * of it.
+ *
  * 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,
@@ -211,10 +245,10 @@ function counted(one, window) {
  * 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) {
+function fromClaude(sources, window, tally) {
   const byCall = new Map();
 
-  for (const entry of entries) {
+  for (const { entries, subagent } of sources) for (const entry of entries) {
     const when = Date.parse(entry.timestamp ?? '');
     if (entry.type === 'system' && entry.subtype === 'compact_boundary') {
       if (Number.isNaN(when)) tally.gaps.records_without_time += 1;
@@ -233,10 +267,11 @@ function fromClaude(entries, window, tally) {
     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, broken });
+    byCall.get(call).push({ entry, when, broken, subagent });
   }
 
   for (const records of byCall.values()) {
+    records.sort((one, other) => one.when - other.when || one.broken - other.broken || size(one.entry) - size(other.entry));
     const made = records[0].when;
     const atEnd = records.findLast(({ when, broken }) => !broken && when < window.to);
     if (atEnd === undefined) continue;
@@ -252,10 +287,17 @@ function fromClaude(entries, window, tally) {
     const isNew = inside(made, window);
     if (!isNew && KINDS.every((kind) => grew[kind] === 0)) continue;
 
-    count(tally, grew, atEnd.entry.message?.model, atEnd.entry.effort, isNew ? made : atEnd.when, isNew ? 1 : 0);
+    const subagent = records.every((record) => record.subagent);
+    count(tally, grew, atEnd.entry.message?.model, atEnd.entry.effort, isNew ? made : atEnd.when, isNew ? 1 : 0, subagent);
   }
 }
 
+/** How much one Claude Code record says its call has used so far, all kinds together. */
+const size = (entry) => {
+  const now = figures(entry);
+  return KINDS.reduce((sum, kind) => sum + now[kind], 0);
+};
+
 /** 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'];
 
@@ -300,15 +342,15 @@ 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.
+ * An event whose running total has a figure missing, or has none at all, 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;
@@ -338,14 +380,11 @@ function fromCodex(entries, window, tally) {
     const info = entry.payload?.info;
     if (info === undefined || info === null) continue;
 
-    const total = info.total_token_usage ?? undefined;
+    const total = info.total_token_usage;
     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)) {
+    // No running total at all is a running total with every figure missing:
+    // the next one's rise would take this call in again (#302).
+    if (!complete(total, CODEX_READ)) {
       used = null;
       broken = true;
     } else {
@@ -418,8 +457,9 @@ function kindsOf(raw) {
  * the total that has to be complete, and a row headed by nothing would be worse
  * than no row.
  */
-function count(tally, used, model, effort, when, calls = 1) {
+function count(tally, used, model, effort, when, calls = 1, subagent = false) {
   tally.calls += calls;
+  if (subagent) tally.subagentCalls += calls;
   for (const kind of KINDS) tally.tokens[kind] += used[kind];
   add(tally.models, model);
   add(tally.efforts, effort);