@assuredloop/orca-bot-kit 0.14.0 → 0.16.0

package/SETUP.md

@@ -194,12 +194,12 @@ waiting for:
 | On screen | Send | Which is | Proven on |
 |---|---|---|---|
 | Claude Code's folder trust list | `\x1b[B\r` | down, then return: its selection starts on **No, exit** | Claude Code 2.1.283 |
-| Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `\r` | return: its selection starts on **Trust and continue** | Codex 0.157.1 |
-| Codex's `Hooks need review` | `\x1b[B\r` | down, then return, to **Trust all and continue**; if the selection already starts there, return alone | Codex 0.157.1 |
-| Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home) | Codex 0.157.1 |
-| Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; 0.157.1 has had no newer release to offer |
+| Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `\r` | return: its selection starts on **Trust and continue** | Codex 0.158.0 |
+| Codex's `Hooks need review` | `\x1b[B\r` | down, then return, to **Trust all and continue**; if the selection already starts there, return alone | Codex 0.158.0 |
+| Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home) | Codex 0.158.0 |
+| Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; seen on 0.157.1 (offering 0.158.0) with the selection on **Update now**, not pressed; 0.158.0 has had no newer release to offer |
 | `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell | oh-my-zsh bf77e35 |
-| Claude Code's `Teach auto mode about your environment?` | `\x1b` | Esc, which is **Not now**: it would write settings of theirs | Not yet proven: Esc is Not now in Claude Code 2.1.283's code; last seen live on 2.1.278, answered with 2. Not now |
+| Claude Code's `Teach auto mode about your environment?` | `\x1b` | Esc, which cancels it. On 2.1.283 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live on 2.1.283 (#416); 2.1.278 showed a numbered list, answered with 2. Not now |
 
 Each key counts on where the selection starts, as it did on the version named.
 Read the screen in front of you before you send: if the selection is somewhere
@@ -217,7 +217,7 @@ empty book and nothing says why.
 Codex's trust question applies to the **repository root**, which for a bot means
 the whole bots folder rather than the one bot. That is what they are agreeing to.
 
-Codex's `/new` question (seen on 0.156.1 and 0.157.1) is always answered with the current checkout, which is the bot
+Codex's `/new` question (seen on 0.156.1, 0.157.1 and 0.158.0) is always answered with the current checkout, which is the bot
 home. The kit never makes a git worktree, so
 `2. New worktree` is never the answer.
 

package/package.json

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

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

@@ -284,12 +284,12 @@ otherwise `/Applications/Orca.app/Contents/Resources/bin/orca`. A bare
 | On screen | Send | Which is | Proven on |
 |---|---|---|---|
 | Claude Code's trust list | `\x1b[B\r` | down, return: off **No, exit** | Claude Code 2.1.283 |
-| Codex's `Trust this folder?` | `\r` | return: it starts on yes | Codex 0.157.1 |
-| Codex's `Hooks need review` | `\x1b[B\r` | **Trust all and continue** | Codex 0.157.1 |
-| Codex's `Where should the new conversation run?` | `\r` | **Current checkout** | Codex 0.157.1 |
+| Codex's `Trust this folder?` | `\r` | return: it starts on yes | Codex 0.158.0 |
+| Codex's `Hooks need review` | `\x1b[B\r` | **Trust all and continue** | Codex 0.158.0 |
+| Codex's `Where should the new conversation run?` | `\r` | **Current checkout** | Codex 0.158.0 |
 | Codex's update offer, `1. Update now` | `\r` | **Update now**, where it starts | Codex 0.156.1 |
 | `[oh-my-zsh] Would you like to update?` | `n` | no: the user updates it | oh-my-zsh bf77e35 |
-| Claude Code's `Teach auto mode…` | `\x1b` | Esc, **Not now** | Not yet proven, below |
+| Claude Code's `Teach auto mode…` | `\x1b` | Esc cancels; no return | Not yet proven, below |
 
 Each key counts on where the selection starts on the version named. Read the
 screen before you send: if the selection is elsewhere or the options have
@@ -297,15 +297,18 @@ moved, go to the answer with the arrows, then return. Never a digit and then
 return: on Codex's update offer that took the highlighted **Update now**,
 whatever the digit was. Codex's trust said `1. Yes, continue` on older
 versions. Its hooks review sometimes starts on `2` already: then return alone.
-0.157.1 has had no newer release to offer, so its update offer was proven on
-0.156.1. Claude Code's `Teach auto mode` has not been seen live on 2.1.283:
-Esc is Not now in its code, and 2.1.278 was answered with `2. Not now`.
-Not now, because Yes writes the user's settings. Codex's hooks
+Its update offer was proven on 0.156.1; 0.157.1 showed it with the selection on
+Update now, not pressed, and 0.158.0 has had no newer release to offer.
+Claude Code's `Teach auto mode` on 2.1.283 is a form, not a list, ending
+`Enter to continue · Esc to cancel`: never send it a return, since
+Enter is Continue, which scans the project, recent sessions and the machine's
+shell history. Esc cancels in its code; that is not yet proven live. On 2.1.278
+it was a numbered list, answered with `2. Not now`. Codex's hooks
 question matters most. The kit's hook is how the book learns which
 conversation the session is running, and until it is answered the
 conversation has not started. Codex's trust applies to the repository root,
 which is the whole bots folder. Codex's `/new` may ask where the new
-conversation runs (0.156.1 and 0.157.1 both did); the answer is
+conversation runs (0.156.1, 0.157.1 and 0.158.0 all did); the answer is
 always the current checkout, the bot home, and never `2. New worktree`:
 the kit never makes a git worktree.
 

package/skills/obk-debugging/SKILL.md

@@ -379,12 +379,16 @@ Write the regression test before the fix, at a seam where it exercises the bug
 the way it actually happened; if there is no correct seam, that is itself the
 finding.
 
-The test is the separate author's to write, as it is for any other behaviour,
-and your reproduction is what the brief is made from: `obk-tdd` has what that
-costs and how the brief goes. Two are often better than one: one at the
-interface saying what a caller should have got, and the smallest one that shows
-the fault where it lives. A test that now looks wrong goes back to its author;
-it is not edited to fit the fix.
+The test is the separate author's to write, as it is for any other behaviour:
+someone with a context of their own, such as a fresh subagent, another session
+or a person, never a fork of this conversation. Give them the requirement and
+what the correct result is, the public interface, and your reproduction as the
+worked example; not your fix, your diff or your plan. They return the tests, the
+command, and the failing output, failing because the bug is there rather than
+because of a typo. `obk-tdd` has more on the brief, if you can load it. Two are
+often better than one: one at the interface saying what a caller should have
+got, and the smallest one that shows the fault where it lives. A test that now
+looks wrong goes back to its author; it is not edited to fit the fix.
 
 Watch it fail. Fix. Watch it pass. Then run the original, unminimised scenario
 again, on the same surface the bug appeared on. A different surface, or an

package/skills/obk-fleet-review/SKILL.md

@@ -227,6 +227,18 @@ ask for and you do it.
 A grooming report is input to this review, not its end: check what it flags
 against the fleet, and recommend from there.
 
+When a grooming report names temporary sessions a bot left behind, offer the
+user one rule for that bot's charter, with the words ready to accept, such as:
+"Retire each temporary session you make as soon as its work is done, and
+before you end a piece of work, check that none of yours is left." On a yes,
+read the bot's charter, add the line, and set the whole with `obk bot change
+--bots <folder> --bot <bot> --charter <text>`, which replaces the charter, so
+what you pass is all of it. On a no, nothing changes, and it is not offered
+again for the same sessions: write the declined offer in grooming's open
+findings, next to those sessions, so it outlasts this conversation. Retire
+none of them yourself, and send nothing to their makers: the hint is for the
+user, and only a maker knows when its work is done.
+
 Sort the problem before you write it up. Something the kit does wrong, or
 cannot do, is filed where the kit's problems are filed, as one issue, in one
 step: no draft to approve first. Something a bot is doing wrong goes back to

package/skills/obk-grilling/NOTICE.md

@@ -73,7 +73,7 @@ words where they are quoted here:
   against the session log (19:12:40, 19:15:38), which is the fix the skill
   gives.
 
-Three deliberate departures from `grilling` and `domain-modeling`, so they are
+Five deliberate departures from `grilling` and `domain-modeling`, so they are
 not mistaken for consolidation:
 
 - **A round is three questions, not the whole frontier.** `grilling` says to

package/skills/obk-grooming/SKILL.md

@@ -185,6 +185,25 @@ Never edit a memory yourself, not even to cut it. The memory is the bot's, the
 harness keeps it, and a pass that rewrites what a bot remembers is a pass that
 decides what the bot knows.
 
+## Temporary sessions left behind
+
+A temporary session is one a bot's own session made for a piece of work with
+`obk temp make`, and its maker retires it when the work is done. Each bot's
+book, `sessions.yaml` in its folder, marks one on its entry as `temporary`,
+with its `maker` and when it was `made`. Read the books every run, a quiet one
+included: a session left behind does no work, so the usage index never shows
+it.
+
+Count one as left behind when its maker is no longer one of the bot's
+sessions, or when it was made more than a day ago. The report names each: the
+bot and session, its maker, saying so where the maker is gone, and how old it
+is. Put them in the open findings, so the next run says whether each is still
+there rather than reporting it as new.
+
+Retire none of them. Only the maker knows when the work is done: a review
+session can be waiting on an open pull request for a re-review. What to do
+about a bot that leaves them behind is the management session's to offer.
+
 ## Say whether this run was worth making
 
 Every run, record which of three things happened: it found something that

package/src/bot.js

@@ -8,6 +8,7 @@
 // writes nothing, rather than leave a bot half made or a bot.yaml half edited.
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { parse, parseDocument, stringify } from 'yaml';
@@ -114,6 +115,25 @@ function whereItLeads(target) {
 export const displayName = (name) =>
   name.split('-').map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
 
+/**
+ * What Orca is asked to call a bot's project. A fleet whose bots folder is under
+ * the system's temp folder, as a system test's or a live check's is, gets a mark
+ * and the name of the first folder under the temp folder, so its Bot Father is
+ * never taken for the owner's in Orca's sidebar (#401). Every other fleet's
+ * project is called what it always was. Tab titles keep `displayName` either way.
+ */
+export function projectName(bots, name) {
+  let under;
+  try {
+    under = path.relative(realpathSync(os.tmpdir()), realpathSync(bots));
+  } catch {
+    return displayName(name);
+  }
+  // The temp folder itself, or anywhere outside it, is not a throwaway fleet's.
+  if (under === '' || under === '..' || under.startsWith(`..${path.sep}`) || path.isAbsolute(under)) return displayName(name);
+  return `${displayName(name)} · temp fleet ${under.split(path.sep)[0]}`;
+}
+
 /**
  * A bot's own file: which harness its sessions run on unless they say
  * otherwise, and the sessions it keeps.

package/src/cli.js

@@ -1574,11 +1574,21 @@ function harnessLines(tab, bots) {
       ...ANSWER_IT,
     ];
 
-  lines.push(...promptLines(tab));
+  lines.push(...promptLines(tab), ...listLines(tab));
   if (tab.unclaimed !== undefined) lines.push(...unclaimedLines(tab, bots));
   return lines;
 }
 
+/**
+ * Whether a resumed Codex session was typed its one line so Orca lists it among
+ * its agents, which it does only from a session's first turn (#226).
+ */
+function listLines(tab) {
+  if (tab.listLine === true) return ['             it was typed one line so Orca lists it among its agents: Codex tells Orca only at a first turn.'];
+  if (tab.listLine === false) return [`             it was not typed the line that makes Orca list it (${tab.listLineTrouble}): Orca lists it at its next turn.`];
+  return [];
+}
+
 /**
  * Whether the session got its start prompt, as its own record has it (#274):
  * received, or not confirmed yet. Nothing for a session that was told nothing.

package/src/orca-reload.applescript

@@ -1,5 +1,5 @@
 -- Run by the kit as `osascript orca-reload.applescript <Orca.app path>`, after
--- a project was removed (#343, ADR 0025).
+-- a project was removed (#343, ADR 0031).
 --
 -- Orca's window keeps a removed project in its sidebar until the window is
 -- rebuilt (stablyai/orca#23224; once a release fixes it, this can go behind a

package/src/orca-runtime.cjs

@@ -2,7 +2,7 @@
 // CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-runtime.cjs <client> <method> <params> <wait>`.
 //
 // It makes one call to Orca's runtime, through Orca's own client, for a method
-// Orca's CLI does not offer (ADR 0025): `project.update`, which makes Orca's
+// Orca's CLI does not offer (ADR 0031): `project.update`, which makes Orca's
 // window read its projects again (#224), and `terminal.inspectProcess`, which
 // says who is in front of a tab where `ps` cannot (#298). `params` is JSON. It
 // prints the runtime's answer as JSON and exits 0 only when the runtime took

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0025). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0031). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -13,6 +13,9 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { SHELL_ENV } from './launch.js';
+import { TAB_ENV } from './record.js';
+
 // The Orca that works for a normal user: `/usr/local/bin/orca` is a root-only
 // symlink on this machine (tech notes, section 1). OBK_ORCA overrides it, for a
 // machine that keeps Orca somewhere else.
@@ -40,10 +43,14 @@ export function orca(args, { timeoutMs } = {}) {
 /** What an error carries when Orca was given a time and did not answer in it. */
 export const TIMED_OUT = 'orca_timed_out';
 
-/** Orca's refusal as an error, with its code on it, so a caller can tell a stale handle from the rest (#294). */
+/**
+ * Orca's refusal as an error, with its code on it, so a caller can tell a stale
+ * handle from the rest (#294), and its own message as `reason`, so a caller
+ * that goes by the message reads Orca's words rather than the kit's (#405).
+ */
 const refusal = (args, answer) => Object.assign(
   new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`),
-  { code: answer.error?.code },
+  { code: answer.error?.code, reason: answer.error?.message },
 );
 
 /** One Orca command, and the whole envelope back, refusals included. */
@@ -195,7 +202,7 @@ const CLIENT_KILL_MS = 3000;
  *
  * Orca's window re-reads only when its runtime says the projects changed, and
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
- * changes does, and Orca's CLI does not offer it (ADR 0025). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0031). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -206,7 +213,7 @@ export const tellWindow = (projectId) => askRuntime('project.update', { projectI
  * runtime's answer, or undefined when there is none to be had.
  *
  * It goes through Orca's own runtime client out of the installed app, run by
- * Orca's binary the way its `bin/orca` runs its CLI (ADR 0025). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0031). None of that is
  * Orca's published interface, so anything that goes wrong is a quiet
  * undefined: it never throws and is never tried twice.
  */
@@ -243,7 +250,7 @@ const RELOAD_KILL_MS = 5000;
 
 /**
  * Have Orca's window force-reload itself, after a project was removed: true
- * only when it did (#343, ADR 0025).
+ * only when it did (#343, ADR 0031).
  *
  * The window keeps a removed project in its sidebar until it is rebuilt, and
  * `tellWindow` only relabels the row "Unknown" (stablyai/orca#23224; once a
@@ -319,9 +326,11 @@ export const retitleTab = (handle, title) =>
  * the screen, as `questionIn` answers, and `screenUnreadable` says why there
  * was none.
  */
-export function harnessInTab(handle, timeoutMs) {
+export function harnessInTab(handle, timeoutMs, readMs) {
   const args = ['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)];
-  const answer = ask(args);
+  // With `readMs`, each call to Orca is given that long on top of what it was
+  // asked to wait, and ends as TIMED_OUT when it has not answered (#422).
+  const answer = ask(args, readMs === undefined ? undefined : timeoutMs + readMs);
 
   // Out of time means nothing went idle, busy or absent alike. That is an
   // answer, not a breakdown.
@@ -329,20 +338,26 @@ export function harnessInTab(handle, timeoutMs) {
     throw refusal(args, answer);
   }
 
-  const shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
+  const shown = orca(['terminal', 'show', '--terminal', handle], { timeoutMs: readMs }).terminal;
   const agent = typeof shown?.agentIdentity === 'string' && shown.agentIdentity !== '' ? shown.agentIdentity : undefined;
   return {
     answered: answer.ok === true,
     blockedReason: answer.result?.wait?.blockedReason,
     agent,
-    ...frontOf(handle, shown?.ptyId),
-    ...screenOf(handle),
+    ...frontOf(handle, shown?.ptyId, readMs),
+    ...screenOf(handle, readMs),
   };
 }
 
 /** Orca's reason for a folder-trust screen, which it can go on giving once that is answered (#342). */
 const TRUST_REASON = 'agent-trust-workspace';
 
+/**
+ * How long each call to Orca the typing gate makes is given, beyond any wait it
+ * asked for, before the gate gives up on it and cannot tell (#422).
+ */
+const GATE_READ_MS = 5000;
+
 /** The kit's word for a tab whose screen shows a question of its harness's own (#329). */
 export const QUESTION_ON_SCREEN = 'question-on-screen';
 
@@ -353,10 +368,10 @@ export const QUESTION_ON_SCREEN = 'question-on-screen';
  * rendered screen: accumulated output comes back in fragments (tech notes,
  * section 1).
  */
-function screenOf(handle) {
+function screenOf(handle, readMs) {
   let read;
   try {
-    read = orca(['terminal', 'read', '--terminal', handle, '--screen']).terminal;
+    read = orca(['terminal', 'read', '--terminal', handle, '--screen'], { timeoutMs: readMs }).terminal;
   } catch (error) {
     return { screenUnreadable: `Orca would not read its screen: ${error.message}` };
   }
@@ -369,6 +384,9 @@ function screenOf(handle) {
 /** A row the harness starts with its selection pointer: `›` on Codex, `❯` on Claude Code. */
 const POINTER_ROW = /^ *[›❯]/;
 
+/** How a harness's form says it is answered, as Claude Code 2.1.283 draws its foot (#416). */
+const FORM_FOOT = /Enter to (?:continue|confirm|select)\b.*Esc to cancel/i;
+
 /** That pointer on a numbered choice, and the column its number starts in. */
 const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
 
@@ -376,7 +394,7 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Whether the rows of a rendered screen hold a question of the harness's own.
  *
  * Every one seen is a numbered list of choices with the harness's pointer on
- * one (tech notes, section 1; ADR 0025). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0031). The same pointer starts the harness's
  * input line and its echo of the user's past turns, and the input line is the
  * lowest of them whenever it is on screen, so only the lowest pointer row is
  * asked about: a question counts while it stands in the input line's place.
@@ -385,6 +403,13 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  */
 export function questionIn(rows) {
   const at = rows.findLastIndex((row) => POINTER_ROW.test(row));
+  // A form of the harness's own has no numbers but a foot that says how to
+  // answer it: Claude Code 2.1.283's "Teach auto mode" ends `Enter to continue
+  // · Esc to cancel`, and a return there is Continue, which starts a scan
+  // (#416). It counts on or below the lowest pointer row, or anywhere when
+  // there is none: under old words of one in the history, the input line is
+  // the lowest pointer, and nothing below it is a foot.
+  if (rows.slice(Math.max(at, 0)).some((row) => FORM_FOOT.test(row))) return true;
   const pointer = at < 0 ? null : ON_A_CHOICE.exec(rows[at]);
   if (pointer === null) return false;
   const column = pointer[1].length;
@@ -408,10 +433,18 @@ export function questionIn(rows) {
  */
 export function tabToTypeInto(home, tabId, timeoutMs) {
   if (tabId === undefined) return {};
-  const live = tabs(home).find((tab) => tab.tabId === tabId);
-  if (live === undefined) return {};
-
-  const seen = harnessInTab(live.handle, timeoutMs);
+  // Every call to Orca here has a bound, so one slow reply cannot hold the
+  // command that asked: one that runs out is "cannot tell" (#422).
+  let live;
+  let seen;
+  try {
+    live = tabs(home, { timeoutMs: GATE_READ_MS }).find((tab) => tab.tabId === tabId);
+    if (live === undefined) return {};
+    seen = harnessInTab(live.handle, timeoutMs, GATE_READ_MS);
+  } catch (error) {
+    if (error.code !== TIMED_OUT) throw error;
+    return { unsure: `Orca did not answer in time (${error.message}), so the kit could not tell whether a harness is running in it, and nothing was typed` };
+  }
   // A line typed into a screen waiting for an answer is that answer: once, it
   // confirmed Claude Code's folder-trust default, `No, exit` (tech notes,
   // section 1).
@@ -431,9 +464,12 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   // there. The program in front has to be the agent Orca names. With no name
   // it may be a harness a few seconds into its launch; under another name it
   // may be a pager started after the harness quit, under an identity Orca has
-  // not let go of (tech notes, section 1). A harness run through a wrapper such
-  // as `node` lands here too, until #261.
-  if (seen.front === undefined || seen.agent === undefined || seen.command !== seen.agent) {
+  // not let go of (tech notes, section 1). A harness run under another name,
+  // such as `node` for an npm install, passes on the kit's own mark instead
+  // (#261).
+  // Either way Orca has to name an agent there: a harness it has not named yet
+  // may be seconds into its launch and not ready for a line.
+  if (seen.front === undefined || seen.agent === undefined || (seen.command !== seen.agent && !launchedHere(seen.pid, tabId))) {
     const why = seen.front === undefined
       ? seen.unreadable
       : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
@@ -449,6 +485,25 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   return { handle: live.handle, agent: seen.agent };
 }
 
+/**
+ * Whether the process `pid`, in front of the tab `tabId`, is the harness the
+ * kit's launch line started there, whatever it is called (#261). The line sets
+ * `OBK_TAB_SHELL` to the tab's shell's pid, for the harness alone and not
+ * exported, so the harness carries it, with its parent that shell. A program
+ * the shell starts later, such as `less` after the harness quit (#232), has no
+ * mark. A program the harness starts carries the mark, and its parent is the
+ * harness. A tab Orca restored by itself has no mark at all. Only whole words
+ * of the environment count, and anything unread is a no.
+ */
+function launchedHere(pid, tabId) {
+  if (pid === undefined) return false;
+  const words = wordsOfProcess(pid);
+  if (words === undefined || !words.includes(`${TAB_ENV}=${tabId}`)) return false;
+  const marks = words.filter((word) => new RegExp(`^${SHELL_ENV}=[0-9]+$`).test(word));
+  const own = psLine(pid);
+  return marks.length === 1 && own !== undefined && Number(marks[0].slice(SHELL_ENV.length + 1)) === own.ppid;
+}
+
 /**
  * Who holds the terminal of the tab `handle`, as `frontOf` answers, without
  * waiting on the tab: for a caller that asks about every tab and has nothing
@@ -475,10 +530,10 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  *
  * `ps` is asked first. Where it cannot read the tab, as inside Codex's
  * sandbox, where it does not start at all, Orca's runtime is asked instead
- * (#298, ADR 0025).
+ * (#298, ADR 0031).
  */
-function frontOf(handle, ptyId) {
-  const read = frontByPs(ptyId);
+function frontOf(handle, ptyId, readMs) {
+  const read = frontByPs(ptyId, readMs);
   if (read.unreadable === undefined) return read;
   const asked = frontByOrca(handle);
   return asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` };
@@ -511,19 +566,23 @@ function frontByOrca(handle) {
  * Who holds the terminal of the pane `ptyId`, as `ps` says it.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0025).
+ * gives that pid's terminal's foreground process group (ADR 0031).
  * On macOS the pane is `login` with the shell as its child, so the shell is in
  * front when the group is the pane's own or that of a child of a `login` pane.
  * `diagnostics memory` is a diagnostics command and may change, so everything
  * here ends in "cannot tell" rather than in an error or a guess.
  */
-function frontByPs(ptyId) {
+function frontByPs(ptyId, readMs) {
   let pane;
   try {
-    pane = orca(['diagnostics', 'memory']).worktrees
+    pane = orca(['diagnostics', 'memory'], { timeoutMs: readMs }).worktrees
       .flatMap((worktree) => worktree.sessions ?? [])
       .find((session) => session.sessionId === ptyId)?.pid;
   } catch (error) {
+    // Orca not answering within the bound the typing gate set is not a tab
+    // `ps` cannot read: it ends the gate as "cannot tell", with no fallback to
+    // the runtime (review of PR #424).
+    if (error.code === TIMED_OUT) throw error;
     return { unreadable: `Orca would not give the pane's pid: ${error.message}` };
   }
   if (!Number.isInteger(pane) || pane <= 0) return { unreadable: 'Orca gave no pid for its pane' };
@@ -563,14 +622,25 @@ function psLine(pid) {
 /**
  * Close one tab, by the handle Orca issued for it.
  *
- * The only place in the kit that takes anything away, and it takes away one
- * tab: `--terminal <handle> --tab`. Orca's other form, `--worktree <sel> --all`,
+ * With `closeTerminal` below, the only place in the kit that takes anything
+ * away, and each takes away one tab: `--terminal <handle> --tab`. Orca's other
+ * form, `--worktree <sel> --all`,
  * closes every tab of a project with its layouts and resume records, which are
  * the user's work and not the kit's to end (tech notes, section 1).
  */
 export const closeTab = (handle) =>
   orca(['terminal', 'close', '--terminal', handle, '--tab']).close;
 
+/**
+ * Close one terminal without `--tab`: for a tab of one pane, as every tab the
+ * kit opens is, Orca then closes that tab by its id and stops its process (read
+ * in the 1.4.215 bundle). Only for a tab `--tab` could not find (#405): Orca
+ * looks a `--tab` close up in a tab snapshot of its own, which a tab it still
+ * lists can be missing from after a restart, and answers `tab_not_found`.
+ */
+export const closeTerminal = (handle) =>
+  orca(['terminal', 'close', '--terminal', handle]).close;
+
 /**
  * Type `text` into a tab and press return.
  *

package/src/pause.js

@@ -14,7 +14,7 @@ import { realpathSync } from 'node:fs';
 
 import { botDir, markPaused, readBot } from './bot.js';
 import { DAILY_SESSION } from './init.js';
-import { closeTabs, tabsToClose } from './restart.js';
+import { closeTabs, commandLine, tabsToClose } from './restart.js';
 import { BOT_FATHER, botsNamed, bringUp, sessionsOf } from './up.js';
 
 /**
@@ -30,7 +30,7 @@ export async function pauseSessions(bots, { bot, session }) {
   // they were.
   const going = tabsToClose(bots, bot, home, sessions);
   const changed = markPaused(bots, bot, session, true);
-  const closed = await closeTabs(home, going, bots, bot);
+  const closed = await closeTabs(home, going, bots, bot, commandLine('pause', bots, bot, session));
   return { bot, session, changed, closed };
 }
 

package/src/restart.js

@@ -34,7 +34,7 @@ import { setTimeout as pause } from 'node:timers/promises';
 import { bookFile, readBook } from './book.js';
 import { botDir, readBot } from './bot.js';
 import { ownCli, shellWord } from './launch.js';
-import { closeTab, findProject, frontOfTab, tabs } from './orca.js';
+import { closeTab, closeTerminal, findProject, frontOfTab, orcaCli, tabs } from './orca.js';
 import { botsNamed, bringUp, prepareBots, sessionsOf } from './up.js';
 
 /**
@@ -68,7 +68,7 @@ export async function restartSessions(bots, { bot: name, session: onlySession }
   }
 
   const going = tabsToClose(bots, name, home, sessions.filter((session) => session.paused !== true), { quit: true });
-  const closed = await closeTabs(home, going, bots, name);
+  const closed = await closeTabs(home, going, bots, name, commandLine('restart', bots, name, onlySession));
   return { closed, ...(await bringUp(bots, { bot: name, session: onlySession })) };
 }
 
@@ -113,12 +113,14 @@ export function tabsToClose(bots, name, home, sessions, { keepless = false, quit
 /**
  * Close the tabs `tabsToClose` gave, one at a time by their own handles, and
  * wait until Orca's listing agrees they are gone. Returns one entry per tab.
+ * `again` is the command that asked, as the user would run it again: what to do
+ * once a tab Orca would not close has been closed by hand.
  */
-export async function closeTabs(home, going, bots, name) {
+export async function closeTabs(home, going, bots, name, again) {
   const closed = [];
   for (const { name: session, tab } of going) {
     try {
-      closeTab(tab.handle);
+      closeWhole(tab.handle, again);
     } catch (error) {
       // A tab that would not close still holds its session, so nothing is
       // opened after this: two harnesses on one conversation is worse than a
@@ -132,6 +134,41 @@ export async function closeTabs(home, going, bots, name) {
   return closed;
 }
 
+/**
+ * Close one session's tab. Orca finds a `--tab` close in a tab snapshot of its
+ * own, which a tab it still lists can be missing from after a restart, and then
+ * answers `tab_not_found` (#405, read in the 1.4.215 bundle). The same terminal
+ * closed without `--tab` closes its one-pane tab by id, so that is done instead,
+ * and `gone` checks the tab went as it does after any close. Every other
+ * refusal stops the restart as it did.
+ */
+function closeWhole(handle, again) {
+  try {
+    closeTab(handle);
+  } catch (error) {
+    if (!notFound(error)) throw error;
+    try {
+      closeTerminal(handle);
+    } catch (second) {
+      // With the tab closed by hand there is nothing left for the command to
+      // close, so running it again finishes it, whichever command it was.
+      throw new Error(`${error.message}, and then ${second.message}. Close it by hand, then run the same command again: ${shellWord(orcaCli())} terminal close --terminal ${shellWord(handle)}  then  ${again}`);
+    }
+  }
+}
+
+/**
+ * Whether Orca refused a `--tab` close for a tab it could not find: its code,
+ * or its 1.4.215 form of code `runtime_error` with exactly that message. Orca's
+ * own words, never the kit's wrapped text, and no other form (#405).
+ */
+const notFound = (error) =>
+  error.code === 'tab_not_found' || (error.code === 'runtime_error' && error.reason === 'tab_not_found');
+
+/** A command of the kit's as the user would type it, for a message to name. */
+export const commandLine = (verb, bots, bot, session) =>
+  `${shellWord(ownCli())} ${verb} --bots ${shellWord(bots)} --bot ${bot}${session === undefined ? '' : ` --session ${session}`}`;
+
 /** How long Orca is given to stop listing a tab it has closed, and how often it is asked. */
 const SETTLED_MS = 5000;
 const ASK_MS = 100;

package/src/retire.js

@@ -26,7 +26,7 @@ import { readBook, tabIdsIn, updateBook } from './book.js';
 import { botDir, dropSession, readBot } from './bot.js';
 import { deleteProject, findProject, projects, reloadWindow, tabs } from './orca.js';
 import { fleetMember } from './pause.js';
-import { closeTabs, tabsToClose } from './restart.js';
+import { closeTabs, commandLine, tabsToClose } from './restart.js';
 import { unlinkSkills } from './skills.js';
 import { promptPath, sessionsOf } from './up.js';
 
@@ -41,7 +41,7 @@ export async function retireSession(bots, { bot, session }) {
   const home = fleetMember(bots, bot, 'retire', session);
   const sessions = sessionsOf(readBot(home, bot), session);
 
-  const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot);
+  const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, commandLine('retire', bots, bot, session));
   dropSession(bots, bot, session);
 
   const at = new Date().toISOString();
@@ -86,7 +86,7 @@ export async function retireBot(bots, { bot }) {
   // taken away with one of them still open. `closeTabs` waits until Orca agrees
   // they are gone.
   const booked = Object.keys(readBook(home).sessions).map((name) => ({ name }));
-  const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot);
+  const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot, commandLine('retire', bots, bot));
   let windowReloaded;
   if (project !== undefined) {
     deleteProject(project.id);

package/src/up.js

@@ -9,12 +9,12 @@ import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
 import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, sessionIdsIn, tabIdsIn, takeMailboxTurn, updateBook, withUnclaimed } from './book.js';
-import { botDir, botNames, displayName, readBot } from './bot.js';
+import { botDir, botNames, displayName, projectName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { writePermissions } from './permissions.js';
 import { addressOf, harnessOf, isAddressOf, isShortPrompt, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, tabs, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, 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';
@@ -211,7 +211,7 @@ async function bringUpBot(bots, home, bot, onlySession) {
   // Orca is asked first and the book is written after: nothing that takes time
   // happens while the book is held, because a session's own hook may be writing
   // its id into that same file at any moment.
-  const { change, ...orca } = orcaProject(home, title);
+  const { change, ...orca } = orcaProject(home, projectName(bots, name));
   await updateBook(home, (book) => { book.orca = orca; });
   // Orca's window does not see a project made or renamed on the command line
   // until it is told (#224).
@@ -369,6 +369,14 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     ? undefined
     : await heldInRecord(home, session.name, harness, launch.prompt, { launched, running: tui.running === true });
 
+  // A Codex session resumed here is not among Orca's agents until its first
+  // turn: Codex fires its SessionStart then and not at the resume, seen live on
+  // 0.157.1 (#226). So it is given one line, through the same gate as a mail
+  // notice, which the owner allowed. A fresh start's first turn is its prompt.
+  const list = harness === 'codex' && launch.resume !== undefined && tui.running === true
+    ? await typeListLine(home, made.tabId)
+    : undefined;
+
   return entry(made, {
     bot: bot.name,
     name: session.name,
@@ -382,9 +390,60 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     resumed: launch.resume !== undefined,
     noConversation: which.noConversation,
     unclaimed: which.unclaimed,
+    listLine: list?.typed,
+    listLineTrouble: list?.why,
   });
 }
 
+/** The line a resumed Codex session is typed so Orca lists it, in the architect's words (#226). */
+const LIST_LINE = 'obk: this session was resumed in a new tab, and this line is only so Orca lists it. Reply "ok"; nothing else is asked.';
+
+/**
+ * How long a resumed Codex tab is given to be one the kit may type into: live,
+ * Orca named the agent 7 to 11 s after the restart (#226), and the gate waits
+ * for that name. How long each look waits on the tab, and the pause between.
+ */
+const LIST_WAIT_MS = 20000;
+const LIST_LOOK_MS = 2000;
+const LIST_ASK_MS = 500;
+
+/**
+ * Type LIST_LINE into the tab `tabId` once the gate every typed line goes
+ * through lets it: `{ typed: true }`, or `{ typed: false, why }` with the
+ * gate's last reason once LIST_WAIT_MS is up. Nothing goes into a question, a
+ * form or a menu (#329, #416), nor into a tab the kit cannot tell about.
+ */
+async function typeListLine(home, tabId) {
+  const until = Date.now() + LIST_WAIT_MS;
+  for (;;) {
+    let found;
+    try {
+      // Each look waits no longer than what is left of the wait.
+      found = tabToTypeInto(home, tabId, Math.max(1, Math.min(LIST_LOOK_MS, until - Date.now())));
+    } catch (error) {
+      return { typed: false, why: `Orca would not say whether it may be typed into: ${error.message}` };
+    }
+    // A yes that comes after the wait is too late: the wait is a cutoff, not a
+    // count of looks (review of PR #421).
+    if (found.handle !== undefined && Date.now() > until) {
+      return { typed: false, why: `the ${LIST_WAIT_MS / 1000} s wait for it ran out before the kit could tell it may be typed into` };
+    }
+    if (found.handle !== undefined) {
+      try {
+        typeIntoTab(found.handle, LIST_LINE);
+        return { typed: true };
+      } catch (error) {
+        return { typed: false, why: `Orca refused the line: ${error.message}` };
+      }
+    }
+    if (Date.now() >= until) {
+      const last = found.blocked !== undefined ? `it is waiting on ${found.blocked}` : found.unsure ?? 'no harness is running in it';
+      return { typed: false, why: `the ${LIST_WAIT_MS / 1000} s wait for it ran out: ${last}` };
+    }
+    await pause(LIST_ASK_MS);
+  }
+}
+
 /**
  * The line that starts this session: resuming `resume`, or, with none, a fresh
  * start carrying its duty. Returns `{ resume, prompt, promptFile, command, address }`.
@@ -714,11 +773,15 @@ const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, cha
 export const promptPath = (bots, bot, session) =>
   path.join(`${bots}.prompts`, `${encodeURIComponent(bot)}.${encodeURIComponent(session)}.txt`);
 
-function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, unclaimed, noMailbox = false }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, unclaimed, noMailbox = false, listLine, listLineTrouble }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // Whether this run picked the session up where it was or started a new one.
   // Only for a tab this run opened: a tab that was already there was left alone.
   if (resumed !== undefined) made.resumed = resumed;
+  // Whether a resumed Codex session was typed its one line so Orca lists it,
+  // and why not when it was not (#226).
+  if (listLine !== undefined) made.listLine = listLine;
+  if (listLineTrouble !== undefined) made.listLineTrouble = listLineTrouble;
   // The id the book held that had no conversation behind it, now in the history.
   if (noConversation !== undefined) made.noConversation = noConversation;
   // Orca's own words for what is on screen waiting to be answered, when it