@assuredloop/orca-bot-kit 0.29.0 → 0.31.0

package/README.md

@@ -166,16 +166,18 @@ nobody asked: its own commands for this bots folder, reading a long message,
 `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
+`obk bot change`, `obk session add`, `obk session change` and `obk init` 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 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.
+`orca orchestration check --run`. So does a bot that holds a rule you allowed
+for the kit's `run` command, which the kit no longer has. `obk rules build` and
+`obk up` name each such rule, 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
@@ -680,82 +682,7 @@ fleet at all. Turn it off for a session with your own
 the kit will report that session as out of reach of fleet mail rather than
 failing quietly.
 
-## Working on the kit
+## Contributing
 
-```sh
-npm test                      # the whole suite, in a few minutes
-npm run test:system           # what the system tests would drive, and nothing else
-npm run test:system -- --yes  # drive them, on this machine, for real
-npm run test:system -- --yes test/system/groom.test.js  # only the ones you name
-npm run mutate                # the mutation audit, on what your branch changed
-```
-
-The tests come in two layers, and every test file belongs to one of them.
-
-`npm test` is `test/*.test.js` and `test/dev/*.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, 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. The floor leaves out `test/dev/`, the
-tests that need a development tool.
-
-`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,
-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. 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.
-
-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,
-which Orca, which files, and what they will do to it — and then stops without
-driving any of it, answering non-zero so that a run which did not run them
-cannot be read as one that passed. `-- --yes` is how you say you meant it. When
-Orca is not answering, the command says which Orca it asked and skips, rather
-than report a kit that is not broken. Name files after it to run only those;
-each must be one of the `*.test.js` files under `test/system/`, links followed,
-and a name that is not is refused before anything runs. This command is the
-only way in: a system test loaded any other way, with `node --test` or an
-editor's runner, skips and says how to run it.
-
-`npm run mutate` runs [StrykerJS](https://stryker-mutator.io) over the
-JavaScript this branch changed against `main` — committed, still in the working
-tree, or not tracked yet — and reports the mutants the tests do not kill. It is
-an audit, not a step of every pull request
-([PRD 7.3](docs/prd/prd.md#prd-21-73-decided-rules-inside-the-skills)): the everyday
-check is the implementer's own hand check, and the tool runs over the whole
-suite at a milestone or when the owner asks, or once, narrowed to the changed
-logic, for a change at the core of the kit. A surviving mutant is a change to
-the code that no test objects to. It is worth a test only where it shows a gap
-in behaviour the requirement cares about, and that test is written by the
-separate test author. Name targets yourself to check a whole area instead:
-
-```sh
-npm run mutate -- 'src/**/*.js'
-```
-
-Every mutant means running the tests again, so the check does not run them the
-way `npm test` does. It runs [`scripts/mutation-suite.js`](scripts/mutation-suite.js)
-instead: the same test files, one at a time, stopping at the first file that
-fails, trying the file that killed the last mutant first and then the quickest.
-On a ten-core machine, `src/up.js` as it was when this was measured (128 lines,
-76 mutants) took about twelve minutes that way. Running the whole suite for every mutant, as it used to, took
-forty, and counted a mutant as killed whenever a run of it ran out of time. A
-change across several files takes proportionally longer, so check one or two at
-a time.
-
-The check still takes minutes where the suite takes seconds, which is why it is
-a command of its own. StrykerJS is a development dependency of this repo, pinned
-to an exact version and needing Node 22 or newer; the kit itself neither ships
-it nor needs it.
+How to run the kit's own tests, and how they are laid out, is in
+[CONTRIBUTING.md](CONTRIBUTING.md). The package does not ship it.

package/SETUP.md

@@ -144,8 +144,8 @@ Read everything it prints. Three parts of it matter to them:
   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`, `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;
+  `obk bot change`, `obk session add`, `obk session change` and `obk init` 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
@@ -218,7 +218,7 @@ answers that screen, by the command and its arguments below the table.
 | 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?` | `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'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 the foot starts `←/→ to change usage`, and on 2.1.302 it starts `←/→ to change`. The values after the three settings can differ: `Also scan shell history` showed `true` on 2.1.283, and both `false` and `true` on 2.1.302. The kit sends Esc whatever the values are. **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 twice, in #604 and in #646, where it showed `Also scan shell history` on `true` and one Esc sent by hand removed it |
 | 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.
@@ -248,7 +248,7 @@ rule to type into any tab. On Codex's hooks review, the maker runs
 `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
 shapes in the table exactly as the kit knows it: Esc for the 2.1.283 and
-2.1.302 forms, and
+2.1.302 forms, whatever values their settings show, 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.

package/package.json

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

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

@@ -214,12 +214,13 @@ 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`, `obk bot change`, `obk session add`,
-`obk session change`, `obk init` and `obk run`. A bot that still holds a rule that the
+`obk session change` and `obk init`. 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
+--run`) keeps it, and so does a bot that holds a rule the user allowed for the
+kit's `run` command, which the kit no longer has. `obk rules build` and `obk up`
+name each such rule 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.
 
