@assuredloop/orca-bot-kit 0.2.0 → 0.4.0

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0001). 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.
  *
@@ -192,25 +236,125 @@ export const retitleTab = (handle, title) =>
   orca(['terminal', 'rename', '--terminal', handle, '--title', title]).rename;
 
 /**
- * Whether a TUI is running in the tab, and what it is waiting on if Orca says.
+ * What can be learned about the harness in a tab: what Orca says, and who is
+ * in front of the tab's terminal.
  *
- * `tui-idle` asks about a TUI, not about a shell: a tab sitting at a shell
- * prompt is refused with `timeout` however long you wait, a TUI that is up
- * answers `ok:true`, and `satisfied` only tells idle from busy. So this is the
- * way to learn whether a harness actually started — and `blockedReason` is
- * Orca saying something on screen wants answering, which is for the caller to
- * deal with, not the kit.
+ * Orca's answers alone do not tell a harness from a shell (tech notes, section
+ * 1, #232). `tui-idle` refuses a busy harness with `timeout` just as it refuses
+ * a shell, and a shell Codex quit to answers `ok`. `agentIdentity` comes late
+ * and can outlast the harness by minutes. So the answer the caller acts on is
+ * `front`: `program` when something other than the tab's shell holds its
+ * terminal, with `command` its name, `shell` when the shell does, and
+ * undefined when that cannot be read, with `unreadable` saying why. `answered` (an `ok` from `tui-idle`) and
+ * `agent` are Orca's own hints, for a caller that has nothing better.
+ * `blockedReason` is Orca saying something on screen wants answering, which is
+ * for the caller to deal with, not the kit.
  */
-export function tuiInTab(handle, timeoutMs) {
+export function harnessInTab(handle, timeoutMs) {
   const args = ['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)];
   const answer = ask(args);
 
-  if (answer.ok !== true) {
-    // Out of time means no TUI came up. That is an answer, not a breakdown.
-    if (answer.error?.code === 'timeout') return { running: false };
+  // Out of time means nothing went idle, busy or absent alike. That is an
+  // answer, not a breakdown.
+  if (answer.ok !== true && answer.error?.code !== 'timeout') {
     throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
   }
-  return { running: true, blockedReason: answer.result?.wait?.blockedReason };
+
+  const shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
+  const agent = typeof shown?.agentIdentity === 'string' && shown.agentIdentity !== '' ? shown.agentIdentity : undefined;
+  return {
+    answered: answer.ok === true,
+    blockedReason: answer.result?.wait?.blockedReason,
+    agent,
+    ...frontOf(shown?.ptyId),
+  };
+}
+
+/**
+ * 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 };
+}
+
+/** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
+const psCli = () => process.env.OBK_PS || '/bin/ps';
+
+/**
+ * Who holds the terminal of the pane `ptyId`: `{ front: 'shell' }`,
+ * `{ front: 'program', command }` with the name of the process leading the
+ * 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 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
+ * here ends in "cannot tell" rather than in an error or a guess.
+ */
+function frontOf(ptyId) {
+  let pane;
+  try {
+    pane = orca(['diagnostics', 'memory']).worktrees
+      .flatMap((worktree) => worktree.sessions ?? [])
+      .find((session) => session.sessionId === ptyId)?.pid;
+  } catch (error) {
+    return { unreadable: `Orca would not give the pane's pid: ${error.message}` };
+  }
+  if (!Number.isInteger(pane) || pane <= 0) return { unreadable: 'Orca gave no pid for its pane' };
+
+  const own = psLine(pane);
+  if (own === undefined) return { unreadable: `ps could not read its pane, pid ${pane}` };
+  if (own.tpgid === pane) return { front: 'shell' };
+
+  const front = psLine(own.tpgid);
+  if (front === undefined) return { unreadable: `ps could not read the process in front, pid ${own.tpgid}` };
+  const shell = front.ppid === pane && path.basename(own.comm) === 'login';
+  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm) };
+}
+
+/** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, or undefined. */
+function psLine(pid) {
+  const asked = spawnSync(psCli(), ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8' });
+  if (asked.error || asked.status !== 0) return undefined;
+  const line = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(.+?)\s*$/.exec(asked.stdout);
+  if (line === null) return undefined;
+  return { ppid: Number(line[2]), tpgid: Number(line[3]), comm: line[4] };
 }
 
 /**
@@ -257,19 +401,33 @@ const SUBMIT_WAIT_S = 5;
  * A mailbox of one session's own: an Orca Run, which is a name and an inbox and
  * nothing else — it schedules nothing and runs nobody. The objective is what a
  * person sees in `orca orchestration run-list`, so it says whose it is.
+ *
+ * Bound to `handle`, the session's own tab, from the moment it is made. Orca
+ * tells a Run's coordinator terminal about its mail and nobody else, and binds
+ * the caller when no `--from` is given: the tab that ran `obk up` would be told
+ * about every session it brought up, and would lose its own Run's binding, since
+ * one terminal holds one Run (tech notes, section 1).
  */
-export const makeMailbox = (objective) =>
-  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`]).run.id;
+export const makeMailbox = (objective, handle) =>
+  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`, '--from', handle]).run.id;
 
 /**
- * Take this process's turn at reading a mailbox.
- *
- * Orca fences a Run to one reader: a `check` from a caller 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.
+ * 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) => orca(['orchestration', 'run-use', '--id', id]).run;
+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 }) {
@@ -281,11 +439,16 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
 
 /**
  * What is waiting in a mailbox: the oldest batch that has not been
- * acknowledged, or, peeking, whatever is unread without touching it.
+ * acknowledged, or, peeking, whatever is unread without touching it. Read as
+ * the terminal `handle` when one is given, which is how a read works from a tab
+ * bound to another Run; otherwise as this process's own terminal.
  */
