@assuredloop/orca-bot-kit 0.15.0 → 0.17.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 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 |
+| Claude Code's `Teach auto mode about your environment?` | `\x1b` | Esc, which cancels it (**Not now**). 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 twice on 2.1.283, in #261's live test and #239's live run 1 (#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.15.0",
+  "version": "0.17.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/rules/limits.md

@@ -18,5 +18,5 @@ When something you were told to use is missing (a model, a tool, a file), say
 so and ask. Quietly using a different one hides the change.
 
 Permission rules in a harness's settings or rules files are the kit's to write,
-after the user's yes to the exact rules: `obk bot change --allow <rule>` or
+after the user's yes to the exact rules: `"${OBK_CLI:-obk}" bot change --allow <rule>` or
 `--disallow <rule>`. Never edit one in or out yourself, Bot Father included.

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

@@ -19,6 +19,10 @@ own commands write them.
 These are defaults for work where nothing says otherwise. A user who asks for
 something else gets what they asked for; say which of these you left and why.
 
+Where this skill says `obk`, run the kit that started your tab, `"${OBK_CLI:-obk}"`,
+in its place: in a tab the kit launched that is the kit's own path, and anywhere
+else it is plain `obk`.
+
 ## Ask whether this wants a new bot
 
 Look at the fleet before you add to it. Where a bot already there could own
@@ -284,12 +288,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 cancels; no return | Not yet proven, below |
+| Claude Code's `Teach auto mode…` | `\x1b` | Esc: Not now; 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,17 +301,19 @@ 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` on 2.1.283 is a form, not a list,
-ending `Enter to continue · Esc to cancel`: never send it a return, since
+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
+shell history. Esc cancels it (Not now) in its code; that is not yet proven
+live, though the form was seen live twice on 2.1.283. 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-finops/SKILL.md

@@ -24,6 +24,10 @@ kind that gets read once.
 These are defaults for work where nothing says otherwise. A user who asks for
 something else gets what they asked for; say which of these you left and why.
 
+Where this skill says `obk`, run the kit that started your tab, `"${OBK_CLI:-obk}"`,
+in its place: in a tab the kit launched that is the kit's own path, and anywhere
+else it is plain `obk`.
+
 ## Start from what was used, not from an impression
 
 The kit counts it for you. `obk usage` reports, per session, the conversations

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

@@ -25,6 +25,10 @@ act on your own, and that is set by the charter you are working under.
 These are defaults for work where nothing says otherwise. A user who asks for
 something else gets what they asked for; say which of these you left and why.
 
+Where this skill says `obk`, run the kit that started your tab, `"${OBK_CLI:-obk}"`,
+in its place: in a tab the kit launched that is the kit's own path, and anywhere
+else it is plain `obk`.
+
 ## Start from what is on disk
 
 Read the fleet before you talk about it. `obk roster` reports what each bot

package/skills/obk-grooming/SKILL.md

@@ -22,6 +22,10 @@ reports the same thing every morning teaches its reader to stop looking.
 These are defaults for work where nothing says otherwise. A user who asks for
 something else gets what they asked for; say which of these you left and why.
 
+Where this skill says `obk`, run the kit that started your tab, `"${OBK_CLI:-obk}"`,
+in its place: in a tab the kit launched that is the kit's own path, and anywhere
+else it is plain `obk`.
+
 ## Only what has happened since last time
 
 Fix the end of the window before you read, not after. Take the moment you are

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.js

@@ -326,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.
@@ -336,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';
 
@@ -360,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}` };
   }
@@ -425,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).
@@ -516,8 +532,8 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  * sandbox, where it does not start at all, Orca's runtime is asked instead
  * (#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}` };
@@ -556,13 +572,17 @@ function frontByOrca(handle) {
  * `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' };

package/src/up.js

@@ -14,7 +14,7 @@ import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from
 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';
@@ -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