@assuredloop/orca-bot-kit 0.3.0 → 0.4.0

package/README.md

@@ -263,12 +263,22 @@ name for a directory in `skills/` inside your bots folder, or anything with a
 `/` in it for a skill directory anywhere on disk. `obk up` links them before it
 opens a tab, and `bot create` gives a new bot what the lists already name.
 
+A bot whose sessions are running gets a changed list without a restart.
+When `skills build` links or takes away a skill, it tells each running
+session of that bot. A Claude Code session gets `/reload-skills` typed into
+its tab: Claude Code's own reload, which a busy session runs when its turn
+ends. Codex has no reload command and takes the change at the start of its
+next turn, so nothing is typed there. The kit prints the new skills'
+`SKILL.md` paths, and says that a restart would make a skill appear if it is
+still missing after that turn. A session the kit could not tell is named,
+with the reason.
+
 What lands in the bot is a symlink, never a copy
 ([ADR 0014](docs/adr/0014-skills-are-linked-never-copied.md)) — into
 `.claude/skills` and `.agents/skills` in the bot home, which is where each
 harness reads a project's skills from. So a kit skill is read where npm
-installed it, editing a skill is what a running session reads without a
-restart, and updating the kit updates every bot at once.
+installed it, a running session reads an edited skill the next time it loads
+it, and updating the kit updates every bot at once.
 
 The kit takes away only what it can prove it put there. It writes down every
 link it makes, in `.obk-skills.yaml` in the bot folder, and when no list names
@@ -404,7 +414,10 @@ same refusals, and `obk up` leaves what is paused closed until `obk unpause`
 brings it back with its conversations. Retiring a session takes it off the bot
 and keeps its conversations in the book under `retired`. Retiring a bot closes
 its tabs, removes its Orca project and moves its folder to `retired/`; it will
-not touch a bot whose Orca project holds a tab your book does not name. Bot
+not touch a bot whose Orca project holds a tab your book does not name. The
+folder moves only once Orca no longer lists the project; if Orca still lists it,
+or its list cannot be read, retire says so and leaves the bot where it is, and
+retiring it again finishes the job. Bot
 Father itself, and its management session `daily`, are never paused or
 retired; its other sessions are like any bot's.
 

package/SETUP.md

@@ -145,8 +145,9 @@ different answers.
 
 `obk init` tells you which, for every tab it opened:
 
-- *the harness was typed in and came up* — it is running. It may still be asking
-  something of its own; that is the table below.
+- *the harness was typed in and is running. The kit cannot see whether a screen
+  in it is waiting for an answer* — look at it: Orca does not flag every first-run
+  screen, so it may still be asking something of its own. That is the table below.
 - *the harness was typed in and came up, waiting on: …* — running and blocked on
   a question. The table below.
 - *the harness was typed in, and no session came up in the tab* — **the line did

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/obk-bot-building/SKILL.md

@@ -273,17 +273,29 @@ again and check a session is running before you call the bot ready.
 ## When the bot is already running
 
 Changing a bot whose sessions are up is the ordinary case rather than the
-awkward one. Both harnesses read a skill through the link and notice a change
-to the skills directory while a session is running, so putting a skill on a
-bot, or taking one off, reaches a live session without restarting it.
-
-Noticing is not the same as confirmed. Check that the session can actually see
-the skill before telling anyone it is there, and check by asking that session
-rather than by looking again at the disk you just wrote: what you wrote is not
-evidence about what another process has loaded. Where it has not appeared, say
-so and say what would make it appear. A restart is the user's to ask for, and
-taking one because it is the quick way ends a conversation they were in the
-middle of.
+awkward one. Putting a skill on a bot or taking one off reaches its running
+sessions without a restart, and `obk skills build` says, session by session,
+how:
+
+- Claude Code: the kit types `/reload-skills` into the session's tab. That is
+  Claude Code's own reload. A busy session queues it and runs it as a command
+  when its turn ends, so it never reaches the model as text.
+- Codex: nothing is typed, because Codex has no reload command. It takes the
+  change at the start of its next turn, not in the middle of the one it is on.
+
+The kit reports a session it could not tell, and why: not up, or on a screen
+waiting for an answer. A session that is not up reads its skills when it
+starts.
+
+Told is not the same as confirmed. Before telling anyone a skill is there,
+check that the session can use it: ask it to load the skill. Do not look
+again at the disk you just wrote, since that says nothing about what another
+process has loaded. Do not ask a Codex session whether the skill is in its
+list: it has answered "none" while its list held the skill. Where a skill has
+not appeared after the next turn, say so. A restart would make it appear, and
+meanwhile the session can read the skill's `SKILL.md` by the path the kit
+printed. A restart is the user's to ask for. Taking one because it is quick
+ends a conversation they were in the middle of.
 
 Instructions are not skills. A session is working from the rules it read when
 it started, so a change to a bot's `AGENTS.md` may not reach one that is

