@assuredloop/orca-bot-kit 0.5.1 → 0.7.0

package/README.md

@@ -340,7 +340,7 @@ with why that one ended and when
 
 The book stays true to the harness through a hook `obk up` puts in the bot's own
 folder — `.claude/settings.json` or `.codex/hooks.json`, never your user-level
-settings ([ADR 0020](docs/adr/0020-kit-hooks-live-in-the-bot-folder.md)). Your own
+settings ([ADR 0022](docs/adr/0022-kit-hooks-live-in-the-bot-folder.md)). Your own
 settings in those files are kept. Codex asks you to trust a hooks file the first
 time it sees one; answer its question in the tab.
 
@@ -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
@@ -527,6 +545,7 @@ failing quietly.
 npm test                      # the whole suite, in a few minutes
 npm run test:system           # what the system tests would drive, and nothing else
 npm run test:system -- --yes  # drive them, on this machine, for real
+npm run test:system -- --yes test/system/groom.test.js  # only the ones you name
 npm run mutate                # the mutation audit, on what your branch changed
 ```
 
@@ -552,7 +571,9 @@ which Orca, which files, and what they will do to it — and then stops without
 driving any of it, answering non-zero so that a run which did not run them
 cannot be read as one that passed. `-- --yes` is how you say you meant it. When
 Orca is not answering, the command says which Orca it asked and skips, rather
-than report a kit that is not broken.
+than report a kit that is not broken. Name files after it to run only those;
+each must be one of the `*.test.js` files under `test/system/`, links followed,
+and a name that is not is refused before anything runs.
 
 `npm run mutate` runs [StrykerJS](https://stryker-mutator.io) over the
 JavaScript this branch changed against `main` — committed, still in the working

package/SETUP.md

@@ -102,8 +102,9 @@ Ask both in one message, then wait.
 
 **Where the bots folder goes.** An absolute path. It becomes a git repository of
 theirs holding every bot's configuration: charters, rules, session settings, the
-book of sessions. It holds none of the kit's code. They may push it somewhere
-later; the kit never commits for them.
+book of sessions. It holds none of the kit's code. The bots commit their own
+changes to it; the kit's commands never commit, and pushing it somewhere is
+theirs to decide.
 
 **Which harness Bot Father runs on**, `claude` or `codex`. There is no default
 and the kit will not guess. It is Bot Father's own harness only; each bot they

package/package.json

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

package/rules/commit.md

@@ -0,0 +1,18 @@
+---
+name: commit
+title: Commit your changes
+applies: all
+---
+
+Commit your own changes to the bots repo often, as each piece of work there is
+done: what you changed, in whatever folder it is, and what the kit wrote in
+your own bot's folder (its files there and your book of sessions). Stage each
+file by name and name them in the commit too (`git commit -- <files>`), so
+nothing another session staged goes in with yours. What no bot owns (init's
+files, the defaults, the user's rules and skill lists) is Bot Father's to
+commit. Commit yours even when the repo has no commit yet or holds files that
+are not yours; leave those to their owner.
+
+Committing is not pushing: pushing is the user's call. A clone in your work dir
+follows its own repo's rules. When a commit fails, for example on another
+session's index lock, try again, and say so if it still fails.

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

@@ -214,8 +214,12 @@ index load at every start. Codex's memories belong to the user and are shared
 by every Codex session, so a Codex bot cannot have its own; say so before
 turning them on for one. It is a hand edit, and say that you made it.
 
-After each change, commit what it changed in the bots folder; the kit never
-commits by itself.
+After each change, commit what it changed in the bots folder, naming each
+file when you stage it and again in the commit. Commit with it what no bot
+owns and nobody has committed yet: `init`'s files, `defaults.yaml`,
+`skills.yaml`, and the user's `rules/` and `skills/`. What it changed
+includes the folder of a bot it made or changed. The kit never commits by
+itself.
 
 Do the reversible part and stop at the line. Making a bot, adding a session
 and linking skills add things and are safe to run again; closing a tab,

package/skills/obk-fleet-review/SKILL.md

@@ -251,6 +251,7 @@ identifiers, counts and paths that only show the work; where evidence matters,
 say where it is.
 
 Say what you did not look at. Where you changed anything in the bots folder,
-commit it; the kit never commits by itself.
+commit it, naming each file when you stage it and again in the commit; the
+kit never commits by itself.
 
 Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-grooming/SKILL.md

@@ -63,7 +63,8 @@ them says so and reads less, not everything.
 The open findings are what stops the same thing being reported every day:
 before filing an issue or sending feedback, look there, and where it is already
 open, add to it rather than raising it again. Take a finding off when it is
-fixed or no longer true. Commit these once a day, at the end of the run.
+fixed or no longer true. Commit these at the end of each run, naming each
+file when you stage it and again in the commit.
 
 ## Keep the run bounded
 

package/src/bot.js

@@ -59,7 +59,7 @@ export function botNames(bots) {
  * link the user made takes it out of that folder; undefined when it stays in.
  *
  * The kit writes only in the bot folder, never in user-level settings (PRD 6.3,
- * ADR 0020), and a link would make the one the other without a word. So the
+ * ADR 0022), and a link would make the one the other without a word. So the
  * answer is the file system's, not the spelling's: see `whereItLeads`.
  */
 export function leadsOutside(home, target) {
@@ -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. */
@@ -409,7 +414,7 @@ const RECORD = 'session record';
  * A hook runs inside the user's own session, so this one stays out of the way:
  * it writes on standard output only what the harness is to read as JSON, and
  * whatever goes wrong, it goes wrong quietly. A book left stale is a thing the
- * health check finds later; a session disturbed is the user's work (ADR 0020).
+ * health check finds later; a session disturbed is the user's work (ADR 0022).
  */
 async function record(bots, bot) {
   try {
@@ -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,11 +22,12 @@ 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';
-import { frontOfTab, orcaDefaultArgs, projects, tabs } from './orca.js';
+import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
+import { frontOfTab, orcaDefaultArgs, projects, tabs, wordsOfProcess } from './orca.js';
+import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
 import { settingsInUse } from './settings.js';
 import { skillsTrouble } from './skills.js';
@@ -186,6 +187,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')),
@@ -214,8 +216,9 @@ const hooksOf = (bots, home, bot) => [...new Set(bot.sessions.map((session) => h
 /**
  * Each session of this bot running in a tab Orca has, with what it runs on set
  * beside what the bot asks for now, added to `sessions`; a finding for each
- * one that runs on something else (#271, #272); and a finding for each one
- * whose tab is open with its harness gone from it (#300).
+ * one that runs on something else (#271, #272), or whose harness the kit's
+ * launch line did not start (#318); and a finding for each one whose tab is
+ * open with its harness gone from it (#300).
  *
  * Two questions, each answered from where the answer is written. The settings
  * from the harness's own record of the conversation the session is in now,
@@ -256,15 +259,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);
@@ -277,8 +272,15 @@ function runningOn(bots, home, bot, book, handles, sessions) {
     if (running !== 'yes') continue;
 
     const off = Object.entries(settings).filter(([, one]) => one.state === 'mismatch');
-    if (off.length > 0) {
-      const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+    const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+    if (startedByKit(front.pid, entry.tab) === false) {
+      // Orca brings its tabs back by itself after a restart or an update, with
+      // a bare resume and none of the kit's launch line (#318). What health can
+      // see may still match, by the harness's own defaults; the rest of what
+      // bot.yaml asks for is not on it either way.
+      const drift = off.length === 0 ? '' : ` ${parts}, as the harness's own record of its conversation ${conversation} says.`;
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} was not started by the kit: the harness in its tab ${entry.tab} carries nothing of the kit's launch line, as when Orca brings its tabs back by itself after a restart or an update. So it runs on the harness's own defaults and whatever Orca added, not on what ${path.join(home, 'bot.yaml')} asks for.${drift} ${restart} starts it on bot.yaml.`, bot.name));
+    } else if (off.length > 0) {
       found.push(finding('session', file, `${bot.name}'s session ${session.name} does not run on what ${path.join(home, 'bot.yaml')} asks for. ${parts}. That is what the harness's own record of its conversation ${conversation} says. A session takes these when it starts, so if bot.yaml changed after it started, ${restart} starts it on them; if not, something else set them, such as a default of the harness's own or a change made inside the session.`, bot.name));
     }
 
@@ -296,6 +298,19 @@ function runningOn(bots, home, bot, book, handles, sessions) {
   return found;
 }
 
+/**
+ * Whether the kit's launch line started the process `pid` in the tab `tab`:
+ * true when it carries the marker the line puts there, false when it carries
+ * that tab's id and no marker, and undefined when its environment cannot be
+ * read (tech notes, section 1). Only a whole word counts: an argument, such as
+ * a start prompt, can hold anything.
+ */
+function startedByKit(pid, tab) {
+  const words = pid === undefined ? undefined : wordsOfProcess(pid);
+  if (words === undefined || !words.includes(`${TAB_ENV}=${tab}`)) return undefined;
+  return words.some((word) => new RegExp(`^${SHELL_ENV}=[0-9]+$`).test(word));
+}
+
 /**
  * What Orca has of this bot against what the book says it should have: a
  * session whose tab is gone, a conversation nobody claims, and a tab in the
@@ -364,7 +379,7 @@ function inOrca(bots, home, bot, setups, sessions) {
 /**
  * The conversations a harness has on record in this bot's folder that the book
  * does not name anywhere. The hook is how an id reaches the book, and when it
- * fails it fails quietly (ADR 0020), so this is where a stale book shows: the
+ * fails it fails quietly (ADR 0022), so this is where a stale book shows: the
  * harness's own record set beside it (ADR 0012).
  */
 function offTheBook(home, bot, book, onRecord) {

package/src/hooks.js

@@ -1,4 +1,4 @@
-// The kit's own hook, in the bot's folder and nowhere else (ADR 0020).
+// The kit's own hook, in the bot's folder and nowhere else (ADR 0022).
 //
 // Both harnesses read a hooks file out of the folder a session starts in, and
 // every session starts at its bot home, so the bot folder is where the kit's
@@ -35,7 +35,7 @@ const TIMEOUT = 10;
  * What the hook runs: the CLI that wrote it, by its own path, so the session
  * reports to the kit that set it up and not to whatever `obk` PATH finds in the
  * harness's shell (#220). `|| true` and a quiet stderr because a hook must never
- * disturb the session it fires in (ADR 0020): a kit that is not there, or a book
+ * disturb the session it fires in (ADR 0022): a kit that is not there, or a book
  * that cannot be written, leaves the session alone and the health check finds
  * the stale book later.
  */
@@ -124,7 +124,7 @@ export function hookTrouble(home, harness, { bots, bot }) {
 /**
  * What to say about a hooks file that a link takes out of the bot folder, or
  * undefined when it stays in. The kit writes its hook in the bot folder and
- * nowhere else (ADR 0020); through a link like that it would be writing the
+ * nowhere else (ADR 0022); through a link like that it would be writing the
  * user's own settings, so it does not, and says why.
  */
 function outside(home, file) {

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}`);
   }
@@ -338,8 +346,8 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
 
 /**
  * Who holds the terminal of the pane `ptyId`: `{ front: 'shell' }`,
- * `{ front: 'program', command }` with the name of the process leading the
- * group in front, or `{ unreadable: <why> }`.
+ * `{ front: 'program', command, pid }` with the name and pid of the process
+ * leading the group in front, or `{ unreadable: <why> }`.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
  * gives that pid's terminal's foreground process group (ADR 0021).
@@ -366,7 +374,20 @@ function frontOf(ptyId) {
   const front = psLine(own.tpgid);
   if (front === undefined) return { unreadable: `ps could not read the process in front, pid ${own.tpgid}` };
   const shell = front.ppid === pane && path.basename(own.comm) === 'login';
-  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm) };
+  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm), pid: own.tpgid };
+}
+
+/**
+ * The process `pid` as `ps -E` gives it, word by word: its command, its
+ * arguments, then its environment as `NAME=value` words. Undefined when it
+ * cannot be read. macOS gives a same-user harness's environment this way (tech
+ * notes, section 1); nothing in it says where the arguments end, so a caller
+ * looks for one whole word it knows.
+ */
+export function wordsOfProcess(pid) {
+  const asked = spawnSync(psCli(), ['-E', '-ww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+  if (asked.error || asked.status !== 0) return undefined;
+  return asked.stdout.trim().split(/\s+/);
 }
 
 /** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, or undefined. */
@@ -418,37 +439,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/record.js

@@ -166,22 +166,26 @@ function unclaimedFor(book, home, bot, tabId, id) {
 }
 
 /**
- * Whether the harness that ran this hook is the session's own — the one the kit
- * typed into the tab — rather than a harness started inside the session.
+ * Whether the harness that ran this hook is the session's own — the one the
+ * tab's shell started — rather than a harness started inside the session.
  *
  * Proved live on both harnesses (tech notes, sections 2 and 3): a hook's process
  * is the harness's own child, or the child of the shell the harness ran the hook
  * command through. Either way the harness itself is the process just above, and
- * the session's harness is the child of the shell named in the launch line. A
- * harness started inside the session sits further down a longer chain, under
- * whatever shell the agent ran it from, so it can never answer this.
+ * the session's harness is the child of the tab's shell. A harness started
+ * inside the session sits further down a longer chain, under whatever shell the
+ * agent ran it from, so it can never answer this.
+ *
+ * The launch line names the tab's shell. A tab Orca brought back by itself has
+ * no launch line (#318), and there the tab's shell is the one `login` started
+ * for the pane, which is where Orca's own resume puts the harness too (tech
+ * notes, section 1).
  *
  * Anything it cannot establish is a no: a report that cannot be shown to be the
  * session's own is not written down.
  */
 export function startedTheSession(shellPid, pid = process.pid) {
-  if (!/^[0-9]+$/.test(String(shellPid ?? ''))) return false;
-  const shell = Number(shellPid);
+  if (shellPid !== undefined && !/^[0-9]+$/.test(String(shellPid))) return false;
 
   const tree = processTree();
   if (tree === undefined) return false;
@@ -190,11 +194,21 @@ export function startedTheSession(shellPid, pid = process.pid) {
   const parent = mine === undefined ? undefined : tree.get(mine.ppid);
   if (parent === undefined) return false;
 
-  if (parent.ppid === shell) return true;
-  if (!isShell(parent.command)) return false;
+  if (shellPid !== undefined) {
+    const shell = Number(shellPid);
+    if (parent.ppid === shell) return true;
+    if (!isShell(parent.command)) return false;
+
+    const above = tree.get(parent.ppid);
+    return above !== undefined && above.ppid === shell;
+  }
 
-  const above = tree.get(parent.ppid);
-  return above !== undefined && above.ppid === shell;
+  // With no shell named, which process is the harness has to be settled first:
+  // the one above the shell the hook ran through, or the hook's own parent.
+  const harness = isShell(parent.command) ? tree.get(parent.ppid) : parent;
+  const shell = harness === undefined ? undefined : tree.get(harness.ppid);
+  const pane = shell === undefined ? undefined : tree.get(shell.ppid);
+  return pane !== undefined && path.basename(pane.command) === 'login';
 }
 
 /** Every process on the machine, by pid: who its parent is and what it runs. */

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/skills.js

@@ -292,7 +292,7 @@ export function unlinkSkills(home) {
  * user made, or one of the kit's that they have since repointed, is theirs.
  *
  * It is the kit's own file and lives beside the hook files it already keeps in
- * the bot folder (ADR 0020). A record that cannot be read is treated as an
+ * the bot folder (ADR 0022). A record that cannot be read is treated as an
  * empty one: the worst that follows is that the kit leaves alone something it
  * would otherwise have tidied up, which is the safe way round.
  */

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';
 
@@ -93,7 +94,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
  *
  * Separate from the tabs because the order matters twice over. A session reads
  * its rules, its skills and its hooks as it comes up, so all three have to be
- * there before the tab is (PRD 6.6, ADR 0020) — and a restart closes a tab in
+ * there before the tab is (PRD 6.6, ADR 0022) — and a restart closes a tab in
  * between, so everything that can refuse must have refused before that. It
  * refuses by throwing, exactly as `up` always has; a bot it leaves out of
  * `running` is one whose sessions must not be started.
@@ -139,7 +140,7 @@ export function prepareBots(bots, names, onlySession) {
 
   // And the kit's hook goes into every bot folder before Orca is asked for
   // anything, for the same reason: a harness reads its hooks when it comes up,
-  // so one written later would miss the session it was written for (ADR 0020),
+  // so one written later would miss the session it was written for (ADR 0022),
   // and a bot folder the kit cannot write it into stops the run with nothing
   // opened anywhere. Only the harnesses a bot actually runs on; a bot with no
   // sessions gets none.
@@ -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;