@assuredloop/orca-bot-kit 0.2.0 → 0.3.0

package/src/hooks.js

@@ -1,4 +1,4 @@
-// The kit's own hook, in the bot's folder and nowhere else (ADR 0010).
+// The kit's own hook, in the bot's folder and nowhere else (ADR 0020).
 //
 // 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
@@ -15,7 +15,7 @@ import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
 import { leadsOutside } from './bot.js';
-import { shellWord } from './launch.js';
+import { ownCli, shellWord } from './launch.js';
 
 /** Where each harness reads a project's hooks, inside the bot home. */
 const HOOK_FILE = { claude: '.claude/settings.json', codex: '.codex/hooks.json' };
@@ -31,17 +31,16 @@ const EVENT = 'SessionStart';
 /** How long the harness gives the hook before it goes on without it. */
 const TIMEOUT = 10;
 
-/** The kit's own hook among whatever else the user keeps in the file. */
-const KIT_COMMAND = 'obk session record';
-
 /**
- * What the hook runs. `|| true` and a quiet stderr because a hook must never
- * disturb the session it fires in (ADR 0010): a kit that is not installed, or a
- * book that cannot be written, leaves the session alone and the health check
- * finds the stale book later.
+ * 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
+ * that cannot be written, leaves the session alone and the health check finds
+ * the stale book later.
  */
-export const hookCommand = (bots, bot) =>
-  `${KIT_COMMAND} --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+export const hookCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session record --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
 /**
  * Make sure the bot at `home` has the kit's SessionStart hook for `harness`.
@@ -81,7 +80,7 @@ export function installHook(home, harness, { bots, bot }) {
  *
  * The same question `installHook` asks, without the writing. It matters more
  * than it looks: the hook is the whole of how the book learns which
- * conversation a session is running as (ADR 0002), and when it is not there
+ * conversation a session is running as (ADR 0012), and when it is not there
  * nothing else says so — the book simply stops being true.
  */
 export function hookTrouble(home, harness, { bots, bot }) {
@@ -95,7 +94,22 @@ export function hookTrouble(home, harness, { bots, bot }) {
   let settings;
   try {
     settings = readSettings(file);
-    wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot), timeout: TIMEOUT }) };
+    // The hook in the file is judged by what it runs, not by whether this is
+    // the install that wrote it. A bot made before the kit named itself by path
+    // runs the bare `obk`, and one another install wrote runs that install: both
+    // still reach a kit, and the next `obk up` writes this one's. So the line is
+    // checked against the program already in it, and only one that names a CLI
+    // that is not there any more is wrong — `|| true` would keep that quiet, and
+    // the book would stop being true with nothing to say why.
+    const running = kitProgramIn(settings);
+    if (running !== undefined && running !== BARE && !existsSync(running)) {
+      return {
+        where: file,
+        says: `${file} holds the kit's session hook, but it runs ${running}, which is not there any more. ${stale} obk up puts back one that runs the kit you have.`,
+      };
+    }
+    const program = running ?? ownCli();
+    wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
   } catch (error) {
     return { where: file, says: `${error.message} ${stale}` };
   }
