@assuredloop/orca-bot-kit 0.26.0 → 0.27.0

package/README.md

@@ -141,15 +141,19 @@ words, `dangerously-skip`
 ([ADR 0015](docs/adr/0015-three-approval-levels-auto-by-default.md)). Only
 `obk permission approval` changes it, after your yes: `session add` and
 `session change` take no approval, and refuse an extra argument that sets one
-([ADR 0037](docs/adr/0037-permission-changes-and-risky-operations-have-commands-of-their-own.md)).
+([ADR 0041](docs/adr/0041-permission-changes-and-risky-operations-have-commands-of-their-own.md)).
 
 Every bot gets the kit's default permission rules, written by the kit with
 nobody asked: its own commands for this bots folder, reading a long message,
 `git add` and `git commit`, and Orca's `orca orchestration check --run`
 ([ADR 0036](docs/adr/0036-the-kit-writes-every-bots-default-permission-rules.md)).
-`obk permission`, `obk retire`, `obk pause` and `obk init` are not in the set,
-and keep your yes. A rule beyond the set is written by `obk permission allow`,
-after your yes to the exact rule.
+`obk permission`, `obk retire`, `obk pause`, `obk restart`, `obk bot create`
+and `obk init` are not in the set, and keep your yes
+([ADR 0041](docs/adr/0041-permission-changes-and-risky-operations-have-commands-of-their-own.md)).
+A rule beyond the set is written by `obk permission allow`, after your yes to
+the exact rule. A bot that still holds the `obk restart` or `obk bot create`
+rule, which kit 0.26.0 gave every bot, keeps it: `obk rules build` and `obk up`
+name it, with the `obk permission disallow` command that takes it back.
 
 Neither command touches Orca. `obk up` is what makes it all real there: an Orca
 project per bot, a tab per session, each started at the bot home with its own
@@ -361,19 +365,6 @@ address that is none of your bots folder's sessions, the hook tells it so, and
 names the address `obk message to` would have given. The message goes either
 way ([ADR 0032](docs/adr/0032-a-native-message-outside-the-fleet-is-warned-about.md)).
 
-And a third: at the end of each turn, it tells the session once about fleet
-mail the kit sent it that is still unread, without typing into its tab
-([ADR 0035](docs/adr/0035-messaging-transport.md)). It asks Orca only when the kit
-knows of mail for that session.
-
-A Codex bot gets one more hook too. Inside Codex's sandbox the kit cannot always
-tell whether the receiver of a message has its harness in front, as for a Claude
-session busy running a command, so `obk message send` leaves that nudge, and the
-hook, which Codex runs outside its sandbox right after the command, decides it and
-types it, or says why not ([ADR 0034](docs/adr/0034-orca-is-the-host.md)). Codex
-asks you to trust a hook it has not seen before, so a Codex bot made before this
-hook asks again once.
-
 So: kill a tab, or reboot, and `obk up` brings the session back with the
 conversation it was having, rather than starting a new one. Clear a session —
 `/clear` on Claude Code, `/new` on Codex — and the kit writes down the new id,
@@ -473,7 +464,12 @@ same refusals, and one more: it also refuses a tab with only its shell in front
 whose conversation the book does not name. `obk up` leaves what is paused
 closed until `obk unpause` brings it back with its conversations. Retiring a
 session takes it off the bot and keeps its conversations in the book under
-`retired`. Retiring a bot closes
+`retired`. Once its tab is closed, it stops what the session left running in
+its work dir: each of your processes whose working folder is there, and what
+they started, with SIGTERM and, after up to 3 seconds, SIGKILL. It names each
+process it stopped, and each it left: one that only shares a process group with
+them, or one it could not stop. Where it cannot read the processes, as inside
+Codex's sandbox, it says so and stops nothing. Retiring a bot closes
 its tabs, removes its Orca project and moves its folder to `retired/`; it will
 not touch a bot whose Orca project holds a tab your book does not name. The
 folder moves only once Orca no longer lists the project; if Orca still lists it,
