@assuredloop/orca-bot-kit 0.12.0 → 0.14.0

package/README.md

@@ -508,7 +508,7 @@ verdict: which of these matter, and in what order, is for you or for Bot Father.
 ## Sessions and bots that talk
 
 Ask the kit how to reach a session, and it answers with the road and the
-address ([ADR 0018](docs/adr/0018-messaging-transport.md)):
+address ([ADR 0030](docs/adr/0030-messaging-transport.md)):
 
 ```sh
 obk message to    --bots /path/to/my-bots --to api-bot/daily

package/package.json

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

package/rules/temporary.md

@@ -0,0 +1,21 @@
+---
+name: temporary
+title: Temporary sessions of your own
+applies: all
+---
+
+For a piece of work that wants a helper, a long-lived session may make a
+temporary session of its own bot, without asking Bot Father:
+`"${OBK_CLI:-obk}" temp make --bots <bots> --name <name> --prompt <the task>`,
+run in your own tab. It takes your settings unless you say otherwise, and gets
+a work dir, a tab and a mailbox.
+
+A new tab can stop on a first-run screen. Answer it yourself, from the table
+the command's output points to.
+
+Retire it when its work is done:
+`"${OBK_CLI:-obk}" temp retire --bots <bots> --name <name>`. Before you make
+another, first retire any of yours whose work is done.
+
+You manage only the temporary sessions you made; a temporary session makes
+none of its own. Every other session is Bot Father's to make, change or retire.

package/src/book.js

@@ -30,6 +30,9 @@ const HEADER = `# What Orca calls this bot on this machine, and where each of it
 #
 # \`retired\` holds what the book knew about each session \`obk retire\` took off
 # the bot, with when, so the conversations it had are still accounted for.
