@assuredloop/orca-bot-kit 0.2.0 → 0.4.0

package/src/skills.js

@@ -1,26 +1,32 @@
 // The skills a bot has: links in the bot's own folder, into both harnesses
-// (PRD 6.7, ADR 0004, ADR 0009).
+// (PRD 6.7, ADR 0014, ADR 0019).
 //
 // 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 { 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';
 
@@ -39,7 +45,7 @@ export const SKILL_DIRS = {
 /**
  * What a skill may be called: the Agent Skills name, which is also the name of
  * the directory it lives in and of the link the kit makes (tech notes, section
- * 4, and ADR 0009).
+ * 4, and ADR 0019).
  */
 const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
@@ -129,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
@@ -209,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)) {
@@ -217,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) {
@@ -231,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.`,
     };
   }
@@ -242,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(' '),
     };
@@ -250,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
@@ -280,7 +292,7 @@ export function unlinkSkills(home) {
  * user made, or one of the kit's that they have since repointed, is theirs.
  *
  * It is the kit's own file and lives beside the hook files it already keeps in
- * the bot folder (ADR 0010). A record that cannot be read is treated as an
+ * the bot folder (ADR 0020). A record that cannot be read is treated as an
  * empty one: the worst that follows is that the kit leaves alone something it
  * would otherwise have tidied up, which is the safe way round.
  */
@@ -311,7 +323,7 @@ function writeRecord(home, record) {
  *
  * A link that leads nowhere is reported whoever made it. Whose it is changes
  * what may be done about it, not the fact that a session cannot read the skill
- * (ADR 0004).
+ * (ADR 0014).
  */
 export function skillsTrouble(bots, home, bot) {
   const record = readRecord(home);
@@ -390,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);
@@ -400,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 };
+    }
   });
 }
 
@@ -460,7 +551,7 @@ function follow(bots, ref, sources) {
         throw new Error(`${ref} names the source ${named}, and skills.yaml lists no source called that.`);
       }
       if (!isCloned(bots, named)) {
-        throw new Error(`${ref}: ${named} has not been fetched yet, so there is nothing to link. Run obk skills fetch --bots ${bots} --source ${named}.`);
+        throw new Error(`${ref}: ${named} has not been fetched yet, so there is nothing to link. Run ${shellWord(ownCli())} skills fetch --bots ${shellWord(bots)} --source ${named}.`);
       }
       const wrong = wrongClone(bots, source);
       if (wrong !== undefined) throw new Error(`${ref}: ${wrong}`);
@@ -488,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
@@ -496,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)) {
@@ -537,12 +628,13 @@ function link(dir, wanted, record) {
     }
 
     // Absolute: a kit skill lives in the installed package, outside the user's
-    // repo, and the link has to reach out of the repo to find it (ADR 0004).
+    // 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/sources.js

@@ -1,4 +1,4 @@
-// Skills from an online repo, at the version the user pinned (PRD 6.7, ADR 0004).
+// Skills from an online repo, at the version the user pinned (PRD 6.7, ADR 0014).
 //
 // A source is a git repository the user names in `<bots>/skills.yaml`. The kit
 // clones it into `<bots>.skill-sources/<name>`, a sibling of the bots folder and
@@ -19,6 +19,7 @@ import path from 'node:path';
 import { parseDocument } from 'yaml';
 
 import { changesExactly, requireBotsFolder, YAML_OUT } from './bot.js';
+import { ownCli, shellWord } from './launch.js';
 
 /** The user's file that lists where skills come from. */
 const SKILLS_YAML = 'skills.yaml';
@@ -201,7 +202,7 @@ function clone(bots, source, rev, recorded) {
 export function wrongClone(bots, source) {
   const from = originOf(cloneDir(bots, source.name));
   if (from === source.repo) return undefined;
-  return `${source.name}: the clone beside your bots folder came from ${from}, and skills.yaml now names ${source.repo}. Run obk skills update --source ${source.name} to take it from there instead.`;
+  return `${source.name}: the clone beside your bots folder came from ${from}, and skills.yaml now names ${source.repo}. Run ${shellWord(ownCli())} skills update --source ${source.name} to take it from there instead.`;
 }
 
 /** Where a clone came from, as git itself has it written down. */
@@ -226,7 +227,7 @@ function checkout(dir, source, rev, recorded) {
 
   if (at === undefined) {
     throw new Error(recorded
-      ? `${source.name}: ${source.repo} no longer has the commit skills.yaml records for it (${rev.slice(0, 7)}), so the version you pinned cannot be put back. Run obk skills update --source ${source.name} to take what ${source.ref} names now, or point it at a version the repo still has.`
+      ? `${source.name}: ${source.repo} no longer has the commit skills.yaml records for it (${rev.slice(0, 7)}), so the version you pinned cannot be put back. Run ${shellWord(ownCli())} skills update --source ${source.name} to take what ${source.ref} names now, or point it at a version the repo still has.`
       : `${source.name}: ${source.repo} has nothing called ${rev}`);
   }
   git(['-c', 'advice.detachedHead=false', 'checkout', '--quiet', at], dir, `${source.name}: could not go to ${rev}`);

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, makeMailbox, makeProject, openTab, retitleTab, tabs, tuiInTab, typeIntoTab } 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';
 
@@ -26,8 +26,8 @@ const STARTUP_MS = 10000;
  * And how long the second look takes. A harness can draw its first screen and
  * then die on something it was handed — a context window it cannot read, an
  * extra argument it does not know — and the first look would have called it
- * started. A tab whose TUI is still there answers this at once; only one that
- * has fallen back to a shell waits it out.
+ * started. An idle harness answers this at once; a busy one and a shell both
+ * wait it out, and it is the tab's foreground that tells them apart (#232).
  */
 const SECOND_LOOK_MS = 2000;
 
@@ -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,
   };
 }
 
@@ -87,7 +92,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
  *
  * Separate from the tabs because the order matters twice over. A session reads
  * its rules, its skills and its hooks as it comes up, so all three have to be
- * there before the tab is (PRD 6.6, ADR 0010) — and a restart closes a tab in
+ * there before the tab is (PRD 6.6, ADR 0020) — and a restart closes a tab in
  * between, so everything that can refuse must have refused before that. It
  * refuses by throwing, exactly as `up` always has; a bot it leaves out of
  * `running` is one whose sessions must not be started.
@@ -133,7 +138,7 @@ export function prepareBots(bots, names, onlySession) {
 
   // And the kit's hook goes into every bot folder before Orca is asked for
   // anything, for the same reason: a harness reads its hooks when it comes up,
-  // so one written later would miss the session it was written for (ADR 0010),
+  // so one written later would miss the session it was written for (ADR 0020),
   // and a bot folder the kit cannot write it into stops the run with nothing
   // opened anywhere. Only the harnesses a bot actually runs on; a bot with no
   // sessions gets none.
@@ -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) {
@@ -234,7 +242,7 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     // live harness. Writing the name down here would advertise an address that
     // answers to nobody (review of PR #132, finding 1). It gets one the next
     // time it starts, which is the next time the kit types its launch line.
-    await ensureMailbox(home, bot, session, harness);
+    await ensureMailbox(home, bot, session, harness, known.handle);
 
     // Whatever runs in the tab may have rewritten its title. The kit writes its
     // own back, and reports that one rather than the name Orca last saw: the id
@@ -312,7 +320,7 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // tab is on the books, so a mailbox Orca will not make leaves a tab the next
   // run finds and finishes rather than a tab nobody owns (review of PR #132,
   // finding 3).
-  await ensureMailbox(home, bot, session, harness, { named: harness === 'claude' });
+  await ensureMailbox(home, bot, session, harness, made.handle, { named: harness === 'claude', opened: true });
 
   // And then asking whether a TUI came up, rather than assuming one did. The
   // text goes into the tab's own shell, which may have been busy with a
@@ -321,9 +329,9 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // Twice, because coming up and staying up are different things: a harness
   // that refuses what it was handed draws a screen, prints its complaint and
   // leaves a shell behind, and a run that looked once would report it as
-  // started. A tab that still has a TUI answers the second look at once,
-  // whatever the agent in it is busy with.
-  const tui = tuiInTab(made.handle, STARTUP_MS).running ? tuiInTab(made.handle, SECOND_LOOK_MS) : { running: false };
+  // started.
+  const first = lookFor(made.handle, STARTUP_MS);
+  const tui = first.running ? lookFor(made.handle, SECOND_LOOK_MS) : first;
 
   // The start prompt went in with that line, as the harness's own prompt
   // argument, so it is the harness that holds it until it is ready — through
@@ -344,6 +352,23 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   });
 }
 
+/**
+ * One look at a tab the kit just typed a launch line into: whether a harness
+ * is running there, and what it is waiting on if Orca says.
+ *
+ * The harness is up when something other than the shell holds the tab's
+ * terminal, busy or not, or when Orca sees a question on its screen. Orca's
+ * `agentIdentity` is not asked for: it can come seconds after the launch
+ * (tech notes, section 1). When the tab's foreground cannot be read, Orca's own
+ * answers stand in, for this report only: nothing more is typed here.
+ */
+function lookFor(handle, timeoutMs) {
+  const seen = harnessInTab(handle, timeoutMs);
+  const running = seen.blockedReason !== undefined
+    || (seen.front === undefined ? seen.answered || seen.agent !== undefined : seen.front === 'program');
+  return { running, blockedReason: seen.blockedReason };
+}
+
 /**
  * Make sure the book holds this session's mailbox, and — only where this run
  * has just launched the session under it — the name it answers to.
@@ -361,15 +386,23 @@ async function bringUpSession(bots, home, live, session, bot, title) {
  * a restart (tech notes, section 1). Orca offers no way to delete one, so this
  * makes exactly one per session and never a second.
  *
+ * It is bound to `handle`, the session's own tab, and never to the tab this run
+ * of `obk up` was typed in: Orca tells a Run's coordinator about its mail, and
+ * only the session the mail is for should be told (issue #228). A mailbox the
+ * session already had is bound again when this run `opened` a new tab for it —
+ * after a restart, or a closed tab brought back — or it would stay with the tab
+ * that is gone (review of PR #248, finding 1).
+ *
  * A Codex session whose user turned the sandbox switch off gets none: it could
  * not read a mailbox if it had one, and an address nobody can read is worse
  * than none at all. `obk message` says so in those words.
  */
-async function ensureMailbox(home, bot, session, harness, { named = false } = {}) {
+async function ensureMailbox(home, bot, session, harness, handle, { named = false, opened = false } = {}) {
   const held = readBook(home).sessions[session.name] ?? {};
+  if (opened && typeof held.mailbox === 'string') useMailbox(held.mailbox, handle);
 
   const address = named ? addressOf(bot.name, session.name) : undefined;
-  const mailbox = mailboxFor(readBook(home), bot, session, harness);
+  const mailbox = mailboxFor(readBook(home), bot, session, harness, handle);
 
   if (mailbox === undefined && (address === undefined || held.address === address)) return;
 
@@ -392,10 +425,10 @@ async function ensureMailbox(home, bot, session, harness, { named = false } = {}
  * The Orca call is made outside the book's lock, which is held for one read and
  * one write (book.js).
  */
-function mailboxFor(book, bot, session, harness) {
+function mailboxFor(book, bot, session, harness, handle) {
   const held = book.sessions[session.name] ?? {};
   if (typeof held.mailbox === 'string' || !reachesMail(session, harness)) return undefined;
-  return makeMailbox(`${bot.name}/${session.name}`);
+  return makeMailbox(`${bot.name}/${session.name}`, handle);
 }
 
 /**
@@ -403,7 +436,7 @@ function mailboxFor(book, bot, session, harness) {
  * the one the book holds, one the harness itself still has on record, or none.
  *
  * One tab holds one session, and the book is the authority for which
- * conversation that is (ADR 0002). But the book can be incomplete — on Codex a
+ * conversation that is (ADR 0012). But the book can be incomplete — on Codex a
  * hooks file must be trusted before any hook runs, and trusting it does not
  * replay the event it missed — and "the book does not say" must never be read as
  * "there was no conversation". So where the book is silent about a tab the kit
@@ -430,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
@@ -438,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)

package/src/usage.js

@@ -5,10 +5,10 @@
 // and efforts, between which two moments, and how many times it was compacted.
 // What any of that costs is a skill's to work out: a price comes from a live
 // lookup and a price that cannot be found has to be said to be unknown, which is
-// judgement and not arithmetic (ADR 0006).
+// judgement and not arithmetic (ADR 0016).
 //
 // Which conversation belongs to which session is the book's to say and is never
-// guessed, as everywhere else in the kit (ADR 0002). A session's conversations
+// guessed, as everywhere else in the kit (ADR 0012). A session's conversations
 // are the one the book names for it now and the ones in its history. One in the
 // bot's folder that no session claims is reported under the bot instead, with
 // its figures, so that what it spent is visible rather than quietly dropped.