@@ -553,6 +549,8 @@ What it looks for:
   `<bot>.<session>` every fleet's sessions had before 0.10.0, which a session of
   another fleet can write to. Its next start through the kit gives it one of its
   own, so the finding names the `obk restart … --session` that does it;
+- **a process still running in a retired session's work dir**: one from before
+  retire stopped them, or one it could not stop, with its pid and command;
 - **leftovers no book owns**: an Orca project inside your bots folder with no
   bot in it, a tab in a bot's project that the book does not name, a start
   prompt written for a session that has gone, a clone of a skills source you no
@@ -576,7 +574,7 @@ verdict: which of these matter, and in what order, is for you or for Bot Father.
 ## Sessions and bots that talk
 
 Ask the kit how to reach a session, and it answers with the road and the
-address ([ADR 0035](docs/adr/0035-messaging-transport.md)):
+address ([ADR 0042](docs/adr/0042-messaging-transport.md)):
 
 ```sh
 obk message to    --bots /path/to/my-bots --to api-bot/daily
@@ -619,17 +617,17 @@ 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 each message gets one signal that tells
-the receiver to look. Orca's own notice comes first: Orca types it into an idle
-tab. The kit watches an idle receiver for up to 8 seconds, and reads the
-receiver's own record of its turns. When Orca's notice is there, the kit types
-nothing. When no turn started, the kit types its own line. A Claude session busy
-with a turn gets nothing typed: its hook tells it at the end of the turn. A busy
-Codex session gets the kit's line, which Codex takes into the turn it is having.
-The send says which signal went. A session that is not up is not typed into at
-all; its message waits. When a session is retired, the kit says how many
-messages sent to it were not read with `obk message check`, and who sent them
-([ADR 0035](docs/adr/0035-messaging-transport.md)).
+Nothing in a mailbox wakes anybody, so each message gets one signal: Orca's
+own notice, which Orca types into the receiver's tab once it is idle. A busy
+receiver gets it a minute or a few after its turn ends. The kit types nothing
+into the receiver's tab, and the send says which road it took. For urgent mail,
+`obk message send --interrupt` presses Escape once in a busy receiver's tab to
+end its turn, and then sends the message, so the notice comes at once. Codex
+keeps a command it was running as a background terminal after an Escape. A
+receiver reads its mail with `obk message check`, which marks it read: a bare
+`orca orchestration check` leaves it unread, and Orca then gives no more
+notices for that mailbox
+([ADR 0042](docs/adr/0042-messaging-transport.md)).
 
 A message longer than 4 KiB is written to a file beside your bots folder and
 named in the message, so a long one arrives whole without landing a document in
@@ -676,6 +674,8 @@ except the mailbox Runs Orca gives no way to delete, which the run names; it
 never closes a tab it did not open. The trust its harnesses write into your
 `~/.codex/config.toml` and `~/.claude.json` for the run's own throwaway folders
 is taken out again after the run, and named; nothing else in them is changed.
+An Orca project the run leaves in one of its own throwaway folders is named,
+with its setup id, and fails the run; the command removes none itself.
 
 They run on the machine the command is typed on, so the command will not start
 them by itself. On its own it says what it is about to drive — whose machine,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/rules/mail.md

@@ -12,12 +12,12 @@ If your harness refuses a message, do not send it again by another road. Tell
 your maker or your user, with the harness's reason. A refusal can mean a missing
 permission rule, which they can add through the kit after the user's yes.
 
-Mail is queued, not an interruption. Read it when you finish what you are on.
+Mail is queued, not an interruption. When Orca says you have mail, read it
+with `"${OBK_CLI:-obk}" message check --bots <bots>`, never a bare `orca
+orchestration check`: that leaves it unread, and Orca stops telling you of mail.
 
 Ask for a reply when you need one, and send one when you were asked for one.
 
-A message sent is queued, not read or acted on: the reply, or the work done,
-is what shows it arrived. Look for one before you send it again.
+A sent message is only queued. Look for the reply or the work before you resend.
 
-Write to the session that needs it, not to several in the hope that one of
-them is right.
+Write only to the session that needs it, not to several at once.

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

@@ -213,8 +213,11 @@ its commits. The kit writes this default set itself, with nobody asked:
 does not have yet to its `bot.yaml` and its settings, or for Codex its
 `.codex/rules/obk.rules`, and say which rules they wrote. The set leaves out
 the commands that keep the user's yes: `obk permission`, `obk retire`, `obk