@@ -245,11 +246,7 @@ 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. 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.
+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
@@ -328,7 +325,9 @@ numbered list, answered with `2. Not now`, and on 2.1.289 it is one again:
 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
+`←/→ to change` (seen live in #604), and later with it on `true` (#646). The
+values of its three settings can differ, and the kit sends it Esc whatever
+they are. 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,

package/src/bot.js

@@ -8,7 +8,6 @@
 // writes nothing, rather than leave a bot half made or a bot.yaml half edited.
 
 import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { isSeq, parse, parseDocument, stringify } from 'yaml';
@@ -133,25 +132,6 @@ function whereItLeads(target) {
 export const displayName = (name) =>
   name.split('-').map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
 
-/**
- * What Orca is asked to call a bot's project. A fleet whose bots folder is under
- * the system's temp folder, as a system test's or a live check's is, gets a mark
- * and the name of the first folder under the temp folder, so its Bot Father is
- * never taken for the owner's in Orca's sidebar (#401). Every other fleet's
- * project is called what it always was. Tab titles keep `displayName` either way.
- */
-export function projectName(bots, name) {
-  let under;
-  try {
-    under = path.relative(realpathSync(os.tmpdir()), realpathSync(bots));
-  } catch {
-    return displayName(name);
-  }
-  // The temp folder itself, or anywhere outside it, is not a throwaway fleet's.
-  if (under === '' || under === '..' || under.startsWith(`..${path.sep}`) || path.isAbsolute(under)) return displayName(name);
-  return `${displayName(name)} · temp fleet ${under.split(path.sep)[0]}`;
-}
-
 /**
  * A bot's own file: which harness its sessions run on unless they say
  * otherwise, and the sessions it keeps.

package/src/cli.js

@@ -21,7 +21,7 @@ import { nameSession } from './name.js';
 import { APPROVALS, harnessOf, HARNESSES, ownCli, refuseApprovalArgs, shellWord, workDirOf } from './launch.js';
 import { checkMail, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE, TERMINAL_ENV } from './orca.js';
-import { allowIn, beyondDefaults, botDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
+import { allowIn, beyondDefaults, botDefaults, isRunRule, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -34,7 +34,6 @@ import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
 import { addSource, fetchSources } from './sources.js';
 import { answerSession, answerTemp, listRoles, makeTemp, optionsLine, retireTemp, trustHooks, trustSessionHooks } from './temp.js';
 import { readUsage } from './usage.js';
-import { parseRun, runBounded } from './run.js';
 import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 
 const USAGE = `obk — Orca Bot Kit.
@@ -327,22 +326,13 @@ Usage:
                             For the kit's own launch line, not for typing: run
                             in the session's own tab, it gives the session its
                             mailbox, or binds the one it has, to that tab.
-  obk run --timeout <seconds> -- <command> [<arg> ...]
-                            Run one command with a hard time limit, with no
-                            shell, and exit with its exit code. When the time
-                            runs out, it stops the command and everything it
-                            started (SIGTERM, then SIGKILL after 3 s), says so
-                            on stderr, and exits 124. A command it cannot find
-                            exits 127. A rule can allow it for one command,
-                            such as Bash(obk run --timeout 300 -- go test:*).
-                            It needs no --bots, and takes no --json.
   obk --version             Print the kit's version.
   obk --help                Print this text.
 
 Every command is safe to run again. Most only add what is missing; the ones
 that close a tab or take something away say so above. Every bot is allowed
-the kit's commands by default, except obk permission, retire, pause, init and
-run, which keep the user's yes.
+the kit's commands by default, except obk permission, retire, pause and init,
+which keep the user's yes.
 Add --json to any of them for the same answer as JSON.
 
 For another build of Orca, OBK_ORCA names its CLI, and OBK_ORCA_DATA the full
@@ -396,10 +386,6 @@ function version() {
 }
 
 async function run(argv) {
-  // What follows `obk run --timeout <n> --` is the command's own, flags and
-  // all, so it is read by `run` alone, before the kit reads its flags (#532).
-  if (argv[0] === 'run') return runBounded(parseRun(argv.slice(1)));
-
   const { values, positionals, tokens } = parseArgs({
     args: argv,
     allowPositionals: true,
@@ -1819,7 +1805,7 @@ function permissionsLines(permissions, bots) {
     ...(entry.trouble === undefined ? [] : [`${'refused'.padEnd(9)}  ${entry.trouble}`]),
     ...(listed.has(entry.bot) || !listed.add(entry.bot) ? [] : [
       ...(entry.defaults ?? []).map((rule) => `${'allowed'.padEnd(9)}  ${entry.bot}  ${rule}`),
-      ...(entry.held ?? []).map((rule) => `${'holds'.padEnd(9)}  ${entry.bot}  ${rule}, which is no longer one of the kit's defaults. To take it back:  ${disallow(entry.bot, rule)}`),
+      ...(entry.held ?? []).map((rule) => `${'holds'.padEnd(9)}  ${entry.bot}  ${rule}, ${isRunRule(rule) ? 'which is for obk run, a command the kit no longer has' : "which is no longer one of the kit's defaults"}. To take it back:  ${disallow(entry.bot, rule)}`),
     ]),
     ...(entry.written.length === 0
       ? []

package/src/commands.js

@@ -46,7 +46,6 @@ export const COMMANDS = {
   'temp retire': ['bots', 'name'],
   'temp trust-hooks': ['bots', 'name'],
   'temp answer': ['bots', 'name'],
-  run: ['timeout'],
 };
 
 /**
@@ -69,14 +68,12 @@ export const DEFAULT_COMMANDS = [
  * The commands kept out of the default permission set, which keep the user's
  * yes (ADR 0051): the ones that change permissions, close a long-lived
  * session, make the bots folder, or make or change a bot or its sessions,
- * which the owner leaves to Bot Father (#548, #615); and `run`, which runs
- * whatever its arguments say, so a rule for it names its command (#532).
+ * which the owner leaves to Bot Father (#548, #615).
  */
 export const KEPT_BACK = [
   'init', 'retire', 'pause', 'restart', 'bot create',
   'bot change', 'session add', 'session change',
   'permission allow', 'permission disallow', 'permission approval',
-  'run',
 ];
 
 /**
@@ -87,8 +84,8 @@ export const KEPT_BACK = [
 export const NO_LONGER_DEFAULT = ['restart', 'bot create', 'bot change', 'session add', 'session change'];
 
 /**
- * The commands kit 0.26.0 gave every bot by default and that the kit no longer
- * has (#555). A bot may still hold their rules, which the kit names and leaves
- * (#564).
+ * The commands the kit no longer has: the two kit 0.26.0 gave every bot by
+ * default (#555), and `run` (#532), which #652 took out of the kit. A bot may
+ * still hold their rules, which the kit names and leaves (#564).
  */
-export const REMOVED = ['session mail', 'session nudge'];
+export const REMOVED = ['session mail', 'session nudge', 'run'];

package/src/orca.js

@@ -381,8 +381,8 @@ function askRuntime(method, params, killMs = CLIENT_KILL_MS) {
 
 const RUNTIME_SCRIPT = fileURLToPath(new URL('./orca-runtime.cjs', import.meta.url));
 
-/** The `osascript` this run asks. OBK_OSASCRIPT overrides it, as OBK_PS does `ps`. */
-const osascriptCli = () => process.env.OBK_OSASCRIPT || '/usr/bin/osascript';
+/** The `osascript` the kit asks, by its fixed path: no setting changes it (#652). */
+const OSASCRIPT = '/usr/bin/osascript';
 
 /** How long macOS is given to click the menu item. */
 const RELOAD_KILL_MS = 5000;
@@ -406,7 +406,7 @@ export function reloadWindow() {
   try {
     // <Orca.app>/Contents/Resources/bin/orca, often reached through a link.
     const app = path.resolve(realpathSync(orcaCli()), '..', '..', '..', '..');
-    const asked = spawnSync(osascriptCli(), [RELOAD_SCRIPT, app], {
+    const asked = spawnSync(OSASCRIPT, [RELOAD_SCRIPT, app], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: RELOAD_KILL_MS,
@@ -741,8 +741,8 @@ export function frontOfTab(handle) {
   return frontOf(handle, shown?.ptyId);
 }
 
-/** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
-export const psCli = () => process.env.OBK_PS || '/bin/ps';
+/** The `ps` the kit reads, by its fixed path: no setting changes it (#652). */
+export const PS = '/bin/ps';
 
 /**
  * Who holds the terminal of the tab `handle`, whose pane is `ptyId`:
@@ -838,9 +838,9 @@ function panePid(ptyId, readMs) {
   return { pane };
 }
 
-/** The `lsof` and `stty` this run asks. OBK_LSOF and OBK_STTY override them, as OBK_PS does `ps`. */
-export const lsofCli = () => process.env.OBK_LSOF || '/usr/sbin/lsof';
-const sttyCli = () => process.env.OBK_STTY || '/bin/stty';
+/** The `lsof` and `stty` the kit asks, by their fixed paths, as `ps`. */
+export const LSOF = '/usr/sbin/lsof';
+const STTY = '/bin/stty';
 
 /**
  * One look at the shell of a tab the kit has just opened, before anything is
@@ -893,7 +893,7 @@ export function shellInTab(handle, until) {
  * or as the pane itself where the pane is the shell.
  */
 function ttyMode(pid, left) {
-  const listed = spawnSync(lsofCli(), ['-a', '-R', '-d', '0', '-u', String(process.getuid()), '-FpRn'], { encoding: 'utf8', timeout: left() });
+  const listed = spawnSync(LSOF, ['-a', '-R', '-d', '0', '-u', String(process.getuid()), '-FpRn'], { encoding: 'utf8', timeout: left() });
   if (listed.error?.code === 'ETIMEDOUT') return { unreadable: 'lsof did not answer in time', late: true };
   if (listed.error || listed.status !== 0) return { unreadable: `lsof could not list the processes' ttys` };
   // One record per process: `p<pid>`, `R<parent pid>`, `f0`, `n<name>`.
@@ -906,7 +906,7 @@ function ttyMode(pid, left) {
   }
   if (tty === undefined) return { unreadable: `lsof named no tty for the shell of its pane, pid ${pid}` };
 
-  const read = spawnSync(sttyCli(), ['-a', '-f', tty], { encoding: 'utf8', timeout: left() });
+  const read = spawnSync(STTY, ['-a', '-f', tty], { encoding: 'utf8', timeout: left() });
   if (read.error?.code === 'ETIMEDOUT') return { unreadable: `stty did not answer in time for ${tty}`, late: true };
   if (read.error || read.status !== 0) return { unreadable: `stty could not read ${tty}` };
   const words = read.stdout.split(/\s+/);
@@ -926,14 +926,14 @@ function ttyMode(pid, left) {
  * looks for one whole word it knows.
  */
 export function wordsOfProcess(pid) {
-  const asked = spawnSync(psCli(), ['-E', '-ww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+  const asked = spawnSync(PS, ['-E', '-ww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
   if (asked.error || asked.status !== 0) return undefined;
   return asked.stdout.trim().split(/\s+/);
 }
 
 /** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, `{ late: true }` past `readMs`, or undefined. */
 function psLine(pid, readMs) {
-  const asked = spawnSync(psCli(), ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8', ...(readMs === undefined ? {} : { timeout: readMs }) });
+  const asked = spawnSync(PS, ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8', ...(readMs === undefined ? {} : { timeout: readMs }) });
   if (asked.error?.code === 'ETIMEDOUT') return { late: true };
   if (asked.error || asked.status !== 0) return undefined;
   const line = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(.+?)\s*$/.exec(asked.stdout);

package/src/permissions.js

@@ -59,18 +59,34 @@ export function defaultRules(bots, cli = ownCli()) {
  */
 const ORCA_CHECK = 'Bash(orca orchestration check --run:*)';
 
+/**
+ * Whether a rule is one for `obk run` (#532), which #652 took out of the kit:
+ * the kit, then `run`. The kit is its CLI as `permission allow` recorded it,
+ * the bare `obk` that `obk run`'s own help spelled, or any path to an `obk`,
+ * quoted or not. A rule for it named the command after `--`, so it is known by
+ * its first two shell words.
+ */
+export function isRunRule(rule, cli = ownCli()) {
+  const text = /^Bash\((.*)\)$/s.exec(rule)?.[1];
+  const [kit, word] = (text === undefined ? undefined : shellWords(text).words) ?? [];
+  if (kit === undefined || word === undefined) return false;
+  return (kit === cli || path.basename(kit) === 'obk') && (word === 'run' || word.startsWith('run:'));
+}
+
 /**
  * The rules that were defaults once and are not now, that the bot's `allow`
  * holds: those of the commands kept back (#548, #615) or gone from the kit (#555),
- * spelled as `defaultRules` spelled them, and Orca's check (#564). The kit
- * cannot tell its own old entry from a user's yes to the same rule, so it
+ * spelled as `defaultRules` spelled them, and Orca's check (#564); and any rule
+ * for `obk run`, which the user allowed and the kit no longer has (#652). The
+ * kit cannot tell its own old entry from a user's yes to the same rule, so it
  * names them and leaves them (ADR 0051, ADR 0050).
  */
 export function heldRules(bots, home, bot, cli = ownCli()) {
   const allowed = allowOf(home, bot);
-  return [...NO_LONGER_DEFAULT, ...REMOVED].map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+  const spelled = [...NO_LONGER_DEFAULT, ...REMOVED].map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
     .concat(ORCA_CHECK)
     .filter((rule) => allowed.includes(rule));
+  return [...new Set([...spelled, ...allowed.filter((rule) => isRunRule(rule, cli))])];
 }
 
 /** Command wrappers: programs that run the command their arguments name. */
@@ -165,14 +181,12 @@ function commandBroadness(all) {
   if (star === -1) return undefined;
 
   const program = path.basename(words[0].replace(/:?\*.*$/, ''));
-  if (isKit(words[0]) && mayRun(words[1] ?? '')) return runBroadness(words);
   if (runnerOf(program) !== undefined) {
     // Only what runs, fixed by its absolute path, narrows it. A wrapper's
-    // program is then judged by itself; an interpreter's script is the end,
-    // unless it is the kit, which is judged as the kit.
+    // program is then judged by itself; an interpreter's script is the end.
     const next = (words[1] ?? '').replace(/:\*$/, '');
     const fixed = next.startsWith('/') && !next.includes('*');
-    if (fixed && (WRAPPERS.has(program) || isKit(next))) return commandBroadness(words.slice(1));
+    if (fixed && WRAPPERS.has(program)) return commandBroadness(words.slice(1));
     if (fixed && runnerOf(path.basename(next)) === undefined) return undefined;
     return `${program} runs whatever its arguments say, so ${ANY}`;
   }
@@ -185,37 +199,6 @@ function commandBroadness(all) {
   return undefined;
 }
 
-/** Whether a word is the kit's CLI: `obk` by its name, or the path the kit runs as. */
-const isKit = (word) => path.basename(word) === 'obk' || word === ownCli();
-
-/**
- * Whether a rule's word can match `run`: Claude's `*` matches any characters,
- * spaces too, so `ru*` matches `run --timeout 1 -- sh`, while `:*` matches
- * only at the end of a word.
- */
-function mayRun(word) {
-  const star = word.indexOf('*');
-  if (star === -1) return word === 'run';
-  const before = word.slice(0, star);
-  return before.endsWith(':') ? before === 'run:' : 'run'.startsWith(before);
-}
-
-/**
- * Why a rule for `obk run`, as shell words, is broad, or undefined (#532). It
- * runs whatever its arguments say, so only a fixed time limit, `--`, and a
- * command after it that is narrow as a rule of its own narrow it.
- */
-function runBroadness(words) {
-  const [, , ...rest] = words;
-  let command;
-  if (rest[0] === '--timeout' && /^\d+$/.test(rest[1] ?? '') && rest[2] === '--') command = rest.slice(3);
-  if (/^--timeout=\d+$/.test(rest[0] ?? '') && rest[1] === '--') command = rest.slice(2);
-  if (words[1] !== 'run' || command === undefined || command.length === 0) {
-    return `obk run runs whatever its arguments say, so ${ANY}. A rule for it names the command after --, such as Bash(obk run --timeout 300 -- go test:*)`;
-  }
-  return commandBroadness(command);
-}
-
 /**
  * Refuse the rules `permission allow` was given when any is broad, before anything is
  * written, naming the file the user can add it to themselves.

package/src/processes.js

@@ -19,19 +19,18 @@
 // signals: SIGTERM first, to the whole group where every process in it is the
 // session's own, then up to 3 seconds for them to end, then SIGKILL to each
 // that still runs. Inside Codex's sandbox `ps` does not start (#298), and then
-// nothing is stopped and the answer says it cannot tell. OBK_PS, OBK_LSOF and
-// OBK_KILL override the three, as OBK_ORCA does Orca, so the suite runs on
-// fakes and sends no real signal.
+// nothing is stopped and the answer says it cannot tell. The kit runs the three
+// by their fixed paths, and no setting changes them (#652).
 
 import { spawnSync } from 'node:child_process';
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 
-import { lsofCli, psCli } from './orca.js';
+import { LSOF, PS } from './orca.js';
 
-/** The `kill` this run sends signals with. OBK_KILL overrides it. */
-const killCli = () => process.env.OBK_KILL || '/bin/kill';
+/** The `kill` the kit sends signals with, by its fixed path. */
+const KILL = '/bin/kill';
 
 /** How long one `ps`, `lsof` or `kill` may take. */
 const READ_MS = 10_000;
@@ -273,7 +272,7 @@ function readProcesses() {
  * READ_MS.
  */
 function workingFolders(ms = READ_MS) {
-  const asked = spawnSync(lsofCli(), ['-a', '-d', 'cwd', '-u', String(process.getuid()), '-Fpn'], { encoding: 'utf8', timeout: bound(ms), maxBuffer: 64 * 1024 * 1024 });
+  const asked = spawnSync(LSOF, ['-a', '-d', 'cwd', '-u', String(process.getuid()), '-Fpn'], { encoding: 'utf8', timeout: bound(ms), maxBuffer: 64 * 1024 * 1024 });
   if (asked.error?.code === 'ETIMEDOUT') return { unreadable: 'lsof did not answer in time' };
   if (asked.error || asked.status !== 0) return { unreadable: `lsof could not list the processes' working folders${because(asked)}` };
   const cwds = new Map();
@@ -292,7 +291,7 @@ function workingFolders(ms = READ_MS) {
  * own command line (review of PR #543). Or `{ unreadable: <why> }`.
  */
 function processTable(ms = READ_MS) {
-  const asked = spawnSync(psCli(), ['-A', '-ww', '-o', 'pid=,ppid=,pgid=,uid=,stat=,lstart=,command='], { encoding: 'utf8', timeout: bound(ms), maxBuffer: 64 * 1024 * 1024 });
+  const asked = spawnSync(PS, ['-A', '-ww', '-o', 'pid=,ppid=,pgid=,uid=,stat=,lstart=,command='], { encoding: 'utf8', timeout: bound(ms), maxBuffer: 64 * 1024 * 1024 });
   if (asked.error?.code === 'ETIMEDOUT') return { unreadable: 'ps did not answer in time' };
   if (asked.error || asked.status !== 0) return { unreadable: `ps could not read the process table${because(asked)}` };
   const table = new Map();
@@ -383,7 +382,7 @@ const inside = (cwd, dir) => cwd === dir || cwd.startsWith(`${dir}${path.sep}`);
  */
 function signal(name, target, ms = READ_MS) {
   if (!Number.isInteger(target) || Math.abs(target) <= 1) return { refused: `the kit does not signal ${target}` };
-  const sent = spawnSync(killCli(), ['-s', name, '--', String(target)], { encoding: 'utf8', timeout: bound(ms) });
+  const sent = spawnSync(KILL, ['-s', name, '--', String(target)], { encoding: 'utf8', timeout: bound(ms) });
   // Cut off at its time: whether the signal went is not known.
   if (sent.error?.code === 'ETIMEDOUT') return { late: true };
   if (!sent.error && sent.status === 0) return {};

package/src/temp.js

@@ -530,10 +530,30 @@ const TEACH_TITLE = 'Teach auto mode about your environment?';
 /** The foot that ends a Claude Code form, below which its input box sits. */
 const TEACH_FOOT = /Enter to .*· Esc to cancel/;
 
+/**
+ * A setting row of the Teach form: its name, then spaces and a value. The value
+ * is whatever the setting shows, `Mixed`, `true` or `false` as read, and Esc
+ * cancels the form whatever it is (#646).
+ */
+const setting = (name) => ({ name, fits: (row) => row.startsWith(name) && /^ +\S/.test(row.slice(name.length)) });
+
+/** The Teach form's rows, from its title to its foot, with `foot`. */
+const teachForm = (foot) => [
+  TEACH_TITLE,
+  'Claude Code reads this project, your recent Claude sessions, and optionally your shell history and other',
+  'repositories. Claude analyzes this data and customizes auto mode to make better decisions.',
+  setting('How you use Claude here'),
+  setting('Also scan shell history'),
+  setting('Also scan your other repos'),
+  'Continue',
+  foot,
+];
+
 /**
  * The known shapes of the Teach screen, from its title to its foot, each as
  * captured live, with what answers it. Rows are compared trimmed, the pointer
- * `❯` taken out, so the pointer may sit on any one of them.
+ * `❯` taken out, so the pointer may sit on any one of them. A setting row
+ * matches by its name, whatever its value.
  *
  * Claude Code 2.1.283's form (#261's live test, #416) and 2.1.302's (#604) are
  * answered with Esc, which cancels them (Not now), never a return, which is
@@ -542,34 +562,8 @@ const TEACH_FOOT = /Enter to .*· Esc to cancel/;
  * architect's ruling on #489).
  */
 const TEACH_SHAPES = [
-  {
-    name: 'the 2.1.283 form',
-    rows: [
-      TEACH_TITLE,
-      'Claude Code reads this project, your recent Claude sessions, and optionally your shell history and other',
-      'repositories. Claude analyzes this data and customizes auto mode to make better decisions.',
-      'How you use Claude here     Mixed',
-      'Also scan shell history     true',
-      'Also scan your other repos  false',
-      'Continue',
-      '←/→ to change usage · Enter to continue · Esc to cancel',
-    ],
-    escape: true,
-  },
-  {
-    name: 'the 2.1.302 form',
-    rows: [
-      TEACH_TITLE,
-      'Claude Code reads this project, your recent Claude sessions, and optionally your shell history and other',
-      'repositories. Claude analyzes this data and customizes auto mode to make better decisions.',
-      'How you use Claude here     Mixed',
-      'Also scan shell history     false',
-      'Also scan your other repos  false',
-      'Continue',
-      '←/→ to change · Enter to continue · Esc to cancel',
-    ],
-    escape: true,
-  },
+  { name: 'the 2.1.283 form', rows: teachForm('←/→ to change usage · Enter to continue · Esc to cancel'), escape: true },
+  { name: 'the 2.1.302 form', rows: teachForm('←/→ to change · Enter to continue · Esc to cancel'), escape: true },
   {
     name: 'the 2.1.289 list',
     rows: [
@@ -589,6 +583,12 @@ const NOT_NOW_CHOICE = '2. Not now';
 /** A row as a shape is compared: trimmed, with its pointer, wherever it sits, taken out. */
 const unpointed = (row) => row.replace('❯', ' ').trim();
 
+/** Whether a shape's row `want` is the screen's `row`, as unpointed gives it. */
+const fitsRow = (want, row) => (typeof want === 'string' ? row === want : want.fits(row));
+
+/** A shape's row as a refusal names it. */
+const shapeRow = (want) => (typeof want === 'string' ? want : `${want.name} and a value`);
+
 /** The full-width rule Claude Code draws right above the screen's title: `─` in 2.1.289, `▔` in 2.1.283. */
 const ABOVE_TITLE = /^(?:─+|▔+)$/;
 
@@ -622,13 +622,13 @@ function teachScreen(rows) {
   const misfits = TEACH_SHAPES.map((shape) => {
     const pointers = block.filter((row) => row.includes('❯')).length;
     if (pointers !== 1) return `${pointers} rows with the pointer ❯, where ${shape.name} has one`;
-    const odd = block.find((row) => !shape.rows.includes(unpointed(row)));
+    const odd = block.find((row) => !shape.rows.some((want) => fitsRow(want, unpointed(row))));
     if (odd !== undefined) return `a row ${shape.name} does not have: ${odd.trim()}`;
-    const missing = shape.rows.find((row) => !block.map(unpointed).includes(row));
-    if (missing !== undefined) return `no row ${missing}, which ${shape.name} has`;
+    const missing = shape.rows.find((want) => !block.some((row) => fitsRow(want, unpointed(row))));
+    if (missing !== undefined) return `no row ${shapeRow(missing)}, which ${shape.name} has`;
     if (block.length !== shape.rows.length) return `${block.length} rows, where ${shape.name} has ${shape.rows.length}`;
-    const moved = block.findIndex((row, at) => unpointed(row) !== shape.rows[at]);
-    if (moved >= 0) return `the row ${block[moved].trim()} where ${shape.name} has ${shape.rows[moved]}`;
+    const moved = block.findIndex((row, at) => !fitsRow(shape.rows[at], unpointed(row)));
+    if (moved >= 0) return `the row ${block[moved].trim()} where ${shape.name} has ${shapeRow(shape.rows[moved])}`;
     return undefined;
   });
   const fits = misfits.findIndex((misfit) => misfit === undefined);
@@ -642,7 +642,7 @@ const wholeScreen = (rows) => rows.filter((row) => row.trim() !== '').map((row)
 /**
  * Answer the first-run screen of a temporary session the caller made (#489):
  * Claude Code's Teach auto mode screen, in one of the shapes the kit knows,
- * matched exactly. The 2.1.283 and 2.1.302 forms get Esc. The 2.1.289 list gets arrows to
+ * matched exactly. The 2.1.283 and 2.1.302 forms get Esc, whatever their settings show. The 2.1.289 list gets arrows to
  * "2. Not now" where needed, a second look that the pointer is there and the
  * list is otherwise as it was, and only then a return. Anything else is refused with
  * nothing typed. Like `trustHooks`, it is one command a permission rule of its

package/src/up.js

@@ -10,7 +10,7 @@ import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
 import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, rememberSession, sessionIdsIn, tabIdsIn, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS, updateBook, withUnclaimed } from './book.js';
-import { botDir, botNames, displayName, projectName, readBot } from './bot.js';
+import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { dropRemovedHooks, installHook } from './hooks.js';
 import { writePermissions } from './permissions.js';
@@ -233,7 +233,7 @@ async function bringUpBot(bots, home, bot, onlySession) {
   // Orca is asked first and the book is written after: nothing that takes time
   // happens while the book is held, because a session's own hook may be writing
   // its id into that same file at any moment.
-  const { change, ...orca } = orcaProject(home, projectName(bots, name));
+  const { change, ...orca } = orcaProject(home, title);
   await updateBook(home, (book) => { book.orca = orca; });
   // Orca's window does not see a project made or renamed on the command line
   // until it is told (#224).

package/src/run.js

@@ -1,155 +0,0 @@
-// `obk run --timeout <seconds> -- <command…>`: one command run with a hard time
-// limit (#532). macOS has no `timeout`, and the fleet's form for a bounded run,
-// `perl -e 'alarm …; exec @ARGV' -- <command>`, cannot be allowed by a narrow
-// rule, since perl runs whatever its arguments say. A rule for this command
-// names the real command after `--`, and the kit judges that command as a rule
-// of its own (permissions.js). It runs whatever its arguments say too, so it is
-// never in the default set (ADR 0050).
-//
-// The command runs with no shell, in a process group of its own, so the time
-// limit stops what it started as well. Its exit code comes back as it is; one
-// ended by a signal the kit did not send comes back as 128 and the signal's
-// number, as a shell gives it.
-
-import { spawn } from 'node:child_process';
-import { constants } from 'node:os';
-
-/** The exit code of a run the time limit stopped, as GNU timeout gives it. */
-const TIMED_OUT = 124;
-
-/** The exit codes a shell gives a command it cannot find, and one it cannot run. */
-const NOT_FOUND = 127;
-const CANNOT_RUN = 126;
-
-/** How long the group has after SIGTERM before SIGKILL, as `retire` gives a session's processes (#537). */
-const GRACE_MS = 3000;
-
-/** How often the kit looks whether anything of the group still runs. */
-const LOOK_MS = 100;
-
-/** The longest time limit a timer holds, in seconds: about 24 days. */
-const LONGEST = Math.floor((2 ** 31 - 1) / 1000);
-
-/** The signals that end the kit and that it passes on to the command's group, so it is not left running. */
-const PASSED_ON = ['SIGINT', 'SIGTERM', 'SIGHUP'];
-
-const USE = 'obk run takes --timeout <seconds>, then --, then the command: obk run --timeout 300 -- go test ./...';
-
-/**
- * The time limit and the command from `obk run`'s arguments, or a refusal.
- * Only `--timeout` goes before `--`; everything after it is the command's.
- */
-export function parseRun(args) {
-  const end = args.indexOf('--');
-  const options = end === -1 ? args : args.slice(0, end);
-  let value;
-  for (let at = 0; at < options.length; at += 1) {
-    const option = options[at];
-    if (option === '--timeout' && at + 1 < options.length && value === undefined) {
-      value = options[at + 1];
-      at += 1;
-    } else if (option.startsWith('--timeout=') && value === undefined) {
-      value = option.slice('--timeout='.length);
-    } else {
-      throw new Error(`run does not take ${option}. ${USE}. Nothing was run.`);
-    }
-  }
-  if (value === undefined) throw new Error(`run needs --timeout <seconds>: how long the command may run. ${USE}. Nothing was run.`);
-  if (!/^\d+$/.test(value) || Number(value) === 0 || Number(value) > LONGEST) {
-    throw new Error(`run's --timeout is a whole number of seconds from 1 to ${LONGEST}, and got: ${value === '' ? 'nothing' : value}. Nothing was run.`);
-  }
-  const command = end === -1 ? [] : args.slice(end + 1);
-  if (command.length === 0) throw new Error(`run needs the command after --. ${USE}. Nothing was run.`);
-  return { seconds: Number(value), command };
-}
-
-/**
- * Run the command with its time limit, its input and output the caller's, and
- * give back the exit code `obk run` exits with. The run ends when nothing of
- * the command's group runs any more: a process the command started and left
- * running is held to the same limit, and to a signal the kit passes on.
- */
-export function runBounded({ seconds, command }) {
-  return new Promise((resolve) => {
-    // `detached` makes the command the leader of a group of its own, so its
-    // pid, taken here at spawn, is the group's id.
-    const child = spawn(command[0], command.slice(1), { stdio: 'inherit', detached: true });
-    // The leader's exit code, once it has exited.
-    let exitCode;
-    let stopping = false;
-    let result;
-    let killAt;
-    let deadline;
-    let look;
-    const signal = (pid, name) => {
-      try {
-        process.kill(pid, name);
-        return true;
-      } catch {
-        return false;
-      }
-    };
-    // Each process of the group gets a signal once. The leader gets it by its
-    // own pid as well only when it may have left the group: when nothing is
-    // left in the group, or for SIGKILL, which no handler sees. And only
-    // while it has not exited, since its pid is free again after that.
-    const group = (name) => {
-      const sent = signal(-child.pid, name);
-      if (exitCode === undefined && name !== 0 && (!sent || name === 'SIGKILL')) signal(child.pid, name);
-      return sent;
-    };
-
-    const finish = (code) => {
-      clearTimeout(deadline);
-      clearTimeout(look);
-      for (const name of PASSED_ON) process.off(name, passOn);
-      resolve(code);
-    };
-
-    // Once the leader has exited or the group is being stopped: look until
-    // nothing of the group runs, and send SIGKILL when the grace is over.
-    const watch = () => {
-      if (exitCode !== undefined && !group(0)) return finish(result ?? exitCode);
-      if (killAt !== undefined && Date.now() >= killAt) {
-        group('SIGKILL');
-        killAt = undefined;
-      }
-      look = setTimeout(watch, LOOK_MS);
-      return undefined;
-    };
-
-    // Stop the group: `name` first, then SIGKILL to what still runs after the
-    // grace. obk run exits with `code`, or with the leader's own when it is
-    // undefined.
-    const stop = (name, code) => {
-      if (stopping) return;
-      stopping = true;
-      result = code;
-      clearTimeout(deadline);
-      group(name);
-      killAt = Date.now() + GRACE_MS;
-      clearTimeout(look);
-      watch();
-    };
-    const passOn = (name) => stop(name, undefined);
-
-    child.on('error', (error) => {
-      const missing = error.code === 'ENOENT';
-      process.stderr.write(`obk: run could not start ${command[0]}: ${missing ? 'there is no such command' : error.code ?? error.message}.\n`);
-      finish(missing ? NOT_FOUND : CANNOT_RUN);
-    });
-    if (child.pid === undefined) return;
-    for (const name of PASSED_ON) process.on(name, passOn);
-
-    child.on('exit', (code, name) => {
-      exitCode = code ?? 128 + constants.signals[name];
-      clearTimeout(look);
-      watch();
-    });
-
-    deadline = setTimeout(() => {
-      process.stderr.write(`obk: run stopped ${command.join(' ')}: it ran past its time limit of ${seconds} seconds, and its whole process group was stopped.\n`);
-      stop('SIGTERM', TIMED_OUT);
-    }, seconds * 1000);
-  });
-}