@assuredloop/orca-bot-kit 0.9.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

@@ -125,9 +125,14 @@ This makes the folder a git repository, seeds it, writes Bot Father, and opens
 its two tabs in Orca: the management tab where they will talk to it, and an ops
 tab, which is a plain shell for work across the whole fleet.
 
-Read everything it prints. Two parts of it matter to them:
+Read everything it prints. Three parts of it matter to them:
 
 - **what it created** — say it in a sentence, not as a file listing;
+- **the permission rules it says wait for their yes**, when Bot Father runs on
+  Claude Code: its mail through the kit, reading a long message beside the
+  bots folder, and its commits, so auto mode does not stop it for those. Show
+  them the rules word for word and ask. Only on a yes, run the one command
+  `init` printed for them; on a no, run nothing, and nothing is written;
 - **anything it says about Orca's own default launch arguments.** Orca adds
   these to every agent it launches, relaunches and resumes. When they carry a
   permission bypass, every session runs in that mode whatever approval level the
@@ -186,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.
 
@@ -210,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.9.0",
+  "version": "0.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/rules/limits.md

@@ -16,3 +16,7 @@ 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 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/rules/mail.md

@@ -6,8 +6,7 @@ applies: all
 
 To reach another session, ask the kit for the road rather than guessing an
 address: `"${OBK_CLI:-obk}" message to --bots <bots> --to <bot>/<session>`. It
-answers with the address and the command that carries it. Your bots folder is
-two levels above the folder you start in.
+answers with the address and the command that carries it.
 
 Mail is queued, not an interruption. Read it when you finish what you are on.
 

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

@@ -201,6 +201,39 @@ 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 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
 else. The harness writes it, loads it and keeps it tidy itself. On Claude Code
@@ -245,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/bot.js

@@ -136,6 +136,9 @@ export function readBot(home, name = path.basename(home)) {
     // and a list the build cannot follow is that build's to report (PRD 6.6).
     charter: bot.charter,
     rules: bot.rules,
+    // The permission rules the user said yes to, judged where they are written
+    // (src/permissions.js), as `rules` is judged by the build.
+    allow: bot.allow,
     // A paused bot is one `obk up` leaves closed; its sessions keep their book.
     ...(bot.paused === true ? { paused: true } : {}),
     sessions: sessions.map((session) => {
@@ -250,6 +253,42 @@ export function changeBot(bots, bot, { charter }) {
   return { bot, home: botDir(bots, bot), charter: text };
 }
 
+/**
+ * The bot's `allow` list as it is, after refusing what `allowRules` would refuse:
+ * an empty rule, or a list already there that is not a list of rules. Asked
+ * before anything is written, so a refused `bot change` changes nothing, its
+ * charter included.
+ */
+export function allowedNow(bots, bot, rules) {
+  if (rules.some((rule) => rule.trim() === '')) {
+    throw new Error('--allow is empty. Give it the exact permission rule the user said yes to, such as Bash(git add:*).');
+  }
+  const home = existingBot(bots, bot);
+  const was = readBot(home, bot).allow ?? [];
+  if (!Array.isArray(was) || was.some((rule) => typeof rule !== 'string' || rule.trim() === '')) {
+    throw new Error(`the allow entry in ${path.join(home, BOT_YAML)} is not a list of permission rules, so nothing was written. Fix it, then run the command again.`);
+  }
+  return { home, was };
+}
+
+/**
+ * Add the permission rules the user said yes to, `rules`, to the bot's `allow`,
+ * after the ones already there and never twice. Returns { bot, home, allow,
+ * added }: the whole list now, and what this call put in it.
+ *
+ * Only the list: the rules are written into the harness's settings by the
+ * caller, as the rules build is run by the caller of `changeBot`.
+ */
+export function allowRules(bots, bot, rules) {
+  const { home, was } = allowedNow(bots, bot, rules);
+  const added = [...new Set(rules)].filter((rule) => !was.includes(rule));
+  const allow = [...was, ...added];
+  if (added.length > 0) {
+    editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }));
+  }
+  return { bot, home, allow, added };
+}
+
 /**
  * Change the settings of the session `name` of the bot `bot`. Returns
  * { bot, home, session } — the session as it now reads.
@@ -414,7 +453,7 @@ export const SESSION_FIELDS = [
 ];
 
 /** Everything the top of a bot's own file can hold. */
-const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'sessions', 'paused'];
+const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'allow', 'sessions', 'paused'];
 
 /**
  * The keys in a bot's file that the kit does not know, and so that nothing