@assuredloop/orca-bot-kit 0.25.2 → 0.25.4

package/src/message.js

@@ -1,4 +1,4 @@
-// `obk message`: one session writing to another (PRD 6.9, ADR 0030).
+// `obk message`: one session writing to another (PRD 6.9, ADR 0035).
 //
 // 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 —
@@ -11,18 +11,23 @@
 // 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.
+// a tab leaves the harness in it untouched, proved live — so each message gets
+// one signal that tells the receiver to look: Orca's own notice first, and the
+// kit's typed line only where that did not come (#509, ADR 0035). A busy
+// Claude session gets nothing typed, since Claude Code holds a line typed into
+// it until its turn ends; its own turn-end hook tells it instead.
 
 import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+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 { recordMark, userTurnSince } from './conversations.js';
 import { harnessOf, isAddressOf, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
-import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, typeIntoTab, useMailbox } from './orca.js';
+import { ackMailbox, coordinatorOf, idleNow, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, typeIntoTab, useMailbox } from './orca.js';
+import { forgetUnread, markTold, noteUnread, unreadOf } from './unread.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -74,6 +79,9 @@ export function findSession(bots, target) {
     address: isAddressOf(bot.name, session.name, held.address) ? held.address : undefined,
     mailbox: typeof held.mailbox === 'string' ? held.mailbox : undefined,
     tab: typeof held.tab === 'string' ? held.tab : undefined,
+    // The conversation the book holds for it, whose record says whether Orca's
+    // notice reached it (#509).
+    conversation: typeof held.session === 'string' ? held.session : undefined,
     trouble: whyNotReachable(bot.name, session, harness, held),
   };
 }
@@ -125,7 +133,7 @@ export function lookUp(bots, { to: target, from: sender, tab }) {
  * 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 }) {
+export async 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);
@@ -159,6 +167,9 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
   }
 
   const written = bodyOf(bots, { from, to, subject, text, textFile });
+  // The receiver's record as it stands before the mail: Orca can type its
+  // notice the moment the mail is in.
+  const mark = recordMark(to.harness, to.home, to.conversation);
   const message = postMessage({
     to: road.address,
     from: `run:${from.mailbox}`,
@@ -166,6 +177,7 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
     body: written.body,
     thread,
   });
+  noteUnread(to.home, to.session, { id: message.id, from: `${from.bot}/${from.session}`, subject, at: message.created_at ?? new Date().toISOString() });
 
   return {
     ...answer,
@@ -173,7 +185,7 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
     id: message.id,
     thread: message.thread_id ?? thread,
     file: written.file,
-    ...nudge(to, from, subject, tab),
+    ...(await nudge(to, from, subject, tab, mark)),
   };
 }
 
@@ -207,7 +219,11 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
     };
   }
   try {
-    return mailOf(bots, findSession(bots, `${asked.bot}/${asked.session}`), peek, Date.now() + HOLD_MS);
+    const who = findSession(bots, `${asked.bot}/${asked.session}`);
+    const read = mailOf(bots, who, peek, Date.now() + HOLD_MS);
+    // What was read is out of the kit's hint of unread mail (#509); a peek reads nothing.
+    if (!peek && read.messages.length > 0) forgetUnread(who.home, who.session, read.messages.map((message) => message.id));
+    return read;
   } finally {
     turn.release();
   }
