@assuredloop/orca-bot-kit 0.36.0 → 0.37.0

package/README.md

@@ -474,6 +474,18 @@ It closes the session's tab — one tab, by its own handle — and opens a new o
 with the conversation the book holds, so the session comes back as itself. With
 no `--session` it does that for every session of the bot.
 
+Closing the old tab ends the harness there, and the background shells it ran
+end with it: a timer, a watch, a long build. So once a session whose tab the
+restart closed is back with its conversation, the kit types one line into its
+new tab. A session whose tab was already closed, or that starts fresh, gets no
+line. The line says that its background shells
+ended, that the kit cannot tell which ones ran or whether a scheduled job still
+runs, and that it should look at its scheduled jobs before it makes one again.
+It also asks the session to read its mail and do what it asks. The line goes in
+only when the tab shows no question, form or menu, within 20 seconds. The
+report says under each tab whether the line went in. When it did not, it says
+why, and you tell the session yourself.
+
 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:

package/package.json

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

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

@@ -127,6 +127,22 @@ the bots folder moves. `obk session add` and `obk session change` say so when a
 work dir leads out of the bot home; take that back to the user rather than
 past them.
 
+## How its sessions choose a subagent's model
+
+A session runs on one model of its own, but the model of each subagent it starts
+can be chosen task by task. A bot that should choose carries its way of working
+for this as a rule unit of its own. The bot can decide that way of working, or
+the user can. Write it in their words as a unit in `rules/` of the bots folder,
+name it in that bot's `rules:` list, and run `obk rules build`: every session
+of the bot then reads it in its `AGENTS.md`. Another bot can carry another
+rule, or none. A bot with none works as before, and each subagent runs on what
+the harness gives it.
+
+The rule acts where the harness lets a session choose a model for a subagent,
+as Claude Code's Agent tool does with its `model`. Where the harness does not,
+nothing changes. The kit names no model and no table from a task to a model:
+any model in the rule is the bot's or the user's choice.
+
 ## Offer a line-up rather than a blank page
 
 Someone making their first bots does not know what a good set looks like, so

package/skills/obk-finops/SKILL.md

@@ -119,6 +119,9 @@ A usual shape: high effort for the session that orchestrates, medium for the
 ones doing the work, and the top of the range only for deep read-only
 analysis.
 
+A bot can also carry its own rule on the model each subagent gets: see "How
+its sessions choose a subagent's model" in the obk-bot-building skill.
+
 ## When a model is not up to the work
 
 The signs are in the work, not in the answers. The same instruction given

package/src/cli.js

@@ -1177,6 +1177,10 @@ const commands = {
       answer,
       lines: [
         `${'sent'.padEnd(9)}  ${where.padEnd(24)}  ${answer.subject}`,
+        // Orca took it, and its answer named no letter (#730).
+        ...(answer.id === undefined
+          ? ['             Orca queued it, and its answer gave no message id for it.']
+          : []),
         ...(answer.file === undefined
           ? []
           : [`             it was too long to travel as itself, so it went as a file:  ${answer.file}`]),
@@ -1984,6 +1988,7 @@ function harnessLines(tab, bots) {
       `             Look at it:  ${lookAt(tab.terminal)}`,
       ...ANSWER_IT,
       ...promptLines(tab),
+      ...restartLines(tab),
     ];
   }
 
@@ -2005,7 +2010,7 @@ function harnessLines(tab, bots) {
       ...ANSWER_IT,
     ];
 
-  lines.push(...promptLines(tab), ...listLines(tab));
+  lines.push(...promptLines(tab), ...listLines(tab), ...restartLines(tab));
   if (tab.unclaimed !== undefined) lines.push(...unclaimedLines(tab, bots));
   return lines;
 }
@@ -2020,6 +2025,16 @@ function listLines(tab) {
   return [];
 }
 
