@assuredloop/orca-bot-kit 0.10.0 → 0.12.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
@@ -579,10 +587,11 @@ The tests come in two layers, and every test file belongs to one of them.
 
 `npm test` is `test/*.test.js`: unit tests and end-to-end runs of the CLI in a
 throwaway folder, with a fake `orca` on PATH. It needs nothing but Node, so
-[GitHub Actions](.github/workflows/ci.yml) runs it on every pull request and on
-every push to `main`: on Node 25.8.0, the current line, and again on 24.21.0,
-the floor `engines.node` promises users, with only the kit's own dependencies
-installed.
+[GitHub Actions](.github/workflows/ci.yml) runs it on every pull request, split
+into shards that run side by side, on Node 25.8.0, the current line. A release
+runs every shard on 25.8.0 and again on 24.21.0, the floor `engines.node`
+promises users, with only the kit's own dependencies installed, before anything
+is published.
 
 `npm run test:system` is `test/system/*.test.js`: the real `obk` against the
 real Orca and the real harnesses on your own machine. No CI runner can do that,

package/SETUP.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,6 +24,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
+    "test:shard": "node --test --test-shard=$SHARD test/*.test.js",
     "test:system": "node scripts/test-system.js",
     "mutate": "node scripts/mutate.js"
   },

package/rules/limits.md

@@ -17,6 +17,6 @@ publishing, releasing, spending money, anything another person receives.
 When something you were told to use is missing (a model, a tool, a file), say
 so and ask. Quietly using a different one hides the change.
 
-Permission rules in a harness's settings file are the kit's to write, after
-the user's yes to the exact rules: `obk bot change --allow <rule>` records and
-writes them. Never edit them into a settings file yourself, Bot Father included.
+Permission rules in a harness's settings or rules files are the kit's to write,
+after the user's yes to the exact rules: `obk bot change --allow <rule>` or
+`--disallow <rule>`. Never edit one in or out yourself, Bot Father included.

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

@@ -201,16 +201,41 @@ say that you edited it by hand.
 Run `obk --help` for the flags of the version actually installed rather than
 trusting a line you remember.
 
-A bot on Claude Code needs a few permission rules so that auto mode does not
-stop it for what the kit's own rules tell it to do: its mail through the kit,
-reading a long message kept beside the bots folder, and its commits. `obk bot
-create`, `obk up` and `obk rules build` list the rules still waiting for a bot
-and give one command that allows them. Show the user those rules word for word
-and say in a line what each lets the bot do. Run the command only after their
-yes: it records the yes in the bot's `bot.yaml` and writes the rules into its
-settings. On a no, run nothing, and nothing is written. When the kit lists new
-rules for a bot later, ask again. Never write a permission rule into a settings
-file by hand.
+A bot needs a few permission rules so that auto mode, or Codex's sandbox and
+reviewer, does not stop it for what the kit's own rules tell it to do: its
+mail through the kit, reading a long message kept beside the bots folder, and
+its commits. `obk bot create`, `obk up` and `obk rules build` list the rules
+still waiting for a bot and give one command that allows them. Show the user
+those rules word for word and say in a line what each lets the bot do. Run the
+command only after their yes: it records the yes in the bot's `bot.yaml` and
+writes the rules into its settings, or for Codex into its
+`.codex/rules/obk.rules`. On a no, run nothing, and nothing is written. When
+the kit lists new rules for a bot later, ask again. Never write a permission
+rule into a settings or rules file by hand.
+
+The charter decides what else the bot needs. What it lets the bot do without
+asking, such as merging pull requests, auto mode or Codex's sandbox can still
+stop, so each grant needs its own rule. When the charter is written, and again
+whenever it changes, list the exact rules it grants: `Bash(gh pr merge:*)` for
+a bot that merges pull requests, `Bash(gh issue close:*)` for one that closes
+issues. Spell each command as the bot will run it, the kit by the path the
+bot's rules give it and every folder absolute, or the rule will not match.
+Spell them in Claude Code's form for a Codex bot too, `Bash(<command>:*)`: the
+kit writes Codex's own form of each, and says which ones Codex has none for,
+such as an `Edit` rule or one exact command.
+Show the user the list word for word, with a line on what each lets the bot do,
+and only after their yes run `obk bot change --allow`, once per rule they said
+yes to. On a no, run nothing. `obk bot change --charter` names the rules the
+bot is allowed now; say which of them the new charter no longer grants, show
+each word for word, and ask whether to take it back. Only after their yes run
+`obk bot change --disallow`, once per rule, which takes it out of `bot.yaml`
+and the bot's settings or Codex rules; on a no, run nothing, and it stays
+allowed. A rule the user added to a settings file by hand is theirs to take
+out; the kit refuses it. Keep
+each rule narrow: a program and what it does. The kit refuses a rule that lets
+the bot run any command, a program with any arguments, or a shell or
+interpreter with any arguments; a user who wants one for a bot adds it to that
+bot's settings themselves. Propose no rule for what the charter does not grant.
 
 A bot that should learn across its sessions can use its harness's own memory,
 turned on for that bot alone, whatever the user's own setting is for everything
