@assuredloop/orca-bot-kit 0.3.0 → 0.5.0

package/src/health.js

@@ -21,13 +21,14 @@
 import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
-import { bookFile, readBook, tabIdsIn } from './book.js';
+import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { bypassFlags, harnessOf, HARNESSES, sessionTrouble } from './launch.js';
-import { orcaDefaultArgs, projects, tabs } from './orca.js';
-import { agentsTrouble } from './rules.js';
+import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, shellWord } from './launch.js';
+import { frontOfTab, orcaDefaultArgs, projects, tabs } from './orca.js';
+import { agentsTrouble, rulesStamp } from './rules.js';
+import { settingsInUse } from './settings.js';
 import { skillsTrouble } from './skills.js';
 import { readSources, sourcesDir } from './sources.js';
 import { BOT_FATHER, botsNamed, promptPath } from './up.js';
@@ -37,14 +38,18 @@ import { BOT_FATHER, botsNamed, promptPath } from './up.js';
  * settings do to every session, what is lying about that no book owns, and then
  * each bot in name order. `bot` narrows the per-bot checks to one; what the
  * whole fleet lives under is reported whichever bot was named.
+ *
+ * Beside the list, `sessions`: each running session the book knows, with what
+ * it runs on against what its bot asks for now, good news included.
  */
 export function checkHealth(bots, { bot: onlyBot } = {}) {
   const names = botsNamed(bots, onlyBot);
   const setups = projects();
 
   const found = [...orcaSettingFindings(), ...leftInOrca(bots, setups), ...leftBeside(bots)];
-  for (const name of names) found.push(...aboutBot(bots, name, setups));
-  return found;
+  const sessions = [];
+  for (const name of names) found.push(...aboutBot(bots, name, setups, sessions));
+  return { found, sessions };
 }
 
 /** One finding, as the report and the `--json` answer carry it. */
@@ -165,8 +170,8 @@ function leftBeside(bots) {
   return found;
 }
 
