@assuredloop/orca-bot-kit 0.1.0 → 0.2.0

package/src/launch.js

@@ -0,0 +1,276 @@
+// 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
+// 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
+// harness's own.
+//
+// The text goes into the tab's ordinary shell, so every word is quoted the way
+// a shell needs it. `claude --model sonnet[1m]` would be a glob to zsh.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** The approval levels, and what each one is called on each harness. */
+const APPROVAL = {
+  claude: {
+    auto: ['--permission-mode', 'auto'],
+    ask: ['--permission-mode', 'manual'],
+    'dangerously-skip': ['--dangerously-skip-permissions'],
+  },
+  codex: {
+    auto: ['--approve-for-me'],
+    ask: ['-a', 'on-request'],
+    'dangerously-skip': ['--dangerously-bypass-approvals-and-sandbox'],
+  },
+};
+
+export const APPROVALS = Object.keys(APPROVAL.claude);
+
+/**
+ * How a permission bypass is spelled on a harness: the flags the
+ * `dangerously-skip` level puts on the launch line, and the same ones Orca's
+ * own default launch arguments carry when they carry a bypass (PRD 6.5).
+ */
+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). */
+export const DEFAULT_APPROVAL = 'auto';
+
+/** A setting the user left out. An empty string is one too: it means the harness's own. */
+const set = (value) => value !== undefined && value !== null && String(value).trim() !== '';
+
+/** Which harness a session runs on: its own, or the bot's. */
+export const harnessOf = (session, botHarness) => (set(session.harness) ? session.harness : botHarness);
+
+/**
+ * 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
+ * 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.
+ */
+export const addressOf = (bot, session) => `${bot}.${session}`;
+
+/**
+ * The Codex setting without which a bot cannot reach Orca at all.
+ *
+ * Inside Codex's workspace-write sandbox the Orca CLI runs but cannot connect
+ * to the running app, so `orca orchestration` is refused and a Codex bot can
+ * neither read nor send fleet mail. With this switch on, the same session at
+ * the same approval level reaches it (tech notes, section 3, proved live).
+ * The widening is real and said plainly where the user sees the launch line:
+ * that sandbox gains network access, there being no localhost-only setting.
+ */
+const NETWORK_ACCESS = 'sandbox_workspace_write.network_access';
+
+/**
+ * Whether the user has settled that switch themselves in this session's extra
+ * arguments. Theirs wins, whichever way they set it: the kit adds nothing
+ * beside it, and a session that turned it off is reported as out of reach of
+ * fleet mail rather than quietly failing to answer.
+ */
+export const setsNetworkAccess = (session) =>
+  extraWords(session.extra_args).some((word) => word.includes(NETWORK_ACCESS));
+
+/**
+ * Whether fleet mail can reach this session at all: everything but a Codex
+ * session whose user turned the sandbox switch off.
+ */
+export const reachesMail = (session, harness) =>
+  harness !== 'codex' || !turnedOff(session);
+
+const turnedOff = (session) =>
+  extraWords(session.extra_args).some((word) => word.includes(`${NETWORK_ACCESS}=false`));
+
+/** Where a session's work dir is: under the bot home, or wherever it says. */
+export function workDirOf(session, home) {
+  if (!set(session.work_dir)) return undefined;
+  return path.resolve(home, session.work_dir);
+}
+
+/**
+ * What a session asks for that cannot be done, in the user's own terms.
+ *
+ * Both commands that write a session check this, and so does the run that
+ * starts one: a session can also arrive by hand, and a bot.yaml the user edited
+ * is worth the same plain sentence rather than a stray flag typed into a tab.
+ */
+export function sessionTrouble(session, harness, home) {
+  if (set(session.prompt) && set(session.prompt_file)) {
+    return `${where(session)} has both a prompt and a prompt file, and a session is told its duty once. Keep the one you meant.`;
+  }
+  // The file is the prompt, so a session that cannot be read cannot be started,
+  // and saying so now beats a tab that comes up with nothing to do.
+  if (set(session.prompt_file)) {
+    try {
+      readFileSync(promptFile(session, home), 'utf8');
+    } catch (error) {
+      return `${where(session)} has its prompt in ${session.prompt_file}, and that file cannot be read (${error.code}): ${promptFile(session, home)}. Write it, or point the session at the file you meant.`;
+    }
+  }
+  if (!HARNESSES.includes(harness)) {
+    return `${where(session)} runs on ${harness}, and the harnesses are ${HARNESSES.join(' and ')}.`;
+  }
+  if (set(session.approval) && !APPROVALS.includes(session.approval)) {
+    return `${where(session)} is set to approval ${session.approval}, and the levels are ${APPROVALS.join(', ')}.`;
+  }
+  // Codex is given the context window as a number of tokens. `1m` is what a
+  // Claude session would say, and copying it here does not fail at the kit but
+  // in Codex, which exits with a type error the moment it starts.
+  if (harness === 'codex' && set(session.context) && !/^\d+$/.test(String(session.context).trim())) {
+    return `${where(session)} sets a context of ${session.context} on Codex, and Codex counts that in tokens, as a whole number: 200000, for example. A context like 1m belongs on Claude Code, where it is part of the model name.`;
+  }
+  // On Claude Code the context window is a suffix on the model name, so there
+  // is nothing to hang it on when no model was named.
+  if (harness === 'claude' && set(session.context) && !set(session.model)) {
+    return `${where(session)} sets a context on Claude Code but no model. On Claude Code the context is part of the model name (--model 'sonnet[1m]'), so give the session a model as well, or leave the context out.`;
+  }
+  return undefined;
+}
+
+const where = (session) => (set(session.name) ? `session ${session.name}` : 'this session');
+
+/**
+ * The line that starts the harness in a session's tab, with the session's start
+ * prompt on the end of it as the harness's own prompt argument.
+ *
+ * Nothing is added for a setting the session left out, and the order is fixed:
+ * approval, model, effort, context, work dir, whatever the user added, and the
+ * prompt last, where a positional argument goes.
+ *
+ * The prompt rides on this line rather than being typed in afterwards, which is
+ * what a first run in a fresh bots repo taught us: the harness may be showing
+ * its folder-trust question, Claude Code's reads as idle to Orca, and a second
+ * send would land on that list and answer it. A prompt given as an argument is
+ * held by the harness until it is ready for it (tech notes, section 1).
+ */
+export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address }) {
+  const trouble = sessionTrouble(session, harness, home);
+  if (trouble !== undefined) throw new Error(trouble);
+
+  const words = [harness];
+  // Codex resumes through a subcommand, which has to come first; Claude Code
+  // resumes through a flag, which goes with the session id at the end. Both
+  // take every other flag exactly as a fresh session does.
+  if (resume !== undefined && harness === 'codex') words.push('resume');
+  words.push(...APPROVAL[harness][set(session.approval) ? session.approval : DEFAULT_APPROVAL]);
+
+  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).
+    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);
+    if (set(session.effort)) words.push('--effort', String(session.effort));
+  } else {
+    // Without this the Orca CLI cannot reach Orca from inside the sandbox, so
+    // the session is in no fleet at all. The user's own setting of it wins.
+    if (!setsNetworkAccess(session)) words.push('-c', `${NETWORK_ACCESS}=true`);
+    if (set(session.model)) words.push('-m', session.model);
+    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
+    // home has to be named.
+    if (workDir !== undefined && !inside(home, workDir)) words.push('--add-dir', workDir);
+  }
+
+  return [
+    // The shell's own pid, so the session's hook can tell the harness this line
+    // 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}=$$`,
+    ...words.map(quoted),
+    ...extraWords(session.extra_args),
+    ...resumeWords(harness, resume),
+    // `--` first: a prompt of the user's own may start with a dash — a
+    // Markdown bullet does — and both harnesses would read it as an option of
+    // theirs and refuse to start.
+    ...promptWords(prompt, fromFile),
+  ].join(' ');
+}
+
+/**
+ * What the session is told when it comes up, or undefined when it has nothing
+ * to say. The work dir is named here and nowhere else: it is an instruction to
+ * the session, not something the harness is told (PRD 6.4).
+ *
+ * A long prompt lives in a file in the bot home and the session points at it;
+ * a short one is written in the session itself. Either way it is word for word
+ * as the user wrote it: it travels as one argument, quoted for the shell it is
+ * typed into, so nothing has to be flattened to keep it whole — the two
+ * spaces, the newlines and the indentation of a prompt carrying a piece of
+ * text or code are the user's, and none of the kit's business.
+ */
+export function startPrompt(session, { home, workDir }) {
+  const note = workDir === undefined
+    ? undefined
+    : `Your work dir is ${workDir}. It is a plain folder the kit made for you, not a git worktree.`;
+
+  // Only the ends are taken off — a `prompt: |` in YAML, and a file, both carry
+  // a newline the user never typed. What is inside is theirs.
+  const said = [set(session.prompt_file) ? readFileSync(promptFile(session, home), 'utf8') : session.prompt, note]
+    .filter(set)
+    .map((part) => String(part).trim());
+  return said.length === 0 ? undefined : said.join('\n\n');
+}
+
+/** Where a session's prompt file is: in the bot home, where the user put it. */
+export const promptFile = (session, home) => path.resolve(home, session.prompt_file);
+
+/**
+ * A prompt short and simple enough to type into the launch line as it is: one
+ * line, and not a long one. Everything else goes to the harness out of a file,
+ * which keeps a page of text out of a tab's shell and its history.
+ */
+export const isShortPrompt = (prompt) => !prompt.includes('\n') && prompt.length <= SHORT_PROMPT;
+
+const SHORT_PROMPT = 200;
+
+/**
+ * The prompt on the launch line: the text itself when it is short, and
+ * otherwise the file the kit wrote it to, read back by the shell that types the
+ * line. `"$(cat …)"` hands the harness one argument whatever is in the file.
+ */
+function promptWords(prompt, fromFile) {
+  if (fromFile !== undefined) return ['--', `"$(cat ${quoted(fromFile)})"`];
+  return prompt === undefined ? [] : ['--', quoted(prompt)];
+}
+
+/**
+ * The session the harness is told to pick up again, when there is one: a flag
+ * on Claude Code, the argument of the `resume` subcommand on Codex.
+ */
+const resumeWords = (harness, resume) => {
+  if (resume === undefined) return [];
+  return harness === 'claude' ? ['--resume', quoted(resume)] : [quoted(resume)];
+};
+
+/** Whether `target` is the folder at `home` or something inside it. */
+const inside = (home, target) => target === home || target.startsWith(home + path.sep);
+
+/**
+ * The user's own `extra_args`. A list is a list of arguments, each quoted as
+ * one. A plain string is the user's own shell text, typed as they wrote it.
+ */
+function extraWords(extra) {
+  if (Array.isArray(extra)) return extra.filter(set).map((arg) => quoted(String(arg)));
+  return set(extra) ? [String(extra).trim()] : [];
+}
+
+/**
+ * Where the launch line tells the session's hook which shell typed the harness
+ * in. One tab holds one session: the harness this shell starts. Anything that
+ * session starts inside the tab is not the session and can never be it.
+ */
+export const SHELL_ENV = 'OBK_TAB_SHELL';
+
+/** A word as a shell needs it. Anything a shell would read as more than a word is quoted. */
+const quoted = (word) => (/^[A-Za-z0-9,._+:@%/=-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`);
+
+/** The same, for anything else of the kit's that has to build a shell line. */
+export const shellWord = quoted;

package/src/message.js

@@ -0,0 +1,380 @@
+// `obk message`: one session writing to another (PRD 6.9, ADR 0008).
+//
+// 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 —
+// so the kit answers with the address and says to use it. Everything else goes
+// through the Orca mailbox, which the kit does carry.
+//
+// What the mailbox is, and why it is not the tab: Orca calls a terminal a live
+// terminal-only mailbox, warns that delivery does not outlive the tab, and
+// refuses a send once the pane is gone. A Run survives the tab, the relaunch
+// and the restart, so a session's address is its Run (tech notes, section 1).
+//
+// Nothing in a mailbox wakes the session it belongs to — a message addressed to
+// a tab leaves the harness in it untouched, proved live — so a send also types
+// one line into the receiver's tab. Both harnesses queue a typed line while
+// they are busy, which is what PRD 6.9 means by queued and not interrupting.
+
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+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';
+
+/**
+ * How much of a message travels as itself. Above this it is written to a file
+ * beside the bots folder and the message names the file, which is PRD 6.9's one
+ * rule with no judgement in it.
+ *
+ * The number is the receiver's, not Orca's: 200 KB goes through the mailbox
+ * whole, but it lands in a session's context, and a command line dies near a
+ * megabyte anyway. Four kilobytes is a message; more than that is a document,
+ * and a document has a name.
+ */
+export const INLINE_LIMIT = 4 * 1024;
+
+/** How long Orca is given to say whether a tab has a TUI in it to nudge. */
+const LOOK_MS = 2000;
+
+/**
+ * Everything the kit knows about one session as somebody to write to: which
+ * harness it runs on, which approval class it is in, its mailbox, its name on
+ * Claude Code, and the tab it is in. `trouble` is the one sentence that says
+ * why it cannot be written to, when it cannot.
+ */
+export function findSession(bots, target) {
+  const { bot: botName, session: sessionName } = splitTarget(target);
+
+  const names = botNames(bots);
+  if (!names.includes(botName)) {
+    throw new Error(`there is no bot called ${botName} in ${bots}. The bots there are: ${names.join(', ')}.`);
+  }
+
+  // Resolved, because Orca is asked about this folder by path and does not
+  // follow a link to it (tech notes, section 1).
+  const home = realpathSync(botDir(bots, botName));
+  const bot = readBot(home, botName);
+  const session = pickSession(bot, sessionName, target);
+  const harness = harnessOf(session, bot.harness);
+  const held = readBook(home).sessions[session.name] ?? {};
+
+  return {
+    bots,
+    home,
+    bot: bot.name,
+    session: session.name,
+    harness,
+    approval: classOf(session),
+    address: typeof held.address === 'string' ? held.address : undefined,
+    mailbox: typeof held.mailbox === 'string' ? held.mailbox : undefined,
+    tab: typeof held.tab === 'string' ? held.tab : undefined,
+    trouble: whyNotReachable(bot.name, session, harness, held),
+  };
+}
+
+/**
+ * Which road a message between these two takes, and the address it goes to.
+ *
+ * Native is the harness's own cross-session messaging: Claude Code to Claude
+ * Code, and only where both sit in the same approval class, because a message
+ * across classes is held for somebody to approve and the kit chooses a road in
+ * advance rather than working around a hold (PRD 6.9).
+ */
+export function roadBetween(from, to) {
+  const pair = from.harness === 'claude' && to.harness === 'claude' && from.approval === to.approval;
+  if (pair && to.address !== undefined) return { transport: 'native', address: to.address };
+
+  return {
+    transport: 'orca',
+    address: to.mailbox === undefined ? undefined : `run:${to.mailbox}`,
+    // A Claude pair that the native road cannot carry, because the receiver is
+    // running under no name the kit gave it: it was started before the kit
+    // named sessions, and nothing renames a live harness. The mailbox is the
+    // road that exists, and the caller is told why it is the one being used
+    // rather than left to wonder (review of PR #132, finding 1).
+    unnamed: pair ? true : undefined,
+  };
+}
+
+/** What `obk message to` answers: the road, the address, and who is at each end. */
+export function lookUp(bots, { to: target, from: sender, tab }) {
+  const from = whoIsWriting(bots, sender, tab);
+  const to = findSession(bots, target);
+  const road = roadBetween(from, to);
+
+  return {
+    bots,
+    from: { bot: from.bot, session: from.session, harness: from.harness },
+    to: { bot: to.bot, session: to.session, harness: to.harness },
+    ...road,
+    trouble: to.trouble ?? (road.address === undefined ? notUpYet(to) : undefined),
+  };
+}
+
+/**
+ * Send one message down the Orca road, and tell the receiver's tab to look.
+ *
+ * A native pair is not carried here: no command line can send a Claude session's
+ * own message. The kit says which address to write to instead, and sends
+ * nothing, which is the whole of "the bot never picks the transport".
+ */
+export function sendMessage(bots, { to: target, from: sender, tab, subject, text, textFile, thread }) {
+  const from = whoIsWriting(bots, sender, tab);
+  const to = findSession(bots, target);
+  const road = roadBetween(from, to);
+
+  const answer = {
+    bots,
+    from: { bot: from.bot, session: from.session },
+    to: { bot: to.bot, session: to.session },
+    subject,
+    ...road,
+  };
+
+  if (road.transport === 'native') {
+    return {
+      ...answer,
+      sent: false,
+      trouble: `${to.bot}/${to.session} is a Claude session in your own approval class, so it is written to with your own harness's messaging, not through Orca. Its address is ${to.address}.`,
+    };
+  }
+
+  if (to.trouble !== undefined) return { ...answer, sent: false, trouble: to.trouble };
+  if (road.address === undefined) return { ...answer, sent: false, trouble: notUpYet(to) };
+  if (from.mailbox === undefined) {
+    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}`,
+    };
+  }
+
+  const written = bodyOf(bots, { from, to, subject, text, textFile });
+  const message = postMessage({
+    to: road.address,
+    from: `run:${from.mailbox}`,
+    subject,
+    body: written.body,
+    thread,
+  });
+
+  return {
+    ...answer,
+    sent: true,
+    id: message.id,
+    thread: message.thread_id ?? thread,
+    file: written.file,
+    ...nudge(to, from, subject),
+  };
+}
+
+/**
+ * What is waiting for a session, and the reading of it.
+ *
+ * Orca fences a Run to one reader, so this binds before it reads. A read that
+ * is not a peek acknowledges the batch it read: that is what makes the next
+ * check bring the next one rather than the same again.
+ */
+export function checkMail(bots, { bot: botName, session: sessionName, tab, peek = false }) {
+  const who = sessionName === undefined && botName === undefined
+    ? whoIsWriting(bots, undefined, tab, '--bot <bot> [--session <name>]: whose mail to read')
+    : findSession(bots, sessionName === undefined ? botName : `${botName}/${sessionName}`);
+
+  if (who.mailbox === undefined) {
+    return {
+      bots,
+      bot: who.bot,
+      session: who.session,
+      messages: [],
+      trouble: who.trouble ?? notUpYet(who),
+    };
+  }
+
+  useMailbox(who.mailbox);
+  const found = readMailbox(who.mailbox, { peek });
+  const messages = (found.messages ?? []).map((message) => asMessage(bots, message));
+  if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId);
+
+  return { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
+}
+
+/** One message, in the kit's words rather than Orca's. */
+const asMessage = (bots, message) => ({
+  id: message.id,
+  // The mailbox it came from, said as the session it belongs to where the
+  // fleet knows it: a reply is written to a session, not to a run id.
+  from: whoOwns(bots, message.from_handle) ?? message.from_handle,
+  fromMailbox: message.from_handle,
+  subject: message.subject,
+  body: message.body,
+  thread: message.thread_id ?? undefined,
+  at: message.created_at,
+});
+
+/** Whose mailbox `run:<id>` is, as `<bot>/<session>`, when it is one of the fleet's. */
+function whoOwns(bots, handle) {
+  if (typeof handle !== 'string' || !handle.startsWith('run:')) return undefined;
+  const mailbox = handle.slice('run:'.length);
+
+  for (const name of botNames(bots)) {
+    const book = readBook(botDir(bots, name));
+    for (const [session, entry] of Object.entries(book.sessions)) {
+      if (entry?.mailbox === mailbox) return `${name}/${session}`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The session that is writing: the one named, or the one whose Orca tab this
+ * command is running in. A caller that is in neither is asked to say, rather
+ * than being given somebody else's name.
+ */
+function whoIsWriting(bots, sender, tab, asked = '--from <bot>/<session>: which session is writing') {
+  if (sender !== undefined) return findSession(bots, sender);
+
+  const found = tab === undefined ? undefined : sessionInTab(bots, tab);
+  if (found === undefined) {
+    throw new Error(`${asked}. The kit reads it from the tab when it runs in one, and this is not one of the fleet's tabs.`);
+  }
+  return found;
+}
+
+/** The session the book says is in this Orca tab, wherever in the fleet it is. */
+function sessionInTab(bots, tab) {
+  for (const name of botNames(bots)) {
+    const book = readBook(botDir(bots, name));
+    for (const [session, entry] of Object.entries(book.sessions)) {
+      if (entry?.tab === tab) return findSession(bots, `${name}/${session}`);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The message as it will travel: the text itself when it is short enough, and
+ * otherwise a file beside the bots folder with a body that names it.
+ *
+ * The file is the kit's own, next to the bots repo the way start prompts are,
+ * so a long message is not written into the user's git status and does not
+ * depend on a file of theirs staying where it was when they sent it.
+ */
+function bodyOf(bots, { from, to, subject, text, textFile }) {
+  const said = textFile === undefined ? text : readText(textFile);
+  if (said === undefined || said.trim() === '') {
+    throw new Error('message send needs something to say: --text <text> or --text-file <path>, with something in it.');
+  }
+  if (Buffer.byteLength(said, 'utf8') <= INLINE_LIMIT) return { body: said };
+
+  const file = path.join(
+    `${bots}.messages`,
+    `${encodeURIComponent(`${from.bot}.${from.session}`)}.${encodeURIComponent(`${to.bot}.${to.session}`)}.${stamp()}.md`,
+  );
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, said);
+  return {
+    body: `${subject} is longer than a message carries, so it is in this file, whole and as it was written:\n${file}`,
+    file,
+  };
+}
+
+function readText(file) {
+  try {
+    return readFileSync(file, 'utf8');
+  } catch (error) {
+    throw new Error(`--text-file names ${file}, and that file cannot be read (${error.code}). Write it, or name the one you meant.`);
+  }
+}
+
+const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '-');
+
+/**
+ * Tell the receiver's tab that mail is waiting: one line, typed in.
+ *
+ * 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
+ * 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.
+ *
+ * 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
+ * up. That is not a worry, it is a thing that happened — in slice 03 a second
+ * line went into a tab on Claude Code's folder-trust list, confirmed its
+ * default, `No, exit`, and the harness quit (tech notes, section 1). So where
+ * Orca says a tab is blocked, nothing is typed and the mail waits.
+ *
+ * Orca's `blockedReason` catches Codex's screens and not Claude Code's, which
+ * answer as idle with nothing said, so this narrows the case rather than
+ * closing it. What closes it is nobody sending to a session before its first
+ * screens are answered, which is the caller's work either way.
+ */
+function nudge(to, from, subject) {
+  if (to.tab === undefined) return { nudged: false };
+
+  try {
+    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 };
+
+    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}`,
+    );
+    return { nudged: true };
+  } catch (error) {
+    // The message is already queued, and it is waiting whatever Orca says
+    // about the tab. So this is reported rather than thrown: a send that ends
+    // in an error the caller reads as "it did not go" would be a lie, and a
+    // silent `false` would read as "the session is not up", which is a
+    // different thing from "Orca would not say".
+    return { nudged: false, nudgeTrouble: error.message };
+  }
+}
+
+/** `<bot>/<session>`, or a bot on its own when it has only the one session. */
+function splitTarget(target) {
+  const parts = target.split('/');
+  if (parts.length > 2 || parts.some((part) => part.trim() === '')) {
+    throw new Error(`a session is written <bot>/<session>, and got: ${target}`);
+  }
+  return { bot: parts[0], session: parts[1] };
+}
+
+function pickSession(bot, sessionName, target) {
+  if (sessionName === undefined) {
+    if (bot.sessions.length === 1) return bot.sessions[0];
+    if (bot.sessions.length === 0) {
+      throw new Error(`${bot.name} has no sessions yet. Add one with obk session add --bots <path> --bot ${bot.name} --name <name>.`);
+    }
+    throw new Error(`${bot.name} has ${bot.sessions.length} sessions, so say which one: ${bot.sessions.map((session) => `${bot.name}/${session.name}`).join(', ')}.`);
+  }
+
+  const found = bot.sessions.find((session) => session.name === sessionName);
+  if (found === undefined) {
+    throw new Error(`${bot.name} has no session called ${sessionName}. It has: ${bot.sessions.map((session) => session.name).join(', ') || 'none'}.`);
+  }
+  return found;
+}
+
+/**
+ * Claude Code delivers between two sessions of the same class without asking,
+ * and holds a message that crosses classes for somebody to approve (tech notes,
+ * section 2). The kit's levels map onto the harness's two: the bypassing one is
+ * `dangerously-skip`, and everything else prompts.
+ */
+const classOf = (session) => (session.approval === 'dangerously-skip' ? 'bypassing' : 'prompting');
+
+/** Why fleet mail cannot reach this session at all, when it cannot. */
+function whyNotReachable(bot, session, harness, held) {
+  if (reachesMail(session, harness)) return undefined;
+  return `${bot}/${session.name} is a Codex session whose extra arguments turn sandbox_workspace_write.network_access off. Orca is out of reach from inside that sandbox, so it can neither be written to nor read its own mail. Take that argument out, or write to it another way.`;
+}
+
+const notUpYet = (who) =>
+  `${who.bot}/${who.session} has no mailbox yet: it has never been brought up. Start it and it gets one:  obk up --bots ${who.bots} --bot ${who.bot} --session ${who.session}`;