@assuredloop/orca-bot-kit 0.28.0 → 0.29.0

package/README.md

@@ -166,8 +166,8 @@ 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` and `obk init` are
-not in the set, and keep your yes
+`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 a rule that the kit gave every bot
@@ -577,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

package/SETUP.md

@@ -54,7 +54,10 @@ 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
@@ -141,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` and `obk init` are
-  not in it and keep their yes;
+  `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

package/package.json

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

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

@@ -214,7 +214,7 @@ 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` and `obk init`. A bot that still holds a rule that the
+`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
@@ -245,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

package/src/cli.js

@@ -34,6 +34,7 @@ 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.
@@ -326,14 +327,28 @@ 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 and init,
-which keep the user's yes.
+the kit's commands by default, except obk permission, retire, pause, init and
+run, 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
+path of the folder it keeps its data in, such as
+$HOME/Library/Application Support/orca-lean.
+The kit reads Orca's launch arguments from the profiles folder there.
 `;
 
 
@@ -381,6 +396,10 @@ 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,

package/src/commands.js

@@ -46,6 +46,7 @@ export const COMMANDS = {
   'temp retire': ['bots', 'name'],
   'temp trust-hooks': ['bots', 'name'],
   'temp answer': ['bots', 'name'],
+  run: ['timeout'],
 };
 
 /**
@@ -68,12 +69,14 @@ 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).
+ * 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).
  */
 export const KEPT_BACK = [
   'init', 'retire', 'pause', 'restart', 'bot create',
   'bot change', 'session add', 'session change',
   'permission allow', 'permission disallow', 'permission approval',
+  'run',
 ];
 
 /**

package/src/health.js

@@ -26,7 +26,7 @@ import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bo
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
 import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, promptFile, sessionTrouble, set, SHELL_ENV, shellWord, workDirOf } from './launch.js';
-import { frontOfTab, orcaDefaultArgs, projects, runMissing, tabs, wordsOfProcess } from './orca.js';
+import { frontOfTab, mailIn, orcaDefaultArgs, projects, runMissing, tabs, tabToTypeInto, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
 import { processesIn } from './processes.js';
 import { TAB_ENV } from './record.js';
@@ -459,6 +459,12 @@ function inOrca(bots, home, bot, setups, sessions) {
       found.push(finding('session', bookFile(home), `${bot.name}'s session ${name} has the mailbox ${entry.mailbox} in the book, and Orca has no Run of that id: it was made by another Orca, as on another machine, so mail sent to it is refused. The session's next start makes it a new one: ${fix}`, bot.name));
     }
 
+    // Mail Orca has not told a running session of (#630). A session that is
+    // paused or whose tab is gone reads no mail by design, or is named above.
+    if (typeof entry?.mailbox === 'string' && there.has(entry.tab) && !closed.has(name)) {
+      found.push(...unannounced(bots, home, bot, name, entry));
+    }
+
     const unclaimed = (Array.isArray(entry?.unclaimed) ? entry.unclaimed : []).filter((id) => !helpers.has(id));
     if (unclaimed.length > 0) {
       found.push(finding('leftover', bookFile(home), `The book notes conversations under ${bot.name}'s session ${name} that no session of this bot claims: ${unclaimed.join(', ')}. They ran in this bot's folder, and the kit will not say whose they were. To give one back, write it into ${bookFile(home)} under ${name} as  session: <id>  and run obk up again.`, bot.name));
@@ -481,6 +487,70 @@ function inOrca(bots, home, bot, setups, sessions) {
   return found;
 }
 
+/** How old an unread letter Orca has not rung for is before it counts as waiting (#630). */
+const WAITING_MS = 60 * 60 * 1000;
+
+/** How long the look at a session's tab waits for its harness to be idle. */
+const IDLE_LOOK_MS = 2000;
+
+/** How many of a mailbox's newest letters health reads: one read, whatever the mailbox holds. */
+const MAIL_READ = 100;
+
+/**
+ * The session `name`'s mail that Orca has not told it of, while its harness is
+ * idle now: one finding, or none (#630). Orca rings only a tab whose harness it
+ * has seen go idle since Orca last started, so a session that sat idle through
+ * an Orca restart or update is never told (tech notes, section 1). A busy one
+ * is told when its turn ends, so it is not named. Only flags and times are
+ * read: a letter's subject and text are the session's own. A mailbox or a tab
+ * Orca will not answer about leaves it unsaid.
+ *
+ * One read of the newest letters (review of PR #632). Orca hands mail to its
+ * reader oldest first, so a full read whose oldest letter is read is taken to
+ * hold every unread one. That misses an older letter left unread below a letter
+ * `orca orchestration reply` marked read out of order; the kit never runs it.
+ * A full read whose oldest letter is unread may have more below it, and the
+ * finding says so rather than count what it did not read.
+ */
+function unannounced(bots, home, bot, name, entry) {
+  let mail;
+  try {
+    mail = mailIn(entry.mailbox, MAIL_READ);
+  } catch {
+    return [];
+  }
+  const before = Date.now() - WAITING_MS;
+  const waiting = mail
+    .filter((one) => one.read === 0 && one.delivered_at == null && Date.parse(one.created_at) < before)
+    .sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+  const last = mail.at(-1);
+  const more = mail.length >= MAIL_READ && last.read === 0;
+  // Unread and never rung for, with more of the mailbox below it.
+  const below = more && last.delivered_at == null;
+  if (waiting.length === 0 && !below) return [];
+
+  // The gate the kit's own keys go through tells an idle harness from a busy
+  // one, a question on its screen or a shell; only its answer is kept.
+  let look;
+  try {
+    look = tabToTypeInto(home, entry.tab, IDLE_LOOK_MS);
+  } catch {
+    return [];
+  }
+  if (look.handle === undefined || look.idle !== true) return [];
+
+  const count = `${more ? 'at least ' : ''}${waiting.length}`;
+  const letters = waiting.length === 1 && !more ? '1 letter' : `${count} letters`;
+  const read = `Health reads the newest ${MAIL_READ} letters of a mailbox, and the oldest of those is unread too, so older letters may wait as well.`;
+  const what = waiting.length === 0
+    ? `has mail in its mailbox ${entry.mailbox} that Orca has not told it of: the oldest of the newest ${MAIL_READ} letters, from ${last.created_at}, is unread, and Orca has not rung for it. Older letters may wait below it, which health does not read.`
+    : more
+      ? `has ${letters} in its mailbox ${entry.mailbox} that it has not read and that Orca has not told it of, each more than an hour old; the oldest of them that health read is from ${waiting[0].created_at}. ${read}`
+      : `has ${letters} in its mailbox ${entry.mailbox} that it has not read and that Orca has not told it of, the oldest from ${waiting[0].created_at}, more than an hour ago.`;
+  const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${name}`;
+  return [finding('mail', entry.mailbox, `${bot.name}'s session ${name} ${what} Its harness is idle now, and Orca tells an idle session of its mail within minutes, unless the session sat idle through an Orca restart or update: then Orca does not tell it until it takes a turn. ${restart} opens a new tab for it, which Orca tells. A restart drops what lives only in the old tab, such as Claude Code schedules, so the session makes them again.`, bot.name)];
+}
+
 /**
  * The conversations a harness has on record in this bot's folder that the book
  * does not name anywhere. The hook is how an id reaches the book, and when it

package/src/hooks.js

@@ -101,7 +101,7 @@ export function installHook(home, harness, { bots, bot }) {
   const started = withKitHook(settings.hooks, file, mine);
   // The Claude Code mail hook and the Codex nudge hook went with the kit's
   // typed line (#555), so an entry of either is taken out.
-  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, withoutHooks(started, [KIT_MAIL, KIT_NUDGE])) };
+  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, withoutHooks(started, REMOVED_HOOKS)) };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -112,6 +112,41 @@ export function installHook(home, harness, { bots, bot }) {
   return HOOK_FILE[harness];
 }
 
+/**
+ * Take the kit's hooks of commands it no longer has out of every hooks file the
+ * bot at `home` has, whatever its sessions run on now and whether or not it is
+ * paused (#613). `installHook` does this only for a harness a session runs on,
+ * so a file the kit wrote for a harness the bot has since left kept them.
+ * Returns the files it wrote, relative to the bot home.
+ *
+ * It adds nothing and changes no other entry. A file it cannot read, a hooks
+ * entry that is not a mapping of events, or a link out of the bot folder is
+ * left as it is: the kit cannot tell its entries there, and health and
+ * `installHook` speak for a harness that runs.
+ */
+export function dropRemovedHooks(home) {
+  return Object.values(HOOK_FILE).flatMap((relative) => {
+    const file = path.join(home, relative);
+    if (!existsSync(file) || outside(home, file) !== undefined) return [];
+    let settings;
+    try {
+      settings = readSettings(file);
+    } catch {
+      return [];
+    }
+    const { hooks } = settings;
+    if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) return [];
+    const kept = withoutHooks(hooks, REMOVED_HOOKS);
+    if (isDeepStrictEqual(hooks, kept)) return [];
+    try {
+      writeFileSync(file, `${JSON.stringify({ ...settings, hooks: kept }, null, 2)}\n`);
+    } catch (error) {
+      throw new Error(`${file} cannot be written (${error.code ?? error.message}), and it holds the kit's hook of a command the kit no longer has, which the kit takes out. Let the kit write it, then run the command again.`);
+    }
+    return [relative];
+  });
+}
+
 /**
  * Whether the kit's hook is in place for one harness, and what to say when it
  * is not: `{ where, says }`, or nothing when the file already holds it.
@@ -361,6 +396,7 @@ const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_MAIL = new RegExp(String.raw`^(${WORD}) session mail --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const REMOVED_HOOKS = [KIT_MAIL, KIT_NUDGE];
 
 /**
  * Whether a hook entry is one of the kit's own as this kit writes it: a

package/src/orca-reload.applescript

@@ -16,29 +16,28 @@
 on run argv
 	set appPath to item 1 of argv
 	tell application "System Events"
-		repeat with candidate in (every application process whose name is "Orca")
-			if POSIX path of application file of candidate is appPath then
-				tell candidate
-					-- Menu 1 is Apple's own.
-					repeat with b from 2 to count of menu bar items of menu bar 1
-						set m to menu 1 of menu bar item b of menu bar 1
-						set labels to name of menu items of m
-						repeat with i from 1 to count of labels
-							set label to item i of labels
-							if label is not missing value then
-								if label is "Force Reload" or label starts with ("Force Reload" & tab) or label ends with (tab & "⌘⇧R") then
-									-- Asked last, right before the click, so Orca has had no time to
-									-- lose the front since.
-									if frontmost of candidate is false then return "Orca is not the front app"
-									click menu item i of m
-									return "reloaded"
-								end if
+		-- By its path alone: another build of Orca has another name (#551).
+		repeat with candidate in (every application process whose POSIX path of application file is appPath)
+			tell candidate
+				-- Menu 1 is Apple's own.
+				repeat with b from 2 to count of menu bar items of menu bar 1
+					set m to menu 1 of menu bar item b of menu bar 1
+					set labels to name of menu items of m
+					repeat with i from 1 to count of labels
+						set label to item i of labels
+						if label is not missing value then
+							if label is "Force Reload" or label starts with ("Force Reload" & tab) or label ends with (tab & "⌘⇧R") then
+								-- Asked last, right before the click, so Orca has had no time to
+								-- lose the front since.
+								if frontmost of candidate is false then return "Orca is not the front app"
+								click menu item i of m
+								return "reloaded"
 							end if
-						end repeat
+						end if
 					end repeat
-				end tell
-				return "no Force Reload in Orca's menus"
-			end if
+				end repeat
+			end tell
+			return "no Force Reload in Orca's menus"
 		end repeat
 	end tell
 	return "no Orca running from " & appPath

package/src/orca.js

@@ -29,10 +29,11 @@ export const orcaCli = () => process.env.OBK_ORCA || BUILT_IN;
  * Run one Orca command and give back its `result`.
  * Every call asks for `--json`; anything else would be text to guess at.
  * With `timeoutMs`, Orca is given that long to answer, and the call is ended
- * and refused if it has not.
+ * and refused if it has not. With `whole`, an answer of any size is taken,
+ * where Node would otherwise stop at a megabyte (review of PR #632).
  */
