@assuredloop/orca-bot-kit 0.20.0 → 0.21.0

package/README.md

@@ -344,6 +344,12 @@ settings ([ADR 0022](docs/adr/0022-kit-hooks-live-in-the-bot-folder.md)). Your o
 settings in those files are kept. Codex asks you to trust a hooks file the first
 time it sees one; answer its question in the tab.
 
+A Claude bot gets one more hook there. Claude Code's own messaging reaches every
+Claude session on the machine, so after a session sends a native message to an
+address that is none of your bots folder's sessions, the hook tells it so, and
+names the address `obk message to` would have given. The message goes either
+way ([ADR 0032](docs/adr/0032-a-native-message-outside-the-fleet-is-warned-about.md)).
+
 So: kill a tab, or reboot, and `obk up` brings the session back with the
 conversation it was having, rather than starting a new one. Clear a session —
 `/clear` on Claude Code, `/new` on Codex — and the kit writes down the new id,

package/package.json

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

package/rules/temporary.md

@@ -4,18 +4,17 @@ title: Temporary sessions of your own
 applies: all
 ---
 
-For a piece of work that wants a helper, a long-lived session may make a
-temporary session of its own bot, without asking Bot Father:
+For a piece of work that wants a helper, a session may make a temporary
+session of its own bot, without asking Bot Father:
 `"${OBK_CLI:-obk}" temp make --bots <bots> --name <name> --prompt <the task>`,
 run in your own tab. It takes your settings unless you say otherwise, and gets
-a work dir, a tab and a mailbox.
+a work dir, a tab and a mailbox. A temporary session may make one of its own,
+one at a time; one made by a temporary session makes none.
 
 A new tab can stop on a first-run screen. Answer it yourself, from the table
 the command's output points to.
 
-Retire it when its work is done:
+Retire it when its work is done, and what it made goes with it:
 `"${OBK_CLI:-obk}" temp retire --bots <bots> --name <name>`. Before you make
-another, first retire any of yours whose work is done.
-
-You manage only the temporary sessions you made; a temporary session makes
-none of its own. Every other session is Bot Father's to make, change or retire.
+another, first retire any of yours whose work is done. You manage only the
+temporary sessions you made; every other session is Bot Father's.

package/src/cli.js

@@ -24,6 +24,7 @@ import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
 import { retireBot, retireSession } from './retire.js';
+import { sentWarning } from './sent.js';
 import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
 import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
@@ -90,28 +91,34 @@ Usage:
                             session with the conversation it was having.
   obk retire --bots <path> --bot <bot> [--session <name>]
                             End a session: close its tab and take it off the
-                            bot, keeping its conversations in the book. Or end
-                            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, and moves the folder only once Orca no
-                            longer lists the project.
+                            bot, keeping its conversations in the book, and
+                            first do the same for the temporary sessions it
+                            made, and theirs. Or end 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, and
+                            moves the folder only once Orca no longer lists
+                            the project.
   obk temp make --bots <path> --name <session>
                 (--prompt <text> | --prompt-file <path>) [--harness claude|codex]
                 [--model <m>] [--effort <e>] [--context <c>]
                 [--approval ${APPROVALS.join('|')}] [--extra-arg=<arg>]...
-                            Run in a long-lived session's own tab: make a
-                            temporary session of that session's bot for a piece
-                            of work, and bring it up. It takes your harness,
-                            model, effort, context and approval unless you say
-                            otherwise; on another harness than yours it takes
-                            only your approval. It works in work/<session>, and
-                            has the task as its start prompt. The book records
-                            it as temporary, made by you.
+                            Run in a session's own tab: make a temporary
+                            session of that session's bot for a piece of work,
+                            and bring it up. A temporary session makes one at
+                            a time, and one it made makes none. It takes your
+                            harness, model, effort, context and approval unless
+                            you say otherwise; on another harness than yours
+                            it takes only your approval. It works in
+                            work/<session>, and has the task as its start
+                            prompt. The book records it as temporary, made by
+                            you.
   obk temp retire --bots <path> --name <session>
                             Run in the maker's own tab: retire a temporary
                             session it made, as obk retire does. It refuses a
                             long-lived session, or one another session made.