@@ -110,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 0010); through a link like that it would be writing the
+ * nowhere else (ADR 0020); 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) {
@@ -169,14 +183,55 @@ function withKitHook(hooks, file, mine) {
 /**
  * The kit's own hook entry, wherever it sits and whatever sits beside it: a
  * command of exactly the shape `hookCommand` writes, for any bots folder and
- * bot, so an entry written before the folder moved is still the kit's. A line
- * of the user's that only mentions the command is theirs (PRD 6.5).
+ * bot, run by a kit — the bare `obk` a bot made before #220 still has, this
+ * install, or another — so an entry written before the folder moved or the kit
+ * changed is still the kit's, and is rewritten in place rather than joined by a
+ * second. A line of the user's that only mentions the command, or runs it with
+ * a program of their own, is theirs (PRD 6.5).
  */
-const isKitHook = (hook) => typeof hook?.command === 'string' && KIT_HOOK.test(hook.command);
+const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
 
 /** One word as `shellWord` writes it: bare, or single-quoted with `'\''` inside. */
 const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
-const KIT_HOOK = new RegExp(String.raw`^${KIT_COMMAND} --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+
+/** The program a bot made before the kit named itself by path runs. */
+const BARE = 'obk';
+
+/**
+ * Whether a program is a kit: the bare name, an install's `obk` wherever it
+ * lives, or a checkout's `src/cli.js` — the only two ways `ownCli` is reached.
+ */
+const isKitCli = (program) => path.basename(program) === BARE || program.endsWith('/src/cli.js');
+
+/** The program a hook command of the kit's runs, unquoted, or undefined for any other command. */
+function kitProgramOf(command) {
+  const found = typeof command === 'string' ? KIT_HOOK.exec(command) : null;
+  if (found === null) return undefined;
+  const program = unquoted(found[1]);
+  return isKitCli(program) ? program : undefined;
+}
+
+/**
+ * What the kit's hook in these settings runs, as a path or the bare name, or
+ * undefined when there is none. Read back out of its shell quoting, so it can be
+ * looked for on disk.
+ */
+function kitProgramIn(settings) {
+  for (const groups of Object.values(settings.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const hook of Array.isArray(group?.hooks) ? group.hooks : []) {
+        const program = kitProgramOf(hook?.command);
+        if (program !== undefined) return program;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** A word as `shellWord` wrote it, read back to what it stands for. */
+const unquoted = (word) => (word.startsWith("'") ? word.slice(1, -1).replaceAll(`'\\''`, "'") : word);
 
 /**
  * What the file says, or nothing when there is no file yet. A file the kit

package/src/init.js

@@ -1,6 +1,6 @@
 // Creates the user's bots folder: their own git repo, seeded with the files the
 // kit reads, and Bot Father. The kit puts none of its own code in here — kit
-// skills are linked from the installed package (ADR 0004).
+// skills are linked from the installed package (ADR 0014).
 //
 // Seeding only ever adds what is missing. The user edits these files, by hand
 // or through Bot Father, so a re-run must never write over them.
@@ -15,7 +15,7 @@ import { RECORD, SKILL_DIRS } from './skills.js';
 
 /**
  * What the kit makes on this machine, and what the repo therefore does not
- * carry (ADR 0004, PRD 6.3).
+ * carry (ADR 0014, PRD 6.3).
  *
  * A bot's skills are symlinks into wherever the kit and the user's skill
  * sources are installed on the machine that made them, so a clone somewhere
@@ -126,7 +126,7 @@ const MANAGEMENT_SKILLS = ['obk-bot-building', 'obk-finops', 'obk-fleet-review',
 const BOT_FATHER_YAML = 'bots/bot-father/bot.yaml';
 
 /** The management session every Bot Father has: the tab you talk to it in. */
-const DAILY_SESSION = 'daily';
+export const DAILY_SESSION = 'daily';
 
 const seeds = (harness) => [
   ['.gitignore', GITIGNORE],

package/src/launch.js

@@ -1,7 +1,7 @@
 // What a session is started with: the one line typed into its tab, which brings
 // the harness up and carries the session's start prompt with it.
 //
-// The flag mapping is PRD 6.4 and ADR 0005, re-checked against the installed
+// The flag mapping is PRD 6.4 and ADR 0015, re-checked against the installed
 // CLIs (Claude Code 2.1.278, Codex 0.155.1). Every session is given its
 // approval level explicitly, so a user's own global harness defaults cannot
 // leak into a bot. The kit names no model: a session that sets none gets the
@@ -12,6 +12,7 @@
 
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /** The approval levels, and what each one is called on each harness. */
 const APPROVAL = {
@@ -38,7 +39,7 @@ export const bypassFlags = (harness) => APPROVAL[harness]['dangerously-skip'];
 
 export const HARNESSES = Object.keys(APPROVAL);
 
-/** The level a session that names none runs at (ADR 0005). */
+/** The level a session that names none runs at (ADR 0015). */
 export const DEFAULT_APPROVAL = 'auto';
 
 /** A setting the user left out. An empty string is one too: it means the harness's own. */
@@ -49,7 +50,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 0008). It goes on the launch line as `-n`, and it is
+ * 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.
  */
@@ -161,7 +162,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 0008).
+    // every launch line, a resume included (ADR 0018).
     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);
@@ -174,7 +175,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     if (set(session.effort)) words.push('-c', `model_reasoning_effort=${session.effort}`);
     if (set(session.context)) words.push('-c', `model_context_window=${session.context}`);
     // In Codex's auto mode the sandbox lets it write in the folder it was
-    // started in, and nowhere else (ADR 0005), so a work dir outside the bot
+    // started in, and nowhere else (ADR 0015), so a work dir outside the bot
     // home has to be named.
     if (workDir !== undefined && !inside(home, workDir)) words.push('--add-dir', workDir);
   }
@@ -184,6 +185,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     // starts — the shell's child — from anything the session starts later inside
     // the tab. `$$` is the shell's, and it is not quoted for that reason.
     `${SHELL_ENV}=$$`,
+    `${CLI_ENV}=${quoted(ownCli())}`,
     ...words.map(quoted),
     ...extraWords(session.extra_args),
     ...resumeWords(harness, resume),
@@ -274,3 +276,24 @@ 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;
+
+/**
+ * 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
+ * whatever PATH says, and PATH is not the kit's to decide (#220). A user's
+ * install is started through npm's bin link, and the link is kept rather than
+ * resolved, so the path survives an upgrade of the package; a system test that
+ * runs a checkout's `src/cli.js` gets that checkout. What an environment
+ * variable claims is not asked: the kit says who it is from how it was started.
+ */
+export const ownCli = () => (process.argv[1] === undefined
+  // Nothing started as a script, as with `node -e`: the kit's own entry file.
+  ? fileURLToPath(new URL('./cli.js', import.meta.url))
+  : path.resolve(process.argv[1]));
+
+/**
+ * Where the launch line hands the session the CLI that started it, so a bot's
+ * own commands can call the same one. A plain variable, because a harness's
+ * shell keeps those where it rearranges PATH (#220).
+ */
+export const CLI_ENV = 'OBK_CLI';

package/src/message.js

@@ -1,4 +1,4 @@
-// `obk message`: one session writing to another (PRD 6.9, ADR 0008).
+// `obk message`: one session writing to another (PRD 6.9, ADR 0018).
 //
 // Two roads, and the bot never picks. Claude to Claude in the same approval
 // class is the harness's own messaging, which no command line can send for it —
@@ -20,8 +20,8 @@ import path from 'node:path';
 
 import { readBook } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
-import { harnessOf, reachesMail } from './launch.js';
-import { ackMailbox, postMessage, readMailbox, tabs, tuiInTab, typeIntoTab, useMailbox } from './orca.js';
+import { harnessOf, ownCli, reachesMail, shellWord } from './launch.js';
+import { ackMailbox, harnessInTab, postMessage, readMailbox, tabs, typeIntoTab, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -147,7 +147,7 @@ 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:  obk up --bots ${bots} --bot ${from.bot}`,
+      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)}`,
     };
   }
 