+#
+# \`temporary\` marks a session another session of this bot made with
+# \`obk temp make\`: which session made it, and when. Its maker retires it.
 `;
 
 export const bookFile = (home) => path.join(home, 'sessions.yaml');

package/src/bot.js

@@ -21,7 +21,7 @@ export const botsDir = (bots) => path.join(bots, 'bots');
 export const botDir = (bots, name) => path.join(botsDir(bots), name);
 
 /** A bot's name: the folder it lives in, and safe to be one. */
-const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 /** The file that says what a bot is. A folder without one is not a bot. */
 const BOT_YAML = 'bot.yaml';
@@ -277,14 +277,15 @@ export function allowedNow(bots, bot, rules, flag = '--allow') {
  * 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 };
 }
@@ -410,10 +411,15 @@ function editBot(bots, bot, what, edit, expected, write = true) {
   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 (!changesExactly(source, text, expected)) throw refusal;
   if (write && text !== source) writeFileSync(file, text);
 }
 

package/src/cli.js

@@ -17,9 +17,9 @@ 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, takeBack, writePermissions } from './permissions.js';
+import { checkMail, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
+import { orcaCli, orcaTrouble, RELOAD_LINE, TERMINAL_ENV } from './orca.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';
@@ -28,6 +28,7 @@ import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
 import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
 import { addSource, fetchSources } from './sources.js';
+import { makeTemp, retireTemp } from './temp.js';
 import { readUsage } from './usage.js';
 import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 
@@ -95,6 +96,21 @@ Usage:
                             bot whose Orca project holds a tab your book does
                             not name, and moves the folder only once Orca no
                             longer lists the project.
+  obk temp make --bots <path> --name <session>
+                (--prompt <text> | --prompt-file <path>) [--harness claude|codex]
+                [--model <m>] [--effort <e>] [--context <c>]
+                [--approval ${APPROVALS.join('|')}]
+                            Run in a long-lived session's own tab: make a
+                            temporary session of that session's bot for a piece
+                            of work, and bring it up. It takes your harness,
+                            model, effort, context and approval unless you say
+                            otherwise, works in work/<session>, and has the task
+                            as its start prompt. The book records it as
+                            temporary, made by you.
+  obk temp retire --bots <path> --name <session>
+                            Run in the maker's own tab: retire a temporary
+                            session it made, as obk retire does. It refuses a
+                            long-lived session, or one another session made.
   obk rules build --bots <path> [--bot <bot>]
                             Build every bot's AGENTS.md from its charter and
                             the rule units it carries, or just the one you
@@ -242,6 +258,8 @@ const COMMANDS = {
   'message check': ['bots'],
   'session record': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
+  'temp make': ['bots', 'name'],
+  'temp retire': ['bots', 'name'],
 };
 
 /** What each flag is for, in the sentence a caller reads when it is missing. */
@@ -335,9 +353,9 @@ async function run(argv) {
     return 1;
   }
 
-  // `bot`, `rules`, `skills`, `session`, `source` and `message` are commands of
-  // two words; the rest are one.
-  const words = ['bot', 'rules', 'skills', 'session', 'source', 'message'].includes(positionals[0]) ? 2 : 1;
+  // `bot`, `rules`, `skills`, `session`, `source`, `message` and `temp` are
+  // commands of two words; the rest are one.
+  const words = ['bot', 'rules', 'skills', 'session', 'source', 'message', 'temp'].includes(positionals[0]) ? 2 : 1;
   const command = positionals.slice(0, words).join(' ');
   const extra = positionals.slice(words);
 
@@ -534,8 +552,6 @@ const commands = {
 
   async retire(bots, values) {
     refuseWhenOrcaIsDown();
-    const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab.name}  tab ${tab.tabId}  terminal ${tab.terminal}`);
-
     if (values.session !== undefined) {
       const retired = await retireSession(bots, { bot: values.bot, session: values.session });
       return {
@@ -543,6 +559,7 @@ const commands = {
         lines: [
           ...closedLines(retired.closed),
           `retired    ${retired.bot} ${retired.session}: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+          ...leftLines(retired.promptsLeft),
         ],
       };
     }
@@ -571,6 +588,39 @@ const commands = {
           retired.windowReloaded ? "reloaded   Orca's window, so its sidebar no longer shows the project" : RELOAD_LINE,
         ]),
         `retired    ${retired.bot}: moved to ${path.relative(bots, retired.moved)}, with its book, charter and memory`,
+        ...leftLines(retired.promptsLeft),
+      ],
+    };
+  },
+
+  async 'temp make'(bots, values) {
+    const tab = callerTab(bots, true);
+    refuseWhenOrcaIsDown();
+    const given = { name: values.name };
+    for (const [flag, key] of [['harness', 'harness'], ['model', 'model'], ['effort', 'effort'], ['approval', 'approval'], ['prompt', 'prompt'], ['prompt-file', 'prompt_file']]) {
+      if (values[flag] !== undefined) given[key] = values[flag];
+    }
+    if (values.context !== undefined) given.context = asNumberOrText(values.context);
+    const made = await makeTemp(bots, { tab, ...given });
+    const { tabs, rules, skills, permissions, paused, projects } = made.up;
+    const answer = { bots, bot: made.bot, session: made.session, maker: made.maker, settings: made.settings, created: [], completed: [], rules, skills, permissions, tabs, paused, projects };
+    const retire = `${shellWord(ownCli())} temp retire --bots ${shellWord(bots)} --name ${made.session}`;
+    return {
+      answer,
+      lines: tabLines(answer, `Made ${made.bot}/${made.session}, a temporary session of ${made.maker}'s, working in work/${made.session}. Retire it when its work is done:  ${retire}`),
+    };
+  },
+
+  async 'temp retire'(bots, values) {
+    const tab = callerTab(bots, true);
+    refuseWhenOrcaIsDown();
+    const retired = await retireTemp(bots, { tab, name: values.name });
+    return {
+      answer: { bots, ...retired },
+      lines: [
+        ...closedLines(retired.closed),
+        `retired    ${retired.bot} ${retired.session}, a temporary session of ${retired.maker}'s: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+        ...leftLines(retired.promptsLeft),
       ],
     };
   },
@@ -618,10 +668,14 @@ const commands = {
     }
     // 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) {
@@ -662,9 +716,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(
@@ -826,11 +882,12 @@ const commands = {
   },
 
   'message send'(bots, values) {
+    const tab = callerTab(bots, values.from === undefined);
     refuseWhenOrcaIsDown();
     const answer = sendMessage(bots, {
       to: values.to,
       from: values.from,
-      tab: process.env[TAB_ENV],
+      tab,
       subject: values.subject,
       text: values.text,
       textFile: values['text-file'],
@@ -859,11 +916,13 @@ const commands = {
   },
 
   'message check'(bots, values) {
+    // Named or not, the mail is read as the caller's own terminal when it has one.
+    const tab = callerTab(bots, values.bot === undefined || process.env[TERMINAL_ENV] !== undefined);
     refuseWhenOrcaIsDown();
     const answer = checkMail(bots, {
       bot: values.bot,
       session: values.session,
-      tab: process.env[TAB_ENV],
+      tab,
       peek: values.peek === true,
     });
     const where = `${answer.bot}/${answer.session}`;
@@ -967,6 +1026,12 @@ function toLines(answer, bots, where) {
  * about the message.
  */
 function nudgeLine(answer, where) {
+  if (answer.nudged && answer.nudgeWatched === false) {
+    return `             its tab was typed into, and Orca could not say whether it was taken: ${answer.nudgeUnseen} The message waits in its mailbox for its next check either way.`;
+  }
+  if (answer.nudged && answer.nudgeUnseen !== undefined) {
+    return '             its tab was typed into, but Orca did not see the line start a turn: it may be queued behind the work in hand, or lost. The message waits in its mailbox for its next check either way.';
+  }
   if (answer.nudged) return '             its tab was told to look; it will read it when it is done with what it is doing.';
   if (answer.blocked !== undefined) {
     return `             its tab has something waiting to be answered (${answer.blocked}), so nothing was typed into it. Settle that, and the mail is there.`;
@@ -1004,11 +1069,33 @@ function settingsOf(values) {
   return settings;
 }
 
+/** The tabs a command closed, one line each. */
+const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab.name}  tab ${tab.tabId}  terminal ${tab.terminal}`);
+
+/** What a retire could not remove, and how to: nothing reads these files now (#393). */
+const leftLines = (left = []) => left.flatMap(({ file, reason }) => [
+  `left       ${file}: it could not be removed (${reason}). Nothing reads it now.`,
+  `           Remove it with:  rm ${shellWord(file)}`,
+]);
+
 /** A context window written as a plain number stays one in the file. */
 const asNumberOrText = (value) => (/^\d+$/.test(value) ? Number(value) : value);
 
 const oneLine = (value) => (Array.isArray(value) ? value.join(' ') : String(value)).replace(/\s+/g, ' ').trim();
 
+/**
+ * The Orca tab this command runs in, with the caller taken to be the session
+ * there only once sessionInTab has shown it is, when the command takes its
+ * caller from the tab (#408). Asked before Orca is: a Codex that Orca brought
+ * back by itself may run in a sandbox that cannot reach Orca at all, and
+ * "Orca is not ready" would send its user the wrong way.
+ */
+function callerTab(bots, takesCaller) {
+  const tab = process.env[TAB_ENV];
+  if (takesCaller && tab !== undefined) sessionInTab(bots, tab);
+  return tab;
+}
+
 function refuseWhenOrcaIsDown() {
   const trouble = orcaTrouble();
   if (trouble !== undefined) throw new Error(trouble);
@@ -1258,6 +1345,7 @@ function sessionLines(session) {
     ...(book.tab === undefined
       ? []
       : [`             tab ${book.tab}${book.launched === undefined ? '' : `  launched ${book.launched}`}`]),
+    ...(book.temporary === undefined ? [] : [`             temporary, made by ${book.temporary.maker}${book.temporary.made === undefined ? '' : ` at ${book.temporary.made}`}`]),
     ...(book.session === undefined ? [] : [`             conversation ${book.session}`]),
     ...(book.history ?? [])
       .filter((was) => was?.session !== undefined)

package/src/conversations.js

@@ -50,9 +50,16 @@ 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.

package/src/health.js

@@ -281,7 +281,11 @@ function runningOn(bots, home, bot, book, handles, sessions) {
       // see may still match, by the harness's own defaults; the rest of what
       // bot.yaml asks for is not on it either way.
       const drift = off.length === 0 ? '' : ` ${parts}, as the harness's own record of its conversation ${conversation} says.`;
-      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} was not started by the kit: the harness in its tab ${entry.tab} carries nothing of the kit's launch line, as when Orca brings its tabs back by itself after a restart or an update. So it runs on the harness's own defaults and whatever Orca added, not on what ${path.join(home, 'bot.yaml')} asks for.${drift} ${restart} starts it on bot.yaml.`, bot.name));
+      // A Codex brought back this way also runs its commands in Codex's shared
+      // background server, under whichever tab started it (#408).
+      const daemon = harness !== 'codex' ? '' : ` Without the kit's line it also runs without --no-daemon, so its commands run in Codex's shared background server, under the tab of whichever session started that server: another tab's identity, not its own. So the kit refuses its commands that take the caller from its tab, such as reading its mail.`;
+      const held = harness !== 'codex' ? '' : ` If Codex then shows "This conversation is open in another app", Codex's shared background server still holds the conversation, and it can outlive the session that started it: once every such session is back on the kit's line, stop the server with Codex's own \`codex app-server daemon stop\`, then restart this session again. That stops the server for everything using it, Codex sessions outside the kit included, so first check that nothing else needs it.`;
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} was not started by the kit: the harness in its tab ${entry.tab} carries nothing of the kit's launch line, as when Orca brings its tabs back by itself after a restart or an update. So it runs on the harness's own defaults and whatever Orca added, not on what ${path.join(home, 'bot.yaml')} asks for.${drift}${daemon} ${restart} starts it on bot.yaml.${held}`, bot.name));
     } else if (off.length > 0) {
       found.push(finding('session', file, `${bot.name}'s session ${session.name} does not run on what ${path.join(home, 'bot.yaml')} asks for. ${parts}. That is what the harness's own record of its conversation ${conversation} says. A session takes these when it starts, so if bot.yaml changed after it started, ${restart} starts it on them; if not, something else set them, such as a default of the harness's own or a change made inside the session.`, bot.name));
     }

package/src/init.js

@@ -86,8 +86,9 @@ charter: |
   Good looks like: every bot has a charter its owner recognises, the skills it
   needs and no more, and sessions that come back after a restart.
 
-  Ask first before: retiring a bot or a session, restarting anything, or
-  changing a bot's rules in a way its owner did not ask for.
+  Ask first before: retiring a bot or a long-lived session, restarting
+  anything, or changing a bot's rules in a way its owner did not ask for. A
+  temporary session is its maker's to retire, without asking.
 
   When the kit itself goes wrong (an obk command fails in a way its own message
   does not explain, or does something other than what it says), tell your owner

package/src/launch.js

@@ -51,7 +51,7 @@ export const harnessOf = (session, botHarness) => (set(session.harness) ? sessio
 
 /**
  * A session's name on Claude Code, which is also the address another Claude
- * session writes to (ADR 0018). It goes on the launch line as `-n`, and it is
+ * session writes to (ADR 0030). It goes on the launch line as `-n`, and it is
  * re-applied every time the session is started: a resume keeps the name by
  * itself (tech notes, section 2), and the kit does not depend on that.
  *
@@ -224,7 +224,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
 
   if (harness === 'claude') {
     // The name is the address other Claude sessions write to, so it goes on
-    // every launch line, a resume included (ADR 0018).
+    // every launch line, a resume included (ADR 0030).
     if (address !== undefined) words.push('-n', address);
     // The context window rides on the model name: `sonnet[1m]`.
     if (set(session.model)) words.push('--model', set(session.context) ? `${session.model}[${session.context}]` : session.model);

package/src/message.js

@@ -1,4 +1,4 @@
-// `obk message`: one session writing to another (PRD 6.9, ADR 0018).
+// `obk message`: one session writing to another (PRD 6.9, ADR 0030).
 //
 // Two roads, and the bot never picks. Claude to Claude in the same approval
 // class is the harness's own messaging, which no command line can send for it —
@@ -20,7 +20,7 @@ import path from 'node:path';
 
 import { MAILBOX_WAIT_MS, readBook, takeMailboxTurn } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
-import { harnessOf, isAddressOf, ownCli, reachesMail, shellWord } from './launch.js';
+import { harnessOf, isAddressOf, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
 import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, typeIntoTab, useMailbox } from './orca.js';
 
 /**
@@ -360,17 +360,37 @@ function whoIsWriting(bots, sender, tab, asked = '--from <bot>/<session>: which
   return found;
 }
 
-/** The session the book says is in this Orca tab, wherever in the fleet it is. */
-function sessionInTab(bots, tab) {
+/**
+ * The session the book says is in this Orca tab, wherever in the fleet it is,
+ * when the caller is that session.
+ *
+ * A Codex session is the caller only when the kit's launch line started the
+ * Codex it runs under: `shell` is the mark that line leaves, and everything the
+ * harness runs inherits it. A Codex that Orca brought back by itself has no
+ * mark and no `--no-daemon`, so it runs its commands in Codex's shared
+ * background server, whose every process carries the tab of whichever session
+ * started it (#408). Its tab then says nothing about who is asking. Inside
+ * Codex's sandbox `ps` does not run, so the environment is all there is to go
+ * on. A Claude session has no such server, and one Orca brought back is still
+ * the session in its tab.
+ */
+export function sessionInTab(bots, tab, shell = process.env[SHELL_ENV]) {
   for (const name of botNames(bots)) {
     const book = readBook(botDir(bots, name));
     for (const [session, entry] of Object.entries(book.sessions)) {
-      if (entry?.tab === tab) return findSession(bots, `${name}/${session}`);
+      if (entry?.tab !== tab) continue;
+      const found = findSession(bots, `${name}/${session}`);
+      if (found.harness === 'codex' && (shell === undefined || shell === '')) throw new Error(notTheCodexInTab(found, tab));
+      return found;
     }
   }
   return undefined;
 }
 
+/** Why a caller in a Codex session's tab is not taken to be that session, and what puts it right. */
+const notTheCodexInTab = (found, tab) =>
+  `this command takes its caller from the Orca tab it runs in, ${tab}, which is ${found.bot}/${found.session}'s, a Codex session; but it did not come from a Codex the kit started there: nothing of the kit's launch line is in its environment. A Codex that Orca brought back by itself, after a restart or an update, runs its commands in Codex's shared background server, under the tab of whichever session started that server, so the kit cannot tell which session is asking. Nothing was done. \`${shellWord(ownCli())} restart --bots ${shellWord(found.bots)} --bot <bot> --session <name>\` starts each such session on the kit's line; \`${shellWord(ownCli())} health --bots ${shellWord(found.bots)}\` names them. If Codex then shows "This conversation is open in another app", Codex's shared background server still holds that conversation, and it can outlive the session that started it: once every such session is back on the kit's line, stop the server with Codex's own \`codex app-server daemon stop\`, then restart the stuck session again. That stops the server for everything using it, Codex sessions outside the kit included, so first check that nothing else needs it.`;
+
 /**
  * The message as it will travel: the text itself when it is short enough, and
  * otherwise a file beside the bots folder with a body that names it.
@@ -442,11 +462,19 @@ function nudge(to, from, subject) {
     if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure };
     if (found.handle === undefined) return { nudged: false };
 
-    typeIntoTab(
+    const sent = typeIntoTab(
       found.handle,
       `Fleet mail from ${from.bot}/${from.session}: ${subject}. Read it with  ${shellWord(ownCli())} message check --bots ${shellWord(to.bots)} --bot ${shellWord(to.bot)} --session ${shellWord(to.session)}`,
+      { watch: true },
     );
-    return { nudged: true };
+    // Typed is not taken. A harness busy with a turn queues the line and gives
+    // it no turn of its own, and a line can be lost, and Orca's receipt looks
+    // the same for both: only a turn start it saw says the line landed (#394).
+    if (sent?.send?.prompt?.stages?.includes('turn_started')) return { nudged: true };
+    // Where Orca did not watch the line at all, as when its own notice has
+    // just started a turn in the tab, it saw nothing either way, and says so.
+    if (sent?.send?.prompt?.observation === 'unsupported') return { nudged: true, nudgeUnseen: unseen(sent), nudgeWatched: false };
+    return { nudged: true, nudgeUnseen: unseen(sent) };
   } catch (error) {
     // The message is already queued, and it is waiting whatever Orca says
     // about the tab. So this is reported rather than thrown: a send that ends
@@ -457,6 +485,14 @@ function nudge(to, from, subject) {
   }
 }
 
+/** Orca's words about a line it did not see start a turn, or what its receipt says when it gives none. */
+function unseen(sent) {
+  const warnings = Array.isArray(sent?.warnings) ? sent.warnings.filter((warning) => typeof warning === 'string') : [];
+  if (warnings.length > 0) return warnings.join(' ');
+  const stages = sent?.send?.prompt?.stages;
+  return `Orca's receipt shows ${Array.isArray(stages) ? stages.join(', ') : 'no stages'} and no turn start`;
+}
+
 /**
  * The look before the nudge. Orca now and then refuses a handle it has just
  * listed as stale, and a fresh listing hands out one that works (tech notes,

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;
 
@@ -579,20 +584,28 @@ export const closeTab = (handle) =>
  * The wait is short because the caller is telling a session it has mail, not
  * handing it work: mail that has to wait for the next check is a smaller cost
  * than a command that hangs for half a minute.
+ *
+ * With `watch`, the line is sent with that wait from the start, and Orca's
+ * receipt says whether it saw the line start a turn (#394). It gives back
+ * Orca's `result`: the receipt is in its `send.prompt`, and Orca's words about
+ * a turn it did not see in its `warnings`.
  */
-export function typeIntoTab(handle, text) {
+export function typeIntoTab(handle, text, { watch = false } = {}) {
   const args = ['terminal', 'send', '--terminal', handle, '--text', text, '--enter'];
-  const answer = ask(args);
-  if (answer.ok === true) return answer.result.send;
+  const answer = ask(watch ? [...args, '--wait-submit', String(SUBMIT_WAIT_S)] : args);
+  if (answer.ok === true) return answer.result;
 
   const again = answer.error?.data?.orchestrationRequestId;
   if (answer.error?.code !== 'agent_prompt_blocked' || typeof again !== 'string') {
     throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
   }
-  return orca([...args, '--retry-request', again, '--wait-submit', String(SUBMIT_WAIT_S)]).send;
+  return orca([...args, '--retry-request', again, '--wait-submit', String(SUBMIT_WAIT_S)]);
 }
 
-/** How long a re-issued line is given to be submitted before Orca gives up on it. */
+/**
+ * How long a watched or re-issued line is given to be submitted before Orca
+ * gives up on it. An idle harness started its turn in about 2 s, live (#394).
+ */
 const SUBMIT_WAIT_S = 5;
 
 /** Where Orca names the terminal a process runs in, in every pane it opens. */

package/src/permissions.js

@@ -19,7 +19,7 @@
 // `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 { accessSync, constants, 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';
@@ -267,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 };
@@ -279,30 +279,55 @@ 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 };
+    },
+  };
 }
 
 /**
@@ -358,7 +383,7 @@ export function takeBack(bots, home, bot, rules) {
       entries.push({ bot: bot.name, file, written: [], removed, waiting: waitingFor(bots, home, after, 'claude') });
     }
     if (runsOnCodex(after)) {
-      const entry = writeCodex(bots, home, 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) => {
@@ -371,12 +396,20 @@ export function takeBack(bots, home, bot, rules) {
   };
 }
 
-/** A refusal, before anything is written, of a file the kit could not write. */
+/**
+ * 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 {
-    accessSync(file, constants.W_OK);
+    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) {
-    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.`);
+    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.`);
   }
 }
 
@@ -417,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 = [
@@ -434,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/retire.js

@@ -9,12 +9,15 @@
 // What goes is what the kit made for it: its tabs, closed one at a time by
 // their own handles; its Orca project, after the tabs and never before; its
 // start-prompt files beside the bots folder; and, for a bot, the skill links
-// the kit made in its folder. A tab the book does not name is the user's, so a
+// the kit made in its folder. A prompt file that cannot be removed, as under a
+// harness's sandbox that may not write beside the bots folder, does not stop a
+// retire halfway: nothing reads it once its session is gone, so the retire
+// finishes and names it, with how to remove it (#393). A tab the book does not name is the user's, so a
 // bot whose project holds one is not retired until they have dealt with it.
 //
 // Closing a tab here ends the conversation in it on purpose, so unlike a
 // restart or a pause it does not wait for the book to know which one it was.
-// The mailbox Runs stay: Orca has no way to remove one (ADR 0018).
+// The mailbox Runs stay: Orca has no way to remove one (ADR 0030).
 
 import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import path from 'node:path';
@@ -31,7 +34,8 @@ import { promptPath, sessionsOf } from './up.js';
 export const retiredDir = (bots) => path.join(bots, 'retired');
 
 /**
- * Retire the session `session` of the bot `bot`. Returns `{ bot, session, closed }`.
+ * Retire the session `session` of the bot `bot`. Returns `{ bot, session,
+ * closed }`, and `promptsLeft` when its prompt file could not be removed.
  */
 export async function retireSession(bots, { bot, session }) {
   const home = fleetMember(bots, bot, 'retire', session);
@@ -47,15 +51,16 @@ export async function retireSession(bots, { bot, session }) {
     delete book.sessions[session];
     book.retired = [...(Array.isArray(book.retired) ? book.retired : []), { name: session, ...entry, retired: at }];
   });
-  rmSync(promptPath(bots, bot, session), { force: true });
+  const left = removePrompts([promptPath(bots, bot, session)]);
 
-  return { bot, session, closed };
+  return { bot, session, closed, ...left };
 }
 
 /**
  * Retire the bot `bot`. Returns `{ bot, closed, project, windowReloaded, moved }`:
  * the tabs it closed, the Orca project it took away (if it had one), whether
- * Orca's window was reloaded after that, and where the bot is now.
+ * Orca's window was reloaded after that, and where the bot is now; and
+ * `promptsLeft` when a prompt file could not be removed.
  * When Orca does not confirm the project gone, it returns `{ bot, closed,
  * project, trouble }` instead, and the bot is left where it was.
  */
@@ -103,12 +108,28 @@ export async function retireBot(bots, { bot }) {
     windowReloaded = reloadWindow();
   }
 
-  for (const name of new Set([...known.sessions, ...booked].map((session) => session.name))) {
-    rmSync(promptPath(bots, bot, name), { force: true });
-  }
+  const names = new Set([...known.sessions, ...booked].map((session) => session.name));
+  const left = removePrompts([...names].map((name) => promptPath(bots, bot, name)));
   unlinkSkills(home);
   mkdirSync(retiredDir(bots), { recursive: true });
   renameSync(botDir(bots, bot), moved);
 
-  return { bot, closed, ...(project === undefined ? {} : { project: project.id, windowReloaded }), moved };
+  return { bot, closed, ...(project === undefined ? {} : { project: project.id, windowReloaded }), moved, ...left };
+}
+
+/**
+ * Remove start-prompt files, and say which could not be: `{ promptsLeft: [{
+ * file, reason }] }`, or nothing when every one went. One that is not there is
+ * nothing to remove.
+ */
+function removePrompts(files) {
+  const promptsLeft = files.flatMap((file) => {
+    try {
+      rmSync(file, { force: true });
+      return [];
+    } catch (error) {
+      return [{ file, reason: error.message }];
+    }
+  });
+  return promptsLeft.length === 0 ? {} : { promptsLeft };
 }

package/src/temp.js

@@ -0,0 +1,173 @@
+// `obk temp make` and `obk temp retire`: a session's own temporary sessions
+// (PRD 6.4, #227).
+//
+// Any long-lived session can make a temporary session of its own bot for a
+// piece of work, and retire it when the work is done, without Bot Father, who
+// stays the manager of long-lived sessions. A temporary session is an ordinary
+// session in every other way: in bot.yaml, brought up with a tab and a mailbox,
+// its conversations kept in the book. What makes it temporary is one field of
+// its book entry, `temporary: { maker, made }`, and the book is the one place
+// that says so (ADR 0012).
+//
+// The caller is the session whose tab this runs in, as the book records it: the
+// tab says who is calling now. The maker is kept by its session name, not its
+// tab, so it still owns what it made after a restart gives it a new tab.
+//
+// Everything that can refuse is checked before anything is written, so a
+// refusal leaves bot.yaml, the book and Orca as they were. The one write that
+// may fall outside what a harness's sandbox lets a session write, its start
+// prompt's file beside the bots folder, is made first, the way #383 puts the
+// risky write before bot.yaml: refused there, nothing else has changed, and the
+// same command run again with that access goes through.
+
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { readBook, updateBook } from './book.js';
+import { addSession, dropSession, NAME, readBot } from './bot.js';
+import { isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
+import { sessionInTab } from './message.js';
+import { retireSession } from './retire.js';
+import { bringUp, promptPath } from './up.js';
+
+/** The settings a temporary session takes from its maker unless told otherwise. */
+const INHERITED = ['model', 'effort', 'context', 'approval'];
+
+/**
+ * Make a temporary session of the caller's own bot and bring it up. `given`
+ * holds what the caller said: `name`, `prompt` or `prompt_file`, and any of
+ * `harness` and the inherited settings. Returns `{ bot, session, maker,
+ * settings, up }`, where `up` is what bringing it up answered.
+ */
+export async function makeTemp(bots, { tab, ...given }) {
+  const caller = callerIn(bots, tab, 'make');
+  if (caller.temporary !== undefined) {
+    throw new Error(`${caller.bot}/${caller.session} is a temporary session, and only a long-lived session makes one. Nothing was made.`);
+  }
+  // The name is a folder under work/ and a file beside the bots folder, so it
+  // is held to the rule a bot's name is: one plain name, never a path.
+  if (!NAME.test(given.name)) {
+    throw new Error(`${given.name} cannot be a session's name: a name is lower-case letters, digits and single hyphens, such as review-250. Nothing was made.`);
+  }
+  if (given.prompt === undefined && given.prompt_file === undefined) {
+    throw new Error(`temp make needs the task: --prompt <text> or --prompt-file <path>. Nothing was made.`);
+  }
+  if (given.prompt !== undefined && given.prompt_file !== undefined) {
+    throw new Error(`temp make was given the task twice, as --prompt and as --prompt-file, and a session is told its duty once. Give it one way. Nothing was made.`);
+  }
+
+  const bot = readBot(caller.home, caller.bot);
+  const maker = bot.sessions.find((session) => session.name === caller.session);
+  const settings = { name: given.name };
+  const harness = given.harness ?? maker?.harness;
+  if (harness !== undefined) settings.harness = harness;
+  for (const field of INHERITED) {
+    const value = given[field] ?? maker?.[field];
+    if (value !== undefined) settings[field] = value;
+  }
+  if (given.prompt !== undefined) settings.prompt = given.prompt;
+  else settings.prompt_file = given.prompt_file;
+  settings.work_dir = `work/${given.name}`;
+
+  const written = bot.sessions.some((session) => session.name === given.name) ? undefined : writePromptFirst(bots, caller, settings);
+  // Refuses a name the bot already has, and a setting that will not work,
+  // before it writes anything; the prompt written first goes with a refusal.
+  let added;
+  try {
+    added = addSession(bots, caller.bot, settings);
+  } catch (error) {
+    if (written !== undefined) rmSync(written, { force: true });
+    throw error;
+  }
+  const made = new Date().toISOString();
+  try {
+    await updateBook(caller.home, (book) => {
+      book.sessions[given.name] = { ...book.sessions[given.name], temporary: { maker: caller.session, made } };
+    });
+  } catch (error) {
+    // A session in bot.yaml that the book does not call temporary would be a
+    // long-lived one to everything that reads it, its maker's retire included,
+    // so it is taken back off rather than left that way.
+    const failed = `${caller.bot}/${given.name} could not be recorded in the book as temporary (${error.message})`;
+    try {
+      dropSession(bots, caller.bot, given.name);
+    } catch (undo) {
+      throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}`);
+    }
+    // Off bot.yaml, nothing is made; a prompt file that stays is only a file,
+    // and nothing reads it (#393).
+    try {
+      if (written !== undefined) rmSync(written, { force: true });
+    } catch (left) {
+      throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
+    }
+    throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Run this again once the book can be written.`);
+  }
+
+  let up;
+  try {
+    up = await bringUp(bots, { bot: caller.bot, session: given.name });
+  } catch (error) {
+    const cli = shellWord(ownCli());
+    throw new Error(`${caller.bot}/${given.name} is made, in bot.yaml and in the book as temporary with its maker ${caller.session}, and could not be brought up: ${error.message} Bring it up with  ${cli} up --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}  or retire it with  ${cli} temp retire --bots ${shellWord(bots)} --name ${given.name}`);
+  }
+  return { bot: caller.bot, session: given.name, maker: caller.session, settings: added.session, up };
+}
+
+/**
+ * Write the start prompt's file where bringing the session up will write it,
+ * when its prompt goes to the harness out of a file at all, and say where. A
+ * prompt that cannot be read yet is left to `addSession`, which refuses it in
+ * its own words.
+ */
+function writePromptFirst(bots, caller, settings) {
+  let prompt;
+  try {
+    prompt = startPrompt(settings, { home: caller.home, workDir: workDirOf(settings, caller.home) });
+  } catch {
+    return undefined;
+  }
+  if (isShortPrompt(prompt)) return undefined;
+
+  const file = promptPath(bots, caller.bot, settings.name);
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, prompt);
+  } catch (error) {
+    throw new Error(`${caller.bot}/${settings.name}'s start prompt could not be written to ${file} (${error.message}), and it is written first, so nothing was made. Run this again where that folder can be written: from a harness's sandbox, with the access to write it.`);
+  }
+  return file;
+}
+
+/**
+ * Retire a temporary session the caller made. Returns what `retireSession`
+ * does, with the maker.
+ */
+export async function retireTemp(bots, { tab, name }) {
+  const caller = callerIn(bots, tab, 'retire');
+  const bot = readBot(caller.home, caller.bot);
+  if (!bot.sessions.some((session) => session.name === name)) {
+    throw new Error(`${caller.bot} has no session called ${name}, so there is nothing of yours to retire. Nothing was retired.`);
+  }
+  const temporary = readBook(caller.home).sessions[name]?.temporary;
+  if (temporary === undefined) {
+    throw new Error(`${caller.bot}/${name} is a long-lived session, and those are Bot Father's to retire. Nothing was retired.`);
+  }
+  if (temporary.maker !== caller.session) {
+    throw new Error(`${caller.bot}/${name} is a temporary session ${temporary.maker} made, not ${caller.session}, so it is ${temporary.maker}'s to retire. Nothing was retired.`);
+  }
+  return { ...(await retireSession(bots, { bot: caller.bot, session: name })), maker: caller.session };
+}
+
+/**
+ * The session this runs in, as the book knows it, with its home and whether it
+ * is itself temporary.
+ */
+function callerIn(bots, tab, what) {
+  const found = tab === undefined ? undefined : sessionInTab(bots, tab);
+  if (found === undefined) {
+    throw new Error(`temp ${what} is run by a session in its own tab, and this is not one of the fleet's tabs, so there is no session here to ${what} it for. Nothing was done.`);
+  }
+  const entry = readBook(found.home).sessions[found.session] ?? {};
+  return { bot: found.bot, session: found.session, home: found.home, temporary: entry.temporary };
+}

package/src/usage.js

@@ -25,6 +25,9 @@
 //      `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
@@ -40,7 +43,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 
 import { botDir, botNames, readBot } from './bot.js';
 import { readBook, sessionIdsIn } from './book.js';
-import { claudeSubagentTranscripts, transcriptsIn } from './conversations.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. */
@@ -193,7 +196,10 @@ function counted(one, window) {
       return { entries, subagent: index > 0 };
     });
   if (one.harness === 'claude') fromClaude(sources, window, tally);
-  else fromCodex(sources[0].entries, 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: {
@@ -351,13 +357,22 @@ const CODEX_FIELDS = [
  * 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 ?? '');
@@ -381,10 +396,26 @@ function fromCodex(entries, window, tally) {
     if (info === undefined || info === null) continue;
 
     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;
     // 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)) {
+    if (unknown && complete(total, CODEX_READ)) {
+      used = null;
+      running = total;
+      broken = false;
+    } else if (!complete(total, CODEX_READ)) {
       used = null;
       broken = true;
     } else {
@@ -412,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;