+                            Like obk retire, it first retires the temporary
+                            sessions that session made.
   obk temp trust-hooks --bots <path> --name <session>
                             Run in the maker's own tab: answer the hooks review
                             of a Codex temporary session it made with "Trust
@@ -230,6 +237,11 @@ Usage:
                             For the kit's own hook, not for typing: it reads
                             what the harness says about a session starting on
                             standard input and writes it into the book.
+  obk session sent --bots <path> --bot <bot>
+                            For the kit's own hook, not for typing: after a
+                            Claude session's native message, it warns the
+                            session when the address was none of this bots
+                            folder's own. It never stops a message.
   obk session mailbox --bots <path> --bot <bot> --session <name>
                             For the kit's own launch line, not for typing: run
                             in the session's own tab, it gives the session its
@@ -269,6 +281,7 @@ const COMMANDS = {
   'message send': ['bots', 'to', 'subject'],
   'message check': ['bots'],
   'session record': ['bots', 'bot'],
+  'session sent': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
   'temp make': ['bots', 'name'],
   'temp retire': ['bots', 'name'],
@@ -394,6 +407,10 @@ async function run(argv) {
     throw new Error(`--harness is ${HARNESSES.join(' or ')}, and got: ${values.harness}`);
   }
 
+  // The send hook is quiet whatever it is given, a bots folder that is not
+  // there included, so it goes before anything that can complain (ADR 0032).
+  if (command === SENT) return sent(path.resolve(values.bots));
+
   // One fleet, one identity, whatever spelling of its path was given (#164).
   const bots = command === 'init' ? path.resolve(values.bots) : sameFleet(path.resolve(values.bots));
   if (command === RECORD) return record(bots, values.bot);
@@ -457,8 +474,26 @@ const ANSWER_IT = [
   '             Anything you do not recognise gets no keypress: take it to the user.',
 ];
 
-/** The one command a harness runs rather than a person: the kit's hook. */
+/** The commands a harness runs rather than a person: the kit's hooks. */
 const RECORD = 'session record';
+const SENT = 'session sent';
+
+/**
+ * What the kit's send hook says after a native message: a warning the session
+ * reads, as Claude Code's `additionalContext`, or nothing. Never a decision,
+ * and never anything but exit 0 (ADR 0032).
+ */
+function sent(bots) {
+  try {
+    const warning = sentWarning(bots, JSON.parse(readFileSync(0, 'utf8')));
+    if (warning !== undefined) {
+      process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: warning } })}\n`);
+    }
+  } catch {
+    // Nothing: a hook does not disturb the session it runs in.
+  }
+  return 0;
+}
 
 /**
  * What the kit's hook does with what the harness told it, and what it answers.
@@ -571,6 +606,7 @@ const commands = {
       return {
         answer: { bots, ...retired },
         lines: [
+          ...withLines(retired.retiredWith, retired.session),
           ...closedLines(retired.closed),
           `retired    ${retired.bot} ${retired.session}: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
           ...leftLines(retired.promptsLeft),
