@assuredloop/orca-bot-kit 0.27.0 → 0.29.0

package/src/message.js

@@ -13,7 +13,8 @@
 // One road and one signal (#555, ADR 0042): the letter goes into the
 // receiver's mailbox, and Orca's own notice tells the receiver to look once it
 // is idle. The kit types nothing into the receiver's tab, except the one
-// Escape a sender asks for with --interrupt.
+// Escape a sender asks for with --interrupt. Orca gives no notice to a tab its
+// window has not loaded, so the send says when the receiver's is one (#579).
 
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
@@ -126,7 +127,7 @@ export function lookUp(bots, { to: target, from: sender, tab }) {
  * nothing, which is the whole of "the bot never picks the transport".
  */
 export async function sendMessage(bots, { to: target, from: sender, tab, subject, text, textFile, thread, interrupt = false }) {
-  const from = whoIsWriting(bots, sender, tab);
+  const from = whoIsSending(bots, sender, tab);
   const to = findSession(bots, target);
   const road = roadBetween(from, to);
 
@@ -159,6 +160,8 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
   }
 
   const written = bodyOf(bots, { from, to, subject, text, textFile });
+  // Looked at before the post, which is the send's last call to Orca (PRD 6.9).
+  const shown = loaded(to);
   // The Escape goes first, so the turn has ended when the letter is in.
   const interrupted = interrupt ? interruptBusy(to) : {};
   const message = postMessage({
@@ -176,9 +179,30 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
     thread: message.thread_id ?? thread,
     file: written.file,
     ...interrupted,
+    ...shown,
   };
 }
 
+/**
+ * Whether Orca's window has loaded the receiver's tab, looked at just before
+ * the letter goes in. Orca gives its notice only to a pane the window has loaded,
+ * and lists one it has not as orphaned, as after a window restart (#579; tech
+ * notes, section 1). So an orphaned tab is said, with its handle, and a
+ * listing that cannot be read is said too, rather than taken for a loaded tab.
+ * The look is made once: a tab orphaned after the send is not seen here.
+ */
+function loaded(to) {
+  if (to.tab === undefined) return {};
+  let listed;
+  try {
+    listed = tabs(to.home, { timeoutMs: LOOK_MS });
+  } catch (error) {
+    return { loadTrouble: error.message };
+  }
+  const tab = listed.find((one) => one.tabId === to.tab);
+  return tab?.orphaned === true ? { orphaned: true, handle: tab.handle } : {};
+}
+
 /**
  * What is waiting for a session, and the reading of it.
  *
@@ -364,6 +388,22 @@ function whoIsWriting(bots, sender, tab, asked = '--from <bot>/<session>: which
   return found;
 }
 
+/**
+ * The session that is sending. In one of this fleet's tabs it is the tab's own
+ * session, and `--from` may name only that one: otherwise a bot could send as
+ * another, and the reply and the receiver's check would take it for that one
+ * (#570). Outside the fleet's tabs `--from` says who is writing, as before.
+ */
+function whoIsSending(bots, sender, tab) {
+  const caller = tab === undefined ? undefined : sessionInTab(bots, tab);
+  if (caller === undefined) return whoIsWriting(bots, sender, tab);
+  if (sender === undefined) return caller;
+
+  const named = findSession(bots, sender);
+  if (named.bot === caller.bot && named.session === caller.session) return caller;
+  throw new Error(`this command runs in ${caller.bot}/${caller.session}'s Orca tab, ${tab}, so it sends as ${caller.bot}/${caller.session} and not as ${named.bot}/${named.session}. Nothing was sent. Leave out --from, or name ${caller.bot}/${caller.session}.`);
+}
+
 /**
  * The session the book says is in this Orca tab, wherever in the fleet it is,
  * when the caller is that session.

package/src/orca-reload.applescript

@@ -1,5 +1,5 @@
 -- Run by the kit as `osascript orca-reload.applescript <Orca.app path>`, after
--- a project was removed (#343, ADR 0034).
+-- a project was removed (#343, ADR 0046).
 --
 -- Orca's window keeps a removed project in its sidebar until the window is
 -- rebuilt (stablyai/orca#23224; once a release fixes it, this can go behind a
@@ -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-runtime.cjs

@@ -2,7 +2,7 @@
 // CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-runtime.cjs <client> <method> <params> <wait>`.
 //
 // It makes one call to Orca's runtime, through Orca's own client, for a method
-// Orca's CLI does not offer (ADR 0034): `project.update`, which makes Orca's
+// Orca's CLI does not offer (ADR 0046): `project.update`, which makes Orca's
 // window read its projects again (#224), and `terminal.inspectProcess`, which
 // says who is in front of a tab where `ps` cannot (#298). `params` is JSON. It
 // prints the runtime's answer as JSON and exits 0 only when the runtime took

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0034). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0046). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -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 });
   }
@@ -106,6 +111,15 @@ export function orcaTrouble() {
   if (asked.error) return `could not run Orca at ${orcaCli()}: ${asked.error.message}. ${where}`;
 
   const answer = parse(asked.stdout);
+  // A CLI that dies with no answer has not reached the app at all: it can fail
+  // on its own, as on a current folder macOS will not let it read, while Orca
+  // runs (#556). So what it said is passed on, and nobody is sent to start Orca.
+  if (answer === undefined && asked.status !== 0) {
+    const exit = asked.status ?? `signal ${asked.signal}`;
+    return `the Orca CLI at ${orcaCli()} failed before it answered status (exit ${exit}; `
+      + `stdout ${said(asked.stdout)}; stderr ${said(asked.stderr)}). `
+      + 'Fix what it says and run the command again, or point OBK_ORCA at another Orca CLI.';
+  }
   // Orca knowing what is wrong beats the kit guessing, so its own words go
   // first when it gave any.
   if (answer !== null && typeof answer === 'object' && answer.ok !== true && answer.error?.message) {
@@ -126,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:
@@ -319,7 +341,7 @@ const CLIENT_KILL_MS = 3000;
  *
  * Orca's window re-reads only when its runtime says the projects changed, and
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
- * changes does, and Orca's CLI does not offer it (ADR 0034). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0046). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -330,7 +352,7 @@ export const tellWindow = (projectId) => askRuntime('project.update', { projectI
  * runtime's answer, or undefined when there is none to be had.
  *
  * It goes through Orca's own runtime client out of the installed app, run by
- * Orca's binary the way its `bin/orca` runs its CLI (ADR 0034). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0046). None of that is
  * Orca's published interface, so anything that goes wrong is a quiet
  * undefined: it never throws and is never tried twice.
  */
@@ -367,7 +389,7 @@ const RELOAD_KILL_MS = 5000;
 
 /**
  * Have Orca's window force-reload itself, after a project was removed: true
- * only when it did (#343, ADR 0034).
+ * only when it did (#343, ADR 0046).
  *
  * The window keeps a removed project in its sidebar until it is rebuilt, and
  * `tellWindow` only relabels the row "Unknown" (stablyai/orca#23224; once a
@@ -524,7 +546,7 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Whether the rows of a rendered screen hold a question of the harness's own.
  *
  * Every one seen is a numbered list of choices with the harness's pointer on
- * one (tech notes, section 1; ADR 0034). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0046). The same pointer starts the harness's
  * input line and its echo of the user's past turns, and the input line is the
  * lowest of them whenever it is on screen, so the lowest pointer row is asked
  * about: a question counts while it stands in the input line's place, or
@@ -730,7 +752,7 @@ export const psCli = () => process.env.OBK_PS || '/bin/ps';
  *
  * `ps` is asked first. Where it cannot read the tab, as inside Codex's
  * sandbox, where it does not start at all, Orca's runtime is asked instead
- * (#298, ADR 0034). `readMs` bounds each call: a number, or a function that
+ * (#298, ADR 0046). `readMs` bounds each call: a number, or a function that
  * says what is left of a wait, asked before each one (#498). A `ps` that runs
  * out of it ends the look, `late`, with no runtime asked after it.
  */
@@ -770,7 +792,7 @@ function frontByOrca(handle, readMs) {
  * Who holds the terminal of the pane `ptyId`, as `ps` says it.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0034).
+ * gives that pid's terminal's foreground process group (ADR 0046).
  * On macOS the pane is `login` with the shell as its child, so the shell is in
  * front when the group is the pane's own or that of a child of a `login` pane.
  * `diagnostics memory` is a diagnostics command and may change, so everything
@@ -1048,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

@@ -6,7 +6,7 @@
 // body beside the bots folder, commit. A matching allow rule is settled before
 // that check (Claude Code's permissions docs), so the kit gives every bot a
 // default set, spelled with its real CLI and bots folder, with nobody asked
-// (#527, ADR 0036). A rule beyond it is the user's yes, which
+// (#527, ADR 0050). A rule beyond it is the user's yes, which
 // `permission allow` keeps in bot.yaml's `allow`. The kit's code writes what
 // `allow` holds into `.claude/settings.json` in the bot folder, beside its hook
 // (ADR 0022). A model editing the file by hand may get the format wrong; code
@@ -24,7 +24,7 @@ import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync
 import path from 'node:path';
 
 import { allowRules, leadsOutside } from './bot.js';
-import { DEFAULT_COMMANDS, NO_LONGER_DEFAULT } from './commands.js';
+import { DEFAULT_COMMANDS, NO_LONGER_DEFAULT, REMOVED } from './commands.js';
 import { readSettings } from './hooks.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 
@@ -36,11 +36,10 @@ const CODEX_RULES = '.codex/rules';
 const CODEX_FILE = `${CODEX_RULES}/obk.rules`;
 
 /**
- * The rules every bot is given (ADR 0036): each of the kit's default commands,
- * and none kept back for the user's yes (ADR 0041), narrowed to this bots folder and
+ * The rules every bot is given (ADR 0050): each of the kit's default commands,
+ * and none kept back for the user's yes (ADR 0051), narrowed to this bots folder and
  * spelled as the kit prints them, which is what a bot runs; reading a long
- * message; committing; and the check Orca's mail notice tells a session to
- * run. `//` is Claude's form for an absolute path.
+ * message; and committing. `//` is Claude's form for an absolute path.
  */
 export function defaultRules(bots, cli = ownCli()) {
   const kit = shellWord(cli);
@@ -50,19 +49,27 @@ export function defaultRules(bots, cli = ownCli()) {
     `Read(/${bots}.messages/**)`,
     'Bash(git add:*)',
     'Bash(git commit:*)',
-    'Bash(orca orchestration check --run:*)',
   ];
 }
 
 /**
- * The rules of the commands that were defaults once and are kept back now
- * (#548), spelled as `defaultRules` spelled them, that the bot's `allow`
- * holds. 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 0041).
+ * Orca's check, which the set held until #564: the kit's rules tell a bot to
+ * read its mail with `obk message check`, never with the bare check, which
+ * leaves it unread (ADR 0042).
+ */
+const ORCA_CHECK = 'Bash(orca orchestration check --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
+ * 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.map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+  return [...NO_LONGER_DEFAULT, ...REMOVED].map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+    .concat(ORCA_CHECK)
     .filter((rule) => allowed.includes(rule));
 }
 
