@assuredloop/orca-bot-kit 0.5.1 → 0.6.0

package/README.md

@@ -391,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
@@ -415,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,
@@ -438,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;
@@ -489,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.1",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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.`);
@@ -1180,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}`;

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)}`,
     };
   }
 
@@ -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) {
@@ -417,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,9 +24,11 @@ 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.
@@ -35,6 +37,9 @@ export function orca(args) {
   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'}`),
@@ -42,8 +47,11 @@ const refusal = (args, answer) => Object.assign(
 );
 
 /** 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}`);
   }
@@ -418,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 }) {

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

@@ -12,8 +12,9 @@ import { forgetClaimed, forgetSession, readBook, sessionIdsIn, tabIdsIn, updateB
 import { botDir, botNames, displayName, readBot } from './bot.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
@@ -264,7 +266,7 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // Asked before the book is held, because it reads a folder of the harness's
   // own files: nothing slow happens under the lock.
   let which = whichConversation(book, home, bot, session, was, harness);
-  const launchOf = (chosen) => launchFor(bots, bot, session, harness, home, workDir, chosen.resume);
+  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
@@ -322,13 +324,12 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // the harness as the tab's own command times out and leaves a dead tab.
   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
@@ -354,6 +355,9 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     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: launch.promptFile,
@@ -365,23 +369,34 @@ async function bringUpSession(bots, home, live, session, bot, title) {
 
 /**
  * The line that starts this session: resuming `resume`, or, with none, a fresh
- * start carrying its duty. Returns `{ resume, prompt, promptFile, command }`.
+ * start carrying its duty. Returns `{ resume, prompt, promptFile, command, address }`.
  */
-function launchFor(bots, bot, session, harness, home, workDir, resume) {
+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);
-  const command = launchCommand(session, {
+  // 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: harness === 'claude' ? addressOf(bot.name, session.name) : undefined,
+    address,
   });
-  return { resume, prompt, promptFile, command };
+  // 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 };
 }
 
 /**
@@ -441,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
@@ -450,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';
+  }
 }
 
 /**
@@ -568,7 +670,7 @@ 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, noConversation, 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.
@@ -578,6 +680,9 @@ function entry(tab, { bot, name, created, running = false, blockedReason, prompt
   // 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;