@assuredloop/orca-bot-kit 0.9.0 → 0.11.0

package/src/cli.js

@@ -12,13 +12,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
-import { addSession, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
+import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
 import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
 import { checkMail, lookUp, noMailboxYet, sendMessage } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
+import { allowCommand, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -54,9 +55,14 @@ Usage:
                             given glued to its flag, so its dashes are not read
                             as ours: --prompt='- a bullet', and
                             --extra-arg=--search, once per extra argument.
-  obk bot change --bots <path> --bot <bot> --charter <text>
+  obk bot change --bots <path> --bot <bot> [--charter <text>]
+                 [--allow <rule> ...]
                             Give a bot a new charter and rebuild its AGENTS.md.
                             A running session reads it when it next starts.
+                            --allow records a permission rule the user said
+                            yes to, once per rule, and writes it into the bot's
+                            Claude settings. A broad rule, such as Bash(gh:*),
+                            is refused and nothing is written.
   obk session change --bots <path> --bot <bot> --session <session>
                   [--model <m>] [--effort <e>] [--context <c>]
                   [--approval ${APPROVALS.join('|')}]
@@ -300,6 +306,7 @@ async function run(argv) {
       thread: { type: 'string' },
       peek: { type: 'boolean' },
       charter: { type: 'string' },
+      allow: { type: 'string', multiple: true },
       ...Object.fromEntries(SETTINGS.map(([flag]) => [flag, { type: 'string' }])),
       'extra-arg': { type: 'string', multiple: true },
       json: { type: 'boolean' },
@@ -441,19 +448,19 @@ const commands = {
     const seeded = initBots(bots, values.harness);
     // The typed path was for making the folder and naming it in a refusal; from
     // here on it is the fleet, and the fleet is its real path (#164).
-    const { tabs, rules, skills, paused, projects } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
+    const { tabs, rules, skills, permissions, paused, projects } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
     // Setup is the other place the PRD asks for Orca's own launch arguments to
     // be looked at (6.5), and the one where the user is still standing in front
     // of the fleet they are making. Only that one check: a folder init has just
     // made has nothing else to say about itself.
-    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, tabs, paused, projects, found: orcaSettingFindings() };
+    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, permissions, tabs, paused, projects, found: orcaSettingFindings() };
     return { answer, lines: tabLines(answer, `Bot Father is up in Orca. Your bots folder: ${seeded.bots}`) };
   },
 
   async up(bots, values) {
     refuseWhenOrcaIsDown();
-    const { tabs, rules, skills, paused, projects } = await bringUp(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects };
+    const { tabs, rules, skills, permissions, paused, projects } = await bringUp(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, permissions, tabs, paused, projects };
     const up = [...new Set(tabs.map((tab) => tab.bot))];
     const summary = up.length === 0
       ? `Nothing was brought up in Orca. Your bots folder: ${bots}`
@@ -481,8 +488,8 @@ const commands = {
 
   async restart(bots, values) {
     refuseWhenOrcaIsDown();
-    const { closed, tabs, rules, skills, paused, projects } = await restartSessions(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects, closed };
+    const { closed, tabs, rules, skills, permissions, paused, projects } = await restartSessions(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, permissions, tabs, paused, projects, closed };
     const what = values.session === undefined ? values.bot : `${values.bot} ${values.session}`;
     return {
       answer,
@@ -551,9 +558,12 @@ const commands = {
       answer: { bots, ...retired },
       lines: [
         ...closedLines(retired.closed),
-        // After every removal, whatever the window was told: Orca's window can
-        // keep a removed project's row even after it re-reads (stablyai/orca#20102).
-        ...(retired.project === undefined ? [] : [`removed    Orca project ${retired.project}`, RELOAD_LINE]),
+        // Orca's window keeps a removed project's row until it is rebuilt
+        // (#343): the user reloads it by hand only when the kit could not.
+        ...(retired.project === undefined ? [] : [
+          `removed    Orca project ${retired.project}`,
+          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`,
       ],
     };
@@ -567,7 +577,10 @@ const commands = {
     // A new bot is given what the lists already name, so it is whole before
     // anybody opens a tab on it.
     const skills = [linkSkills(bots, made.home, readBot(made.home))];
-    const answer = { bots, bot: made.bot, home: made.home, created: made.created, rules, skills };
+    // 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));
+    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"
     // would send the caller past the thing that needs settling first.
@@ -578,6 +591,7 @@ const commands = {
         ...made.created.map((entry) => `created    ${entry}`),
         ...rulesLines(rules, bots),
         ...skillsLines(skills),
+        ...permissionsLines(permissions, bots),
         trouble
           ? `${made.bot} is written, and its rules are not. Settle what the line above says, then:  ${shellWord(ownCli())} rules build --bots ${shellWord(bots)} --bot ${made.bot}`
           : `${made.bot} is written. Give it a session:  ${shellWord(ownCli())} session add --bots ${shellWord(bots)} --bot ${made.bot} --name <name>`,
@@ -590,22 +604,67 @@ const commands = {
     if (values.harness !== undefined) {
       throw new Error(`bot change does not change a bot's harness: its sessions' conversations belong to the harness they ran on. To move to ${values.harness}, give it a session on ${values.harness} with obk session add, or retire the bot with obk retire and create a new one.`);
     }
-    const changed = changeBot(bots, values.bot, { charter: values.charter });
-    // Rebuilt at once, as bot create builds it, so the charter a session reads
-    // is the one the bot now has.
-    const rules = [buildAgents(bots, changed.home, readBot(changed.home))];
-    const trouble = rules[0].trouble !== undefined;
-    return {
-      answer: { bots, bot: changed.bot, home: changed.home, charter: changed.charter, rules },
-      lines: [
+    if (values.charter === undefined && values.allow === undefined) {
+      throw new Error('bot change needs --charter <text> or --allow <rule>: what to change.');
+    }
+    // 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) {
+      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 = [];
+    let trouble = false;
+    if (values.charter !== undefined) {
+      const changed = changeBot(bots, values.bot, { charter: values.charter });
+      // Rebuilt at once, as bot create builds it, so the charter a session reads
+      // is the one the bot now has.
+      const rules = [buildAgents(bots, changed.home, readBot(changed.home))];
+      trouble = rules[0].trouble !== undefined;
+      Object.assign(answer, { charter: changed.charter, rules });
+      lines.push(
         `changed    the charter in ${path.join('bots', changed.bot, 'bot.yaml')}`,
         ...rulesLines(rules, bots),
         trouble
           ? `${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.`,
-      ],
-      code: trouble ? 1 : 0,
-    };
+      );
+      // 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));
+      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.`,
+      );
+    }
+    return { answer, lines, code: trouble ? 1 : 0 };
   },
 
   'skills build'(bots, values) {
@@ -698,17 +757,19 @@ const commands = {
 
   'rules build'(bots, values) {
     const rules = buildRules(bots, { bot: values.bot });
-    const trouble = rules.filter((entry) => entry.trouble !== undefined);
+    const permissions = rules.flatMap((entry) => permissionsOf(bots, entry.bot));
+    const trouble = [...rules, ...permissions].filter((entry) => entry.trouble !== undefined);
     return {
-      answer: { bots, rules },
+      answer: { bots, rules, permissions },
       lines: [
         ...rulesLines(rules, bots),
+        ...permissionsLines(permissions, bots),
         trouble.length === 0
           ? `Rules are built. Your bots folder: ${bots}`
           // Not "not built": the file itself may be fine and the trouble be
           // the CLAUDE.md beside it, which is a bot whose rules still do not
           // reach both harnesses.
-          : `${trouble.map((entry) => entry.bot).join(', ')}: the rules are not in place. Settle what the lines above say, then build again.`,
+          : `${[...new Set(trouble.map((entry) => entry.bot))].join(', ')}: the rules are not in place. Settle what the lines above say, then build again.`,
       ],
       // The build is the whole of this command, so a build it could not make is
       // what the command ends in. `up` answers for its tabs and is not held to
@@ -774,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
@@ -1169,6 +1233,68 @@ function sessionLines(session) {
   ];
 }
 
+/**
+ * The permission rules of one bot, written as `rules build` writes them: its
+ * entry, one with the trouble that stopped it, or none for a bot that does not
+ * run on Claude. A bot.yaml that cannot be read is the rules build's to report.
+ */
+function permissionsOf(bots, name) {
+  const home = botDir(bots, name);
+  let bot;
+  try {
+    bot = readBot(home, name);
+  } catch {
+    return [];
+  }
+  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}`,
+  ];
+}
+
+/**
+ * What became of each bot's permission rules: the file the allowed ones were
+ * written into, and the kit's rules that still wait for the user's yes, each
+ * word for word, with the one command that allows them once the user has said
+ * 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`]),
+    // 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)}`,
+    ]),
+  ]);
+}
+
 /**
  * What became of each bot's `AGENTS.md`, in the same column as the rest of the
  * report: what the build did, the file it did it to, and what it carries. A
@@ -1252,12 +1378,13 @@ function settingsLine({ bot, session, running, settings, rules }) {
   return `${word.padEnd(9)}  ${who}  ${each.join('  ')}  rules ${rules.state}`;
 }
 
-function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], projects = [], found = [] }, summary) {
+function tabLines({ bots, created, completed, rules, skills, permissions = [], tabs, paused = [], projects = [], found = [] }, summary) {
   const lines = [
     ...created.map((entry) => `created    ${entry}`),
     ...completed.map((entry) => `completed  ${entry}`),
     ...rulesLines(rules, bots),
     ...skillsLines(skills),
+    ...permissionsLines(permissions, bots),
   ];
 
   for (const tab of tabs) {

package/src/health.js

@@ -27,6 +27,7 @@ import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
 import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
 import { frontOfTab, orcaDefaultArgs, projects, tabs, wordsOfProcess } from './orca.js';
+import { permissionsTrouble } from './permissions.js';
 import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
 import { settingsInUse } from './settings.js';
@@ -191,6 +192,7 @@ function aboutBot(bots, name, setups, sessions) {
     ...sessionSettings(home, bot).map(said('config')),
     ...agentsTrouble(bots, home, bot).map(said('config')),
     ...hooksOf(bots, home, bot).map(said('config')),
+    ...permissionsTrouble(home, bot).map(said('config')),
     ...skillsTrouble(bots, home, bot).map(said('skill')),
     ...inOrca(bots, home, bot, setups, sessions),
   ];

package/src/hooks.js

@@ -238,12 +238,12 @@ const unquoted = (word) => (word.startsWith("'") ? word.slice(1, -1).replaceAll(
  * cannot read as JSON is the user's, and guessing at it would lose what they
  * wrote, so the command says so and writes nothing.
  */
-function readSettings(file) {
+export function readSettings(file, what = "the kit's session hook") {
   if (!existsSync(file)) return {};
 
   const parsed = parse(readFileSync(file, 'utf8'));
   if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error(`${file} is not readable as JSON, and the kit's session hook goes in it. Fix it or move it aside, then run the command again.`);
+    throw new Error(`${file} is not readable as JSON, and ${what} goes in it. Fix it or move it aside, then run the command again.`);
   }
   return parsed;
 }

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-reload.applescript

@@ -0,0 +1,45 @@
+-- Run by the kit as `osascript orca-reload.applescript <Orca.app path>`, after
+-- a project was removed (#343, ADR 0025).
+--
+-- Orca's window keeps a removed project in its sidebar until the window is
+-- rebuilt (stablyai/orca#23224; once a release fixes it, this can go behind a
+-- version check), and its menu item Force Reload rebuilds it. This has System Events
+-- click that item in the Orca at <Orca.app path>, and in no other app. The
+-- item's name is localized, so it is also known by the shortcut the menu draws
+-- after a tab, Orca's own ⌘⇧R. Only when that Orca is the front app: macOS
+-- takes a click on a background Orca's menu and Orca does nothing, and the
+-- kit never brings Orca to the front, where the user's typing would land. It
+-- prints `reloaded` only when it clicked; no such Orca, Orca not in front or
+-- no such item prints something else, and anything macOS refuses is an
+-- error. The kit reads all of those the same way.
+
+on run argv
+	set appPath to item 1 of argv
+	tell application "System Events"
+		repeat with candidate in (every application process whose name is "Orca")
+			if POSIX path of application file of candidate is appPath then
+				tell candidate
+					-- Menu 1 is Apple's own.
+					repeat with b from 2 to count of menu bar items of menu bar 1
+						set m to menu 1 of menu bar item b of menu bar 1
+						set labels to name of menu items of m
+						repeat with i from 1 to count of labels
+							set label to item i of labels
+							if label is not missing value then
+								if label is "Force Reload" or label starts with ("Force Reload" & tab) or label ends with (tab & "⌘⇧R") then
+									-- Asked last, right before the click, so Orca has had no time to
+									-- lose the front since.
+									if frontmost of candidate is false then return "Orca is not the front app"
+									click menu item i of m
+									return "reloaded"
+								end if
+							end if
+						end repeat
+					end repeat
+				end tell
+				return "no Force Reload in Orca's menus"
+			end if
+		end repeat
+	end tell
+	return "no Orca running from " & appPath
+end run

package/src/orca-runtime.cjs

@@ -0,0 +1,28 @@
+// Run by Orca's own binary as plain Node, the way Orca's `bin/orca` runs its
+// CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-runtime.cjs <client> <method> <params> <wait>`.
+//
+// It makes one call to Orca's runtime, through Orca's own client, for a method
+// Orca's CLI does not offer (ADR 0025): `project.update`, which makes Orca's
+// window read its projects again (#224), and `terminal.inspectProcess`, which
+// says who is in front of a tab where `ps` cannot (#298). `params` is JSON. It
+// prints the runtime's answer as JSON and exits 0 only when the runtime took
+// the call; anything else is a non-zero exit, and the kit reads every non-zero
+// exit the same way.
+
+'use strict';
+
+const [client, method, params, wait] = process.argv.slice(2);
+
+process.exitCode = 1;
+const { RuntimeClient } = require(client);
+new RuntimeClient(undefined, Number(wait))
+  .call(method, JSON.parse(params))
+  // A write to a pipe is not done when it returns on macOS, so the exit waits
+  // for it: an answer cut short would read as no answer.
+  .then((answer) => answer?.ok === true && new Promise((done) => {
+    process.stdout.write(JSON.stringify(answer), () => {
+      process.exitCode = 0;
+      done();
+    });
+  }), () => {})
+  .finally(() => process.exit());