@assuredloop/orca-bot-kit 0.25.2 → 0.25.4

package/README.md

@@ -350,6 +350,11 @@ address that is none of your bots folder's sessions, the hook tells it so, and
 names the address `obk message to` would have given. The message goes either
 way ([ADR 0032](docs/adr/0032-a-native-message-outside-the-fleet-is-warned-about.md)).
 
+And a third: at the end of each turn, it tells the session once about fleet
+mail the kit sent it that is still unread, without typing into its tab
+([ADR 0035](docs/adr/0035-messaging-transport.md)). It asks Orca only when the kit
+knows of mail for that session.
+
 A Codex bot gets one more hook too. Inside Codex's sandbox the kit cannot always
 tell whether the receiver of a message has its harness in front, as for a Claude
 session busy running a command, so `obk message send` leaves that nudge, and the
@@ -555,7 +560,7 @@ verdict: which of these matter, and in what order, is for you or for Bot Father.
 ## Sessions and bots that talk
 
 Ask the kit how to reach a session, and it answers with the road and the
-address ([ADR 0030](docs/adr/0030-messaging-transport.md)):
+address ([ADR 0035](docs/adr/0035-messaging-transport.md)):
 
 ```sh
 obk message to    --bots /path/to/my-bots --to api-bot/daily
@@ -598,11 +603,17 @@ mailbox where it was and says so, and the harness starts all the same. A check
 holds its turn for 40 seconds at most: with more mail than it reads in that
 time, it shows what it read and says the rest is still waiting.
 
-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
-whole of "queued, not interrupting". A session that is not up is not typed
-into at all; its message waits.
+Nothing in a mailbox wakes anybody, so each message gets one signal that tells
+the receiver to look. Orca's own notice comes first: Orca types it into an idle
+tab. The kit watches an idle receiver for up to 8 seconds, and reads the
+receiver's own record of its turns. When Orca's notice is there, the kit types
+nothing. When no turn started, the kit types its own line. A Claude session busy
+with a turn gets nothing typed: its hook tells it at the end of the turn. A busy
+Codex session gets the kit's line, which Codex takes into the turn it is having.
+The send says which signal went. A session that is not up is not typed into at
+all; its message waits. When a session is retired, the kit says how many
+messages sent to it were not read with `obk message check`, and who sent them
+([ADR 0035](docs/adr/0035-messaging-transport.md)).
 
 A message longer than 4 KiB is written to a file beside your bots folder and
 named in the message, so a long one arrives whole without landing a document in

package/SETUP.md

@@ -201,7 +201,7 @@ waiting for:
 | Claude Code's folder trust list | `\x1b[B\r` | down, then return: its selection starts on **No, exit** | Claude Code 2.1.283 |
 | Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `\r` | return: its selection starts on **Trust and continue** | Codex 0.160.0 |
 | Codex's `Hooks need review` | `\x1b[B\r` | down, then return, to **Trust all and continue**; if the selection already starts there, return alone | Codex 0.160.0 |
-| Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home) | Codex 0.160.0 |
+| Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home); on 0.162.0 it is called **1. Use current Git worktree** (Keep using the current working directory). Never **Create new Git worktree** | Codex 0.160.0; Codex 0.162.0 (#516) |
 | Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; seen on 0.157.1 (offering 0.158.0) with the selection on **Update now**, not pressed; 0.158.0 offered 0.160.0, taken on 2026-10-02 by Bot Father's restarts |
 | `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell | oh-my-zsh bf77e35 |
 | Claude Code's `Teach auto mode about your environment?` | `\x1b` | Esc, which cancels it (**Not now**). On 2.1.283 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live twice on 2.1.283, in #261's live test and #239's live run 1 (#416); 2.1.278 showed a numbered list, answered with 2. Not now |

package/package.json

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

package/src/clear.js

@@ -38,9 +38,13 @@ const POINTER = { claude: '❯', codex: '›' };
  */
 const RECORD_LINE = 'obk: this conversation was started by obk session clear, and this line is only so the kit can record it. Reply "ok"; nothing else is asked.';
 
-/** What Codex asks after `/new`, and the one answer the kit gives it: the bot home it runs in. */
+/**
+ * What Codex asks after `/new`, and the one answer the kit gives it: the bot
+ * home it runs in. Codex 0.162.0 calls it by another name, and its whole row
+ * has to be as captured, but for the padding before its description (#516).
+ */
 const WHERE_TO_RUN = 'Where should the new conversation run?';
-const CURRENT_CHECKOUT = /^ *› +1\. Current checkout\b/;
+const CURRENT_CHECKOUT = /^ *› +1\. Current checkout\b|^ *› 1\. Use current Git worktree\s+Keep using the current working directory *$/;
 
 /** Codex's empty input line: its pointer alone, or with its placeholder. */
 const CODEX_EMPTY = ['›', '› Ask Codex to do anything'];
@@ -51,7 +55,8 @@ const CODEX_EMPTY = ['›', '› Ask Codex to do anything'];
  * selected row stands for what Return will run: with the menu open, Return
  * runs the selected command, and the menu is narrowed to what was typed
  * (codex-rs/tui/src/bottom_pane/chat_composer.rs, rust-v0.160.0). The
- * architect's ruling on #391, after live run 4.
+ * architect's ruling on #391, after live run 4. Only where Orca gives no
+ * draft: a draft is the line's text, and has to be the command (#516).
  */
 const CODEX_BARE_LINE = '0.160.0';
 
@@ -221,16 +226,19 @@ async function enter(it, verb, before = () => {}) {
  * when it was typed.
  */
 export async function typeCommand(it, command, { before = () => {}, check = menuWrong, cannot = () => '', deadline = Infinity } = {}) {
-  // On Codex, what is typed cannot be read back once its menu is open, so
-  // nothing may be in its input line before: no draft for the command to join.
-  const emptyLine = (rows) => {
+  // Nothing may be in the input line before: no draft for the command to join.
+  // Orca gives a draft in the line beside the screen, and the screen's line
+  // then reads the pointer alone (#510, #516). Where it gives none, Codex's
+  // line on the screen has to be empty.
+  const emptyLine = ({ rows, draft }) => {
+    if (draft !== undefined) throw new Error(`${it.name}: nothing was typed, because its input line holds a draft: it reads "${draft}".${shownEnd(rows)}`);
     if (it.harness !== 'codex') return;
     const line = rows.findLast((row) => /^ *›/.test(row))?.trim();
     if (!CODEX_EMPTY.includes(line)) {
       throw new Error(`${it.name}: nothing was typed, because its input line is not empty: it reads "${line ?? 'nothing'}".${shownEnd(rows)}`);
     }
   };
-  emptyLine((await idleTab(it)).rows);
+  emptyLine(await idleTab(it));
   const version = it.harness === 'codex' ? codexVersion(readBook(it.home).sessions[it.session]?.session) : undefined;
 
   before();
@@ -238,7 +246,7 @@ export async function typeCommand(it, command, { before = () => {}, check = menu
   // with no wait, before the first key (#480 review).
   const ready = lookAt(it);
   if (ready.why !== undefined) throw new Error(`${it.name}: nothing was typed, because ${ready.why}.`);
-  emptyLine(ready.rows);
+  emptyLine(ready);
   const { handle } = ready;
   const typedAt = Date.now();
   // One character a send, each after a look through the gate, so nothing goes
@@ -329,7 +337,7 @@ async function idleTab(it) {
 }
 
 /**
- * One look through the typing gate at the session's tab: `{ handle }` when
+ * One look through the typing gate at the session's tab: `{ handle, rows, draft }` when
  * nothing on its screen asks a question and nothing says it is at work, and,
  * with `idle`, Orca's tui-idle answered ok; or `{ why }`, naming the signal,
  * with `moved` when the book holds another tab for the session now, or, where
@@ -364,7 +372,7 @@ function lookAt(it, { idle = true } = {}) {
   const signal = signalIn(found.rows);
   if (signal !== undefined) return { why: signal };
   if (idle && !found.idle) return { why: 'it is busy with a turn: Orca\'s tui-idle did not answer ok' };
-  return { handle: found.handle, rows: found.rows };
+  return { handle: found.handle, rows: found.rows, draft: found.draft };
 }
 
 /**
@@ -384,7 +392,7 @@ async function typedWrong(handle, harness, command, version, check) {
     // a question that shows on it stops it at once (review of c1e5ba4).
     const signal = seen.rows === undefined ? undefined : signalIn(seen.rows);
     if (signal !== undefined) return { why: signal, rows: seen.rows };
-    const wrong = seen.rows === undefined ? { why: `its screen could not be read (${seen.unreadable})` } : check(seen.rows, harness, command, version);
+    const wrong = seen.rows === undefined ? { why: `its screen could not be read (${seen.unreadable})` } : check(seen.rows, harness, command, version, seen.draft);
     if (wrong === undefined || Date.now() >= until) return wrong && { ...wrong, rows: seen.rows };
     await pause(ASK_MS);
   }
@@ -406,13 +414,17 @@ function signalIn(rows) {
   return undefined;
 }
 
-function menuWrong(rows, harness, command, version) {
+function menuWrong(rows, harness, command, version, draft) {
   const at = rows.findLastIndex((row) => /^ *[›❯]/.test(row));
   if (at < 0) return { why: 'its screen shows no input line' };
   // Claude Code 2.1.288 puts a non-breaking space after its pointer (live run 4).
   const line = rows[at].replaceAll('\u00a0', ' ').trim();
-  if (harness === 'codex') return codexMenuWrong(rows, at, line, command, version);
-  if (line !== `${POINTER[harness]} ${command}`) return { why: `its input line reads "${line}"` };
+  // Orca 1.4.223 gives the line's text as the draft, and the line on the
+  // screen then reads the pointer alone: Claude Code 2.1.296's (#510, probe 4)
+  // and Codex 0.162.0's (#516).
+  const text = draft === undefined ? line : `${POINTER[harness]} ${draft}`;
+  if (harness === 'codex') return codexMenuWrong(rows, at, text, command, version);
+  if (text !== `${POINTER[harness]} ${command}`) return { why: `its input line reads "${text}"` };
   return claudeMenuWrong(rows, at, command);
 }
 
@@ -420,25 +432,30 @@ function menuWrong(rows, harness, command, version) {
  * Claude Code 2.1.288 draws its slash menu above its input box's top rule, a
  * row of ─: a row per command, starting with it, its description wrapped onto
  * rows set far in (live run 4). No pointer marks a selection, so the first
- * command row there has to be the command.
+ * command row there has to be the command. Claude Code 2.1.296 starts the
+ * selected row with its pointer, `  ❯ /compact`, and that row has to be the
+ * command (#510, probes 1 and 2). The menu's pointer is above the rule, the
+ * input line's below it, so the one is never taken for the other.
  */
 function claudeMenuWrong(rows, at, command) {
   const rule = rows.slice(0, at).findLastIndex((row) => /^\s*─{3}/.test(row));
   const menu = [];
-  for (let up = rule - 1; up >= 0 && (/^ {1,4}\/\S/.test(rows[up]) || /^ {20,}\S/.test(rows[up])); up -= 1) menu.unshift(rows[up]);
-  const first = menu.find((row) => /^ {1,4}\//.test(row));
-  if (rule < 0 || first === undefined) return { why: 'no menu of commands came up above its input box', menu: true };
-  if (first.trim().split(/\s+/)[0] !== command) return { why: `the first row of its menu is "${first.trim()}"`, menu: true };
+  for (let up = rule - 1; up >= 0 && (/^ {1,4}(?:❯ +)?\/\S/.test(rows[up]) || /^ {20,}\S/.test(rows[up])); up -= 1) menu.unshift(rows[up]);
+  const pointed = menu.find((row) => /^ {1,4}❯ +\//.test(row));
+  const selected = pointed === undefined ? menu.find((row) => /^ {1,4}\//.test(row)) : pointed.replace(/^ *❯ +/, '');
+  if (rule < 0 || selected === undefined) return { why: 'no menu of commands came up above its input box', menu: true };
+  if (selected.trim().split(/\s+/)[0] !== command) return { why: `the ${pointed === undefined ? 'first' : 'selected'} row of its menu is "${selected.trim()}"`, menu: true };
   return undefined;
 }
 
 /**
  * Codex draws its slash menu above the input line: a row per command, the
- * selected one starting with its pointer, then a blank row, then the input
- * line (its own snapshot tests, chat_composer slash_popup_*.snap,
- * rust-v0.160.0; live run 4). The menu has to hold one command row, the
- * selected one, naming the command. The input line reads the command, or, on
- * the Codex whose line Orca shows bare, its pointer alone.
+ * selected one starting with its pointer, then a blank row on 0.160.0 and none
+ * on 0.162.0, then the input line (its own snapshot tests, chat_composer
+ * slash_popup_*.snap, rust-v0.160.0; live run 4; #516's probe). The menu has
+ * to hold one command row, the selected one, naming the command. The input
+ * line, Orca's draft where it gives one, reads the command, or, with no draft
+ * on the Codex whose line Orca shows bare, its pointer alone.
  */
 function codexMenuWrong(rows, at, line, command, version) {
   const bare = line === '›' && version === CODEX_BARE_LINE;
@@ -483,7 +500,7 @@ async function answerWhereToRun(it, handle, command) {
       const pointer = rows.findLast((row) => /^ *›/.test(row));
       if (pointer === undefined || !CURRENT_CHECKOUT.test(pointer)) {
         send(handle, '\x1b');
-        throw new Error(`${it.name}: after ${command}, Codex asked "${WHERE_TO_RUN}" with its selection on "${pointer?.trim() ?? 'nothing'}" rather than "1. Current checkout", so it was backed out of with Esc and nothing else was typed. Look at its tab.`);
+        throw new Error(`${it.name}: after ${command}, Codex asked "${WHERE_TO_RUN}" with its selection on "${pointer?.trim() ?? 'nothing'}" rather than "1. Current checkout" (on Codex 0.162.0, "1. Use current Git worktree"), so it was backed out of with Esc and nothing else was typed. Look at its tab.`);
       }
       send(handle, '\r');
       return;

package/src/cli.js

@@ -18,14 +18,14 @@ import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { nameSession } from './name.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
-import { checkMail, decideLeftNudges, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
+import { checkMail, decideLeftNudges, lookUp, noMailboxYet, sendMessage, sessionInTab, stillUnread, WATCH_MS } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE, TERMINAL_ENV } from './orca.js';
 import { allowCommand, allowIn, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
 import { clearSession, compactSession } from './clear.js';
-import { retireBot, retireSession } from './retire.js';
+import { retireBot, retireSession, unreadWords } from './retire.js';
 import { sentWarning } from './sent.js';
 import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
@@ -281,6 +281,11 @@ Usage:
                             nudges a send there left because it could not
                             tell from inside Codex's sandbox, and types each
                             one or says why not.
+  obk session mail --bots <path> --bot <bot>
+                            For the kit's own hook, not for typing: at the end
+                            of a Claude session's turn, it tells the session
+                            once about each fleet mail the kit sent it that is
+                            still unread. It types nothing into the tab.
   obk session name --bots <path> --bot <bot>
                             For the kit's own hook, not for typing: after a
                             Codex session's turn, it names the session's thread
@@ -329,6 +334,7 @@ const COMMANDS = {
   'session record': ['bots', 'bot'],
   'session sent': ['bots', 'bot'],
   'session nudge': ['bots', 'bot'],
+  'session mail': ['bots', 'bot'],
   'session name': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
   'temp make': ['bots', 'name'],
@@ -463,6 +469,7 @@ async function run(argv) {
   // there included, so it goes before anything that can complain (ADR 0032).
   if (command === SENT) return sent(path.resolve(values.bots));
   if (command === NUDGE) return nudgeLeft();
+  if (command === MAIL) return mailHook(path.resolve(values.bots), values.bot);
   if (command === NAME) return nameThread(path.resolve(values.bots), values.bot);
 
   // One fleet, one identity, whatever spelling of its path was given (#164).
@@ -534,6 +541,7 @@ const ANSWER_IT = [
 const RECORD = 'session record';
 const SENT = 'session sent';
 const NUDGE = 'session nudge';
+const MAIL = 'session mail';
 const NAME = 'session name';
 
 /**
@@ -559,11 +567,11 @@ function sent(bots) {
  * what became of each, as Codex's `additionalContext` (#350, ADR 0034). Silent
  * when nothing was left, never a decision, and never anything but exit 0.
  */
-function nudgeLeft() {
+async function nudgeLeft() {
   try {
     const said = JSON.parse(readFileSync(0, 'utf8'));
     if (said?.hook_event_name !== 'PostToolUse') return 0;
-    const decided = decideLeftNudges(process.env[TAB_ENV]);
+    const decided = await decideLeftNudges(process.env[TAB_ENV]);
     if (decided.length > 0) {
       const words = decided.map((one) => `Your mail "${one.subject}" to ${one.to}: ${one.nudged ? "the kit's hook nudged its tab, from outside Codex's sandbox:" : "the kit's hook looked at its tab from outside Codex's sandbox, and"} ${nudgeLine(one, one.to).trim()}`);
       process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: words.join('\n') } })}\n`);
@@ -574,6 +582,24 @@ function nudgeLeft() {
   return 0;
 }
 
+/**
+ * What the kit's Claude Code Stop hook does at a turn end (#509, ADR 0035): tell
+ * the session once about fleet mail still unread, as the Stop event's
+ * additional context, which the session goes on with. Not a block: Claude Code
+ * 2.1.296 draws a block's reason in red as "Stop hook error", and its additional
+ * context as "Stop hook feedback". Nothing typed into the tab; never anything
+ * but exit 0; silent whenever it cannot be sure.
+ */
+function mailHook(bots, bot) {
+  try {
+    const reason = stillUnread(sameFleet(bots), bot, JSON.parse(readFileSync(0, 'utf8')), process.env[TAB_ENV], process.env[TERMINAL_ENV]);
+    if (reason !== undefined) process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'Stop', additionalContext: reason } })}\n`);
+  } catch {
+    // Nothing: a hook does not disturb the session it runs in.
+  }
+  return 0;
+}
+
 /**
  * What the kit's Codex Stop hook does at a turn end: name the session's thread
  * after its bot and session, once it is idle (#480). Silent, never a decision,
@@ -703,6 +729,7 @@ const commands = {
           ...withLines(retired.retiredWith, retired.session),
           ...closedLines(retired.closed),
           `retired    ${retired.bot} ${retired.session}: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+          ...unreadLines(retired.unread),
           ...leftLines(retired.promptsLeft),
         ],
       };
@@ -732,6 +759,7 @@ const commands = {
           retired.windowReloaded ? "reloaded   Orca's window, so its sidebar no longer shows the project" : RELOAD_LINE,
         ]),
         `retired    ${retired.bot}: moved to ${path.relative(bots, retired.moved)}, with its book, charter and memory`,
+        ...(retired.unread ?? []).flatMap((one) => unreadLines(one, `${retired.bot}/${one.session}`)),
         ...leftLines(retired.promptsLeft),
       ],
     };
@@ -788,6 +816,7 @@ const commands = {
         ...withLines(retired.retiredWith, retired.session),
         ...closedLines(retired.closed),
         `retired    ${retired.bot} ${retired.session}, a temporary session of ${retired.maker}'s: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+        ...unreadLines(retired.unread),
         ...leftLines(retired.promptsLeft),
       ],
     };
@@ -1081,10 +1110,10 @@ const commands = {
     };
   },
 
-  'message send'(bots, values) {
+  async 'message send'(bots, values) {
     const tab = callerTab(bots, values.from === undefined);
     refuseWhenOrcaIsDown();
-    const answer = sendMessage(bots, {
+    const answer = await sendMessage(bots, {
       to: values.to,
       from: values.from,
       tab,
@@ -1174,6 +1203,7 @@ const commands = {
     const said = {
       made: `${who} has its mailbox ${answer.mailbox}, made in this tab.`,
       bound: `${who}'s mailbox ${answer.mailbox} is bound to this tab.`,
+      replaced: `${who}'s mailbox ${answer.replaced} is not one this Orca has, as when the book was written on another machine, so it has a new one, ${answer.mailbox}, made in this tab and written into the book.`,
       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]] };
@@ -1248,13 +1278,26 @@ function toLines(answer, bots, where) {
  * about the message.
  */
 function nudgeLine(answer, where) {
+  const seconds = answer.watchedMs === undefined ? '' : ` in ${Math.max(Math.round(answer.watchedMs / 1000), 1)} s`;
+  if (answer.signal === 'orca') return `             Orca's notice reached it${seconds}, so no line was typed: it reads the mail from there.`;
+  if (answer.signal === 'hook') {
+    return answer.because === 'busy'
+      ? "             it is busy with a turn, so nothing was typed into its tab: its own hook tells it about the mail when that turn ends."
+      : `             a turn of other work started in its tab${seconds}, not Orca's notice, so nothing was typed: its own hook tells it about the mail when that turn ends.`;
+  }
+  const why = {
+    'no-turn': `no turn started in its tab in ${WATCH_SECONDS} s, so the kit's line was typed`,
+    busy: "it is busy with a turn, and Codex takes a line into the turn it is having, so the kit's line was typed",
+    'other-turn': "a turn of other work started in its tab, not Orca's notice, so the kit's line was typed",
+  }[answer.because];
+  const head = why === undefined ? '             ' : `             ${why}: `;
   if (answer.nudged && answer.nudgeWatched === false) {
-    return `             its tab was typed into, and Orca could not say whether it was taken: ${answer.nudgeUnseen} The message waits in its mailbox for its next check either way.`;
+    return `${head}its tab was typed into, and Orca could not say whether it was taken: ${answer.nudgeUnseen} The message waits in its mailbox for its next check either way.`;
   }
   if (answer.nudged && answer.nudgeUnseen !== undefined) {
-    return '             its tab was typed into, but Orca did not see the line start a turn: it may be queued behind the work in hand, or lost. The message waits in its mailbox for its next check either way.';
+    return `${head}its tab was typed into, but Orca did not see the line start a turn: it may be queued behind the work in hand, or lost. The message waits in its mailbox for its next check either way.`;
   }
-  if (answer.nudged) return '             its tab was told to look; it will read it when it is done with what it is doing.';
+  if (answer.nudged) return `${head}its tab was told to look; it will read it when it is done with what it is doing.`;
   if (answer.blocked !== undefined) {
     return `             its tab has something waiting to be answered (${answer.blocked}), so nothing was typed into it. Settle that, and the mail is there.`;
   }
@@ -1267,6 +1310,9 @@ function nudgeLine(answer, where) {
   return `             ${where} is not up, so nothing was typed anywhere: the message waits in its mailbox.`;
 }
 
+/** The watch before the kit's line, as the send says it (#509, ADR 0035). */
+const WATCH_SECONDS = WATCH_MS / 1000;
+
 /**
  * What there is to say about the work dir this command was given: one finding
  * when it leads out of the bot home, through `..` or a link or as a path
@@ -1301,9 +1347,13 @@ const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab
 const withLines = (retiredWith, session) => retiredWith.flatMap((gone) => [
   ...closedLines(gone.closed),
   `retired    ${gone.bot} ${gone.session}, a temporary session of ${gone.maker}'s, along with ${session}: off ${path.join('bots', gone.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+  ...unreadLines(gone.unread),
   ...leftLines(gone.promptsLeft),
 ]);
 
+/** The mail a retired session did not read, as far as the kit knows (#509). */
+const unreadLines = (unread, who = 'it') => (unread === undefined ? [] : [`unread     ${unreadWords(unread, who)}`]);
+
 /** What a retire could not remove, and how to: nothing reads these files now (#393). */
 const leftLines = (left = []) => left.flatMap(({ file, reason }) => [
   `left       ${file}: it could not be removed (${reason}). Nothing reads it now.`,

package/src/conversations.js

@@ -159,6 +159,43 @@ export function heldAsUserTurn(harness, file, text) {
   return held;
 }
 
+/**
+ * Where the harness keeps the conversation `id` of this bot home, and how long
+ * that record is now: `{ harness, file, size }`, so a later look reads only
+ * what was written after this moment. Undefined when there is no id, no
+ * record, or it cannot be read (#509).
+ */
+export function recordMark(harness, home, id) {
+  if (typeof id !== 'string' || id === '') return undefined;
+  try {
+    const file = harness === 'codex' ? codexRollout(id) : claudeTranscript(home, id);
+    if (file === undefined) return undefined;
+    const found = statSync(file);
+    return found.isFile() ? { harness, file, size: found.size } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether a turn of the user's written after `mark` holds `text` anywhere in
+ * it (#509). A record that cannot be read says no: not seeing a thing is not
+ * seeing it.
+ */
+export function userTurnSince(mark, text) {
+  if (mark === undefined || mark === null) return false;
+  let held = false;
+  try {
+    eachLine(mark.file, (line) => {
+      held = line !== undefined && userTexts(mark.harness, line).some((said) => said.includes(text));
+      return held;
+    }, { from: mark.size });
+  } catch {
+    return false;
+  }
+  return held;
+}
+
 /** The texts of one record line, when it is a turn of the user's. */
 function userTexts(harness, line) {
   let parsed;

package/src/health.js

@@ -26,7 +26,7 @@ import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bo
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
 import { bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
-import { frontOfTab, orcaDefaultArgs, projects, tabs, wordsOfProcess } from './orca.js';
+import { frontOfTab, orcaDefaultArgs, projects, runMissing, tabs, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
 import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
@@ -96,7 +96,7 @@ export function orcaSettingFindings() {
 const unreadableSettings = (where) => finding(
   'orca',
   where,
-  `The kit could not read Orca's own settings at ${where}, so it cannot say whether Orca adds default launch arguments of its own. When those carry a permission bypass, every session Orca launches, relaunches or resumes runs in that mode whatever approval level the kit asked for.`,
+  `The kit could not read Orca's own settings at ${where}, so it cannot say whether Orca adds default launch arguments of its own. It looks for them in profile-state.db in each Orca profile, or in orca-data.json for an older Orca. When those carry a permission bypass, every session Orca launches, relaunches or resumes runs in that mode whatever approval level the kit asked for.`,
 );
 
 /** Whether a line of arguments carries `flag` as a word of its own. */
@@ -387,6 +387,21 @@ function inOrca(bots, home, bot, setups, sessions) {
       found.push(finding('session', entry.tab, `${bot.name}'s session ${name} is in the book with tab ${entry.tab}, and Orca has no tab of that id: the tab was closed, or the machine was restarted. The conversation is in the book, and obk up opens a tab and brings it back.`, bot.name));
     }
 
+    // A Run Orca does not have, as when the book was written on another
+    // machine: mail sent to it is refused. The session's next start makes it
+    // a new one (#508).
+    if (typeof entry?.mailbox === 'string' && runMissing(entry.mailbox)) {
+      // The bot's unpause leaves a session paused on its own as it is, so a
+      // session under both marks needs both commands.
+      const unpause = `${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${bot.name}`;
+      const steps = [
+        ...(bot.paused === true ? [unpause] : []),
+        ...(bot.sessions.some((session) => session.name === name && session.paused === true) ? [`${unpause} --session ${name}`] : []),
+      ];
+      const fix = steps.length > 0 ? steps.join(', then ') : `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${name}`;
+      found.push(finding('session', bookFile(home), `${bot.name}'s session ${name} has the mailbox ${entry.mailbox} in the book, and Orca has no Run of that id: it was made by another Orca, as on another machine, so mail sent to it is refused. The session's next start makes it a new one: ${fix}`, bot.name));
+    }
+
     const unclaimed = (Array.isArray(entry?.unclaimed) ? entry.unclaimed : []).filter((id) => !helpers.has(id));
     if (unclaimed.length > 0) {
       found.push(finding('leftover', bookFile(home), `The book notes conversations under ${bot.name}'s session ${name} that no session of this bot claims: ${unclaimed.join(', ')}. They ran in this bot's folder, and the kit will not say whose they were. To give one back, write it into ${bookFile(home)} under ${name} as  session: <id>  and run obk up again.`, bot.name));

package/src/hooks.js

@@ -54,6 +54,20 @@ const SENT_MATCHER = 'SendMessage';
 export const sentCommand = (bots, bot, cli = ownCli()) =>
   `${shellWord(cli)} session sent --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
+/**
+ * Claude Code's third kit hook: at each turn end, it tells the session once
+ * about fleet mail the kit sent it that is still unread (#509, ADR 0035).
+ * Claude Code only: on Codex a new hook entry puts every session on "Hooks
+ * need review", and that waits for #511. It asks Orca only when the kit's hint
+ * holds mail for the session, and gives Orca at most ten seconds of its thirty.
+ */
+const MAIL_EVENT = 'Stop';
+const MAIL_TIMEOUT = 30;
+
+/** What the mail hook runs, by the kit's own path, as `hookCommand` does. */
+export const mailCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session mail --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+
 /**
  * Codex's second kit hook: after each command its shell tool ran, outside
  * Codex's sandbox, it decides the mail nudges a send in that command could not
@@ -250,7 +264,7 @@ function withKitHook(hooks, file, mine) {
 
 /** Each harness's kit hooks beside its session hook, as `toolHookOf` gives each. */
 const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
-  (harness === 'claude' ? ['sent'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
+  (harness === 'claude' ? ['sent', 'mail'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
 
 /**
  * One of the kit's hooks beside its session hook: Claude Code's after a native
@@ -259,6 +273,15 @@ const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
  * goes, how the kit knows its own, and what is lost without it.
  */
 function toolHookOf(kind, bots, bot, cli = ownCli()) {
+  if (kind === 'mail') {
+    return {
+      kind,
+      event: MAIL_EVENT,
+      pattern: KIT_MAIL,
+      mine: { type: 'command', command: mailCommand(bots, bot, cli), timeout: MAIL_TIMEOUT },
+      missing: 'a Claude session busy when fleet mail came is never told about it at the end of its turn, and nothing is typed into its tab either (#509)',
+    };
+  }
   if (kind === 'name') {
     return {
       kind,
@@ -355,6 +378,7 @@ const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
 const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const KIT_MAIL = new RegExp(String.raw`^(${WORD}) session mail --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 
 /** The program a bot made before the kit named itself by path runs. */

package/src/launch.js

@@ -51,7 +51,7 @@ export const harnessOf = (session, botHarness) => (set(session.harness) ? sessio
 
 /**
  * A session's name on Claude Code, which is also the address another Claude
- * session writes to (ADR 0030). It goes on the launch line as `-n`, and it is
+ * session writes to (ADR 0035). 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.
  *
@@ -224,7 +224,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
 
   if (harness === 'claude') {
     // The name is the address other Claude sessions write to, so it goes on
-    // every launch line, a resume included (ADR 0030).
+    // every launch line, a resume included (ADR 0035).
     if (address !== undefined) words.push('-n', address);
     // The context window rides on the model name: `sonnet[1m]`.
     if (set(session.model)) words.push('--model', set(session.context) ? `${session.model}[${session.context}]` : session.model);