@@ -192,10 +192,15 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
     };
   }
 
-  useMailbox(who.mailbox);
-  const found = readMailbox(who.mailbox, { peek });
+  // Read as the session's own tab, wherever this check was typed. Binding the
+  // tab that asked would hand it the session's mailbox, and Orca's notice for
+  // every message after (issue #228). A session with no live tab is read as
+  // this process's own terminal, as it always was.
+  const handle = who.tab === undefined ? undefined : tabs(who.home).find((tab) => tab.tabId === who.tab)?.handle;
+  useMailbox(who.mailbox, handle);
+  const found = readMailbox(who.mailbox, { peek, handle });
   const messages = (found.messages ?? []).map((message) => asMessage(bots, message));
-  if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId);
+  if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId, handle);
 
   return { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
 }
@@ -295,9 +300,10 @@ const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '
  *
  * Nothing in the mailbox reaches a running harness by itself, and a typed line
  * is taken as the next turn by a busy session rather than cutting into the one
- * it is having. A tab with no TUI in it is not typed into at all — there is
+ * it is having. A tab with no harness in it is not typed into at all — there is
  * nobody there to read it, and the message waits in the mailbox until the
- * session is up. A tab the book does not hold is never typed into on any road.
+ * session is up. Nor is one the kit cannot tell about. A tab the book does not
+ * hold is never typed into on any road.
  *
  * Nor is a tab with something on screen waiting to be answered. A line typed
  * into one of those is not a message: it is an answer to whatever question is