-export function orca(args, { timeoutMs } = {}) {
-  const answer = ask(args, timeoutMs);
+export function orca(args, { timeoutMs, whole = false } = {}) {
+  const answer = ask(args, timeoutMs, whole);
   if (answer.ok !== true) {
     // Orca's own words: it knows what went wrong, and the caller is an LLM
     // that can act on them.
@@ -55,8 +56,12 @@ const refusal = (args, answer) => Object.assign(
 );
 
 /** One Orca command, and the whole envelope back, refusals included. */
-function ask(args, timeoutMs) {
-  const asked = spawnSync(orcaCli(), [...args, '--json'], { encoding: 'utf8', ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }) });
+function ask(args, timeoutMs, whole = false) {
+  const asked = spawnSync(orcaCli(), [...args, '--json'], {
+    encoding: 'utf8',
+    ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
+    ...(whole ? { maxBuffer: Infinity } : {}),
+  });
   if (asked.error?.code === 'ETIMEDOUT') {
     throw Object.assign(new Error(`Orca did not answer ${args.join(' ')} within ${timeoutMs / 1000} seconds.`), { code: TIMED_OUT });
   }
@@ -135,8 +140,16 @@ export function findProject(home) {
   return projects().find((setup) => setup.path === home);
 }
 
-/** Where Orca keeps its own settings: one file per profile, under the user's home. */
-export const profilesDir = () => path.join(homedir(), 'Library', 'Application Support', 'orca', 'profiles');
+/**
+ * Where Orca keeps its own settings: one file per profile, under the user's home.
+ * OBK_ORCA_DATA names the data folder of another build of Orca, as OBK_ORCA
+ * names its CLI: a build's folder is written only inside its own CLI, so the
+ * kit cannot tell it from the app (#551).
+ */
+export const profilesDir = () => path.join(
+  process.env.OBK_ORCA_DATA || path.join(homedir(), 'Library', 'Application Support', 'orca'),
+  'profiles',
+);
 
 /**
  * Orca's own default launch arguments, per profile it keeps:
@@ -1057,6 +1070,17 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
 export const readMailbox = (id, { peek = false, handle } = {}, options) =>
   orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])], options);
 
+/**
+ * The newest `limit` messages in a mailbox, newest first, with every column
+ * Orca keeps for them: `read` and `delivered_at` among them, which `check`
+ * leaves out. Orca asks no reader for this, so any tab can read any mailbox,
+ * and nothing is marked read or delivered (tech notes, section 1; #630). The
+ * answer carries each letter's whole text, and a local letter's text has no
+ * cap in Orca, so the answer is taken whatever its size.
+ */
+export const mailIn = (id, limit) =>
+  orca(['orchestration', 'inbox', '--terminal', `run:${id}`, '--limit', String(limit)], { whole: true }).messages ?? [];
+
 /** Say a batch has been read. Orca answers with the batch after it. */
 export const ackMailbox = (id, delivery, handle, options) =>
   orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery], options);

package/src/permissions.js

@@ -165,12 +165,14 @@ 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.
+    // program is then judged by itself; an interpreter's script is the end,
+    // unless it is the kit, which is judged as the kit.
     const next = (words[1] ?? '').replace(/:\*$/, '');
     const fixed = next.startsWith('/') && !next.includes('*');
-    if (fixed && WRAPPERS.has(program)) return commandBroadness(words.slice(1));
+    if (fixed && (WRAPPERS.has(program) || isKit(next))) return commandBroadness(words.slice(1));
     if (fixed && runnerOf(path.basename(next)) === undefined) return undefined;
     return `${program} runs whatever its arguments say, so ${ANY}`;
   }