@@ -633,6 +669,7 @@ const commands = {
     return {
       answer: { bots, ...retired },
       lines: [
+        ...withLines(retired.retiredWith, retired.session),
         ...closedLines(retired.closed),
         `retired    ${retired.bot} ${retired.session}, a temporary session of ${retired.maker}'s: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
         ...leftLines(retired.promptsLeft),
@@ -1106,6 +1143,13 @@ function settingsOf(values) {
 /** The tabs a command closed, one line each. */
 const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab.name}  tab ${tab.tabId}  terminal ${tab.terminal}`);
 
+/** The temporary sessions a retire took along with the one it named, each as it went (#464). */
+const withLines = (retiredWith, session) => retiredWith.flatMap((gone) => [
+  ...closedLines(gone.closed),
+  `retired    ${gone.bot} ${gone.session}, a temporary session of ${gone.maker}'s, along with ${session}: off ${path.join('bots', gone.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+  ...leftLines(gone.promptsLeft),
+]);
+
 /** What a retire could not remove, and how to: nothing reads these files now (#393). */
 const leftLines = (left = []) => left.flatMap(({ file, reason }) => [
   `left       ${file}: it could not be removed (${reason}). Nothing reads it now.`,

package/src/hooks.js

@@ -42,6 +42,18 @@ const TIMEOUT = 10;
 export const hookCommand = (bots, bot, cli = ownCli()) =>
   `${shellWord(cli)} session record --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
+/**
+ * Claude Code's second kit hook: after a native `SendMessage`, a warning when
+ * it went outside the bots folder (ADR 0032). Claude Code only, since Codex has
+ * no native messaging.
+ */
+const SENT_EVENT = 'PostToolUse';
+const SENT_MATCHER = 'SendMessage';
+
+/** What the send hook runs, by the kit's own path, as `hookCommand` does. */
+export const sentCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session sent --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+
 /**
  * Make sure the bot at `home` has the kit's SessionStart hook for `harness`.
  * Returns the file it wrote, relative to the bot home, or undefined when the
@@ -63,7 +75,9 @@ export function installHook(home, harness, { bots, bot }) {
   // path is corrected rather than doubled, an entry under an event the kit no
   // longer asks about is taken out, and a hook of the user's beside the kit's
   // stays where they put it.
-  const wanted = { ...settings, hooks: withKitHook(settings.hooks, file, mine) };
+  const started = withKitHook(settings.hooks, file, mine);
+  const sentHook = { type: 'command', command: sentCommand(bots, bot), timeout: TIMEOUT };
+  const wanted = { ...settings, hooks: harness === 'claude' ? withSentHook(started, sentHook) : started };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -110,6 +124,27 @@ export function hookTrouble(home, harness, { bots, bot }) {
     }
     const program = running ?? ownCli();
     wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
+    // The send hook is judged on its own: the session hook may be right while
+    // the warning after a native message is missing (ADR 0032).
+    if (harness === 'claude' && isDeepStrictEqual(settings, wanted)) {
+      const sentRunning = sentProgramIn(settings);
+      // A send hook that runs a kit no longer there is as quiet as a missing
+      // one: `|| true` hides it, and no warning is ever given (#451 review).
+      if (sentRunning !== undefined && sentRunning !== BARE && !existsSync(sentRunning)) {
+        return {
+          where: file,
+          says: `${file} holds the kit's PostToolUse hook for SendMessage, but it runs ${sentRunning}, which is not there any more, so a session is never warned when its native message goes outside this bots folder (ADR 0032). obk up puts back one that runs the kit you have.`,
+        };
+      }
+      const sentProgram = sentRunning ?? program;
+      const withSent = { ...settings, hooks: withSentHook(settings.hooks, { type: 'command', command: sentCommand(bots, bot, sentProgram), timeout: TIMEOUT }) };
+      if (!isDeepStrictEqual(settings, withSent)) {
+        return {
+          where: file,
+          says: `${file} does not hold the kit's PostToolUse hook for SendMessage, which warns a session when its native message went outside this bots folder (ADR 0032). obk up puts it back.`,
+        };
+      }
+    }
   } catch (error) {
     return { where: file, says: `${error.message} ${stale}` };
   }
@@ -180,6 +215,58 @@ function withKitHook(hooks, file, mine) {
   return { ...events, [EVENT]: [...(events[EVENT] ?? []), { hooks: [mine] }] };
 }
 
+/**
+ * The hooks with the kit's send hook in a `PostToolUse` group matched to
+ * `SendMessage`, and everything else as the user left it, as `withKitHook`
+ * keeps the session hook: one entry of the kit's, written in place where it
+ * already sits in such a group, taken out of anywhere else, and added in a
+ * group of its own when there is none. A group the kit empties goes.
+ */
+function withSentHook(hooks, mine) {
+  let placed = false;
+  const events = Object.fromEntries(Object.entries(hooks).flatMap(([event, groups]) => {
+    if (!Array.isArray(groups)) return [[event, groups]];
+    const kept = groups.flatMap((group) => {
+      if (!Array.isArray(group?.hooks)) return [group];
+      const entries = group.hooks.flatMap((hook) => {
+        if (!isSentHook(hook)) return [hook];
+        if (event !== SENT_EVENT || group.matcher !== SENT_MATCHER || placed) return [];
+        placed = true;
+        return [mine];
+      });
+      return entries.length === 0 ? [] : [{ ...group, hooks: entries }];
+    });
+    return kept.length === 0 ? [] : [[event, kept]];
+  }));
+  if (placed) return events;
+  return { ...events, [SENT_EVENT]: [...(events[SENT_EVENT] ?? []), { matcher: SENT_MATCHER, hooks: [mine] }] };
+}
+
+
+/** Whether a hook entry is the kit's send hook, run by a kit, for any bots folder and bot. */
+const isSentHook = (hook) => sentProgramOf(hook?.command) !== undefined;
+
+function sentProgramOf(command) {
+  const found = typeof command === 'string' ? KIT_SENT.exec(command) : null;
+  if (found === null) return undefined;
+  const program = unquoted(found[1]);
+  return isKitCli(program) ? program : undefined;
+}
+
+/** What the kit's send hook in these settings runs, or undefined when there is none. */
+function sentProgramIn(settings) {
+  for (const groups of Object.values(settings.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const hook of Array.isArray(group?.hooks) ? group.hooks : []) {
+        const program = sentProgramOf(hook?.command);
+        if (program !== undefined) return program;
+      }
+    }
+  }
+  return undefined;
+}
+
 /**
  * The kit's own hook entry, wherever it sits and whatever sits beside it: a
  * command of exactly the shape `hookCommand` writes, for any bots folder and
@@ -194,6 +281,7 @@ const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
 /** One word as `shellWord` writes it: bare, or single-quoted with `'\''` inside. */
 const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
 const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 
 /** The program a bot made before the kit named itself by path runs. */
 const BARE = 'obk';

package/src/retire.js

@@ -25,6 +25,7 @@ import path from 'node:path';
 import { readBook, tabIdsIn, updateBook } from './book.js';
 import { botDir, dropSession, readBot } from './bot.js';
 import { deleteProject, findProject, projects, reloadWindow, tabs } from './orca.js';
+import { shellWord } from './launch.js';
 import { fleetMember } from './pause.js';
 import { closeTabs, commandLine, tabsToClose } from './restart.js';
 import { unlinkSkills } from './skills.js';
@@ -34,26 +35,57 @@ import { promptPath, sessionsOf } from './up.js';
 export const retiredDir = (bots) => path.join(bots, 'retired');
 
 /**
- * Retire the session `session` of the bot `bot`. Returns `{ bot, session,
- * closed }`, and `promptsLeft` when its prompt file could not be removed.
+ * Retire the session `session` of the bot `bot`, and first the temporary
+ * sessions it made, and theirs (#464, ADR 0033). Returns `{ bot, session,
+ * closed, retiredWith }`, and `promptsLeft` when its prompt file could not be
+ * removed. `retiredWith` holds one `{ bot, session, maker, closed }` for each
+ * session that went with it, deepest first, with its own `promptsLeft`.
  */
 export async function retireSession(bots, { bot, session }) {
   const home = fleetMember(bots, bot, 'retire', session);
-  const sessions = sessionsOf(readBot(home, bot), session);
+  const known = readBot(home, bot);
+  const sessions = sessionsOf(known, session);
 
-  const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, commandLine('retire', bots, bot, session));
-  dropSession(bots, bot, session);
+  const retiredWith = [];
+  const book = readBook(home);
+  const made = known.sessions.filter((one) => book.sessions[one.name]?.temporary?.maker === session);
+  let closed;
+  try {
+    for (const { name } of made) {
+      const { retiredWith: theirs, ...gone } = await retireSession(bots, { bot, session: name });
+      retiredWith.push(...theirs, { ...gone, maker: session });
+    }
 
-  const at = new Date().toISOString();
-  await updateBook(home, (book) => {
-    const entry = book.sessions[session];
-    if (entry === undefined) return;
-    delete book.sessions[session];
-    book.retired = [...(Array.isArray(book.retired) ? book.retired : []), { name: session, ...entry, retired: at }];
-  });
+    closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, commandLine('retire', bots, bot, session));
+    dropSession(bots, bot, session);
+
+    const at = new Date().toISOString();
+    await updateBook(home, (book) => {
+      const entry = book.sessions[session];
+      if (entry === undefined) return;
+      delete book.sessions[session];
+      book.retired = [...(Array.isArray(book.retired) ? book.retired : []), { name: session, ...entry, retired: at }];
+    });
+  } catch (error) {
+    // What already went stays gone, and is named: a retire run again finds
+    // nothing of it left to name (#464).
+    if (retiredWith.length > 0) error.message = `${error.message} ${goneBefore(session, retiredWith)}`;
+    throw error;
+  }
   const left = removePrompts([promptPath(bots, bot, session)]);
 
-  return { bot, session, closed, ...left };
+  return { bot, session, closed, retiredWith, ...left };
+}
+
+/**
+ * The sessions retired along with `session` before its own retire failed, in
+ * words, with any prompt file of theirs left and how to remove it.
+ */
+function goneBefore(session, retiredWith) {
+  const names = retiredWith.map((gone) => `${gone.bot}/${gone.session}, a temporary session of ${gone.maker}'s`);
+  const left = retiredWith.flatMap((gone) => gone.promptsLeft ?? [])
+    .map(({ file, reason }) => ` ${file} could not be removed (${reason}), and nothing reads it. Remove it with  rm ${shellWord(file)}`);
+  return `Retired along with ${session} before that, and still retired: ${names.join('; ')}.${left.join('')}`;
 }
 
 /**

package/src/sent.js

@@ -0,0 +1,111 @@
+// `obk session sent`: what the kit's PostToolUse hook says after a session's
+// native message (#451, ADR 0032).
+//
+// Claude Code's own messaging reaches every Claude session on the machine, not
+// only the sessions of one bots folder. After a send to another session, this
+// looks at where it went: to a session address none of the fleet's books name,
+// the session is told so, with the road the kit would have given it. The send
+// has gone either way. Nothing here decides anything about it, and anything it
+// cannot read is silence (ADR 0022: a hook never disturbs the session).
+//
+// It reads the send from its fields, never from its wording. Seen on Claude
+// Code 2.1.283: a send to an in-process teammate answers with a `routing`
+// object, and one to another session without it; the input's `to` names the
+// target, as a session's name with an optional ` [xxxxxx]` reference, or as a
+// `uds:` socket path when answering a message, which no book can map.
+
+import { readBook } from './book.js';
+import { botDir, botNames } from './bot.js';
+import { isAddressOf, ownCli, shellWord } from './launch.js';
+import { lookUp } from './message.js';
+import { TAB_ENV } from './record.js';
+
+/**
+ * The warning for a send the hook was told about, or undefined when there is
+ * nothing to say. `said` is what Claude Code handed the hook.
+ */
+export function sentWarning(bots, said) {
+  if (said?.tool_name !== 'SendMessage') return undefined;
+  const to = said.tool_input?.to;
+  if (typeof to !== 'string') return undefined;
+  const result = resultOf(said);
+  // A teammate in the same session, or a send that did not go: not this.
+  if (result === undefined || result.success !== true || 'routing' in result) return undefined;
+  if (/^(uds|bridge):/.test(to)) return undefined;
+
+  const name = to.replace(/\s*\[[^\]]*\]\s*$/, '').trim();
+  if (name === '') return undefined;
+  const fleet = addressesIn(bots);
+  if (fleet === undefined || fleet.all.has(name)) return undefined;
+
+  const meant = fleet.byName.get(name.split('.').slice(0, 2).join('.'));
+  const ask = (to) => `\`${shellWord(ownCli())} message to --bots ${shellWord(bots)} --to ${to}\``;
+  const road = meant === undefined
+    ? `${ask('<bot>/<session>')} gives the road to a session of this fleet.`
+    : roadTo(bots, meant, ask(`${meant.bot}/${meant.session}`));
+  return `That message went to ${name}, which is not one of the sessions of your bots folder, ${bots}: Claude Code's messaging reaches every session on this machine. ${road} Check before you send to it again.`;
+}
+
+/**
+ * The road to the session the sender probably meant, as `obk message to` would
+ * answer it from the sender's own tab: native to its address only between
+ * sessions of one approval class, the kit's mailbox otherwise (PRD 6.9). Where
+ * the sender cannot be told by its tab, the session's address and the question
+ * to ask, without claiming the address is the answer (#451 review).
+ */
+function roadTo(bots, meant, ask) {
+  let found;
+  try {
+    found = lookUp(bots, { to: `${meant.bot}/${meant.session}`, tab: process.env[TAB_ENV] });
+  } catch {
+    found = undefined;
+  }
+  const who = `${meant.bot}/${meant.session}`;
+  if (found?.transport === 'native' && typeof found.address === 'string') {
+    return `If you meant ${who}, ${ask} gives the road from your session: write to ${found.address} with your own messaging.`;
+  }
+  if (found?.transport === 'orca' && typeof found.address === 'string') {
+    return `If you meant ${who}, ${ask} gives the road from your session: its mailbox, ${found.address}, by \`${shellWord(ownCli())} message send\`, not your own messaging.`;
+  }
+  return `If you meant ${who}, its session address is ${meant.address}; ${ask} says which road to take from your session.`;
+}
+
+/** What the send answered, as an object: Claude Code hands it over as one, or as its JSON. */
+function resultOf(said) {
+  const raw = said.tool_output ?? said.tool_response;
+  if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) return raw;
+  if (typeof raw !== 'string') return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Every session address the fleet's books name, retired sessions' included, and
+ * each live one by `<bot>.<session>`: `{ all, byName }`. Undefined when a book
+ * cannot be read, since an address missing from it would be warned about wrongly.
+ */
+function addressesIn(bots) {
+  const all = new Set();
+  const byName = new Map();
+  try {
+    for (const bot of botNames(bots)) {
+      const book = readBook(botDir(bots, bot));
+      for (const [session, entry] of Object.entries(book.sessions ?? {})) {
+        const address = entry?.address;
+        if (typeof address !== 'string') continue;
+        all.add(address);
+        if (isAddressOf(bot, session, address)) byName.set(`${bot}.${session}`, { bot, session, address });
+      }
+      for (const entry of Array.isArray(book.retired) ? book.retired : []) {
+        if (typeof entry?.address === 'string') all.add(entry.address);
+      }
+    }
+  } catch {
+    return undefined;
+  }
+  return { all, byName };
+}

