@assuredloop/orca-bot-kit 0.10.0 → 0.12.0

package/src/permissions.js

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