@assuredloop/orca-bot-kit 0.5.0 → 0.6.0

package/README.md

@@ -350,6 +350,11 @@ conversation it was having, rather than starting a new one. Clear a session —
 keeps the old one, and gives the session its start prompt again, because that
 prompt is what tells one session's duty from another's.
 
+A session paused before its first turn can have an id in the book and no
+conversation behind it: the harness has nothing on record for that id. There is
+nothing to resume, so it starts again with its duty, and the book moves the id
+into its history as `no conversation`.
+
 One tab holds one session: the harness the kit started in it. Anything that
 session runs inside the tab — a `codex exec`, a helper, a subagent's own process
 — is not the session, and never becomes the conversation the kit brings back.
@@ -386,7 +391,10 @@ What it will not do, in order of how much it would cost you. It closes only a
 tab your book names, so Bot Father's ops tab and anything you opened yourself
 are left alone. It will not close a tab whose conversation the book cannot name:
 that close would be the end of that conversation, so it refuses, tells you which
-session and which file to settle it in, and touches nothing. It will not close
+session and which file to settle it in, and touches nothing. The one exception
+is a tab with only its shell in front: its harness has already quit, so there
+is nothing in it to lose, and restart closes it and starts the session fresh
+with its duty. It will not close
 anything at all until everything that would stop the session starting again has
 been settled — the same refusals `obk up` gives, made before the tab goes rather
 than after. If Orca refuses to close a tab it stops there, rather than start a
@@ -410,9 +418,11 @@ obk retire --bots /path/to/my-bots --bot api-bot [--session daily]
 A change to a charter or a setting is written at once, and a running session
 takes it when it next starts. A session keeps its harness: to move one, retire
 it and add another. A pause closes the tabs the way a restart does, with the