@@ -430,32 +446,135 @@ function readText(file) {
 const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '-');
 
 /**
- * Tell the receiver's tab that mail is waiting: one line, typed in.
+ * Tell the receiver that mail is waiting, with one signal (#509, ADR 0035).
  *
- * 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 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. Nor is one the kit cannot tell about. A tab the book does not
- * hold is never typed into on any road.
+ * Orca's own notice is the first signal: it types it into the receiver's tab
+ * once the tab is at rest. The kit's line is the fallback, for a receiver the
+ * notice did not reach. So an idle receiver is watched for up to WATCH_MS, and
+ * its own record of its turns says whether the notice came: a turn of the
+ * user's, written after the send, that names its mailbox. Then nothing is
+ * typed. When no turn started, the kit types its line, which an idle harness
+ * takes at once. A Claude session busy with a turn, from the first look or
+ * from a turn of other work in the watch, gets nothing typed: Claude Code
+ * holds a line typed during a turn in its input box until the turn ends,
+ * which can be after the mail was read, or never, and the session's own
+ * turn-end hook tells it about mail still unread. A busy Codex session gets the
+ * line: Codex takes it into the running turn at once, and it is what ends
+ * Codex's sleep tool (#432). A record that cannot be found or read is a notice
+ * not seen.
  *
- * Nor is a tab with something on screen waiting to be answered. A line typed
+ * Nothing is typed into a tab with no harness in it — there is nobody there to
+ * read it, and the message waits in the mailbox until the session is up. Nor
+ * into one the kit cannot tell about. A tab the book does not hold is never
+ * typed into on any road.
+ *
+ * Nor into 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). And in
  * #329 a return took Codex's "Update now". So where Orca says a tab is
  * blocked, or the kit sees a numbered choice list of the harness's own on its
- * screen, nothing is typed and the mail waits.
+ * screen, nothing is typed and the mail waits. The gate is passed again right
+ * before the line, after the watch.
  *
  * That narrows the case rather than closing it: a question drawn any other way,
  * such as Claude Code's unnumbered trust list, is seen by neither. What closes
  * it is nobody sending to a session before its first screens are answered,
  * which is the caller's work either way.
+ *
+ * What is left open: a turn that starts between the gate's last look and the
+ * line meets the line, which then waits for that turn to end.
  */
