@assuredloop/orca-bot-kit 0.30.0 → 0.32.0

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/processes.js

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

package/src/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;

package/src/settings.js

@@ -2,7 +2,7 @@
 //
 // A session can run on settings other than the ones bot.yaml asks for: it
 // started before a change, a default of the user's own leaked in, or a flag was
-// dropped. Each harness writes down what it used (tech notes, sections 2 and 3),
+// dropped. Each harness writes down what it used (tech notes, sections 2, 3 and 6),
 // so the two can be put side by side. Read only: these are the harness's files.
 //
 // Four answers, and only one of them is good news. A record that cannot be read,
@@ -10,7 +10,8 @@
 // setting the session never asked for is not a disagreement either, whatever the
 // harness chose: it is `not-asked-for`.
 
-import { DEFAULT_APPROVAL } from './launch.js';
+import { defaultApproval } from './launch.js';
+import { withoutThinking } from './pi.js';
 import { lines } from './usage.js';
 
 export const SETTINGS = ['model', 'effort', 'context', 'approval'];
@@ -22,47 +23,56 @@ export const SETTINGS = ['model', 'effort', 'context', 'approval'];
  * every setting asked for is then unknown.
  */
 export function settingsInUse(harness, session, file, since) {
-  const used = file === undefined ? {} : (harness === 'claude' ? fromClaude : fromCodex)(sinceStart(lines(file), since));
-  return Object.fromEntries(SETTINGS.map((name) => [name, judged(harness, name, asked(session, name), used[name])]));
+  const entries = file === undefined ? [] : lines(file);
+  const start = startOf(entries, since);
+  // Pi's reader also looks before the start, for the selection a reply follows.
+  const used = harness === 'pi' ? fromPi(entries, start)
+    : (harness === 'claude' ? fromClaude : fromCodex)(start === -1 ? [] : entries.slice(start));
+  return Object.fromEntries(SETTINGS.map((name) => [name, judged(harness, name, asked(harness, session, name), used[name])]));
 }
 
 /**
- * What the record says since the kit last started the session. A start resumes
- * the conversation it had, so the file still holds what the process before it
- * wrote, and that says what that process ran with, not this one. Everything
+ * Where the record since the kit last started the session begins, or -1. A
+ * start resumes the conversation it had, so the file still holds what the
+ * process before it wrote, and that says what that process ran with, not this
+ * one. Everything
  * from the first line written at or after the start counts, a line with no time
  * of its own included. With no start to go by, no line can be shown to be this
  * process's, so none counts.
  */