package/src/cli.js

@@ -18,7 +18,7 @@ import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
 import { checkMail, lookUp, sendMessage } from './message.js';
-import { orcaCli, orcaTrouble } from './orca.js';
+import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -83,7 +83,8 @@ Usage:
                             a bot: close its tabs, remove its Orca project and
                             move its folder to retired/. It will not retire a
                             bot whose Orca project holds a tab your book does
-                            not name.
+                            not name, and moves the folder only once Orca no
+                            longer lists the project.
   obk rules build --bots <path> [--bot <bot>]
                             Build every bot's AGENTS.md from its charter and
                             the rule units it carries, or just the one you
@@ -103,7 +104,10 @@ Usage:
                             skills folder, or any path, and take away a link
                             it made that no list names any more. What you put
                             in a bot's skills directory yourself is left alone
-                            and shown as yours. It does not touch Orca.
+                            and shown as yours. A bot whose links changed has
+                            its running sessions told: Claude Code gets
+                            /reload-skills typed in, and Codex takes the
+                            change at its next turn.
   obk skills fetch --bots <path> [--source <name>]
                             Clone the online sources skills.yaml lists, beside
                             your bots folder and never inside it, each at the
@@ -425,19 +429,19 @@ const commands = {
     const seeded = initBots(bots, values.harness);
     // The typed path was for making the folder and naming it in a refusal; from
     // here on it is the fleet, and the fleet is its real path (#164).
-    const { tabs, rules, skills, paused } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
+    const { tabs, rules, skills, paused, projects } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
     // Setup is the other place the PRD asks for Orca's own launch arguments to
     // be looked at (6.5), and the one where the user is still standing in front
     // of the fleet they are making. Only that one check: a folder init has just
     // made has nothing else to say about itself.
-    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, tabs, paused, found: orcaSettingFindings() };
+    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, tabs, paused, projects, found: orcaSettingFindings() };
     return { answer, lines: tabLines(answer, `Bot Father is up in Orca. Your bots folder: ${seeded.bots}`) };
   },
 
   async up(bots, values) {
     refuseWhenOrcaIsDown();
-    const { tabs, rules, skills, paused } = await bringUp(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused };
+    const { tabs, rules, skills, paused, projects } = await bringUp(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects };
     const up = [...new Set(tabs.map((tab) => tab.bot))];
     const summary = up.length === 0
       ? `Nothing was brought up in Orca. Your bots folder: ${bots}`
@@ -464,8 +468,8 @@ const commands = {
 
   async restart(bots, values) {
     refuseWhenOrcaIsDown();
-    const { closed, tabs, rules, skills, paused } = await restartSessions(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, closed };
+    const { closed, tabs, rules, skills, paused, projects } = await restartSessions(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects, closed };
     const what = values.session === undefined ? values.bot : `${values.bot} ${values.session}`;
     return {
       answer,
@@ -518,11 +522,25 @@ const commands = {
     }
 
     const retired = await retireBot(bots, { bot: values.bot });
+    if (retired.trouble !== undefined) {
+      return {
+        answer: { bots, ...retired },
+        lines: [
+          ...closedLines(retired.closed),
+          `${'trouble'.padEnd(9)}  Orca project ${retired.project}`,
+          `             ${retired.trouble}`,
+          `Retire it again:  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${retired.bot}`,
+        ],
+        code: 1,
+      };
+    }
     return {
       answer: { bots, ...retired },
       lines: [
         ...closedLines(retired.closed),
-        ...(retired.project === undefined ? [] : [`removed    Orca project ${retired.project}`]),
+        // After every removal, whatever the window was told: Orca's window can
+        // keep a removed project's row even after it re-reads (stablyai/orca#20102).
+        ...(retired.project === undefined ? [] : [`removed    Orca project ${retired.project}`, RELOAD_LINE]),
         `retired    ${retired.bot}: moved to ${path.relative(bots, retired.moved)}, with its book, charter and memory`,
       ],
     };
@@ -1084,9 +1102,24 @@ function skillsLines(skills) {
     ...(entry.trouble === undefined ? [] : [`  ${'trouble'.padEnd(9)}  ${entry.trouble}`]),
     ...entry.skills.map((skill) => `  ${(skill.managed ? 'linked' : 'yours').padEnd(9)}  ${skill.name.padEnd(24)}  ${skill.from ?? 'no list names it; the kit leaves it alone'}`),
     ...(entry.removed ?? []).map((name) => `  ${'removed'.padEnd(9)}  ${name.padEnd(24)}  no list names it now`),
+    ...(entry.sessions ?? []).map((one) => toldLine(entry.bot, one)),
   ]);
 }
 
+/** What `skills build` did about one running session of a bot whose skills changed. */
+function toldLine(bot, { session, harness, state, read, blocked, trouble }) {
+  const who = `${bot}/${session}`;
+  const after = harness === 'claude' ? 'Once that is settled, type /reload-skills in its tab.' : 'Its next turn takes the change by itself.';
+  const [word, says] = {
+    reloaded: ['reloaded', '/reload-skills was typed into its tab; a busy session runs it when its turn ends'],
+    'next-turn': ['next turn', `Codex takes the change at the start of its next turn. If a skill is not there then, a restart makes it appear${read?.length > 0 ? `; meanwhile it can read ${read.join(', ')}` : ''}`],
+    'not-up': ['not told', 'not up; it reads its skills when it starts'],
+    blocked: ['not told', `its tab is waiting for an answer (${blocked}), so nothing was typed. ${after}`],
+    unknown: ['not told', `${trouble}. ${after}`],
+  }[state];
+  return `  ${word.padEnd(9)}  ${who.padEnd(24)}  ${says}`;
+}
+
 /**
  * What a check found, two lines each: what kind of trouble it is and the one
  * thing to go and look at, then the sentence about it. The same shape wherever
@@ -1095,7 +1128,7 @@ function skillsLines(skills) {
 const foundLines = (found) =>
   found.flatMap((one) => [`${one.kind.padEnd(9)}  ${one.where}`, `             ${one.says}`]);
 
-function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], found = [] }, summary) {
+function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], projects = [], found = [] }, summary) {
   const lines = [
     ...created.map((entry) => `created    ${entry}`),
     ...completed.map((entry) => `completed  ${entry}`),
@@ -1115,7 +1148,10 @@ function tabLines({ bots, created, completed, rules, skills, tabs, paused = [],
 
   // Last before the summary, because what a check found is about the setup the
   // run has just left behind rather than about any one thing it did.
-  lines.push(...foundLines(found), summary);
+  lines.push(...foundLines(found));
+  // Hedged, because nothing here can see whether the window was told (#224).
+  if (projects.length > 0) lines.push(RELOAD_LINE);
+  lines.push(summary);
   return lines;
 }
 
@@ -1144,8 +1180,17 @@ function harnessLines(tab, bots) {
     ];
   }
 
+  // Orca naming no reason does not mean nothing is on screen: on 1.4.209 it
+  // names none for Codex's trust and hooks screens, nor for Claude Code's trust
+  // list (tech notes, section 1, #288). So the kit says what it cannot see.
   const lines = tab.blockedReason === undefined
-    ? [...how, '             the harness was typed in and came up.']
+    ? [
+      ...how,
+      '             the harness was typed in and is running. The kit cannot see whether a screen',
+      '             in it is waiting for an answer.',
+      `             Look at it:  ${lookAt(tab.terminal)}`,
+      ...ANSWER_IT,
+    ]
     : [
       ...how,
       `             the harness was typed in and came up, waiting on: ${tab.blockedReason}`,

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,48 @@ 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 };
+}
+
 /** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
 const psCli = () => process.env.OBK_PS || '/bin/ps';
 
@@ -235,7 +321,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 +412,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/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/skills.js

@@ -3,25 +3,30 @@
 //
 // Linked, never copied, in both directions. Inwards: what lands in the bot home
 // is a symlink to the skill's own directory, so a kit skill is read where the
-// package installed it and an edit to a skill is what a running session reads —
-// both harnesses follow a symlinked skill folder and pick a change up without a
-// restart (tech notes, sections 2 and 3). Outwards: the kit takes away only the
-// links it put there, and never the skill one was pointing at.
+// package installed it, and both harnesses follow the link. A running session
+// reads an edited skill the next time it loads it. A skill linked in or taken
+// 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
+// there, and never the skill one was pointing at.
 //
 // An entry names one of four shelves: the kit's own (`kit:<name>`), an online
 // source `skills.yaml` lists (`<source>:<name>`, read from its clone beside the
 // bots folder), the user's common folder (a bare name), or a path to anywhere
 // on disk.
 
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { parse, parseDocument, stringify } from 'yaml';
 
+import { bookFile, readBook } from './book.js';
 import { botDir, botNames, changesExactly, leadsOutside, readBot, YAML_OUT } from './bot.js';
-import { ownCli, shellWord } from './launch.js';
+import { harnessOf, ownCli, shellWord } from './launch.js';
+import { orcaCli, orcaTrouble, tabToTypeInto, typeIntoTab } from './orca.js';
 import { listIn } from './rules.js';
 import { cloneDir, isCloned, readSources, skillsIn, wrongClone } from './sources.js';
 
@@ -130,7 +135,7 @@ export function removeSkill(bots, bot, ref) {
 
 /**
  * Give one bot the skills its lists name. Returns what there is to report:
- * `{ bot, skills, removed }` for a bot whose links are in place, and
+ * `{ 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.
  *
  * A list with one entry the kit cannot follow links nothing at all: half a
@@ -210,6 +215,7 @@ export function linkSkills(bots, home, bot) {
   // something to throw through `prepareBots` and stop the fleet. What was
   // linked before it went wrong is still written down, so the next run knows it
   // for the kit's own.
+  const linked = [];
   const removed = [];
   try {
     for (const harness of Object.keys(SKILL_DIRS)) {
@@ -218,8 +224,8 @@ export function linkSkills(bots, home, bot) {
         held.set(harness, heldIn(path.join(home, SKILL_DIRS[harness]), record[harness]));
         continue;
       }
-      const done = link(path.join(home, SKILL_DIRS[harness]), wanted, record[harness]);
-      removed.push(...done.removed);
+      // Filled as it goes, so what was changed before a failure is still known.
+      const done = link(path.join(home, SKILL_DIRS[harness]), wanted, record[harness], linked, removed);
       held.set(harness, done.held);
     }
   } catch (error) {
@@ -232,6 +238,9 @@ export function linkSkills(bots, home, bot) {
     return {
       bot: bot.name,
       skills: heldBy(home, [], held),
+      // What did change before it went wrong, so the sessions it reaches are told.
+      linked: [...new Set(linked)].sort(),
+      removed: [...new Set(removed)].sort(),
       trouble: `${bot.name}'s skills could not be linked: ${error.message}. Nothing of yours was changed; put right what is named there, then build again.`,
     };
   }
@@ -243,6 +252,7 @@ export function linkSkills(bots, home, bot) {
     return {
       bot: bot.name,
       skills,
+      linked: [...new Set(linked)].sort(),
       removed: [...new Set(removed)].sort(),
       trouble: [...away].map(([harness, real]) => `${path.join(home, SKILL_DIRS[harness])} leads outside the bot folder, to ${real}, through a link, and the kit links skills only inside the bot folder, so ${harness} does not get the skills the lists name. Replace the link with a directory of the bot's own, then build again.`).join(' '),
     };
@@ -251,6 +261,7 @@ export function linkSkills(bots, home, bot) {
   return {
     bot: bot.name,
     skills,
+    linked: [...new Set(linked)].sort(),
     removed: [...new Set(removed)].sort(),
     // A name the lists ask for that the bot has something else under. The user's
     // own is never written over, so what they have to know is that the list did
@@ -391,7 +402,8 @@ function namesIn(dir) {
 
 /**
  * Give every bot in the folder its skills, or the one named, in name order.
- * This is the whole of `obk skills build`: it writes links and asks Orca nothing.
+ * This is the whole of `obk skills build`: it writes links, and a bot whose
+ * links changed has its running sessions told (`tellSessions`).
  */
 export function buildSkills(bots, { bot: onlyBot } = {}) {
   const names = botNames(bots);
@@ -401,11 +413,89 @@ export function buildSkills(bots, { bot: onlyBot } = {}) {
 
   return (onlyBot === undefined ? names : [onlyBot]).map((name) => {
     const home = botDir(bots, name);
+    let bot;
+    let entry;
     try {
-      return linkSkills(bots, home, readBot(home, name));
+      bot = readBot(home, name);
+      entry = linkSkills(bots, home, bot);
     } catch (error) {
       return { bot: name, skills: [], trouble: error.message };
     }
+    const changed = (entry.linked?.length ?? 0) + (entry.removed?.length ?? 0) > 0;
+    return changed ? { ...entry, sessions: tellSessions(home, bot, entry.linked) } : entry;
+  });
+}
+
+/** How long Orca is given to say what is in a session's tab. */
+const LOOK_MS = 2000;
+
+/**
+ * Tell each session of a bot whose skill links just changed, through its
+ * 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
+ * `blocked`) or `unknown` (with `trouble`).
+ *
+ * Claude Code gets `/reload-skills` typed into its tab, through the same gate
+ * as the mail nudge. A busy session queues it and runs it as a command when
+ * its turn ends, so it never reaches the model as text. Codex has no reload
+ * 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.
+ */
+function tellSessions(home, bot, linked) {
+  let book;
+  try {
+    book = readBook(home).sessions;
+  } catch (error) {
+    // The links are made; which tab is whose is what cannot be known.
+    const trouble = `${bookFile(home)} cannot be read (${error.message}), so the kit could not tell which tab is this session's, and nothing was typed`;
+    return bot.sessions.map((session) => ({ session: session.name, harness: harnessOf(session, bot.harness), state: 'unknown', trouble }));
+  }
+  // Resolved, because Orca is asked about this folder by path and does not
+  // follow a link to it (tech notes, section 1).
+  let real;
+  try {
+    real = realpathSync(home);
+  } catch {
+    real = home;
+  }
+  // An Orca whose runtime is not there still answers some commands from what
+  // it last knew, so it is asked whether it is up before it is asked anything
+  // about a tab.
+  const down = bot.sessions.some((session) => typeof book[session.name]?.tab === 'string') ? orcaTrouble() : undefined;
+
+  return bot.sessions.map((session) => {
+    const harness = harnessOf(session, bot.harness);
+    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' };
+    if (down !== undefined) return { ...told, state: 'unknown', trouble: `Orca is not answering at ${orcaCli()}, so the kit could not look at its tab, and nothing was typed` };
+    try {
+      const found = tabToTypeInto(real, tab, LOOK_MS);
+      if (found.blocked !== undefined) return { ...told, state: 'blocked', blocked: found.blocked };
+      if (found.unsure !== undefined) return { ...told, state: 'unknown', trouble: found.unsure };
+      if (found.handle === undefined) return { ...told, state: 'not-up' };
+      // The book's tab, now running the other harness: its reload is not this one's.
+      if (found.agent !== harness) {
+        return { ...told, state: 'unknown', trouble: `Orca names ${found.agent} in its tab, not ${harness}, so nothing was typed` };
+      }
+
+      if (harness === 'codex') {
+        // Only what Codex can actually read: a link can fail for one harness
+        // alone, and a skills directory that is the user's gets none.
+        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');
+      return { ...told, state: 'reloaded' };
+    } catch (error) {
+      // The links are made whatever Orca says, so this is reported, not
+      // thrown: the build did what it was asked, and the session was not told.
+      return { ...told, state: 'unknown', trouble: error.message };
+    }
   });
 }
 
@@ -489,7 +579,9 @@ function follow(bots, ref, sources) {
 
 /**
  * Make one harness's skills directory hold what `wanted` says, as far as the
- * kit is allowed to. Returns `{ removed, held }` — the names it took away, and
+ * kit is allowed to. Returns `{ linked, removed, held }` — the names it linked
+ * in or repointed, the names it took away (added to the lists given, as it
+ * goes, so a caller whose run throws still has them), and
  * what is in the directory afterwards.
  *
  * The kit acts only where the entry on disk is still the link it wrote, which
@@ -497,12 +589,10 @@ function follow(bots, ref, sources) {
  * link the very same skill by hand — so the kit remembers what it made rather
  * than guessing from where a link points (PRD 6.7).
  */
-function link(dir, wanted, record) {
+function link(dir, wanted, record, linked = [], removed = []) {
   // The directory is there: `linkSkills` makes both before it calls this.
 
   const keep = new Map(wanted.map((skill) => [skill.name, skill]));
-  const removed = [];
-
   // What the lists no longer name. The kit takes back only its own, and only
   // while it is untouched; anything else it forgets about and leaves.
   for (const name of Object.keys(record)) {
@@ -541,9 +631,10 @@ function link(dir, wanted, record) {
     // repo, and the link has to reach out of the repo to find it (ADR 0014).
     symlinkSync(skill.dir, at);
     record[skill.name] = skill.dir;
+    linked.push(skill.name);
   }
 
-  return { removed, held: heldIn(dir, record) };
+  return { linked, removed, held: heldIn(dir, record) };
 }
 
 /**

package/src/up.js

@@ -12,7 +12,7 @@ import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isShortPrompt, launchCommand, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, typeIntoTab, useMailbox } from './orca.js';
+import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, tellWindow, typeIntoTab, useMailbox } from './orca.js';
 import { buildAgents } from './rules.js';
 import { linkSkills } from './skills.js';
 
@@ -35,6 +35,7 @@ const SECOND_LOOK_MS = 2000;
  * Bring bots up in Orca. Returns `{ tabs, rules }`: one tab entry per tab it
  * looked at — the sessions the book knows, and, for Bot Father, whatever else
  * is open in its project — and one rules entry and one skills entry per bot.
+ * `projects` has one entry per Orca project this run made or renamed.
  *
  * With no name it is every bot in the folder, in name order. `bot` brings up
  * one bot and `session` one of its sessions, for a caller that wants one thing
@@ -58,11 +59,14 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
   const { running, rules, skills } = prepareBots(bots, names, onlySession);
 
   const report = [];
+  const projects = [];
   for (const { bot, home } of running) {
     for (const session of sessionsOf(bot, onlySession)) {
       if (session.paused === true) paused.push({ bot: bot.name, session: session.name });
     }
-    report.push(...await bringUpBot(bots, home, bot, onlySession));
+    const up = await bringUpBot(bots, home, bot, onlySession);
+    report.push(...up.tabs);
+    if (up.project !== undefined) projects.push(up.project);
   }
 
   // A bot whose rules would not build is reported here rather than in the
@@ -78,6 +82,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
     })),
     skills,
     paused,
+    projects,
   };
 }
 
@@ -197,8 +202,11 @@ async function bringUpBot(bots, home, bot, onlySession) {
   // Orca is asked first and the book is written after: nothing that takes time
   // happens while the book is held, because a session's own hook may be writing
   // its id into that same file at any moment.
-  const orca = orcaProject(home, title);
+  const { change, ...orca } = orcaProject(home, title);
   await updateBook(home, (book) => { book.orca = orca; });
+  // Orca's window does not see a project made or renamed on the command line
+  // until it is told (#224).
+  if (change !== undefined) tellWindow(orca.project);
 
   const live = new Map(tabs(home).map((tab) => [tab.tabId, tab]));
   const report = [];
@@ -217,7 +225,7 @@ async function bringUpBot(bots, home, bot, onlySession) {
       : spare.map((tab) => entry(tab, { bot: name, name: null, created: false }))));
   }
 
-  return report;
+  return { tabs: report, project: change === undefined ? undefined : { bot: name, project: orca.project, change } };
 }
 
 async function bringUpSession(bots, home, live, session, bot, title) {
@@ -455,7 +463,8 @@ function whichConversation(book, home, bot, session, was, harness) {
 }
 
 /**
- * A bot's Orca project, made if it is not there yet.
+ * A bot's Orca project, made if it is not there yet, with `change` saying
+ * whether this run `made` it, `renamed` it or left it as it was (undefined).
  *
  * It has to be a folder workspace. Registering a folder that sits inside the
  * bots repo gets it recorded as a git one, which Orca gives no workspace at
@@ -463,12 +472,12 @@ function whichConversation(book, home, bot, session, was, harness) {
  */
 function orcaProject(home, title) {
   const found = findProject(home);
-  const setup = found === undefined
-    ? makeProject(home, title)
-    : (found.kind === 'folder' ? found : asFolderProject(found.id, title));
-  return { project: setup.projectId, setup: setup.id };
+  if (found === undefined) return ids(makeProject(home, title), 'made');
+  return found.kind === 'folder' ? ids(found) : ids(asFolderProject(found.id, title), 'renamed');
 }
 
+const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, change });
+
 /**
  * Where the kit leaves a prompt for the launch line to pick up: a folder of its
  * own beside the bots repo, the way skill-source clones sit beside it (PRD 6.3)