@assuredloop/orca-bot-kit 0.23.0 → 0.24.1

package/package.json

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

package/src/book.js

@@ -152,8 +152,13 @@ function takeLock(home) {
   }
 }
 
-/** The lock on `file`, waited for `waitMs` at most: see `takeLock` for why it is this one. */
-function lockOn(file, waitMs) {
+/**
+ * The lock on `file`, waited for `waitMs` at most: see `takeLock` for why it is
+ * this one. `how` is SQLite's: `IMMEDIATE`, one holder at a time; `SHARED`,
+ * any number at once, none while an `EXCLUSIVE` is held or waited for; and
+ * `EXCLUSIVE`, alone, once every `SHARED` holder has let go.
+ */
+function lockOn(file, waitMs, how = 'IMMEDIATE') {
   mkdirSync(path.dirname(file), { recursive: true });
 
   const db = new DatabaseSync(file);
@@ -161,7 +166,13 @@ function lockOn(file, waitMs) {
     // A writer that arrives while another is working waits for it rather than
     // failing at once, and gives up saying so rather than waiting for ever.
     db.exec(`PRAGMA busy_timeout = ${waitMs}`);
-    db.exec('BEGIN IMMEDIATE');
+    if (how === 'SHARED') {
+      // A reading transaction holds its shared lock from its first read.
+      db.exec('BEGIN');
+      db.prepare('SELECT count(*) FROM sqlite_master').get();
+    } else {
+      db.exec(`BEGIN ${how}`);
+    }
   } catch (error) {
     db.close();
     throw error;
@@ -233,6 +244,86 @@ export function takeMailboxTurn(home, session) {
   }
 }
 
+/**
+ * A session's turn to have its Codex thread named (#480), beside its mailbox
+ * turn: `{ release }`, or undefined at once when another naming holds it, so
+ * that two turn ends close together type the name once.
+ */
+export const takeNameTurn = (home, session) => turnOn(home, session, 'name', 0);
+
+/**
+ * A session's typing turn (#480, the architect's ruling), for what the kit
+ * types into the session's tab one key at a time: no line of the kit's may
+ * land in between and send what is there with its own return. Two locks
+ * beside its mailbox turn: `typing`, the gate, held for the whole typing, and
+ * `lines`, taken alone once the lines already on their way have gone in.
+ * Returns `{ release }`, or undefined when it did not come within `waitMs`,
+ * or the lines in flight did not finish within LINES_WAIT_MS.
+ */
+export function takeTypingTurn(home, session, waitMs) {
+  const gate = turnOn(home, session, 'typing', waitMs);
+  if (gate === undefined) return undefined;
+  let lines;
+  try {
+    lines = turnOn(home, session, 'lines', LINES_WAIT_MS, 'EXCLUSIVE');
+  } finally {
+    if (lines === undefined) gate.release();
+  }
+  if (lines === undefined) return undefined;
+  return {
+    release() {
+      try {
+        lines.release();
+      } finally {
+        gate.release();
+      }
+    },
+  };
+}
+
+/**
+ * A session's turn for one whole line, sent with its return in one go, as the
+ * mail nudge is: through the typing turn's gate, waited for `waitMs` at most,
+ * and then held beside any other line, so whole lines never wait on each
+ * other, only on typing one key at a time. Returns `{ release }`, or undefined
+ * when the gate did not come within `waitMs`. Every whole line the kit types
+ * takes it: the nudge, the list line, the skills reload and the grooming line (#482).
+ */
+export function takeLineTurn(home, session, waitMs) {
+  const gate = turnOn(home, session, 'typing', waitMs);
+  if (gate === undefined) return undefined;
+  try {
+    return turnOn(home, session, 'lines', 0, 'SHARED');
+  } finally {
+    gate.release();
+  }
+}
+
+/**
+ * How long a kit path waits for a session's typing turn before it types
+ * nothing (#480, #482): a naming holds it for seconds.
+ */
+export const TYPING_WAIT_MS = 5000;
+
+/** What a kit path reports when the session's typing turn did not come within TYPING_WAIT_MS. */
+export const TYPING_HELD = `the kit is typing into it, and it was still at it after ${TYPING_WAIT_MS / 1000} s, so nothing was typed`;
+
+/**
+ * How long a typing turn waits for the lines already on their way: a nudge
+ * holds its line's turn while Orca waits up to 5 s to see it start a turn.
+ */
+const LINES_WAIT_MS = 10_000;
+
+/** A turn of the kit's own for one session, on a file beside its mailbox turn's. */
+function turnOn(home, session, kind, waitMs, how) {
+  try {
+    return lockOn(mailboxLockFile(home, session).replace(/\.mailbox\.lock$/, `.${kind}.lock`), waitMs, how);
+  } catch (error) {
+    if (error.errcode === SQLITE_BUSY) return undefined;
+    throw error;
+  }
+}
+
 /**
  * How long a step, a check or an `up` waits for a session's turn. Longer than a
  * step can hold it — three Orca calls of twenty seconds each at most — and short

package/src/clear.js

@@ -14,12 +14,12 @@
 import { realpathSync, statSync } from 'node:fs';
 import { setTimeout as pause } from 'node:timers/promises';
 
-import { readBook } from './book.js';
+import { readBook, takeTypingTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 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 } from './orca.js';
+import { 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). */
@@ -58,6 +58,13 @@ const CODEX_BARE_LINE = '0.160.0';
 /** How long the session is given to be idle before nothing is typed, and how long each look waits on it. */
 const IDLE_WAIT_MS = 30_000;
 const LOOK_MS = 2000;
+/**
+ * How long each look between two characters waits on Orca's tui-idle, whose
+ * answer it does not use: an open slash menu keeps it from answering ok (live
+ * run 3 of #391). Short, so a naming holds the session's typing turn for
+ * seconds (#480).
+ */
+const CHAR_LOOK_MS = 250;
 /** How long the screen is given to show the command typed, or Codex's question after `/new`. */
 const SCREEN_MS = 3000;
 /** How long the book is given to hold the new conversation, and a harness to record a compaction (the architect: up to 5 minutes). */
@@ -95,14 +102,20 @@ const AT_WORK = [/esc to interrupt/i, /^\s*\S\s+\S+…\s+\(\d/];
 export async function clearSession(bots, { bot, session }) {
   const it = sessionToType(bots, bot, session);
   const was = readBook(it.home).sessions[session]?.session ?? null;
-  const { command, handle } = await enter(it, 'clear');
+  const { command, handle, typing } = await enter(it, 'clear');
 
-  if (it.harness === 'codex') {
-    await answerWhereToRun(it, handle, command);
-    const line = await typeListLine(it.home, it.tabId, RECORD_LINE);
-    if (!line.typed) {
-      throw new Error(`${it.name}: ${command} went in, but the line that starts the new conversation's first turn was not typed (${line.why}), and Codex reports a new conversation only at its first turn. The book still holds ${was ?? 'no conversation'}. Look at its tab.`);
+  // Codex's question and the line after it are part of the clear, typed in
+  // the typing turn it took for the command.
+  try {
+    if (it.harness === 'codex') {
+      await answerWhereToRun(it, handle, command);
+      const line = await typeListLine(it.home, it.session, it.tabId, { line: RECORD_LINE, held: true });
+      if (!line.typed) {
+        throw new Error(`${it.name}: ${command} went in, but the line that starts the new conversation's first turn was not typed (${line.why}), and Codex reports a new conversation only at its first turn. The book still holds ${was ?? 'no conversation'}. Look at its tab.`);
+      }
     }
+  } finally {
+    typing.release();
   }
 
   const until = Date.now() + CLEAR_MS;
@@ -128,9 +141,10 @@ export async function compactSession(bots, { bot, session }) {
   // that ends while the kit waits for the session to be idle is the one
   // before it (review of PR #466). So only what is written after counts.
   let record;
-  const { typedAt } = await enter(it, 'compact', () => {
+  const { typedAt, typing } = await enter(it, 'compact', () => {
     record = recordAt(it.harness, it.home, readBook(it.home).sessions[session]?.session ?? null);
   });
+  typing.release();
 
   const until = typedAt + COMPACT_MS;
   for (;;) {
@@ -150,7 +164,7 @@ export async function compactSession(bots, { bot, session }) {
  * The session as something to type into, once everything that refuses before
  * Orca is asked to type has been asked: `{ name, home, session, harness, tabId }`.
  */
-function sessionToType(bots, bot, session) {
+export function sessionToType(bots, bot, session) {
   botsNamed(bots, bot);
   const home = realpathSync(botDir(bots, bot));
   const known = readBot(home, bot);
@@ -174,22 +188,58 @@ function sessionToType(bots, bot, session) {
  * Type the harness's command for `verb` into the session's tab and press
  * return, once it is idle and the screen shows the command typed and nothing
  * else. `before` runs just before the command is typed. Returns the command,
- * the handle it went into, and when it was typed.
+ * the handle it went into, when it was typed, and the session's typing turn
+ * (#482), taken once it is idle, as the naming takes it, and held for the
+ * caller to release.
  */
 async function enter(it, verb, before = () => {}) {
-  const command = COMMANDS[verb][it.harness];
-  const { handle, rows } = await idleTab(it);
+  let typing;
+  try {
+    const typed = await typeCommand(it, COMMANDS[verb][it.harness], {
+      before: () => {
+        typing = takeTypingTurn(it.home, it.session, TYPING_WAIT_MS);
+        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]}.` : ''),
+    });
+    return { ...typed, typing };
+  } catch (error) {
+    typing?.release();
+    throw error;
+  }
+}
+
+/**
+ * Type `command` into the session's tab, `it` as `sessionToType` gives it, and
+ * press return, once it is idle and `check` finds nothing wrong with the
+ * screen: by default the slash menu's check, which a command with words after
+ * it does not pass, since Codex closes its menu at the space (#480). `before`
+ * runs just before the command is typed; `cannot` adds to a refusal what a
+ * wrong screen means; past `deadline`, a time, what was typed is taken back
+ * and nothing is entered. Returns the command, the handle it went into, and
+ * when it was typed.
+ */
+export async function typeCommand(it, command, { before = () => {}, check = menuWrong, cannot = () => '', deadline = Infinity } = {}) {
   // On Codex, what is typed cannot be read back once its menu is open, so
   // nothing may be in its input line before: no draft for the command to join.
-  if (it.harness === 'codex') {
+  const emptyLine = (rows) => {
+    if (it.harness !== 'codex') return;
     const line = rows.findLast((row) => /^ *›/.test(row))?.trim();
     if (!CODEX_EMPTY.includes(line)) {
       throw new Error(`${it.name}: nothing was typed, because its input line is not empty: it reads "${line ?? 'nothing'}".${shownEnd(rows)}`);
     }
-  }
+  };
+  emptyLine((await idleTab(it)).rows);
   const version = it.harness === 'codex' ? codexVersion(readBook(it.home).sessions[it.session]?.session) : undefined;
 
   before();
+  // What `before` waited for can have changed the session: one more look,
+  // with no wait, before the first key (#480 review).
+  const ready = lookAt(it);
+  if (ready.why !== undefined) throw new Error(`${it.name}: nothing was typed, because ${ready.why}.`);
+  emptyLine(ready.rows);
+  const { handle } = ready;
   const typedAt = Date.now();
   // One character a send, each after a look through the gate, so nothing goes
   // in as one burst and nothing goes in once something asks a question
@@ -197,31 +247,63 @@ async function enter(it, verb, before = () => {}) {
   // Between characters, and once more before the return, the look is the gate
   // and the harness's own at-work row, not Orca's tui-idle: an open slash menu
   // can stop it answering ok (live run 3).
+  // The characters Orca took, and so what is in the input line of ours.
   let typed = 0;
+  // Taken back, one backspace a character, in one send, so the input line is
+  // as it was. Whatever stops the typing takes them back, a send Orca refused
+  // or a look that threw included (#480 review); a take-back Orca refuses
+  // too leaves nothing more the kit can do.
+  const takeBack = () => {
+    const keys = '\x7f'.repeat(typed);
+    typed = 0;
+    if (keys === '') return;
+    try {
+      send(handle, keys);
+    } catch {
+      // Said by the error that stopped the typing.
+    }
+  };
   const lookAgain = async () => {
     await pause(CHAR_GAP_MS);
     const look = lookAt(it, { idle: false });
+    // Past the caller's deadline nothing more goes in: a hook stopped partway
+    // would leave the text in the input line (#480 review).
+    if (look.why === undefined && Date.now() > deadline) look.why = 'its time ran out';
     if (look.why === undefined) return;
-    send(handle, '\x7f'.repeat(typed));
-    throw new Error(`${it.name}: ${command} was being typed, and after ${command.slice(0, typed)} ${look.why}, so what was typed was taken back and nothing was entered.`);
+    const sofar = command.slice(0, typed);
+    takeBack();
+    throw new Error(`${it.name}: ${command} was being typed, and after ${sofar} ${look.why}, so what was typed was taken back and nothing was entered.`);
   };
-  for (const char of command) {
-    if (typed > 0) await lookAgain();
-    send(handle, char);
-    typed += 1;
-  }
-  await lookAgain();
-  const wrong = await typedWrong(handle, it.harness, command, version);
-  if (wrong !== undefined) {
-    // Taken back, one backspace a character, so the input line is as it was.
-    send(handle, '\x7f'.repeat(command.length));
-    const cannot = verb === 'compact' && wrong.menu ? ` ${harnessName(it.harness)} here cannot compact: its menu does not offer ${command}.` : '';
-    throw new Error(`${it.name}: ${command} was typed but not entered, and was taken back, because ${wrong.why}.${cannot}${shownEnd(wrong.rows)}`);
+  try {
+    for (const char of command) {
+      if (typed > 0) await lookAgain();
+      try {
+        send(handle, char);
+      } catch (error) {
+        // A send Orca did not answer in time may have gone in all the same.
+        // Counted only where the line was empty before the first key, so the
+        // one backspace too many can take nothing of the user's (#480 review).
+        if (error.code === TIMED_OUT && it.harness === 'codex') typed += 1;
+        throw error;
+      }
+      typed += 1;
+    }
+    await lookAgain();
+    let wrong = await typedWrong(handle, it.harness, command, version, check);
+    if (wrong === undefined && Date.now() > deadline) wrong = { why: 'its time ran out' };
+    if (wrong !== undefined) {
+      takeBack();
+      throw new Error(`${it.name}: ${command} was typed but not entered, and was taken back, because ${wrong.why}.${cannot(wrong)}${shownEnd(wrong.rows)}`);
+    }
+    // A return of its own, not `--enter`: Orca's gate can refuse a line sent
+    // with `--enter` while it names a reason, and on Codex a return inside the
+    // text lands in the draft (helpers in the system tests, #329).
+    send(handle, '\r');
+    typed = 0;
+  } catch (error) {
+    takeBack();
+    throw error;
   }
-  // A return of its own, not `--enter`: Orca's gate can refuse a line sent
-  // with `--enter` while it names a reason, and on Codex a return inside the
-  // text lands in the draft (helpers in the system tests, #329).
-  send(handle, '\r');
   return { command, handle, typedAt };
 }
 
@@ -235,6 +317,7 @@ async function idleTab(it) {
   const until = Date.now() + IDLE_WAIT_MS;
   for (;;) {
     const look = lookAt(it);
+    if (look.moved) throw new Error(`${it.name}: nothing was typed, because ${look.why}.`);
     let why = look.why;
     // The wait is a cutoff, not a count of looks: a yes that comes after it
     // is too late (as for LIST_LINE, review of PR #421).
@@ -248,11 +331,23 @@ async function idleTab(it) {
 /**
  * One look through the typing gate at the session's tab: `{ handle }` when
  * nothing on its screen asks a question and nothing says it is at work, and,
- * with `idle`, Orca's tui-idle answered ok; or `{ why }`, naming the signal.
+ * with `idle`, Orca's tui-idle answered ok; or `{ why }`, naming the signal,
+ * with `moved` when the book holds another tab for the session now, or, where
+ * `it.conversation` is given, another conversation.
  * Throws when the tab holds no harness.
  */
 function lookAt(it, { idle = true } = {}) {
-  const found = tabToTypeInto(it.home, it.tabId, LOOK_MS);
+  // A restart can give the session a new tab while this waits or types, and
+  // a hook can outlive its Codex (#480): only the tab the book holds is the
+  // session's.
+  const entry = readBook(it.home).sessions[it.session];
+  if (entry?.tab !== it.tabId) return { moved: true, why: `the book no longer holds its tab ${it.tabId} for it, but ${entry?.tab ?? 'none'}` };
+  // And, for a caller typing for one conversation, a `/new` in the same tab
+  // gives the session another (#480 review).
+  if (it.conversation !== undefined && entry.session !== it.conversation) {
+    return { moved: true, why: `the book no longer holds the conversation ${it.conversation} for it, but ${entry.session ?? 'none'}` };
+  }
+  const found = tabToTypeInto(it.home, it.tabId, idle ? LOOK_MS : CHAR_LOOK_MS);
   if (found.blocked !== undefined) {
     return {
       why: found.blocked === QUESTION_ON_SCREEN
@@ -274,13 +369,14 @@ function lookAt(it, { idle = true } = {}) {
 
 /**
  * Why the screen does not show `command` typed and ready, or undefined when it
- * does: the input line, the lowest row the harness's pointer starts, reads the
- * pointer and the command and nothing else, and the slash menu's selected row
- * names the command. `menu` is set when the input line was right and the menu
- * was not. Read again for SCREEN_MS while it is not so: a screen
+ * does, as `check` reads it: for a slash command alone, the input line, the
+ * lowest row the harness's pointer starts, reads the pointer and the command
+ * and nothing else, and the slash menu's selected row names the command.
+ * `menu` is set when the input line was right and the menu was not. Read
+ * again for SCREEN_MS while it is not so: a screen
  * takes a moment to draw what was typed.
  */
-async function typedWrong(handle, harness, command, version) {
+async function typedWrong(handle, harness, command, version, check) {
   const until = Date.now() + SCREEN_MS;
   for (;;) {
     const seen = screenRows(handle, READ_MS);
@@ -288,7 +384,7 @@ async function typedWrong(handle, harness, command, version) {
     // a question that shows on it stops it at once (review of c1e5ba4).
     const signal = seen.rows === undefined ? undefined : signalIn(seen.rows);
     if (signal !== undefined) return { why: signal, rows: seen.rows };
-    const wrong = seen.rows === undefined ? { why: `its screen could not be read (${seen.unreadable})` } : menuWrong(seen.rows, harness, command, version);
+    const wrong = seen.rows === undefined ? { why: `its screen could not be read (${seen.unreadable})` } : check(seen.rows, harness, command, version);
     if (wrong === undefined || Date.now() >= until) return wrong && { ...wrong, rows: seen.rows };
     await pause(ASK_MS);
   }
@@ -449,7 +545,10 @@ function shownEnd(rows) {
 /** How many rows of the screen a refusal shows. */
 const SHOWN_ROWS = 12;
 
+/** How long Orca is given to take one send: a send it never answers must not hold the caller (#480 review). */
+const SEND_MS = 5000;
+
 /** Type `keys` into the tab as they are, with no return of Orca's. */
-const send = (handle, keys) => orca(['terminal', 'send', '--terminal', handle, '--text', keys]);
+const send = (handle, keys) => orca(['terminal', 'send', '--terminal', handle, '--text', keys], { timeoutMs: SEND_MS });
 
 const harnessName = (harness) => (harness === 'claude' ? 'Claude Code' : 'Codex');

package/src/cli.js

@@ -16,6 +16,7 @@ import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, c
 import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
+import { nameSession } from './name.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
 import { checkMail, decideLeftNudges, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE, TERMINAL_ENV } from './orca.js';
@@ -274,6 +275,11 @@ Usage:
                             nudges a send there left because it could not
                             tell from inside Codex's sandbox, and types each
                             one or says why not.
+  obk session name --bots <path> --bot <bot>
+                            For the kit's own hook, not for typing: after a
+                            Codex session's turn, it names the session's thread
+                            <bot>.<session> with Codex's /rename, once the
+                            session is idle, so its tab says which it is.
   obk session mailbox --bots <path> --bot <bot> --session <name>
                             For the kit's own launch line, not for typing: run
                             in the session's own tab, it gives the session its
@@ -317,6 +323,7 @@ const COMMANDS = {
   'session record': ['bots', 'bot'],
   'session sent': ['bots', 'bot'],
   'session nudge': ['bots', 'bot'],
+  'session name': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
   'temp make': ['bots', 'name'],
   'temp roles': ['bots'],
@@ -449,6 +456,7 @@ async function run(argv) {
   // there included, so it goes before anything that can complain (ADR 0032).
   if (command === SENT) return sent(path.resolve(values.bots));
   if (command === NUDGE) return nudgeLeft();
+  if (command === NAME) return nameThread(path.resolve(values.bots), values.bot);
 
   // One fleet, one identity, whatever spelling of its path was given (#164).
   const bots = command === 'init' ? path.resolve(values.bots) : sameFleet(path.resolve(values.bots));
@@ -517,6 +525,7 @@ const ANSWER_IT = [
 const RECORD = 'session record';
 const SENT = 'session sent';
 const NUDGE = 'session nudge';
+const NAME = 'session name';
 
 /**
  * What the kit's send hook says after a native message: a warning the session
@@ -556,6 +565,21 @@ function nudgeLeft() {
   return 0;
 }
 
+/**
+ * What the kit's Codex Stop hook does at a turn end: name the session's thread
+ * after its bot and session, once it is idle (#480). Silent, never a decision,
+ * and never anything but exit 0: what it could not type now waits for the next
+ * turn end.
+ */
+async function nameThread(bots, bot) {
+  try {
+    await nameSession(bots, bot, JSON.parse(readFileSync(0, 'utf8')), process.env[TAB_ENV]);
+  } catch {
+    // Nothing: a hook does not disturb the session it runs in.
+  }
+  return 0;
+}
+
 /**
  * What the kit's hook does with what the harness told it, and what it answers.
  *

package/src/groom.js

@@ -42,7 +42,7 @@ import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { botDir, readBot, requireBotsFolder } from './bot.js';
-import { readBook } from './book.js';
+import { readBook, takeLineTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { claudeTranscript } from './conversations.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 import { tabs, tabToTypeInto, typeIntoTab } from './orca.js';
@@ -189,21 +189,28 @@ function refuseRun(run, ask) {
 /**
  * Type `line` into the grooming tab, through the kit's one gate for typing into
  * a running session: nothing goes into a tab with something on screen waiting
- * for an answer, or with anything but Claude Code in front of it.
+ * for an answer, or with anything but Claude Code in front of it. In the
+ * session's turn for a line, so it never lands in what the kit is typing (#482).
  */
 function typeInto(bots, home, session, tab, line) {
   if (!session.up) {
     throw new Error(`${BOT_FATHER}'s ${GROOMING} session is not up, so nothing was typed. Bring it up with ${upCommand(bots)}, then run this again.`);
   }
-  const found = tabToTypeInto(home, tab, LOOK_MS);
-  if (found.blocked !== undefined) {
-    throw new Error(`the ${GROOMING} tab is waiting for an answer (${found.blocked}), so nothing was typed. Answer it in the tab, then run this again.`);
-  }
-  if (found.unsure !== undefined) throw new Error(`the ${GROOMING} tab: ${found.unsure}.`);
-  if (found.handle === undefined || found.agent !== 'claude') {
-    throw new Error(`the ${GROOMING} tab has no Claude Code in front of it, so nothing was typed. Bring it back with ${restartCommand(bots)}, then run this again.`);
+  const turn = takeLineTurn(home, GROOMING, TYPING_WAIT_MS);
+  if (turn === undefined) throw new Error(`the ${GROOMING} tab: ${TYPING_HELD}. Run this again in a moment.`);
+  try {
+    const found = tabToTypeInto(home, tab, LOOK_MS);
+    if (found.blocked !== undefined) {
+      throw new Error(`the ${GROOMING} tab is waiting for an answer (${found.blocked}), so nothing was typed. Answer it in the tab, then run this again.`);
+    }
+    if (found.unsure !== undefined) throw new Error(`the ${GROOMING} tab: ${found.unsure}.`);
+    if (found.handle === undefined || found.agent !== 'claude') {
+      throw new Error(`the ${GROOMING} tab has no Claude Code in front of it, so nothing was typed. Bring it back with ${restartCommand(bots)}, then run this again.`);
+    }
+    typeIntoTab(found.handle, line);
+  } finally {
+    turn.release();
   }
-  typeIntoTab(found.handle, line);
 }
 
 /**

package/src/hooks.js

@@ -69,6 +69,21 @@ const NUDGE_TIMEOUT = 30;
 export const nudgeCommand = (bots, bot, cli = ownCli()) =>
   `${shellWord(cli)} session nudge --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
+/**
+ * Codex's third kit hook: at each turn end, the session's thread is named after
+ * its bot and session, so its tab says which it is (#480). Async, so the turn
+ * ends without waiting on it: it waits for the session to be idle, up to 30 s,
+ * then types and confirms. A naming took 73 s live, each character waiting on
+ * a look through Orca's gate, and a hook stopped partway would leave half the
+ * command in the input line, so the timeout leaves room to spare.
+ */
+const NAME_EVENT = 'Stop';
+const NAME_TIMEOUT = 300;
+
+/** What the naming hook runs, by the kit's own path, as `hookCommand` does. */
+export const nameCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session name --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+
 /**
  * Make sure the bot at `home` has the kit's SessionStart hook for `harness`.
  * Returns the file it wrote, relative to the bot home, or undefined when the
@@ -91,7 +106,7 @@ export function installHook(home, harness, { bots, bot }) {
   // longer asks about is taken out, and a hook of the user's beside the kit's
   // stays where they put it.
   const started = withKitHook(settings.hooks, file, mine);
-  const wanted = { ...settings, hooks: withToolHook(started, toolHookOf(harness, bots, bot)) };
+  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, started) };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -138,26 +153,29 @@ export function hookTrouble(home, harness, { bots, bot }) {
     }
     const program = running ?? ownCli();
     wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
-    // The harness's second hook is judged on its own: the session hook may be
-    // right while the warning after a native message (ADR 0032), or the nudge
-    // a Codex sender left (ADR 0034), is missing.
+    // The harness's other hooks are each judged on their own: the session hook
+    // may be right while the warning after a native message (ADR 0032), the
+    // nudge a Codex sender left (ADR 0034), or the naming of a Codex thread
+    // (#480) is missing.
     if (isDeepStrictEqual(settings, wanted)) {
-      const tool = toolHookOf(harness, bots, bot);
-      const toolRunning = programIn(settings, tool.pattern);
-      // One that runs a kit no longer there is as quiet as a missing one:
-      // `|| true` hides it (#451 review).
-      if (toolRunning !== undefined && toolRunning !== BARE && !existsSync(toolRunning)) {
-        return {
-          where: file,
-          says: `${file} holds the kit's ${tool.event} hook for ${tool.matcher}, but it runs ${toolRunning}, which is not there any more, so ${tool.missing}. obk up puts back one that runs the kit you have.`,
-        };
-      }
-      const withTool = { ...settings, hooks: withToolHook(settings.hooks, toolHookOf(harness, bots, bot, toolRunning ?? program)) };
-      if (!isDeepStrictEqual(settings, withTool)) {
-        return {
-          where: file,
-          says: `${file} does not hold the kit's ${tool.event} hook for ${tool.matcher}, without which ${tool.missing}. obk up puts it back.`,
-        };
+      for (const tool of toolHooksOf(harness, bots, bot)) {
+        const toolRunning = programIn(settings, tool.pattern);
+        const what = tool.matcher === undefined ? `${tool.event} hook` : `${tool.event} hook for ${tool.matcher}`;
+        // One that runs a kit no longer there is as quiet as a missing one:
+        // `|| true` hides it (#451 review).
+        if (toolRunning !== undefined && toolRunning !== BARE && !existsSync(toolRunning)) {
+          return {
+            where: file,
+            says: `${file} holds the kit's ${what}, but it runs ${toolRunning}, which is not there any more, so ${tool.missing}. obk up puts back one that runs the kit you have.`,
+          };
+        }
+        const withTool = { ...settings, hooks: withToolHook(settings.hooks, toolHookOf(tool.kind, bots, bot, toolRunning ?? program)) };
+        if (!isDeepStrictEqual(settings, withTool)) {
+          return {
+            where: file,
+            says: `${file} does not hold the kit's ${what}, without which ${tool.missing}. obk up puts it back.`,
+          };
+        }
       }
     }
   } catch (error) {
@@ -230,15 +248,29 @@ function withKitHook(hooks, file, mine) {
   return { ...events, [EVENT]: [...(events[EVENT] ?? []), { hooks: [mine] }] };
 }
 
+/** Each harness's kit hooks beside its session hook, as `toolHookOf` gives each. */
+const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
+  (harness === 'claude' ? ['sent'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
+
 /**
- * Each harness's second kit hook, after one of its tools: Claude Code's after a
- * native `SendMessage` (ADR 0032), Codex's after its shell tool (ADR 0034).
- * The entry, where it goes, how the kit knows its own, and what is lost
- * without it.
+ * One of the kit's hooks beside its session hook: Claude Code's after a native
+ * `SendMessage` (`sent`, ADR 0032), Codex's after its shell tool (`nudge`,
+ * ADR 0034), and Codex's at a turn end (`name`, #480). The entry, where it
+ * goes, how the kit knows its own, and what is lost without it.
  */
-function toolHookOf(harness, bots, bot, cli = ownCli()) {
-  if (harness === 'claude') {
+function toolHookOf(kind, bots, bot, cli = ownCli()) {
+  if (kind === 'name') {
+    return {
+      kind,
+      event: NAME_EVENT,
+      pattern: KIT_NAME,
+      mine: { type: 'command', command: nameCommand(bots, bot, cli), timeout: NAME_TIMEOUT, async: true },
+      missing: "a Codex session's thread is never named after its bot and session, and its tab shows a topic Codex made up instead (#480)",
+    };
+  }
+  if (kind === 'sent') {
     return {
+      kind,
       event: SENT_EVENT,
       matcher: SENT_MATCHER,
       pattern: KIT_SENT,
@@ -247,6 +279,7 @@ function toolHookOf(harness, bots, bot, cli = ownCli()) {
     };
   }
   return {
+    kind,
     event: NUDGE_EVENT,
     matcher: NUDGE_MATCHER,
     pattern: KIT_NUDGE,
@@ -257,10 +290,11 @@ function toolHookOf(harness, bots, bot, cli = ownCli()) {
 
 /**
  * The hooks with the kit's tool hook in a group of its event matched to its
- * tool, and everything else as the user left it, as `withKitHook` keeps the
- * session hook: one entry of the kit's, written in place where it already sits
- * in such a group, taken out of anywhere else, and added in a group of its own
- * when there is none. A group the kit empties goes.
+ * tool (or with no matcher, for one that has none), and everything else as the
+ * user left it, as `withKitHook` keeps the session hook: one entry of the
+ * kit's, written in place where it already sits in such a group, taken out of
+ * anywhere else, and added in a group of its own when there is none. A group
+ * the kit empties goes.
  */
 function withToolHook(hooks, { event: wantedEvent, matcher, pattern, mine }) {
   let placed = false;
@@ -279,7 +313,8 @@ function withToolHook(hooks, { event: wantedEvent, matcher, pattern, mine }) {
     return kept.length === 0 ? [] : [[event, kept]];
   }));
   if (placed) return events;
-  return { ...events, [wantedEvent]: [...(events[wantedEvent] ?? []), { matcher, hooks: [mine] }] };
+  const group = matcher === undefined ? { hooks: [mine] } : { matcher, hooks: [mine] };
+  return { ...events, [wantedEvent]: [...(events[wantedEvent] ?? []), group] };
 }
 
 /** The program a command of the kit's of this pattern runs, unquoted, or undefined for any other command. */
@@ -320,6 +355,7 @@ const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
 const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 
 /** The program a bot made before the kit named itself by path runs. */
 const BARE = 'obk';

package/src/message.js

@@ -19,7 +19,7 @@ import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync,
 import os from 'node:os';
 import path from 'node:path';
 
-import { MAILBOX_WAIT_MS, readBook, takeMailboxTurn } from './book.js';
+import { MAILBOX_WAIT_MS, readBook, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
 import { harnessOf, isAddressOf, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
 import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, typeIntoTab, useMailbox } from './orca.js';
@@ -456,6 +456,18 @@ const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '
 function nudge(to, from, subject, tab) {
   if (to.tab === undefined) return { nudged: false };
 
+  // A line typed while the kit types a command one key at a time would land
+  // in it and send it with its own return (#480): so the receiver's turn for
+  // a line first, for a bounded time, and the mail waits in its mailbox if not.
+  let turn;
+  try {
+    turn = takeLineTurn(to.home, to.session, TYPING_WAIT_MS);
+  } catch (error) {
+    return { nudged: false, nudgeTrouble: error.message };
+  }
+  if (turn === undefined) {
+    return { nudged: false, nudgeTrouble: TYPING_HELD };
+  }
   try {
     const found = lookAt(to);
     if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
@@ -483,6 +495,8 @@ function nudge(to, from, subject, tab) {
     // silent `false` would read as "the session is not up", which is a
     // different thing from "Orca would not say".
     return { nudged: false, nudgeTrouble: error.message };
+  } finally {
+    turn.release();
   }
 }
 

package/src/name.js

@@ -0,0 +1,138 @@
+// `obk session name`: the kit names a Codex session's thread `<bot>.<session>`
+// (#480), so the tab, which Codex titles with the thread's name after every
+// turn, says which bot and session it is. A Claude session has its name from
+// the kit's `-n` already.
+//
+// Codex 0.160.0 has no launch-time way to name a thread, so this types Codex's
+// own `/rename` (the architect's ruling on #480). It runs from the kit's async
+// Stop hook (src/hooks.js) at each turn end, never inside a turn: a fresh
+// start's first turn is its start prompt, which nothing may cut off. It types
+// only through the path `obk session clear` takes (src/clear.js, #391), and
+// what is not safe to type now waits for the next turn end.
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { setTimeout as pause } from 'node:timers/promises';
+
+import { readBook, takeNameTurn, takeTypingTurn } from './book.js';
+import { botDir, readBot } from './bot.js';
+import { sessionToType, typeCommand } from './clear.js';
+import { harnessOf } from './launch.js';
+import { sessionsOf } from './up.js';
+
+/**
+ * Where Codex keeps its threads' names: a line `{ id, thread_name, updated_at }`
+ * a name, the file only growing and the newest line for an id winning
+ * (codex-rs/rollout/src/session_index.rs, rust-v0.160.0).
+ */
+const sessionIndex = () => path.join(homedir(), '.codex', 'session_index.jsonl');
+
+/**
+ * When a naming stops typing, counted from its start: well inside the hook's
+ * 300 s (src/hooks.js), at which Codex kills the hook's whole process group
+ * (codex-rs/hooks/src/engine/command_runner.rs), so that what was typed is
+ * taken back first.
+ */
+const DEADLINE_MS = 240_000;
+
+/** How long Codex is given to write the name down after the return. */
+const CONFIRM_MS = 10_000;
+const ASK_MS = 500;
+
+/**
+ * Name the thread that just ended a turn in the tab `tabId`, as Codex's Stop
+ * hook `said` it, when that tab is a Codex session of `bot` and its thread does
+ * not have the name yet. Returns whether Codex's record names it afterwards,
+ * or undefined when there was nothing to do. Throws when it could not type.
+ */
+export async function nameSession(bots, bot, said, tabId) {
+  const deadline = Date.now() + DEADLINE_MS;
+  if (said?.hook_event_name !== 'Stop') return undefined;
+  if (typeof tabId !== 'string' || tabId === '') return undefined;
+
+  const home = realpathSync(botDir(bots, bot));
+  const [session, entry] = Object.entries(readBook(home).sessions).find(([, one]) => one?.tab === tabId) ?? [];
+  if (session === undefined) return undefined;
+  const known = readBot(home, bot);
+  const [settings] = sessionsOf(known, session);
+  if (harnessOf(settings, known.harness) !== 'codex') return undefined;
+  // Only the thread the book says this tab is running. A Codex that Orca
+  // brought back by itself runs its hooks in Codex's shared background server,
+  // under another session's tab (#408), and that tab shows another thread.
+  const thread = said.session_id;
+  if (typeof thread !== 'string' || thread !== entry.session) return undefined;
+
+  const name = `${bot}.${session}`;
+  if (nameOf(thread) === name) return undefined;
+
+  const turn = takeNameTurn(home, session);
+  if (turn === undefined) return undefined;
+  let typing;
+  try {
+    // Another naming may have finished while this one waited for its turn.
+    if (nameOf(thread) === name) return undefined;
+    // Only into the tab the hook ran in: one whose Codex was killed hard can
+    // leave its hook running (Codex starts each hook in a session of its own,
+    // codex-rs/hooks/src/engine/command_runner.rs), and the tab the book holds
+    // now shows another process.
+    const it = { ...sessionToType(bots, bot, session), conversation: thread };
+    if (it.tabId !== tabId) return undefined;
+    // The session's typing turn, taken once it is idle and not before, so a
+    // mail nudge waits seconds for it and not the whole wait for idle. Held by
+    // anything else: nothing is typed, and the next turn end tries again.
+    const before = () => {
+      typing = takeTypingTurn(home, session, 0);
+      if (typing === undefined) throw new Error(`${it.name}: nothing was typed, because the kit is typing into its tab already.`);
+    };
+    try {
+      await typeCommand(it, `/rename ${name}`, { check: renameWrong, deadline, before });
+    } finally {
+      typing?.release();
+    }
+    const until = Date.now() + CONFIRM_MS;
+    while (nameOf(thread) !== name && Date.now() < until) await pause(ASK_MS);
+    return nameOf(thread) === name;
+  } finally {
+    turn.release();
+  }
+}
+
+/** The name Codex's record gives `thread` now, or undefined. */
+function nameOf(thread) {
+  let text;
+  try {
+    text = readFileSync(sessionIndex(), 'utf8');
+  } catch {
+    return undefined;
+  }
+  let name;
+  for (const line of text.split('\n')) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry?.id === thread && typeof entry.thread_name === 'string') name = entry.thread_name;
+  }
+  return name;
+}
+
+/**
+ * Why the screen does not show `command` typed and ready, or undefined when it
+ * does: the input line, the lowest row Codex's pointer starts, reads the
+ * pointer and the command exactly, and no row of its slash menu stands above
+ * it. With words after the command Codex has closed its menu (chat_composer.rs
+ * `sync_command_popup`, rust-v0.160.0), so a menu still open means the line is
+ * not what it seems.
+ */
+function renameWrong(rows, _harness, command) {
+  const at = rows.findLastIndex((row) => /^ *›/.test(row));
+  if (at < 0) return { why: 'its screen shows no input line' };
+  const line = rows[at].replaceAll(' ', ' ').trim();
+  if (line !== `› ${command}`) return { why: `its input line reads "${line}"` };
+  const above = rows.slice(0, at).findLast((row) => row.trim() !== '');
+  if (above !== undefined && /^ *(?:› +)?\/\S/.test(above)) return { why: `a menu of commands stands above its input line: "${above.trim()}"` };
+  return undefined;
+}

package/src/skills.js

@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 
 import { parse, parseDocument, stringify } from 'yaml';
 
-import { bookFile, readBook } from './book.js';
+import { bookFile, readBook, takeLineTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, botNames, changesExactly, leadsOutside, readBot, YAML_OUT } from './bot.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 import { orcaCli, orcaTrouble, tabToTypeInto, typeIntoTab } from './orca.js';
@@ -473,7 +473,14 @@ function tellSessions(home, bot, linked) {
     const tab = typeof book[session.name]?.tab === 'string' ? book[session.name].tab : undefined;
     if (tab === undefined) return { ...told, state: 'not-up' };
     if (down !== undefined) return { ...told, state: 'unknown', trouble: `Orca is not answering at ${orcaCli()}, so the kit could not look at its tab, and nothing was typed` };
+    let turn;
     try {
+      // The session's turn for a line (#482), for the look and its line. Codex
+      // is typed nothing here, so it waits for none.
+      if (harness !== 'codex') {
+        turn = takeLineTurn(real, session.name, TYPING_WAIT_MS);
+        if (turn === undefined) return { ...told, state: 'unknown', trouble: TYPING_HELD };
+      }
       const found = tabToTypeInto(real, tab, LOOK_MS);
       if (found.blocked !== undefined) return { ...told, state: 'blocked', blocked: found.blocked };
       if (found.unsure !== undefined) return { ...told, state: 'unknown', trouble: found.unsure };
@@ -495,6 +502,8 @@ function tellSessions(home, bot, linked) {
       // The links are made whatever Orca says, so this is reported, not
       // thrown: the build did what it was asked, and the session was not told.
       return { ...told, state: 'unknown', trouble: error.message };
+    } finally {
+      turn?.release();
     }
   });
 }

package/src/temp.js

@@ -28,7 +28,7 @@ import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
-import { readBook, updateBook } from './book.js';
+import { readBook, takeLineTurn, TYPING_HELD, TYPING_WAIT_MS, updateBook } from './book.js';
 import { addSession, dropSession, NAME, readBot, tempRoles } from './bot.js';
 import { DEFAULT_APPROVAL, harnessOf, isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
 import { sessionInTab } from './message.js';
@@ -353,16 +353,23 @@ export async function trustHooks(bots, { tab, name }) {
   if (handle === undefined) {
     throw new Error(`${run} has no tab open in Orca, so there is no review of its to answer. ${nothing}`);
   }
-  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}`);
-  }
-  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 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}.`);
+  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}`);
+    }
+    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]);
+  } finally {
+    turn.release();
   }
-  // The return is inside the text: `--enter` would be a second key.
-  orca(['terminal', 'send', '--terminal', handle, '--text', keys]);
   for (let waited = 0; ; waited += 500) {
     const after = screenRows(handle);
     if (after.rows !== undefined && !after.rows.some((row) => row.includes(HOOKS_REVIEW))) break;

package/src/up.js

@@ -8,7 +8,7 @@ import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
-import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, sessionIdsIn, tabIdsIn, takeMailboxTurn, updateBook, withUnclaimed } from './book.js';
+import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, sessionIdsIn, tabIdsIn, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, projectName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
@@ -374,7 +374,7 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // 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)
+    ? await typeListLine(home, session.name, made.tabId)
     : undefined;
 
   return entry(made, {
@@ -408,43 +408,65 @@ const LIST_LOOK_MS = 2000;
 const LIST_ASK_MS = 500;
 
 /**
- * Type `line`, LIST_LINE unless told otherwise, 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.
+ * Type `line`, LIST_LINE unless told otherwise, into the tab `tabId` of
+ * `session` 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. Each look and its
+ * line are taken in the session's turn for a line (#482), unless the caller
+ * says it holds the session's typing turn already (`held`).
  */
-export async function typeListLine(home, tabId, line = LIST_LINE) {
+export async function typeListLine(home, session, tabId, { line = LIST_LINE, held = false } = {}) {
   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) {
+    let turn;
+    if (!held) {
       try {
-        typeIntoTab(found.handle, line);
-        return { typed: true };
+        turn = takeLineTurn(home, session, TYPING_WAIT_MS);
       } catch (error) {
-        return { typed: false, why: `Orca refused the line: ${error.message}` };
+        return { typed: false, why: error.message };
       }
+      if (turn === undefined) return { typed: false, why: TYPING_HELD };
     }
-    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}` };
+    try {
+      const done = lookAndType(home, tabId, line, until);
+      if (done !== undefined) return done;
+    } finally {
+      turn?.release();
     }
     await pause(LIST_ASK_MS);
   }
 }
 
+/** One look of typeListLine's, and its line when the gate lets it: what it returns, or undefined to look again. */
+function lookAndType(home, tabId, line, until) {
+  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, 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}` };
+  }
+  return undefined;
+}
+
 /**
  * The line that starts this session: resuming `resume`, or, with none, a fresh
  * start carrying its duty. Returns `{ resume, prompt, promptFile, command, address }`.