-export const readMailbox = (id, { peek = false } = {}) =>
-  orca(['orchestration', 'check', '--run', id, ...(peek ? ['--peek'] : [])]);
+export const readMailbox = (id, { peek = false, handle } = {}) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])]);
 
 /** Say a batch has been read, so the next check brings the one after it. */
-export const ackMailbox = (id, delivery) =>
-  orca(['orchestration', 'check', '--run', id, '--ack', delivery]);
+export const ackMailbox = (id, delivery, handle) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery]);
+
+/** The reader of a `check`: the terminal named, or this process's own. */
+const as = (handle) => (handle === undefined ? [] : ['--terminal', handle]);

package/src/pause.js

@@ -4,7 +4,7 @@
 // A pause is a mark in the bot's `bot.yaml` and the bot's tabs closed. The
 // mark is what `up` reads to leave it closed, and the book keeps the
 // conversation each session was in, so an unpause is the mark taken off and
-// the ordinary `up`, which resumes it (ADR 0002).
+// the ordinary `up`, which resumes it (ADR 0012).
 //
 // The closing is restart's, with restart's rules: only the tabs the book names,
 // one at a time by their own handles, and none at all when one of them holds a
@@ -13,6 +13,7 @@
 import { realpathSync } from 'node:fs';
 
 import { botDir, markPaused, readBot } from './bot.js';
+import { DAILY_SESSION } from './init.js';
 import { closeTabs, tabsToClose } from './restart.js';
 import { BOT_FATHER, botsNamed, bringUp, sessionsOf } from './up.js';
 