@@ -318,13 +324,29 @@ function nudge(to, from, subject) {
     const live = tabs(to.home).find((tab) => tab.tabId === to.tab);
     if (live === undefined) return { nudged: false };
 
-    const tui = tuiInTab(live.handle, LOOK_MS);
-    if (!tui.running) return { nudged: false };
-    if (tui.blockedReason !== undefined) return { nudged: false, blocked: tui.blockedReason };
+    const seen = harnessInTab(live.handle, LOOK_MS);
+    if (seen.blockedReason !== undefined) return { nudged: false, blocked: seen.blockedReason };
+    // The shell in front is a tab with no harness, whatever a stale
+    // `agentIdentity` says.
+    if (seen.front === 'shell') return { nudged: false };
+    // Not knowing is not a reason to type: a line that lands in a shell is run
+    // there, with the sender's subject in it. The program in front has to be
+    // the agent Orca names. With no name it may be a harness a few seconds
+    // into its launch; under another name it may be a pager started after the
+    // harness quit, under an identity Orca has not let go of (tech notes,
+    // section 1). A harness run through a wrapper such as `node` lands here
+    // too, until #261.
+    if (seen.front === undefined || seen.agent === undefined || seen.command !== seen.agent) {
+      const why = seen.front === undefined
+        ? seen.unreadable
+        : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
+      return { nudged: false, nudgeTrouble: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed` };
+    }
+    // A busy harness is typed into: it takes the line as its next turn.
 
     typeIntoTab(
       live.handle,
-      `Fleet mail from ${from.bot}/${from.session}: ${subject}. Read it with  obk message check --bots ${to.bots} --bot ${to.bot} --session ${to.session}`,
+      `Fleet mail from ${from.bot}/${from.session}: ${subject}. Read it with  ${shellWord(ownCli())} message check --bots ${shellWord(to.bots)} --bot ${shellWord(to.bot)} --session ${shellWord(to.session)}`,
     );
     return { nudged: true };
   } catch (error) {
@@ -377,4 +399,4 @@ function whyNotReachable(bot, session, harness, held) {
 }
 
 const notUpYet = (who) =>
-  `${who.bot}/${who.session} has no mailbox yet: it has never been brought up. Start it and it gets one:  obk up --bots ${who.bots} --bot ${who.bot} --session ${who.session}`;
+  `${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)}`;

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0001). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0011). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -192,25 +192,83 @@ export const retitleTab = (handle, title) =>
   orca(['terminal', 'rename', '--terminal', handle, '--title', title]).rename;
 
 /**
- * Whether a TUI is running in the tab, and what it is waiting on if Orca says.
+ * What can be learned about the harness in a tab: what Orca says, and who is
+ * in front of the tab's terminal.
  *
- * `tui-idle` asks about a TUI, not about a shell: a tab sitting at a shell
- * prompt is refused with `timeout` however long you wait, a TUI that is up
- * answers `ok:true`, and `satisfied` only tells idle from busy. So this is the
- * way to learn whether a harness actually started — and `blockedReason` is
- * Orca saying something on screen wants answering, which is for the caller to
- * deal with, not the kit.
+ * Orca's answers alone do not tell a harness from a shell (tech notes, section
+ * 1, #232). `tui-idle` refuses a busy harness with `timeout` just as it refuses
+ * a shell, and a shell Codex quit to answers `ok`. `agentIdentity` comes late
+ * and can outlast the harness by minutes. So the answer the caller acts on is
+ * `front`: `program` when something other than the tab's shell holds its
+ * terminal, with `command` its name, `shell` when the shell does, and
+ * undefined when that cannot be read, with `unreadable` saying why. `answered` (an `ok` from `tui-idle`) and
+ * `agent` are Orca's own hints, for a caller that has nothing better.
+ * `blockedReason` is Orca saying something on screen wants answering, which is
+ * for the caller to deal with, not the kit.
  */
-export function tuiInTab(handle, timeoutMs) {
+export function harnessInTab(handle, timeoutMs) {
   const args = ['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)];
   const answer = ask(args);
 
-  if (answer.ok !== true) {
-    // Out of time means no TUI came up. That is an answer, not a breakdown.
-    if (answer.error?.code === 'timeout') return { running: false };
+  // Out of time means nothing went idle, busy or absent alike. That is an
+  // answer, not a breakdown.
+  if (answer.ok !== true && answer.error?.code !== 'timeout') {
     throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
   }
-  return { running: true, blockedReason: answer.result?.wait?.blockedReason };
+
+  const shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
+  const agent = typeof shown?.agentIdentity === 'string' && shown.agentIdentity !== '' ? shown.agentIdentity : undefined;
+  return {
+    answered: answer.ok === true,
+    blockedReason: answer.result?.wait?.blockedReason,
+    agent,
+    ...frontOf(shown?.ptyId),
+  };
+}
+
+/** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
+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> }`.
+ *
+ * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
+ * gives that pid's terminal's foreground process group (ADR 0011).
+ * On macOS the pane is `login` with the shell as its child, so the shell is in
+ * front when the group is the pane's own or that of a child of a `login` pane.
+ * `diagnostics memory` is a diagnostics command and may change, so everything
+ * here ends in "cannot tell" rather than in an error or a guess.
+ */
+function frontOf(ptyId) {
+  let pane;
+  try {
+    pane = orca(['diagnostics', 'memory']).worktrees
+      .flatMap((worktree) => worktree.sessions ?? [])
+      .find((session) => session.sessionId === ptyId)?.pid;
+  } catch (error) {
+    return { unreadable: `Orca would not give the pane's pid: ${error.message}` };
+  }
+  if (!Number.isInteger(pane) || pane <= 0) return { unreadable: 'Orca gave no pid for its pane' };
+
+  const own = psLine(pane);
+  if (own === undefined) return { unreadable: `ps could not read its pane, pid ${pane}` };
+  if (own.tpgid === pane) return { front: 'shell' };
+
+  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) };
+}
+
+/** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, or undefined. */
+function psLine(pid) {
+  const asked = spawnSync(psCli(), ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8' });
+  if (asked.error || asked.status !== 0) return undefined;
+  const line = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(.+?)\s*$/.exec(asked.stdout);
+  if (line === null) return undefined;
+  return { ppid: Number(line[2]), tpgid: Number(line[3]), comm: line[4] };
 }
 
 /**
@@ -257,19 +315,27 @@ const SUBMIT_WAIT_S = 5;
  * 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).
  */
-export const makeMailbox = (objective) =>
-  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`]).run.id;
+export const makeMailbox = (objective, handle) =>
+  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`, '--from', handle]).run.id;
 
 /**
- * Take this process's turn at reading a mailbox.
+ * Take a turn at reading a mailbox, as the terminal `handle`.
  *
- * Orca fences a Run to one reader: a `check` from a caller bound elsewhere is
+ * Orca fences a Run to one reader: a `check` from a terminal bound elsewhere is
  * refused with `consumer_fenced`, whatever the Run says. So a read binds first,
  * every time — the kit's runs are short and the binding is the last one to have
- * asked, not a lease anybody has to give back.
+ * asked, not a lease anybody has to give back. Without a handle it binds this
+ * process's own terminal.
  */
