@assuredloop/orca-bot-kit 0.24.1 → 0.25.1

package/SETUP.md

@@ -147,14 +147,19 @@ their own edits included.
 ## 5. Answer what the tabs ask
 
 **How the tab got into this state**, because it decides what you do about it. A
-tab the kit has just made has no harness in it yet and nothing to wait for, so
-the kit types the launch line straight into the tab's shell and only then asks
-whether a harness came up. If that shell was busy with a question of its own, it
-swallowed the line. So two different things can be on the screen, and they need
-different answers.
+tab the kit has just made has no harness in it yet. The kit waits up to 15 s for
+the tab's shell to come to a ready prompt, types the launch line, and only then
+asks whether a harness came up. A shell that asks a question of its own as it
+starts gets nothing typed. So different things can be on the screen, and they
+need different answers.
 
 `obk init` tells you which, for every tab it opened:
 
+- *not launched: the shell is asking: …* — the shell asked a question as it
+  started, and the kit typed nothing. Answer the shell (the oh-my-zsh question
+  in the table below is the usual one), then run the `obk restart` command the
+  output gives for that session. It closes that tab and launches the session in
+  a new one. The command exits 1 while a session is not launched.
 - *the harness was typed in and is running. The kit cannot see whether a screen
   in it is waiting for an answer* — look at it: Orca does not flag every first-run
   screen, so it may still be asking something of its own. That is the table below.
@@ -200,6 +205,7 @@ waiting for:
 | 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 offered 0.160.0, taken on 2026-10-02 by Bot Father's restarts |
 | `[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 (**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 |
+| Claude Code 2.1.289's `Teach auto mode about your environment?`, a numbered list: `1. Yes`, `2. Not now`, `3. Don't show again`, and `Enter to confirm · Esc to cancel`, above the input box | `\x1b[B\r` | down, then return, to **2. Not now**: its selection starts on **1. Yes**. Read the screen after the down arrow, and send the return only with the selection on **2. Not now**. Never **1. Yes**, which starts the teach scan, and never **3. Don't show again** | Not yet proven: the list was seen live on 2.1.289 with its selection on 1. Yes, in #489's live run 1, and was not answered there |
 
 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
@@ -221,6 +227,27 @@ Codex's `/new` question (seen on 0.156.1, 0.157.1, 0.158.0 and 0.160.0) is alway
 home. The kit never makes a git worktree, so
 `2. New worktree` is never the answer.
 
+A bot's own temporary sessions are answered by their maker, through the kit, so
+that one narrow permission rule allows it rather than a rule to type into any
+tab. On Codex's hooks review, the maker runs
+`obk temp trust-hooks --bots <their path> --name <session>`. On Claude Code's
+`Teach auto mode` screen, it runs `obk temp answer --bots <their path> --name <session>`.
+That command reads the screen and answers only when it holds one of the two
+shapes in the table exactly as the kit knows it: Esc for the 2.1.283 form, and
+**2. Not now** for the 2.1.289 list. On the list it sends the arrows, reads the
+screen again, and sends the return only with the selection on **2. Not now**.
+It refuses any other screen, types nothing then, and prints what it saw.
+Afterwards it checks that the screen has gone. In
+auto mode the maker's bot needs this rule, with the kit's full CLI path for
+`<kit>`, as the command's own output prints it:
+
+```text
+Bash(<kit> temp answer:*)
+```
+
+Ask the user, and only after their yes run
+`obk bot change --bots <their path> --bot <bot> --allow 'Bash(<kit> temp answer:*)'`.
+
 **Anything you do not recognise: type nothing.** Tell them what is on the
 screen and which tab it is in, and wait. A keypress into a menu you have not read
 is how a harness quits back to the shell.

package/package.json

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

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

@@ -294,6 +294,7 @@ otherwise `/Applications/Orca.app/Contents/Resources/bin/orca`. A bare
 | 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; no return | Not yet proven, below |
+| The same, 2.1.289's list | `\x1b[B\r` | down, return: **2. Not now** | 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
@@ -309,7 +310,10 @@ Claude Code's `Teach auto mode` on 2.1.283 is a form, not a list, ending
 Enter is Continue, which scans the project, recent sessions and the machine's
 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