-function nudge(to, from, subject, tab) {
+async function nudge(to, from, subject, tab, mark = recordMark(to.harness, to.home, to.conversation)) {
   if (to.tab === undefined) return { nudged: false };
+  const notice = `orchestration check --run ${to.mailbox}`;
+
+  const first = atTheGate(to, from, subject, tab, mark, (found) => (found.idle ? { watch: found.handle } : { busy: true }));
+  if (first.busy) {
+    // Busy at the first look may be Orca's notice, typed the moment the mail
+    // was in: an idle Codex took it as a turn before the kit looked, live.
+    if (await noticeShows(mark, notice)) return { nudged: false, signal: 'orca' };
+    if (to.harness === 'claude') return { nudged: false, signal: 'hook', because: 'busy' };
+    return atTheGate(to, from, subject, tab, mark, (found) => (userTurnSince(mark, notice)
+      ? { nudged: false, signal: 'orca' }
+      : line(found.handle, to, from, subject, 'busy')));
+  }
+  if (first.watch === undefined) return first;
+
+  const watched = await watch(first.watch, mark, notice);
+  const watchedMs = watched.ms;
+  if (watched.notice) return { nudged: false, signal: 'orca', watchedMs };
+  if (watched.turn && to.harness === 'claude') return { nudged: false, signal: 'hook', because: 'other-turn', watchedMs };
+
+  const last = atTheGate(to, from, subject, tab, mark, (found) => {
+    // What came while the gate looked, said as it was.
+    if (userTurnSince(mark, notice)) return { nudged: false, signal: 'orca' };
+    const because = watched.turn || !found.idle ? 'other-turn' : 'no-turn';
+    if (!found.idle && to.harness === 'claude') return { nudged: false, signal: 'hook', because };
+    return line(found.handle, to, from, subject, because);
+  });
+  return { ...last, watchedMs };
+}
+
+/**
+ * How long an idle receiver is watched for Orca's notice before the kit types
+ * its line, the architect's ruling for #509. The send returns as soon as the
+ * notice shows, so only a notice that did not come costs the whole of it.
+ */
+export const WATCH_MS = 8000;
+
+/** How long one look in the watch asks Orca to wait for an idle tab, and the pause after an idle one. */
+const WATCH_LOOK_MS = 500;
+
+/**
+ * How long the record is read once a turn has started, for the notice that
+ * started it: the harness writes the turn as it takes it, and a look can see
+ * the turn a moment before the record does.
+ */
+const RECORD_GRACE_MS = 1500;
+
+/** How often the record is read in that time. */
+const RECORD_ASK_MS = 250;
+
+/**
+ * Whether the receiver's record shows Orca's notice within RECORD_GRACE_MS, for
+ * a tab seen busy: the most a send to a receiver busy with other work waits.
+ */
+async function noticeShows(mark, notice) {
+  for (const end = Date.now() + RECORD_GRACE_MS; ; await pause(RECORD_ASK_MS)) {
+    if (userTurnSince(mark, notice)) return true;
+    if (Date.now() >= end) return false;
+  }
+}
+
+/**
+ * Watch an idle receiver for up to WATCH_MS: `{ notice: true }` once its record
+ * shows Orca's notice, `{ turn: true }` once a turn started that the record
+ * does not show as the notice, or `{}` when it stayed at rest; with `ms`, how
+ * long it watched. A look Orca does not answer says nothing, and the watch
+ * goes on to its end.
+ */
+async function watch(handle, mark, notice) {
+  const started = Date.now();
+  const until = started + WATCH_MS;
+  const ms = () => Date.now() - started;
+  for (;;) {
+    if (userTurnSince(mark, notice)) return { notice: true, ms: ms() };
+    const left = until - Date.now();
+    if (left <= 0) return { ms: ms() };
+    const seen = idleNow(handle, Math.min(WATCH_LOOK_MS, left));
+    if (seen === 'busy') return (await noticeShows(mark, notice)) ? { notice: true, ms: ms() } : { turn: true, ms: ms() };
+    if (seen === 'idle') await pause(Math.min(WATCH_LOOK_MS, Math.max(until - Date.now(), 0)));
+  }
+}
 
+/**
+ * Look at the receiver's tab through the gate every typed line goes through,
+ * holding its turn for a line, and answer what `then` makes of a tab that
+ * passed; a tab that did not pass is answered as it was before #509.
+ */
+function atTheGate(to, from, subject, tab, mark, then) {
   // A line typed while the kit types a command one key at a time would land
   // in it and send it with its own return (#480): so the receiver's turn for
   // a line first, for a bounded time, and the mail waits in its mailbox if not.
@@ -472,22 +591,9 @@ function nudge(to, from, subject, tab) {
     const found = lookAt(to);
     if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
     // A line that lands in a shell is run there, with the sender's subject in it.
-    if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure, ...(found.psUnread ? leftForHook(to, from, subject, tab) : {}) };
+    if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure, ...(found.psUnread ? leftForHook(to, from, subject, tab, mark) : {}) };
     if (found.handle === undefined) return { nudged: false };
-
-    const sent = typeIntoTab(
-      found.handle,
-      `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)}`,
-      { watch: true },
-    );
-    // Typed is not taken. A harness busy with a turn queues the line and gives
-    // it no turn of its own, and a line can be lost, and Orca's receipt looks
-    // the same for both: only a turn start it saw says the line landed (#394).
-    if (sent?.send?.prompt?.stages?.includes('turn_started')) return { nudged: true };
-    // Where Orca did not watch the line at all, as when its own notice has
-    // just started a turn in the tab, it saw nothing either way, and says so.
-    if (sent?.send?.prompt?.observation === 'unsupported') return { nudged: true, nudgeUnseen: unseen(sent), nudgeWatched: false };
-    return { nudged: true, nudgeUnseen: unseen(sent) };
+    return then(found);
   } 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
@@ -500,6 +606,24 @@ function nudge(to, from, subject, tab) {
   }
 }
 
+/** Type the kit's line into the receiver's tab, and say what Orca saw of it. */
+function line(handle, to, from, subject, because) {
+  const sent = typeIntoTab(
+    handle,
+    `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)}`,
+    { watch: true },
+  );
+  const said = { nudged: true, signal: 'line', because };
+  // Typed is not taken. A harness busy with a turn queues the line and gives
+  // it no turn of its own, and a line can be lost, and Orca's receipt looks
+  // the same for both: only a turn start it saw says the line landed (#394).
+  if (sent?.send?.prompt?.stages?.includes('turn_started')) return said;
+  // Where Orca did not watch the line at all, as when its own notice has
+  // just started a turn in the tab, it saw nothing either way, and says so.
+  if (sent?.send?.prompt?.observation === 'unsupported') return { ...said, nudgeUnseen: unseen(sent), nudgeWatched: false };
+  return { ...said, nudgeUnseen: unseen(sent) };
+}
+
 /**
  * The nudge a Codex sender could not decide, left for its own hook (#350, ADR
  * 0034): `{ nudgeLeft: true }`, or nothing when it is not left.
@@ -514,12 +638,15 @@ function nudge(to, from, subject, tab) {
  * the receiver's tab: anywhere else no hook would see it, or would see no more
  * than the send did.
  */
