@assuredloop/orca-bot-kit 0.10.0 → 0.12.0

package/src/cli.js

@@ -12,14 +12,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
-import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
+import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, disallowRules, 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, writePermissions } from './permissions.js';
+import { allowCommand, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -56,12 +56,17 @@ Usage:
                             as ours: --prompt='- a bullet', and
                             --extra-arg=--search, once per extra argument.
   obk bot change --bots <path> --bot <bot> [--charter <text>]
-                 [--allow <rule> ...]
+                 [--allow <rule> ... | --disallow <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.
+                            Claude settings. A broad rule, such as Bash(gh:*),
+                            is refused and nothing is written.
+                            --disallow takes back a rule the bot was allowed,
+                            once the user has said yes to that, from bot.yaml
+                            and the bot's settings. A rule the user added by
+                            hand is not the kit's, and is refused.
   obk session change --bots <path> --bot <bot> --session <session>
                   [--model <m>] [--effort <e>] [--context <c>]
                   [--approval ${APPROVALS.join('|')}]
@@ -183,14 +188,15 @@ Usage:
                             only while its tab is up in Orca.
   obk usage --bots <path> [--bot <bot>] [--session <name>] [--since <time>] [--until <time>]
                             Say what your sessions have used: the conversations
-                            each one had, their calls and tokens, the models and
-                            efforts they ran at, and how often they were
-                            compacted. --since counts the calls made from that
-                            moment on, and --until the calls made before that
-                            one: a daily run asks from the last run's end up to
-                            its own, and the next starts where it stopped, so no
-                            call is counted twice. It counts tokens and never
-                            money: what a token costs is looked up live by
+                            each one had, their calls and tokens (their
+                            subagents' included, and how many were theirs), the
+                            models and efforts they ran at, and how often they
+                            were compacted. --since counts the calls made from
+                            that moment on, and --until the calls made before
+                            that one: a daily run asks from the last run's end
+                            up to its own, and the next starts where it stopped,
+                            so no call is counted twice. It counts tokens and
+                            never money: what a token costs is looked up live by
                             whoever is asking.
   obk session record --bots <path> --bot <bot>
                             For the kit's own hook, not for typing: it reads
@@ -306,6 +312,7 @@ async function run(argv) {
       peek: { type: 'boolean' },
       charter: { type: 'string' },
       allow: { type: 'string', multiple: true },
+      disallow: { type: 'string', multiple: true },
       ...Object.fromEntries(SETTINGS.map(([flag]) => [flag, { type: 'string' }])),
       'extra-arg': { type: 'string', multiple: true },
       json: { type: 'boolean' },
@@ -578,7 +585,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"
@@ -603,12 +610,25 @@ 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.`);
     }
-    if (values.charter === undefined && values.allow === undefined) {
-      throw new Error('bot change needs --charter <text> or --allow <rule>: what to change.');
+    if (values.charter === undefined && values.allow === undefined && values.disallow === undefined) {
+      throw new Error('bot change needs --charter <text>, --allow <rule> or --disallow <rule>: what to change.');
+    }
+    if (values.allow !== undefined && values.disallow !== undefined) {
+      throw new Error('bot change takes --allow or --disallow, not both at once, so nothing was changed. Run one, then the other.');
     }
     // 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);
+    }
+    let takeBackFrom;
+    if (values.disallow !== undefined) {
+      const { home } = allowedNow(bots, values.bot, values.disallow, '--disallow');
+      takeBackFrom = takeBack(bots, home, readBot(home, values.bot), values.disallow);
+      disallowRules(bots, values.bot, values.disallow, { write: false });
+    }
 
     const answer = { bots, bot: values.bot, home: botDir(bots, values.bot) };
     const lines = [];
@@ -627,20 +647,55 @@ 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 && values.disallow === 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.`,
       );
     }
+    if (values.disallow !== undefined) {
+      // The harness's files first, bot.yaml last: a write that fails leaves the
+      // rules in `allow`, so the same command can take them back again (#360).
+      const permissions = takeBackFrom();
+      const taken = disallowRules(bots, values.bot, values.disallow);
+      Object.assign(answer, { allow: taken.allow, disallowed: taken.disallowed, permissions });
+      const codex = permissions.find((entry) => entry.unwritten !== undefined);
+      lines.push(
+        ...taken.disallowed.map((rule) => `${'took back'.padEnd(9)}  ${rule}`),
+        ...permissions.filter((entry) => entry.removed?.length > 0).map((entry) => `${'wrote'.padEnd(9)}  ${path.relative(bots, entry.file)}  ${entry.removed.length} permission rule${entry.removed.length === 1 ? '' : 's'} taken out`),
+        ...permissionsLines(permissions, bots),
+        ...(codex === undefined || codex.removed.length === 0 ? [] : [
+          `Codex reads ${codex.file} when a session starts: a Codex session of ${taken.bot} that is running now keeps ${codex.removed.length === 1 ? 'this rule' : 'these rules'} until its next start (obk restart).`,
+        ]),
+        `${taken.bot}'s allow list in ${path.join('bots', taken.bot, 'bot.yaml')} no longer holds ${taken.disallowed.length === 1 ? 'it' : 'them'}.`,
+      );
+    }
     return { answer, lines, code: trouble ? 1 : 0 };
   },
 
@@ -812,19 +867,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
@@ -1027,7 +1085,7 @@ function usageLines(usage, bots) {
   for (const entry of usage) {
     lines.push(`${'bot'.padEnd(9)}  ${entry.bot}`);
     for (const session of entry.sessions) {
-      lines.push(`${'session'.padEnd(9)}  ${session.name}`);
+      lines.push(`${'session'.padEnd(9)}  ${session.name}${'retired' in session ? `  retired ${session.retired}` : ''}`);
       const notCounted = notCountedLine(session.not_counted);
       lines.push(...session.conversations.map(conversationLine));
       if (session.conversations.length === 0 && notCounted.length === 0) lines.push('             nothing on record');
@@ -1067,6 +1125,7 @@ function conversationLine(one) {
     .map(([kind, count]) => `${kind} ${count}`)
     .join('  ');
   return `             ${one.id}  ${one.calls} call${one.calls === 1 ? '' : 's'}`
+    + `${one.subagent_calls > 0 ? `  of which subagents: ${one.subagent_calls} call${one.subagent_calls === 1 ? '' : 's'}` : ''}`
     + `${ran === '' ? '' : `  ${ran}`}`
     + `${used === '' ? '' : `  ${used}`}`
     + `${one.compactions > 0 ? `  compacted ${one.compactions}` : ''}`;
@@ -1220,12 +1279,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 says yes to taking one back out of ${path.join('bots', name, 'bot.yaml')}${settings}${codex}. For one the new charter no longer grants, ask the user, and only after their yes run  ${shellWord(ownCli())} bot change --bots ${shellWord(bots)} --bot ${shellWord(name)} --disallow <rule>. ${until}`,
+  ];
 }
 
 /**
@@ -1235,12 +1308,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/conversations.js

@@ -59,6 +59,30 @@ export function hasConversation(harness, home, id) {
  */
 export const claudeTranscript = (home, id) => path.join(claudeDir(home), `${id}.jsonl`);
 
+/**
+ * The transcripts of the subagents a Claude Code conversation started, given the
+ * file the conversation is in. They sit beside it, in a folder named by its id,
+ * one `agent-<name>.jsonl` each, with a `.meta.json` beside each that is not a
+ * transcript (tech notes, section 2).
+ *
+ * No folder is a conversation that started no subagent. A folder that is there
+ * and cannot be listed is `unreadable`: what is in it cannot be counted, and
+ * taking it as empty would say nothing of that.
+ */
+export function claudeSubagentTranscripts(file) {
+  const dir = path.join(file.slice(0, -'.jsonl'.length), 'subagents');
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (error) {
+    return { files: [], unreadable: error.code === 'ENOENT' ? 0 : 1 };
+  }
+  return {
+    files: names.filter((name) => name.endsWith('.jsonl')).sort().map((name) => path.join(dir, name)),
+    unreadable: 0,
+  };
+}
+
 /**
  * The same conversations, each with the file the harness keeps it in, for a
  * caller that has to read what is inside one rather than only know it is there,

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]);