-export const useMailbox = (id) => orca(['orchestration', 'run-use', '--id', id]).run;
+export const useMailbox = (id, handle) =>
+  orca(['orchestration', 'run-use', '--id', id, ...(handle === undefined ? [] : ['--from', handle])]).run;
 
 /** Queue one message. `to` and `from` are mailboxes, written `run:<id>`. */
 export function postMessage({ to, from, subject, body, type = 'status', thread }) {
@@ -281,11 +347,16 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
 
 /**
  * What is waiting in a mailbox: the oldest batch that has not been
- * acknowledged, or, peeking, whatever is unread without touching it.
+ * acknowledged, or, peeking, whatever is unread without touching it. 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.
  */
-export const readMailbox = (id, { peek = false } = {}) =>
-  orca(['orchestration', 'check', '--run', id, ...(peek ? ['--peek'] : [])]);
+export const readMailbox = (id, { peek = false, handle } = {}) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])]);
 
 /** Say a batch has been read, so the next check brings the one after it. */
-export const ackMailbox = (id, delivery) =>
-  orca(['orchestration', 'check', '--run', id, '--ack', delivery]);
+export const ackMailbox = (id, delivery, handle) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery]);
+
+/** The reader of a `check`: the terminal named, or this process's own. */
+const as = (handle) => (handle === undefined ? [] : ['--terminal', handle]);