package/src/temp.js

@@ -4,7 +4,8 @@
 //
 // Any long-lived session can make a temporary session of its own bot for a
 // piece of work, and retire it when the work is done, without Bot Father, who
-// stays the manager of long-lived sessions. A temporary session is an ordinary
+// stays the manager of long-lived sessions. A temporary session can make one
+// of its own, one level deep and one at a time (#464, ADR 0033). A temporary session is an ordinary
 // session in every other way: in bot.yaml, brought up with a tab and a mailbox,
 // its conversations kept in the book. What makes it temporary is one field of
 // its book entry, `temporary: { maker, made }`, and the book is the one place
@@ -44,9 +45,9 @@ const INHERITED = ['model', 'effort', 'context', 'approval'];
  */
 export async function makeTemp(bots, { tab, ...given }) {
   const caller = callerIn(bots, tab, 'make');
-  if (caller.temporary !== undefined) {
-    throw new Error(`${caller.bot}/${caller.session} is a temporary session, and only a long-lived session makes one. Nothing was made.`);
-  }
+  // Checked here, before anything is written, and again under the book's lock
+  // below, where two makes at once cannot both pass it.
+  refuseNested(bots, caller, readBook(caller.home));
   // The name is a folder under work/ and a file beside the bots folder, so it
   // is held to the rule a bot's name is: one plain name, never a path.
   if (!NAME.test(given.name)) {
@@ -77,38 +78,44 @@ export async function makeTemp(bots, { tab, ...given }) {
   settings.work_dir = `work/${given.name}`;
 
   const written = bot.sessions.some((session) => session.name === given.name) ? undefined : writePromptFirst(bots, caller, settings);
-  // Refuses a name the bot already has, and a setting that will not work,
-  // before it writes anything; the prompt written first goes with a refusal.
-  let added;
-  try {
-    added = addSession(bots, caller.bot, settings);
-  } catch (error) {
-    if (written !== undefined) rmSync(written, { force: true });
-    throw error;
-  }
+  // bot.yaml and the book are written under the book's lock, so that a second
+  // make from the same maker waits, and then sees this one (#464). addSession
+  // refuses a name the bot already has, and a setting that will not work,
+  // before it writes anything.
   const made = new Date().toISOString();
+  let locked = false;
+  let added;
   try {
     await updateBook(caller.home, (book) => {
+      locked = true;
+      refuseNested(bots, caller, book);
+      added = addSession(bots, caller.bot, settings);
       book.sessions[given.name] = { ...book.sessions[given.name], temporary: { maker: caller.session, made } };
     });
   } catch (error) {
+    // A refusal under the lock has written nothing but the prompt file.
+    const refused = locked && added === undefined;
+    const failed = `${caller.bot}/${given.name} could not be recorded in the book as temporary (${error.message})`;
     // A session in bot.yaml that the book does not call temporary would be a
     // long-lived one to everything that reads it, its maker's retire included,
     // so it is taken back off rather than left that way.
-    const failed = `${caller.bot}/${given.name} could not be recorded in the book as temporary (${error.message})`;
-    try {
-      dropSession(bots, caller.bot, given.name);
-    } catch (undo) {
-      throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}`);
+    if (added !== undefined) {
+      try {
+        dropSession(bots, caller.bot, given.name);
+      } catch (undo) {
+        throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}`);
+      }
     }
     // Off bot.yaml, nothing is made; a prompt file that stays is only a file,
     // and nothing reads it (#393).
+    const why = refused ? error.message.replace(/ ?Nothing was made\.$/, '') : `${failed}${added === undefined ? '.' : ', so it was taken back off bot.yaml.'}`;
     try {
       if (written !== undefined) rmSync(written, { force: true });
     } catch (left) {
-      throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
+      throw new Error(`${why} Nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
     }
-    throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Run this again once the book can be written.`);
+    if (refused) throw error;
+    throw new Error(`${why} Nothing was made. Run this again once the book can be written.`);
   }
 
   let up;
@@ -121,6 +128,23 @@ export async function makeTemp(bots, { tab, ...given }) {
   return { bot: caller.bot, session: given.name, maker: caller.session, settings: added.session, up };
 }
 
+/**
+ * Refuse a make by a temporary session that may not make one now, against
+ * `book`: one made by a temporary session makes none, and a temporary session
+ * has one of its own open at a time (#464, ADR 0033).
+ */
+function refuseNested(bots, caller, book) {
+  if (caller.temporary === undefined) return;
+  const maker = caller.temporary.maker;
+  if (book.sessions[maker]?.temporary !== undefined) {
+    throw new Error(`${caller.bot}/${caller.session} is a temporary session ${maker} made, and ${maker} is temporary itself, so it makes none of its own: temporary sessions go one level deep. Nothing was made.`);
+  }
+  const open = Object.keys(book.sessions).filter((name) => book.sessions[name]?.temporary?.maker === caller.session);
+  if (open.length > 0) {
+    throw new Error(`${caller.bot}/${caller.session} is a temporary session, and it already has ${open.join(', ')} open; a temporary session has one of its own at a time. Retire it first with  ${shellWord(ownCli())} temp retire --bots ${shellWord(bots)} --name ${open[0]}  Nothing was made.`);
+  }
+}
+
 /**
  * Write the start prompt's file where bringing the session up will write it,
  * when its prompt goes to the harness out of a file at all, and say where. A