@assuredloop/orca-bot-kit 0.27.0 → 0.29.0

package/README.md

@@ -141,19 +141,41 @@ 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 0041](docs/adr/0041-permission-changes-and-risky-operations-have-commands-of-their-own.md)).
+([ADR 0051](docs/adr/0051-permission-changes-and-risky-operations-have-commands-of-their-own.md))
+or that widens what the session may write or run, such as `--add-dir`, Claude
+Code's `--settings` or Codex's `--profile`. On Codex, `-c` passes only for a
+short list of keys known to be safe, such as `model_reasoning_effort`
+([ADR 0049](docs/adr/0049-extra-arguments-that-widen-a-session-are-refused.md)).
+A Codex session's work dir stays in its bot folder: Codex may write in its work
+dir, so `session add` and `session change` refuse one outside the bot folder for
+a Codex session
+([ADR 0045](docs/adr/0045-a-codex-sessions-work-dir-stays-in-its-bot-folder.md)).
+
+A bot or a session can also run on [Pi](https://pi.dev) (`--harness pi`, tested
+with Pi 1.1.0). Pi asks before no tool call, so a Pi session is always
+`dangerously-skip`, and the kit refuses `auto` and `ask` for it. Sign in to Pi
+yourself first: `obk up` asks Pi which models it can use, and starts nothing
+when Pi has none, or not the one the session names. The kit gives a Pi session
+its id, so `obk up` resumes it after its tab is closed. Pi has no context
+setting: name a model that carries it. Mail, temporary sessions, skills and
+health for a Pi session come later, and so do `obk init --harness pi` and
+`obk session clear` and `compact` on Pi.
 
 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`, `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)).
