@assuredloop/orca-bot-kit 0.31.0 → 0.33.0

package/src/health.js

@@ -23,11 +23,12 @@ import path from 'node:path';
 
 import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bot.js';
-import { transcriptsIn } from './conversations.js';
+import { hasConversation, 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, mailIn, orcaDefaultArgs, projects, runMissing, tabs, tabToTypeInto, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
+import { askPi } from './pi.js';
 import { processesIn } from './processes.js';
 import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
@@ -51,7 +52,9 @@ export function checkHealth(bots, { bot: onlyBot } = {}) {
 
   const found = [...orcaSettingFindings(), ...leftInOrca(bots, setups), ...leftBeside(bots)];
   const sessions = [];
-  for (const name of names) found.push(...aboutBot(bots, name, setups, sessions));
+  // Pi is asked only when a bot has a Pi session, and each question once (#660).
+  const pi = askPi();
+  for (const name of names) found.push(...aboutBot(bots, name, setups, sessions, pi));
   return { found, sessions };
 }
 
@@ -185,7 +188,7 @@ function leftBeside(bots) {
 }
 
 /** Everything wrong with one bot. Its running sessions are added to `sessions`. */
-function aboutBot(bots, name, setups, sessions) {
+function aboutBot(bots, name, setups, sessions, pi) {
   const home = botDir(bots, name);
 
   let bot;
@@ -206,6 +209,7 @@ function aboutBot(bots, name, setups, sessions) {
     ...agentsTrouble(bots, home, bot).map(said('config')),
     ...hooksOf(bots, home, bot).map(said('config')),
     ...permissionsTrouble(home, bot).map(said('config')),
+    ...piReadiness(home, bot, pi).map(said('config')),
     ...skillsTrouble(bots, home, bot).map(said('skill')),
     ...inOrca(bots, home, bot, setups, sessions),
     ...leftRunning(home, bot),
@@ -261,6 +265,40 @@ function sessionSettings(home, bot) {
   });
 }
 
+/**
+ * Why Pi cannot run this bot's Pi sessions, paused ones too, in the words
+ * `up` would refuse them with (#660): Pi does not run, can use no model, or
+ * cannot use the model a session names. When Pi cannot list its models at
+ * all, that is said instead, and no model is judged. Pi is asked read only,
+ * through the answers `pi` keeps for the whole run, and never about its
+ * credentials.
+ */
+function piReadiness(home, bot, pi) {
+  const onPi = bot.sessions.filter((session) => harnessOf(session, bot.harness) === 'pi');
+  if (onPi.length === 0) return [];
+  const where = path.join(home, 'bot.yaml');
+  const names = onPi.map((session) => session.name).join(', ');
+  const runs = pi.runs();
+  if (runs !== undefined) {
+    return [{ where, says: `Pi does not run here (${runs}), and ${bot.name}'s sessions ${names} run on Pi. obk up will not start them until it does. Install Pi.` }];
+  }
+  const models = pi.models();
+  if (models.failed !== undefined) {
+    return [{ where, says: `Pi could not list its models: pi --list-models failed (${models.failed}), and ${bot.name}'s sessions ${names} run on Pi. The kit cannot say whether Pi can use their models. Run that command yourself to see why.` }];
+  }
+  if (!models.any) {
+    return [{ where, says: `Pi has no model it can use: it is signed in to no provider, and ${bot.name}'s sessions ${names} run on Pi. obk up will not start them until it is. Sign in to Pi yourself (start pi and use /login, or set a provider's API key). The kit never handles Pi's credentials.` }];
+  }
+  return onPi.filter((session) => set(session.model)).flatMap((session) => {
+    const model = String(session.model).trim();
+    const found = pi.model(model);
+    if (found.failed !== undefined) {
+      return [{ where, says: `${bot.name}'s session ${session.name} runs on Pi with the model ${model}, and the kit cannot say whether Pi can use it: pi --list-models ${found.search} failed (${found.failed}). Run that command yourself to see why.` }];
+    }
+    return found.listed ? [] : [{ where, says: `${bot.name}'s session ${session.name} runs on Pi with the model ${model}, and Pi cannot use it: pi --list-models lists none matching it. obk up will not start the session. Sign in to its provider in Pi yourself, or give the session a model Pi lists.` }];
+  });
+}
+
 /** What is wrong with the roles the bot's temporary sessions are made in (#465). */
 function rolesTrouble(home, bot) {
   const where = path.join(home, 'bot.yaml');
@@ -471,7 +509,7 @@ function inOrca(bots, home, bot, setups, sessions) {
     }
   }
 
-  found.push(...offTheBook(real ?? home, bot, book, onRecord));
+  found.push(...offTheBook(bots, real ?? home, bot, book, onRecord));
 
   // A tab outside the book is somebody else's, and in Bot Father's project it
   // is the ops tab: the one tab the kit deliberately keeps no record of, so it
@@ -555,9 +593,11 @@ function unannounced(bots, home, bot, name, entry) {
  * 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
  * fails it fails quietly (ADR 0022), so this is where a stale book shows: the
- * harness's own record set beside it (ADR 0012).
+ * harness's own record set beside it (ADR 0012). Pi has no hook of the kit's,
+ * so for Pi it also names a session whose conversation in the book Pi has no
+ * record of (#660).
  */
-function offTheBook(home, bot, book, onRecord) {
+function offTheBook(bots, home, bot, book, onRecord) {
   // A retired session's conversations are in the book too, under `retired`.
   const named = sessionIdsIn(book);
   for (const entry of Object.values(book.sessions)) {
@@ -566,10 +606,32 @@ function offTheBook(home, bot, book, onRecord) {
 
   // A subagent's conversation is no session's, so the book has no reason to name it.
   const stray = onRecord.filter((one) => !one.subagent && !named.has(one.id));
-  if (stray.length === 0) return [];
+  const listed = (some) => some.map((one) => `${one.id} (begun ${one.at})`).join(', ');
+  const give = `To give one to a session, write it into ${bookFile(home)} under that session as  session: <id>  and run obk up again.`;
+  const found = [];
+
+  const hooked = stray.filter((one) => one.harness !== 'pi');
+  if (hooked.length > 0) {
+    found.push(finding('session', bookFile(home), `The harness has conversations on record in ${bot.name}'s folder that the book does not name: ${listed(hooked)}. The kit's hook may have missed them: a clear it did not record, or a Codex hooks file trusted late. ${give}`, bot.name));
+  }
 
-  const listed = stray.map((one) => `${one.id} (begun ${one.at})`).join(', ');
-  return [finding('session', bookFile(home), `The harness has conversations on record in ${bot.name}'s folder that the book does not name: ${listed}. The kit's hook may have missed them: a clear it did not record, or a Codex hooks file trusted late. To give one to a session, write it into ${bookFile(home)} under that session as  session: <id>  and run obk up again.`, bot.name)];
+  // The kit has no hook in Pi: it names a Pi session's conversation on the
+  // launch line, so one the book does not name was begun inside Pi (#660).
+  const onPi = stray.filter((one) => one.harness === 'pi');
+  if (onPi.length === 0) return found;
+  found.push(finding('session', bookFile(home), `Pi has conversations on record in ${bot.name}'s folder that the book does not name: ${listed(onPi)}. Pi begins one when /new is typed in its tab, and the kit's Pi extension tells the book of it, so these were missed: the tab ran without the extension (a tab Orca brought back by itself, or one the kit started before it had the extension), or the extension's record went wrong. ${give}`, bot.name));
+
+  // A Pi session whose conversation in the book Pi has no record of, while Pi
+  // has one the book does not name: it is in another conversation than the
+  // book holds, and its next start would begin the book's one afresh. A book
+  // id with no record and no such conversation is a session before its first
+  // turn, which Pi has written nothing for yet, and is not said.
+  for (const session of bot.sessions) {
+    const id = book.sessions[session.name]?.session;
+    if (harnessOf(session, bot.harness) !== 'pi' || bot.paused === true || session.paused === true || typeof id !== 'string' || hasConversation('pi', home, id)) continue;
+    found.push(finding('session', bookFile(home), `${bot.name}'s session ${session.name} has the conversation ${id} in the book, and Pi has no record of it in this bot's folder, while Pi has conversations there that the book does not name. So it is likely in one of those, and its next start would begin ${id} afresh rather than go on with it. Write the one it is in into ${bookFile(home)} under ${session.name} as  session: <id>, then ${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`, bot.name));
+  }
+  return found;
 }
 
 /** Every conversation on record in the bot's folder, from every harness any of its sessions runs on or a retired one may have, as `obk usage` reads them. */
@@ -580,7 +642,7 @@ function recordIn(home, bot, book) {
   if (Array.isArray(book.retired) && book.retired.length > 0) for (const harness of HARNESSES) harnesses.add(harness);
   return [...harnesses]
     .filter((harness) => HARNESSES.includes(harness))
-    .flatMap((harness) => transcriptsIn(harness, home));
+    .flatMap((harness) => transcriptsIn(harness, home).map((one) => ({ ...one, harness })));
 }
 
 /** What a directory holds, and nothing at all when there is no directory. */

package/src/init.js

@@ -97,7 +97,8 @@ charter: |
   names in paths, tokens, what a charter says. Put in the command that was run
   and its whole output, what you expected instead, and what these print:
   obk --version, obk health --bots <folder> --json, node --version, the Orca
-  version, and claude --version or codex --version; and the operating system.
+  version, and claude --version, codex --version or pi --version; and the
+  operating system.
   One problem per issue. If you cannot file it yourself, give your owner the
   text to paste.
 rules: []

package/src/launch.js

@@ -226,6 +226,19 @@ export const set = (value) => value !== undefined && value !== null && String(va
 /** Which harness a session runs on: its own, or the bot's. */
 export const harnessOf = (session, botHarness) => (set(session.harness) ? session.harness : botHarness);
 
+/** Whether a bot runs on Pi: as its own harness, or in one of its sessions. */
+export const runsOnPi = (bot) => bot.harness === 'pi'
+  || bot.sessions.some((session) => harnessOf(session, bot.harness) === 'pi');
+
+/**
+ * The folder a Pi session loads its bot's skills from: the bot's own
+ * `.agents/skills`, which the kit links every bot's skills into for Codex
+ * (`SKILL_DIRS` in skills.js). `--no-approve` keeps Pi from the folder's own
+ * skills, and a folder named with `--skill` loads whatever the trust (tech
+ * notes, section 6, #659).
+ */
+export const piSkillsDir = (home) => path.join(home, '.agents', 'skills');
+
 /**
  * A session's name on Claude Code, which is also the address another Claude
  * session writes to (ADR 0042). It goes on the launch line as `-n`, and it is
@@ -431,6 +444,13 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     // Pi trusts none of the folder's own files (`.pi/`, `.agents/skills`), so it
     // shows no trust screen and runs nothing the kit has not looked at (#578).
     words.push('--no-approve');
+    // So it is given the bot's skills by name, from the bot folder and nowhere
+    // every Pi session reads (#659).
+    words.push('--skill', piSkillsDir(home));
+    // The kit's own extension, from this kit's own folder: Pi has no hooks, so
+    // this is how the book hears of a `/new` in the tab (#662). Pi loads a file
+    // named here whatever the trust.
+    words.push('--extension', PI_EXTENSION);
     // The id the book holds, resumed or new: Pi opens the conversation with it,
     // and makes it when there is none (tech notes, section 6).
     words.push('--session-id', resume ?? sessionId);
@@ -576,6 +596,9 @@ export const shellWord = quoted;
 export const mailboxStep = (bots, bot, session) =>
   [ownCli(), 'session', 'mailbox', '--bots', bots, '--bot', bot, '--session', session].map(quoted).join(' ');
 
+/** The kit's Pi extension, beside this file (src/pi-record.js). */
+const PI_EXTENSION = fileURLToPath(new URL('./pi-record.js', import.meta.url));
+
 /**
  * The CLI that is running, by the path it was started by: the kit calls itself
  * back with this, never with the bare name `obk`, because the bare name is

package/src/orca.js

@@ -484,7 +484,7 @@ export function harnessInTab(handle, timeoutMs, readMs) {
     blockedReason: answer.result?.wait?.blockedReason,
     agent,
     ...frontOf(handle, shown?.ptyId, readMs),
-    ...screenOf(handle, readMs),
+    ...screenOf(handle, readMs, agent),
   };
 }
 
@@ -502,14 +502,15 @@ export const QUESTION_ON_SCREEN = 'question-on-screen';
 
 /**
  * What the tab `handle` renders: `{ question }`, true when it shows a question
- * of its harness's own, with the `rows` it read, or `{ screenUnreadable: <why> }`. Orca refusing is an
+ * of its harness's own, `agent` the one Orca names there, with the `rows` it
+ * read, or `{ screenUnreadable: <why> }`. Orca refusing is an
  * answer that cannot be read, not an error, and so is anything that is not the
  * rendered screen: accumulated output comes back in fragments (tech notes,
  * section 1).
  */
-function screenOf(handle, readMs) {
+function screenOf(handle, readMs, agent) {
   const read = screenRows(handle, readMs);
-  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows), rows: read.rows, draft: read.draft };
+  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows, agent), rows: read.rows, draft: read.draft };
 }
 
 /**
@@ -539,6 +540,83 @@ const POINTER_ROW = /^ *[›❯]/;
 /** How a harness's form says it is answered, as Claude Code 2.1.283 draws its foot (#416). */
 const FORM_FOOT = /Enter to (?:continue|confirm|select)\b.*Esc to cancel/i;
 
+/**
+ * How Pi 1.3.0 ends each of its selectors and dialogs: its cancel key, by
+ * default `escape/ctrl+c` (`Escape/Ctrl+C` under /model), then what it does.
+ * Pi points with `→` and has no numbers, so neither rule above sees one, and
+ * Orca calls the tab idle under it (developer-660, live, 2026-10-19; tech
+ * notes, section 6, for the trust screen). Pi draws it from the user's
+ * keybindings, so a rebound cancel key is not seen.
+ */
+const PI_FOOT = /\bescape\/ctrl\+c (?:to )?(?:cancel|close|skip setup)\b/i;
+
+/**
+ * The rules of Pi 1.3.0's input box, each across the whole width: the bottom
+ * one only `─`, or with Pi's ` ↓ <n> more ` (or ` ↑ <n> more `) while a long
+ * draft scrolls; the top one starting `──`, with Pi's status in it while it
+ * works, `── ⠋ Working ───…` (pi-tui `editor.js`, `custom-editor.js`; read in
+ * code, #663). Pi wraps its editor's text a column short of the width, so no
+ * row of a draft is as long as a rule.
+ */
+const PI_SCROLL = / [↑↓] \d+ more /;
+const PI_RULE = new RegExp(`^─+(?:${PI_SCROLL.source}─*)?$`);
+const PI_TOP_RULE = /^──.*─$/;
+
+/** The words in a row of Pi's, once its rule characters and its scroll label are taken out. */
+const piWords = (row) => row.replace(PI_SCROLL, '').replaceAll('─', '').trim();
+
+/**
+ * Pi's two rules on a rendered screen, `{ bottom, top }` or `{ bottom, status
+ * }` as indexes into `rows`, or `{}` with no bottom rule. The bottom rule is
+ * the lowest rule. Then, up from it, only rows with a rule's ends count, and
+ * the first that decides is taken: one as long is the top rule, and rows
+ * above it are the chat (Pi's own dividers among them). One not as long,
+ * with words of more than ASCII in it, is a status: Pi lays out by columns
+ * and the kit counts characters, so a status with wide or combining
+ * characters is not as long. An ASCII status always is, so one not as long
+ * with ASCII words is an editor row, and the walk goes on (reviews of PR
+ * #666).
+ */
+function piRules(rows) {
+  const bottom = rows.findLastIndex((row) => PI_RULE.test(row.trimEnd()));
+  if (bottom < 0) return {};
+  const width = [...rows[bottom].trimEnd()].length;
+  for (let at = bottom - 1; at >= 0; at -= 1) {
+    const row = rows[at].trimEnd();
+    if (!PI_TOP_RULE.test(row)) continue;
+    if ([...row].length === width) return { bottom, top: at };
+    if (/[^\x20-\x7e]/.test(piWords(row))) return { bottom, status: at };
+  }
+  return { bottom };
+}
+
+/**
+ * Pi's input box on a rendered screen, `{ top, editor, below }`: its top rule,
+ * every row between its two rules, and the rows under the bottom one (Pi's
+ * slash menu, then its footer). Undefined when `piRules` finds no top rule.
+ */
+export function piBox(rows) {
+  const { bottom, top } = piRules(rows);
+  if (top === undefined) return undefined;
+  return { top: rows[top], editor: rows.slice(top + 1, bottom), below: rows.slice(bottom + 1) };
+}
+
+/**
+ * The row of a rendered screen that says the harness is at work, as only Pi
+ * draws it, or undefined: its input box's top rule with anything in it but
+ * the rule and the scroll label, or a status `piRules` found instead. Pi's
+ * usual status is a plain `Working`, and an extension can put its own words
+ * there, so no word is looked for; Pi's startup help says `escape to
+ * interrupt` too, and is no turn. `agent` is the harness Orca names in the
+ * tab: the row counts only where it is pi (#663).
+ */
+export function piAtWorkIn(rows, agent) {
+  if (agent !== 'pi') return undefined;
+  const { top, status } = piRules(rows);
+  if (status !== undefined) return rows[status];
+  return top !== undefined && piWords(rows[top]) !== '' ? rows[top] : undefined;
+}
+
 /** That pointer on a numbered choice, and the column its number starts in. */
 const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
 
@@ -553,8 +631,14 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * while it is the last thing drawn right above the input box (#491).
  * Unnumbered lists do not count. Codex puts a status row right under its input
  * line, lined up with it, and by its layout that is one.
+ *
+ * `agent` is the harness Orca names in the tab. For Pi, a row anywhere with
+ * Pi's own foot counts too (#659): Pi keeps no closed selector in its chat, so
+ * only text a model printed can put those words higher up, and then nothing is
+ * typed, which is the safe way to be wrong. Other harnesses never see it.
  */
-export function questionIn(rows) {
+export function questionIn(rows, agent) {
+  if (agent === 'pi' && rows.some((row) => PI_FOOT.test(row))) return true;
   if (feedbackPanelIn(rows)) return true;
   const at = rows.findLastIndex((row) => POINTER_ROW.test(row));
   // A form of the harness's own has no numbers but a foot that says how to
@@ -704,7 +788,9 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   if (seen.question === undefined) {
     return { unsure: `the kit could not tell whether a question is waiting on its screen (${seen.screenUnreadable}), so nothing was typed` };
   }
-  return { handle: live.handle, agent: seen.agent, idle: seen.answered, rows: seen.rows, draft: seen.draft };
+  // Orca's tui-idle does not answer the same each time for a Pi tab (tech
+  // notes, section 6), so Pi's own word that it is at work counts too.
+  return { handle: live.handle, agent: seen.agent, idle: seen.answered && piAtWorkIn(seen.rows, seen.agent) === undefined, rows: seen.rows, draft: seen.draft };
 }
 
 /**

package/src/pi-record.js

@@ -0,0 +1,96 @@
+// The kit's Pi extension: what a Claude Code or Codex session's SessionStart
+// hook does, for a Pi session (#662).
+//
+// Pi has no hooks; it has extensions. Every Pi launch line names this file with
+// `--extension`, and Pi loads it even with `--no-approve`. At each session_start,
+// a `/new` in the tab included, it runs the kit's own `session record`, as the
+// hooks do (src/hooks.js), and hands Pi the start prompt when the kit answers
+// with one. Seen live on Pi 1.3.0 (tech notes, section 6): the extension runs in
+// Pi's own process, so the command it starts is Pi's child, as a hook is the
+// harness's, and it has Pi's environment, the tab's id included.
+//
+// It runs inside the user's session, so it stays out of the way: whatever goes
+// wrong, it goes wrong quietly, and a book left stale is for the health check
+// to find (ADR 0022). It handles no credentials, types into no tab and reaches
+// no network.
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The CLI beside this file: the kit whose launch line named it (#220). */
+const CLI = fileURLToPath(new URL('./cli.js', import.meta.url));
+
+/** How long the kit is given to answer, as the hooks' TIMEOUT gives a harness. */
+const WAIT_MS = 10_000;
+
+/** What Pi calls the start prompt the kit hands it. */
+const CUSTOM_TYPE = 'obk-start-prompt';
+
+export default function piRecord(pi) {
+  pi.on('session_start', async (event, ctx) => {
+    try {
+      const bot = botAbove(ctx.cwd);
+      if (bot === undefined) return;
+
+      const said = { session_id: ctx.sessionManager.getSessionId(), source: event.reason, hook_event_name: event.type };
+      const duty = (await record(bot, said))?.hookSpecificOutput?.additionalContext;
+      // Into the conversation for its next turn, as Claude Code's
+      // additionalContext is: no turn is started for it.
+      if (typeof duty === 'string' && duty !== '') pi.sendMessage({ customType: CUSTOM_TYPE, content: duty, display: true });
+    } catch {
+      // Nothing: see above.
+    }
+  });
+}
+
+/**
+ * The bot whose home is `cwd` or the nearest folder above it, as
+ * `{ bots, bot }`, or undefined. A bot lives at `<bots>/bots/<bot>` with its
+ * `bot.yaml` (botDir in src/bot.js). A kit tab starts at the bot home; a folder
+ * below it holds too.
+ */
+function botAbove(cwd) {
+  if (typeof cwd !== 'string' || cwd === '') return undefined;
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    const parent = path.dirname(dir);
+    if (path.basename(parent) === 'bots' && existsSync(path.join(dir, 'bot.yaml'))) {
+      return { bots: path.dirname(parent), bot: path.basename(dir) };
+    }
+    if (parent === dir) return undefined;
+  }
+}
+
+/** The kit's answer to what Pi said, or undefined when it has none or none could be had. */
+function record({ bots, bot }, said) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(CLI, ['session', 'record', '--bots', bots, '--bot', bot], {
+        stdio: ['pipe', 'pipe', 'ignore'],
+        timeout: WAIT_MS,
+        killSignal: 'SIGKILL',
+      });
+    } catch {
+      resolve(undefined);
+      return;
+    }
+    let out = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      out += chunk;
+    });
+    child.on('error', () => resolve(undefined));
+    child.on('close', (code) => {
+      if (code !== 0) return resolve(undefined);
+      try {
+        resolve(JSON.parse(out));
+      } catch {
+        resolve(undefined);
+      }
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify(said));
+  });
+}

package/src/pi.js

@@ -20,36 +20,74 @@ const THINKING = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
  * 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 ?? '')) {
+  const pi = askPi();
+  const runs = pi.runs();
+  if (runs !== undefined) return `Pi does not run here (${runs}), so no Pi session was started. Install Pi, then run this again.`;
+  if (pi.models().any !== true) {
     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.`;
+    const found = pi.model(model);
+    if (found.failed !== undefined) {
+      return `Pi cannot say whether it can use the model ${model}: pi --list-models ${found.search} failed (${found.failed}), 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 ?? '')) {
+    if (!found.listed) {
       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;
 }
 
+/**
+ * Pi's answers, each question asked once however often it is asked here: for
+ * a caller that asks about many sessions, as `obk health` does (#660).
+ *
+ * - `runs()`: undefined when `pi --version` answers, or why it does not.
+ * - `models()`: `{ any }`, whether `pi --list-models` lists any model, or
+ *   `{ failed }` with why that question failed.
+ * - `model(m)`: `{ search, listed }`, whether `pi --list-models <search>` lists
+ *   a model matching `m` without its thinking level, or `{ search, failed }`
+ *   with why that question failed.
+ */
+export function askPi() {
+  const asked = new Map();
+  const once = (args) => {
+    const key = args.join('\0');
+    if (!asked.has(key)) asked.set(key, ask(args));
+    return asked.get(key);
+  };
+  return {
+    runs() {
+      const version = once(['--version']);
+      if (version.error === undefined && version.status === 0) return undefined;
+      return version.error?.code === 'ENOENT' ? 'there is no pi on PATH' : (version.error?.message ?? ((version.stderr ?? '').trim() || `it exited with ${version.status}`));
+    },
+    models() {
+      const all = once(['--list-models']);
+      if (failed(all)) return { failed: why(all) };
+      return { any: !/^No models available\b/m.test(all.stdout ?? '') };
+    },
+    model(model) {
+      const search = withoutThinking(model);
+      const found = once(['--list-models', search]);
+      if (failed(found)) return { search, failed: why(found) };
+      // 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.
+      return { search, listed: !/^No models (matching|available)\b/m.test(found.stdout ?? '') };
+    },
+  };
+}
+
 /** The model without a trailing `:<thinking level>`, which `--list-models` does not match. */
-function withoutThinking(model) {
+export function withoutThinking(model) {
   const at = model.lastIndexOf(':');
   return at > 0 && THINKING.includes(model.slice(at + 1)) ? model.slice(0, at) : model;
 }
 
+const failed = (answer) => answer.error !== undefined || answer.status !== 0;
+
+/** Why a question to Pi failed: the error, what Pi printed, or how it ended. */
+const why = (answer) => answer.error?.message
+  ?? ((answer.stderr ?? '').trim() || (answer.signal ? `it was killed by ${answer.signal}` : `it exited with ${answer.status}`));
+
 const ask = (args) => spawnSync('pi', args, { encoding: 'utf8', timeout: ASK_MS });

package/src/rules.js

@@ -22,7 +22,7 @@ import { parse } from 'yaml';
 
 import { botDir, botNames, displayName, readBot, refuseOutside } from './bot.js';
 import { dropRemovedHooks } from './hooks.js';
-import { ownCli, shellWord } from './launch.js';
+import { ownCli, runsOnPi, shellWord } from './launch.js';
 
 /** The kit's own units, inside the installed package. */
 const KIT_RULES = fileURLToPath(new URL('../rules', import.meta.url));
@@ -73,8 +73,16 @@ const checksum = (text) => createHash('sha256').update(text).digest('hex').slice
  * What the bot carries is `failed` — a name that resolves to nothing, a unit
  * that cannot be read — and the user fixes it in a list. The file itself is
  * `conflict`, which only the person who edited it can settle.
+ *
+ * A bot that runs on Pi has `pi: true` too, for the report to say what the
+ * kit does and does not write for Pi (#659).
  */
 export function buildAgents(bots, home, bot) {
+  const built = agentsInto(bots, home, bot);
+  return runsOnPi(bot) ? { ...built, pi: true } : built;
+}
+
+function agentsInto(bots, home, bot) {
   const file = path.join(home, AGENTS);
 
   let built;