@@ -256,23 +281,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 {
@@ -183,12 +191,65 @@ function takeLock(home) {
  * is nobody's to sweep, and the user can see it and delete it.
  *
  * One folder per bots folder, so two bots folders each holding an api-bot cannot
- * take each other's turn.
+ * take each other's turn. Resolved first, as the mailbox's is: one writer reaches
+ * the bots folder through a link and another by its real path, and two paths
+ * would be two locks for one book (#375).
  */
-const lockFile = (home) => path.join(
-  `${path.dirname(path.dirname(home))}.locks`,
-  `${encodeURIComponent(path.basename(home))}.lock`,
-);
+const lockFile = (home) => {
+  const real = realpathSync(home);
+  return path.join(
+    `${path.dirname(path.dirname(real))}.locks`,
+    `${encodeURIComponent(path.basename(real))}.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

package/src/bot.js

@@ -254,14 +254,14 @@ export function changeBot(bots, bot, { charter }) {
 }
 
 /**
- * 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.
+ * The bot's `allow` list as it is, after refusing what `allowRules` or
+ * `disallowRules` 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) {
+export function allowedNow(bots, bot, rules, flag = '--allow') {
   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:*).');
+    throw new Error(`${flag} 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 ?? [];
@@ -289,6 +289,21 @@ export function allowRules(bots, bot, rules) {
   return { bot, home, allow, added };
 }
 
+/**
+ * Take the permission rules the user said yes to taking back, `rules`, out of
+ * the bot's `allow` (#360). Returns { bot, home, allow, disallowed }: the whole
+ * list now, and what this call took out. The caller has refused a rule `allow`
+ * does not hold, and takes them out of the harness's files first. With `write`
+ * false it only refuses what the edit would refuse, and writes nothing.
+ */
+export function disallowRules(bots, bot, rules, { write = true } = {}) {
+  const { home, was } = allowedNow(bots, bot, rules, '--disallow');
+  const disallowed = [...new Set(rules)];
+  const allow = was.filter((rule) => !disallowed.includes(rule));
+  editBot(bots, bot, `take back ${disallowed.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
+  return { bot, home, allow, disallowed };
+}
+
 /**
  * Change the settings of the session `name` of the bot `bot`. Returns
  * { bot, home, session } — the session as it now reads.
@@ -387,9 +402,10 @@ function editSession(bots, bot, index, session, what) {
 
 /**
  * Make one edit to a bot's `bot.yaml` through the YAML library, and write it
- * only if exactly the change `expected` describes is what came out.
+ * only if exactly the change `expected` describes is what came out, and
+ * `write` is not false.
  */
-function editBot(bots, bot, what, edit, expected) {
+function editBot(bots, bot, what, edit, expected, write = true) {
   const file = path.join(existingBot(bots, bot), BOT_YAML);
   const source = readFileSync(file, 'utf8');
   const doc = parseDocument(source);
@@ -398,7 +414,7 @@ function editBot(bots, bot, what, edit, expected) {
   if (!changesExactly(source, text, expected)) {
     throw new Error(`${file} cannot be changed to ${what} without changing something else in it, so nothing was written. Make the change by hand.`);
   }
-  if (text !== source) writeFileSync(file, text);
+  if (write && text !== source) writeFileSync(file, text);
 }
 
 /** A bot that is there, by its home, or the refusal a caller who named another is owed. */