@@ -183,6 +185,37 @@ 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.
@@ -220,6 +253,15 @@ export function allowOf(home, bot) {
 export const runsOnCodex = (bot) => bot.harness === 'codex'
   || bot.sessions.some((session) => harnessOf(session, bot.harness) === 'codex');
 
+/**
+ * Whether the kit keeps the bot's Codex rules file: while the bot runs on
+ * Codex, and after it has left Codex for as long as the file it wrote is
+ * there in the bot folder, so the file never holds a rule that `allow` no
+ * longer does (#613). A link out of the bot folder is not the kit's file.
+ */
+const keepsCodex = (bot, home) => runsOnCodex(bot)
+  || (existsSync(path.join(home, CODEX_FILE)) && leadsOutside(home, path.join(home, CODEX_FILE)) === undefined);
+
 /**
  * The default rules this bot is not allowed yet, in the default order. A bot
  * only on Codex is not given the Read rule: its sandbox reads every file
@@ -293,7 +335,7 @@ export function refuseNoCodexForm(bot, rules) {
  * not write is an entry with its `trouble` rather than a throw.
  */
 export function writePermissions(bots, home, bot, { keepGoing = false } = {}) {
-  const writers = [[runsOnClaude, FILE], [runsOnCodex, CODEX_FILE]].filter(([runs]) => runs(bot));
+  const writers = [[runsOnClaude, FILE], [keepsCodex, CODEX_FILE]].filter(([runs]) => runs(bot, home));
   let defaults = [];
   // Read before anything is written, so a file's trouble still names them.
   let held = [];
@@ -324,8 +366,8 @@ export function writePermissions(bots, home, bot, { keepGoing = false } = {}) {
  */
 export function allowIn(bots, home, bot) {
   refuseUnwritable(path.join(home, 'bot.yaml'));
-  const plans = [[runsOnClaude, planClaude], [runsOnCodex, planCodex]]
-    .filter(([runs]) => runs(bot)).map(([, plan]) => plan(bots, home, bot));
+  const plans = [[runsOnClaude, planClaude], [keepsCodex, planCodex]]
+    .filter(([runs]) => runs(bot, home)).map(([, plan]) => plan(bots, home, bot));
   for (const plan of plans) if (plan.writes) refuseUnwritable(plan.answer.file);
   return () => plans.map((plan) => plan.write());
 }
@@ -404,7 +446,8 @@ export function takeBack(bots, home, bot, rules) {
   }
   const codex = path.join(home, CODEX_FILE);
   let before = [];
-  if (runsOnCodex(bot)) {
+  const codexKept = keepsCodex(bot, home);
+  if (codexKept) {
     refuseOutside(home, codex);
     if (existsSync(codex)) {
       before = ruleLines(readFileSync(codex, 'utf8'));
@@ -422,7 +465,7 @@ export function takeBack(bots, home, bot, rules) {
       }
       entries.push({ bot: bot.name, file, written: [], removed });
     }
-    if (runsOnCodex(after)) {
+    if (codexKept) {
       const entry = planCodex(bots, home, after).write();
       // A line goes only when no rule still allowed gives it.
       const kept = [...codexOf(home, after).lines.keys()];

package/src/rules.js

@@ -21,6 +21,7 @@ import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 
 import { botDir, botNames, displayName, readBot, refuseOutside } from './bot.js';
+import { dropRemovedHooks } from './hooks.js';
 import { ownCli, shellWord } from './launch.js';
 
 /** The kit's own units, inside the installed package. */
@@ -109,13 +110,23 @@ export function buildRules(bots, { bot: onlyBot } = {}) {
 
   return (onlyBot === undefined ? names : [onlyBot]).map((name) => {
     const home = botDir(bots, name);
+    let built;
     try {
-      return buildAgents(bots, home, readBot(home, name));
+      built = buildAgents(bots, home, readBot(home, name));
     } catch (error) {
       // A `bot.yaml` the kit cannot read at all. Same answer as a list it
       // cannot follow: this bot is not built, and nothing else changes.
-      return { bot: name, file: path.join(home, AGENTS), state: 'failed', trouble: error.message };
+      built = { bot: name, file: path.join(home, AGENTS), state: 'failed', trouble: error.message };
     }
+    // Every bot, a paused one too, so this is the command that reaches each
+    // hooks file the kit wrote, whatever the bot's sessions run on now (#613).
+    // A file it cannot write is this bot's trouble, as above.
+    try {
+      dropRemovedHooks(home);
+    } catch (error) {
+      return { ...built, trouble: [built.trouble, error.message].filter((one) => one !== undefined).join(' ') };
+    }
+    return built;
   });
 }
 

package/src/run.js

@@ -0,0 +1,155 @@
+// `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);
+  });
+}

package/src/up.js

@@ -12,7 +12,7 @@ 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 { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
-import { installHook } from './hooks.js';
+import { dropRemovedHooks, installHook } from './hooks.js';
 import { writePermissions } from './permissions.js';
 import { piTrouble } from './pi.js';
 import { addressOf, HARNESSES, harnessOf, isAddressOf, isShortPrompt, kitFolders, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
@@ -148,8 +148,10 @@ export function prepareBots(bots, names, onlySession) {
   // so one written later would miss the session it was written for (ADR 0022),
   // and a bot folder the kit cannot write it into stops the run with nothing
   // opened anywhere. Only the harnesses a bot actually runs on; a bot with no
-  // sessions gets none.
+  // sessions gets none. The hooks of commands the kit no longer has go from
+  // every hooks file the bot has, of a harness it has left too (#613).
   for (const { bot, home } of running) {
+    dropRemovedHooks(home);
     for (const harness of new Set(awake(sessionsOf(bot, onlySession)).map((session) => harnessOf(session, bot.harness)))) {
       installHook(home, harness, { bots, bot: bot.name });
     }