+/**
+ * Whether a session `obk restart` resumed was typed the line that tells it what
+ * the restart ended (#726). When it was not, the caller is the one left to tell it.
+ */
+function restartLines(tab) {
+  if (tab.restartLine === true) return ['             it was typed one line that tells it what the restart ended: its background shells, and to look at its scheduled jobs and its mail.'];
+  if (tab.restartLine === false) return [`             it was not told what the restart ended (${tab.restartLineTrouble}): tell it yourself that its background shells ended, and to look at its scheduled jobs and its mail.`];
+  return [];
+}
+
 /**
  * Whether the session got its start prompt, as its own record has it (#274):
  * received, or not confirmed yet. Nothing for a session that was told nothing.

package/src/message.js

@@ -16,6 +16,7 @@
 // Escape a sender asks for with --interrupt. Orca gives no notice to a tab its
 // window has not loaded, so the send says when the receiver's is one (#579).
 
+import { randomUUID } from 'node:crypto';
 import { mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
@@ -24,7 +25,7 @@ import { setTimeout as pause } from 'node:timers/promises';
 import { MAILBOX_WAIT_MS, readBook, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
 import { harnessOf, isAddressOf, kitFolders, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
-import { ackMailbox, coordinatorOf, isRunning, listedOrphaned, loadInWindow, postMessage, pressEscape, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, useMailbox } from './orca.js';
+import { ackMailbox, coordinatorOf, isRunning, listedOrphaned, loadInWindow, postMessage, pressEscape, readMailbox, readsCarryRequest, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -203,19 +204,21 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
   const shown = await loaded(to);
   // The Escape goes first, so the turn has ended when the letter is in.
   const interrupted = interrupt ? interruptBusy(to) : {};
-  const message = postMessage({
+  const posted = postMessage({
     to: road.address,
     from: `run:${from.mailbox}`,
     subject,
     body: written.body,
     thread,
   });
+  // Orca took it: sent, whatever else its answer says or leaves out (#730).
+  const message = posted?.message;
 
   return {
     ...answer,
     sent: true,
-    id: message.id,
-    thread: message.thread_id ?? thread,
+    id: message?.id ?? posted?.messageId,
+    thread: message?.thread_id ?? thread,
     file: written.file,
     ...interrupted,
     ...shown,
@@ -356,15 +359,25 @@ function mailOf(bots, who, peek, until) {
       trouble: `${who.bot}/${who.session} is not up, and its mailbox is bound to no tab, so there is nothing to read it as. Its mail waits until its tab is back: \`up\` brings it back, or \`unpause\` when it is paused.`,
     };
   }
-  // Orca hands mail over a batch at a time and replays the oldest until it is
-  // acknowledged; the acknowledgement answers with the next batch. So a read
-  // takes every batch in turn, or newer mail waits behind an older one (#299).
-  //
-  // A batch is given back once it is acknowledged, and not before: one this
-  // check stops short of acknowledging is handed over again to the next.
+  // Orca hands mail over a batch at a time, so a read takes every batch in
+  // turn, or newer mail waits behind an older one (#299). Up to 1.4.245 it
+  // replays the oldest until it is acknowledged, and the acknowledgement
+  // answers with the next batch: a batch this check stops short of
+  // acknowledging is handed over again to the next. From 1.4.246 a read
+  // acknowledges the batch it hands over and says so (`deliveryAcknowledged`),
+  // and an acknowledgement answers with no batch, so the next is read again
+  // (#729; read in the 1.4.246 and 1.4.255 source). So a read that is not a
+  // peek is asked again, under the same request id, when Orca does not answer
+  // it in time (#735).
   const messages = [];
   const read = { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
-  let found = readMailbox(who.mailbox, { peek, handle }, timeLeft(until));
+  let found;
+  try {
+    found = peek ? readMailbox(who.mailbox, { peek, handle }, timeLeft(until)) : take(who.mailbox, handle, until, timeLeft(until));
+  } catch (error) {
+    if (peek || error.code !== TIMED_OUT) throw error;
+    return { ...read, trouble: `${error.message} Orca may have taken letters as read without the kit seeing them. Other mail waits for the next check.` };
+  }
   for (;;) {
     const batch = (found.messages ?? []).map((message) => asMessage(bots, message));
     if (peek || !found.deliveryId || batch.length === 0) {
@@ -372,6 +385,24 @@ function mailOf(bots, who, peek, until) {
       return read;
     }
     const wait = timeLeft(until, false);
+    if (found.deliveryAcknowledged === true) {
+      // Read already, so shown whatever comes after.
+      messages.push(...batch);
+      if (wait === undefined) {
+        return { ...read, trouble: `${who.bot}/${who.session} has more mail than one check reads in ${HOLD_MS / 1000} seconds, so it stopped there. The rest is still waiting: check again.` };
+      }
+      try {
+        found = take(who.mailbox, handle, until, wait);
+      } catch (error) {
+        // A read Orca did not answer about may have taken the next batch all
+        // the same, and taken is read: that batch is not handed over again.
+        if (error.code === TIMED_OUT) {
+          return { ...read, trouble: `${error.message} Orca may have taken the next letters as read without the kit seeing them. The mail shown above is read.` };
+        }
+        return { ...read, trouble: `${error.message} The mail shown above is read, and the rest waits for the next check.` };
+      }
+      continue;
+    }
     if (wait === undefined) {
       return { ...read, trouble: `${who.bot}/${who.session} has more mail than one check reads in ${HOLD_MS / 1000} seconds, so it stopped there. The rest is still waiting: check again.` };
     }
@@ -395,6 +426,31 @@ function mailOf(bots, who, peek, until) {
   }
 }
 
+/**
+ * Take the next batch of `mailbox`, read as `handle`, under a request id of
+ * its own, the first call given `options` (#735). Orca keeps the answer of a
+ * read under its id: the same read asked again with that id answers the same
+ * batch and takes nothing new, waits for the first if it is still running,
+ * and runs as new if the first never reached Orca (read in the 1.4.246 and
+ * 1.4.255 source). So a read Orca does not answer in time is asked again with
+ * the same id while the check's hold lasts, and a batch Orca took as read is
+ * shown once. No other call is asked again: a send, a bind or an ack Orca did
+ * not answer about is not sent twice (#734).
+ */
+function take(mailbox, handle, until, options) {
+  const request = randomUUID();
+  for (;;) {
+    try {
+      return readMailbox(mailbox, { handle, request }, options);
+    } catch (error) {
+      // A read that went without the id is not asked again (#734).
+      if (error.code !== TIMED_OUT || !readsCarryRequest()) throw error;
+      options = timeLeft(until, false);
+      if (options === undefined) throw error;
+    }
+  }
+}
+
 /**
  * How long a check holds the session's turn, all its Orca calls together. Well
  * inside the minute `up` waits for the turn before it writes a new tab, so a

package/src/orca.js

@@ -1021,6 +1021,36 @@ function panePid(ptyId, readMs) {
   return { pane };
 }
 
+/**
+ * The ids of the ptys Orca holds a process for, from `diagnostics memory`, as
+ * a set, or undefined when the kit cannot tell (#733). Each session there is a
+ * pty of Orca's own registry, which drops a pty once its process has ended
+ * (read in the 1.4.255 bundle; seen live, the pty went from the answer as its
+ * pane process and shell ended). An Orca that refuses the command, or an
+ * answer in another shape, cannot tell. Nor can an answer with no worktree at
+ * all: Orca answers a snapshot that failed with an empty list (read in the
+ * 1.4.255 bundle), and the kit cannot tell that from a machine with no
+ * terminal.
+ */
+export function livePtys() {
+  let worktrees;
+  try {
+    worktrees = orca(['diagnostics', 'memory']).worktrees;
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(worktrees) || worktrees.length === 0) return undefined;
+  const ids = new Set();
+  for (const worktree of worktrees) {
+    if (!Array.isArray(worktree?.sessions)) return undefined;
+    for (const session of worktree.sessions) {
+      if (typeof session?.sessionId !== 'string') return undefined;
+      ids.add(session.sessionId);
+    }
+  }
+  return ids;
+}
+
 /** The `lsof` and `stty` the kit asks, by their fixed paths, as `ps`. */
 export const LSOF = '/usr/sbin/lsof';
 const STTY = '/bin/stty';
@@ -1203,6 +1233,33 @@ export const pressEscape = (handle) =>
 /** Where Orca names the terminal a process runs in, in every pane it opens. */
 export const TERMINAL_ENV = 'ORCA_TERMINAL_HANDLE';
 
+/**
+ * One `orca orchestration` command, answered in full. From 1.4.246 Orca prints
+ * a short answer for each of these unless it is given `--full`, and the short
+ * one leaves out what the kit reads: a Run's `id` and `coordinator_handle`, a
+ * letter's `from_handle`, `created_at`, `thread_id`, `read` and `delivered_at`,
+ * and a sent letter's `message` (#729, #730; read in the 1.4.246 and 1.4.255
+ * source, and seen live on 1.4.255). Orca 1.4.245 and older do not know the
+ * flag on any of them but `inbox`, and refuse it before they do anything, as
+ * `deleteProject` finds with `--force` (#528). Only that refusal sends the
+ * command again without it: one Orca took, or did not answer, is never sent a
+ * second time. Once refused, the rest of this run sends no `--full`.
+ */
+function orchestration(args, options) {
+  if (fullKnown) {
+    try {
+      return orca([...args, '--full'], options);
+    } catch (error) {
+      if (error.code !== 'invalid_argument' || !error.reason?.startsWith('Unknown flag --full for command: ')) throw error;
+      fullKnown = false;
+    }
+  }
+  return orca(args, options);
+}
+
+/** Whether this Orca may know `--full` on its orchestration commands: false once it has refused it. */
+let fullKnown = true;
+
 /**
  * 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
@@ -1215,7 +1272,7 @@ export const TERMINAL_ENV = 'ORCA_TERMINAL_HANDLE';
  * tab and names no `--from` (tech notes, section 1; #317).
  */
 export const makeMailbox = (objective, options) =>
-  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`], options).run.id;
+  orchestration(['orchestration', 'run-create', '--objective', `obk ${objective}`], options).run.id;
 
 /**
  * Bind a mailbox to the terminal `handle`, which makes it the Run's coordinator
@@ -1226,7 +1283,7 @@ export const makeMailbox = (objective, options) =>
  * tab may name no other (#317).
  */
 export const useMailbox = (id, handle, options) =>
-  orca(['orchestration', 'run-use', '--id', id, ...(handle === undefined ? [] : ['--from', handle])], options).run;
+  orchestration(['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
@@ -1234,7 +1291,7 @@ export const useMailbox = (id, handle, options) =>
  * nothing, only `run-use` does (tech notes, section 1).
  */
 export const coordinatorOf = (id, options) =>
-  orca(['orchestration', 'run-show', '--id', id], options).run.coordinator_handle ?? undefined;
+  orchestration(['orchestration', 'run-show', '--id', id], options).run.coordinator_handle ?? undefined;
 
 /**
  * Whether this Orca has no Run of that id at all, as when the book was written
@@ -1245,29 +1302,64 @@ export const coordinatorOf = (id, options) =>
  */
 export function runMissing(id, options) {
   try {
-    orca(['orchestration', 'run-show', '--id', id], options);
+    orchestration(['orchestration', 'run-show', '--id', id], options);
     return false;
   } catch (error) {
     return error.code === 'run_not_found';
   }
 }
 
-/** Queue one message. `to` and `from` are mailboxes, written `run:<id>`. */
+/**
+ * Queue one message. `to` and `from` are mailboxes, written `run:<id>`. Orca's
+ * whole answer comes back: the letter it queued is its `message`, where Orca
+ * says so. Once Orca has taken it, an answer the kit cannot read is no reason
+ * to say it was not sent (#730).
+ */
 export function postMessage({ to, from, subject, body, type = 'status', thread }) {
   const args = ['orchestration', 'send', '--to', to, '--subject', subject, '--body', body, '--type', type];
   if (from !== undefined) args.push('--from', from);
   if (thread !== undefined) args.push('--thread-id', thread);
-  return orca(args).message;
+  return orchestration(args);
 }
 
 /**
  * What is waiting in a mailbox: the oldest batch that has not been
- * acknowledged, or, peeking, whatever is unread without touching it. Read as
+ * acknowledged, or, peeking, whatever is unread without touching it. From
+ * Orca 1.4.246 a read that is not a peek acknowledges the batch it hands over,
+ * and says so with `deliveryAcknowledged: true` (#729). Read as
  * the terminal `handle` when one is given, which is how a read works from a tab
  * bound to another Run; otherwise as this process's own terminal.
+ *
+ * A read given a `request` id carries it as `--retry-request`: Orca keeps its
+ * answer under that id, and the same read asked again with it answers the
+ * same batch and takes nothing new (#735). An Orca that refuses the flag as
+ * unknown did nothing, and is asked again without it, as for `--full`.
  */
-export const readMailbox = (id, { peek = false, handle } = {}, options) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])], options);
+export function readMailbox(id, { peek = false, handle, request } = {}, options) {
+  const args = ['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])];
+  if (request !== undefined && retryKnown) {
+    try {
+      return orchestration([...args, '--retry-request', request], options);
+    } catch (error) {
+      if (error.code !== 'invalid_argument' || error.reason !== RETRY_UNKNOWN) throw error;
+      retryKnown = false;
+    }
+  }
+  return orchestration(args, options);
+}
+
+/** Orca's own words when its CLI does not know `--retry-request` on `check`: nothing was done. */
+const RETRY_UNKNOWN = 'Unknown flag --retry-request for command: orchestration check';
+
+/** Whether this Orca may know `--retry-request` on `check`: false once it has refused it. */
+let retryKnown = true;
+
+/**
+ * Whether a read given a request id still carries it. Once Orca has refused
+ * the flag, a read goes without it, and a read with no id is never asked again
+ * after a time-out: it would take another batch, not answer the first (#735).
+ */
+export const readsCarryRequest = () => retryKnown;
 
 /**
  * The newest `limit` messages in a mailbox, newest first, with every column
@@ -1278,11 +1370,14 @@ export const readMailbox = (id, { peek = false, handle } = {}, options) =>
  * cap in Orca, so the answer is taken whatever its size.
  */
 export const mailIn = (id, limit) =>
-  orca(['orchestration', 'inbox', '--terminal', `run:${id}`, '--limit', String(limit)], { whole: true }).messages ?? [];
+  orchestration(['orchestration', 'inbox', '--terminal', `run:${id}`, '--limit', String(limit)], { whole: true }).messages ?? [];
 
-/** Say a batch has been read. Orca answers with the batch after it. */
+/**
+ * Say a batch has been read. Up to Orca 1.4.245 Orca answers with the batch
+ * after it; from 1.4.246 with no batch, since its read acknowledged it (#729).
+ */
 export const ackMailbox = (id, delivery, handle, options) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery], options);
+  orchestration(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery], options);
 
 /** The reader of a `check`: the terminal named, or this process's own. */
 const as = (handle) => (handle === undefined ? [] : ['--terminal', handle]);

package/src/restart.js

@@ -34,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, closeTerminal, findProject, frontOfTab, orcaCli, tabs } from './orca.js';
+import { closeTab, closeTerminal, findProject, frontOfTab, livePtys, orcaCli, tabs } from './orca.js';
 import { botsNamed, bringUp, prepareBots, sessionsOf } from './up.js';
 
 /**
@@ -69,7 +69,9 @@ export async function restartSessions(bots, { bot: name, session: onlySession }
 
   const going = tabsToClose(bots, name, home, sessions.filter((session) => session.paused !== true), { quit: true });
   const closed = await closeTabs(home, going, bots, name, commandLine('restart', bots, name, onlySession));
-  return { closed, ...(await bringUp(bots, { bot: name, session: onlySession })) };
+  // The sessions whose tabs this closed are the ones the restart ended
+  // something of, and the ones told so once they are back (#726).
+  return { closed, ...(await bringUp(bots, { bot: name, session: onlySession, restarted: new Set(closed.map((tab) => tab.name)) })) };
 }
 
 /**
@@ -114,9 +116,11 @@ export function tabsToClose(bots, name, home, sessions, { keepless = false, quit
  * Close the tabs `tabsToClose` gave, one at a time by their own handles, and
  * wait until Orca's listing agrees they are gone. Returns one entry per tab.
  * `again` is the command that asked, as the user would run it again: what to do
- * once a tab Orca would not close has been closed by hand.
+ * once a tab Orca would not close has been closed by hand. With `retiring`, the
+ * caller starts no harness in the tabs' place, so a tab Orca still lists after
+ * the wait may count as gone once its process is shown to have ended (#733).
  */
-export async function closeTabs(home, going, bots, name, again) {
+export async function closeTabs(home, going, bots, name, again, { retiring = false } = {}) {
   const closed = [];
   for (const { name: session, tab } of going) {
     try {
@@ -125,12 +129,12 @@ export async function closeTabs(home, going, bots, name, again) {
       // A tab that would not close still holds its session, so nothing is
       // opened after this: two harnesses on one conversation is worse than a
       // restart that did not happen.
-      throw new Error(alsoClosed(error.message, closed, bots, name));
+      throw new Error(alsoClosed(error.message, closed, bots, name, retiring ? again : undefined));
     }
     closed.push({ bot: name, name: session, tabId: tab.tabId, terminal: tab.handle });
   }
 
-  await gone(home, closed, bots, name);
+  await gone(home, closed, bots, name, retiring ? { again, ptys: new Map(going.map(({ tab }) => [tab.tabId, tab.ptyId])) } : undefined);
   return closed;
 }
 
@@ -185,8 +189,21 @@ const ASK_MS = 100;
  * A listing that never catches up is not something the kit can put right, so it
  * stops and says which tab it is waiting on. The conversation is in the book,
  * which is the way back to it.
+ *
+ * A retire, given as `retire: { again, ptys }`, starts nothing in the tabs'
+ * place, and what it must not leave behind is a live harness (#733). Orca
+ * 1.4.255 can go on listing a closed tab for minutes, `connected: false`,
+ * after its process has ended: a pane its window still holds (tech notes,
+ * section 1). That row alone does not prove the process ended, since a pane
+ * can say it is not connected while its pty is live, and so Orca's own list
+ * of live ptys is read too. Once the wait is over, a tab of the retire's
+ * counts as gone when every row Orca lists for it says `connected: false`
+ * with the pty the kit closed, and Orca holds no process for that pty.
+ * Anything the kit cannot read is "cannot tell", and the retire stops as
+ * before, with the retire to run again: the user wants the session gone, not
+ * back.
  */
-async function gone(home, closed, bots, bot) {
+async function gone(home, closed, bots, bot, retire) {
   // Nothing closed is nothing to wait for, and a bot that has never been up has
   // no Orca project to ask: Orca refuses the listing (tech notes, section 1).
   if (closed.length === 0) return;
@@ -194,18 +211,40 @@ async function gone(home, closed, bots, bot) {
   const ids = closed.map((tab) => tab.tabId);
 
   for (;;) {
-    const there = new Set(tabs(home).map((tab) => tab.tabId));
-    const left = ids.filter((id) => there.has(id));
+    const listed = tabs(home);
+    const there = new Set(listed.map((tab) => tab.tabId));
+    let left = ids.filter((id) => there.has(id));
     if (left.length === 0) return;
 
     if (Date.now() >= until) {
       const one = left.length === 1;
-      throw new Error(`Orca answered the close for ${one ? 'this tab' : 'these tabs'} and is still listing ${one ? 'it' : 'them'} ${SETTLED_MS / 1000} seconds later: ${left.join(', ')}. Nothing was opened in ${one ? 'its' : 'their'} place, because a tab that is on the way out is not a tab to start a harness in. The conversations are in the book: ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot} brings them back once Orca has caught up.`);
+      if (retire === undefined) {
+        throw new Error(`Orca answered the close for ${one ? 'this tab' : 'these tabs'} and is still listing ${one ? 'it' : 'them'} ${SETTLED_MS / 1000} seconds later: ${left.join(', ')}. Nothing was opened in ${one ? 'its' : 'their'} place, because a tab that is on the way out is not a tab to start a harness in. The conversations are in the book: ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot} brings them back once Orca has caught up.`);
+      }
+      left = stillRunning(listed, left, retire.ptys);
+      if (left.length === 0) return;
+      const few = left.length === 1;
+      throw new Error(`Orca answered the close for ${few ? 'this tab' : 'these tabs'} and is still listing ${few ? 'it' : 'them'} ${SETTLED_MS / 1000} seconds later, and the kit cannot tell that ${few ? 'its harness has' : 'their harnesses have'} stopped: ${left.join(', ')}. The retire stopped there. Once Orca has caught up, run the same retire again: ${retire.again}`);
     }
     await pause(ASK_MS);
   }
 }
 
+/**
+ * Of the tab ids `left`, the ones Orca's listing `listed` does not show to have
+ * ended: a tab ended when each row for it says `connected: false` with the pty
+ * `ptys` gives it, and `livePtys` reads and lacks that pty.
+ */
+function stillRunning(listed, left, ptys) {
+  const live = livePtys();
+  if (live === undefined) return left;
+  return left.filter((id) => {
+    const pty = ptys.get(id);
+    const ended = (tab) => tab.connected === false && tab.ptyId === pty;
+    return typeof pty !== 'string' || live.has(pty) || !listed.filter((tab) => tab.tabId === id).every(ended);
+  });
+}
+
 /**
  * A session the kit will not close a tab on: it is live, and the book does not
  * say which conversation is in it — a Codex hooks file trusted too late is
@@ -225,10 +264,17 @@ function cannotComeBack(bots, bot, name, was) {
   ].join(' ');
 }
 
-/** What a failed close owes whoever is reading: the tabs that went before it. */
-function alsoClosed(why, closed, bots, bot) {
+/**
+ * What a failed close owes whoever is reading: the tabs that went before it.
+ * For a retire, given as the command to run again, the way on is that retire,
+ * not `up`: the user wants those sessions gone, not back (#733).
+ */
+function alsoClosed(why, closed, bots, bot, retireAgain) {
   if (closed.length === 0) return why;
 
   const one = closed.length === 1;
+  if (retireAgain !== undefined) {
+    return `${why} ${closed.map((tab) => tab.name).join(', ')} ${one ? 'was' : 'were'} closed before it, and nothing more was retired. Once that tab can be closed, run the same retire again: ${retireAgain}`;
+  }
   return `${why} ${closed.map((tab) => tab.name).join(', ')} ${one ? 'was' : 'were'} closed before it and nothing was opened in ${one ? 'its' : 'their'} place: ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot} brings ${one ? 'it' : 'them'} back with ${one ? 'its' : 'their'} conversation.`;
 }

package/src/retire.js

@@ -45,9 +45,11 @@ export const retiredDir = (bots) => path.join(bots, 'retired');
  * removed, and `processes` when it has a work dir: what `stopProcesses`
  * stopped and left of what it started there (#537). `retiredWith` holds one
  * `{ bot, session, maker, closed }` for each session that went with it,
- * deepest first, with its own `promptsLeft` and `processes`.
+ * deepest first, with its own `promptsLeft` and `processes`. `again` is the
+ * command the user ran, as they would run it again: what a refusal names, for
+ * this session and each that goes with it.
  */
-export async function retireSession(bots, { bot, session }) {
+export async function retireSession(bots, { bot, session }, again = commandLine('retire', bots, bot, session)) {
   const home = fleetMember(bots, bot, 'retire', session);
   const known = readBot(home, bot);
   const sessions = sessionsOf(known, session);
@@ -59,11 +61,11 @@ export async function retireSession(bots, { bot, session }) {
   let processes;
   try {
     for (const { name } of made) {
-      const { retiredWith: theirs, ...gone } = await retireSession(bots, { bot, session: name });
+      const { retiredWith: theirs, ...gone } = await retireSession(bots, { bot, session: name }, again);
       retiredWith.push(...theirs, { ...gone, maker: session });
     }
 
-    closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, commandLine('retire', bots, bot, session));
+    closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, again, { retiring: true });
     // Only once its tab is closed: its harness starts nothing more.
     const dir = workDirOf(sessions[0], home);
     if (dir !== undefined) processes = await stopProcesses([{ session, dir }]);
@@ -137,7 +139,7 @@ export async function retireBot(bots, { bot }) {
   // taken away with one of them still open. `closeTabs` waits until Orca agrees
   // they are gone.
   const booked = Object.keys(readBook(home).sessions).map((name) => ({ name }));
-  const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot, commandLine('retire', bots, bot));
+  const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot, commandLine('retire', bots, bot), { retiring: true });
   // Once their tabs are closed, and before the folder moves (#537).
   const dirs = known.sessions.flatMap((session) => {
     const dir = workDirOf(session, home);

package/src/temp.js

@@ -367,7 +367,8 @@ const promptLeft = (why, written, left) =>
 export async function retireTemp(bots, { tab, name }) {
   const caller = callerIn(bots, tab, 'retire');
   ownTemp(caller, name, 'retire', 'Nothing was retired.');
-  return { ...(await retireSession(bots, { bot: caller.bot, session: name })), maker: caller.session };
+  const again = `${shellWord(ownCli())} temp retire --bots ${shellWord(bots)} --name ${name}`;
+  return { ...(await retireSession(bots, { bot: caller.bot, session: name }, again)), maker: caller.session };
 }
 
 /**

package/src/up.js

@@ -49,7 +49,7 @@ const SECOND_LOOK_MS = 2000;
  * one bot and `session` one of its sessions, for a caller that wants one thing
  * back rather than the fleet.
  */
-export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {}) {
+export async function bringUp(bots, { bot: onlyBot, session: onlySession, restarted } = {}) {
   const named = botsNamed(bots, onlyBot);
   if (onlySession !== undefined && onlyBot === undefined) {
     throw new Error('--session needs --bot: say which bot the session belongs to.');
@@ -72,7 +72,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
     for (const session of sessionsOf(bot, onlySession)) {
       if (session.paused === true) paused.push({ bot: bot.name, session: session.name });
     }
-    const up = await bringUpBot(bots, home, bot, onlySession);
+    const up = await bringUpBot(bots, home, bot, onlySession, restarted);
     report.push(...up.tabs);
     if (up.project !== undefined) projects.push(up.project);
   }
@@ -230,7 +230,7 @@ export function sessionsOf(bot, onlySession) {
   return named;
 }
 
-async function bringUpBot(bots, home, bot, onlySession) {
+async function bringUpBot(bots, home, bot, onlySession, restarted) {
   const name = bot.name;
   const title = displayName(name);
   const sessions = awake(sessionsOf(bot, onlySession));
@@ -250,7 +250,7 @@ async function bringUpBot(bots, home, bot, onlySession) {
 
   const live = new Map(tabs(home).map((tab) => [tab.tabId, tab]));
   const report = [];
-  for (const session of sessions) report.push(await bringUpSession(bots, home, live, session, bot, title));
+  for (const session of sessions) report.push(await bringUpSession(bots, home, live, session, bot, title, restarted?.has(session.name) === true));
 
   // The ops tab, and the whole of what the kit knows about it: Bot Father's
   // project needs one tab that is not a session, for work across the fleet. Any
@@ -274,7 +274,7 @@ async function bringUpBot(bots, home, bot, onlySession) {
   return { tabs: report, project: change === undefined && windowTrouble === undefined ? undefined : project };
 }
 
-async function bringUpSession(bots, home, live, session, bot, title) {
+async function bringUpSession(bots, home, live, session, bot, title, restarted) {
   const harness = harnessOf(session, bot.harness);
   const book = readBook(home);
   const was = book.sessions[session.name];
@@ -431,11 +431,20 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     ? undefined
     : await heldInRecord(home, session.name, harness, launch.prompt, { launched, running: tui.running === true });
 
+  // A session whose tab `obk restart` closed lost the background shells its
+  // harness ran there, and nothing else tells it (#726). So once it is resumed
+  // it is typed one line that says so, through the same gate, whatever its
+  // harness. For Codex that line is its first turn too, so it takes the place
+  // of the list line below.
+  const told = !restarted || launch.resume === undefined ? undefined
+    : tui.running === true ? await typeListLine(home, session.name, made.tabId, { line: restartLine(bots) })
+    : { typed: false, why: 'its harness did not come up in the new tab' };
+
   // A Codex session resumed here is not among Orca's agents until its first
   // turn: Codex fires its SessionStart then and not at the resume, seen live on
   // 0.157.1 (#226). So it is given one line, through the same gate as a mail
   // notice, which the owner allowed. A fresh start's first turn is its prompt.
-  const list = harness === 'codex' && launch.resume !== undefined && tui.running === true
+  const list = told === undefined && harness === 'codex' && launch.resume !== undefined && tui.running === true
     ? await typeListLine(home, session.name, made.tabId, { line: listLine(bots) })
     : undefined;
 
@@ -456,6 +465,8 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     unclaimed: which.unclaimed,
     listLine: list?.typed,
     listLineTrouble: list?.why,
+    restartLine: told?.typed,
+    restartLineTrouble: told?.why,
   });
 }
 
@@ -516,6 +527,25 @@ const listLine = (bots) => 'obk: this session was resumed in a new tab, and the
   + ` Read your mail with \`${shellWord(ownCli())} message check --bots ${shellWord(bots)}\`, and do what it asks.`
   + ' That includes mail you read just before this line. If there is none, reply "ok".';
 
+/**
+ * The line a session is typed once `obk restart` has resumed it in a new tab,
+ * in the architect's ruling (#726). It says only what the kit knows: the old
+ * tab's harness ended, and its background shells with it. The kit cannot tell
+ * which shells ran, nor whether a scheduled job survived (one was seen to), so
+ * the session looks before it makes a job again. The mail part is the list
+ * line's as #709 left it, but for its last sentence: "If nothing needs doing"
+ * where the list line says "If there is none". This line also asks the session
+ * to start its shells again, and a session with no mail must not reply "ok"
+ * and stop there (the architect's ruling on PR #731).
+ */
+const restartLine = (bots) => 'obk: obk restart closed this session\'s old tab and resumed the conversation in this new one.'
+  + ' Closing the old tab ended the harness there, and the background shells it ran ended with it.'
+  + ' The kit cannot tell which shells ran, or whether a scheduled job of the harness still runs.'
+  + ' Look at the harness\'s scheduled jobs before you make one again, so that only one of each runs.'
+  + ' Start again the shells you still need.'
+  + ` Read your mail with \`${shellWord(ownCli())} message check --bots ${shellWord(bots)}\`, and do what it asks.`
+  + ' That includes mail you read just before this line. If nothing needs doing, reply "ok".';
+
 /**
  * How long a resumed Codex tab is given to be one the kit may type into: live,
  * Orca named the agent 7 to 11 s after the restart (#226), and the gate waits
@@ -969,7 +999,7 @@ export const promptPath = (bots, bot, session) =>
 export const oldPromptPath = (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, harnessChanged, ranOn, unclaimed, noMailbox = false, listLine, listLineTrouble, notLaunched }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, harnessChanged, ranOn, unclaimed, noMailbox = false, listLine, listLineTrouble, restartLine, restartLineTrouble, notLaunched }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // A tab whose shell was not ready for the launch line, and why: nothing was
   // typed into it (#498).
@@ -981,6 +1011,8 @@ function entry(tab, { bot, name, created, running = false, blockedReason, prompt
   // and why not when it was not (#226).
   if (listLine !== undefined) made.listLine = listLine;
   if (listLineTrouble !== undefined) made.listLineTrouble = listLineTrouble;
+  if (restartLine !== undefined) made.restartLine = restartLine;
+  if (restartLineTrouble !== undefined) made.restartLineTrouble = restartLineTrouble;
   // The id the book held that had no conversation behind it, now in the history.
   if (noConversation !== undefined) made.noConversation = noConversation;
   // The id the book held that ran on another harness, the one this session