+numbered list, answered with `2. Not now`, and on 2.1.289 it is one again:
+`1. Yes`, `2. Not now`, `3. Don't show again`, above the input box, its
+selection on 1. Yes (seen live, not answered, in #489). Go down to 2. Not now,
+read the screen, and only then return. 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,
@@ -323,7 +327,13 @@ exception: answer it with `obk temp trust-hooks --bots <bots> --name
 <session>`, not with the keys. It reads the screen, chooses **Trust all and
 continue** only if the review is there, and checks that the review went. A
 permission rule can allow that one command, where it cannot allow keys sent
-into any tab.
+into any tab. The same goes for Claude Code's `Teach auto mode` screen on a
+temporary session you made: answer it with `obk temp answer --bots <bots>
+--name <session>`. It answers only a shape in the table exactly as the kit
+knows it (Esc on the 2.1.283 form, 2. Not now on the 2.1.289 list, the return
+only after a second look), refuses any other screen, and checks that it went. Its
+rule is `Bash(<kit> temp answer:*)`, `<kit>` the kit's CLI path as the
+command prints it; ask the user before `obk bot change --allow` adds it.
 
 Where the kit says no session came up, the shell swallowed the launch line,
 usually while it was asking its own question. Answer the shell, then close

package/src/cli.js

@@ -31,7 +31,7 @@ import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
 import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
 import { addSource, fetchSources } from './sources.js';
-import { listRoles, makeTemp, optionsLine, retireTemp, trustHooks } from './temp.js';
+import { answerTemp, listRoles, makeTemp, optionsLine, retireTemp, trustHooks } from './temp.js';
 import { readUsage } from './usage.js';
 import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 
@@ -140,6 +140,12 @@ Usage:
                             all and continue", and check the review went. It
                             refuses anything else on that screen, and types
                             nothing then.
+  obk temp answer --bots <path> --name <session>
+                            Run in the maker's own tab: answer Claude Code's
+                            "Teach auto mode" screen on a temporary session it
+                            made with Not now, in a shape the kit knows, and
+                            check the screen went. It refuses any other
+                            screen, and types nothing then.
   obk rules build --bots <path> [--bot <bot>]
                             Build every bot's AGENTS.md from its charter and
                             the rule units it carries, or just the one you
@@ -329,6 +335,7 @@ const COMMANDS = {
   'temp roles': ['bots'],
   'temp retire': ['bots', 'name'],
   'temp trust-hooks': ['bots', 'name'],
+  'temp answer': ['bots', 'name'],
 };
 
 /** What each flag is for, in the sentence a caller reads when it is missing. */
@@ -465,7 +472,9 @@ async function run(argv) {
   const { answer, lines, code = 0 } = await commands[command](bots, values);
 
   process.stdout.write(values.json ? `${JSON.stringify(answer, null, 2)}\n` : `${lines.join('\n')}\n`);
-  return code;
+  // A session whose tab was opened and not launched is a command that stopped
+  // short, whichever command opened it (#498).
+  return answer?.tabs?.some((tab) => tab.launched === false) ? 1 : code;
 }
 
 /**
@@ -749,7 +758,9 @@ const commands = {
       lines: [
         ...(made.role === undefined ? [] : [`role       ${made.role.name}:${made.role.option}${made.role.for === undefined ? '' : `, for ${made.role.for}`}. Its options: ${optionsLine(made.role.options)}`]),
         ...Object.entries(made.chosen).map(([setting, one]) => `${setting.padEnd(9)}  ${one.value === undefined ? `the ${one.from}` : `${one.value}, from ${one.from === 'flag' ? `--${setting}` : `the ${one.from}`}`}`),
-        ...tabLines(answer, `Made ${made.bot}/${made.session}, a temporary session of ${made.maker}'s, working in work/${made.session}. Retire it when its work is done:  ${retire}`),
+        ...tabLines(answer, tabs.some((one) => one.launched === false)
+          ? `${made.bot}/${made.session}, a temporary session of ${made.maker}'s, is in bot.yaml and the book, and was not launched. Restart it once its tab is ready, or retire it:  ${retire}`
+          : `Made ${made.bot}/${made.session}, a temporary session of ${made.maker}'s, working in work/${made.session}. Retire it when its work is done:  ${retire}`),
       ],
     };
   },
@@ -792,6 +803,19 @@ const commands = {
     };
   },
 
+  async 'temp answer'(bots, values) {
+    const tab = callerTab(bots, true);
+    refuseWhenOrcaIsDown();
+    const answered = await answerTemp(bots, { tab, name: values.name });
+    return {
+      answer: { bots, ...answered },
+      lines: [
+        `answered   ${answered.bot} ${answered.session}, a temporary session of ${answered.maker}'s: sent ${answered.sent} to its "Teach auto mode about your environment?" screen, and the screen has gone`,
+        `rule       a maker's bot runs this under one permission rule, which the user approves:  Bash(${shellWord(ownCli())} temp answer:*)`,
+      ],
+    };
+  },
+
   'bot create'(bots, values) {
     const made = createBot(bots, { name: values.name, harness: values.harness, charter: values.charter });
     // The bot's AGENTS.md is the rules build's, here as everywhere else, so
@@ -1751,6 +1775,17 @@ function tabLines({ bots, created, completed, rules, skills, permissions = [], t
 function harnessLines(tab, bots) {
   if (!tab.created || tab.name === null) return [];
 
+  // Nothing was typed into it, so there is nothing more to say about a harness
+  // (#498).
+  if (tab.launched === false) {
+    return [
+      `             not launched: ${tab.notLaunched}. Nothing was typed into it.`,
+      `             Look at it:  ${lookAt(tab.terminal)}`,
+      '             Answer it in the tab, then start the session again in a new tab:',
+      `               ${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${tab.bot} --session ${tab.name}`,
+    ];
+  }
+
   // What the line that was typed in asked for, and where the kit got it: the
   // session the book holds, one the harness itself still had on record, or a new
   // one — and if a new one, whether anything was known about an older one.

package/src/orca.js

@@ -231,7 +231,7 @@ export const tellWindow = (projectId) => askRuntime('project.update', { projectI
  * Orca's published interface, so anything that goes wrong is a quiet
  * undefined: it never throws and is never tried twice.
  */
-function askRuntime(method, params) {
+function askRuntime(method, params, killMs = CLIENT_KILL_MS) {
   try {
     // The CLI sits at <Orca.app>/Contents/Resources/bin/orca, often reached
     // through a link.
@@ -244,8 +244,8 @@ function askRuntime(method, params) {
 
     const asked = spawnSync(
       path.join(contents, 'MacOS', 'Orca'),
-      [RUNTIME_SCRIPT, client, method, JSON.stringify(params), String(CLIENT_WAIT_MS)],
-      { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: CLIENT_KILL_MS },
+      [RUNTIME_SCRIPT, client, method, JSON.stringify(params), String(Math.min(CLIENT_WAIT_MS, killMs))],
+      { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: Math.min(CLIENT_KILL_MS, killMs) },
     );
     if (asked.error !== undefined || asked.status !== 0) return undefined;
     return parse(asked.stdout) ?? undefined;
@@ -420,8 +420,9 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Every one seen is a numbered list of choices with the harness's pointer on
  * one (tech notes, section 1; ADR 0034). 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.
+ * lowest of them whenever it is on screen, so the lowest pointer row is asked
+ * about: a question counts while it stands in the input line's place, or
+ * while it is the last thing drawn right above the input box (#491).
  * Unnumbered lists do not count. Codex puts a status row right under its input
  * line, lined up with it, and by its layout that is one.
  */
@@ -434,6 +435,37 @@ export function questionIn(rows) {
   // 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;
+  if (pointedChoiceAt(rows, at)) return true;
+  // Claude Code 2.1.289 draws its Teach list above its input box, whose own
+  // `❯` stays the lowest pointer row (#491). A question there is the last
+  // thing drawn above the box's top rule: its foot, or its numbered choices
+  // with the pointer on one, under it a foot that a narrow pane wraps onto
+  // rows of its own. The same words with anything after them are history.
+  if (at < 1 || !RULE_ROW.test(rows[at - 1])) return false;
+  let end = rows.slice(0, at - 1).findLastIndex((row) => row.trim() !== '');
+  if (end < 0) return false;
+  if (FORM_FOOT.test(rows[end])) return true;
+  while (end > 0 && FOOT_PART.test(rows[end])) end -= 1;
+  if (!NUMBERED.test(rows[end])) return false;
+  let first = end;
+  while (first > 0 && NUMBERED.test(rows[first - 1])) first -= 1;
+  for (let row = first; row <= end; row += 1) {
+    if (pointedChoiceAt(rows, row)) return true;
+  }
+  return false;
+}
+
+/** A rule Claude Code draws right across, as the top of its input box: `─` or `▔`. */
+const RULE_ROW = /^ *[─▔]{8,}/;
+
+/** A numbered choice, with the pointer on it or not. */
+const NUMBERED = /^ *(?:[›❯] +)?\d+\. /;
+
+/** A part of a foot, as a narrow pane wraps it: `Enter to confirm ·`, `Esc to cancel`. */
+const FOOT_PART = /\b(?:Enter to (?:continue|confirm|select)|Esc to cancel)\b/i;
+
+/** Whether `rows[at]` has the pointer on a numbered choice, with another lined up right above or below it. */
+function pointedChoiceAt(rows, at) {
   const pointer = at < 0 ? null : ON_A_CHOICE.exec(rows[at]);
   if (pointer === null) return false;
   const column = pointer[1].length;
@@ -554,17 +586,21 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  * Who holds the terminal of the tab `handle`, whose pane is `ptyId`:
  * `{ front: 'shell' }`, `{ front: 'program', command, pid }` with the name and,
  * where `ps` gave it, the pid of the process leading the group in front, or
- * `{ unreadable: <why> }`.
+ * `{ unreadable: <why> }`; each with `pane`, the pane's pid, where Orca gave it.
  *
  * `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 0034).
+ * (#298, ADR 0034). `readMs` bounds each call: a number, or a function that
+ * says what is left of a wait, asked before each one (#498). A `ps` that runs
+ * out of it ends the look, `late`, with no runtime asked after it.
  */
 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}` }), psUnread: true };
+  if (read.unreadable === undefined || read.late === true) return read;
+  const asked = frontByOrca(handle, msOf(readMs));
+  // The pane's pid, where `diagnostics memory` gave it, goes on with the answer.
+  const pane = read.pane === undefined ? {} : { pane: read.pane };
+  return { ...(asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` }), psUnread: true, ...pane };
 }
 
 /**
@@ -576,8 +612,8 @@ function frontOf(handle, ptyId, readMs) {
  * else is "cannot tell": for a moment after a harness quits, Orca can name
  * nothing and still see a child in front (read in the Orca 1.4.212 bundle).
  */
-function frontByOrca(handle) {
-  const seen = askRuntime('terminal.inspectProcess', { terminal: handle })?.result?.process;
+function frontByOrca(handle, readMs) {
+  const seen = askRuntime('terminal.inspectProcess', { terminal: handle }, readMs)?.result?.process;
   const evidence = seen?.foregroundProcessEvidence;
   if (evidence?.verdict !== 'live') {
     const why = typeof evidence?.reason === 'string' ? `: ${evidence.reason}` : '';
@@ -601,6 +637,29 @@ function frontByOrca(handle) {
  * here ends in "cannot tell" rather than in an error or a guess.
  */
 function frontByPs(ptyId, readMs) {
+  const { pane, unreadable } = panePid(ptyId, msOf(readMs));
+  if (unreadable !== undefined) return { unreadable };
+
+  const own = psLine(pane, msOf(readMs));
+  if (own?.late === true) return { unreadable: `ps did not answer in time for its pane, pid ${pane}`, late: true };
+  if (own === undefined) return { unreadable: `ps could not read its pane, pid ${pane}`, pane };
+  if (own.tpgid === pane) return { front: 'shell', pane };
+
+  const front = psLine(own.tpgid, msOf(readMs));
+  if (front?.late === true) return { unreadable: `ps did not answer in time for the process in front, pid ${own.tpgid}`, late: true };
+  if (front === undefined) return { unreadable: `ps could not read the process in front, pid ${own.tpgid}`, pane };
+  const shell = front.ppid === pane && path.basename(own.comm) === 'login';
+  return shell ? { front: 'shell', pane } : { front: 'program', command: path.basename(front.comm), pid: own.tpgid, pane };
+}
+
+/** A bound `frontOf` was given, as a number of milliseconds: asked now when it is a function. */
+const msOf = (readMs) => (typeof readMs === 'function' ? readMs() : readMs);
+
+/**
+ * The pid of the pane `ptyId`, `{ pane }`, from `diagnostics memory`, or
+ * `{ unreadable: <why> }`.
+ */
+function panePid(ptyId, readMs) {
   let pane;
   try {
     pane = orca(['diagnostics', 'memory'], { timeoutMs: readMs }).worktrees
@@ -614,15 +673,87 @@ function frontByPs(ptyId, readMs) {
     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' };
+  return { pane };
+}
 
-  const own = psLine(pane);
-  if (own === undefined) return { unreadable: `ps could not read its pane, pid ${pane}` };
-  if (own.tpgid === pane) return { front: 'shell' };
+/** The `lsof` and `stty` this run asks. OBK_LSOF and OBK_STTY override them, as OBK_PS does `ps`. */
+const lsofCli = () => process.env.OBK_LSOF || '/usr/sbin/lsof';
+const sttyCli = () => process.env.OBK_STTY || '/bin/stty';
 
-  const front = psLine(own.tpgid);
-  if (front === undefined) return { unreadable: `ps could not read the process in front, pid ${own.tpgid}` };
-  const shell = front.ppid === pane && path.basename(own.comm) === 'login';
-  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm), pid: own.tpgid };
+/**
+ * One look at the shell of a tab the kit has just opened, before anything is
+ * typed into it (#498): `{ ready: true }` when the shell is at a prompt that
+ * takes a line, `{ asking: true }` when the shell is in front and reading the
+ * tty some other way, `{ program }` when something else is in front, and
+ * `{ unsure: <why> }` when the kit cannot tell, with `late` when a call ran out
+ * of the time left until `until`.
+ *
+ * A shell's line editor (zsh's, bash's readline) puts the tty in non-canonical
+ * mode with no echo and no literal-next key while it waits at a prompt. A
+ * question asked in a start-up file (`read -k 1`, `read -p`, `read -s -k 1`)
+ * leaves echo or the literal-next key on, and so does a shell still busy with
+ * its start-up files. Orca's daemon tells a ready shell
+ * the same way when its own mark does not come (tech notes, section 1). The
+ * shell's prompt itself is never read: it is the user's.
+ */
+export function shellInTab(handle, until) {
+  // Each call is given what is left until `until`, so a reader that hangs
+  // cannot hold the launch past its wait.
+  const left = () => Math.max(1, until - Date.now());
+  try {
+    let shown;
+    try {
+      shown = orca(['terminal', 'show', '--terminal', handle], { timeoutMs: left() }).terminal;
+    } catch (error) {
+      if (error.code === TIMED_OUT) throw error;
+      return { unsure: `Orca would not show the tab: ${error.message}` };
+    }
+    const front = frontOf(handle, shown?.ptyId, left);
+    if (front.unreadable !== undefined) return { unsure: front.unreadable, ...(front.late ? { late: true } : {}) };
+    if (front.front === 'program') return { program: front.command };
+    const { pane, unreadable } = front.pane === undefined ? panePid(shown?.ptyId, left()) : front;
+    if (unreadable !== undefined) return { unsure: unreadable };
+    const mode = ttyMode(pane, left);
+    if (mode.unreadable !== undefined) return { unsure: mode.unreadable, ...(mode.late ? { late: true } : {}) };
+    return mode.lineEditor ? { ready: true } : { asking: true };
+  } catch (error) {
+    if (error.code !== TIMED_OUT) throw error;
+    return { unsure: `Orca did not answer in time: ${error.message}`, late: true };
+  }
+}
+
+/**
+ * Whether the tty of the pane `pid` is in a line editor's mode, `{ lineEditor }`,
+ * or `{ unreadable: <why> }`. `lsof` names the tty on the standard input of the
+ * shell, and `stty` reads its flags; both run inside Codex's sandbox, where
+ * `ps` does not. The pane is `login`, which runs as root and whose files `lsof`
+ * cannot read, so the shell is found as the user's process whose parent it is,
+ * or as the pane itself where the pane is the shell.
+ */
+function ttyMode(pid, left) {
+  const listed = spawnSync(lsofCli(), ['-a', '-R', '-d', '0', '-u', String(process.getuid()), '-FpRn'], { encoding: 'utf8', timeout: left() });
+  if (listed.error?.code === 'ETIMEDOUT') return { unreadable: 'lsof did not answer in time', late: true };
+  if (listed.error || listed.status !== 0) return { unreadable: `lsof could not list the processes' ttys` };
+  // One record per process: `p<pid>`, `R<parent pid>`, `f0`, `n<name>`.
+  let record = {};
+  let tty;
+  for (const line of listed.stdout.split('\n')) {
+    if (line.startsWith('p')) record = { pid: Number(line.slice(1)) };
+    else if (line.startsWith('R')) record.ppid = Number(line.slice(1));
+    else if (line.startsWith('n/dev/') && (record.pid === pid || record.ppid === pid)) tty ??= line.slice(1);
+  }
+  if (tty === undefined) return { unreadable: `lsof named no tty for the shell of its pane, pid ${pid}` };
+
+  const read = spawnSync(sttyCli(), ['-a', '-f', tty], { encoding: 'utf8', timeout: left() });
+  if (read.error?.code === 'ETIMEDOUT') return { unreadable: `stty did not answer in time for ${tty}`, late: true };
+  if (read.error || read.status !== 0) return { unreadable: `stty could not read ${tty}` };
+  const words = read.stdout.split(/\s+/);
+  const flag = (name) => (words.includes(name) ? true : words.includes(`-${name}`) ? false : undefined);
+  const [icanon, echo] = [flag('icanon'), flag('echo')];
+  if (icanon === undefined || echo === undefined) return { unreadable: `stty gave no icanon and echo flags for ${tty}` };
+  // A line editor also turns off the literal-next key, which a question read
+  // with echo off (`read -s -k 1`) leaves on, as Orca's own test has it.
+  return { lineEditor: !icanon && !echo && /(?:^|[;\s])lnext\s*=\s*<undef>(?:;|\s|$)/.test(read.stdout) };
 }
 
 /**
@@ -638,9 +769,10 @@ export function wordsOfProcess(pid) {
   return asked.stdout.trim().split(/\s+/);
 }
 
-/** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, or undefined. */
-function psLine(pid) {
-  const asked = spawnSync(psCli(), ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8' });
+/** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, `{ late: true }` past `readMs`, or undefined. */
+function psLine(pid, readMs) {
+  const asked = spawnSync(psCli(), ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8', ...(readMs === undefined ? {} : { timeout: readMs }) });
+  if (asked.error?.code === 'ETIMEDOUT') return { late: true };
   if (asked.error || asked.status !== 0) return undefined;
   const line = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(.+?)\s*$/.exec(asked.stdout);
   if (line === null) return undefined;

package/src/temp.js

@@ -1,6 +1,7 @@
 // `obk temp make` and `obk temp retire`: a session's own temporary sessions
-// (PRD 6.4, #227). And `obk temp trust-hooks`, the one answer a maker gives its
-// Codex run's hooks review (#238).
+// (PRD 6.4, #227). And `obk temp trust-hooks` and `obk temp answer`, the
+// answers a maker gives its Codex run's hooks review (#238) and its Claude
+// session's Teach auto mode form (#489).
 //
 // Any long-lived session can make a temporary session of its own bot for a
 // piece of work, and retire it when the work is done, without Bot Father, who
@@ -348,59 +349,232 @@ export async function trustHooks(bots, { tab, name }) {
   if (harness !== 'codex') {
     throw new Error(`${run} runs on ${harness}, and temp trust-hooks answers a Codex run's "${HOOKS_REVIEW}" alone. ${nothing}`);
   }
+  await answerScreen(caller, name, {
+    what: 'hooks review',
+    mark: HOOKS_REVIEW,
+    done: `"${TRUST_ALL}" was chosen on its hooks review`,
+    answer(rows, { send }) {
+      const keys = keysToTrustAll(rows);
+      if (keys === undefined) {
+        throw new Error(`${run}'s screen shows no "${HOOKS_REVIEW}" with its choices, so there is nothing for this to answer. It shows: ${shown(rows)}. ${nothing}`);
+      }
+      send(keys);
+    },
+  });
+  return { bot: caller.bot, session: name, maker: caller.session };
+}
+
+/**
+ * The keys that take Codex's hooks review to "2. Trust all and continue" and
+ * answer it, from wherever its pointer is: arrows, then return, never a digit
+ * (a digit and return once took whatever was highlighted). Undefined when the
+ * rows show no such review with the pointer on one of its choices.
+ */
+function keysToTrustAll(rows) {
+  if (!rows.some((row) => row.includes(HOOKS_REVIEW))) return undefined;
+  if (!rows.some((row) => new RegExp(`^ *(?:› +)?2\\. ${TRUST_ALL}`).test(row))) return undefined;
+  const pointer = rows.map((row) => /^ *› +(\d+)\. /.exec(row)).findLast((found) => found !== null);
+  if (pointer === undefined) return undefined;
+  const moves = 2 - Number(pointer[1]);
+  return (moves > 0 ? '\x1b[B'.repeat(moves) : '\x1b[A'.repeat(-moves)) + '\r';
+}
+
+/** What a screen shows, on one line: its rows with words in them, cut short. */
+function shown(rows) {
+  const text = rows.map((row) => row.trim()).filter((row) => row !== '').join(' ⏎ ');
+  return text.length > 500 ? `${text.slice(0, 500)}…` : text;
+}
+
+/**
+ * Answer a screen of `name`, a temporary session the caller made: under the
+ * session's turn for a line (#482), read its screen and hand it to
+ * `answer(rows, { send, look })`, which sends keys with `send`, may read the
+ * screen again with `look`, and throws when the screen is not its to answer.
+ * Then wait for `mark` to leave the screen. `what` names the screen and `done`
+ * says what was sent, for the sentences that refuse or fail; `done` may be a
+ * function of what `answer` returned.
+ */
+async function answerScreen(caller, name, { what, mark, done, answer }) {
+  const run = `${caller.bot}/${name}`;
+  const nothing = 'Nothing was typed.';
   const tabId = readBook(caller.home).sessions[name]?.tab;
   const handle = tabId === undefined ? undefined : tabs(caller.home).find((one) => one.tabId === tabId)?.handle;
   if (handle === undefined) {
-    throw new Error(`${run} has no tab open in Orca, so there is no review of its to answer. ${nothing}`);
+    throw new Error(`${run} has no tab open in Orca, so there is no ${what} of its to answer. ${nothing}`);
   }
-  // The session's turn for a line (#482), for the look and the keys.
   const turn = takeLineTurn(caller.home, name, TYPING_WAIT_MS);
   if (turn === undefined) throw new Error(`${run}: ${TYPING_HELD}.`);
+  let answered;
   try {
     const seen = screenRows(handle);
     if (seen.rows === undefined) {
-      throw new Error(`${run}'s screen could not be read (${seen.unreadable}), so the kit cannot tell whether its hooks review is there. ${nothing}`);
+      throw new Error(`${run}'s screen could not be read (${seen.unreadable}), so the kit cannot tell whether its ${what} is there. ${nothing}`);
     }
-    const keys = keysToTrustAll(seen.rows);
-    if (keys === undefined) {
-      throw new Error(`${run}'s screen shows no "${HOOKS_REVIEW}" with its choices, so there is nothing for this to answer. It shows: ${shown(seen.rows)}. ${nothing}`);
-    }
-    // The return is inside the text: `--enter` would be a second key.
-    orca(['terminal', 'send', '--terminal', handle, '--text', keys]);
+    answered = answer(seen.rows, {
+      // The return, where there is one, is inside the text: `--enter` would be a second key.
+      send: (keys) => orca(['terminal', 'send', '--terminal', handle, '--text', keys]),
+      look: () => screenRows(handle),
+    });
   } finally {
     turn.release();
   }
   for (let waited = 0; ; waited += 500) {
     const after = screenRows(handle);
-    if (after.rows !== undefined && !after.rows.some((row) => row.includes(HOOKS_REVIEW))) break;
+    if (after.rows !== undefined && !after.rows.some((row) => row.includes(mark))) return answered;
     if (waited >= REVIEW_GONE_MS) {
-      const still = after.rows === undefined ? `its screen could not be read again (${after.unreadable})` : `its screen still shows "${HOOKS_REVIEW}"`;
-      throw new Error(`${run}: "${TRUST_ALL}" was chosen on its hooks review, but ${REVIEW_GONE_MS / 1000} seconds later ${still}. Look at its tab.`);
+      const still = after.rows === undefined ? `its screen could not be read again (${after.unreadable})` : `its screen still shows "${mark}"`;
+      throw new Error(`${run}: ${typeof done === 'function' ? done(answered) : done}, but ${REVIEW_GONE_MS / 1000} seconds later ${still}. Look at its tab.`);
     }
     await pause(500);
   }
-  return { bot: caller.bot, session: name, maker: caller.session };
 }
 
+/** The title of Claude Code's "Teach auto mode" screen, in each known shape. */
+const TEACH_TITLE = 'Teach auto mode about your environment?';
+
+/** The foot that ends a Claude Code form, below which its input box sits. */
+const TEACH_FOOT = /Enter to .*· Esc to cancel/;
+
 /**
- * The keys that take Codex's hooks review to "2. Trust all and continue" and
- * answer it, from wherever its pointer is: arrows, then return, never a digit
- * (a digit and return once took whatever was highlighted). Undefined when the
- * rows show no such review with the pointer on one of its choices.
+ * The known shapes of the Teach screen, from its title to its foot, each as
+ * captured live, with what answers it. Rows are compared trimmed, the pointer
+ * `❯` taken out, so the pointer may sit on any one of them.
+ *
+ * Claude Code 2.1.283's form (#261's live test, #416) is answered with Esc,
+ * which cancels it (Not now), never a return, which is Continue. Claude Code
+ * 2.1.289's numbered list (#489's live run 1) is answered with "2. Not now",
+ * never "1. Yes" or "3. Don't show again" (the architect's ruling on #489).
  */
-function keysToTrustAll(rows) {
-  if (!rows.some((row) => row.includes(HOOKS_REVIEW))) return undefined;
-  if (!rows.some((row) => new RegExp(`^ *(?:› +)?2\\. ${TRUST_ALL}`).test(row))) return undefined;
-  const pointer = rows.map((row) => /^ *› +(\d+)\. /.exec(row)).findLast((found) => found !== null);
-  if (pointer === undefined) return undefined;
-  const moves = 2 - Number(pointer[1]);
-  return (moves > 0 ? '\x1b[B'.repeat(moves) : '\x1b[A'.repeat(-moves)) + '\r';
+const TEACH_SHAPES = [
+  {
+    name: 'the 2.1.283 form',
+    rows: [
+      TEACH_TITLE,
+      'Claude Code reads this project, your recent Claude sessions, and optionally your shell history and other',
+      'repositories. Claude analyzes this data and customizes auto mode to make better decisions.',
+      'How you use Claude here     Mixed',
+      'Also scan shell history     true',
+      'Also scan your other repos  false',
+      'Continue',
+      '←/→ to change usage · Enter to continue · Esc to cancel',
+    ],
+  },
+  {
+    name: 'the 2.1.289 list',
+    rows: [
+      TEACH_TITLE,
+      'Auto mode works better when it knows your environment. Takes about a minute.',
+      '1. Yes',
+      '2. Not now',
+      "3. Don't show again",
+      'Enter to confirm · Esc to cancel',
+    ],
+  },
+];
+
+/** The 2.1.289 list's choice this kit takes, and the row it is on. */
+const NOT_NOW_CHOICE = '2. Not now';
+
+/** A row as a shape is compared: trimmed, with its pointer, wherever it sits, taken out. */
+const unpointed = (row) => row.replace('❯', ' ').trim();
+
+/** The full-width rule Claude Code draws right above the screen's title: `─` in 2.1.289, `▔` in 2.1.283. */
+const ABOVE_TITLE = /^(?:─+|▔+)$/;
+
+/**
+ * The Teach screen on `rows`, from its title to its foot, the rows below the
+ * foot (the input box) left out: `{ shape, block }` when its non-blank rows
+ * are one known shape's, in its order and nothing else, with the pointer on
+ * exactly one; otherwise `{ misfit }`, why not.
+ *
+ * It counts only in the frame Claude Code drew it in, in both live captures:
+ * a full-width rule as the non-blank row right above the title, and, right
+ * below the foot, nothing or the input box's top rule. A quote of the screen
+ * in a turn, with the turn's own rows around it, is refused (the review of
+ * #490). A quote of the frame as well would still look the same: the frame
+ * narrows what passes, and is no proof that the screen is live.
+ */
+function teachScreen(rows) {
+  const from = rows.findIndex((row) => row.trim() === TEACH_TITLE);
+  if (from < 0) return { misfit: `it shows no "${TEACH_TITLE}"` };
+  const foot = rows.findIndex((row, at) => at > from && TEACH_FOOT.test(row));
+  if (foot < 0) return { misfit: `it shows "${TEACH_TITLE}" with no foot row ending "Esc to cancel" under it` };
+  const above = rows.slice(0, from).findLast((row) => row.trim() !== '');
+  if (above === undefined || !ABOVE_TITLE.test(above.trim())) {
+    return { misfit: `the row right above its title is ${above === undefined ? 'nothing' : `"${above.trim()}"`}, not the full-width rule Claude Code draws there` };
+  }
+  const below = rows.slice(foot + 1).find((row) => row.trim() !== '');
+  if (below !== undefined && !below.trimStart().startsWith('─')) {
+    return { misfit: `the row right below its foot is "${below.trim()}", not the top rule of the input box` };
+  }
+  const block = rows.slice(from, foot + 1).filter((row) => row.trim() !== '');
+  const misfits = TEACH_SHAPES.map((shape) => {
+    const pointers = block.filter((row) => row.includes('❯')).length;
+    if (pointers !== 1) return `${pointers} rows with the pointer ❯, where ${shape.name} has one`;
+    const odd = block.find((row) => !shape.rows.includes(unpointed(row)));
+    if (odd !== undefined) return `a row ${shape.name} does not have: ${odd.trim()}`;
+    const missing = shape.rows.find((row) => !block.map(unpointed).includes(row));
+    if (missing !== undefined) return `no row ${missing}, which ${shape.name} has`;
+    if (block.length !== shape.rows.length) return `${block.length} rows, where ${shape.name} has ${shape.rows.length}`;
+    const moved = block.findIndex((row, at) => unpointed(row) !== shape.rows[at]);
+    if (moved >= 0) return `the row ${block[moved].trim()} where ${shape.name} has ${shape.rows[moved]}`;
+    return undefined;
+  });
+  const fits = misfits.findIndex((misfit) => misfit === undefined);
+  if (fits >= 0) return { shape: TEACH_SHAPES[fits], block };
+  return { misfit: `its Teach screen is no shape the kit knows: it has ${misfits.join('; and it has ')}` };
 }
 
-/** What a screen shows, on one line: its rows with words in them, cut short. */
-function shown(rows) {
-  const text = rows.map((row) => row.trim()).filter((row) => row !== '').join(' ⏎ ');
-  return text.length > 500 ? `${text.slice(0, 500)}…` : text;
+/** The whole screen, a row to a line: what decides is often at its foot. */
+const wholeScreen = (rows) => rows.filter((row) => row.trim() !== '').map((row) => `    ${row}`).join('\n');
+
+/**
+ * Answer the first-run screen of a temporary session the caller made (#489):
+ * Claude Code's Teach auto mode screen, in one of the shapes the kit knows,
+ * matched exactly. The 2.1.283 form gets Esc. The 2.1.289 list gets arrows to
+ * "2. Not now" where needed, a second look that the pointer is there and the
+ * list is otherwise as it was, and only then a return. Anything else is refused with
+ * nothing typed. Like `trustHooks`, it is one command a permission rule of its
+ * own can allow. Returns `{ bot, session, maker, sent }`, `sent` saying what
+ * answered it.
+ */
+export async function answerTemp(bots, { tab, name }) {
+  const caller = callerIn(bots, tab, 'answer', "answer a session's first-run screen");
+  const nothing = 'Nothing was typed.';
+  ownTemp(caller, name, 'answer for', nothing);
+  const run = `${caller.bot}/${name}`;
+  const sent = await answerScreen(caller, name, {
+    what: `"${TEACH_TITLE}"`,
+    mark: TEACH_TITLE,
+    done: (said) => `${said} was sent to its Teach auto mode screen`,
+    answer(rows, { send, look }) {
+      const seen = teachScreen(rows);
+      if (seen.misfit !== undefined) {
+        const hooks = rows.some((row) => row.includes(HOOKS_REVIEW)) ? ` A Codex run's "${HOOKS_REVIEW}" is answered with temp trust-hooks.` : '';
+        throw new Error(`${run}'s screen is not one temp answer answers: ${seen.misfit}.${hooks} ${nothing} It shows:\n${wholeScreen(rows)}`);
+      }
+      if (seen.shape === TEACH_SHAPES[0]) {
+        send('\x1b');
+        return 'Esc (Not now)';
+      }
+      const at = seen.block.findIndex((row) => row.includes('❯'));
+      const moves = seen.block.findIndex((row) => unpointed(row) === NOT_NOW_CHOICE) - at;
+      if (moves !== 0) send(moves > 0 ? '\x1b[B'.repeat(moves) : '\x1b[A'.repeat(-moves));
+      // The guard, before every return, arrows or none: the list again, its
+      // rows in the same order (an exact shape), and the pointer on "2. Not now".
+      const again = look();
+      const now = again.rows === undefined ? { misfit: `it could not be read again (${again.unreadable})` } : teachScreen(again.rows);
+      const on = now.block?.find((row) => row.includes('❯'));
+      if (now.shape !== seen.shape || unpointed(on) !== NOT_NOW_CHOICE) {
+        const why = now.misfit ?? `its pointer is on ${unpointed(on)}, not ${NOT_NOW_CHOICE}`;
+        const sent = moves === 0 ? 'Nothing was typed' : `The arrows to "${NOT_NOW_CHOICE}" went in`;
+        throw new Error(`${run}: ${sent}, but then ${why}, so no return was sent. Look at its tab.${again.rows === undefined ? '' : ` It shows:\n${wholeScreen(again.rows)}`}`);
+      }
+      send('\r');
+      return `"${NOT_NOW_CHOICE}"`;
+    },
+  });
+  return { bot: caller.bot, session: name, maker: caller.session, sent };
 }
 
 /**

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, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, 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';
@@ -338,6 +338,14 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     writePrompt(launch);
   }
 
+  // Only into a shell that is ready for it (#498). A question the shell asks as
+  // it starts takes the line as its answer: Orca holds a line for a new tab
+  // only until its shell is ready or 15 s pass, and then lets it through.
+  const notLaunched = await shellNotReady(made.handle);
+  if (notLaunched !== undefined) {
+    return entry(made, { bot: bot.name, name: session.name, created: true, notLaunched });
+  }
+
   // Typing it in is the way: for a project the kit has just made, giving Orca
   // the harness as the tab's own command times out and leaves a dead tab.
   typeIntoTab(made.handle, launch.command);
@@ -395,6 +403,53 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   });
 }
 
+/**
+ * How long a new tab's shell is given to come to a ready prompt, and the pause
+ * between looks. A start-up with oh-my-zsh took about a second here; Orca
+ * itself waits 15 s for a new shell.
+ */
+const SHELL_READY_MS = 15000;
+const SHELL_LOOK_MS = 250;
+
+/** The least a look is given: a wait with less left than that ends. */
+const LAST_LOOK_MS = 1000;
+
+/** How long the screen read for a refusal's words is given. */
+const SCREEN_READ_MS = 5000;
+
+/**
+ * Undefined once the shell in the new tab `handle` is at a ready prompt, or,
+ * when it is not within SHELL_READY_MS, a sentence that says why and names
+ * what its screen shows (#498).
+ */
+async function shellNotReady(handle) {
+  const until = Date.now() + SHELL_READY_MS;
+  let seen;
+  // The last look that was not cut short: what the refusal is about, when the
+  // last one ran out of time.
+  let answered;
+  for (;;) {
+    const look = shellInTab(handle, until);
+    seen = look.late === true ? answered ?? look : look;
+    if (look.late !== true) answered = look;
+    // The calls that decide a yes, lsof and stty last, end by `until`, so a
+    // yes is never late.
+    if (seen.ready === true) return undefined;
+    // The last look ends the wait: one more would have no time to answer in.
+    if (until - Date.now() < SHELL_LOOK_MS + LAST_LOOK_MS) break;
+    await pause(SHELL_LOOK_MS);
+  }
+  const wait = `it did not come to a ready prompt in ${SHELL_READY_MS / 1000} s`;
+  if (seen.program !== undefined) return `${seen.program} is running in front of the shell, and ${wait}`;
+  if (seen.unsure !== undefined) return `the kit could not tell whether the shell is ready (${seen.unsure})`;
+  const read = screenRows(handle, SCREEN_READ_MS);
+  if (read.rows === undefined) return `the shell is asking something, and ${wait}; its screen could not be read (${read.unreadable})`;
+  const last = read.rows.findLast((row) => row.trim() !== '');
+  return last === undefined
+    ? `the shell is asking something, and ${wait}; its screen is blank`
+    : `the shell is asking: ${last.trim()} (${wait})`;
+}
+
 /** 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.';
 
@@ -796,8 +851,11 @@ 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, listLine, listLineTrouble }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, unclaimed, noMailbox = false, listLine, listLineTrouble, notLaunched }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
+  // A tab whose shell was not ready for the launch line, and why: nothing was
+  // typed into it (#498).
+  if (notLaunched !== undefined) Object.assign(made, { launched: false, notLaunched });
   // 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;