@assuredloop/orca-bot-kit 0.10.0 → 0.11.0

package/README.md

@@ -543,6 +543,14 @@ runs `obk session mailbox` before the harness. For the same reason a session's
 mail is read in its own tab. `message check` from any other tab reads nothing,
 binds nothing, and says so; the mail waits.
 
+For one session, that step, a `message check`, and `up` writing a new tab for it
+into the book take turns. So two starts of the same session at once leave its
+mailbox bound to the tab the book names, and no mail is read in the other one.
+Each waits a minute at most for its turn. A step that waits it out leaves the
+mailbox where it was and says so, and the harness starts all the same. A check
+holds its turn for 40 seconds at most: with more mail than it reads in that
+time, it shows what it read and says the rest is still waiting.
+
 Nothing in a mailbox wakes anybody, so `message send` also types one line into
 the receiver's tab telling it to look. Both harnesses take a typed line as the
 next thing to do rather than cutting into what they are doing, which is the

package/SETUP.md

@@ -191,19 +191,21 @@ What you will see, and the usual answer. Each goes as one
 text and **no** `--enter`, because a menu takes a return as the keypress it is
 waiting for:
 
-| On screen | Send | Which is |
-|---|---|---|
-| Claude Code's folder trust list | `\x1b[B\r` | down, then return: its selection starts on **No, exit** |
-| Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `1\r` | yes |
-| Codex's `Hooks need review` | `2\r` | trust all and continue |
-| Codex's `/new`: `Where should the new conversation run?` | `1\r` | current checkout (bot home) |
-| Codex's update offer, `1. Update now` | `1\r` | accept it |
-| `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell |
-| Claude Code's `Teach auto mode about your environment?` | `2\r` | **Not now**: it would write settings of theirs |
-
-The numbers there are what these menus showed when this was written. Read them
-off the screen in front of you rather than trusting the table: a harness that has
-added an option since has moved them all down one.
+| 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.157.1 |
+| 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.157.1 |
+| Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home) | Codex 0.157.1 |
+| Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; 0.157.1 has had no newer release to offer |
+| `[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 is **Not now**: it would write settings of theirs | Not yet proven: Esc is Not now in Claude Code 2.1.283's code; last seen live on 2.1.278, answered with 2. Not now |
+
+Each key counts on where the selection starts, as it did on the version named.
+Read the screen in front of you before you send: if the selection is somewhere
+else, or the options have moved, go to the answer with the arrows and then
+return. Never send a digit and then return: on Codex's update offer that took
+the highlighted **Update now**, whatever the digit was.
 
 Three things to know rather than guess at.
 
@@ -215,8 +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 did not show it in the runs
-seen so far) is always answered with the current checkout, which is the bot
+Codex's `/new` question (seen on 0.156.1 and 0.157.1) 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.10.0",
+  "version": "0.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/rules/limits.md

@@ -17,6 +17,6 @@ publishing, releasing, spending money, anything another person receives.
 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 file 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 a settings file yourself, Bot Father included.
+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.

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

@@ -201,16 +201,38 @@ say that you edited it by hand.
 Run `obk --help` for the flags of the version actually installed rather than
 trusting a line you remember.
 
-A bot on Claude Code needs a few permission rules so that auto mode does not
-stop it for what the kit's own rules tell it to do: its mail through the kit,
-reading a long message kept beside the bots folder, and its commits. `obk bot
-create`, `obk up` and `obk rules build` list the rules still waiting for a bot
-and give one command that allows them. Show the user those rules word for word
-and say in a line what each lets the bot do. Run the command only after their
-yes: it records the yes in the bot's `bot.yaml` and writes the rules into its
-settings. On a no, run nothing, and nothing is written. When the kit lists new
-rules for a bot later, ask again. Never write a permission rule into a settings
-file by hand.
+A bot needs a few permission rules so that auto mode, or Codex's sandbox and
+reviewer, does not stop it for what the kit's own rules tell it to do: its
+mail through the kit, reading a long message kept beside the bots folder, and
+its commits. `obk bot create`, `obk up` and `obk rules build` list the rules
+still waiting for a bot and give one command that allows them. Show the user
+those rules word for word and say in a line what each lets the bot do. Run the
+command only after their yes: it records the yes in the bot's `bot.yaml` and
+writes the rules into its settings, or for Codex into its
+`.codex/rules/obk.rules`. On a no, run nothing, and nothing is written. When
+the kit lists new rules for a bot later, ask again. Never write a permission
+rule into a settings or rules file by hand.
+
+The charter decides what else the bot needs. What it lets the bot do without
+asking, such as merging pull requests, auto mode or Codex's sandbox can still
+stop, so each grant needs its own rule. When the charter is written, and again
+whenever it changes, list the exact rules it grants: `Bash(gh pr merge:*)` for
+a bot that merges pull requests, `Bash(gh issue close:*)` for one that closes
+issues. Spell each command as the bot will run it, the kit by the path the
+bot's rules give it and every folder absolute, or the rule will not match.
+Spell them in Claude Code's form for a Codex bot too, `Bash(<command>:*)`: the
+kit writes Codex's own form of each, and says which ones Codex has none for,
+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
+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
+bot's settings themselves. Propose no rule for what the charter does not grant.
 
 A bot that should learn across its sessions can use its harness's own memory,
 turned on for that bot alone, whatever the user's own setting is for everything
@@ -256,23 +278,31 @@ otherwise `/Applications/Orca.app/Contents/Resources/bin/orca`. A bare
 `orca` can fail. Send each answer as one `<orca> terminal send --terminal
 <handle> --text …`, with the return inside the text and no `--enter`:
 
