@assuredloop/orca-bot-kit 0.25.0 → 0.25.2

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.

package/package.json

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

package/src/clear.js

@@ -19,7 +19,7 @@ import { botDir, readBot } from './bot.js';
 import { claudeTranscript, codexRollout } from './conversations.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 import { eachLine, firstLine } from './lines.js';
-import { findProject, orca, QUESTION_ON_SCREEN, questionIn, screenRows, tabs, tabToTypeInto, TIMED_OUT } from './orca.js';
+import { FEEDBACK_PANEL, feedbackPanelIn, findProject, orca, QUESTION_ON_SCREEN, questionIn, screenRows, tabs, tabToTypeInto, TIMED_OUT } from './orca.js';
 import { botsNamed, sessionsOf, typeListLine } from './up.js';
 
 /** The harness's own command for each, as typed into its input line. Codex's clear is `/new` (tech notes, section 3). */
@@ -201,7 +201,7 @@ async function enter(it, verb, before = () => {}) {
         if (typing === undefined) throw new Error(`${it.name}: ${TYPING_HELD}. Run this again in a moment.`);
         before();
       },
-      cannot: (wrong) => (verb === 'compact' && wrong.menu ? ` ${harnessName(it.harness)} here cannot compact: its menu does not offer ${COMMANDS[verb][it.harness]}.` : ''),
+      cannot: (wrong) => (verb === 'compact' && wrong.menu && it.harness === 'codex' ? ` ${harnessName(it.harness)} here cannot compact: its menu does not offer ${COMMANDS[verb][it.harness]}.` : ''),
     });
     return { ...typed, typing };
   } catch (error) {
@@ -350,8 +350,8 @@ function lookAt(it, { idle = true } = {}) {
   const found = tabToTypeInto(it.home, it.tabId, idle ? LOOK_MS : CHAR_LOOK_MS);
   if (found.blocked !== undefined) {
     return {
-      why: found.blocked === QUESTION_ON_SCREEN
-        ? 'a question of its harness\'s own is on its screen'
+      why: found.blocked === FEEDBACK_PANEL ? PANEL_WHY
+        : found.blocked === QUESTION_ON_SCREEN ? 'a question of its harness\'s own is on its screen'
         : `a question is waiting on its screen: Orca says ${found.blocked}`,
     };
   }
@@ -390,10 +390,18 @@ async function typedWrong(handle, harness, command, version, check) {
   }
 }
 
+/**
+ * Why nothing goes in while Claude Code's panel of feedback drafts is open
+ * (#502): it reads single keys from the input line, and one sends a draft to
+ * Anthropic, so only the user answers it.
+ */
+const PANEL_WHY = 'its panel of feedback drafts is open above its input box, and the kit does not answer it, since a draft sent from it goes to Anthropic: it clears once the user reviews, sends or dismisses the drafts in that tab';
+
 /** Why `rows` say not to type now, as the look says it, or undefined: a turn at work, or a question. */
 function signalIn(rows) {
   const working = rows.find((row) => AT_WORK.some((marker) => marker.test(row)));
   if (working !== undefined) return `it is busy with a turn: its screen shows "${working.trim()}"`;
+  if (feedbackPanelIn(rows)) return PANEL_WHY;
   if (questionIn(rows)) return 'a question of its harness\'s own is on its screen';
   return undefined;
 }

package/src/cli.js

@@ -472,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;
 }
 
 /**
@@ -756,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}`),
       ],
     };
   },
@@ -1771,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;
@@ -427,6 +427,7 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * line, lined up with it, and by its layout that is one.
  */
 export function questionIn(rows) {
+  if (feedbackPanelIn(rows)) return true;
   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
@@ -455,6 +456,39 @@ export function questionIn(rows) {
   return false;
 }
 
+/** The gate's answer for Claude Code's panel of feedback drafts (#502). */
+export const FEEDBACK_PANEL = 'feedback-drafts-panel';
+
+/** The first row in the panel's box, as Claude Code 2.1.291 draws it: `✻ Bug report drafted: <title>`. */
+const PANEL_TITLE = /^ *│ +(?:\S+ +)?(?:Bug report|Product feedback|Feature request|Feedback) drafted: /;
+
+/** What Claude Code 2.1.291 asks in the panel's place after a `0`, its keys' foot last: `… 0 to turn off · Esc to keep`. */
+const PANEL_TURN_OFF = /^Turn off Claude-drafted feedback\? 0 to turn off · Esc to keep$/i;
+
+/**
+ * Whether the rows of a rendered screen show Claude Code's panel of feedback
+ * drafts (#502). It has no pointer and no numbers, but it reads single keys
+ * from the input line, and `2` twice sends a draft to Anthropic. Claude Code
+ * 2.1.291 draws it as a box, its title row first, as the last thing above its
+ * input box's top rule; after a `0`, the question whether to turn the drafts
+ * off stands in its place, wrapped as the pane needs, and a typed line answers
+ * that too. The same words
+ * with anything after them are history.
+ */
+export function feedbackPanelIn(rows) {
+  const at = rows.findLastIndex((row) => POINTER_ROW.test(row));
+  if (at < 1 || !RULE_ROW.test(rows[at - 1])) return false;
+  const end = rows.slice(0, at - 1).findLastIndex((row) => row.trim() !== '');
+  if (end < 0) return false;
+  // The question is plain text, which a narrow pane wraps onto rows of its
+  // own, with a blank row above it: it is the whole block that ends there.
+  const start = rows.slice(0, end).findLastIndex((row) => row.trim() === '') + 1;
+  if (PANEL_TURN_OFF.test(rows.slice(start, end + 1).map((row) => row.trim()).join(' '))) return true;
+  if (!/^ *╰─/.test(rows[end])) return false;
+  const top = rows.slice(0, end).findLastIndex((row) => /^ *╭─/.test(row));
+  return top >= 0 && PANEL_TITLE.test(rows[top + 1]);
+}
+
 /** A rule Claude Code draws right across, as the top of its input box: `─` or `▔`. */
 const RULE_ROW = /^ *[─▔]{8,}/;
 
@@ -538,7 +572,7 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   // Orca's reason does not cover every question: it called Codex's update
   // offer idle, and a return typed into it took "Update now" (#329). So the
   // screen is read too, and one that cannot be read is not a reason to type.
-  if (seen.question === true) return { blocked: QUESTION_ON_SCREEN };
+  if (seen.question === true) return { blocked: feedbackPanelIn(seen.rows) ? FEEDBACK_PANEL : QUESTION_ON_SCREEN };
   if (seen.question === undefined) {
     return { unsure: `the kit could not tell whether a question is waiting on its screen (${seen.screenUnreadable}), so nothing was typed` };
   }
@@ -586,17 +620,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 };
 }
 
 /**
@@ -608,8 +646,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}` : '';
@@ -633,6 +671,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
@@ -646,15 +707,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) };
 }
 
 /**
@@ -670,9 +803,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/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;