-function leftForHook(to, from, subject, tab) {
+function leftForHook(to, from, subject, tab, mark) {
   if (tab === undefined || from.tab !== tab || from.harness !== 'codex') return {};
   try {
     const dir = leftDir(tab);
     mkdirSync(dir, { recursive: true });
-    const left = { bots: to.bots, to: `${to.bot}/${to.session}`, from: `${from.bot}/${from.session}`, subject };
+    // The receiver's record as it stood before the post, so the hook reads
+    // what came after the post and not after itself (#509 review): Orca's
+    // notice can land before the hook runs. None stays none.
+    const left = { bots: to.bots, to: `${to.bot}/${to.session}`, from: `${from.bot}/${from.session}`, subject, mark: mark ?? null };
     // Written under a name the hook does not take, then put in place whole: a
     // hook running beside this send never takes a file still being written.
     const name = path.join(dir, `${stamp()}.${process.pid}`);
@@ -541,7 +668,7 @@ const leftDir = (tab) => path.join(os.tmpdir(), 'obk-nudges', encodeURIComponent
  * once, by one hook. Returns `{ to, subject, ...what the nudge came to }` for
  * each, as the send's own answer says it.
  */
-export function decideLeftNudges(tab) {
+export async function decideLeftNudges(tab) {
   if (tab === undefined) return [];
   const dir = leftDir(tab);
   let names;
@@ -550,30 +677,80 @@ export function decideLeftNudges(tab) {
   } catch {
     return [];
   }
-  return names.flatMap((name) => {
+  const decided = [];
+  for (const name of names) {
     const taking = path.join(dir, `${name}.taking`);
     // Another hook took it first: it is that hook's to decide, and to remove.
     try {
       renameSync(path.join(dir, name), taking);
     } catch {
-      return [];
+      continue;
     }
     let left;
     try {
       left = JSON.parse(readFileSync(taking, 'utf8'));
     } catch {
-      return [];
+      continue;
     } finally {
       rmSync(taking, { force: true });
     }
     try {
       const to = findSession(left.bots, left.to);
       const from = findSession(left.bots, left.from);
-      return [{ to: left.to, subject: left.subject, ...nudge(to, from, left.subject) }];
+      decided.push({ to: left.to, subject: left.subject, ...(await nudge(to, from, left.subject, undefined, left.mark ?? null)) });
     } catch (error) {
-      return [{ to: left.to, subject: left.subject, nudged: false, nudgeTrouble: error.message }];
+      decided.push({ to: left.to, subject: left.subject, nudged: false, nudgeTrouble: error.message });
     }
-  });
+  }
+  return decided;
+}
+
+/**
+ * What the kit's Claude Code hook says at the end of a session's turn (#509,
+ * ADR 0035): the reason the turn goes on with, naming each message the kit sent
+ * this session that Orca still lists as unread, once for each; or undefined,
+ * and the turn ends as it would have.
+ *
+ * It must never hold a session. So it says nothing when Claude Code says a stop
+ * hook is already active, when the kit's hint holds nothing new for the
+ * session (and then it asks Orca nothing), when it cannot ask Orca or read the
+ * hint, and when it cannot first mark what it tells as told: a message is told
+ * once, or not at all. It reads the mailbox only by a peek, as the session's
+ * own tab, so nothing is taken as read.
+ */
+export function stillUnread(bots, bot, said, tab, handle) {
+  if (said?.hook_event_name !== 'Stop' || said.stop_hook_active === true) return undefined;
+  if (tab === undefined || handle === undefined) return undefined;
+  const who = sessionInTab(bots, tab);
+  if (who === undefined || who.bot !== bot || who.mailbox === undefined) return undefined;
+  // Only the conversation the book holds for this tab: a harness started
+  // inside the session runs the same hook in the same tab, and would take the
+  // session's one telling (#509 review), as the naming hook guards (#480).
+  if (typeof said.session_id !== 'string' || said.session_id !== who.conversation) return undefined;
+  const untold = unreadOf(who.home, who.session).filter((entry) => !entry.told);
+  if (untold.length === 0) return undefined;
+
+  const found = readMailbox(who.mailbox, { peek: true, handle }, { timeoutMs: HOOK_ASK_MS });
+  const waiting = new Map((found.messages ?? []).map((message) => [message.id, message]));
+  const tell = untold.filter((entry) => waiting.has(entry.id));
+  if (tell.length === 0) return undefined;
+  markTold(who.home, who.session, tell.map((entry) => entry.id));
+
+  const lines = tell.map((entry) => `- from ${entry.from}: "${entry.subject}", which came at ${clockOf(waiting.get(entry.id).created_at ?? entry.at)}`);
+  return [
+    `${tell.length === 1 ? 'A fleet mail sent to you is' : `${tell.length} fleet mails sent to you are`} still unread. This is not new mail; it is told once:`,
+    ...lines,
+    `Read it with  ${shellWord(ownCli())} message check --bots ${shellWord(who.bots)} --bot ${shellWord(who.bot)} --session ${shellWord(who.session)}`,
+  ].join('\n');
+}
+
+/** How long the turn-end hook gives Orca, well inside the 30 s the harness gives the hook. */
+const HOOK_ASK_MS = 10_000;
+
+/** A time as a clock reads it, in UTC; what cannot be read is said as it is. */
+function clockOf(at) {
+  const when = new Date(typeof at === 'string' && /^\d{4}-\d\d-\d\d \d/.test(at) ? `${at.replace(' ', 'T')}Z` : at);
+  return Number.isNaN(when.getTime()) ? String(at) : `${when.toISOString().slice(11, 16)} UTC`;
 }
 
 /** Orca's words about a line it did not see start a turn, or what its receipt says when it gives none. */

package/src/name.js

@@ -125,12 +125,13 @@ function nameOf(thread) {
  * pointer and the command exactly, and no row of its slash menu stands above
  * it. With words after the command Codex has closed its menu (chat_composer.rs
  * `sync_command_popup`, rust-v0.160.0), so a menu still open means the line is
- * not what it seems.
+ * not what it seems. Where Orca gives a draft, the draft is the line's text:
+ * Codex 0.162.0's line on the screen then reads its pointer alone (#516).
  */
-function renameWrong(rows, _harness, command) {
+function renameWrong(rows, _harness, command, _version, draft) {
   const at = rows.findLastIndex((row) => /^ *›/.test(row));
   if (at < 0) return { why: 'its screen shows no input line' };
-  const line = rows[at].replaceAll(' ', ' ').trim();
+  const line = draft === undefined ? rows[at].replaceAll(' ', ' ').trim() : `› ${draft}`;
   if (line !== `› ${command}`) return { why: `its input line reads "${line}"` };
   const above = rows.slice(0, at).findLast((row) => row.trim() !== '');
   if (above !== undefined && /^ *(?:› +)?\/\S/.test(above)) return { why: `a menu of commands stands above its input line: "${above.trim()}"` };

package/src/orca.js

@@ -8,9 +8,10 @@
 // handed to Orca on the command line.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 
 import { SHELL_ENV } from './launch.js';
@@ -135,7 +136,14 @@ export const profilesDir = () => path.join(homedir(), 'Library', 'Application Su
  *
  * Orca adds these to the agents it launches, relaunches and resumes itself, so
  * they override the approval level a session was started with (PRD 6.5). The
- * kit reads the file and never writes it.
+ * kit reads Orca's files and never writes them.
+ *
+ * Orca 1.4.223 keeps them in `profile-state.db`, and older Orca in
+ * `orca-data.json` (tech notes, section 1). Orca's CLI has no command that
+ * prints them. A profile is read from its db when the db holds a settings
+ * document, and from the json file otherwise. A db that cannot be read is not
+ * passed over for the json beside it, which an upgraded Orca no longer keeps up
+ * to date.
  *
  * A mapping with no entry for an agent is not "no arguments": Orca falls back
  * to its own built-in default, which is the permission bypass itself (tech
@@ -153,17 +161,98 @@ export function orcaDefaultArgs() {
 
   return {
     dir,
-    profiles: profiles
-      .map((name) => path.join(dir, name, 'orca-data.json'))
-      .filter((file) => existsSync(file))
-      .map((file) => ({ file, args: argsIn(file) })),
+    profiles: profiles.map((name) => argsOfProfile(path.join(dir, name))).filter((one) => one !== undefined),
   };
 }
 
-/** What one profile file says about the agents' default arguments. */
-function argsIn(file) {
+/** What one profile says about the agents' default arguments, or undefined when it keeps no settings. */
+function argsOfProfile(profile) {
+  const db = path.join(profile, 'profile-state.db');
+  const json = path.join(profile, 'orca-data.json');
+
+  if (existsSync(db)) {
+    let payload;
+    try {
+      payload = settingsPayloadIn(db);
+    } catch {
+      return { file: db, args: undefined };
+    }
+    if (payload !== null) return { file: db, args: argsIn(() => JSON.parse(payload)) };
+  }
+  if (existsSync(json)) return { file: json, args: argsIn(() => JSON.parse(readFileSync(json, 'utf8'))?.settings) };
+  // A db with no settings document and no older file beside it: a store the
+  // kit does not know how to read, which it says rather than pass over.
+  return existsSync(db) ? { file: db, args: undefined } : undefined;
+}
+
+/**
+ * The `settings` document in Orca's `profile-state.db`, as text, or null when
+ * the db has none. Throws when the db cannot be read.
+ *
+ * Orca holds the db open in WAL mode, and its current settings may be in the
+ * `-wal` alone. A SQLite open of Orca's own file, read-only included, writes
+ * reader marks into its `-shm` and is refused while Orca holds the db in
+ * exclusive mode. So the kit reads a copy: the `-wal` and then the db, into a
+ * private folder of its own (0700, as mkdtemp makes it), removed straight after
+ * on every path.
+ *
+ * A copy Orca changed under it is thrown away: a part of the `-wal` laid over a
+ * db Orca has just checkpointed reads as older settings than Orca's own. So the
+ * two files are noted before and after, and a copy is read only when neither
+ * moved; after COPY_TRIES copies that all moved, the db counts as unreadable.
+ * The bytes are read whole and written out rather than copied with
+ * `copyFileSync`, which on macOS never returns when its source is truncated
+ * under it, as a checkpoint truncates the `-wal` (#507).
+ */
+function settingsPayloadIn(db) {
+  const copyDir = mkdtempSync(path.join(tmpdir(), 'obk-orca-'));
+  try {
+    const copy = path.join(copyDir, path.basename(db));
+    for (let tries = 0; tries < COPY_TRIES; tries += 1) {
+      const before = stateOf(db);
+      const wal = bytesIfThere(`${db}-wal`);
+      rmSync(`${copy}-wal`, { force: true });
+      if (wal !== undefined) writeFileSync(`${copy}-wal`, wal);
+      writeFileSync(copy, readFileSync(db));
+      if (stateOf(db) !== before) continue;
+
+      const store = new DatabaseSync(copy);
+      try {
+        const row = store.prepare("SELECT payload FROM profile_state_documents WHERE domain = 'settings'").get();
+        return row === undefined ? null : row.payload;
+      } finally {
+        store.close();
+      }
+    }
+    throw new Error(`${db} changed during each of ${COPY_TRIES} copies`);
+  } finally {
+    rmSync(copyDir, { recursive: true, force: true });
+  }
+}
+
+/** How many copies of Orca's db the kit makes before it gives up on one that keeps changing. */
+const COPY_TRIES = 3;
+
+/** Where Orca's db and its `-wal` stand: one string that changes whenever either file does. */
+const stateOf = (db) => [db, `${db}-wal`].map((file) => {
+  const stat = statSync(file, { bigint: true, throwIfNoEntry: false });
+  return stat === undefined ? 'none' : `${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}).join('|');
+
+/** The bytes of `file`, or undefined when there is no such file. */
+function bytesIfThere(file) {
   try {
-    const settings = JSON.parse(readFileSync(file, 'utf8'))?.settings?.agentDefaultArgs;
+    return readFileSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+/** What one settings document, given by `read`, says about the agents' default arguments. */
+function argsIn(read) {
+  try {
+    const settings = read()?.agentDefaultArgs;
     // Anything that is not a mapping of agents is a mapping with nothing in it,
     // which is Orca falling back to its own defaults for every agent.
     return settings !== null && typeof settings === 'object' && !Array.isArray(settings) ? settings : {};
@@ -323,6 +412,23 @@ export const openTab = (home, title) =>
 export const retitleTab = (handle, title) =>
   orca(['terminal', 'rename', '--terminal', handle, '--title', title]).rename;
 
+/**
+ * One quick look at whether the harness in a tab is at rest, for a caller that
+ * already knows a harness is there and is watching for a turn to start (#509):
+ * `idle` when Orca's tui-idle answers ok, `busy` when it times out, and
+ * `unknown` when Orca refuses or does not answer within `waitMs` and a second
+ * more. Never throws.
+ */
+export function idleNow(handle, waitMs) {
+  try {
+    const answer = ask(['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(waitMs)], waitMs + 1000);
+    if (answer.ok === true) return answer.result?.wait?.blockedReason === undefined ? 'idle' : 'unknown';
+    return answer.error?.code === 'timeout' ? 'busy' : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 /**
  * What can be learned about the harness in a tab: what Orca says, and who is
  * in front of the tab's terminal.
@@ -384,13 +490,16 @@ export const QUESTION_ON_SCREEN = 'question-on-screen';
  */
 function screenOf(handle, readMs) {
   const read = screenRows(handle, readMs);
-  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows), rows: read.rows };
+  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows), rows: read.rows, draft: read.draft };
 }
 
 /**
- * The rows the tab `handle` renders, `{ rows }`, or `{ unreadable: <why> }`.
+ * The rows the tab `handle` renders, `{ rows, draft }`, or `{ unreadable: <why> }`.
  * Orca refusing, or answering with anything but the rendered screen, is a
- * screen that cannot be read, not an error.
+ * screen that cannot be read, not an error. `draft` is the text in the
+ * harness's input line, undefined when there is none: Orca 1.4.223 gives it
+ * beside the rows, and Claude Code 2.1.296's input line in the rows then reads
+ * its pointer alone (#510, probe 4).
  */
 export function screenRows(handle, readMs) {
   let read;
@@ -402,7 +511,7 @@ export function screenRows(handle, readMs) {
   if (read?.source !== 'screen' || !Array.isArray(read.tail)) {
     return { unreadable: `Orca gave no rendered screen for it (source: ${read?.source ?? 'none'})` };
   }
-  return { rows: read.tail };
+  return { rows: read.tail, draft: typeof read.draft === 'string' && read.draft !== '' ? read.draft : undefined };
 }
 
 /** A row the harness starts with its selection pointer: `›` on Codex, `❯` on Claude Code. */
@@ -513,7 +622,7 @@ function pointedChoiceAt(rows, at) {
  * may: `{ handle, agent }`, with the agent Orca names there. Otherwise nothing
  * is typed, and the answer says why. `idle` says whether Orca's `tui-idle` wait
  * answered ok, and `rows` is the screen the gate read, for a caller that must
- * not type into a busy harness (#391):
+ * not type into a busy harness (#391), with the `draft` Orca gave beside it (#510):
  * `{}` for a tab with no harness in it (none in the book, none Orca lists, or
  * the shell in front), `{ blocked }` for one with something on screen waiting
  * to be answered, and `{ unsure }`, a sentence, for one the kit cannot tell
@@ -576,7 +685,7 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   if (seen.question === undefined) {
     return { unsure: `the kit could not tell whether a question is waiting on its screen (${seen.screenUnreadable}), so nothing was typed` };
   }
-  return { handle: live.handle, agent: seen.agent, idle: seen.answered, rows: seen.rows };
+  return { handle: live.handle, agent: seen.agent, idle: seen.answered, rows: seen.rows, draft: seen.draft };
 }
 
 /**
@@ -908,6 +1017,22 @@ export const useMailbox = (id, handle, options) =>
 export const coordinatorOf = (id, options) =>
   orca(['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
+ * on another machine (#508). Only `run-show` refused `run_not_found` says so:
+ * `run-use` gives a legacy Run the same code and words, and a Run shown, a
+ * time-out or any other refusal is not a Run known to be missing (tech notes,
+ * section 1).
+ */
+export function runMissing(id, options) {
+  try {
+    orca(['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>`. */
 export function postMessage({ to, from, subject, body, type = 'status', thread }) {
   const args = ['orchestration', 'send', '--to', to, '--subject', subject, '--body', body, '--type', type];