@assuredloop/orca-bot-kit 0.11.0 → 0.13.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.13.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 ?? [];
@@ -277,18 +277,34 @@ export function allowedNow(bots, bot, rules) {
  * added }: the whole list now, and what this call put in it.
  *
  * Only the list: the rules are written into the harness's settings by the
- * caller, as the rules build is run by the caller of `changeBot`.
+ * caller, as the rules build is run by the caller of `changeBot`. With `write`
+ * false it only refuses what the edit would refuse, and writes nothing.
  */
-export function allowRules(bots, bot, rules) {
+export function allowRules(bots, bot, rules, { write = true } = {}) {
   const { home, was } = allowedNow(bots, bot, rules);
   const added = [...new Set(rules)].filter((rule) => !was.includes(rule));
   const allow = [...was, ...added];
   if (added.length > 0) {
-    editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }));
+    editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
   }
   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,18 +403,24 @@ 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);
   edit(doc);
-  const text = doc.toString(YAML_OUT);
-  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.`);
+  const refusal = new Error(`${file} cannot be changed to ${what} without changing something else in it, so nothing was written. Make the change by hand.`);
+  let text;
+  try {
+    // An edit that leaves an alias with no anchor cannot be written at all.
+    text = doc.toString(YAML_OUT);
+  } catch {
+    throw refusal;
   }
-  if (text !== source) writeFileSync(file, text);
+  if (!changesExactly(source, text, expected)) throw refusal;
+  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, allowIn, 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,15 +610,28 @@ 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.
+    let allowInto;
     if (values.allow !== undefined) {
       const { home } = allowedNow(bots, values.bot, values.allow);
       refuseBroad(home, values.allow);
-      refuseNoCodexForm(readBot(home, values.bot), values.allow);
+      const bot = readBot(home, values.bot);
+      refuseNoCodexForm(bot, values.allow);
+      const { allow } = allowRules(bots, values.bot, values.allow, { write: false });
+      allowInto = allowIn(bots, home, { ...bot, 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) };
@@ -637,7 +656,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));
@@ -647,9 +666,11 @@ const commands = {
       }
     }
     if (values.allow !== undefined) {
+      // Written at once, as the charter's rules are built at once (#344): the
+      // harness's files first, bot.yaml last, so a write that fails leaves
+      // `allow` as it was, and the same command can run again (#383).
+      const permissions = allowInto();
       const allowed = allowRules(bots, values.bot, values.allow);
-      // Written at once, as the charter's rules are built at once (#344).
-      const permissions = writePermissions(bots, allowed.home, readBot(allowed.home));
       Object.assign(answer, { allow: allowed.allow, permissions });
       const codex = permissions.find((entry) => entry.unwritten !== undefined);
       lines.push(
@@ -664,6 +685,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 +1091,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 +1131,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 +1303,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

@@ -50,15 +50,46 @@ export function conversationsIn(harness, home, since) {
  */
 export function hasConversation(harness, home, id) {
   if (harness === 'claude') return existsSync(claudeTranscript(home, id));
-  return rollouts(codexDir()).some((file) => path.basename(file).endsWith(`-${id}.jsonl`));
+  return codexRollout(id) !== undefined;
 }
 
+/**
+ * Where Codex keeps the conversation `id`, whatever folder it ran in, found by
+ * the file name Codex makes from the id; `undefined` when it has none.
+ */
+export const codexRollout = (id) =>
+  rollouts(codexDir()).find((file) => path.basename(file).endsWith(`-${id}.jsonl`));
+
 /**
  * Where Claude Code keeps the conversation `id` of this bot home, whether or
  * not it has written it yet.
  */
 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/orca.js

@@ -180,7 +180,12 @@ export const deleteProject = (setupId) => orca(['project', 'setup-delete', '--se
 /** Said after a run that made or renamed a project, whatever `tellWindow` answered, and after a removal `reloadWindow` could not follow. */
 export const RELOAD_LINE = "If Orca's sidebar does not show it, reload the window with Cmd+Shift+R.";
 
-/** How long Orca's client waits for its runtime, and how long the kit waits for the client. */
+/**
+ * How long Orca's client waits for its runtime, and how long the kit waits for
+ * the client. Measured beside the full unit suite on Orca 1.4.214, the whole
+ * call took at most 721 ms and the call inside the client at most 447 ms
+ * (tech notes, #384).
+ */
 const CLIENT_WAIT_MS = 2000;
 const CLIENT_KILL_MS = 3000;
 

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, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { leadsOutside } from './bot.js';
@@ -266,10 +267,10 @@ export const allowCommand = (bots, bot, rules) => [
  * the kit may not write is an entry with its `trouble` rather than a throw.
  */
 export function writePermissions(bots, home, bot, { keepGoing = false } = {}) {
-  const writers = [[runsOnClaude, FILE, writeClaude], [runsOnCodex, CODEX_FILE, writeCodex]];
-  return writers.filter(([runs]) => runs(bot)).map(([, file, write]) => {
+  const writers = [[runsOnClaude, FILE, planClaude], [runsOnCodex, CODEX_FILE, planCodex]];
+  return writers.filter(([runs]) => runs(bot)).map(([, file, plan]) => {
     try {
-      return write(bots, home, bot);
+      return plan(bots, home, bot).write();
     } catch (error) {
       if (!keepGoing) throw error;
       return { bot: bot.name, file: path.join(home, file), written: [], waiting: [], trouble: error.message };
@@ -278,30 +279,155 @@ export function writePermissions(bots, home, bot, { keepGoing = false } = {}) {
 }
 
 /**
- * Write what the bot is allowed into its Claude settings: `{ bot, file,
- * written, waiting }`, with `written` the rules this run added.
+ * Check every file `bot change --allow` writes before any is written (#383):
+ * bot.yaml, and the files of the harnesses the bot runs on, read and found
+ * writable. `bot` is the bot as it will be, with the new rules in `allow`.
+ * What comes back writes the harness files, one entry per file, Claude's
+ * first; the caller writes bot.yaml after, so a write that fails leaves
+ * `allow` as it was, for the same command to run again.
+ */
+export function allowIn(bots, home, bot) {
+  refuseUnwritable(path.join(home, 'bot.yaml'));
+  const plans = [[runsOnClaude, planClaude], [runsOnCodex, planCodex]]
+    .filter(([runs]) => runs(bot)).map(([, plan]) => plan(bots, home, bot));
+  for (const plan of plans) if (plan.writes) refuseUnwritable(plan.answer.file);
+  return () => plans.map((plan) => plan.write());
+}
+
+/**
+ * What writing the bot's allowed rules into its Claude settings would do,
+ * read and refused before anything is written: `{ answer, writes, write }`.
+ * `write()` gives `{ bot, file, written, waiting }`, with `written` the rules
+ * it added.
  *
  * Only rules `allow` holds are written. Everything else in the file stays as it
  * is, the user's own entries and their order included; a rule missing from the
  * file goes after them, and a run with nothing to add writes nothing.
  */
-function writeClaude(bots, home, bot) {
+function planClaude(bots, home, bot) {
   const file = path.join(home, FILE);
   const allowed = allowOf(home, bot);
   const waiting = waitingFor(bots, home, bot, 'claude');
   const answer = { bot: bot.name, file, written: [], waiting };
-  if (allowed.length === 0) return answer;
+  const none = { answer, writes: false, write: () => answer };
+  if (allowed.length === 0) return none;
 
   refuseOutside(home, file);
   const settings = readSettings(file, 'the permission rules the user allowed');
   const present = presentIn(settings, file);
   const missing = [...new Set(allowed)].filter((rule) => !present.includes(rule));
-  if (missing.length === 0) return answer;
+  if (missing.length === 0) return none;
 
   const wanted = { ...settings, permissions: { ...settings.permissions, allow: [...present, ...missing] } };
-  mkdirSync(path.dirname(file), { recursive: true });
-  writeFileSync(file, `${JSON.stringify(wanted, null, 2)}\n`);
-  return { ...answer, written: missing };
+  return {
+    answer,
+    writes: true,
+    write: () => {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, `${JSON.stringify(wanted, null, 2)}\n`);
+      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 = planCodex(bots, home, after).write();
+      // 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: one
+ * not there yet is made in the nearest folder that is, which the kit must be
+ * able to enter and write in, and which must be a folder.
+ */
+function refuseUnwritable(file) {
+  let where = file;
+  while (!existsSync(where) && path.dirname(where) !== where) where = path.dirname(where);
+  try {
+    if (where !== file && !statSync(where).isDirectory()) throw Object.assign(new Error('not a folder'), { code: 'ENOTDIR' });
+    accessSync(where, where === file ? constants.W_OK : constants.W_OK | constants.X_OK);
+  } catch (error) {
+    const at = where === file ? '' : ` at ${where}`;
+    throw new Error(`${file} cannot be written (${error.code ?? error.message}${at}), 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.`;
 }
 
 /**
@@ -324,16 +450,18 @@ function codexOf(home, bot) {
 const ruleLines = (text) => text.split('\n').map((line) => line.trim()).filter((line) => line !== '' && !line.startsWith('#'));
 
 /**
- * Write the Codex form of what the bot is allowed into `.codex/rules/obk.rules`:
+ * What writing the Codex form of what the bot is allowed into
+ * `.codex/rules/obk.rules` would do, as `planClaude` gives it. `write()` gives
  * `{ bot, file, written, waiting, unwritten }`, with `written` every rule in
- * the file when this run wrote it. The kit owns the file whole and writes it
- * only when it would change; with nothing to write and no file, it makes none.
+ * the file when it wrote it. The kit owns the file whole and writes it only
+ * when it would change; with nothing to write and no file, it makes none.
  */
-function writeCodex(bots, home, bot) {
+function planCodex(bots, home, bot) {
   const file = path.join(home, CODEX_FILE);
   const { lines, unwritten } = codexOf(home, bot);
   const answer = { bot: bot.name, file, written: [], waiting: waitingFor(bots, home, bot, 'codex'), unwritten };
-  if (lines.size === 0 && !existsSync(file)) return answer;
+  const none = { answer, writes: false, write: () => answer };
+  if (lines.size === 0 && !existsSync(file)) return none;
 
   refuseOutside(home, file);
   const text = [
@@ -341,10 +469,16 @@ function writeCodex(bots, home, bot) {
     '# obk rewrites this whole file: put rules of your own in another file in this folder.',
     ...lines.keys(),
   ].join('\n');
-  if (existsSync(file) && readFileSync(file, 'utf8') === `${text}\n`) return answer;
-  mkdirSync(path.dirname(file), { recursive: true });
-  writeFileSync(file, `${text}\n`);
-  return { ...answer, written: [...lines.values()].flat() };
+  if (existsSync(file) && readFileSync(file, 'utf8') === `${text}\n`) return none;
+  return {
+    answer,
+    writes: true,
+    write: () => {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, `${text}\n`);
+      return { ...answer, written: [...lines.values()].flat() };
+    },
+  };
 }
 
 /**

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.
 //
@@ -23,20 +25,26 @@
 //      `last_token_usage` counts a call written down twice twice. So a call is
 //      the difference in the running total from the event before: none is a
 //      repeat, and a fall is a new window, whose own `last_token_usage` counts.
+//      A rollout's first record counts its own figure too: a child's running
+//      total can start with its parent's inside it, and a fork can begin with
+//      its origin's records copied in, which are the origin's calls (#376).
 //   2. The two harnesses do not mean the same thing by `input_tokens`. Claude
 //      Code leaves the cache reads out of it; Codex counts them inside it. So
 //      the Codex figure has its cached tokens taken back out, and `input` means
 //      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, codexRollout, 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 +106,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 +123,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 +169,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 +184,28 @@ 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 {
+    const copied = originOf(sources[0].entries, tally);
+    if (copied !== null) fromCodex(sources[0].entries, window, tally, copied);
+  }
   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 +235,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 +251,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 +273,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 +293,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,22 +348,31 @@ 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.
+ *
+ * A fork begins with the records of the conversation it was forked from, copied
+ * in and stamped at the fork's start, or all at one time in a file Codex rebuilt.
+ * Those are the origin's calls, counted with the origin: the leading records
+ * that are in `copied`, both figures, are followed and not counted (#376).
+ * A leading record with a figure missing may be a copy or the fork's own call;
+ * it is not counted, and is said to be.
  */
-function fromCodex(entries, window, tally) {
+function fromCodex(entries, window, tally, copied) {
   let model;
   let effort;
   let running;
   // Whether a running total with something missing came since the last complete one.
   let broken = false;
+  // Whether the records so far are all the origin's, copied into a fork.
+  let copying = copied !== undefined;
 
   for (const entry of entries) {
     const when = Date.parse(entry.timestamp ?? '');
@@ -338,13 +395,26 @@ 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;
+    const whole = complete(total, CODEX_READ) && complete(info.last_token_usage, CODEX_READ);
+    if (copying && whole && copied.has(key(info))) {
+      running = total;
+      broken = false;
+      continue;
+    }
+    // A record with a figure missing cannot be told from a copy while copies
+    // may still be coming: it is not counted and is said to be, and the next
+    // record is matched as before.
+    const unknown = copying && !whole;
+    if (!unknown) copying = false;
+
     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);
+    // 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 (unknown && complete(total, CODEX_READ)) {
+      used = null;
+      running = total;
+      broken = false;
     } else if (!complete(total, CODEX_READ)) {
       used = null;
       broken = true;
@@ -373,13 +443,56 @@ function fromCodex(entries, window, tally) {
 /** 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');
 
+/**
+ * A usage record as one value, both its figures: a call of the child's own can
+ * bring the running total back to one the origin once had, but not with the same
+ * figure of its own.
+ */
+const key = (info) => [info.total_token_usage, info.last_token_usage]
+  .map((figure) => CODEX_READ.map((field) => figure[field]).join('/')).join('|');
+
+/**
+ * The usage records of the conversation a Codex rollout was forked from, which
+ * it may begin with copies of (tech notes, section 3). `undefined` when it names
+ * no origin. When the origin cannot be read whole, a line of it broken or a
+ * figure missing from a record, where the copies end cannot be told, so none of
+ * the fork is counted: `null`, and said to be.
+ */
+function originOf(entries, tally) {
+  const id = entries.find((entry) => entry.type === 'session_meta')?.payload?.forked_from_id;
+  if (typeof id !== 'string' || id === '') return undefined;
+
+  const file = codexRollout(id);
+  const origin = file === undefined ? { unreadable: 1 } : transcript(file);
+  // No `info` is a note about rate limits, not a record of usage.
+  const records = origin.unreadable > 0 ? [] : origin.entries
+    .filter((entry) => entry.type === 'event_msg' && entry.payload?.type === 'token_count')
+    .map((entry) => entry.payload.info)
+    .filter((info) => info !== undefined && info !== null);
+  const whole = origin.unreadable === 0 && origin.broken === 0 && records.every((info) =>
+    complete(info.total_token_usage, CODEX_READ) && complete(info.last_token_usage, CODEX_READ));
+  if (!whole) {
+    tally.gaps.unreadable_transcripts += 1;
+    return null;
+  }
+  return new Set(records.map(key));
+}
+
 /**
  * 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.
+ * and `null` where what it used cannot be known. The first has nothing before
+ * it, and its running total can hold what a parent spent before this rollout
+ * began, so its own figure is what it used. An own figure of nothing in every
+ * field is a note of where the running total stands, not a call: wherever else
+ * Codex writes one, the running total does not move (tech notes, section 3).
  */
 function spent(running, total, info) {
-  if (running === undefined) return kindsOf(total);
+  if (running === undefined) {
+    const own = info.last_token_usage;
+    if (complete(own, CODEX_READ) && CODEX_FIELDS.every((field) => number(own[field]) === 0)) return undefined;
+    return perCall(info);
+  }
 
   const moved = total.total_tokens - running.total_tokens;
   if (moved === 0) return undefined;
@@ -418,8 +531,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);