@@ -22,7 +23,7 @@ import { BOT_FATHER, botsNamed, bringUp, sessionsOf } from './up.js';
  * per tab it closed.
  */
 export async function pauseSessions(bots, { bot, session }) {
-  const home = fleetMember(bots, bot, 'pause');
+  const home = fleetMember(bots, bot, 'pause', session);
   const sessions = sessionsOf(readBot(home, bot), session);
 
   // Judged before anything is written or closed, so a refusal leaves both as
@@ -38,7 +39,7 @@ export async function pauseSessions(bots, { bot, session }) {
  * Returns `{ bot, session, changed, ...what up answered }`.
  */
 export async function unpauseSessions(bots, { bot, session }) {
-  const home = fleetMember(bots, bot, 'unpause');
+  const home = fleetMember(bots, bot, 'unpause', session);
   sessionsOf(readBot(home, bot), session);
 
   const changed = markPaused(bots, bot, session, false);
@@ -47,12 +48,16 @@ export async function unpauseSessions(bots, { bot, session }) {
 
 /**
  * The bot's home, once it is certain the bot is there and is not Bot Father,
- * which runs the fleet and is the one the user asks to bring anything back.
+ * or its management session: that is where the user asks to bring anything
+ * back. Bot Father's other sessions are like any bot's (#230).
  */
-export function fleetMember(bots, bot, verb) {
-  if (bot === BOT_FATHER) {
+export function fleetMember(bots, bot, verb, session) {
+  if (bot === BOT_FATHER && session === undefined) {
     throw new Error(`${BOT_FATHER} runs the fleet, and the kit does not ${verb} it: it is where you ask for everything else.`);
   }
+  if (bot === BOT_FATHER && session === DAILY_SESSION) {
+    throw new Error(`${DAILY_SESSION} is ${BOT_FATHER}'s management session, and the kit does not ${verb} it: it is where you ask for everything else.`);
+  }
   botsNamed(bots, bot);
   return realpathSync(botDir(bots, bot));
 }

package/src/record.js

@@ -2,7 +2,7 @@
 //
 // Both harnesses run the kit's hook (src/hooks.js) and hand it the session id
 // they are running under. That is how the book stays the authority for session
-// ids (ADR 0002) without the kit guessing from transcripts.
+// ids (ADR 0012) without the kit guessing from transcripts.
 //
 // Which session it is comes from the tab: Orca puts the tab id in the
 // environment of everything running in it, and the book says which session owns

package/src/restart.js

@@ -5,7 +5,7 @@
 // avoided, not banned, and one happens when the user asks for it).
 //
 // When they do ask, the session has to come back as itself. The book holds the
-// conversation each session is running (ADR 0002), so a restart is: close the
+// conversation each session is running (ADR 0012), so a restart is: close the
 // tab the book names, then let `up` open a new one and resume that
 // conversation. Nothing else about it is new.
 //
@@ -31,6 +31,7 @@ import { setTimeout as pause } from 'node:timers/promises';
 
 import { bookFile, readBook } from './book.js';
 import { botDir, readBot } from './bot.js';
+import { ownCli, shellWord } from './launch.js';
 import { closeTab, findProject, tabs } from './orca.js';
 import { botsNamed, bringUp, prepareBots, sessionsOf } from './up.js';
 
@@ -49,10 +50,10 @@ export async function restartSessions(bots, { bot: name, session: onlySession }
   // A paused bot or session has no tab to close and is not to be opened, so
   // there is nothing here to restart.
   if (known.paused === true) {
-    throw new Error(`${name} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with obk unpause --bots ${bots} --bot ${name}.`);
+    throw new Error(`${name} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with ${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${name}.`);
   }
   if (onlySession !== undefined && sessions[0].paused === true) {
-    throw new Error(`${name} ${onlySession} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with obk unpause --bots ${bots} --bot ${name} --session ${onlySession}.`);
+    throw new Error(`${name} ${onlySession} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with ${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${name} --session ${onlySession}.`);
   }
 
   // And the same preparations, made now rather than left to `up`, which makes
@@ -158,7 +159,7 @@ async function gone(home, closed, bots, bot) {
 
     if (Date.now() >= until) {
       const one = left.length === 1;
-      throw new Error(`Orca answered the close for ${one ? 'this tab' : 'these tabs'} and is still listing ${one ? 'it' : 'them'} ${SETTLED_MS / 1000} seconds later: ${left.join(', ')}. Nothing was opened in ${one ? 'its' : 'their'} place, because a tab that is on the way out is not a tab to start a harness in. The conversations are in the book: obk up --bots ${bots} --bot ${bot} brings them back once Orca has caught up.`);
+      throw new Error(`Orca answered the close for ${one ? 'this tab' : 'these tabs'} and is still listing ${one ? 'it' : 'them'} ${SETTLED_MS / 1000} seconds later: ${left.join(', ')}. Nothing was opened in ${one ? 'its' : 'their'} place, because a tab that is on the way out is not a tab to start a harness in. The conversations are in the book: ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot} brings them back once Orca has caught up.`);
     }
     await pause(ASK_MS);
   }
@@ -188,5 +189,5 @@ function alsoClosed(why, closed, bots, bot) {
   if (closed.length === 0) return why;
 
   const one = closed.length === 1;
-  return `${why} ${closed.map((tab) => tab.name).join(', ')} ${one ? 'was' : 'were'} closed before it and nothing was opened in ${one ? 'its' : 'their'} place: obk up --bots ${bots} --bot ${bot} brings ${one ? 'it' : 'them'} back with ${one ? 'its' : 'their'} conversation.`;
+  return `${why} ${closed.map((tab) => tab.name).join(', ')} ${one ? 'was' : 'were'} closed before it and nothing was opened in ${one ? 'its' : 'their'} place: ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot} brings ${one ? 'it' : 'them'} back with ${one ? 'its' : 'their'} conversation.`;
 }

package/src/retire.js

@@ -14,18 +14,18 @@
 //
 // Closing a tab here ends the conversation in it on purpose, so unlike a
 // 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 0008).
+// 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');
@@ -34,7 +34,7 @@ export const retiredDir = (bots) => path.join(bots, 'retired');
  * Retire the session `session` of the bot `bot`. Returns `{ bot, session, closed }`.
  */
 export async function retireSession(bots, { bot, session }) {
-  const home = fleetMember(bots, bot, 'retire');
+  const home = fleetMember(bots, bot, 'retire', session);
   const sessions = sessionsOf(readBot(home, bot), session);
 
   const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot);
@@ -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/roster.js

@@ -5,7 +5,7 @@
 // reads files and only files. It does not ask Orca, it changes nothing, and it
 // judges nothing: whether a bot is the right bot, what its charter comes to in
 // two lines, and which of its limits is the hard one are the reader's to say
-// (ADR 0006). What is wrong with the setup is a different question, and
+// (ADR 0016). What is wrong with the setup is a different question, and
 // `obk health` is the command that answers it.
 //
 // So a list here is the list as the user wrote it, unchecked. A skill named in

package/src/rules.js

@@ -1,5 +1,5 @@
 // A bot's `AGENTS.md`, built from its charter and the rule units it carries
-// (PRD 6.6, ADR 0003).
+// (PRD 6.6, ADR 0013).
 //
 // This is the one place the kit's own text lands inside the user's repo, so the
 // promise around it is narrow: the build owns one marked block and nothing else
@@ -299,7 +299,7 @@ function writeBlock(file, body) {
  * Whatever is already there is the user's and stays. What the build owes them
  * is the fact they cannot see: Claude Code reads a `CLAUDE.md` *instead of*
  * `AGENTS.md`, so one that is not this bot's `AGENTS.md` leaves the two
- * harnesses starting from different rules, which is the one thing ADR 0003
+ * harnesses starting from different rules, which is the one thing ADR 0013
  * says must not happen.
  *
  * Returns `{ linked }` on the run that made the link, `{ trouble }` when what