-function sinceStart(entries, since) {
+function startOf(entries, since) {
   const from = Date.parse(since ?? '');
-  if (Number.isNaN(from)) return [];
-  const first = entries.findIndex((entry) => Date.parse(entry.timestamp ?? '') >= from);
-  return first === -1 ? [] : entries.slice(first);
+  if (Number.isNaN(from)) return -1;
+  return entries.findIndex((entry) => Date.parse(entry.timestamp ?? '') >= from);
 }
 
 /** What the session asks for, as bot.yaml has it, or undefined when it asks for nothing. */
-function asked(session, name) {
+function asked(harness, session, name) {
   const value = session[name];
   const set = value !== undefined && value !== null && String(value).trim() !== '';
   // The kit puts an approval level on every launch line, so a session always
-  // asks for one: the default, when it names none (ADR 0015).
-  if (name === 'approval') return set ? String(value).trim() : DEFAULT_APPROVAL;
+  // asks for one: its harness's default, when it names none (ADR 0015). Pi
+  // has one level (#547).
+  if (name === 'approval') return set ? String(value).trim() : defaultApproval(harness);
   return set ? String(value).trim() : undefined;
 }
 
 function judged(harness, name, configured, observed) {
-  const shown = observed === undefined ? {} : { observed: said(name, observed) };
+  // A Pi reply can leave two values open (see fromPi): its own, which shows,
+  // and the selection before it. Agreeing with one of the two is not a match.
+  const choices = observed?.choices ?? [observed];
+  const shown = choices[0] === undefined ? {} : { observed: said(name, choices[0]) };
   if (configured === undefined) return { state: 'not-asked-for', ...shown };
-  const verdict = same(harness, name, configured, observed);
-  if (verdict === undefined) return { state: 'unknown', configured, ...shown };
-  return { state: verdict ? 'match' : 'mismatch', configured, ...shown };
+  const verdicts = choices.map((choice) => same(harness, name, configured, choice));
+  if (verdicts.every((verdict) => verdict === false)) return { state: 'mismatch', configured, ...shown };
+  if (verdicts.length === 1 && verdicts[0] === true) return { state: 'match', configured, ...shown };
+  return { state: 'unknown', configured, ...shown };
 }
 
 /** Whether the record says what was asked for; undefined when it cannot say. */
 function same(harness, name, configured, observed) {
   if (observed === undefined) return undefined;
-  if (name === 'model') return sameModel(configured, observed);
+  if (name === 'model') return harness === 'pi' ? samePiModel(configured, observed) : sameModel(configured, observed);
   // Codex reports the window it was given at 95%, rounded down (tech notes,
   // section 3): 200000 comes back as 190000.
   if (name === 'context') return Number(observed) === Math.floor(Number(configured) * 0.95);
@@ -82,6 +92,27 @@ function sameModel(configured, observed) {
   return model.includes('-') ? observed === model : observed.split('-').includes(model);
 }
 
+/**
+ * A Pi model as bot.yaml names it, `openai/gpt-6-luna` or `gpt-6-luna`, maybe
+ * with a trailing `:<thinking level>`, against the `<provider>/<model>` Pi
+ * wrote down: it matches either whole, in any case, as Pi does. Pi also takes
+ * a pattern that is part of a model's id, and which model it then chose
+ * depends on what else it lists, so such a pattern cannot be judged (Pi 1.3.0,
+ * resolveModelReference). Pi matches a display name too, which the record
+ * does not hold: such a pattern shows as a mismatch.
+ */
+function samePiModel(configured, observed) {
+  const model = withoutThinking(configured).toLowerCase();
+  const ran = observed.toLowerCase();
+  const provider = ran.slice(0, ran.indexOf('/'));
+  const id = ran.slice(ran.indexOf('/') + 1);
+  if (model === ran || model === id) return true;
+  // A provider before a slash is only a hint: the whole pattern may be part of an id.
+  const slash = model.indexOf('/');
+  const part = id.includes(model) || (slash !== -1 && model.slice(0, slash) === provider && id.includes(model.slice(slash + 1)));
+  return part ? undefined : false;
+}
+
 /** The permission mode Claude Code records for each level (tech notes, section 2). */
 const CLAUDE_MODES = { auto: 'auto', ask: 'default', 'dangerously-skip': 'bypassPermissions' };
 
@@ -134,6 +165,65 @@ function fromClaude(entries) {
   return used;
 }
 
+/** The api of a virtual model's catalog entry (Pi 1.3.0, virtual-models.js). */
+const PI_VIRTUAL = 'pi-virtual';
+
+/**
+ * What a Pi record says it runs with, from `start` on: the model, as
+ * `<provider>/<model>`, and the thinking level (tech notes, section 6). Pi
+ * writes nothing about approval.
+ *
+ * The latest line that names one decides. A `model_change` or
+ * `thinking_level_change` line decides alone. A reply names the model that
+ * answered, and the level it was asked at. On a resume with `--model` or
+ * `--thinking`, Pi writes no change line, so a change before a reply may be
+ * stale; but a change to a virtual model, such as `router/auto`, stays the
+ * selection while the router is registered, and its replies name the model
+ * it routed to (Pi 1.3.0, getBranchSelection, docs/virtual-models.md). The
+ * record cannot show what is registered now. So the reply stands when the
+ * change names the same model, or a model a reply shows is physical, and
+ * otherwise the two are left open. A router may change the level as well, so
+ * a reply's level stands alone only on a physical model. A reply a router
+ * could not route names the virtual model, and is passed over, as Pi does.
+ */
+function fromPi(entries, start) {
+  const named = (provider, model) => (typeof provider === 'string' && typeof model === 'string' ? `${provider}/${model}` : undefined);
+  const text = (value) => (typeof value === 'string' ? value : undefined);
+  const assistant = (entry) => (entry.type === 'message' && entry.message?.role === 'assistant' ? entry.message : undefined);
+  const reply = (entry) => (assistant(entry)?.api === PI_VIRTUAL ? undefined : assistant(entry));
+  const modelOf = (entry) => (entry.type === 'model_change' ? named(entry.provider, entry.modelId) : named(reply(entry)?.provider, reply(entry)?.model));
+  const levelOf = (entry) => text(entry.type === 'thinking_level_change' ? entry.thinkingLevel : reply(entry)?.thinkingLevel);
+  const changeBefore = (type, read, at) => {
+    for (let before = at - 1; before >= 0; before -= 1) if (entries[before].type === type) return read(entries[before]);
+    return undefined;
+  };
+  const physical = (model) => entries.some((entry) => entry.type !== 'model_change' && modelOf(entry) === model);
+  const latest = (read) => {
+    if (start === -1) return -1;
+    for (let at = entries.length - 1; at >= start; at -= 1) if (read(entries[at]) !== undefined) return at;
+    return -1;
+  };
+  /** The model the line at `at` says, and whether it is a physical one that a reply's level is sure of. */
+  const modelAt = (at) => {
+    const own = modelOf(entries[at]);
+    if (entries[at].type === 'model_change') return { model: own, sure: false };
+    const earlier = changeBefore('model_change', modelOf, at);
+    if (own === undefined) return { sure: false };
+    // The reply itself shows its own model is physical, so a change to that model is settled too.
+    if (earlier === undefined || physical(earlier)) return { model: own, sure: true };
+    return { model: { choices: [own, earlier] }, sure: false };
+  };
+
+  const model = latest(modelOf);
+  const level = latest(levelOf);
+  const own = level === -1 ? undefined : levelOf(entries[level]);
+  const earlier = level === -1 || entries[level].type === 'thinking_level_change' ? undefined : changeBefore('thinking_level_change', levelOf, level);
+  return {
+    model: model === -1 ? undefined : modelAt(model).model,
+    effort: earlier === undefined || earlier === own || modelAt(level).sure ? own : { choices: [own, earlier] },
+  };
+}
+
 /** What a Codex rollout says it runs with: its latest turn, and its latest count. */
 function fromCodex(entries) {
   const used = {};

package/src/skills.js

@@ -8,7 +8,9 @@
 // away reaches it without a restart. Claude Code takes it through its own
 // `/reload-skills`, which `obk skills build` types into the session's tab.
 // Codex has no such command and takes it at the start of its next turn (tech
-// notes, sections 2 and 3). Outwards: the kit takes away only the links it put
+// notes, sections 2 and 3). Pi loads the Codex directory, which its launch
+// line names, and takes a change at its own `/reload`, typed only while it is
+// idle (section 6, #659). Outwards: the kit takes away only the links it put
 // there, and never the skill one was pointing at.
 //
 // An entry names one of four shelves: the kit's own (`kit:<name>`), an online
@@ -25,7 +27,7 @@ import { parse, parseDocument, stringify } from 'yaml';
 
 import { bookFile, readBook, takeLineTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, botNames, changesExactly, leadsOutside, readBot, refuseOutside, withBotTurn, writeWhole, YAML_OUT } from './bot.js';
-import { harnessOf, ownCli, shellWord } from './launch.js';
+import { harnessOf, ownCli, piSkillsDir, runsOnPi, shellWord } from './launch.js';
 import { orcaTrouble, tabToTypeInto, typeIntoTab } from './orca.js';
 import { listIn } from './rules.js';
 import { cloneDir, isCloned, leavesClone, readSources, skillsIn, wrongClone } from './sources.js';
@@ -142,12 +144,18 @@ export function removeSkill(bots, bot, ref) {
 /**
  * Give one bot the skills its lists name. Returns what there is to report:
  * `{ bot, skills, linked, removed }` for a bot whose links are in place, and
- * `{ bot, skills, trouble }` for one whose list the kit could not follow.
+ * `{ bot, skills, trouble }` for one whose list the kit could not follow. A bot
+ * that runs on Pi has `pi` too: the directory its Pi sessions load (#659).
  *
  * A list with one entry the kit cannot follow links nothing at all: half a
  * bot's skills is not a bot anybody asked for, and the user fixes one line.
  */
 export function linkSkills(bots, home, bot) {
+  const entry = linkInto(bots, home, bot);
+  return runsOnPi(bot) ? { ...entry, pi: piSkillsDir(home) } : entry;
+}
+
+function linkInto(bots, home, bot) {
   const record = readRecord(home);
   const held = new Map();
 
@@ -440,7 +448,7 @@ const LOOK_MS = 2000;
  * harness's own means (PRD 6.5: changes reach running sessions without a
  * restart, and the sessions a change affects are told). Returns one entry per
  * session, in the bot's order: `{ session, harness, state }`, where the state
- * is `reloaded`, `next-turn` (with `read`), `not-up`, `blocked` (with
+ * is `reloaded`, `next-turn` (with `read`), `busy`, `not-up`, `blocked` (with
  * `blocked`) or `unknown` (with `trouble`).
  *
  * Claude Code gets `/reload-skills` typed into its tab, through the same gate
@@ -449,7 +457,11 @@ const LOOK_MS = 2000;
  * command and takes the change at the start of its next turn by itself, so
  * nothing is typed, and the caller is given the SKILL.md of each skill linked
  * in, for the session to read if the skill has not appeared (tech notes,
- * sections 2 and 3). Nothing is ever restarted.
+ * sections 2 and 3). Pi gets its own `/reload` through the same gate, and only
+ * while it is idle: a busy Pi refuses the command and keeps nothing for later,
+ * so a busy one is `busy`, and one with a draft in its input line is typed
+ * nothing either, since the command would join the draft (section 6, #659).
+ * Nothing is ever restarted.
  */
 function tellSessions(home, bot, linked) {
   let book;
@@ -478,9 +490,6 @@ function tellSessions(home, bot, linked) {
     const told = { session: session.name, harness };
     const tab = typeof book[session.name]?.tab === 'string' ? book[session.name].tab : undefined;
     if (tab === undefined) return { ...told, state: 'not-up' };
-    // Skills reach a Pi session in a later slice (#547), and nothing is typed
-    // into its tab before then.
-    if (harness === 'pi') return { ...told, state: 'unknown', trouble: 'it runs on Pi, and the kit does not give a Pi session skills yet, so nothing was typed' };
     if (down !== undefined) return { ...told, state: 'unknown', trouble: `the kit could not look at its tab, and nothing was typed: ${down}` };
     let turn;
     try {
@@ -505,7 +514,11 @@ function tellSessions(home, bot, linked) {
         const read = linked.map((name) => path.join(home, SKILL_DIRS.codex, name, MANIFEST)).filter((file) => existsSync(file));
         return { ...told, state: 'next-turn', read };
       }
-      typeIntoTab(found.handle, '/reload-skills');
+      if (harness === 'pi') {
+        if (found.draft !== undefined) return { ...told, state: 'unknown', trouble: `its input line holds a draft, "${found.draft}", and /reload would join it, so nothing was typed` };
+        if (!found.idle) return { ...told, state: 'busy' };
+      }
+      typeIntoTab(found.handle, harness === 'pi' ? '/reload' : '/reload-skills');
       return { ...told, state: 'reloaded' };
     } catch (error) {
       // The links are made whatever Orca says, so this is reported, not