@assuredloop/orca-bot-kit 0.22.0 → 0.24.1

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';
@@ -23,6 +24,7 @@ import { allowCommand, allowIn, beyondDefaults, refuseBroad, refuseNoCodexForm,
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
+import { clearSession, compactSession } from './clear.js';
 import { retireBot, retireSession } from './retire.js';
 import { sentWarning } from './sent.js';
 import { readRoster } from './roster.js';
@@ -204,6 +206,18 @@ Usage:
                             one command that closes a tab, it closes only the
                             tabs your book names, and it will not close one
                             whose conversation the book cannot name.
+  obk session clear --bots <path> --bot <bot> --session <name>
+                            Start the session on a new conversation: /clear on
+                            Claude Code, /new on Codex. It waits up to 30 s for
+                            the session to be idle, types nothing into a busy
+                            one or one with a question on its screen, and
+                            answers once the book holds the new conversation.
+                            The kit's hook gives it its start prompt again.
+  obk session compact --bots <path> --bot <bot> --session <name>
+                            Compact the session's conversation with /compact,
+                            as safely as session clear, and answer once the
+                            harness's record shows it, or after 5 minutes that
+                            it is not confirmed yet.
   obk health --bots <path> [--bot <bot>]
                             Say what is wrong with your setup: configuration
                             that will not work, a skill that is not where its
@@ -261,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
@@ -296,12 +315,15 @@ const COMMANDS = {
   'source add': ['bots', 'name', 'repo', 'ref'],
   'session add': ['bots', 'bot', 'name'],
   'session change': ['bots', 'bot', 'session'],
+  'session clear': ['bots', 'bot', 'session'],
+  'session compact': ['bots', 'bot', 'session'],
   'message to': ['bots', 'to'],
   'message send': ['bots', 'to', 'subject'],
   'message check': ['bots'],
   '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'],
@@ -434,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));
@@ -502,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
@@ -541,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.
  *
@@ -1136,6 +1175,28 @@ const commands = {
       ],
     };
   },
+
+  async 'session clear'(bots, values) {
+    refuseWhenOrcaIsDown();
+    const cleared = await clearSession(bots, { bot: values.bot, session: values.session });
+    const after = cleared.was === null ? '' : `, in place of ${cleared.was}`;
+    return {
+      answer: { bots, cleared },
+      lines: [`cleared    ${cleared.bot} ${cleared.session}: the book holds its new conversation ${cleared.now}${after}.`],
+    };
+  },
+
+  async 'session compact'(bots, values) {
+    refuseWhenOrcaIsDown();
+    const compacted = await compactSession(bots, { bot: values.bot, session: values.session });
+    const what = `${compacted.bot} ${compacted.session}`;
+    return {
+      answer: { bots, compacted },
+      lines: [compacted.confirmed
+        ? `compacted  ${what}: the harness's record of its conversation ${compacted.conversation} shows the compaction.`
+        : `asked      ${what} to compact: /compact went in, and after 5 minutes the harness's record shows no compaction, so it is not confirmed yet. Look at its tab.`],
+    };
+  },
 };
 
 /**

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

@@ -322,13 +322,10 @@ function runningOn(bots, home, bot, book, handles, sessions) {
 
     if (rules.state === 'older') {
       const agents = path.join(home, 'AGENTS.md');
-      // A clear on Claude Code reads the instructions again, as a start does
-      // (tech notes, section 2); whether a new conversation on Codex does is
-      // not established, so a start is all that is offered there.
-      const how = harness === 'claude'
-        ? `A Claude Code session reads it again at a /clear in its tab, or when it starts: ${restart}`
-        : `A Codex session reads it when it starts: ${restart}`;
-      found.push(finding('session', agents, `${bot.name}'s session ${session.name} is running on older rules: ${agents} has changed since the kit noted which version this session read. ${how}`, bot.name));
+      // A clear reads the instructions again, as a start does, on both
+      // harnesses (tech notes, sections 2 and 3; #391).
+      const clear = `${shellWord(ownCli())} session clear --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
+      found.push(finding('session', agents, `${bot.name}'s session ${session.name} is running on older rules: ${agents} has changed since the kit noted which version this session read. A session reads it again when it is cleared: ${clear}, or when it starts: ${restart}`, bot.name));
     }
   }
   return found;

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

@@ -25,18 +25,21 @@ const LONGEST = 64 * 1024 * 1024;
 /**
  * Each line of `file`, in order, to `onLine`: its text, or `undefined` for a
  * line too long to hold. A line `onLine` answers `true` to is the last one
- * read. Throws what the file system throws when the file cannot be opened or
- * read.
+ * read. With `from`, reading starts at that byte, for a caller that wants only
+ * what was written after it (#391). Throws what the file system throws when
+ * the file cannot be opened or read.
  */
-export function eachLine(file, onLine) {
+export function eachLine(file, onLine, { from = 0 } = {}) {
   const fd = openSync(file, 'r');
   try {
     const decoder = new StringDecoder('utf8');
     const buffer = Buffer.allocUnsafe(CHUNK);
     let pending = '';
     let tooLong = false;
+    let position = from;
     for (;;) {
-      const read = readSync(fd, buffer, 0, CHUNK, null);
+      const read = readSync(fd, buffer, 0, CHUNK, position);
+      position += read;
       const text = read === 0 ? decoder.end() : decoder.write(buffer.subarray(0, read));
       let start = 0;
       for (let at = text.indexOf('\n'); at !== -1; at = text.indexOf('\n', start)) {

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

@@ -377,14 +377,14 @@ export const QUESTION_ON_SCREEN = 'question-on-screen';
 
 /**
  * What the tab `handle` renders: `{ question }`, true when it shows a question
- * of its harness's own, or `{ screenUnreadable: <why> }`. Orca refusing is an
+ * of its harness's own, with the `rows` it read, or `{ screenUnreadable: <why> }`. Orca refusing is an
  * answer that cannot be read, not an error, and so is anything that is not the
  * rendered screen: accumulated output comes back in fragments (tech notes,
  * section 1).
  */
 function screenOf(handle, readMs) {
   const read = screenRows(handle, readMs);
-  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows) };
+  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows), rows: read.rows };
 }
 
 /**
@@ -445,7 +445,9 @@ export function questionIn(rows) {
  * Whether the kit may type a line into `tabId`, the tab the book holds for a
  * session in the Orca project at `home`, and the handle to type into when it
  * may: `{ handle, agent }`, with the agent Orca names there. Otherwise nothing
- * is typed, and the answer says why:
+ * is typed, and the answer says why. `idle` says whether Orca's `tui-idle` wait
+ * answered ok, and `rows` is the screen the gate read, for a caller that must
+ * not type into a busy harness (#391):
  * `{}` for a tab with no harness in it (none in the book, none Orca lists, or
  * the shell in front), `{ blocked }` for one with something on screen waiting
  * to be answered, and `{ unsure }`, a sentence, for one the kit cannot tell
@@ -508,7 +510,7 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   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` };
   }
-  return { handle: live.handle, agent: seen.agent };
+  return { handle: live.handle, agent: seen.agent, idle: seen.answered, rows: seen.rows };
 }
 
 /**

package/src/record.js

@@ -80,11 +80,10 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
   // this bot's folder, which every session of the bot shares — so it can say
   // that a conversation nobody claims exists, and never whose it is.
   const unclaimed = unclaimedFor(readBook(home), home, bot, tabId, id);
-  // A clear on Claude Code reads the bot's instructions again, as a start does
-  // (tech notes, section 2), so the book notes which ones it read. Codex has no
-  // word for its clear, and whether its new conversation reads them again is
-  // not established, so nothing is noted for it.
-  const rules = said.source === CLEARED ? rulesStamp(home) : undefined;
+  // A clear reads the bot's instructions again, as a start does, so the book
+  // notes which ones it read: Claude Code's `/clear` (tech notes, section 2),
+  // and Codex's `/new`, seen here as a new id (#391).
+  const stamp = rulesStamp(home);
 
   let cleared = false;
   let told;
@@ -106,6 +105,7 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
     const uncertain = was.session === undefined && unclaimed.length > 0;
     told = session;
 
+    const rules = cleared ? stamp : undefined;
     const now = rememberSession(was, id, said.source);
     book.sessions[session] = withUnclaimed(rules === undefined ? now : { ...now, rules }, unclaimed);
     forgetClaimed(book);

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();
     }
   });
 }