-| On screen | Send | Which is |
-|---|---|---|
-| Claude Code's folder trust list | `\x1b[B\r` | down, return: it starts on **No, exit** |
-| Codex's `Trust this folder?`, `1. Trust and continue` | `1\r` | yes (older: `1. Yes, continue`) |
-| Codex's `Hooks need review` | `2\r` | trust all and continue |
-| Codex's `/new`: `Where should the new conversation run?` | `1\r` | current checkout (bot home) |
-| Codex's update offer, `1. Update now` | `1\r` | accept it |
-| `[oh-my-zsh] Would you like to update?` | `n` | no: the shell is the user's to update |
-| Claude Code's `Teach auto mode about…` | `2\r` | **Not now**: it writes the user's settings |
-
-Read the numbers off the screen in front of you rather than trusting the
-table: a harness that has added an option has moved them. Codex's hooks
+| 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.157.1 |
+| Codex's `Hooks need review` | `\x1b[B\r` | **Trust all and continue** | Codex 0.157.1 |
+| Codex's `Where should the new conversation run?` | `\r` | **Current checkout** | Codex 0.157.1 |
+| 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** | Not yet proven, below |
+
+Each key counts on where the selection starts on the version named. Read the
+screen before you send: if the selection is elsewhere or the options have
+moved, go to the answer with the arrows, then return. Never a digit and then
+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.
+0.157.1 has had no newer release to offer, so its update offer was proven on
+0.156.1. Claude Code's `Teach auto mode` has not been seen live on 2.1.283:
+Esc is Not now in its code, and 2.1.278 was answered with `2. Not now`.
+Not now, because Yes writes the user's settings. Codex's hooks
 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 did; 0.157.1 has not so far); the answer is
+conversation runs (0.156.1 and 0.157.1 both 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/book.js

@@ -6,7 +6,7 @@
 // theirs. Beside each session's tab it holds the harness session id that
 // session is running under, and every id it ran under before.
 
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { isDeepStrictEqual } from 'node:util';
@@ -141,18 +141,26 @@ export async function updateBook(home, change) {
  * empty and leaves no journal beside it.
  */
 function takeLock(home) {
-  const file = lockFile(home);
+  try {
+    return lockOn(lockFile(home), WAIT_MS);
+  } catch (error) {
+    throw waitedTooLong(home, error);
+  }
+}
+
+/** The lock on `file`, waited for `waitMs` at most: see `takeLock` for why it is this one. */
+function lockOn(file, waitMs) {
   mkdirSync(path.dirname(file), { recursive: true });
 
   const db = new DatabaseSync(file);
   try {
     // A writer that arrives while another is working waits for it rather than
     // failing at once, and gives up saying so rather than waiting for ever.
-    db.exec(`PRAGMA busy_timeout = ${WAIT_MS}`);
+    db.exec(`PRAGMA busy_timeout = ${waitMs}`);
     db.exec('BEGIN IMMEDIATE');
   } catch (error) {
     db.close();
-    throw waitedTooLong(home, error);
+    throw error;
   }
 
   return {
@@ -190,6 +198,54 @@ const lockFile = (home) => path.join(
   `${encodeURIComponent(path.basename(home))}.lock`,
 );
 
+/**
+ * One session's turn at its mailbox (#321): held by `session mailbox` for its
+ * whole step, by `message check` in the session's own tab for its bind, read and
+ * ack, and by `up` while it writes a new tab for the session into the book. So
+ * the book never moves to another tab while a step or a check is at work, and a
+ * step or check that waited reads the book again once it has its turn: two
+ * starts of one session at once leave its mailbox bound to the tab the book
+ * names, and nothing is read from the one it no longer does.
+ *
+ * A lock of its own, and not the book's: the book's is held for one read and one
+ * write, and a session's hook must never wait behind Orca for it. Taken before
+ * the book's and never while holding it, so neither waits on the other.
+ *
+ * Returns `{ release }`, or undefined when the turn did not come in
+ * `MAILBOX_WAIT_MS`: the caller says what it left, and a launch line goes on
+ * to its harness whatever happened here.
+ */
+export function takeMailboxTurn(home, session) {
+  try {
+    return lockOn(mailboxLockFile(home, session), MAILBOX_WAIT_MS);
+  } catch (error) {
+    if (error.errcode === SQLITE_BUSY) return undefined;
+    throw error;
+  }
+}
+
+/**
+ * How long a step, a check or an `up` waits for a session's turn. Longer than a
+ * step can hold it — three Orca calls of twenty seconds each at most — and short
+ * enough that a harness behind a stuck one still starts.
+ */
+export const MAILBOX_WAIT_MS = 60_000;
+
+/** SQLite's own code for a lock another connection holds. */
+const SQLITE_BUSY = 5;
+
+/**
+ * Beside the book's lock, one file per session. Names are lower-case letters,
+ * digits and hyphens, so a dot between the bot's and the session's cannot be
+ * read two ways. Resolved first, because the same bot is reached through a
+ * link by one command and by its real path by another, and two paths would be
+ * two turns.
+ */
+const mailboxLockFile = (home, session) => {
+  const real = realpathSync(home);
+  return path.join(`${path.dirname(path.dirname(real))}.locks`, `${path.basename(real)}.${session}.mailbox.lock`);
+};
+
 /**
  * Something else has been writing the book for longer than this run is prepared
  * to wait. Every writer holds its turn for one read and one write, so this is a

package/src/cli.js

@@ -19,7 +19,7 @@ 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, writePermissions } from './permissions.js';
+import { allowCommand, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -61,7 +61,8 @@ Usage:
                             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.
+                            Claude settings. A broad rule, such as Bash(gh:*),
+                            is refused and nothing is written.
   obk session change --bots <path> --bot <bot> --session <session>
                   [--model <m>] [--effort <e>] [--context <c>]
                   [--approval ${APPROVALS.join('|')}]
@@ -578,7 +579,7 @@ const commands = {
     const skills = [linkSkills(bots, made.home, readBot(made.home))];
     // Nothing is allowed yet, so this writes nothing: it says which of the
     // kit's rules wait for the user's yes (#344).
-    const permissions = [writePermissions(bots, made.home, readBot(made.home))].filter((entry) => entry !== undefined);
+    const permissions = writePermissions(bots, made.home, readBot(made.home));
     const answer = { bots, bot: made.bot, home: made.home, created: made.created, rules, skills, permissions };
     // A bot whose rules would not build is made but not finished: it has no
     // instructions, so `up` will not start it, and saying "give it a session"
@@ -608,7 +609,11 @@ const commands = {
     }
     // Refused before anything is written, so a bad rule, or a bad list already
     // there, leaves the charter as it was too.
-    if (values.allow !== undefined) allowedNow(bots, values.bot, values.allow);
+    if (values.allow !== undefined) {
+      const { home } = allowedNow(bots, values.bot, values.allow);
+      refuseBroad(home, values.allow);
+      refuseNoCodexForm(readBot(home, values.bot), values.allow);
+    }
 
     const answer = { bots, bot: values.bot, home: botDir(bots, values.bot) };
     const lines = [];
@@ -627,15 +632,33 @@ const commands = {
           ? `${changed.bot}'s charter is written, and its rules are not. Settle what the line above says, then:  ${shellWord(ownCli())} rules build --bots ${shellWord(bots)} --bot ${changed.bot}`
           : `${changed.bot}'s charter is changed. A session that is running read the old one when it started; it reads this one when it next starts.`,
       );
+      // The rules a charter grants are the user's to say yes to again, so the
+      // change names what is allowed now and writes none of it (#353).
+      // 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))) {
+        try {
+          answer.beyondDefaults = beyondDefaults(bots, changed.home, bot);
+          lines.push(...charterRulesLines(bots, bot, answer.beyondDefaults));
+        } catch {
+          // Nothing to name here.
+        }
+      }
     }
     if (values.allow !== undefined) {
       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))].filter((entry) => entry !== undefined);
+      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(
         ...allowed.added.map((rule) => `${'allowed'.padEnd(9)}  ${rule}`),
         ...permissionsLines(permissions, bots),
+        // Codex reads its rules when a session starts, not while it runs.
+        ...(codex === undefined || codex.written.length === 0 ? [] : [
+          `Codex reads ${codex.file} when a session starts: a Codex session of ${allowed.bot} that is running now gets these rules at its next start (obk restart).`,
+        ]),
         allowed.added.length === 0
           ? `${allowed.bot} was allowed every one of these already.`
           : `${allowed.bot}'s allow list in ${path.join('bots', allowed.bot, 'bot.yaml')} holds the user's yes.`,
@@ -812,19 +835,22 @@ const commands = {
       peek: values.peek === true,
     });
     const where = `${answer.bot}/${answer.session}`;
-
+    const messages = answer.messages.flatMap((message) => [
+      `${'message'.padEnd(9)}  ${message.from}  ${message.at}`,
+      `             ${message.subject}`,
+      ...String(message.body ?? '').split('\n').map((line) => `             ${line}`),
+    ]);
+
+    // Trouble after some mail was read still shows that mail: it is read, and
+    // Orca will not hand it over again.
     if (answer.trouble !== undefined) {
-      return { answer, lines: [`${'trouble'.padEnd(9)}  ${where}`, `             ${answer.trouble}`], code: 1 };
+      return { answer, lines: [...messages, `${'trouble'.padEnd(9)}  ${where}`, `             ${answer.trouble}`], code: 1 };
     }
 
     return {
       answer,
       lines: [
-        ...answer.messages.flatMap((message) => [
-          `${'message'.padEnd(9)}  ${message.from}  ${message.at}`,
-          `             ${message.subject}`,
-          ...String(message.body ?? '').split('\n').map((line) => `             ${line}`),
-        ]),
+        ...messages,
         answer.messages.length === 0
           ? `Nothing is waiting for ${where}.`
           // Said plainly, because a peek leaves the same mail there to be found
@@ -1220,12 +1246,26 @@ function permissionsOf(bots, name) {
   } catch {
     return [];
   }
-  try {
-    const entry = writePermissions(bots, home, bot);
-    return entry === undefined ? [] : [entry];
-  } catch (error) {
-    return [{ bot: name, file: path.join(home, '.claude', 'settings.json'), written: [], waiting: [], trouble: error.message }];
-  }
+  return writePermissions(bots, home, bot, { keepGoing: true });
+}
+
+/**
+ * What a charter change says about the permission rules: the ones the bot is
+ * allowed now beyond the kit's defaults, word for word, which stay allowed, and
+ * that a new one is written only after the user's yes to the new charter's.
+ */
+function charterRulesLines(bots, bot, rules) {
+  const name = bot.name;
+  const until = `No new rule is written until the user answers: list the rules the new charter grants, show them to the user word for word, and allow the ones they say yes to with  ${shellWord(ownCli())} bot change --bots ${shellWord(bots)} --bot ${shellWord(name)} --allow <rule>`;
+  if (rules.length === 0) return [`${name} is allowed no permission rules beyond the kit's defaults. ${until}`];
+  const settings = runsOnClaude(bot) ? ` and ${path.join('bots', name, '.claude', 'settings.json')}` : '';
+  // The kit owns the Codex file whole and rewrites it from bot.yaml (#354).
+  const codex = runsOnCodex(bot) ? `, and the kit then rewrites ${path.join(bots, 'bots', name, '.codex', 'rules', 'obk.rules')} without it` : '';
+  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}`,
+  ];
 }
 
 /**
@@ -1235,12 +1275,19 @@ function permissionsOf(bots, name) {
  * it (#344). Nothing for a bot with nothing written and nothing waiting.
  */
 function permissionsLines(permissions, bots) {
+  // A bot on both harnesses has an entry for each file, and what waits for
+  // Codex is also waiting for Claude: the rules are listed once, with the first.
+  const listed = new Set();
   return permissions.flatMap((entry) => [
     ...(entry.trouble === undefined ? [] : [`${'refused'.padEnd(9)}  ${entry.trouble}`]),
     ...(entry.written.length === 0
       ? []
       : [`${'wrote'.padEnd(9)}  ${path.relative(bots, entry.file)}  ${entry.written.length} permission rule${entry.written.length === 1 ? '' : 's'} the user allowed`]),
-    ...(entry.waiting.length === 0 ? [] : [
+    // What the user allowed and Codex has no form for is said at every build,
+    // so a bot given a Codex session later hears of it too (#354). For a bot
+    // only on Codex, `--allow` refused it already.
+    ...(entry.unwritten ?? []).map((one) => `${'not'.padEnd(9)}  written for Codex: ${one.rule}. ${one.why}.`),
+    ...(entry.waiting.length === 0 || listed.has(entry.bot) || !listed.add(entry.bot) ? [] : [
       `${'waiting'.padEnd(9)}  ${entry.bot}: these permission rules wait for the user's yes, and none of them is written until then:`,
       ...entry.waiting.map((rule) => `             ${rule}`),
       `             Show them to the user. Once they say yes:  ${allowCommand(bots, entry.bot, entry.waiting)}`,

package/src/message.js

@@ -18,10 +18,10 @@
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
-import { readBook } from './book.js';
+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 { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, typeIntoTab, useMailbox } from './orca.js';
+import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, typeIntoTab, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -186,10 +186,37 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
  * check hands over all of it (issue #299).
  */
 export function checkMail(bots, { bot: botName, session: sessionName, tab, peek = false }) {
-  const who = sessionName === undefined && botName === undefined
+  const asked = sessionName === undefined && botName === undefined
     ? whoIsWriting(bots, undefined, tab, '--bot <bot> [--session <name>]: whose mail to read')
     : findSession(bots, sessionName === undefined ? botName : `${botName}/${sessionName}`);
 
+  // The session's turn at its mailbox, so the book does not move to another tab
+  // between the bind and the last ack, and the book read again once it is had:
+  // a check that waited while `up` wrote a new tab reads nothing from the old
+  // one (#321).
+  const turn = takeMailboxTurn(asked.home, asked.session);
+  if (turn === undefined) {
+    return {
+      bots,
+      bot: asked.bot,
+      session: asked.session,
+      mailbox: asked.mailbox,
+      messages: [],
+      trouble: `waited ${MAILBOX_WAIT_MS / 1000} seconds for ${asked.bot}/${asked.session}'s mailbox while another obk was making, binding or reading it, and it did not finish. Nothing was read, and its mail is still waiting.`,
+    };
+  }
+  try {
+    return mailOf(bots, findSession(bots, `${asked.bot}/${asked.session}`), peek, Date.now() + HOLD_MS);
+  } finally {
+    turn.release();
+  }
+}
+
+/**
+ * What `checkMail` does once it has the session's turn, with `who` as the book
+ * says now, asking Orca nothing after `until`.
+ */
+function mailOf(bots, who, peek, until) {
   if (who.mailbox === undefined) {
     return {
       bots,
@@ -205,7 +232,7 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
   // every message after (issue #228). A session with no live tab is read as
   // whatever its mailbox is bound to, a closed tab included, and nothing is
   // bound: the session's tab is bound again when it is back up (issue #249).
-  const live = who.tab === undefined ? undefined : tabs(who.home).find((tab) => tab.tabId === who.tab)?.handle;
+  const live = who.tab === undefined ? undefined : tabs(who.home, timeLeft(until)).find((tab) => tab.tabId === who.tab)?.handle;
   // Orca 1.4.210 lets a process in a tab bind and read as that tab and no
   // other, and refuses the rest with nothing done (#317). So from inside any
   // other tab, the kit asks nothing and says where the mail can be read.
@@ -220,8 +247,8 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
       trouble: `${who.bot}/${who.session}'s mail can be read only in its own tab: Orca lets a tab bind and read its own mailbox and no other. Nothing was read, and its mail is still waiting.`,
     };
   }
-  if (live !== undefined) useMailbox(who.mailbox, live);
-  const handle = live ?? coordinatorOf(who.mailbox);
+  if (live !== undefined) useMailbox(who.mailbox, live, timeLeft(until));
+  const handle = live ?? coordinatorOf(who.mailbox, timeLeft(until));
   if (handle === undefined) {
     return {
       bots,
@@ -235,15 +262,60 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
   // Orca hands mail over a batch at a time and replays the oldest until it is
   // acknowledged; the acknowledgement answers with the next batch. So a read
   // takes every batch in turn, or newer mail waits behind an older one (#299).
+  //
+  // A batch is given back once it is acknowledged, and not before: one this
+  // check stops short of acknowledging is handed over again to the next.
   const messages = [];
-  let found = readMailbox(who.mailbox, { peek, handle });
+  const read = { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
+  let found = readMailbox(who.mailbox, { peek, handle }, timeLeft(until));
   for (;;) {
-    messages.push(...(found.messages ?? []).map((message) => asMessage(bots, message)));
-    if (peek || !found.deliveryId || (found.messages ?? []).length === 0) break;
-    found = ackMailbox(who.mailbox, found.deliveryId, handle);
+    const batch = (found.messages ?? []).map((message) => asMessage(bots, message));
+    if (peek || !found.deliveryId || batch.length === 0) {
+      messages.push(...batch);
+      return read;
+    }
+    const wait = timeLeft(until, false);
+    if (wait === undefined) {
+      return { ...read, trouble: `${who.bot}/${who.session} has more mail than one check reads in ${HOLD_MS / 1000} seconds, so it stopped there. The rest is still waiting: check again.` };
+    }
+    try {
+      found = ackMailbox(who.mailbox, found.deliveryId, handle, wait);
+    } catch (error) {
+      // An ack Orca did not answer about may have been taken all the same, and
+      // then this batch is never handed over again: it is shown, said to be
+      // uncertain, rather than lost (review of PR #368). One Orca refused was
+      // not taken, and waits for the next check.
+      if (error.code === TIMED_OUT) {
+        messages.push(...batch);
+        return { ...read, trouble: `${error.message} Orca did not answer whether it took the last ${batch.length === 1 ? 'message' : `${batch.length} messages`} shown above as read, so the next check may show ${batch.length === 1 ? 'it' : 'them'} again. The rest waits for the next check.` };
+      }
+      // What was acknowledged before this is gone from Orca, and would be lost
+      // to everyone if the failure took it down with it.
+      if (messages.length === 0) throw error;
+      return { ...read, trouble: `${error.message} The mail shown above is read, and the rest waits for the next check.` };
+    }
+    messages.push(...batch);
   }
+}
+
+/**
+ * How long a check holds the session's turn, all its Orca calls together. Well
+ * inside the minute `up` waits for the turn before it writes a new tab, so a
+ * check in the old tab is done before the book moves, however slow Orca is,
+ * and however much mail there is (review of PR #368).
+ */
+const HOLD_MS = 40_000;
 
-  return { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
+/**
+ * What one Orca call is given: twenty seconds, as the step gives its own, or
+ * what is left of the check's hold, in whole seconds. With none left, the
+ * call is refused here, or, when `refuse` is false, undefined is answered.
+ */
+function timeLeft(until, refuse = true) {
+  const left = Math.min(20_000, Math.floor((until - Date.now()) / 1000) * 1000);
+  if (left >= 1000) return { timeoutMs: left };
+  if (refuse) throw new Error(`the kit gives a mail check ${HOLD_MS / 1000} seconds of Orca's time, and Orca took them all. Nothing more was asked of it, and the mail is still waiting.`);
+  return undefined;
 }
 
 /** One message, in the kit's words rather than Orca's. */

package/src/orca.js

@@ -277,9 +277,9 @@ const RELOAD_SCRIPT = fileURLToPath(new URL('./orca-reload.applescript', import.
  * the real id, so an orphaned entry is given that one: the tab id is the key
  * (PRD 6.2), and this is where Orca is asked for it (tech notes, section 1).
  */
-export const tabs = (home) => orca(['terminal', 'list', '--worktree', `path:${home}`]).terminals
+export const tabs = (home, options) => orca(['terminal', 'list', '--worktree', `path:${home}`], options).terminals
   .map((tab) => (tab.orphaned === true
-    ? { ...tab, tabId: orca(['terminal', 'show', '--terminal', tab.handle]).terminal.tabId }
+    ? { ...tab, tabId: orca(['terminal', 'show', '--terminal', tab.handle], options).terminal.tabId }
     : tab));
 
 /**
@@ -645,12 +645,12 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
  * the terminal `handle` when one is given, which is how a read works from a tab
  * bound to another Run; otherwise as this process's own terminal.
  */
-export const readMailbox = (id, { peek = false, handle } = {}) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])]);
+export const readMailbox = (id, { peek = false, handle } = {}, options) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])], options);
 
 /** Say a batch has been read. Orca answers with the batch after it. */
-export const ackMailbox = (id, delivery, handle) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery]);
+export const ackMailbox = (id, delivery, handle, options) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery], options);
 
 /** The reader of a `check`: the terminal named, or this process's own. */
 const as = (handle) => (handle === undefined ? [] : ['--terminal', handle]);

