@assuredloop/orca-bot-kit 0.32.0 → 0.34.0

package/README.md

@@ -5,14 +5,14 @@ a manager, developers, reviewers, a personal helper. Each bot keeps its
 identity, its rules, its skills and its sessions across restarts.
 
 [Orca](https://github.com/stablyai/orca) is the host: a bot is an Orca project
-and a session is a tab, on Claude Code or Codex. The kit is an npm package with
+and a session is a tab, on Claude Code, Codex or Pi. The kit is an npm package with
 an `obk` command and a set of skills. You are meant to manage the fleet by
 talking to Bot Father, the first bot, whose skills call the CLI for you — not by
 editing files.
 
 The design is in [`docs/prd/prd.md`](docs/prd/prd.md); the decisions with lasting
 consequences are in [`docs/adr/`](docs/adr/); what we know about Orca and the
-two harnesses is in [`docs/tech-notes.md`](docs/tech-notes.md).
+harnesses is in [`docs/tech-notes.md`](docs/tech-notes.md).
 
 ## Start here
 
@@ -51,13 +51,13 @@ details and, when you say so, files the issue or gives you the text to paste.
 ## Status
 
 Early. The CLI creates your bots folder, brings Bot Father up in Orca, creates
-bots and their sessions on either harness, and builds each bot's `AGENTS.md`
-from its charter and the rules it carries.
+bots and their sessions on any of the three harnesses, and builds each bot's
+`AGENTS.md` from its charter and the rules it carries.
 
 ## Install
 
-Node.js >= 24.21.0, git, and Orca with at least one of Claude Code or Codex
-installed and configured. That line because the kit keeps writers out of each
+Node.js >= 24.21.0, git, and Orca with at least one of Claude Code, Codex or
+Pi installed and configured. That line because the kit keeps writers out of each
 other's way in a bot's book with a SQLite write transaction, through Node's own
 `node:sqlite`. That module is older than the 24 line; 24.21.0 is the first
 release measured here that loads it without an experimental warning on stderr,
@@ -86,8 +86,8 @@ to npm with a provenance statement. Nothing else publishes.
 obk init --bots /absolute/path/to/my-bots --harness claude
 ```
 
-`--harness claude|codex` says which harness Bot Father itself runs on; there is
-no default. This makes the folder a git repository and seeds it:
+`--harness claude|codex|pi` says which harness Bot Father itself runs on; there
+is no default. This makes the folder a git repository and seeds it:
 
 ```
 my-bots/
@@ -163,8 +163,8 @@ setting: name a model that carries it. A Pi session reads its bot's
 no permission rules and no hooks, so the bot's allow list does not limit a Pi
 session. `obk health` reads a Pi session's model and thinking level from Pi's
 own record, and says when Pi cannot run it. `obk session clear` types Pi's
-`/new` into a Pi tab. `obk session compact` on Pi types nothing, and says so.
-`obk init --harness pi` and `obk session compact` on Pi come later.
+`/new` into a Pi tab, and `obk session compact` types Pi's `/compact`.
+`obk init --harness pi` puts Bot Father itself on Pi.
 
 Every bot gets the kit's default permission rules, written by the kit with
 nobody asked: its own commands for this bots folder, reading a long message,
@@ -535,8 +535,8 @@ leaves it running until the session is next restarted; after that, `--on --at`
 puts it back.
 `obk groom --compact` compacts its conversation between runs.
 
-The grooming session is always a Claude Code one, even on a Codex Bot Father (add
-it with `--harness claude` there): it is the clock, and where the reports arrive.
+The grooming session is always a Claude Code one, even on a Codex or Pi Bot Father
+(add it with `--harness claude` there): it is the clock, and where the reports arrive.
 To have the grooming itself done on Codex, turn it on with `--run-on codex`, and
 give the runs their model and effort:
 

package/SETUP.md

@@ -20,7 +20,7 @@ Everything else you can find out by looking.
 ## What you are making
 
 Orca is the host. A bot is an Orca project and a session is a tab, running
-Claude Code or Codex. You are making the first bot, **Bot Father**, and a folder
+Claude Code, Codex or Pi. You are making the first bot, **Bot Father**, and a folder
 that holds the whole fleet's configuration as a git repository of theirs.
 
 When you are done they will have an Orca project called Bot Father with two
@@ -38,7 +38,7 @@ git --version
 /Applications/Orca.app/Contents/Resources/bin/orca status --json
 claude --version                                        # at least one of these
 codex --version                                         # 0.156.1 or newer
-pi --version                                            # 1.3.0, for a bot on Pi
+pi --version                                            # 1.3.0
 ```
 
 The Orca line must come back with `ok: true` and `result.runtime.reachable:
@@ -63,7 +63,7 @@ If Node is older than 24.21.0, say so and stop. The kit's book of sessions is a
 SQLite write transaction through Node's own `node:sqlite`, and 24.21.0 is the
 first release measured here that loads it without an experimental warning.
 
-If neither harness is installed, say so and stop. If only one is, that is fine,
+If no harness is installed, say so and stop. If only one is, that is fine,
 and it is the one Bot Father will run on.
 
 If Codex is older than 0.156.1, say so and ask them to update it before a bot
@@ -121,15 +121,19 @@ book of sessions. It holds none of the kit's code. The bots commit their own
 changes to it; the kit's commands never commit, and pushing it somewhere is
 theirs to decide.
 
-**Which harness Bot Father runs on**, `claude` or `codex`. There is no default
-and the kit will not guess. It is Bot Father's own harness only; each bot they
-make later chooses its own. If only one harness is installed, say so and confirm
-it rather than asking as though the choice were open.
+**Which harness Bot Father runs on**, `claude`, `codex` or `pi`. There is no
+default and the kit will not guess. It is Bot Father's own harness only; each
+bot they make later chooses its own. If only one harness is installed, say so
+and confirm it rather than asking as though the choice were open. If they choose
+`pi`, they sign in to Pi themselves first: the kit never handles Pi's
+credentials, and `obk init` starts nothing while Pi can use no model. When you
+ask or confirm, tell them: "On Pi, Bot Father acts without asking first, because
+Pi has no approval step."
 
 ## 4. Make the fleet
 
 ```sh
-obk init --bots <their path> --harness claude|codex
+obk init --bots <their path> --harness claude|codex|pi
 ```
 
 This makes the folder a git repository, seeds it, writes Bot Father, and opens

package/package.json

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

package/skills/obk-grooming/SKILL.md

@@ -242,8 +242,9 @@ places and sending one to the other loses it.
 The pass runs in a session of Bot Father's own, `grooming`, on Claude Code's
 own scheduler. Add it like any session, with the model and effort it is to run
 at: `obk session add --bots <folder> --bot bot-father --name grooming --model
-<m> --effort <e>`, with `--harness claude` where Bot Father runs on Codex, then
-`obk up`. Its launch line carries them, so they are what every run uses.
+<m> --effort <e>`, with `--harness claude` where Bot Father runs on Codex or
+Pi, then `obk up`. Its launch line carries them, so they are what every run
+uses.
 
 The runs can be done on Codex instead. The session stays this Claude Code one,
 the clock and the reader, and `obk groom --on --at <HH:MM> --run-on codex

package/src/bot.js

@@ -791,7 +791,7 @@ function asMapping(bot, file) {
 export function requireBotsFolder(bots) {
   const dir = botsDir(bots);
   if (statSync(dir, { throwIfNoEntry: false })?.isDirectory() !== true) {
-    throw new Error(`${bots} is not a bots folder: run obk init --bots <path> --harness claude|codex first.`);
+    throw new Error(`${bots} is not a bots folder: run obk init --bots <path> --harness claude|codex|pi first.`);
   }
   return dir;
 }

package/src/clear.js

@@ -16,7 +16,7 @@ import { setTimeout as pause } from 'node:timers/promises';
 
 import { readBook, takeTypingTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, readBot } from './bot.js';
-import { claudeTranscript, codexRollout } from './conversations.js';
+import { claudeTranscript, codexRollout, piSession } from './conversations.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 import { eachLine, firstLine } from './lines.js';
 import { FEEDBACK_PANEL, feedbackPanelIn, findProject, orca, piAtWorkIn, piBox, QUESTION_ON_SCREEN, questionIn, screenRows, tabs, tabToTypeInto, TIMED_OUT } from './orca.js';
@@ -25,7 +25,7 @@ import { botsNamed, sessionsOf, typeListLine } from './up.js';
 /** The harness's own command for each, as typed into its input line. Codex's and Pi's clear is `/new` (tech notes, sections 3 and 6). */
 const COMMANDS = {
   clear: { claude: '/clear', codex: '/new', pi: '/new' },
-  compact: { claude: '/compact', codex: '/compact' },
+  compact: { claude: '/compact', codex: '/compact', pi: '/compact' },
 };
 
 /** The pointer each harness starts its input line with (tech notes, section 1). */
@@ -111,7 +111,7 @@ const PI_SELECTED = /^ *→ +/;
  * (or null) and the one it holds now.
  */
 export async function clearSession(bots, { bot, session }) {
-  const it = sessionToType(bots, bot, session, 'clear');
+  const it = sessionToType(bots, bot, session);
   const was = readBook(it.home).sessions[session]?.session ?? null;
   const { command, handle, typing } = await enter(it, 'clear');
 
@@ -147,7 +147,7 @@ export async function clearSession(bots, { bot, session }) {
  * command began, and not yet when COMPACT_MS passed without one.
  */
 export async function compactSession(bots, { bot, session }) {
-  const it = sessionToType(bots, bot, session, 'compact');
+  const it = sessionToType(bots, bot, session);
   // What the record holds when /compact is typed is not this compact's: one
   // that ends while the kit waits for the session to be idle is the one
   // before it (review of PR #466). So only what is written after counts.
@@ -174,17 +174,13 @@ export async function compactSession(bots, { bot, session }) {
 /**
  * The session as something to type into, once everything that refuses before
  * Orca is asked to type has been asked: `{ name, home, session, harness, tabId }`.
- * A compact is refused on Pi: a later slice of #547 may add it.
  */
-export function sessionToType(bots, bot, session, verb) {
+export function sessionToType(bots, bot, session) {
   botsNamed(bots, bot);
   const home = realpathSync(botDir(bots, bot));
   const known = readBot(home, bot);
   const [settings] = sessionsOf(known, session);
   const name = `${bot} ${session}`;
-  if (verb === 'compact' && harnessOf(settings, known.harness) === 'pi') {
-    throw new Error(`${name} runs on Pi, and obk session ${verb} does not work on a Pi session yet: a later slice of #547 adds it. Nothing was typed.`);
-  }
   const unpause = `${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${bot}`;
   if (known.paused === true) throw new Error(`${bot} is paused, so ${name} is not running and nothing was typed. Bring it back with ${unpause}.`);
   if (settings.paused === true) throw new Error(`${name} is paused, so it is not running and nothing was typed. Bring it back with ${unpause} --session ${session}.`);
@@ -217,6 +213,7 @@ async function enter(it, verb, before = () => {}) {
         before();
       },
       cannot: (wrong) => (verb === 'compact' && wrong.menu && it.harness === 'codex' ? ` ${harnessName(it.harness)} here cannot compact: its menu does not offer ${COMMANDS[verb][it.harness]}.` : ''),
+      close: it.harness === 'pi' ? PI_CLOSE : undefined,
     });
     return { ...typed, typing };
   } catch (error) {
@@ -231,11 +228,12 @@ async function enter(it, verb, before = () => {}) {
  * screen: by default the slash menu's check, which a command with words after
  * it does not pass, since Codex closes its menu at the space (#480). `before`
  * runs just before the command is typed; `cannot` adds to a refusal what a
- * wrong screen means; past `deadline`, a time, what was typed is taken back
- * and nothing is entered. Returns the command, the handle it went into, and
- * when it was typed.
+ * wrong screen means; `close`, `{ key, check }`, is one more key typed once
+ * `check` passes, and its own check of the screen before the return; past
+ * `deadline`, a time, what was typed is taken back and nothing is entered.
+ * Returns the command, the handle it went into, and when it was typed.
  */
-export async function typeCommand(it, command, { before = () => {}, check = menuWrong, cannot = () => '', deadline = Infinity } = {}) {
+export async function typeCommand(it, command, { before = () => {}, check = menuWrong, cannot = () => '', close, deadline = Infinity } = {}) {
   // Nothing may be in the input line before: no draft for the command to join.
   // Orca gives a draft in the line beside the screen, and the screen's line
   // then reads the pointer alone (#510, #516). Where it gives none, Codex's
@@ -299,22 +297,31 @@ export async function typeCommand(it, command, { before = () => {}, check = menu
     takeBack();
     throw new Error(`${it.name}: ${command} was being typed, and after ${sofar} ${look.why}, so what was typed was taken back and nothing was entered.`);
   };
+  const typeKey = (char) => {
+    try {
+      send(handle, char);
+    } catch (error) {
+      // A send Orca did not answer in time may have gone in all the same.
+      // Counted only where the line was empty before the first key, so the
+      // one backspace too many can take nothing of the user's (#480 review).
+      if (error.code === TIMED_OUT && (it.harness === 'codex' || it.harness === 'pi')) typed += 1;
+      throw error;
+    }
+    typed += 1;
+  };
   try {
     for (const char of command) {
       if (typed > 0) await lookAgain();
-      try {
-        send(handle, char);
-      } catch (error) {
-        // A send Orca did not answer in time may have gone in all the same.
-        // Counted only where the line was empty before the first key, so the
-        // one backspace too many can take nothing of the user's (#480 review).
-        if (error.code === TIMED_OUT && (it.harness === 'codex' || it.harness === 'pi')) typed += 1;
-        throw error;
-      }
-      typed += 1;
+      typeKey(char);
     }
     await lookAgain();
     let wrong = await typedWrong(handle, it.harness, command, version, check);
+    if (wrong === undefined && close !== undefined) {
+      await lookAgain();
+      typeKey(close.key);
+      await lookAgain();
+      wrong = await typedWrong(handle, it.harness, command, version, close.check);
+    }
     if (wrong === undefined && Date.now() > deadline) wrong = { why: 'its time ran out' };
     if (wrong !== undefined) {
       takeBack();
@@ -498,8 +505,7 @@ function codexMenuWrong(rows, at, line, command, version) {
  * So the editor's one row, or Orca's draft where it gives one, reads the
  * command, and the selected row below the box names it. A menu still drawn
  * for an earlier part of the command looks the same when its selected row is
- * the command too: the kit's gap between keys and its reads make that
- * unlikely, and this cannot tell it apart.
+ * the command too, and this cannot tell it apart: PI_CLOSE does.
  */
 function piMenuWrong(rows, command, draft) {
   const box = piBox(rows);
@@ -514,6 +520,32 @@ function piMenuWrong(rows, command, draft) {
   return undefined;
 }
 
+/**
+ * Pi 1.3.0 applies a menu list still drawn from an earlier key against that
+ * key's prefix, so `/compact` under a list for `/compa` submits `/ccompact`,
+ * and `/new` under one for `/n` submits `/nnew`; the screen cannot tell that
+ * list from a fresh one. A space makes Pi list `/compact ` or `/new `, for
+ * which it has nothing, and so close the menu; with no menu, Return submits
+ * the line trimmed, the command (tech notes, section 6; #671, #673).
+ */
+const PI_CLOSE = { key: ' ', check: (rows, harness, command, version, draft) => piClosedWrong(rows, command, draft) };
+
+/**
+ * Why the screen does not show Pi's editor reading `command`, a space after
+ * it, with no menu below the box, or undefined when it does. A list still
+ * drawn has its selected row.
+ */
+function piClosedWrong(rows, command, draft) {
+  const box = piBox(rows);
+  if (box === undefined) return { why: 'its screen shows no input box' };
+  const lines = box.editor.map((row) => row.trim()).filter((row) => row !== '');
+  const line = draft?.trim() ?? lines.join(' ⏎ ');
+  if (line !== command || (draft === undefined && lines.length !== 1)) return { why: `its input line reads "${line}" after the space` };
+  const selected = box.below.find((row) => PI_SELECTED.test(row));
+  if (selected !== undefined) return { why: `a menu is still below its input box after the space, its selected row "${selected.trim()}"` };
+  return undefined;
+}
+
 /** The Codex version that wrote the rollout of `conversation`, from its session_meta line; undefined when that cannot be read. */
 function codexVersion(conversation) {
   const file = typeof conversation === 'string' ? codexRollout(conversation) : undefined;
@@ -553,6 +585,7 @@ async function answerWhereToRun(it, handle, command) {
 /** Where the harness keeps the record of `conversation`, or undefined when it has none yet. */
 function recordFile(harness, home, conversation) {
   if (conversation === null) return undefined;
+  if (harness === 'pi') return piSession(home, conversation);
   return harness === 'claude' ? claudeTranscript(home, conversation) : codexRollout(conversation);
 }
 
@@ -585,9 +618,9 @@ function compactedSince(harness, record, since) {
       } catch {
         return false;
       }
-      // Claude Code's marker, and Codex's (tech notes, sections 2 and 3).
-      const compaction = harness === 'claude'
-        ? entry?.type === 'system' && entry.subtype === 'compact_boundary'
+      // Claude Code's marker, Codex's, and Pi's (tech notes, sections 2, 3 and 6).
+      const compaction = harness === 'claude' ? entry?.type === 'system' && entry.subtype === 'compact_boundary'
+        : harness === 'pi' ? entry?.type === 'compaction'
         : entry?.type === 'compacted';
       found = compaction && Date.parse(entry.timestamp) >= since;
       return found;

package/src/cli.js

@@ -12,7 +12,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
-import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, disallowRules, leadsOutside, readBot, refuseCodexOutside, SESSION_FIELDS, setRoleCaps, setTempApproval } from './bot.js';
+import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, disallowRules, displayName, leadsOutside, readBot, refuseCodexOutside, SESSION_FIELDS, setRoleCaps, setTempApproval } from './bot.js';
 import { COMMANDS } from './commands.js';
 import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
@@ -39,7 +39,7 @@ import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 const USAGE = `obk — Orca Bot Kit.
 
 Usage:
-  obk init --bots <path> --harness claude|codex
+  obk init --bots <path> --harness claude|codex|pi
                             Create your bots folder: a git repo holding your
                             bots' configuration, with Bot Father in it, and
                             open Bot Father in Orca.
@@ -610,8 +610,6 @@ async function record(bots, bot) {
 
 const commands = {
   async init(bots, values) {
-    // Bot Father on Pi is not in the first slice of #547.
-    if (values.harness === 'pi') throw new Error('init does not take --harness pi yet: Bot Father runs on claude or codex, and its other bots may run on Pi. Nothing was written.');
     // Asked before anything is written, so an Orca that is down leaves the disk
     // exactly as it was and the caller can simply run the command again.
     refuseWhenOrcaIsDown();
@@ -1934,12 +1932,17 @@ function tabLines({ bots, created, completed, rules, skills, permissions = [], t
     const back = one.session === undefined ? '' : ` --session ${one.session}`;
     lines.push(`${'paused'.padEnd(9)}  ${what}  left closed. Bring it back:  ${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${one.bot}${back}`);
   }
+  // A window that has not loaded a bot's project gives its tabs no notice of
+  // mail (#676).
+  for (const one of projects.filter((project) => project.windowTrouble !== undefined)) {
+    lines.push(`${'window'.padEnd(9)}  ${displayName(one.bot)}  its tabs may get no fleet mail until Orca's window loads its project: ${one.windowTrouble}. Try again:  ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${one.bot}`);
+  }
 
   // Last before the summary, because what a check found is about the setup the
   // run has just left behind rather than about any one thing it did.
   lines.push(...foundLines(found));
   // Hedged, because nothing here can see whether the window was told (#224).
-  if (projects.length > 0) lines.push(RELOAD_LINE);
+  if (projects.some((project) => project.change !== undefined)) lines.push(RELOAD_LINE);
   lines.push(summary);
   return lines;
 }

package/src/conversations.js

@@ -49,7 +49,7 @@ const PI_FILE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z_(.+)\.jsonl$/;
 const piIdOf = (name) => PI_FILE.exec(name)?.[1];
 
 /** Where Pi keeps the conversation `id` of this bot home, or undefined when it has none yet. */
-const piSession = (home, id) => {
+export const piSession = (home, id) => {
   const name = files(piDir(home)).find((one) => piIdOf(one) === id);
   return name === undefined ? undefined : path.join(piDir(home), name);
 };

package/src/init.js

@@ -97,7 +97,8 @@ charter: |
   names in paths, tokens, what a charter says. Put in the command that was run
   and its whole output, what you expected instead, and what these print:
   obk --version, obk health --bots <folder> --json, node --version, the Orca
-  version, and claude --version or codex --version; and the operating system.
+  version, and claude --version, codex --version or pi --version; and the
+  operating system.
   One problem per issue. If you cannot file it yourself, give your owner the
   text to paste.
 rules: []

package/src/message.js

@@ -18,11 +18,12 @@
 
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 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 { harnessOf, isAddressOf, kitFolders, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
-import { ackMailbox, coordinatorOf, postMessage, pressEscape, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, useMailbox } from './orca.js';
+import { ackMailbox, coordinatorOf, listedOrphaned, loadInWindow, postMessage, pressEscape, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -161,7 +162,7 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
 
   const written = bodyOf(bots, { from, to, subject, text, textFile });
   // Looked at before the post, which is the send's last call to Orca (PRD 6.9).
-  const shown = loaded(to);
+  const shown = await loaded(to);
   // The Escape goes first, so the turn has ended when the letter is in.
   const interrupted = interrupt ? interruptBusy(to) : {};
   const message = postMessage({
@@ -189,20 +190,50 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
  * and lists one it has not as orphaned, as after a window restart (#579; tech
  * notes, section 1). So an orphaned tab is said, with its handle, and a
  * listing that cannot be read is said too, rather than taken for a loaded tab.
- * The look is made once: a tab orphaned after the send is not seen here.
+ * An orphaned tab of a project the window has never fetched is loaded by
+ * `loadInWindow`, which changes nothing on screen, so the kit asks for that
+ * and looks again until LOOK_MS after the ask (#676). A tab it does not load,
+ * as after a window restart (#579), is said as before. This is all before the
+ * send: a tab orphaned after it is not seen here.
  */
-function loaded(to) {
+async function loaded(to) {
   if (to.tab === undefined) return {};
-  let listed;
+  let tab;
   try {
-    listed = tabs(to.home, { timeoutMs: LOOK_MS });
+    tab = tabs(to.home, { timeoutMs: LOOK_MS }).find((one) => one.tabId === to.tab);
   } catch (error) {
     return { loadTrouble: error.message };
   }
-  const tab = listed.find((one) => one.tabId === to.tab);
-  return tab?.orphaned === true ? { orphaned: true, handle: tab.handle } : {};
+  if (tab?.orphaned !== true) return {};
+  return (await loadedNow(to.home, tab.handle)) ? {} : { orphaned: true, handle: tab.handle };
 }
 
+/**
+ * Whether the window loads the orphaned tab `handle` at `home` once asked to.
+ * The ask and every look after it keep to one deadline, LOOK_MS from the ask,
+ * and each Orca call gets only the time that is left, so a slow Orca cannot
+ * hold the send up for longer (#676). A look that fails or runs out counts as
+ * a tab still orphaned.
+ */
+async function loadedNow(home, handle) {
+  const until = Date.now() + LOOK_MS;
+  const left = () => until - Date.now();
+  loadInWindow(home, { timeoutMs: LOOK_MS });
+  try {
+    for (let ms = left(); ms > 0; ms = left()) {
+      if (!listedOrphaned(home, handle, { timeoutMs: ms })) return true;
+      const wait = Math.min(RELOOK_MS, left());
+      if (wait > 0) await pause(wait);
+    }
+  } catch {
+    // A look that fails or runs out leaves the tab said as orphaned.
+  }
+  return false;
+}
+
+/** How long the kit waits between two looks at a tab it asked the window to load: it was loaded within 0.4 s, live (#676). */
+const RELOOK_MS = 200;
+
 /**
  * What is waiting for a session, and the reading of it.
  *

package/src/orca.js

@@ -347,6 +347,29 @@ const CLIENT_KILL_MS = 3000;
  */
 export const tellWindow = (projectId) => askRuntime('project.update', { projectId, updates: {} }) !== undefined;
 
+/**
+ * Have Orca's window load the tabs of the Orca project at `home`: undefined
+ * when Orca took the call, or what went wrong.
+ *
+ * The window loads a project's tabs only once it has fetched the project's
+ * worktrees, and nothing fetches them for a project the kit made, so its tabs
+ * stay orphaned and get no notice of mail (#676, tech notes). `worktree set`
+ * with no field writes an empty change and has Orca send the window the event
+ * that fetches them: nothing the user sees changes. What went wrong is said
+ * without Orca's own words, which name worktrees (PRD KIT-22: the kit says
+ * "Orca project"). `options` are `orca`'s.
+ */
+export function loadInWindow(home, options) {
+  try {
+    orca(['worktree', 'set', '--worktree', `path:${home}`], options);
+    return undefined;
+  } catch (error) {
+    return typeof error.code === 'string' && !/worktree/i.test(error.code)
+      ? `Orca refused the call (${error.code})`
+      : 'Orca gave no answer the kit could read';
+  }
+}
+
 /**
  * One call to Orca's runtime for a method its CLI does not offer, and the
  * runtime's answer, or undefined when there is none to be had.
@@ -433,6 +456,14 @@ export const tabs = (home, options) => orca(['terminal', 'list', '--worktree', `
     ? { ...tab, tabId: orca(['terminal', 'show', '--terminal', tab.handle], options).terminal.tabId }
     : tab));
 
+/**
+ * Whether Orca lists the terminal `handle` at `home` as orphaned, from one
+ * listing and no `terminal show`, so a caller with a deadline can give the one
+ * call all the time it has left (#676).
+ */
+export const listedOrphaned = (home, handle, options) => orca(['terminal', 'list', '--worktree', `path:${home}`], options).terminals
+  .some((tab) => tab.handle === handle && tab.orphaned === true);
+
 /**
  * Open a tab in the Orca project at `home`, titled `title`.
  *

package/src/up.js

@@ -16,7 +16,7 @@ import { dropRemovedHooks, installHook } from './hooks.js';
 import { writePermissions } from './permissions.js';
 import { piTrouble } from './pi.js';
 import { addressOf, HARNESSES, harnessOf, isAddressOf, isShortPrompt, kitFolders, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, runMissing, screenRows, shellInTab, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { asFolderProject, coordinatorOf, findProject, harnessInTab, loadInWindow, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, runMissing, screenRows, shellInTab, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
 import { TAB_ENV } from './record.js';
 import { buildAgents, rulesStamp } from './rules.js';
 import { linkSkills } from './skills.js';
@@ -40,7 +40,9 @@ const SECOND_LOOK_MS = 2000;
  * Bring bots up in Orca. Returns `{ tabs, rules }`: one tab entry per tab it
  * looked at — the sessions the book knows, and, for Bot Father, whatever else
  * is open in its project — and one rules entry and one skills entry per bot.
- * `projects` has one entry per Orca project this run made or renamed.
+ * `projects` has one entry per Orca project this run made or renamed, and per
+ * project Orca's window may not have loaded, with what went wrong as
+ * `windowTrouble` (#676).
  *
  * With no name it is every bot in the folder, in name order. `bot` brings up
  * one bot and `session` one of its sessions, for a caller that wants one thing
@@ -238,6 +240,10 @@ async function bringUpBot(bots, home, bot, onlySession) {
   // Orca's window does not see a project made or renamed on the command line
   // until it is told (#224).
   if (change !== undefined) tellWindow(orca.project);
+  // Its tabs get no notice of mail until the window loads them, and the window
+  // does not load a project it has never fetched (#676). Every run asks, so a
+  // project made before this is loaded too; the call changes nothing on screen.
+  const windowTrouble = loadInWindow(home);
 
   const live = new Map(tabs(home).map((tab) => [tab.tabId, tab]));
   const report = [];
@@ -256,7 +262,13 @@ async function bringUpBot(bots, home, bot, onlySession) {
       : spare.map((tab) => entry(tab, { bot: name, name: null, created: false }))));
   }
 
-  return { tabs: report, project: change === undefined ? undefined : { bot: name, project: orca.project, change } };
+  const project = {
+    bot: name,
+    project: orca.project,
+    ...(change === undefined ? {} : { change }),
+    ...(windowTrouble === undefined ? {} : { windowTrouble }),
+  };
+  return { tabs: report, project: change === undefined && windowTrouble === undefined ? undefined : project };
 }
 
 async function bringUpSession(bots, home, live, session, bot, title) {