-/** Everything wrong with one bot. */
-function aboutBot(bots, name, setups) {
+/** Everything wrong with one bot. Its running sessions are added to `sessions`. */
+function aboutBot(bots, name, setups, sessions) {
   const home = botDir(bots, name);
 
   let bot;
@@ -185,7 +190,7 @@ function aboutBot(bots, name, setups) {
     ...agentsTrouble(bots, home, bot).map(said('config')),
     ...hooksOf(bots, home, bot).map(said('config')),
     ...skillsTrouble(bots, home, bot).map(said('skill')),
-    ...inOrca(home, bot, setups),
+    ...inOrca(bots, home, bot, setups, sessions),
   ];
 }
 
@@ -206,12 +211,97 @@ const hooksOf = (bots, home, bot) => [...new Set(bot.sessions.map((session) => h
   .map((harness) => hookTrouble(home, harness, { bots, bot: bot.name }))
   .filter((trouble) => trouble !== undefined);
 
+/**
+ * Each session of this bot running in a tab Orca has, with what it runs on set
+ * beside what the bot asks for now, added to `sessions`; a finding for each
+ * one that runs on something else (#271, #272); and a finding for each one
+ * whose tab is open with its harness gone from it (#300).
+ *
+ * Two questions, each answered from where the answer is written. The settings
+ * from the harness's own record of the conversation the session is in now,
+ * which is what the harness really used. The rules from the stamp the kit noted
+ * in the book when the session last read them, against `AGENTS.md` now: nothing
+ * the harness writes says which instructions it read.
+ *
+ * Only a mismatch and older rules are findings. What cannot be read is said as
+ * unknown in `sessions`, and never taken for agreement.
+ */
+function runningOn(bots, home, bot, book, handles, sessions) {
+  const real = realpathOf(home) ?? home;
+  const records = new Map();
+  const recordOf = (harness, id) => {
+    if (!HARNESSES.includes(harness) || id === null) return undefined;
+    if (!records.has(harness)) records.set(harness, new Map(transcriptsIn(harness, real).map((one) => [one.id, one.file])));
+    return records.get(harness).get(id);
+  };
+
+  const stamp = rulesStamp(home);
+  const found = [];
+  for (const session of bot.sessions) {
+    const entry = book.sessions[session.name];
+    // Running is a tab Orca still has, with the session's harness in front of
+    // it. A session whose tab is gone is not running whatever its record says,
+    // and the missing tab is said already.
+    if (bot.paused === true || session.paused === true || entry === null || typeof entry !== 'object') continue;
+    const handle = handles.get(entry.tab);
+    if (handle === undefined) continue;
+
+    // A harness can quit to the tab's shell and leave the tab open (#232), so
+    // the tab alone is not the answer: who holds its terminal is, asked the way
+    // the kit asks before it types into a tab. The shell in front is a session
+    // that is not running, and a finding: `up` finds the tab open and types
+    // nothing into it, so only a restart brings it back (#300). Anything else
+    // that is not its own harness, or a front that cannot be read, leaves it
+    // unsaid, and nothing unsaid is a finding.
+    const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
+    const front = frontOfTab(handle);
+    if (front.front === 'shell') {
+      // Restart refuses a live tab whose conversation the book cannot name, and
+      // there may be none to name: the harness can quit before it has one. Its
+      // harness is gone, so closing the tab ends nothing, and `up` then starts
+      // the session again as it does any closed tab with no conversation.
+      const up = `${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
+      const back = typeof entry.session === 'string'
+        ? `${restart} does`
+        : `nor does obk restart, which refuses to close a tab whose conversation the book does not name, and the book names none for it. Its harness has already quit, so close the tab in Orca yourself; then ${up} starts it again, with a new conversation and its duty. Any conversation it left in this bot's folder is noted in the book as unclaimed, for health to list`;
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} is not running: its tab ${entry.tab} is open with only the tab's shell in front, so its harness quit or crashed. obk up finds the tab open and types nothing into it, so it does not bring the session back; ${back}.`, bot.name));
+      continue;
+    }
+    const harness = harnessOf(session, bot.harness);
+    const running = front.front === 'program' && front.command === harness ? 'yes' : 'unknown';
+    const conversation = typeof entry.session === 'string' ? entry.session : null;
+    const file = recordOf(harness, conversation);
+    const settings = settingsInUse(harness, session, file, typeof entry.launched === 'string' ? entry.launched : undefined);
+    const rules = { state: typeof entry.rules !== 'string' ? 'unknown' : entry.rules === stamp ? 'current' : 'older' };
+    sessions.push({ bot: bot.name, session: session.name, harness, running, conversation, settings, rules });
+    if (running !== 'yes') continue;
+
+    const off = Object.entries(settings).filter(([, one]) => one.state === 'mismatch');
+    if (off.length > 0) {
+      const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+      found.push(finding('session', file, `${bot.name}'s session ${session.name} does not run on what ${path.join(home, 'bot.yaml')} asks for. ${parts}. That is what the harness's own record of its conversation ${conversation} says. A session takes these when it starts, so if bot.yaml changed after it started, ${restart} starts it on them; if not, something else set them, such as a default of the harness's own or a change made inside the session.`, bot.name));
+    }
+
+    if (rules.state === 'older') {
+      const agents = path.join(home, 'AGENTS.md');
+      // A clear on Claude Code reads the instructions again, as a start does
+      // (tech notes, section 2); whether a new conversation on Codex does is
+      // not established, so a start is all that is offered there.
+      const how = harness === 'claude'
+        ? `A Claude Code session reads it again at a /clear in its tab, or when it starts: ${restart}`
+        : `A Codex session reads it when it starts: ${restart}`;
+      found.push(finding('session', agents, `${bot.name}'s session ${session.name} is running on older rules: ${agents} has changed since the kit noted which version this session read. ${how}`, bot.name));
+    }
+  }
+  return found;
+}
+
 /**
  * What Orca has of this bot against what the book says it should have: a
  * session whose tab is gone, a conversation nobody claims, and a tab in the
  * bot's project that the book does not name.
  */
-function inOrca(home, bot, setups) {
+function inOrca(bots, home, bot, setups, sessions) {
   // The book is read where it is read, and a book nothing can parse is a
   // finding like any other: it says which tab each session is in and which
   // conversation it is running, so without it nothing else here can be asked —
@@ -236,19 +326,26 @@ function inOrca(home, bot, setups) {
   // what paused means rather than something lost.
   const closed = new Set(bot.sessions.filter((session) => bot.paused === true || session.paused === true).map((session) => session.name));
 
+  // What the harness has on record in this bot's folder, read once: it is a walk
+  // through every conversation on the machine.
+  const onRecord = recordIn(real ?? home, bot);
+  // A conversation the harness marks as a subagent's was never a session's, so a
+  // note that holds one is not a loose end for it (#287). The note stays as it is.
+  const helpers = new Set(onRecord.filter((one) => one.subagent).map((one) => one.id));
+
   const found = [];
   for (const [name, entry] of Object.entries(book.sessions)) {
     if (typeof entry?.tab === 'string' && !there.has(entry.tab) && !closed.has(name)) {
       found.push(finding('session', entry.tab, `${bot.name}'s session ${name} is in the book with tab ${entry.tab}, and Orca has no tab of that id: the tab was closed, or the machine was restarted. The conversation is in the book, and obk up opens a tab and brings it back.`, bot.name));
     }
 
-    const unclaimed = Array.isArray(entry?.unclaimed) ? entry.unclaimed : [];
+    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));
     }
   }
 
-  found.push(...offTheBook(real ?? home, bot, book));
+  found.push(...offTheBook(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
@@ -260,6 +357,7 @@ function inOrca(home, bot, setups) {
     }
   }
 
+  found.push(...runningOn(bots, home, bot, book, new Map(live.map((tab) => [tab.tabId, tab.handle])), sessions));
   return found;
 }
 
@@ -269,27 +367,30 @@ function inOrca(home, bot, setups) {
  * fails it fails quietly (ADR 0020), so this is where a stale book shows: the
  * harness's own record set beside it (ADR 0012).
  */
-function offTheBook(home, bot, book) {
-  const named = new Set();
+function offTheBook(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)) {
-    if (typeof entry?.session === 'string') named.add(entry.session);
-    for (const was of Array.isArray(entry?.history) ? entry.history : []) named.add(was?.session);
     for (const id of Array.isArray(entry?.unclaimed) ? entry.unclaimed : []) named.add(id);
   }
 
-  // Every harness any of its sessions runs on, as `obk usage` reads them.
-  const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
-  if (harnesses.size === 0) harnesses.add(bot.harness);
-  const stray = [...harnesses]
-    .filter((harness) => HARNESSES.includes(harness))
-    .flatMap((harness) => transcriptsIn(harness, home))
-    .filter((one) => !named.has(one.id));
+  // 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 = 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)];
 }
 
+/** Every conversation on record in the bot's folder, from every harness any of its sessions runs on, as `obk usage` reads them. */
+function recordIn(home, bot) {
+  const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
+  if (harnesses.size === 0) harnesses.add(bot.harness);
+  return [...harnesses]
+    .filter((harness) => HARNESSES.includes(harness))
+    .flatMap((harness) => transcriptsIn(harness, home));
+}
+
 /** What a directory holds, and nothing at all when there is no directory. */
 function namesIn(dir) {
   try {

package/src/message.js

@@ -21,7 +21,7 @@ import path from 'node:path';
 import { readBook } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
 import { harnessOf, ownCli, reachesMail, shellWord } from './launch.js';
-import { ackMailbox, harnessInTab, postMessage, readMailbox, tabs, typeIntoTab, useMailbox } from './orca.js';
+import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, typeIntoTab, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -173,7 +173,9 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
 /**
  * What is waiting for a session, and the reading of it.
  *
- * Orca fences a Run to one reader, so this binds before it reads. A read that
+ * Orca fences a Run to one reader, its coordinator. A session whose tab is live
+ * is bound to that tab and read as it; one whose tab is down is read as its
+ * Run's coordinator, and nothing is bound (issue #249). A read that
  * is not a peek acknowledges the batch it read: that is what makes the next
  * check bring the next one rather than the same again.
  */
@@ -195,9 +197,21 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
   // Read as the session's own tab, wherever this check was typed. Binding the
   // tab that asked would hand it the session's mailbox, and Orca's notice for
   // every message after (issue #228). A session with no live tab is read as
-  // this process's own terminal, as it always was.
-  const handle = who.tab === undefined ? undefined : tabs(who.home).find((tab) => tab.tabId === who.tab)?.handle;
-  useMailbox(who.mailbox, handle);
+  // whatever its mailbox is bound to, a closed tab included, and nothing is
+  // bound: the session's tab is bound again when it is back up (issue #249).
+  const live = who.tab === undefined ? undefined : tabs(who.home).find((tab) => tab.tabId === who.tab)?.handle;
+  if (live !== undefined) useMailbox(who.mailbox, live);
+  const handle = live ?? coordinatorOf(who.mailbox);
+  if (handle === undefined) {
+    return {
+      bots,
+      bot: who.bot,
+      session: who.session,
+      mailbox: who.mailbox,
+      messages: [],
+      trouble: `${who.bot}/${who.session} is not up, and its mailbox is bound to no tab, so there is nothing to read it as. Its mail waits until its tab is back: \`up\` brings it back, or \`unpause\` when it is paused.`,
+    };
+  }
   const found = readMailbox(who.mailbox, { peek, handle });
   const messages = (found.messages ?? []).map((message) => asMessage(bots, message));
   if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId, handle);
@@ -321,31 +335,14 @@ function nudge(to, from, subject) {
   if (to.tab === undefined) return { nudged: false };
 
   try {
-    const live = tabs(to.home).find((tab) => tab.tabId === to.tab);
-    if (live === undefined) return { nudged: false };
-
-    const seen = harnessInTab(live.handle, LOOK_MS);
-    if (seen.blockedReason !== undefined) return { nudged: false, blocked: seen.blockedReason };
-    // The shell in front is a tab with no harness, whatever a stale
-    // `agentIdentity` says.
-    if (seen.front === 'shell') return { nudged: false };
-    // Not knowing is not a reason to type: a line that lands in a shell is run
-    // there, with the sender's subject in it. The program in front has to be
-    // the agent Orca names. With no name it may be a harness a few seconds
-    // into its launch; under another name it may be a pager started after the
-    // harness quit, under an identity Orca has not let go of (tech notes,
-    // section 1). A harness run through a wrapper such as `node` lands here
-    // too, until #261.
-    if (seen.front === undefined || seen.agent === undefined || seen.command !== seen.agent) {
-      const why = seen.front === undefined
-        ? seen.unreadable
-        : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
-      return { nudged: false, nudgeTrouble: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed` };
-    }
-    // A busy harness is typed into: it takes the line as its next turn.
+    const found = tabToTypeInto(to.home, to.tab, LOOK_MS);
+    if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
+    // A line that lands in a shell is run there, with the sender's subject in it.
+    if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure };
+    if (found.handle === undefined) return { nudged: false };
 
     typeIntoTab(
-      live.handle,
+      found.handle,
       `Fleet mail from ${from.bot}/${from.session}: ${subject}. Read it with  ${shellWord(ownCli())} message check --bots ${shellWord(to.bots)} --bot ${shellWord(to.bot)} --session ${shellWord(to.session)}`,
     );
     return { nudged: true };

package/src/orca-window.cjs

@@ -0,0 +1,21 @@
+// Run by Orca's own binary as plain Node, the way Orca's `bin/orca` runs its
+// CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-window.cjs <client> <projectId> <wait>`.
+//
+// It asks Orca's runtime, through Orca's own client, for `project.update` with
+// no changes on one project. That is the call that makes Orca's window read its
+// projects again, and Orca's CLI does not offer it (#224, ADR 0021). It exits 0
+// only when the runtime took the call; anything else is a non-zero exit, and
+// the kit reads every non-zero exit the same way.
+
+'use strict';
+
+const [client, projectId, wait] = process.argv.slice(2);
+
+process.exitCode = 1;
+const { RuntimeClient } = require(client);
+new RuntimeClient(undefined, Number(wait))
+  .call('project.update', { projectId, updates: {} })
+  .then((answer) => {
+    if (answer?.ok === true) process.exitCode = 0;
+  }, () => {})
+  .finally(() => process.exit());

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0011). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0021). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -8,9 +8,10 @@
 // handed to Orca on the command line.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // The Orca that works for a normal user: `/usr/local/bin/orca` is a root-only
 // symlink on this machine (tech notes, section 1). OBK_ORCA overrides it, for a
@@ -162,6 +163,49 @@ export function asFolderProject(setupId, title) {
  */
 export const deleteProject = (setupId) => orca(['project', 'setup-delete', '--setup', setupId]);
 
+/** Said after a run that made, renamed or removed a project, whatever `tellWindow` answered. */
+export const RELOAD_LINE = "If Orca's sidebar does not show it, reload the window with Cmd+Shift+R.";
+
+/** How long Orca's client waits for its runtime, and how long the kit waits for the client. */
+const CLIENT_WAIT_MS = 2000;
+const CLIENT_KILL_MS = 3000;
+
+/**
+ * Tell Orca's window that the project `projectId` changed, so it reads its
+ * projects again: true when Orca's runtime took the call, false otherwise.
+ *
+ * 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, so this 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 0021). None of that is Orca's published
+ * interface, so anything that goes wrong is a quiet false: it never throws and
+ * is never tried twice, and the caller prints `RELOAD_LINE` either way.
+ */
+export function tellWindow(projectId) {
+  try {
+    // The CLI sits at <Orca.app>/Contents/Resources/bin/orca, often reached
+    // through a link.
+    const contents = path.resolve(realpathSync(orcaCli()), '..', '..', '..');
+    const client = path.join(contents, 'Resources', 'app.asar.unpacked', 'out', 'cli', 'runtime-client.js');
+    const env = { ...process.env, ELECTRON_RUN_AS_NODE: '1' };
+    // As Orca's `bin/orca` does: the kit's own Node options are not Orca's.
+    delete env.NODE_OPTIONS;
+    delete env.NODE_REPL_EXTERNAL_MODULE;
+
+    const asked = spawnSync(
+      path.join(contents, 'MacOS', 'Orca'),
+      [WINDOW_SCRIPT, client, projectId, String(CLIENT_WAIT_MS)],
+      { env, stdio: 'ignore', timeout: CLIENT_KILL_MS },
+    );
+    return asked.error === undefined && asked.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+const WINDOW_SCRIPT = fileURLToPath(new URL('./orca-window.cjs', import.meta.url));
+
 /**
  * The live tabs of the Orca project at `home`, each under its own tab id.
  *
@@ -226,6 +270,63 @@ export function harnessInTab(handle, timeoutMs) {
   };
 }
 
+/**
+ * Whether the kit may type a line into `tabId`, the tab the book holds for a
+ * session in the Orca project at `home`, and the handle to type into when it
+ * may: `{ handle, agent }`, with the agent Orca names there. Otherwise nothing
+ * is typed, and the answer says why:
+ * `{}` for a tab with no harness in it (none in the book, none Orca lists, or
+ * the shell in front), `{ blocked }` for one with something on screen waiting
+ * to be answered, and `{ unsure }`, a sentence, for one the kit cannot tell
+ * about. Orca refusing throws, for the caller to report.
+ *
+ * The one gate for every line the kit types into a running session: the mail
+ * nudge and the skills reload. A busy harness passes it, since both harnesses
+ * take a typed line as their next turn.
+ */
+export function tabToTypeInto(home, tabId, timeoutMs) {
+  if (tabId === undefined) return {};
+  const live = tabs(home).find((tab) => tab.tabId === tabId);
+  if (live === undefined) return {};
+
+  const seen = harnessInTab(live.handle, timeoutMs);
+  // A line typed into a screen waiting for an answer is that answer: once, it
+  // confirmed Claude Code's folder-trust default, `No, exit` (tech notes,
+  // section 1).
+  if (seen.blockedReason !== undefined) return { blocked: seen.blockedReason };
+  // The shell in front is a tab with no harness, whatever a stale
+  // `agentIdentity` says.
+  if (seen.front === 'shell') return {};
+  // Not knowing is not a reason to type: a line that lands in a shell is run
+  // there. The program in front has to be the agent Orca names. With no name
+  // it may be a harness a few seconds into its launch; under another name it
+  // may be a pager started after the harness quit, under an identity Orca has
+  // not let go of (tech notes, section 1). A harness run through a wrapper such
+  // as `node` lands here too, until #261.
+  if (seen.front === undefined || seen.agent === undefined || seen.command !== seen.agent) {
+    const why = seen.front === undefined
+      ? seen.unreadable
+      : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
+    return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed` };
+  }
+  return { handle: live.handle, agent: seen.agent };
+}
+
+/**
+ * Who holds the terminal of the tab `handle`, as `frontOf` answers, without
+ * waiting on the tab: for a caller that asks about every tab and has nothing
+ * to type. Orca refusing is an answer that cannot be read, not an error.
+ */
+export function frontOfTab(handle) {
+  let shown;
+  try {
+    shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
+  } catch (error) {
+    return { unreadable: `Orca would not show the tab: ${error.message}` };
+  }
+  return frontOf(shown?.ptyId);
+}
+
 /** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
 const psCli = () => process.env.OBK_PS || '/bin/ps';
 
@@ -235,7 +336,7 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  * group in front, or `{ unreadable: <why> }`.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0011).
+ * gives that pid's terminal's foreground process group (ADR 0021).
  * 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
@@ -326,17 +427,23 @@ export const makeMailbox = (objective, handle) =>
   orca(['orchestration', 'run-create', '--objective', `obk ${objective}`, '--from', handle]).run.id;
 
 /**
- * Take a turn at reading a mailbox, as the terminal `handle`.
- *
- * Orca fences a Run to one reader: a `check` from a terminal bound elsewhere is
- * refused with `consumer_fenced`, whatever the Run says. So a read binds first,
- * every time — the kit's runs are short and the binding is the last one to have
- * asked, not a lease anybody has to give back. Without a handle it binds this
- * process's own terminal.
+ * Bind a mailbox to the terminal `handle`, which makes it the Run's coordinator
+ * and its one reader: Orca refuses a `check` from any other terminal with
+ * `consumer_fenced`. A read itself binds nothing, so this is for a session's own
+ * live tab, never for whoever is reading (tech notes, section 1). Without a
+ * handle it binds this process's own terminal.
  */
 export const useMailbox = (id, handle) =>
   orca(['orchestration', 'run-use', '--id', id, ...(handle === undefined ? [] : ['--from', handle])]).run;
 
+/**
+ * The terminal a mailbox is bound to, or undefined when it has none. A closed
+ * tab keeps its binding, and a read as its handle still works: a read binds
+ * nothing, only `run-use` does (tech notes, section 1).
+ */
+export const coordinatorOf = (id) =>
+  orca(['orchestration', 'run-show', '--id', id]).run.coordinator_handle ?? undefined;
+
 /** Queue one message. `to` and `from` are mailboxes, written `run:<id>`. */
 export function postMessage({ to, from, subject, body, type = 'status', thread }) {
   const args = ['orchestration', 'send', '--to', to, '--subject', subject, '--body', body, '--type', type];

package/src/record.js

@@ -17,6 +17,7 @@ import { forgetClaimed, readBook, rememberSession, sessionIdsIn, updateBook, wit
 import { botDir, readBot } from './bot.js';
 import { conversationsIn } from './conversations.js';
 import { harnessOf, SHELL_ENV, startPrompt, workDirOf } from './launch.js';
+import { rulesStamp } from './rules.js';
 
 /** Where Orca says which tab a program is running in (tech notes, section 1). */
 export const TAB_ENV = 'ORCA_TAB_ID';
@@ -79,6 +80,11 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
   // this bot's folder, which every session of the bot shares — so it can say
   // that a conversation nobody claims exists, and never whose it is.
   const unclaimed = unclaimedFor(readBook(home), home, bot, tabId, id);
+  // A clear on Claude Code reads the bot's instructions again, as a start does
+  // (tech notes, section 2), so the book notes which ones it read. Codex has no
+  // word for its clear, and whether its new conversation reads them again is
+  // not established, so nothing is noted for it.
+  const rules = said.source === CLEARED ? rulesStamp(home) : undefined;
 
   let cleared = false;
   let told;
@@ -100,7 +106,8 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
     const uncertain = was.session === undefined && unclaimed.length > 0;
     told = session;
 
-    book.sessions[session] = withUnclaimed(rememberSession(was, id, said.source), unclaimed);
+    const now = rememberSession(was, id, said.source);
+    book.sessions[session] = withUnclaimed(rules === undefined ? now : { ...now, rules }, unclaimed);
     forgetClaimed(book);
     if (uncertain) cleared = true;
     return book;

package/src/retire.js

@@ -16,16 +16,16 @@
 // restart or a pause it does not wait for the book to know which one it was.
 // The mailbox Runs stay: Orca has no way to remove one (ADR 0018).
 
-import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, realpathSync, renameSync, rmSync } from 'node:fs';
 import path from 'node:path';
 
 import { readBook, tabIdsIn, updateBook } from './book.js';
 import { botDir, dropSession, readBot } from './bot.js';
-import { deleteProject, findProject, tabs } from './orca.js';
+import { deleteProject, findProject, projects, tabs, tellWindow } from './orca.js';
 import { fleetMember } from './pause.js';
 import { closeTabs, tabsToClose } from './restart.js';
 import { unlinkSkills } from './skills.js';
-import { promptPath, sessionsOf } from './up.js';
+import { BOT_FATHER, promptPath, sessionsOf } from './up.js';
 
 /** Where retired bots go: beside `bots/`, where nothing the kit runs looks. */
 export const retiredDir = (bots) => path.join(bots, 'retired');
@@ -55,6 +55,8 @@ export async function retireSession(bots, { bot, session }) {
 /**
  * Retire the bot `bot`. Returns `{ bot, closed, project, moved }`: the tabs it
  * closed, the Orca project it took away (if it had one) and where the bot is now.
+ * When Orca does not confirm the project gone, it returns `{ bot, closed,
+ * project, trouble }` instead, and the bot is left where it was.
  */
 export async function retireBot(bots, { bot }) {
   const home = fleetMember(bots, bot, 'retire');
@@ -79,7 +81,24 @@ export async function retireBot(bots, { bot }) {
   // they are gone.
   const booked = Object.keys(readBook(home).sessions).map((name) => ({ name }));
   const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot);
-  if (project !== undefined) deleteProject(project.id);
+  if (project !== undefined) {
+    deleteProject(project.id);
+    // Orca's answer to the delete is not the same as the project being gone
+    // (#282): its list afterwards is. Until that list is read and no longer
+    // has the project, the bot stays where it is, so that retiring it again
+    // takes the project away and then finishes. The list is read once, for
+    // this and for the window both.
+    let setups;
+    try {
+      setups = projects();
+    } catch (error) {
+      return { bot, closed, project: project.id, trouble: `Orca answered the delete of Orca project ${project.id}, and its project list could not be read afterwards, so the removal is not confirmed: ${error.message}. ${bot} was not moved. Once Orca is answering, retire ${bot} again with obk retire: it removes the project if it is still there, then finishes.` };
+    }
+    if (setups.some((setup) => setup.id === project.id || setup.path === home)) {
+      return { bot, closed, project: project.id, trouble: `Orca answered the delete of Orca project ${project.id}, and still lists it. ${bot} was not moved. Retire ${bot} again with obk retire; if Orca still lists the project after that, remove it in Orca yourself, then retire ${bot} again.` };
+    }
+    tellWindowOfRemoval(bots, setups);
+  }
 
   for (const name of new Set([...known.sessions, ...booked].map((session) => session.name))) {
     rmSync(promptPath(bots, bot, name), { force: true });
@@ -90,3 +109,19 @@ export async function retireBot(bots, { bot }) {
 
   return { bot, closed, ...(project === undefined ? {} : { project: project.id }), moved };
 }
+
+/**
+ * Tell Orca's window a project went (#224). The call names a project that is
+ * still there, and Bot Father's is the one that always is; when Orca has none
+ * for it in `setups`, Orca's list after the delete, there is nothing to call
+ * on. Finding it is part of the workaround, so it fails as quietly as the call.
+ */
+function tellWindowOfRemoval(bots, setups) {
+  try {
+    const home = botDir(bots, BOT_FATHER);
+    const father = existsSync(home) ? setups.find((setup) => setup.path === realpathSync(home)) : undefined;
+    if (father !== undefined) tellWindow(father.projectId);
+  } catch {
+    // Nothing: see above.
+  }
+}

package/src/rules.js

@@ -406,3 +406,18 @@ function sameFile(one, other) {
     return false;
   }
 }
+
+/**
+ * A stamp of a bot's `AGENTS.md` as it is now, or undefined when there is none
+ * to read. It is what a session read when it started, noted in the book at that
+ * moment, so that health can tell a session running on older rules from one on
+ * the current ones. The whole file, not only the build's block: what the user
+ * wrote below the end marker is part of what the session reads.
+ */
+export function rulesStamp(home) {
+  try {
+    return checksum(readFileSync(path.join(home, AGENTS), 'utf8'));
+  } catch {
+    return undefined;
+  }
+}