@@ -158,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}`;
   }
@@ -176,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.
@@ -213,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
@@ -220,9 +269,16 @@ export const runsOnCodex = (bot) => bot.harness === 'codex'
  */
 function missingDefaults(bots, home, bot) {
   const allowed = allowOf(home, bot);
-  return defaultRules(bots)
-    .filter((rule) => runsOnClaude(bot) || codexForm(rule).line !== undefined)
-    .filter((rule) => !allowed.includes(rule));
+  return botDefaults(bots, bot).filter((rule) => !allowed.includes(rule));
+}
+
+/**
+ * The default rules a bot on Claude or Codex is given, in the default order:
+ * what `bot create` writes into a new bot's bot.yaml (#595).
+ */
+export function botDefaults(bots, bot) {
+  if (!runsOnClaude(bot) && !runsOnCodex(bot)) return [];
+  return defaultRules(bots).filter((rule) => runsOnClaude(bot) || codexForm(rule).line !== undefined);
 }
 
 /**
@@ -270,7 +326,7 @@ export function refuseNoCodexForm(bot, rules) {
 }
 
 /**
- * Add the default rules the bot is not allowed yet to its `allow` (ADR 0036),
+ * Add the default rules the bot is not allowed yet to its `allow` (ADR 0050),
  * then write what it is allowed into the files of the harnesses it runs on:
  * one entry per file, Claude's first, each with `defaults`, the rules this run
  * added, and `held`, the rules of commands no longer in the set that the bot
@@ -279,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 = [];
@@ -310,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());
 }
@@ -390,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'));
@@ -408,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/pi.js

@@ -0,0 +1,55 @@
+// Whether Pi is ready to start a session: it runs, it can use a model, and it
+// can use the one the session names (#578).
+//
+// The kit never handles Pi's credentials: the user signs in to Pi on their own,
+// and the kit only asks Pi what it can use. `pi auth check` is not asked, since
+// it does not know a provider an extension of Pi's brings, such as Cursor's;
+// `pi --list-models` lists the models Pi can use, those included (tech notes,
+// section 6).
+
+import { spawnSync } from 'node:child_process';
+
+/** How long each question to Pi is given. Each took about 0.3 s on Pi 1.1.0. */
+const ASK_MS = 30_000;
+
+/** Pi's thinking levels, which a model name may carry after a colon. */
+const THINKING = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+/**
+ * Why Pi cannot start these sessions, or undefined when it can. `models` are
+ * the models they name; a session that names none takes Pi's own default.
+ */
+export function piTrouble(models) {
+  const version = ask(['--version']);
+  if (version.error !== undefined || version.status !== 0) {
+    const why = version.error?.code === 'ENOENT' ? 'there is no pi on PATH' : (version.error?.message ?? ((version.stderr ?? '').trim() || `it exited with ${version.status}`));
+    return `Pi does not run here (${why}), so no Pi session was started. Install Pi, then run this again.`;
+  }
+
+  const any = ask(['--list-models']);
+  if (any.error !== undefined || any.status !== 0 || /^No models available\b/m.test(any.stdout ?? '')) {
+    return 'Pi has no model it can use: it is signed in to no provider. Sign in to Pi yourself (start pi and use /login, or set a provider\'s API key), then run this again. The kit never handles Pi\'s credentials.';
+  }
+
+  for (const model of new Set(models)) {
+    const found = ask(['--list-models', withoutThinking(model)]);
+    if (found.error !== undefined || found.status !== 0) {
+      const why = found.error?.message ?? ((found.stderr ?? '').trim() || `it exited with ${found.status ?? found.signal}`);
+      return `Pi cannot say whether it can use the model ${model}: pi --list-models ${withoutThinking(model)} failed (${why}), so no Pi session was started. Run that command yourself to see why, then run this again.`;
+    }
+    // Pi says it has no model at all before it searches, so the answer may be
+    // that one too, when a provider dropped out since the question above.
+    if (/^No models (matching|available)\b/m.test(found.stdout ?? '')) {
+      return `Pi cannot use the model ${model}: pi --list-models lists none matching it. Sign in to its provider in Pi yourself, or give the session a model Pi lists.`;
+    }
+  }
+  return undefined;
+}
+
+/** The model without a trailing `:<thinking level>`, which `--list-models` does not match. */
+function withoutThinking(model) {
+  const at = model.lastIndexOf(':');
+  return at > 0 && THINKING.includes(model.slice(at + 1)) ? model.slice(0, at) : model;
+}
+
+const ask = (args) => spawnSync('pi', args, { encoding: 'utf8', timeout: ASK_MS });

package/src/rules.js

@@ -20,7 +20,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 
-import { botDir, botNames, displayName, readBot } from './bot.js';
+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. */
@@ -85,6 +86,7 @@ export function buildAgents(bots, home, bot) {
 
   let state;
   try {
+    refuseOutside(home, file);
     state = writeBlock(file, built.body);
   } catch (error) {
     return { bot: bot.name, file, state: 'conflict', trouble: error.message };
@@ -108,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;
   });
 }
 
@@ -416,7 +428,9 @@ export function agentsTrouble(bots, home, bot) {
 /** Whether two paths are the same file in the end. One that leads nowhere is not. */
 function sameFile(one, other) {
   try {
-    return realpathSync(one) === realpathSync(other);
+    // Native, as in leadsOutside: the JS one takes `hop/..` away before `hop`
+    // is followed.
+    return realpathSync.native(one) === realpathSync.native(other);
   } catch {
     return false;
   }