package/src/permissions.js

@@ -13,8 +13,12 @@
 //
 // The kit owns only the entries `allow` holds. Any other entry in the file is
 // left where it is, and health names it.
+//
+// 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, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { leadsOutside } from './bot.js';
@@ -24,6 +28,10 @@ import { harnessOf, ownCli, shellWord } from './launch.js';
 /** Where Claude Code reads a project's settings, inside the bot home. */
 const FILE = '.claude/settings.json';
 
+/** Where Codex reads a trusted project's rules, and the one file of them the kit owns. */
+const CODEX_RULES = '.codex/rules';
+const CODEX_FILE = `${CODEX_RULES}/obk.rules`;
+
 /**
  * The rules every Claude bot is offered, in this order. The mail commands are
  * narrowed to this bots folder and spelled as the kit prints them in its
@@ -43,6 +51,134 @@ export function defaultRules(bots, cli = ownCli()) {
   ];
 }
 
+/** Command wrappers: programs that run the command their arguments name. */
+const WRAPPERS = new Set(['env', 'xargs', 'sudo', 'eval', 'exec', 'nohup', 'timeout', 'nice', 'command', 'time', 'watch']);
+
+/**
+ * Programs that run whatever their arguments tell them to: shells, interpreters
+ * and the wrappers above. With a wildcard after one of them, a rule lets the bot
+ * run any command, unless the next word fixes what runs by its absolute path.
+ */
+const RUNNERS = new Set([
+  'sh', 'bash', 'zsh', 'fish', 'dash', 'ksh', 'csh', 'tcsh',
+  'python', 'python2', 'python3', 'node', 'deno', 'bun', 'ruby', 'perl', 'php', 'osascript',
+  'npx', 'pnpx', 'bunx', 'uvx',
+  ...WRAPPERS,
+]);
+
+const ANY = 'it lets the bot run any command';
+
+/**
+ * Why a rule is broad, as the end of a sentence, or undefined for a narrow one
+ * (#353). A charter's grants are written as narrow, exact rules only; one that
+ * lets the bot run any command, a program with any arguments, or any file on
+ * the disk or in the home is the user's to add by hand (ADR 0027).
+ */
+export function broadness(rule) {
+  if (typeof rule !== 'string') return undefined;
+  const file = /^(Read|Edit|Write)(?:\((.*)\))?$/s.exec(rule);
+  if (file !== null) {
+    const spec = file[2] ?? '';
+    return spec === '' || /^(\/\/|~\/)[*/]*$/.test(spec) ? `it lets the bot ${file[1].toLowerCase()} any file` : undefined;
+  }
+  const bash = /^Bash(?:\((.*)\))?$/s.exec(rule);
+  if (bash === null) return undefined;
+  const { words, odd } = shellWords(bash[1] ?? '');
+  if (odd !== undefined) return `it holds ${odd}, which the shell reads specially, so the kit cannot tell what it runs`;
+  return commandBroadness(words);
+}
+
+/** What a word may hold outside quotes; anything else the shell reads specially. */
+const PLAIN = /[A-Za-z0-9\-_./:=@%+,^*]/;
+
+/**
+ * A Bash rule's command as the shell words it is, quotes taken off, or the
+ * first thing in it the shell reads specially: `{ words }` or `{ odd }`. Only
+ * plain words are judged, so an escape, an expansion or a second command can
+ * never hide which program runs.
+ */
+function shellWords(text) {
+  const words = [];
+  let word;
+  for (let at = 0; at < text.length; at += 1) {
+    const char = text[at];
+    if (char === ' ' || char === '\t') {
+      if (word !== undefined) words.push(word);
+      word = undefined;
+      continue;
+    }
+    word ??= '';
+    if (char === "'" || char === '"') {
+      const end = text.indexOf(char, at + 1);
+      if (end === -1) return { odd: `a ${char} that does not close` };
+      const inside = text.slice(at + 1, end);
+      const special = char === '"' ? /[$`\\]/.exec(inside) : null;
+      if (special !== null) return { odd: `the character ${special[0]}` };
+      word += inside;
+      at = end;
+    } else if (char === '\\' && text[at + 1] === "'") {
+      // An apostrophe outside quotes, the form shellWord gives one in a path.
+      word += "'";
+      at += 1;
+    } else if (PLAIN.test(char) || (char === '~' && word === '')) {
+      word += char;
+    } else {
+      return { odd: char === '\n' ? 'a newline' : `the character ${char}` };
+    }
+  }
+  if (word !== undefined) words.push(word);
+  return { words };
+}
+
+/** The shell or interpreter a program name is, with a version on its name or not. */
+const runnerOf = (name) => [name, name.replace(/[\d.]+$/, '')].find((one) => RUNNERS.has(one));
+
+/** Why a Bash rule's command, as shell words, is broad, or undefined. */
+function commandBroadness(all) {
+  // The program is the first word after any shell assignments in front of it.
+  let words = all;
+  while (words.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) words = words.slice(1);
+  if (words.length === 0) return ANY;
+  const star = words.findIndex((word) => word.includes('*'));
+  if (star === -1) return undefined;
+
+  const program = path.basename(words[0].replace(/:?\*.*$/, ''));
+  if (runnerOf(program) !== undefined) {
+    // Only what runs, fixed by its absolute path, narrows it. A wrapper's
+    // program is then judged by itself; an interpreter's script is the end.
+    const next = (words[1] ?? '').replace(/:\*$/, '');
+    const fixed = next.startsWith('/') && !next.includes('*');
+    if (fixed && WRAPPERS.has(program)) return commandBroadness(words.slice(1));
+    if (fixed && runnerOf(path.basename(next)) === undefined) return undefined;
+    return `${program} runs whatever its arguments say, so ${ANY}`;
+  }
+
+  // Two words at least before the first wildcard: a program and what it does.
+  const part = words[star].slice(0, words[star].indexOf('*')).replace(/:$/, '');
+  const before = star + (part === '' ? 0 : 1);
+  if (before === 0) return ANY;
+  if (before < 2) return `it lets the bot run ${words[0].replace(/:?\*.*$/, '')} with any arguments`;
+  return undefined;
+}
+
+/**
+ * Refuse the rules `--allow` was given when any is broad, before anything is
+ * written, naming the file the user can add it to themselves.
+ */
+export function refuseBroad(home, rules) {
+  for (const rule of rules) {
+    const why = broadness(rule);
+    if (why === undefined) continue;
+    throw new Error(`--allow ${rule} is broad: ${why}. The kit writes only narrow, exact rules, such as Bash(gh pr merge:*), so nothing was written. If the user wants this rule for ${path.basename(home)}, they add it to ${path.join(home, FILE)} themselves.`);
+  }
+}
+
+/** The rules the bot is allowed beyond the kit's defaults, in `allow`'s order. */
+export const beyondDefaults = (bots, home, bot) => {
+  const defaults = defaultRules(bots);
+  return allowOf(home, bot).filter((rule) => !defaults.includes(rule));
+};
+
 /** Whether any of a bot's sessions, or the bot itself, runs on Claude Code. */
 export const runsOnClaude = (bot) => bot.harness === 'claude'
   || bot.sessions.some((session) => harnessOf(session, bot.harness) === 'claude');
@@ -58,11 +194,64 @@ export function allowOf(home, bot) {
   return value;
 }
 
-/** The default rules this bot has not been allowed yet, in the default order. */
-export function waitingFor(bots, home, bot) {
-  if (!runsOnClaude(bot)) return [];
+/** Whether any of a bot's sessions, or the bot itself, runs on Codex. */
+export const runsOnCodex = (bot) => bot.harness === 'codex'
+  || bot.sessions.some((session) => harnessOf(session, bot.harness) === 'codex');
+
+/**
+ * The default rules this bot has not been allowed yet for one harness's file,
+ * in the default order. Codex is not offered the Read rule: its sandbox reads
+ * every file already.
+ */
+function waitingFor(bots, home, bot, harness) {
   const allowed = allowOf(home, bot);
-  return defaultRules(bots).filter((rule) => !allowed.includes(rule));
+  return defaultRules(bots)
+    .filter((rule) => harness === 'claude' || codexForm(rule).line !== undefined)
+    .filter((rule) => !allowed.includes(rule));
+}
+
+/**
+ * A rule's Codex form: `{ line }`, `{ needless: true }` for a Read rule, which
+ * Codex's sandbox does not need, or `{ why }` for a rule Codex has none for.
+ * Only a prefix of plain words has one; a prefix rule for one exact command
+ * would let the bot add any arguments the user did not say yes to.
+ */
+export function codexForm(rule) {
+  if (/^Read(\(.*\))?$/s.test(rule)) return { needless: true };
+  const bash = /^Bash\((.*)\)$/s.exec(rule);
+  if (bash === null) return { why: 'Codex has no rule for anything but a command, so its sandbox decides it' };
+  const { words, odd } = shellWords(bash[1]);
+  if (odd !== undefined) return { why: `Codex has no rule for it: it holds ${odd}` };
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0] ?? '')) {
+    return { why: 'Codex has no rule for a command with a variable set in front of it' };
+  }
+  if (!words.some((word) => word.includes('*'))) {
+    return { why: 'Codex has no rule for one exact command: its rules match a command\'s first words, whatever comes after them' };
+  }
+  // Only the wildcard comes off, ` *` or `:*` at the very end: every word
+  // before it stays, an empty quoted one included, or the rule would be looser
+  // than the one the user said yes to.
+  const text = bash[1].trimEnd();
+  const end = /(?: |:)\*$/.exec(text);
+  const prefix = end === null ? [] : shellWords(text.slice(0, end.index)).words;
+  if (prefix.length === 0 || prefix.some((word) => word.includes('*'))) {
+    return { why: 'Codex has no rule for a wildcard anywhere but at the end, as a word of its own or after a colon' };
+  }
+  return { line: `prefix_rule(pattern=[${prefix.map((word) => JSON.stringify(word)).join(', ')}], decision="allow")` };
+}
+
+/**
+ * Refuse the rules `--allow` was given for a bot that runs only on Codex when
+ * Codex has no form for one, before anything is written: recorded, it would
+ * let the bot do nothing.
+ */
+export function refuseNoCodexForm(bot, rules) {
+  if (runsOnClaude(bot) || !runsOnCodex(bot)) return;
+  for (const rule of rules) {
+    const { why } = codexForm(rule);
+    if (why === undefined) continue;
+    throw new Error(`--allow ${rule} is not for ${bot.name}: ${why}, and ${bot.name} runs only on Codex, so nothing was written.`);
+  }
 }
 
 /** The one command that allows `rules` for `bot`, as the user can run it. */
@@ -72,19 +261,34 @@ export const allowCommand = (bots, bot, rules) => [
 ].join(' ');
 
 /**
- * Write what the bot is allowed into its Claude settings, and say what waits:
- * `{ bot, file, written, waiting }`, with `written` the rules this run added.
- * Nothing for a bot that does not run on Claude.
+ * Write what the bot is allowed into the files of the harnesses it runs on, and
+ * say what waits: one entry per file, Claude's first. With `keepGoing`, a file
+ * 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]) => {
+    try {
+      return write(bots, home, bot);
+    } catch (error) {
+      if (!keepGoing) throw error;
+      return { bot: bot.name, file: path.join(home, file), written: [], waiting: [], trouble: error.message };
+    }
+  });
+}
+
+/**
+ * Write what the bot is allowed into its Claude settings: `{ bot, file,
+ * written, waiting }`, with `written` the rules this run 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.
  */
-export function writePermissions(bots, home, bot) {
-  if (!runsOnClaude(bot)) return undefined;
+function writeClaude(bots, home, bot) {
   const file = path.join(home, FILE);
   const allowed = allowOf(home, bot);
-  const waiting = waitingFor(bots, home, bot);
+  const waiting = waitingFor(bots, home, bot, 'claude');
   const answer = { bot: bot.name, file, written: [], waiting };
   if (allowed.length === 0) return answer;
 
@@ -100,6 +304,49 @@ export function writePermissions(bots, home, bot) {
   return { ...answer, written: missing };
 }
 
+/**
+ * The Codex form of what the bot is allowed: the file's rule lines, each once,
+ * with the rules that gave them, and the rules Codex has no form for.
+ */
+function codexOf(home, bot) {
+  const lines = new Map();
+  const unwritten = [];
+  for (const rule of allowOf(home, bot)) {
+    const form = codexForm(rule);
+    if (form.why !== undefined) unwritten.push({ rule, why: form.why });
+    if (form.line === undefined) continue;
+    lines.set(form.line, [...(lines.get(form.line) ?? []), rule]);
+  }
+  return { lines, unwritten };
+}
+
+/** The lines of a rules file that are rules: not blank, not a comment. */
+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`:
+ * `{ 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.
+ */
+function writeCodex(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;
+
+  refuseOutside(home, file);
+  const text = [
+    `# Written by obk from ${bot.name}'s bot.yaml, where the user's yes to each rule is kept.`,
+    '# 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() };
+}
+
 /**
  * What health has to say about a bot's permission rules: `{ where, says }` for
  * each entry in the file that `allow` does not hold, and each rule `allow`
@@ -107,15 +354,20 @@ export function writePermissions(bots, home, bot) {
  * never taken out.
  */
 export function permissionsTrouble(home, bot) {
-  if (!runsOnClaude(bot)) return [];
-  const file = path.join(home, FILE);
-
   let allowed;
   try {
     allowed = allowOf(home, bot);
   } catch (error) {
+    if (!runsOnClaude(bot) && !runsOnCodex(bot)) return [];
     return [{ where: path.join(home, 'bot.yaml'), says: error.message }];
   }
+  return [...claudeTrouble(home, bot, allowed), ...codexTrouble(home, bot)];
+}
+
+/** Health's findings in the bot's Claude settings. */
+function claudeTrouble(home, bot, allowed) {
+  if (!runsOnClaude(bot)) return [];
+  const file = path.join(home, FILE);
   if (!existsSync(file) && allowed.length === 0) return [];
 
   // A link out of the bot folder is named by the hook's check already; here it
@@ -133,7 +385,11 @@ export function permissionsTrouble(home, bot) {
   return [
     ...present.filter((rule) => !allowed.includes(rule)).map((rule) => ({
       where: file,
-      says: `${file} allows ${rule}, and ${bot.name}'s bot.yaml does not: the kit did not write it. It stays where it is. If the user wants it, record their yes with obk bot change --allow; if not, take it out of the file.`,
+      // One `--allow` would refuse was added by the user by hand, which the
+      // boundary leaves to them: named, in neutral words, and left alone.
+      says: broadness(rule) === undefined
+        ? `${file} allows ${rule}, and ${bot.name}'s bot.yaml does not: the kit did not write it. It stays where it is. If the user wants it, record their yes with obk bot change --allow; if not, take it out of the file.`
+        : `${file} allows ${rule}, which the user added by hand, not the kit. It stays where it is.`,
     })),
     ...allowed.filter((rule) => !present.includes(rule)).map((rule) => ({
       where: file,
@@ -142,6 +398,71 @@ export function permissionsTrouble(home, bot) {
   ];
 }
 
+/**
+ * Health's findings in the bot's Codex rules: each rule in a file of the
+ * user's beside obk.rules, named and left alone, and an obk.rules that is not
+ * what the kit writes from `allow`.
+ */
+function codexTrouble(home, bot) {
+  if (!runsOnCodex(bot)) return [];
+  const folder = path.join(home, CODEX_RULES);
+  const file = path.join(home, CODEX_FILE);
+  const { lines } = codexOf(home, bot);
+  if (leadsOutside(home, file) !== undefined) {
+    if (lines.size === 0) return [];
+    try {
+      refuseOutside(home, file);
+    } catch (error) {
+      return [{ where: file, says: error.message }];
+    }
+  }
+
+  // A file health cannot read is one finding of its own, and the rest of the
+  // fleet's health still comes out.
+  const unread = (where, error) => [{ where, says: `${where} could not be read (${error.code ?? error.message}), so health cannot say what it holds. It stays where it is.` }];
+  let names = [];
+  try {
+    names = existsSync(folder) ? readdirSync(folder) : [];
+  } catch (error) {
+    return unread(folder, error);
+  }
+  const theirs = names
+    .filter((name) => name.endsWith('.rules') && name !== path.basename(file))
+    .sort()
+    .flatMap((name) => {
+      const where = path.join(folder, name);
+      let text;
+      try {
+        text = readFileSync(where, 'utf8');
+      } catch (error) {
+        return unread(where, error);
+      }
+      return ruleLines(text).map((line) => ({
+        where,
+        says: `${where} holds ${line}, which the user added, not the kit. It stays where it is.`,
+      }));
+    });
+
+  const wanted = [...lines.keys()];
+  let present = [];
+  try {
+    present = existsSync(file) ? ruleLines(readFileSync(file, 'utf8')) : [];
+  } catch (error) {
+    return [...theirs, ...unread(file, error)];
+  }
+  const missing = wanted.filter((line) => !present.includes(line));
+  const extra = present.filter((line) => !wanted.includes(line));
+  if (missing.length === 0 && extra.length === 0) return theirs;
+  const what = [
+    ...(missing.length === 0 ? [] : [`it lacks ${missing.join(' and ')}, which ${bot.name}'s bot.yaml allows`]),
+    ...(extra.length === 0 ? [] : [`it holds ${extra.join(' and ')}, which the kit did not write`]),
+  ].join(', and ');
+  return [...theirs, {
+    where: file,
+    says: `${file} is not what the kit writes from ${bot.name}'s bot.yaml: ${what}. The kit owns this file, and obk up rewrites it; a rule of the user's own goes in another file in ${folder}.`,
+  }];
+}
+
 /** The file's `permissions.allow`, or a refusal when it is there and is not a list. */
 function presentIn(settings, file) {
   const permissions = settings.permissions;

package/src/up.js

@@ -8,7 +8,7 @@ import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
-import { forgetClaimed, forgetSession, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
+import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, sessionIdsIn, tabIdsIn, takeMailboxTurn, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
@@ -155,7 +155,7 @@ export function prepareBots(bots, names, onlySession) {
   // And the permission rules the user allowed, beside the hook and for the same
   // reason: a session that comes up before its rules are there is asked about
   // what the user already said yes to (#344).
-  const permissions = running.map(({ bot, home }) => writePermissions(bots, home, bot)).filter((entry) => entry !== undefined);
+  const permissions = running.flatMap(({ bot, home }) => writePermissions(bots, home, bot));
 
   return { running, rules, skills, permissions };
 }
@@ -296,20 +296,31 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // does not (#272).
   const rules = rulesStamp(home);
   let held;
-  await updateBook(home, (current) => {
-    // What the harness has in this folder that nobody claims goes on the record,
-    // for a person or Bot Father to settle — added to whatever was already noted,
-    // because this run's scan cannot see what an earlier one found. The kit never
-    // settles it itself.
-    let entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
-    if (rules === undefined) delete entry.rules;
-    held = entry.session;
-    // Before the line is typed, so the hook finds no id here and takes the one
-    // it reports for a start rather than a clear, which would tell the duty twice.
-    if (which.noConversation !== undefined && held === which.noConversation) entry = forgetSession(entry, 'no conversation');
-    current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
-    forgetClaimed(current);
-  });
+  // Not while the session's mailbox step or a check in its old tab is at work:
+  // the book moving under one leaves the mailbox bound to, or read in, a tab the
+  // book no longer names (#321). Waited for a bounded time and then written all
+  // the same, because this tab is open and its harness has to start; the step
+  // in it then waits its own turn and says what it left. Let go before the line
+  // is typed, since that step takes it.
+  const turn = takeMailboxTurn(home, session.name);
+  try {
+    await updateBook(home, (current) => {
+      // What the harness has in this folder that nobody claims goes on the record,
+      // for a person or Bot Father to settle — added to whatever was already noted,
+      // because this run's scan cannot see what an earlier one found. The kit never
+      // settles it itself.
+      let entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
+      if (rules === undefined) delete entry.rules;
+      held = entry.session;
+      // Before the line is typed, so the hook finds no id here and takes the one
+      // it reports for a start rather than a clear, which would tell the duty twice.
+      if (which.noConversation !== undefined && held === which.noConversation) entry = forgetSession(entry, 'no conversation');
+      current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
+      forgetClaimed(current);
+    });
+  } finally {
+    turn?.release();
+  }
 
   // The old tab's hook can name another conversation while the tab is being
   // opened. A fresh start chosen before that is chosen again from the id the
@@ -524,6 +535,20 @@ export async function ownMailbox(bots, botName, sessionName) {
     throw new Error(`session mailbox binds ${who}'s mailbox to the Orca tab it runs in, and this is not one: ${TERMINAL_ENV} is not set. The kit runs it in the session's own tab when it starts the session.`);
   }
 
+  // One step, check or tab write for this session at a time, and the book read
+  // once the turn is had (#321). A step that does not get it leaves everything
+  // as it is and says so, and the launch line goes on to the harness.
+  const turn = takeMailboxTurn(home, sessionName);
+  if (turn === undefined) throw noTurn(home, who, sessionName);
+  try {
+    return await mailboxInTurn(home, botName, sessionName, who);
+  } finally {
+    turn.release();
+  }
+}
+
+/** What `ownMailbox` does once it has the session's turn. */
+async function mailboxInTurn(home, botName, sessionName, who) {
   // Only in the tab the book names for the session. Two runs of `up` at once
   // can leave a session two tabs, and the book one of them: a mailbox made or
   // bound in the other would be bound to a tab no message is meant for.
@@ -600,6 +625,15 @@ export async function ownMailbox(bots, botName, sessionName) {
  */
 const STEP_WAIT = { timeoutMs: 20_000 };
 
+/** A step that waited its turn out: nothing was made or bound, and where the mailbox was left. */
+function noTurn(home, who, sessionName) {
+  const held = readBook(home).sessions[sessionName]?.mailbox;
+  const left = typeof held === 'string'
+    ? `${who}'s mailbox ${held} is left bound to ${boundTo(held)}; an \`obk message check\` in ${who}'s own tab binds it there.`
+    : `None is written down for ${who}; it gets one the next time the kit starts it.`;
+  return new Error(`waited ${MAILBOX_WAIT_MS / 1000} seconds for ${who}'s mailbox while another obk was making, binding or reading it, and it did not finish. Nothing was made or bound in this tab. ${left}`);
+}
+
 /** Whether a session that can have a mailbox has none in its book. */
 const lacksMailbox = (home, session, harness) => reachesMail(session, harness)
   && typeof readBook(home).sessions[session.name]?.mailbox !== 'string';