-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
+same refusals, and one more: it also refuses a tab with only its shell in front
+whose conversation the book does not name. `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. The
 folder moves only once Orca no longer lists the project; if Orca still lists it,
@@ -433,11 +443,12 @@ link, not a tab — so everything it finds is yours to decide about.
 
 What it looks for:
 
-- **configuration that will not work**: a `bot.yaml` nothing can read, a session
-  the kit would refuse to start, a bot with no `AGENTS.md`, a block somebody
-  edited by hand, a file bigger than the 32 KiB Codex reads, a `CLAUDE.md` that
-  is not this bot's rules, and a hooks file without the kit's own hook in it,
-  which is how a book goes stale without anything saying so;
+- **configuration that will not work**: a `bot.yaml` nothing can read, a key
+  in it the kit does not know (a typo such as `efort: high`, which nothing
+  reads), a session the kit would refuse to start, a bot with no `AGENTS.md`,
+  a block somebody edited by hand, a file bigger than the 32 KiB Codex reads, a
+  `CLAUDE.md` that is not this bot's rules, and a hooks file without the kit's
+  own hook in it, which is how a book goes stale without anything saying so;
 - **a skill that is not where its list says**: a listed skill missing from one
   of the two harnesses, a skill of your own standing where a listed one would
   go, and a link with nothing at the end of it;
@@ -484,16 +495,28 @@ obk message check --bots /path/to/my-bots --bot api-bot --session daily
 Two roads, and a bot never picks. Claude Code to Claude Code in the same
 approval class (`auto` and `ask` are one class, `dangerously-skip` the other)
 is the harness's own messaging: `message to` answers with the
-session's name — `<bot>.<session>`, which `obk up` puts on its launch line —
-and the sending session writes to that name itself, because no command can send
-that message for it. Everything else goes through Orca's mailbox, which the kit
-does carry.
-
-A session's mailbox is made the first time `obk up` brings it up, and written in
+session's name, `<bot>.<session>.<token>`, which `obk up` puts on its launch
+line, and the sending session writes to that name itself, because no command
+can send that message for it. The token is new for each new conversation and
+kept when one is resumed, because Claude Code refuses a name that other fleets'
+sessions also answer to. Ask `message to` each time rather than keeping the
+name. Everything else goes through Orca's mailbox, which the kit does carry.
+
+That includes a Claude session still running under a name from before the
+token, `<bot>.<session>`: `message to` answers the mailbox road for it, never
+that name, until the session next starts a new conversation.
+
+A session's mailbox is made the first time the kit starts it, and written in
 the book beside its tab. It is an Orca Run rather than the session's tab,
 because a tab's address dies with the tab and a Run does not — so a message sent
 while a session is down is still there when it comes back.
 
+Orca lets a tab bind a mailbox to itself and to no other, so the mailbox is made
+and bound from inside the session's own tab: the launch line the kit types there
+runs `obk session mailbox` before the harness. For the same reason a session's
+mail is read in its own tab. `message check` from any other tab reads nothing,
+binds nothing, and says so; the mail waits.
+
 Nothing in a mailbox wakes anybody, so `message send` also types one line into
 the receiver's tab telling it to look. Both harnesses take a typed line as the
 next thing to do rather than cutting into what they are doing, which is the

package/package.json

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

package/src/book.js

@@ -269,3 +269,13 @@ export function rememberSession(entry = {}, id, ended) {
   const was = { session: entry.session, ended: ended ?? 'replaced', at: new Date().toISOString() };
   return { ...entry, session: id, history: [...(entry.history ?? []), was] };
 }
+
+/**
+ * The session entry once the id it held has turned out to have no conversation
+ * behind it: the id goes into the history with that reason, and the entry holds
+ * none until the harness names the new one.
+ */
+export function forgetSession(entry, ended) {
+  const { session, ...rest } = entry;
+  return { ...rest, history: [...(entry.history ?? []), { session, ended, at: new Date().toISOString() }] };
+}

package/src/bot.js

@@ -413,6 +413,31 @@ export const SESSION_FIELDS = [
   'name', 'harness', 'model', 'effort', 'context', 'approval', 'prompt', 'prompt_file', 'work_dir', 'extra_args',
 ];
 
+/** Everything the top of a bot's own file can hold. */
+const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'sessions', 'paused'];
+
+/**
+ * The keys in a bot's file that the kit does not know, and so that nothing
+ * reads: a typo such as `efort` leaves its session on the harness's default
+ * while the file says otherwise (#273). Said, and never refused or taken out,
+ * because the file is the user's.
+ */
+export function unknownKeys(home, name = path.basename(home)) {
+  const file = path.join(home, BOT_YAML);
+  const unknown = (entry, known) => Object.keys(entry).filter((key) => !known.includes(key));
+  const sessionKeys = [...SESSION_FIELDS, 'paused'];
+  return [
+    ...unknown(asMapping(parseYaml(file), file), BOT_FIELDS).map((key) => ({
+      where: file,
+      says: `${file} has a key the kit does not know, ${key}, so nothing reads it and ${name} runs as if it were not there. The keys a bot's file can have are ${BOT_FIELDS.join(', ')}.`,
+    })),
+    ...readBot(home, name).sessions.flatMap((session) => unknown(session, sessionKeys).map((key) => ({
+      where: file,
+      says: `${file}: ${name}'s session ${session.name} has a setting the kit does not know, ${key}, so nothing reads it and the session runs as if it were not there. The settings a session can have are ${sessionKeys.join(', ')}.`,
+    }))),
+  ];
+}
+
 /** A session's settings, in that order, without the ones left out. */
 function ordered(session) {
   const entry = {};

package/src/cli.js

@@ -17,7 +17,7 @@ import { grooming } from './groom.js';
 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 { checkMail, lookUp, noMailboxYet, sendMessage } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
@@ -28,7 +28,7 @@ import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
 import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
 import { addSource, fetchSources } from './sources.js';
 import { readUsage } from './usage.js';
-import { BOT_FATHER, bringUp } from './up.js';
+import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 
 const USAGE = `obk — Orca Bot Kit.
 
@@ -186,6 +186,10 @@ 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 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
+                            mailbox, or binds the one it has, to that tab.
   obk --version             Print the kit's version.
   obk --help                Print this text.
 
@@ -221,6 +225,7 @@ const COMMANDS = {
   'message send': ['bots', 'to', 'subject'],
   'message check': ['bots'],
   'session record': ['bots', 'bot'],
+  'session mailbox': ['bots', 'bot', 'session'],
 };
 
 /** What each flag is for, in the sentence a caller reads when it is missing. */
@@ -796,6 +801,17 @@ const commands = {
     };
   },
 
+  async 'session mailbox'(bots, values) {
+    const answer = await ownMailbox(bots, values.bot, values.session);
+    const who = `${answer.bot}/${answer.session}`;
+    const said = {
+      made: `${who} has its mailbox ${answer.mailbox}, made in this tab.`,
+      bound: `${who}'s mailbox ${answer.mailbox} is bound to this tab.`,
+      none: `${who} gets no mailbox: it is a Codex session with its sandbox switch off, which could not read one.`,
+    };
+    return { answer, lines: [said[answer.change]] };
+  },
+
   'session change'(bots, values) {
     if (values.harness !== undefined) {
       throw new Error(`session change does not change a session's harness: its conversations belong to the harness they ran on. To move it, retire it with obk retire and add one on ${values.harness} with obk session add.`);
@@ -892,9 +908,14 @@ function refuseWhenOrcaIsDown() {
 
 /** The same facts as `--json`, as lines, for a person reading along. */
 /** The one line that says which conversation this tab was given, and from where. */
-const howLine = (tab) => (tab.resumed === true
-  ? '             it was told to resume the session the book holds, with its conversation.'
-  : '             it was told to start a new session: the book holds none for this one yet.');
+const howLines = (tab) => {
+  if (tab.resumed === true) return ['             it was told to resume the session the book holds, with its conversation.'];
+  if (tab.noConversation === undefined) return ['             it was told to start a new session: the book holds none for this one yet.'];
+  return [
+    `             it was told to start a new session: the book's conversation ${tab.noConversation} had nothing on record`,
+    "             behind it, so it went into the session's history.",
+  ];
+};
 
 /**
  * What the harness still has in this bot's folder that no session claims. The
@@ -1175,6 +1196,9 @@ function tabLines({ bots, created, completed, rules, skills, tabs, paused = [],
   for (const tab of tabs) {
     lines.push(`${tab.created ? 'opened' : 'found '}     ${tab.title}  tab ${tab.tabId}  terminal ${tab.terminal}`);
     lines.push(...harnessLines(tab, bots));
+    if (tab.noMailbox) {
+      lines.push(`             it has no mailbox: ${noMailboxYet({ bots, bot: tab.bot, session: tab.name })}`);
+    }
   }
   for (const one of paused) {
     const what = one.session === undefined ? one.bot : `${one.bot} ${one.session}`;
@@ -1205,7 +1229,7 @@ function harnessLines(tab, bots) {
   // What the line that was typed in asked for, and where the kit got it: the
   // session the book holds, one the harness itself still had on record, or a new
   // one — and if a new one, whether anything was known about an older one.
-  const how = [howLine(tab)];
+  const how = howLines(tab);
 
   if (!tab.harnessStarted) {
     return [

package/src/conversations.js

@@ -10,7 +10,7 @@
 // directory, and every session starts at its bot home. Read only, never
 // written: these are the harness's files (tech notes, sections 2 and 3).
 
-import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 
@@ -39,6 +39,20 @@ export function conversationsIn(harness, home, since) {
     .map((one) => ({ id: one.id, at: one.at }));
 }
 
+/**
+ * Whether the harness has a record of the conversation `id` for this bot home,
+ * which is what its own resume looks for. A session paused before its first
+ * turn has an id the hook reported and nothing written behind it, and Claude
+ * Code answers a resume of it with "No conversation found" (#295).
+ *
+ * Asked of the file names alone, which both harnesses make from the id: nothing
+ * is opened, however many conversations the machine has.
+ */
+export function hasConversation(harness, home, id) {
+  if (harness === 'claude') return existsSync(path.join(claudeDir(home), `${id}.jsonl`));
+  return rollouts(codexDir()).some((file) => path.basename(file).endsWith(`-${id}.jsonl`));
+}
+
 /**
  * The same conversations, each with the file the harness keeps it in, for a
  * caller that has to read what is inside one rather than only know it is there,

package/src/health.js

@@ -22,7 +22,7 @@ import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
 import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
-import { botDir, botNames, botsDir, readBot } from './bot.js';
+import { botDir, botNames, botsDir, readBot, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
 import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, shellWord } from './launch.js';
@@ -186,6 +186,7 @@ function aboutBot(bots, name, setups, sessions) {
 
   const said = (kind) => ({ where, says }) => finding(kind, where, says, name);
   return [
+    ...unknownKeys(home, name).map(said('config')),
     ...sessionSettings(home, bot).map(said('config')),
     ...agentsTrouble(bots, home, bot).map(said('config')),
     ...hooksOf(bots, home, bot).map(said('config')),
@@ -256,15 +257,7 @@ function runningOn(bots, home, bot, book, handles, sessions) {
     const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
     const front = frontOfTab(handle);
     if (front.front === 'shell') {
-      // Restart refuses a live tab whose conversation the book cannot name, and
-      // there may be none to name: the harness can quit before it has one. Its
-      // harness is gone, so closing the tab ends nothing, and `up` then starts
-      // the session again as it does any closed tab with no conversation.
-      const up = `${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
-      const back = typeof entry.session === 'string'
-        ? `${restart} does`
-        : `nor does obk restart, which refuses to close a tab whose conversation the book does not name, and the book names none for it. Its harness has already quit, so close the tab in Orca yourself; then ${up} starts it again, with a new conversation and its duty. Any conversation it left in this bot's folder is noted in the book as unclaimed, for health to list`;
-      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} is not running: its tab ${entry.tab} is open with only the tab's shell in front, so its harness quit or crashed. obk up finds the tab open and types nothing into it, so it does not bring the session back; ${back}.`, bot.name));
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} is not running: its tab ${entry.tab} is open with only the tab's shell in front, so its harness quit or crashed. obk up finds the tab open and types nothing into it, so it does not bring the session back; ${restart} does.`, bot.name));
       continue;
     }
     const harness = harnessOf(session, bot.harness);

package/src/launch.js

@@ -10,6 +10,7 @@
 // The text goes into the tab's ordinary shell, so every word is quoted the way
 // a shell needs it. `claude --model sonnet[1m]` would be a glob to zsh.
 
+import { randomInt } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -53,8 +54,22 @@ export const harnessOf = (session, botHarness) => (set(session.harness) ? sessio
  * session writes to (ADR 0018). It goes on the launch line as `-n`, and it is
  * re-applied every time the session is started: a resume keeps the name by
  * itself (tech notes, section 2), and the kit does not depend on that.
+ *
+ * `<bot>.<session>` alone is not an address: every fleet with that bot and
+ * session answers to it, old runs and throwaway test fleets included, and
+ * Claude Code refuses a send to a name more than one session holds (#286). So
+ * the name ends in a token of its own, made for each new conversation: eight
+ * letters and digits, 36^8 names, so that no two conversations draw the same
+ * one by chance.
  */
-export const addressOf = (bot, session) => `${bot}.${session}`;
+export const addressOf = (bot, session) =>
+  `${bot}.${session}.${Array.from({ length: 8 }, () => randomInt(36).toString(36)).join('')}`;
+
+/** Whether `address` is one `addressOf` made for this bot and session. */
+export function isAddressOf(bot, session, address) {
+  const own = `${bot}.${session}.`;
+  return typeof address === 'string' && address.startsWith(own) && /^[a-z0-9]{8}$/.test(address.slice(own.length));
+}
 
 /**
  * The Codex setting without which a bot cannot reach Orca at all.
@@ -277,6 +292,17 @@ const quoted = (word) => (/^[A-Za-z0-9,._+:@%/=-]+$/.test(word) ? word : `'${wor
 /** The same, for anything else of the kit's that has to build a shell line. */
 export const shellWord = quoted;
 
+/**
+ * What a launch line starts with for a session that can have a mailbox: the
+ * kit itself, run by the new tab's shell before the harness, giving the session
+ * its mailbox bound to that tab. Orca 1.4.210 lets a process in a tab bind a
+ * Run to that tab and to no other, so the `obk` that opened the tab cannot do
+ * it (#317). The line joins it with `;`, so the harness starts whatever became
+ * of it.
+ */
+export const mailboxStep = (bots, bot, session) =>
+  [ownCli(), 'session', 'mailbox', '--bots', bots, '--bot', bot, '--session', session].map(quoted).join(' ');
+
 /**
  * The CLI that is running, by the path it was started by: the kit calls itself
  * back with this, never with the bare name `obk`, because the bare name is

package/src/message.js

@@ -20,8 +20,8 @@ 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, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, typeIntoTab, useMailbox } from './orca.js';
+import { harnessOf, isAddressOf, ownCli, reachesMail, shellWord } from './launch.js';
+import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, typeIntoTab, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -67,7 +67,10 @@ export function findSession(bots, target) {
     session: session.name,
     harness,
     approval: classOf(session),
-    address: typeof held.address === 'string' ? held.address : undefined,
+    // Only a name the kit gave this session is an address. A bare
+    // `<bot>.<session>`, from before #286, is shared with other fleets'
+    // sessions, and Claude Code refuses a send to it.
+    address: isAddressOf(bot.name, session.name, held.address) ? held.address : undefined,
     mailbox: typeof held.mailbox === 'string' ? held.mailbox : undefined,
     tab: typeof held.tab === 'string' ? held.tab : undefined,
     trouble: whyNotReachable(bot.name, session, harness, held),
@@ -91,7 +94,8 @@ export function roadBetween(from, to) {
     address: to.mailbox === undefined ? undefined : `run:${to.mailbox}`,
     // A Claude pair that the native road cannot carry, because the receiver is
     // running under no name the kit gave it: it was started before the kit
-    // named sessions, and nothing renames a live harness. The mailbox is the
+    // named sessions, or before it gave them names of their own (#286), and
+    // nothing renames a live harness. The mailbox is the
     // road that exists, and the caller is told why it is the one being used
     // rather than left to wonder (review of PR #132, finding 1).
     unnamed: pair ? true : undefined,
@@ -147,7 +151,9 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
     return {
       ...answer,
       sent: false,
-      trouble: `${from.bot}/${from.session} has no mailbox of its own yet, so a reply would have nowhere to go. Bring it up first:  ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${shellWord(from.bot)}`,
+      trouble: from.tab === undefined
+        ? `${from.bot}/${from.session} has no mailbox of its own yet, so a reply would have nowhere to go. Bring it up first:  ${upCommand(from)}`
+        : `${from.bot}/${from.session} has no mailbox of its own, so a reply would have nowhere to go: ${noMailboxYet(from)}`,
     };
   }
 
@@ -176,8 +182,8 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
  * 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.
+ * is not a peek acknowledges every batch waiting, one after another, so one
+ * check hands over all of it (issue #299).
  */
 export function checkMail(bots, { bot: botName, session: sessionName, tab, peek = false }) {
   const who = sessionName === undefined && botName === undefined
@@ -200,6 +206,20 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
   // 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;
+  // Orca 1.4.210 lets a process in a tab bind and read as that tab and no
+  // other, and refuses the rest with nothing done (#317). So from inside any
+  // other tab, the kit asks nothing and says where the mail can be read.
+  const caller = process.env[TERMINAL_ENV];
+  if (caller !== undefined && caller !== live) {
+    return {
+      bots,
+      bot: who.bot,
+      session: who.session,
+      mailbox: who.mailbox,
+      messages: [],
+      trouble: `${who.bot}/${who.session}'s mail can be read only in its own tab: Orca lets a tab bind and read its own mailbox and no other. Nothing was read, and its mail is still waiting.`,
+    };
+  }
   if (live !== undefined) useMailbox(who.mailbox, live);
   const handle = live ?? coordinatorOf(who.mailbox);
   if (handle === undefined) {
@@ -212,9 +232,16 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
       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);
+  // Orca hands mail over a batch at a time and replays the oldest until it is
+  // acknowledged; the acknowledgement answers with the next batch. So a read
+  // takes every batch in turn, or newer mail waits behind an older one (#299).
+  const messages = [];
+  let found = readMailbox(who.mailbox, { peek, handle });
+  for (;;) {
+    messages.push(...(found.messages ?? []).map((message) => asMessage(bots, message)));
+    if (peek || !found.deliveryId || (found.messages ?? []).length === 0) break;
+    found = ackMailbox(who.mailbox, found.deliveryId, handle);
+  }
 
   return { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
 }
@@ -335,7 +362,7 @@ function nudge(to, from, subject) {
   if (to.tab === undefined) return { nudged: false };
 
   try {
-    const found = tabToTypeInto(to.home, to.tab, LOOK_MS);
+    const found = lookAt(to);
     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 };
@@ -356,6 +383,21 @@ function nudge(to, from, subject) {
   }
 }
 
+/**
+ * The look before the nudge. Orca now and then refuses a handle it has just
+ * listed as stale, and a fresh listing hands out one that works (tech notes,
+ * section 1), so that refusal earns one more listing and one more look. Only
+ * one: a second refusal is reported as it is (#294).
+ */
+function lookAt(to) {
+  try {
+    return tabToTypeInto(to.home, to.tab, LOOK_MS);
+  } catch (error) {
+    if (error.code !== 'terminal_handle_stale') throw error;
+    return tabToTypeInto(to.home, to.tab, LOOK_MS);
+  }
+}
+
 /** `<bot>/<session>`, or a bot on its own when it has only the one session. */
 function splitTarget(target) {
   const parts = target.split('/');
@@ -395,5 +437,22 @@ function whyNotReachable(bot, session, harness, held) {
   return `${bot}/${session.name} is a Codex session whose extra arguments turn sandbox_workspace_write.network_access off. Orca is out of reach from inside that sandbox, so it can neither be written to nor read its own mail. Take that argument out, or write to it another way.`;
 }
 
-const notUpYet = (who) =>
-  `${who.bot}/${who.session} has no mailbox yet: it has never been brought up. Start it and it gets one:  ${shellWord(ownCli())} up --bots ${shellWord(who.bots)} --bot ${shellWord(who.bot)} --session ${shellWord(who.session)}`;
+const notUpYet = (who) => (who.tab === undefined
+  ? `${who.bot}/${who.session} has no mailbox yet: it has never been brought up. Start it and it gets one:  ${upCommand(who)} --session ${shellWord(who.session)}`
+  : `${who.bot}/${who.session} has no mailbox: ${noMailboxYet(who)}`);
+
+/**
+ * Why a session the kit has started has no mailbox, and what gets it one. Its
+ * mailbox is made by the step at the head of its launch line, in its own tab
+ * (#317), so `up` of a session that is running gives it none: starting it
+ * again does, and `up` does when its tab is closed.
+ */
+export const noMailboxYet = (who) =>
+  `its tab did not make one when it started, and the tab shows why. Start it again and its tab makes one:  ${restartCommand(who)}  (or, if its tab is closed:  ${upCommand(who)} --session ${shellWord(who.session)})`;
+
+/** The command that starts one session again, in a new tab. */
+const restartCommand = (who) =>
+  `${shellWord(ownCli())} restart --bots ${shellWord(who.bots)} --bot ${shellWord(who.bot)} --session ${shellWord(who.session)}`;
+
+/** The command that brings a bot's sessions up, for the caller to finish with a session or not. */
+const upCommand = (who) => `${shellWord(ownCli())} up --bots ${shellWord(who.bots)} --bot ${shellWord(who.bot)}`;

package/src/orca.js

@@ -24,20 +24,34 @@ export const orcaCli = () => process.env.OBK_ORCA || BUILT_IN;
 /**
  * Run one Orca command and give back its `result`.
  * Every call asks for `--json`; anything else would be text to guess at.
+ * With `timeoutMs`, Orca is given that long to answer, and the call is ended
+ * and refused if it has not.
  */
-export function orca(args) {
-  const answer = ask(args);
+export function orca(args, { timeoutMs } = {}) {
+  const answer = ask(args, timeoutMs);
   if (answer.ok !== true) {
     // Orca's own words: it knows what went wrong, and the caller is an LLM
     // that can act on them.
-    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+    throw refusal(args, answer);
   }
   return answer.result;
 }
 
+/** What an error carries when Orca was given a time and did not answer in it. */
+export const TIMED_OUT = 'orca_timed_out';
+
+/** Orca's refusal as an error, with its code on it, so a caller can tell a stale handle from the rest (#294). */
+const refusal = (args, answer) => Object.assign(
+  new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`),
+  { code: answer.error?.code },
+);
+
 /** One Orca command, and the whole envelope back, refusals included. */
-function ask(args) {
-  const asked = spawnSync(orcaCli(), [...args, '--json'], { encoding: 'utf8' });
+function ask(args, timeoutMs) {
+  const asked = spawnSync(orcaCli(), [...args, '--json'], { encoding: 'utf8', ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }) });
+  if (asked.error?.code === 'ETIMEDOUT') {
+    throw Object.assign(new Error(`Orca did not answer ${args.join(' ')} within ${timeoutMs / 1000} seconds.`), { code: TIMED_OUT });
+  }
   if (asked.error) {
     throw new Error(`could not run Orca at ${orcaCli()}: ${asked.error.message}`);
   }
@@ -257,7 +271,7 @@ export function harnessInTab(handle, timeoutMs) {
   // Out of time means nothing went idle, busy or absent alike. That is an
   // answer, not a breakdown.
   if (answer.ok !== true && answer.error?.code !== 'timeout') {
-    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+    throw refusal(args, answer);
   }
 
   const shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
@@ -412,37 +426,41 @@ export function typeIntoTab(handle, text) {
 /** How long a re-issued line is given to be submitted before Orca gives up on it. */
 const SUBMIT_WAIT_S = 5;
 
+/** Where Orca names the terminal a process runs in, in every pane it opens. */
+export const TERMINAL_ENV = 'ORCA_TERMINAL_HANDLE';
+
 /**
  * A mailbox of one session's own: an Orca Run, which is a name and an inbox and
  * nothing else — it schedules nothing and runs nobody. The objective is what a
  * person sees in `orca orchestration run-list`, so it says whose it is.
  *
- * Bound to `handle`, the session's own tab, from the moment it is made. Orca
- * tells a Run's coordinator terminal about its mail and nobody else, and binds
- * the caller when no `--from` is given: the tab that ran `obk up` would be told
- * about every session it brought up, and would lose its own Run's binding, since
- * one terminal holds one Run (tech notes, section 1).
+ * Bound to the terminal this process runs in, which has to be the session's own
+ * tab: Orca tells a Run's coordinator terminal about its mail and nobody else,
+ * and one terminal holds one Run. Orca 1.4.210 lets a process in a tab bind a
+ * Run to that tab and to no other, so this is called from inside the session's
+ * tab and names no `--from` (tech notes, section 1; #317).
  */
-export const makeMailbox = (objective, handle) =>
-  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`, '--from', handle]).run.id;
+export const makeMailbox = (objective, options) =>
+  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`], options).run.id;
 
 /**
  * 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.
+ * handle it binds this process's own terminal; on Orca 1.4.210 a process in a
+ * tab may name no other (#317).
  */
-export const useMailbox = (id, handle) =>
-  orca(['orchestration', 'run-use', '--id', id, ...(handle === undefined ? [] : ['--from', handle])]).run;
+export const useMailbox = (id, handle, options) =>
+  orca(['orchestration', 'run-use', '--id', id, ...(handle === undefined ? [] : ['--from', handle])], options).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;
+export const coordinatorOf = (id, options) =>
+  orca(['orchestration', 'run-show', '--id', id], options).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 }) {
@@ -461,7 +479,7 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
 export const readMailbox = (id, { peek = false, handle } = {}) =>
   orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])]);
 
-/** Say a batch has been read, so the next check brings the one after it. */
+/** Say a batch has been read. Orca answers with the batch after it. */
 export const ackMailbox = (id, delivery, handle) =>
   orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery]);
 

package/src/restart.js

@@ -15,7 +15,9 @@
 //      else open in a bot's project, belongs to the user (PRD 6.2).
 //   2. Never a tab whose conversation the kit could not name again. A live tab
 //      with no session id in the book is refused before anything is touched:
-//      the close would be the end of that conversation.
+//      the close would be the end of that conversation. Unless only its shell
+//      is in front: its harness has quit, so the close ends nothing, and `up`
+//      starts the session fresh as it does any closed tab with no id (#303).
 //   3. One tab at a time, by its own handle. Orca's `--worktree <sel> --all`
 //      ends every tab of a project and is never called from anywhere in the kit.
 //
@@ -32,7 +34,7 @@ import { setTimeout as pause } from 'node:timers/promises';
 import { bookFile, readBook } from './book.js';
 import { botDir, readBot } from './bot.js';
 import { ownCli, shellWord } from './launch.js';
-import { closeTab, findProject, tabs } from './orca.js';
+import { closeTab, findProject, frontOfTab, tabs } from './orca.js';
 import { botsNamed, bringUp, prepareBots, sessionsOf } from './up.js';
 
 /**
@@ -65,7 +67,7 @@ export async function restartSessions(bots, { bot: name, session: onlySession }
     throw new Error(`${name} would not come up again as it is, so nothing was closed. ${prepared.rules[0].trouble}`);
   }
 
-  const going = tabsToClose(bots, name, home, sessions.filter((session) => session.paused !== true));
+  const going = tabsToClose(bots, name, home, sessions.filter((session) => session.paused !== true), { quit: true });
   const closed = await closeTabs(home, going, bots, name);
   return { closed, ...(await bringUp(bots, { bot: name, session: onlySession })) };
 }
@@ -75,9 +77,11 @@ export async function restartSessions(bots, { bot: name, session: onlySession }
  * has been judged safe to close: a live tab whose conversation the book cannot
  * name refuses the lot, before anything is touched. With `keepless`, a tab is
  * closed whatever the book knows, for a caller that is ending the session on
- * purpose.
+ * purpose. With `quit`, a tab whose harness has quit to its shell is closed
+ * too, for a caller that starts the session again: there is nothing in it to
+ * lose. A program in front, or a front that cannot be read, still refuses.
  */
-export function tabsToClose(bots, name, home, sessions, { keepless = false } = {}) {
+export function tabsToClose(bots, name, home, sessions, { keepless = false, quit = false } = {}) {
   const book = readBook(home);
 
   // Orca is asked what the project holds only when it has one: a folder Orca
@@ -96,7 +100,7 @@ export function tabsToClose(bots, name, home, sessions, { keepless = false } = {
     // Nothing of this session's is open: there is nothing to close, and `up`
     // brings it back the way it brings back a tab the user closed themselves.
     if (tab === undefined) continue;
-    if (keepless || typeof was.session === 'string') going.push({ name: session.name, tab });
+    if (keepless || typeof was.session === 'string' || (quit && frontOfTab(tab.handle).front === 'shell')) going.push({ name: session.name, tab });
     else refusals.push(cannotComeBack(bots, name, session.name, was));
   }
 

package/src/up.js

@@ -8,12 +8,13 @@ import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
-import { forgetClaimed, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
+import { forgetClaimed, forgetSession, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, readBot } from './bot.js';
-import { conversationsIn, heldAsUserTurn, transcriptsIn } from './conversations.js';
+import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } 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, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { addressOf, harnessOf, isAddressOf, isShortPrompt, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
+import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { TAB_ENV } from './record.js';
 import { buildAgents, rulesStamp } from './rules.js';
 import { linkSkills } from './skills.js';
 
@@ -237,20 +238,21 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   const tabTitle = `${title} ${session.name}`;
 
   if (known) {
-    // A mailbox it can be written to, and no name. The name is the one thing
-    // the kit cannot give a session that is already running: `-n` goes on the
+    // No name, and no mailbox from here. The name is the one thing the kit
+    // cannot give a session that is already running: `-n` goes on the
     // launch line, this session was launched without one, and nothing renames a
     // 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, known.handle);
+    // time it starts, which is the next time the kit types its launch line. So
+    // does a mailbox, if its book has none: that is made from inside the tab
+    // the session starts in, and nothing is typed into this one (#317).
 
     // 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
     // is the session, and a title is only ever set. Nothing is typed into a tab
     // that is already there — the session is in the middle of its work.
     retitleTab(known.handle, tabTitle);
-    return entry({ ...known, title: tabTitle }, { bot: bot.name, name: session.name, created: false });
+    return entry({ ...known, title: tabTitle }, { bot: bot.name, name: session.name, created: false, noMailbox: lacksMailbox(home, session, harness) });
   }
 
   // Everything that can be refused is settled before Orca is asked for
@@ -263,33 +265,14 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // given again (PRD 6.4) — after a clear it is, and that is the hook's work.
   // Asked before the book is held, because it reads a folder of the harness's
   // own files: nothing slow happens under the lock.
-  const which = whichConversation(book, home, bot, session, was, harness);
-  const resume = which.resume;
-  const prompt = resume === undefined ? startPrompt(session, { home, workDir }) : undefined;
-  // Anything longer than a line goes to the harness out of a file, rather than
-  // through the tab's shell a character at a time.
-  const promptFile = prompt === undefined || isShortPrompt(prompt) ? undefined : promptPath(bots, bot.name, session.name);
-  const command = launchCommand(session, {
-    harness,
-    home,
-    workDir,
-    prompt,
-    promptFile,
-    resume,
-    address: harness === 'claude' ? addressOf(bot.name, session.name) : undefined,
-  });
+  let which = whichConversation(book, home, bot, session, was, harness);
+  const launchOf = (chosen) => launchFor(bots, bot, session, harness, home, workDir, chosen.resume, was?.address);
+  let launch = launchOf(which);
 
   // A work dir is a plain folder, made for the session before it is told about
   // it (PRD 6.4). Nothing here is a git worktree.
   if (workDir !== undefined) mkdirSync(workDir, { recursive: true });
-
-  // The prompt is written where the launch line can read it from, before that
-  // line is typed. It is the kit's own file, not the user's: theirs stays where
-  // they put it, in the bot home.
-  if (promptFile !== undefined) {
-    mkdirSync(path.dirname(promptFile), { recursive: true });
-    writeFileSync(promptFile, prompt);
-  }
+  writePrompt(launch);
 
   const made = openTab(home, tabTitle);
 
@@ -305,28 +288,48 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // built, noted so that health can say when the file moves on and the session
   // does not (#272).
   const rules = rulesStamp(home);
+  let held;
   await updateBook(home, (current) => {
     // What the harness has in this folder that nobody claims goes on the record,
     // for a person or Bot Father to settle — added to whatever was already noted,
     // because this run's scan cannot see what an earlier one found. The kit never
     // settles it itself.
-    const entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
+    let entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
     if (rules === undefined) delete entry.rules;
+    held = entry.session;
+    // Before the line is typed, so the hook finds no id here and takes the one
+    // it reports for a start rather than a clear, which would tell the duty twice.
+    if (which.noConversation !== undefined && held === which.noConversation) entry = forgetSession(entry, 'no conversation');
     current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
     forgetClaimed(current);
   });
 
+  // The old tab's hook can name another conversation while the tab is being
+  // opened. A fresh start chosen before that is chosen again from the id the
+  // book holds now: resumed if the harness has it, and otherwise set aside the
+  // same way (review of PR #310).
+  if (which.noConversation !== undefined && typeof held === 'string' && held !== which.noConversation) {
+    which = hasConversation(harness, home, held) ? { resume: held } : { noConversation: held };
+    if (which.noConversation !== undefined) {
+      await updateBook(home, (current) => {
+        const entry = current.sessions[session.name];
+        if (entry?.session === held) current.sessions[session.name] = forgetSession(entry, 'no conversation');
+      });
+    }
+    launch = launchOf(which);
+    writePrompt(launch);
+  }
+
   // Typing it in is the way: for a project the kit has just made, giving Orca
   // the harness as the tab's own command times out and leaves a dead tab.
-  typeIntoTab(made.handle, command);
+  typeIntoTab(made.handle, launch.command);
 
-  // Now the session has an address, and not before: the mailbox it can be
-  // written to, and — on Claude Code — the name that line just gave it, which
-  // is the name another Claude session writes to. Both are written after the
-  // 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, made.handle, { named: harness === 'claude', opened: true });
+  // Now the session has an address, and not before: on Claude Code, the name
+  // that line just gave it, which is the name another Claude session writes
+  // to. Its mailbox comes from the line's own first step, in the tab, and a
+  // mailbox Orca will not make there leaves a tab on the books all the same,
+  // which the next launch finishes (#317; review of PR #132, finding 3).
+  if (launch.address !== undefined) await writeAddress(home, session, launch.address);
 
   // 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
@@ -344,22 +347,69 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // duty: one held on a first-run screen, or one that refused the argument, has
   // been told nothing. So it is received only when the session's own record
   // holds it as a user turn, and otherwise not confirmed (#274).
-  const promptReceived = prompt === undefined
+  const promptReceived = launch.prompt === undefined
     ? undefined
-    : await heldInRecord(home, session.name, harness, prompt, { launched, running: tui.running === true });
+    : await heldInRecord(home, session.name, harness, launch.prompt, { launched, running: tui.running === true });
 
   return entry(made, {
     bot: bot.name,
     name: session.name,
     created: true,
+    // Asked once the tab is up: the step at the head of the line has run by
+    // then, and whatever it said is on the tab's screen, not in this report.
+    noMailbox: lacksMailbox(home, session, harness),
     ...tui,
     promptReceived,
-    promptFile,
-    resumed: resume !== undefined,
+    promptFile: launch.promptFile,
+    resumed: launch.resume !== undefined,
+    noConversation: which.noConversation,
     unclaimed: which.unclaimed,
   });
 }
 
+/**
+ * The line that starts this session: resuming `resume`, or, with none, a fresh
+ * start carrying its duty. Returns `{ resume, prompt, promptFile, command, address }`.
+ */
+function launchFor(bots, bot, session, harness, home, workDir, resume, held) {
+  const prompt = resume === undefined ? startPrompt(session, { home, workDir }) : undefined;
+  // Anything longer than a line goes to the harness out of a file, rather than
+  // through the tab's shell a character at a time.
+  const promptFile = prompt === undefined || isShortPrompt(prompt) ? undefined : promptPath(bots, bot.name, session.name);
+  // A new conversation is given a new name. A resume goes on under the one the
+  // kit gave it, and under no `-n` at all when the book `held` none of the
+  // kit's own: a resume keeps whatever name the conversation has, which is
+  // proven, and whether `-n` renames it is not (#286). Such a session is
+  // written to through its mailbox until it next starts fresh.
+  const address = harness !== 'claude' ? undefined
+    : resume === undefined ? addressOf(bot.name, session.name)
+    : isAddressOf(bot.name, session.name, held) ? held : undefined;
+  const line = launchCommand(session, {
+    harness,
+    home,
+    workDir,
+    prompt,
+    promptFile,
+    resume,
+    address,
+  });
+  // The session's mailbox first, from inside its own tab (#317), and the
+  // harness whatever became of it.
+  const command = reachesMail(session, harness) ? `${mailboxStep(bots, bot.name, session.name)}; ${line}` : line;
+  return { resume, prompt, promptFile, command, address };
+}
+
+/**
+ * The prompt is written where the launch line can read it from, before that
+ * line is typed. It is the kit's own file, not the user's: theirs stays where
+ * they put it, in the bot home.
+ */
+function writePrompt({ prompt, promptFile }) {
+  if (promptFile === undefined) return;
+  mkdirSync(path.dirname(promptFile), { recursive: true });
+  writeFileSync(promptFile, prompt);
+}
+
 /**
  * How long a running harness's own record is given to show the start prompt.
  * Seen live (Claude Code 2.1.282, a trusted folder): the hook's id and the
@@ -406,8 +456,8 @@ function lookFor(handle, timeoutMs) {
 }
 
 /**
- * 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.
+ * Write down the name a session answers to, where this run has just launched it
+ * under that name.
  *
  * The name is written by whoever typed the launch line that gave it, and by
  * nobody else. A session that was already running when the kit reached it was
@@ -415,56 +465,143 @@ function lookFor(handle, timeoutMs) {
  * that no harness answers to is worse than no name: the kit would send another
  * session to an address with nobody at it.
  *
+ * The session's mailbox is not made here. The launch line this run typed
+ * starts with `obk session mailbox`, which the new tab's shell runs before the
+ * harness: Orca 1.4.210 lets a process in a tab bind a Run to that tab and to
+ * no other, so the `obk` that opened the tab cannot (#317, `ownMailbox`).
+ */
+async function writeAddress(home, session, address) {
+  if (readBook(home).sessions[session.name]?.address === address) return;
+
+  await updateBook(home, (current) => {
+    current.sessions[session.name] = { ...current.sessions[session.name], address };
+  });
+}
+
+/**
+ * `obk session mailbox`: give one session its mailbox, bound to the tab this
+ * runs in, which is the session's own. The kit's launch line runs it in a new
+ * tab before the harness, and nothing else is meant to.
+ *
  * The mailbox is an Orca Run, made once and kept for ever. It has to be a Run
  * rather than the session's tab: Orca calls a terminal a live terminal-only
  * mailbox, says plainly that delivery does not outlive the tab, and refuses a
  * send once the pane is gone, while a Run survives a closed tab, a relaunch and
  * a restart (tech notes, section 1). Orca offers no way to delete one, so this
- * makes exactly one per session and never a second.
+ * makes one for a session whose book names none, and otherwise binds the one
+ * the book names to this tab: after a restart, or a closed tab brought back,
+ * it would stay with the tab that is gone (review of PR #248, finding 1).
  *
- * 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).
+ * Only inside an Orca tab. Asked from anywhere else, Orca picks a terminal
+ * itself, and seen live that was not the asker's (tech notes, section 1), so
+ * this refuses rather than bind somebody else's tab.
  *
  * 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, handle, { named = false, opened = false } = {}) {
-  const held = readBook(home).sessions[session.name] ?? {};
-  if (opened && typeof held.mailbox === 'string') useMailbox(held.mailbox, handle);
+export async function ownMailbox(bots, botName, sessionName) {
+  const home = botDir(bots, botName);
+  const bot = readBot(home, botName);
+  const session = (bot.sessions ?? []).find((entry) => entry.name === sessionName);
+  if (session === undefined) throw new Error(`${botName} has no session called ${sessionName} in ${path.join(home, 'bot.yaml')}.`);
+  const who = `${botName}/${sessionName}`;
+
+  if (!reachesMail(session, harnessOf(session, bot.harness))) {
+    return { bot: botName, session: sessionName, mailbox: null, change: 'none' };
+  }
+  if (process.env[TERMINAL_ENV] === undefined) {
+    throw new Error(`session mailbox binds ${who}'s mailbox to the Orca tab it runs in, and this is not one: ${TERMINAL_ENV} is not set. The kit runs it in the session's own tab when it starts the session.`);
+  }
 
-  const address = named ? addressOf(bot.name, session.name) : undefined;
-  const mailbox = mailboxFor(readBook(home), bot, session, harness, handle);
+  // Only in the tab the book names for the session. Two runs of `up` at once
+  // can leave a session two tabs, and the book one of them: a mailbox made or
+  // bound in the other would be bound to a tab no message is meant for.
+  const entry = readBook(home).sessions[sessionName] ?? {};
+  const here = process.env[TAB_ENV];
+  if (entry.tab === undefined || entry.tab !== here) {
+    throw new Error(`${who}'s mailbox is given in the tab the book names for it, ${entry.tab ?? 'none yet'}, and this is ${here ?? 'a tab that does not say which it is'}. Nothing was made or bound.`);
+  }
 
-  if (mailbox === undefined && (address === undefined || held.address === address)) return;
+  const held = entry.mailbox;
+  if (typeof held === 'string') {
+    try {
+      useMailbox(held, undefined, STEP_WAIT);
+    } catch (error) {
+      // An Orca that did not answer may still have done it, and is not asked
+      // a second time.
+      if (error.code === TIMED_OUT) {
+        throw new Error(`${error.message}\n${who}'s mailbox ${held} may now be bound to this tab, or may still be bound where it was: Orca did not say which.`);
+      }
+      throw new Error(`${error.message}\n${who}'s mailbox ${held} is unchanged: it is still bound to ${boundTo(held)}.`);
+    }
+    return { bot: botName, session: sessionName, mailbox: held, change: 'bound' };
+  }
 
-  await updateBook(home, (current) => {
-    const entry = { ...current.sessions[session.name] };
-    // Under the lock, and only if the book still has none: two runs at once
-    // would each have made one, and a session with two mailboxes is a session
-    // half its mail never reaches. The loser's Run is left unused.
-    if (mailbox !== undefined && typeof entry.mailbox !== 'string') entry.mailbox = mailbox;
-    if (address !== undefined) entry.address = address;
-    current.sessions[session.name] = entry;
-  });
+  // Made outside the book's lock, which is held for one read and one write
+  // (book.js).
+  let made;
+  try {
+    made = makeMailbox(who, STEP_WAIT);
+  } catch (error) {
+    const left = error.code === TIMED_OUT
+      ? `None is written down for ${who}; a Run Orca made after the kit stopped waiting is left unused.`
+      : `No mailbox was made for ${who}, and none is written down.`;
+    throw new Error(`${error.message}\n${left} It gets one the next time the kit starts it.`);
+  }
+
+  let kept;
+  let movedTo;
+  try {
+    await updateBook(home, (current) => {
+      const now = { ...current.sessions[sessionName] };
+      // The book may have moved to another tab while Orca was asked: a second
+      // `up` of the same session. Then nothing is written here and nothing
+      // bound, so the tab the book names keeps whatever it has.
+      if (now.tab !== here) {
+        movedTo = now.tab ?? 'none';
+        return undefined;
+      }
+      // Under the lock, and only if the book still has none: two runs at once
+      // would each have made one, and a session with two mailboxes is a session
+      // half its mail never reaches. The loser's Run is left unused.
+      if (typeof now.mailbox !== 'string') now.mailbox = made;
+      kept = now.mailbox;
+      current.sessions[sessionName] = now;
+      return undefined;
+    });
+  } catch (error) {
+    throw new Error(`${error.message}\nOrca made the mailbox ${made} for ${who}, bound to this tab, but it could not be written into the book, so it is left unused. The next time the kit starts ${who}, it makes another.`);
+  }
+  if (movedTo !== undefined) {
+    throw new Error(`the book now names another tab for ${who}, ${movedTo}, so the mailbox ${made} made in this tab is left unused. It is bound to this tab, and nothing was written into the book: ${who}'s mailbox there is left where it is.`);
+  }
+  // One terminal holds one Run, so making the loser took this tab off the one
+  // the book kept. It goes back.
+  if (kept !== made) useMailbox(kept, undefined, STEP_WAIT);
+  return { bot: botName, session: sessionName, mailbox: kept, change: kept === made ? 'made' : 'bound' };
 }
 
 /**
- * A new mailbox for this session, or undefined when it should not have one: it
- * has one already, or it is a Codex session whose user turned the sandbox
- * switch off, which could not read a mailbox if it had one.
- *
- * The Orca call is made outside the book's lock, which is held for one read and
- * one write (book.js).
+ * How long the step gives each Orca call. The step runs in front of the
+ * harness on the launch line, so it has to end: an Orca that never answers
+ * would otherwise leave the tab blank and the session never started. Generous,
+ * because a busy machine is slow.
  */
-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}`, handle);
+const STEP_WAIT = { timeoutMs: 20_000 };
+
+/** Whether a session that can have a mailbox has none in its book. */
+const lacksMailbox = (home, session, harness) => reachesMail(session, harness)
+  && typeof readBook(home).sessions[session.name]?.mailbox !== 'string';
+
+/** Where a Run is bound, as a sentence can say it, or the plain truth when Orca will not say. */
+function boundTo(id) {
+  try {
+    const handle = coordinatorOf(id, STEP_WAIT);
+    return handle === undefined ? 'no tab' : `the terminal ${handle}`;
+  } catch {
+    return 'whatever it was bound to before';
+  }
 }
 
 /**
@@ -479,7 +616,14 @@ function mailboxFor(book, bot, session, harness, handle) {
  * has already started a harness in, the harness's own record is asked.
  */
 function whichConversation(book, home, bot, session, was, harness) {
-  if (typeof was?.session === 'string') return { resume: was.session };
+  if (typeof was?.session === 'string') {
+    if (hasConversation(harness, home, was.session)) return { resume: was.session };
+    // The hook reported an id and the harness never wrote a conversation behind
+    // it: a session paused before its first turn is one. There is nothing to
+    // resume, so it starts again with its duty, and the book keeps the id in the
+    // history with the reason (#295).
+    return { noConversation: was.session };
+  }
   // No tab: nothing has ever run for this session, so there is nothing to find.
   if (typeof was?.tab !== 'string') return {};
 
@@ -526,14 +670,19 @@ const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, cha
 export const promptPath = (bots, bot, session) =>
   path.join(`${bots}.prompts`, `${encodeURIComponent(bot)}.${encodeURIComponent(session)}.txt`);
 
-function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, unclaimed }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, unclaimed, noMailbox = false }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // Whether this run picked the session up where it was or started a new one.
   // Only for a tab this run opened: a tab that was already there was left alone.
   if (resumed !== undefined) made.resumed = resumed;
+  // The id the book held that had no conversation behind it, now in the history.
+  if (noConversation !== undefined) made.noConversation = noConversation;
   // Orca's own words for what is on screen waiting to be answered, when it
   // gave any: the caller acts on it, the kit only passes it on.
   if (blockedReason !== undefined) made.blockedReason = blockedReason;
+  // A session that should have a mailbox and has none: the step in its tab
+  // did not make one, and nothing in this run would (#317).
+  if (noMailbox) made.noMailbox = true;
   // Conversations the harness still has in this bot's folder that no session
   // claims: the caller is told, because the kit will not pick one.
   if (unclaimed !== undefined && unclaimed.length > 0) made.unclaimed = unclaimed;