package/src/pause.js

@@ -4,7 +4,7 @@
 // A pause is a mark in the bot's `bot.yaml` and the bot's tabs closed. The
 // mark is what `up` reads to leave it closed, and the book keeps the
 // conversation each session was in, so an unpause is the mark taken off and
-// the ordinary `up`, which resumes it (ADR 0002).
+// the ordinary `up`, which resumes it (ADR 0012).
 //
 // The closing is restart's, with restart's rules: only the tabs the book names,
 // one at a time by their own handles, and none at all when one of them holds a
@@ -13,6 +13,7 @@
 import { realpathSync } from 'node:fs';
 
 import { botDir, markPaused, readBot } from './bot.js';
+import { DAILY_SESSION } from './init.js';
 import { closeTabs, tabsToClose } from './restart.js';
 import { BOT_FATHER, botsNamed, bringUp, sessionsOf } from './up.js';
 
@@ -22,7 +23,7 @@ import { BOT_FATHER, botsNamed, bringUp, sessionsOf } from './up.js';
  * per tab it closed.
  */
 export async function pauseSessions(bots, { bot, session }) {
-  const home = fleetMember(bots, bot, 'pause');
+  const home = fleetMember(bots, bot, 'pause', session);
   const sessions = sessionsOf(readBot(home, bot), session);
 
   // Judged before anything is written or closed, so a refusal leaves both as
@@ -38,7 +39,7 @@ export async function pauseSessions(bots, { bot, session }) {
  * Returns `{ bot, session, changed, ...what up answered }`.
  */
 export async function unpauseSessions(bots, { bot, session }) {
-  const home = fleetMember(bots, bot, 'unpause');
+  const home = fleetMember(bots, bot, 'unpause', session);
   sessionsOf(readBot(home, bot), session);
 
   const changed = markPaused(bots, bot, session, false);
@@ -47,12 +48,16 @@ export async function unpauseSessions(bots, { bot, session }) {
 
 /**
  * The bot's home, once it is certain the bot is there and is not Bot Father,
- * which runs the fleet and is the one the user asks to bring anything back.
+ * or its management session: that is where the user asks to bring anything
+ * back. Bot Father's other sessions are like any bot's (#230).
  */
-export function fleetMember(bots, bot, verb) {
-  if (bot === BOT_FATHER) {
+export function fleetMember(bots, bot, verb, session) {
+  if (bot === BOT_FATHER && session === undefined) {
     throw new Error(`${BOT_FATHER} runs the fleet, and the kit does not ${verb} it: it is where you ask for everything else.`);
   }
+  if (bot === BOT_FATHER && session === DAILY_SESSION) {
+    throw new Error(`${DAILY_SESSION} is ${BOT_FATHER}'s management session, and the kit does not ${verb} it: it is where you ask for everything else.`);
+  }
   botsNamed(bots, bot);
   return realpathSync(botDir(bots, bot));
 }

package/src/record.js

@@ -2,7 +2,7 @@
 //
 // Both harnesses run the kit's hook (src/hooks.js) and hand it the session id
 // they are running under. That is how the book stays the authority for session
-// ids (ADR 0002) without the kit guessing from transcripts.
+// ids (ADR 0012) without the kit guessing from transcripts.
 //
 // Which session it is comes from the tab: Orca puts the tab id in the
 // environment of everything running in it, and the book says which session owns

package/src/restart.js

@@ -5,7 +5,7 @@
 // avoided, not banned, and one happens when the user asks for it).
 //
 // When they do ask, the session has to come back as itself. The book holds the
-// conversation each session is running (ADR 0002), so a restart is: close the
+// conversation each session is running (ADR 0012), so a restart is: close the
 // tab the book names, then let `up` open a new one and resume that
 // conversation. Nothing else about it is new.
 //
@@ -31,6 +31,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 { botsNamed, bringUp, prepareBots, sessionsOf } from './up.js';
 
@@ -49,10 +50,10 @@ export async function restartSessions(bots, { bot: name, session: onlySession }
   // A paused bot or session has no tab to close and is not to be opened, so
   // there is nothing here to restart.
   if (known.paused === true) {
-    throw new Error(`${name} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with obk unpause --bots ${bots} --bot ${name}.`);
+    throw new Error(`${name} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with ${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${name}.`);
   }
   if (onlySession !== undefined && sessions[0].paused === true) {
-    throw new Error(`${name} ${onlySession} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with obk unpause --bots ${bots} --bot ${name} --session ${onlySession}.`);
+    throw new Error(`${name} ${onlySession} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with ${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${name} --session ${onlySession}.`);
   }
 
   // And the same preparations, made now rather than left to `up`, which makes
@@ -158,7 +159,7 @@ async function gone(home, closed, bots, bot) {
 
     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: obk up --bots ${bots} --bot ${bot} brings them back once Orca has caught up.`);
+      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.`);
     }
     await pause(ASK_MS);
   }
@@ -188,5 +189,5 @@ function alsoClosed(why, closed, bots, bot) {
   if (closed.length === 0) return why;
 
   const one = closed.length === 1;
-  return `${why} ${closed.map((tab) => tab.name).join(', ')} ${one ? 'was' : 'were'} closed before it and nothing was opened in ${one ? 'its' : 'their'} place: obk up --bots ${bots} --bot ${bot} brings ${one ? 'it' : 'them'} back with ${one ? 'its' : 'their'} conversation.`;
+  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

@@ -14,7 +14,7 @@
 //
 // Closing a tab here ends the conversation in it on purpose, so unlike a
 // restart or a pause it does not wait for the book to know which one it was.
-// The mailbox Runs stay: Orca has no way to remove one (ADR 0008).
+// The mailbox Runs stay: Orca has no way to remove one (ADR 0018).
 
 import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import path from 'node:path';
@@ -34,7 +34,7 @@ export const retiredDir = (bots) => path.join(bots, 'retired');
  * Retire the session `session` of the bot `bot`. Returns `{ bot, session, closed }`.
  */
 export async function retireSession(bots, { bot, session }) {
-  const home = fleetMember(bots, bot, 'retire');
+  const home = fleetMember(bots, bot, 'retire', session);
   const sessions = sessionsOf(readBot(home, bot), session);
 
   const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot);