@assuredloop/orca-bot-kit 0.19.0 → 0.20.0

package/README.md

@@ -615,7 +615,9 @@ real Orca and the real harnesses on your own machine. No CI runner can do that,
 so these are run by hand before a change that touches Orca or a harness is
 merged. A system test touches only what it creates and removes it afterwards,
 except the mailbox Runs Orca gives no way to delete, which the run names; it
-never closes a tab it did not open.
+never closes a tab it did not open. The trust its harnesses write into your
+`~/.codex/config.toml` and `~/.claude.json` for the run's own throwaway folders
+is taken out again after the run, and named; nothing else in them is changed.
 
 They run on the machine the command is typed on, so the command will not start
 them by itself. On its own it says what it is about to drive — whose machine,

package/SETUP.md

@@ -194,10 +194,10 @@ waiting for:
 | On screen | Send | Which is | Proven on |
 |---|---|---|---|
 | Claude Code's folder trust list | `\x1b[B\r` | down, then return: its selection starts on **No, exit** | Claude Code 2.1.283 |
-| Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `\r` | return: its selection starts on **Trust and continue** | Codex 0.158.0 |
-| Codex's `Hooks need review` | `\x1b[B\r` | down, then return, to **Trust all and continue**; if the selection already starts there, return alone | Codex 0.158.0 |
-| Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home) | Codex 0.158.0 |
-| Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; seen on 0.157.1 (offering 0.158.0) with the selection on **Update now**, not pressed; 0.158.0 has had no newer release to offer |
+| Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `\r` | return: its selection starts on **Trust and continue** | Codex 0.160.0 |
+| Codex's `Hooks need review` | `\x1b[B\r` | down, then return, to **Trust all and continue**; if the selection already starts there, return alone | Codex 0.160.0 |
+| Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home) | Codex 0.160.0 |
+| Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; seen on 0.157.1 (offering 0.158.0) with the selection on **Update now**, not pressed; 0.158.0 offered 0.160.0, taken on 2026-10-02 by Bot Father's restarts |
 | `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell | oh-my-zsh bf77e35 |
 | Claude Code's `Teach auto mode about your environment?` | `\x1b` | Esc, which cancels it (**Not now**). On 2.1.283 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live twice on 2.1.283, in #261's live test and #239's live run 1 (#416); 2.1.278 showed a numbered list, answered with 2. Not now |
 
@@ -217,7 +217,7 @@ empty book and nothing says why.
 Codex's trust question applies to the **repository root**, which for a bot means
 the whole bots folder rather than the one bot. That is what they are agreeing to.
 
-Codex's `/new` question (seen on 0.156.1, 0.157.1 and 0.158.0) is always answered with the current checkout, which is the bot
+Codex's `/new` question (seen on 0.156.1, 0.157.1, 0.158.0 and 0.160.0) is always answered with the current checkout, which is the bot
 home. The kit never makes a git worktree, so
 `2. New worktree` is never the answer.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,7 +35,8 @@
     "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@stryker-mutator/core": "10.0.0"
+    "@stryker-mutator/core": "10.0.0",
+    "smol-toml": "1.9.0"
   },
   "overrides": {
     "typed-rest-client": {

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

@@ -288,9 +288,9 @@ otherwise `/Applications/Orca.app/Contents/Resources/bin/orca`. A bare
 | On screen | Send | Which is | Proven on |
 |---|---|---|---|
 | Claude Code's trust list | `\x1b[B\r` | down, return: off **No, exit** | Claude Code 2.1.283 |
-| Codex's `Trust this folder?` | `\r` | return: it starts on yes | Codex 0.158.0 |
-| Codex's `Hooks need review` | `\x1b[B\r` | **Trust all and continue** | Codex 0.158.0 |
-| Codex's `Where should the new conversation run?` | `\r` | **Current checkout** | Codex 0.158.0 |
+| Codex's `Trust this folder?` | `\r` | return: it starts on yes | Codex 0.160.0 |
+| Codex's `Hooks need review` | `\x1b[B\r` | **Trust all and continue** | Codex 0.160.0 |
+| Codex's `Where should the new conversation run?` | `\r` | **Current checkout** | Codex 0.160.0 |
 | Codex's update offer, `1. Update now` | `\r` | **Update now**, where it starts | Codex 0.156.1 |
 | `[oh-my-zsh] Would you like to update?` | `n` | no: the user updates it | oh-my-zsh bf77e35 |
 | Claude Code's `Teach auto mode…` | `\x1b` | Esc: Not now; no return | Not yet proven, below |
@@ -302,7 +302,8 @@ return: on Codex's update offer that took the highlighted **Update now**,
 whatever the digit was. Codex's trust said `1. Yes, continue` on older
 versions. Its hooks review sometimes starts on `2` already: then return alone.
 Its update offer was proven on 0.156.1; 0.157.1 showed it with the selection on
-Update now, not pressed, and 0.158.0 has had no newer release to offer.
+Update now, not pressed, and 0.158.0 offered 0.160.0, taken on 2026-10-02 by
+Bot Father's restarts.
 Claude Code's `Teach auto mode` on 2.1.283 is a form, not a list, ending
 `Enter to continue · Esc to cancel`: never send it a return, since
 Enter is Continue, which scans the project, recent sessions and the machine's
@@ -313,7 +314,7 @@ question matters most. The kit's hook is how the book learns which
 conversation the session is running, and until it is answered the
 conversation has not started. Codex's trust applies to the repository root,
 which is the whole bots folder. Codex's `/new` may ask where the new
-conversation runs (0.156.1, 0.157.1 and 0.158.0 all did); the answer is
+conversation runs (0.156.1, 0.157.1, 0.158.0 and 0.160.0 all did); the answer is
 always the current checkout, the bot home, and never `2. New worktree`:
 the kit never makes a git worktree.
 

package/src/cli.js

@@ -217,15 +217,15 @@ Usage:
   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 (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.
+                            subagents' and Codex's auto-reviews included, and
+                            how many were whose), 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
                             what the harness says about a session starting on
@@ -1247,6 +1247,7 @@ function conversationLine(one) {
     .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'}` : ''}`
+    + `${one.review_calls > 0 ? `  of which Codex's auto-review: ${one.review_calls} call${one.review_calls === 1 ? '' : 's'}` : ''}`
     + `${ran === '' ? '' : `  ${ran}`}`
     + `${used === '' ? '' : `  ${used}`}`
     + `${one.compactions > 0 ? `  compacted ${one.compactions}` : ''}`;

package/src/conversations.js

@@ -115,7 +115,8 @@ export function claudeSubagentTranscripts(file) {
 /**
  * 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,
- * and whether the harness marks it as a subagent's.
+ * whether the harness marks it as a subagent's, and, for a Codex subagent, the
+ * conversation it was started for and whether it is Codex's auto-review.
  */
 export function transcriptsIn(harness, home, since) {
   const from = since === undefined ? 0 : Date.parse(since);
@@ -123,7 +124,13 @@ 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, subagent: one.subagent === true }));
+    .map((one) => ({
+      id: one.id,
+      at: new Date(one.at).toISOString(),
+      file: one.file,
+      subagent: one.subagent === true,
+      ...(one.parent === undefined ? {} : { parent: one.parent, review: one.review }),
+    }));
 }
 
 /**
@@ -209,11 +216,29 @@ 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, subagent: isSubagent(meta) }]
+        ? [{ id: meta.id, at: Date.parse(meta.timestamp ?? '') || startedAt(file) || 0, file, subagent: isSubagent(meta), ...codexParent(meta) }]
         : [];
     });
 }
 
+/**
+ * Every Codex subagent on record, wherever it ran, with the conversation it was
+ * started for: `{ id, file, parent, review }` (#449). Found by the link in its
+ * own record, not by folder: a session's worker can run in a folder of its own.
+ * Read once per process, since every bot asks the same question of the same
+ * files.
+ */
+let subagents;
+export function codexSubagents() {
+  subagents ??= rollouts(codexDir()).flatMap((file) => {
+    const meta = sessionMeta(file);
+    if (meta === undefined || typeof meta.id !== 'string') return [];
+    const link = codexParent(meta);
+    return link.parent === undefined ? [] : [{ id: meta.id, file, ...link }];
+  });
+  return subagents;
+}
+
 /** Every rollout file under Codex's sessions folder, however deep it files them. */
 function rollouts(dir, depth = 0) {
   if (depth > 4) return [];
@@ -243,6 +268,21 @@ function sessionMeta(file) {
 const isSubagent = (meta) =>
   meta.source !== null && typeof meta.source === 'object' && 'subagent' in meta.source;
 
+/**
+ * The conversation a Codex subagent was started for, as its own record names
+ * it, and whether it is Codex's auto-review: `{ parent, review }`, or nothing
+ * for a session's own (#449). A session's spawned subagent names it under
+ * `source.subagent.thread_spawn.parent_thread_id`; Codex's auto-review, which
+ * is `{ subagent: { other: 'guardian' } }`, names the conversation it reviewed
+ * as a top-level `parent_thread_id` (tech notes, section 3).
+ */
+function codexParent(meta) {
+  if (!isSubagent(meta)) return {};
+  const parent = meta.source.subagent?.thread_spawn?.parent_thread_id ?? meta.parent_thread_id;
+  if (typeof parent !== 'string' || parent === '') return {};
+  return { parent, review: meta.source.subagent?.other === 'guardian' };
+}
+
 /** When a file was last written, for leaving out what is plainly too old. */
 function lastTouched(file) {
   try {

package/src/usage.js

@@ -43,7 +43,7 @@ import { realpathSync } from 'node:fs';
 
 import { botDir, botNames, readBot } from './bot.js';
 import { readBook, sessionIdsIn } from './book.js';
-import { claudeSubagentTranscripts, claudeTranscriptAnywhere, codexRollout, transcriptsIn } from './conversations.js';
+import { claudeSubagentTranscripts, claudeTranscriptAnywhere, codexRollout, codexSubagents, transcriptsIn } from './conversations.js';
 import { eachLine } from './lines.js';
 import { HARNESSES, harnessOf } from './launch.js';
 
@@ -91,11 +91,41 @@ export function readUsage(bots, { bot: only, session: onlySession, since, until
     throw new Error(`--until is before --since, so there is no window between them: ${until} comes before ${since}.`);
   }
 
-  return (only === undefined ? names : [only]).map((name) => forBot(bots, name, onlySession, { from, to }));
+  // Who owns a Codex subagent is a question about the whole fleet, asked once:
+  // one can run in another bot's folder, or be claimed by another bot's book.
+  const fleet = subagentOwners(bots, names);
+  return (only === undefined ? names : [only]).map((name) => forBot(bots, name, onlySession, { from, to }, fleet));
+}
+
+/**
+ * Every conversation any bot's book names, the Codex subagents that hang off
+ * each by their own links, and the ones so attached (#449). A subagent a book
+ * names is that book's, and is never attached under another: the book's word
+ * comes first (ADR 0012). One claimed or attached anywhere is no bot's
+ * unclaimed.
+ */
+function subagentOwners(bots, names) {
+  const claimed = new Set();
+  for (const name of names) for (const id of sessionIdsIn(readBook(realHome(botDir(bots, name))))) claimed.add(id);
+  const childrenOf = new Map();
+  for (const one of codexSubagents()) {
+    if (claimed.has(one.id)) continue;
+    if (!childrenOf.has(one.parent)) childrenOf.set(one.parent, []);
+    childrenOf.get(one.parent).push(one);
+  }
+  const attached = new Set();
+  const waiting = [...claimed].flatMap((id) => childrenOf.get(id) ?? []);
+  while (waiting.length > 0) {
+    const child = waiting.shift();
+    if (attached.has(child.id)) continue;
+    attached.add(child.id);
+    waiting.push(...(childrenOf.get(child.id) ?? []));
+  }
+  return { claimed, childrenOf, attached };
 }
 
 /** One bot: what each of its sessions used, and what nobody claims. */
-function forBot(bots, name, onlySession, window) {
+function forBot(bots, name, onlySession, window, fleet) {
   // The folder as the file system knows it, not as the caller spelled it: a
   // bots folder reached through a symlink is the same fleet, and the harnesses
   // file their transcripts under the real path (as `restart` and `message` do).
@@ -138,6 +168,31 @@ function forBot(bots, name, onlySession, window) {
     }
   }
 
+  // A Codex subagent names the conversation it was started for, and what it
+  // spent is that conversation's, at any depth, as a Claude Code subagent's is
+  // (#449). It is found by that link wherever it ran, and joined only through
+  // links that end at a conversation the book names, as the fleet's owners
+  // say: a parent no session claims leaves its children where they were, and
+  // nothing is guessed from timing or folder. The book's word is enough
+  // without the parent's own file, whose calls are then said to be unreadable.
+  const { childrenOf } = fleet;
+  const attached = new Set();
+  for (const id of claimed) {
+    const own = onRecord.get(id);
+    if (own !== undefined && own.harness !== 'codex') continue;
+    const found = [];
+    const waiting = [...(childrenOf.get(id) ?? [])];
+    while (waiting.length > 0) {
+      const child = waiting.shift();
+      if (attached.has(child.id)) continue;
+      attached.add(child.id);
+      // A review of a subagent is still the harness's approval, not the work.
+      found.push({ file: child.file, kind: child.review ? 'review' : 'subagent' });
+      waiting.push(...(childrenOf.get(child.id) ?? []));
+    }
+    if (found.length > 0) onRecord.set(id, { id, harness: 'codex', subagent: false, ...own, children: found });
+  }
+
   // 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.
@@ -155,7 +210,9 @@ function forBot(bots, name, onlySession, window) {
     .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);
+  // What any bot's book names, or any claim gathered in, is not unclaimed here,
+  // wherever its record lies (#449 review).
+  const unclaimed = all([...onRecord.values()].filter((one) => !fleet.claimed.has(one.id) && !fleet.attached.has(one.id)), window);
 
   return { bot: name, home, sessions, unclaimed: unclaimed.conversations, unclaimed_not_counted: unclaimed.gaps };
 }
@@ -187,6 +244,7 @@ function counted(one, window) {
   const tally = {
     calls: 0,
     subagentCalls: 0,
+    reviewCalls: 0,
     compactions: 0,
     tokens: Object.fromEntries(KINDS.map((kind) => [kind, 0])),
     models: new Set(),
@@ -203,7 +261,10 @@ function counted(one, window) {
   // 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]
+  // A Codex conversation the book names, whose own record is gone but whose
+  // subagents' are not: its own calls cannot be counted, and that is said (#449).
+  if (one.file === undefined) tally.gaps.unreadable_transcripts += 1;
+  const sources = [...(one.file === undefined ? [] : [one.file]), ...subagents.files]
     .map((file, index) => {
       const { entries, unreadable, broken } = transcript(file, countable);
       tally.gaps.unreadable_transcripts += unreadable;
@@ -212,8 +273,19 @@ function counted(one, window) {
     });
   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 (one.file !== undefined) {
+      const copied = originOf(sources[0].entries, tally);
+      if (copied !== null) fromCodex(sources[0].entries, window, tally, copied);
+    }
+    // Each subagent's rollout keeps its own running total, so each is counted
+    // on its own, from its own records (#449).
+    for (const child of one.children ?? []) {
+      const { entries, unreadable, broken } = transcript(child.file, countable);
+      tally.gaps.unreadable_transcripts += unreadable;
+      tally.gaps.broken_lines += broken;
+      const itsCopied = originOf(entries, tally);
+      if (itsCopied !== null) fromCodex(entries, window, tally, itsCopied, child.kind);
+    }
   }
   if (tally.calls === 0 && KINDS.every((kind) => tally.tokens[kind] === 0)) return { gaps: tally.gaps };
 
@@ -221,6 +293,7 @@ function counted(one, window) {
     id: one.id,
     calls: tally.calls,
     subagent_calls: tally.subagentCalls,
+    review_calls: tally.reviewCalls,
     tokens: tally.tokens,
     by_model: [...tally.byModel].map(([model, its]) => ({ model, calls: its.calls, tokens: its.tokens })),
     models: [...tally.models],
@@ -309,7 +382,7 @@ function fromClaude(sources, window, tally) {
     if (!isNew && KINDS.every((kind) => grew[kind] === 0)) continue;
 
     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);
+    count(tally, grew, atEnd.entry.message?.model, atEnd.entry.effort, isNew ? made : atEnd.when, isNew ? 1 : 0, subagent ? 'subagent' : undefined);
   }
 }
 
@@ -380,7 +453,7 @@ const CODEX_FIELDS = [
  * 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, copied) {
+function fromCodex(entries, window, tally, copied, kind) {
   let model;
   let effort;
   let running;
@@ -451,7 +524,7 @@ function fromCodex(entries, window, tally, copied) {
       continue;
     }
 
-    count(tally, used, model, effort, when);
+    count(tally, used, model, effort, when, 1, kind);
   }
 }
 
@@ -546,9 +619,10 @@ 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, subagent = false) {
+function count(tally, used, model, effort, when, calls = 1, kind = undefined) {
   tally.calls += calls;
-  if (subagent) tally.subagentCalls += calls;
+  if (kind === 'subagent') tally.subagentCalls += calls;
+  if (kind === 'review') tally.reviewCalls += calls;
   for (const kind of KINDS) tally.tokens[kind] += used[kind];
   add(tally.models, model);
   add(tally.efforts, effort);