+`git add` and `git commit`
+([ADR 0050](docs/adr/0050-the-kit-writes-every-bots-default-permission-rules.md)).
+`obk permission`, `obk retire`, `obk pause`, `obk restart`, `obk bot create`,
+`obk bot change`, `obk session add`, `obk session change`, `obk init` and
+`obk run` are not in the set, and keep your yes
+([ADR 0051](docs/adr/0051-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.
+the exact rule. A bot that still holds a rule that the kit gave every bot
+before and that is no longer in the set keeps it: the rule of `obk restart`,
+`obk bot create`, `obk bot change`, `obk session add`, `obk session change`,
+`obk session mail` or `obk session nudge`, or of Orca's
+`orca orchestration check --run`. `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
@@ -451,6 +473,7 @@ obk permission disallow --bots /path/to/my-bots --bot api-bot --rule 'Bash(gh pr
 obk permission approval --bots /path/to/my-bots --bot api-bot --session daily --approval ask
 obk permission approval --bots /path/to/my-bots --bot api-bot --temps --approval dangerously-skip
 obk session change --bots /path/to/my-bots --bot api-bot --session daily --model opus
+obk session change --bots /path/to/my-bots --bot bot-father --session daily --harness codex
 obk skills remove --bots /path/to/my-bots --bot api-bot --skill kit:obk-tdd
 obk pause --bots /path/to/my-bots --bot api-bot [--session daily]
 obk unpause --bots /path/to/my-bots --bot api-bot [--session daily]
@@ -458,8 +481,11 @@ obk retire --bots /path/to/my-bots --bot api-bot [--session daily]
 ```
 
 A change to a charter or a setting is written at once, and a running session
-takes it when it next starts. A session keeps its harness: to move one, retire
-it and add another. A pause closes the tabs the way a restart does, with the
+takes it when it next starts. A session can move to the other harness with
+`--harness`, Bot Father's management session too: it then starts a new
+conversation there, the book keeps the old one in its history, and its model,
+effort and context go back to the new harness's defaults unless you give them
+too. A pause closes the tabs the way a restart does, with the
 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
@@ -514,7 +540,9 @@ obk groom --bots /path/to/my-bots --on --at 04:00 --run-on codex --model gpt-6-s
 Each fire then makes a temporary Codex session of the grooming session's, named
 `groom-<date and time>`, which does the grooming, mails its report back, and is
 retired; the grooming session sends the report on to the management session. A
-run an earlier fire left behind is retired at the next one.
+run an earlier fire left behind is retired at the next one. Each run also
+carries the grooming session's own prompt, as `--on` finds it: after you change
+that prompt, run `obk groom --at <HH:MM>` alone, which keeps the runs on Codex.
 
 ## When something is wrong
 
@@ -549,6 +577,13 @@ 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 session whose mail waits and Orca has not told it**: mail older than an
+  hour that is unread and that Orca's notice never reached, while the session's
+  harness is idle now. Orca can stop telling a session that sat idle through an
+  Orca restart or update, so the finding names the `obk restart … --session`
+  that opens a new tab, which Orca tells. It counts the letters and gives the
+  time of the oldest; it never shows their subject or text. A busy session is
+  not named: Orca tells it when its turn ends;
 - **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
@@ -671,9 +706,14 @@ real Orca and the real harnesses on your own machine. No CI runner can do that,
 so these are run by hand before a change that touches Orca or a harness is
 merged. A system test touches only what it creates and removes it afterwards,
 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.
+never closes a tab it did not open. Before any test loads, the command copies
+your `~/.claude.json` and `~/.codex/config.toml` into a new
+`obk-config-backup-*` folder in your temp folder, readable by you alone, and
+says where; if a copy fails, no test runs. After the run it says whether each
+file still matches its copy, and never copies one back: that is yours to
+decide. 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.
 

package/SETUP.md

@@ -38,15 +38,26 @@ git --version
 /Applications/Orca.app/Contents/Resources/bin/orca status --json
 claude --version                                        # at least one of these
 codex --version                                         # 0.156.1 or newer
+pi --version                                            # 1.1.0, for a bot on Pi
 ```
 
 The Orca line must come back with `ok: true` and `result.runtime.reachable:
-true`. Anything else means Orca is not running, whatever else it says: ask them
-to start it, then run the line again.
+true`. When it answers that Orca is not running or not reachable, ask them to
+start it, then run the line again.
+
+When the line fails with an error instead of an answer, the error is the
+problem. It does not show that Orca is stopped. Tell them the error as the CLI
+printed it, and do not ask them to start Orca for it. For example, `EPERM` with
+`process.cwd failed` or `uv_cwd` means that the CLI cannot read the folder the
+shell is in, while Orca can be running. Run the line again from their home
+folder.
 
 On the Orca CLI path: `/usr/local/bin/orca` is a root-only symlink on some
 machines and fails for an ordinary user, so use the full path above. If Orca
-lives somewhere else here, find it and set `OBK_ORCA` to it.
+lives somewhere else here, find it and set `OBK_ORCA` to it. If that is another
+build of Orca with its own data folder, also set `OBK_ORCA_DATA` to the full
+path of that folder, for example `$HOME/Library/Application Support/orca-lean`.
+The kit reads Orca's launch arguments from the `profiles` folder there.
 
 If Node is older than 24.21.0, say so and stop. The kit's book of sessions is a
 SQLite write transaction through Node's own `node:sqlite`, and 24.21.0 is the
@@ -132,8 +143,9 @@ Read everything it prints. Three parts of it matter to them:
   not stop Bot Father for the kit's own commands, reading a long message
   beside the bots folder, and its commits. The kit writes this set for every
   bot, with nobody asked. Say in a sentence what it allows, and that
-  `obk permission`, `obk retire`, `obk pause` and `obk init` are not in it and
-  keep their yes;
+  `obk permission`, `obk retire`, `obk pause`, `obk restart`, `obk bot create`,
+  `obk bot change`, `obk session add`, `obk session change`, `obk init` and
+  `obk run` are not in it and keep their yes;
 - **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
@@ -192,21 +204,22 @@ that folder itself, exactly as you gave it to `obk init`:
 "$ORCA" terminal read --terminal <handle> --screen --json
 ```
 
-What you will see, and the usual answer. Each goes as one
+What you will see, and the usual answer. Each key goes as one
 `"$ORCA" terminal send --terminal <handle> --text …`, with the return inside the
 text and **no** `--enter`, because a menu takes a return as the keypress it is
-waiting for:
+waiting for. Where the Send cell names `obk` commands, send no keys: the kit
+answers that screen, by the command and its arguments below the table.
 
 | 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.160.0 |
-| 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.160.0 |
+| Codex's `Hooks need review` | `obk session trust-hooks`, or `obk temp trust-hooks` for a temporary session | the kit checks the hooks, then goes to **Trust all and continue** | Codex 0.160.0 |
 | Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home); on 0.162.0 it is called **1. Use current Git worktree** (Keep using the current working directory). Never **Create new Git worktree** | Codex 0.160.0; Codex 0.162.0 (#516) |
 | Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; seen on 0.157.1 (offering 0.158.0) with the selection on **Update now**, not pressed; 0.158.0 offered 0.160.0, taken on 2026-10-02 by Bot Father's restarts |
 | `[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 cancels it (**Not now**). On 2.1.283 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live twice on 2.1.283, in #261's live test and #239's live run 1 (#416); 2.1.278 showed a numbered list, answered with 2. Not now |
-| Claude Code 2.1.289's `Teach auto mode about your environment?`, a numbered list: `1. Yes`, `2. Not now`, `3. Don't show again`, and `Enter to confirm · Esc to cancel`, above the input box | `\x1b[B\r` | down, then return, to **2. Not now**: its selection starts on **1. Yes**. Read the screen after the down arrow, and send the return only with the selection on **2. Not now**. Never **1. Yes**, which starts the teach scan, and never **3. Don't show again** | Not yet proven: the list was seen live on 2.1.289 with its selection on 1. Yes, in #489's live run 1, and was not answered there |
+| Claude Code's `Teach auto mode about your environment?` | `obk session answer`, or `obk temp answer` for a temporary session | the kit sends Esc, which cancels it (**Not now**). On 2.1.283 and 2.1.302 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. On 2.1.283, `Also scan shell history` shows `true` and the foot starts `←/→ to change usage`. On 2.1.302, it shows `false` and the foot starts `←/→ to change`. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live twice on 2.1.283, in #261's live test and #239's live run 1 (#416); 2.1.278 showed a numbered list, answered with 2. Not now; the 2.1.302 form was seen live once, in #604 |
+| Claude Code 2.1.289's `Teach auto mode about your environment?`, a numbered list: `1. Yes`, `2. Not now`, `3. Don't show again`, and `Enter to confirm · Esc to cancel`, above the input box | `obk session answer`, or `obk temp answer` for a temporary session | the kit goes down, then returns, to **2. Not now**: its selection starts on **1. Yes**. The kit reads the screen after the down arrow, and sends the return only with the selection on **2. Not now**. Never **1. Yes**, which starts the teach scan, and never **3. Don't show again** | Not yet proven: the list was seen live on 2.1.289 with its selection on 1. Yes, in #489's live run 1, and was not answered there |
 
 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
@@ -233,8 +246,9 @@ that a narrow permission rule of the kit's default set allows it rather than a
 rule to type into any tab. On Codex's hooks review, the maker runs
 `obk temp trust-hooks --bots <their path> --name <session>`. On Claude Code's
 `Teach auto mode` screen, it runs `obk temp answer --bots <their path> --name <session>`.
-That command reads the screen and answers only when it holds one of the two
-shapes in the table exactly as the kit knows it: Esc for the 2.1.283 form, and
+That command reads the screen and answers only when it holds one of the
+shapes in the table exactly as the kit knows it: Esc for the 2.1.283 and
+2.1.302 forms, and
 **2. Not now** for the 2.1.289 list. On the list it sends the arrows, reads the
 screen again, and sends the return only with the selection on **2. Not now**.
 It refuses any other screen, types nothing then, and prints what it saw.
@@ -298,8 +312,10 @@ obk health --bots <their path>
 
 It reads the setup and says what it found, and writes nothing at all. It exits 1
 when it found something, so do not read a non-zero exit as a broken setup. The
-one exception is an error with no findings, saying Orca is not answering: that
-is a real problem, and the fix is to start Orca and run it again.
+one exception is an error with no findings: that is a real problem. Tell them
+the error as it is. When it says Orca is not answering, run the Orca line from
+step 1 again, and go by what that gives: start Orca only when it answers that
+Orca is not running.
 
 Relay what it says in plain words. Nothing it prints is a verdict: which findings
 matter is for them, or for Bot Father, to judge. If something looks wrong to you,

package/package.json

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

package/rules/mail.md

@@ -8,9 +8,9 @@ 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.
 
-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.
+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. Send the refusal to
+whoever adds your rules: your maker, your user or your fleet's manager.
 
 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

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

@@ -213,10 +213,14 @@ 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`, `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
+pause`, `obk restart`, `obk bot create`, `obk bot change`, `obk session add`,
+`obk session change`, `obk init` and `obk run`. A bot that still holds a rule that the
+kit gave every bot before and that is no longer in the set (`obk restart`,
+`obk bot create`, `obk bot change`, `obk session add`, `obk session change`,
+`obk session mail`, `obk session nudge`, or Orca's `orca orchestration check
+--run`) 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
@@ -241,7 +245,11 @@ out; the kit refuses it, and it refuses a rule of its own default set too. 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.
+bot's settings themselves. For a test run with a time limit, propose `obk run`
+with the real command after `--`, such as
+`Bash(<kit> run --timeout 300 -- go test:*)`: the kit refuses a rule for
+`perl -e 'alarm …'`, since perl runs whatever its arguments say. 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
@@ -284,26 +292,29 @@ sometimes. Read each screen with `<orca> terminal read --terminal <handle>
 --screen`, where `<handle>` is the terminal the kit named for the tab and
 `<orca>` is the Orca CLI the kit uses: `$OBK_ORCA` when that is set, and
 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`:
+`orca` can fail. Send each key as one `<orca> terminal send --terminal
+<handle> --text …`, with the return inside the text and no `--enter`. Where
+the Send cell names `obk` commands, send no keys: the kit answers that
+screen, by the commands below, the first for a long-lived session and the
+second for a temporary one.
 
 | 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.160.0 |
-| Codex's `Hooks need review` | `\x1b[B\r` | **Trust all and continue** | Codex 0.160.0 |
+| Codex's hooks review | `obk session trust-hooks`, `obk temp trust-hooks` | trust | Codex 0.160.0 |
 | Codex's `Where should the new conversation run?` | `\r` | **Current checkout** | Codex 0.160.0 |
 | 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; no return | Not yet proven, below |
-| The same, 2.1.289's list | `\x1b[B\r` | down, return: **2. Not now** | Not yet proven, below |
+| Claude Code's Teach form | `obk session answer`, `obk temp answer` | Esc | Not yet proven, below |
+| Its 2.1.289 list | `obk session answer`, `obk temp answer` | 2. 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.
+versions.
 Its update offer was proven on 0.156.1; 0.157.1 showed it with the selection on
 Update now, not pressed, and 0.158.0 offered 0.160.0, taken on 2026-10-02 by
 Bot Father's restarts.
@@ -314,8 +325,10 @@ shell history. Esc cancels it (Not now) in its code; that is not yet proven
 live, though the form was seen live twice on 2.1.283. On 2.1.278 it was a
 numbered list, answered with `2. Not now`, and on 2.1.289 it is one again:
 `1. Yes`, `2. Not now`, `3. Don't show again`, above the input box, its
-selection on 1. Yes (seen live, not answered, in #489). Go down to 2. Not now,
-read the screen, and only then return. Codex's hooks
+selection on 1. Yes (seen live, not answered, in #489). The kit goes down to
+2. Not now, reads the screen, and only then returns. On 2.1.302 it is the
+form again, with `Also scan shell history` on `false` and a foot that starts
+`←/→ to change` (seen live in #604); the kit sends it Esc too. 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,
@@ -324,15 +337,15 @@ conversation runs (0.156.1, 0.157.1, 0.158.0 and 0.160.0 all did); the answer is
 always the current checkout, the bot home, and never `2. New worktree`:
 the kit never makes a git worktree.
 
-The hooks review of a Codex temporary session you made yourself is the one
-exception: answer it with `obk temp trust-hooks --bots <bots> --name
+The hooks review of a Codex temporary session you made yourself is answered
+through the kit: answer it with `obk temp trust-hooks --bots <bots> --name
 <session>`, not with the keys. It reads the screen, chooses **Trust all and
 continue** only if the review is there, and checks that the review went. A
 permission rule can allow that one command, where it cannot allow keys sent
 into any tab. The same goes for Claude Code's `Teach auto mode` screen on a
 temporary session you made: answer it with `obk temp answer --bots <bots>
 --name <session>`. It answers only a shape in the table exactly as the kit
-knows it (Esc on the 2.1.283 form, 2. Not now on the 2.1.289 list, the return
+knows it (Esc on the 2.1.283 and 2.1.302 forms, 2. Not now on the 2.1.289 list, the return
 only after a second look), refuses any other screen, and checks that it went. The kit's
 default set allows it, as it allows `obk temp trust-hooks`.
 

package/skills/obk-grooming/SKILL.md

@@ -171,9 +171,10 @@ For a bot with its own memory, the report gets a short section:
 - **A proposed cut**, when it is near or over the limit: which entries could go
   or be merged, and why.
 
-A contradiction is not yours to fix. Send it to that bot's own session, as Bot
-Father's management session, whose pass this is: `obk message to --from
-bot-father/<its session> --to <bot>/<session>` gives the road. Where the road
+A contradiction is not yours to fix. Send it to that bot's own session, from
+your own session, for Bot Father's pass: `obk message to --to <bot>/<session>`,
+run in your own tab, gives the road. In a session's tab the kit sends only as
+that session (#570), so name no other with `--from`. Where the road
 is the mailbox, `obk message send` carries it, whatever you run on. Where it is
 an address, that road is Claude Code's own messaging, and it is yours only if
 you run on Claude Code yourself; if you do not, put the finding in your report

package/src/book.js

@@ -6,8 +6,9 @@
 // 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 { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { DatabaseSync } from 'node:sqlite';
 import { isDeepStrictEqual } from 'node:util';
 import { parse, stringify } from 'yaml';
@@ -85,11 +86,18 @@ function withHistoryListed(entry) {
  * is, never half of it, and a writer that dies leaves the old file in place:
  * the new text goes to a file of this process's own and is moved over the book,
  * which is one operation the file system either did or did not do.
+ *
+ * Whatever is already at that file's name is taken away and the file is made
+ * new, never written through: a session can leave a link there in its own bot
+ * folder, which would take the book's text out of it, and the move would make
+ * the book that link (#599). A link made there in between makes the write fail,
+ * and the old book stays whole.
  */
 export function writeBook(home, book) {
   const file = bookFile(home);
   const half = `${file}.${process.pid}.part`;
-  writeFileSync(half, `${HEADER}${stringify(book)}`);
+  rmSync(half, { force: true });
+  writeFileSync(half, `${HEADER}${stringify(book)}`, { flag: 'wx' });
   renameSync(half, file);
 }
 
@@ -171,17 +179,40 @@ function lockOn(file, waitMs, how = 'IMMEDIATE') {
   // 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.
+  //
+  // A session can write its bot's folder of locks, so a link, a FIFO or a
+  // folder may sit at the lock's name, and a lock taken through a link would
+  // make or write a file anywhere the kit may write (#605). So the kit opens
+  // the file itself without following a link, and SQLite opens it only if it
+  // is there and makes nothing. A link put at the name only while SQLite
+  // opens it is followed, and SQLite names the file it opened, so a file of
+  // any other name is closed before it is locked or written. And the turn
+  // ends with ROLLBACK, so SQLite never writes the file it locks.
+  //
+  // What is left, accepted by the architect on #605: SQLite reads the first
+  // 100 bytes of the file it opens before the kit can ask its name, so such a
+  // link can have a file outside read into SQLite's memory and dropped; and a
+  // FIFO put there that instant can hang the command. A lock taken by name
+  // cannot close that without a lock Node does not have.
   if (!heldHere.has(file)) {
     try {
       mkdirSync(path.dirname(file), { recursive: true });
-      closeSync(openSync(file, 'a'));
+      plainFile(file);
     } catch (error) {
       throw new LockNotWritable(file, error);
     }
   }
 
-  const db = new DatabaseSync(file);
+  let db;
+  try {
+    db = new DatabaseSync(new URL(`${pathToFileURL(file).href}?mode=rw`));
+  } catch (error) {
+    throw new LockNotWritable(file, error);
+  }
   try {
+    if (db.location() !== path.join(realpathSync(path.dirname(file)), path.basename(file))) {
+      throw new LockNotWritable(file, notPlain(`a link at it led SQLite to ${db.location()}`));
+    }
     // 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 = ${waitMs}`);
@@ -201,7 +232,7 @@ function lockOn(file, waitMs, how = 'IMMEDIATE') {
   return {
     release() {
       try {
-        db.exec('COMMIT');
+        db.exec('ROLLBACK');
       } finally {
         db.close();
         const left = heldHere.get(file) - 1;
@@ -212,6 +243,30 @@ function lockOn(file, waitMs, how = 'IMMEDIATE') {
   };
 }
 
+/**
+ * Make the lock file at `file` if it is not there, and open it for writing
+ * without following a link or waiting on a FIFO. Anything at the name but a
+ * plain file is refused.
+ */
+function plainFile(file) {
+  let fd;
+  try {
+    fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  } catch (error) {
+    // A link, a folder and a FIFO with no reader, in that order.
+    if (['ELOOP', 'EISDIR', 'ENXIO'].includes(error.code)) throw notPlain(error.code);
+    throw error;
+  }
+  try {
+    if (!fstatSync(fd).isFile()) throw notPlain('not a plain file');
+  } finally {
+    closeSync(fd);
+  }
+}
+
+const NOT_PLAIN = 'ENOTPLAIN';
+const notPlain = (message) => Object.assign(new Error(message), { code: NOT_PLAIN });
+
 /** How many turns this process holds on each lock file, by its path. */
 const heldHere = new Map();
 
@@ -256,11 +311,36 @@ const botLocks = (home) => {
  */
 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.`);
+    super(why.code === NOT_PLAIN
+      ? `something other than a plain file is at the name of the kit's lock ${file} (${why.message}), so the kit did not take the turn, and nothing was done. Remove ${file}; the kit makes it again.`
+      : `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;
   }
 }
 
+/**
+ * The right to change the bot's `bot.yaml` (#595), held from the read a command
+ * makes its change on until that change is written. Two commands that change
+ * one bot at the same time then each change what the other left, and neither
+ * change is lost.
+ *
+ * The book's kind of lock, on a file of its own beside the book's: `temp make`
+ * writes bot.yaml while it holds the book's, and nothing takes the book's while
+ * it holds this one, so neither waits on the other.
+ */
+export function takeBotTurn(home) {
+  const file = botLockFile(home);
+  try {
+    return lockOn(file, WAIT_MS);
+  } catch (error) {
+    if (error instanceof LockNotWritable) throw error;
+    throw new Error(`waited ${WAIT_MS / 1000} seconds for something else to finish writing ${path.join(home, 'bot.yaml')} and it did not (${error.message}). bot.yaml was not changed. Try again; if nothing is running, remove ${file}, which is where writers take their turn.`);
+  }
+}
+
+/** Beside the book's lock, with the bot's name: the lock files of its sessions carry one more part. */
+const botLockFile = (home) => path.join(botLocks(home), `${encodeURIComponent(path.basename(realpathSync(home)))}.bot.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
@@ -468,10 +548,11 @@ export function rememberSession(entry = {}, id, ended) {
 
 /**
  * The session entry once the id it held has turned out to have no conversation
- * behind it: the id goes into the history with that reason, and the entry holds
- * none until the harness names the new one.
+ * behind it on the session's harness: the id goes into the history with that
+ * reason, and anything else worth knowing about it, such as the harness it ran
+ * on, and the entry holds none until the harness names the new one.
  */
-export function forgetSession(entry, ended) {
+export function forgetSession(entry, ended, more = {}) {
   const { session, ...rest } = entry;
-  return { ...rest, history: [...(entry.history ?? []), { session, ended, at: new Date().toISOString() }] };
+  return { ...rest, history: [...(entry.history ?? []), { session, ended, ...more, at: new Date().toISOString() }] };
 }