-pause` and `obk init`. Never write a permission rule into a settings or rules
-file by hand.
+pause`, `obk restart`, `obk bot create` and `obk init`. A bot that still holds
+the `obk restart` or `obk bot create` rule from kit 0.26.0 keeps it, and `obk
+rules build` and `obk up` name it with the `obk permission disallow` command
+that takes it back; run that command only after the user's yes. 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

package/src/book.js

@@ -6,12 +6,14 @@
 // 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, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { isDeepStrictEqual } from 'node:util';
 import { parse, stringify } from 'yaml';
 
+import { kitFolders } from './launch.js';
+
 const HEADER = `# What Orca calls this bot on this machine, and where each of its sessions
 # lives. \`obk up\` writes this file; it is committed with the rest of the repo.
 #
@@ -151,7 +153,7 @@ function takeLock(home) {
   try {
     return lockOn(lockFile(home), WAIT_MS);
   } catch (error) {
-    throw waitedTooLong(home, error);
+    throw error instanceof LockNotWritable ? error : waitedTooLong(home, error);
   }
 }
 
@@ -162,7 +164,21 @@ function takeLock(home) {
  * `EXCLUSIVE`, alone, once every `SHARED` holder has let go.
  */
 function lockOn(file, waitMs, how = 'IMMEDIATE') {
-  mkdirSync(path.dirname(file), { recursive: true });
+  // SQLite opens a file it cannot write read-only, without a word, and a
+  // read-only connection's BEGIN passes while another process holds the lock:
+  // seen in Codex's sandbox (#534). So the file is opened for writing first,
+  // and a lock that cannot be held is an error, never a turn that is not one.
+  // Only while this process holds no turn on it: closing any descriptor of a
+  // file lets go of every lock the process holds on that file, and SQLite's
+  // own are among them. A file a turn is held on was written already.
+  if (!heldHere.has(file)) {
+    try {
+      mkdirSync(path.dirname(file), { recursive: true });
+      closeSync(openSync(file, 'a'));
+    } catch (error) {
+      throw new LockNotWritable(file, error);
+    }
+  }
 
   const db = new DatabaseSync(file);
   try {
@@ -181,17 +197,24 @@ function lockOn(file, waitMs, how = 'IMMEDIATE') {
     throw error;
   }
 
+  heldHere.set(file, (heldHere.get(file) ?? 0) + 1);
   return {
     release() {
       try {
         db.exec('COMMIT');
       } finally {
         db.close();
+        const left = heldHere.get(file) - 1;
+        if (left > 0) heldHere.set(file, left);
+        else heldHere.delete(file);
       }
     },
   };
 }
 
+/** How many turns this process holds on each lock file, by its path. */
+const heldHere = new Map();
+
 /**
  * Where a writer takes its turn: a folder of the kit's own beside the bots repo,
  * carrying that folder's own name, the way start-prompt files sit beside it
@@ -213,14 +236,31 @@ function lockOn(file, waitMs, how = 'IMMEDIATE') {
  * 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) => {
+const lockFile = (home) => path.join(botLocks(home), `${encodeURIComponent(path.basename(realpathSync(home)))}.lock`);
+
+/**
+ * The bot's own folder of locks, `<bots>.locks/<bot>/`: the one a Codex
+ * session of the bot is given to write, beside its mail and its start prompts
+ * (#534). One folder per bot, so a bot's sessions can take each other's turns
+ * and no other bot's.
+ */
+const botLocks = (home) => {
   const real = realpathSync(home);
-  return path.join(
-    `${path.dirname(path.dirname(real))}.locks`,
-    `${encodeURIComponent(path.basename(real))}.lock`,
-  );
+  return kitFolders(path.dirname(path.dirname(real)), path.basename(real)).locks;
 };
 
+/**
+ * A lock the kit cannot write. Inside Codex's sandbox that is a session
+ * started before the kit gave its bot a folder of locks, so it says what puts
+ * it right.
+ */
+class LockNotWritable extends Error {
+  constructor(file, why) {
+    super(`the kit cannot write its lock ${file} (${why.code ?? why.message}), so it did not take the turn, and nothing was done. A Codex session started before this version of the kit cannot write its bot's folder of locks: restart this session with the kit. Elsewhere, make ${path.dirname(file)} writable.`);
+    this.code = why.code;
+  }
+}
+
 /**
  * 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
@@ -286,11 +326,11 @@ export function takeTypingTurn(home, session, waitMs) {
 
 /**
  * A session's turn for one whole line, sent with its return in one go, as the
- * mail nudge is: through the typing turn's gate, waited for `waitMs` at most,
+ * mail interrupt is: through the typing turn's gate, waited for `waitMs` at most,
  * and then held beside any other line, so whole lines never wait on each
  * other, only on typing one key at a time. Returns `{ release }`, or undefined
  * when the gate did not come within `waitMs`. Every whole line the kit types
- * takes it: the nudge, the list line, the skills reload and the grooming line (#482).
+ * takes it: the mail interrupt, the list line, the skills reload and the grooming line (#482).
  */
 export function takeLineTurn(home, session, waitMs) {
   const gate = turnOn(home, session, 'typing', waitMs);
@@ -312,8 +352,9 @@ export const TYPING_WAIT_MS = 5000;
 export const TYPING_HELD = `the kit is typing into it, and it was still at it after ${TYPING_WAIT_MS / 1000} s, so nothing was typed`;
 
 /**
- * How long a typing turn waits for the lines already on their way: a nudge
- * holds its line's turn while Orca waits up to 5 s to see it start a turn.
+ * How long a typing turn waits for the lines already on their way: a line
+ * re-issued to Orca holds its turn while Orca waits up to 5 s to see it start
+ * a turn.
  */
 const LINES_WAIT_MS = 10_000;
 
@@ -344,10 +385,8 @@ const SQLITE_BUSY = 5;
  * 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`);
-};
+const mailboxLockFile = (home, session) =>
+  path.join(botLocks(home), `${path.basename(realpathSync(home))}.${session}.mailbox.lock`);
 
 /**
  * Something else has been writing the book for longer than this run is prepared

package/src/bot.js

@@ -162,7 +162,7 @@ export function readBot(home, name = path.basename(home)) {
     // The roles its temporary sessions can be made in, judged by tempRoles.
     ...(bot.temp_roles === undefined ? {} : { temp_roles: bot.temp_roles }),
     // The widest approval its temporary sessions may be made at, the user's yes
-    // kept by `permission approval --temps` (ADR 0037).
+    // kept by `permission approval --temps` (ADR 0041).
     ...(bot.temp_approval === undefined ? {} : { temp_approval: bot.temp_approval }),
     // A paused bot is one `obk up` leaves closed; its sessions keep their book.
     ...(bot.paused === true ? { paused: true } : {}),
@@ -362,7 +362,7 @@ export function changeSession(bots, bot, name, settings) {
 
 /**
  * Record the widest approval the bot's temporary sessions may be made at,
- * `level`, as `temp_approval` (ADR 0037). Returns { bot, home, level }.
+ * `level`, as `temp_approval` (ADR 0041). Returns { bot, home, level }.
  */
 export function setTempApproval(bots, bot, level) {
   editBot(bots, bot, `let ${bot}'s temporary sessions be made at ${level}`, (doc) => doc.set('temp_approval', level), (was) => ({ ...was, temp_approval: level }));