@assuredloop/orca-bot-kit 0.22.0 → 0.23.0

package/README.md

@@ -10,7 +10,7 @@ an `obk` command and a set of skills. You are meant to manage the fleet by
 talking to Bot Father, the first bot, whose skills call the CLI for you — not by
 editing files.
 
-The design is in [`docs/prd.md`](docs/prd.md); the decisions with lasting
+The design is in [`docs/prd/prd.md`](docs/prd/prd.md); the decisions with lasting
 consequences are in [`docs/adr/`](docs/adr/); what we know about Orca and the
 two harnesses is in [`docs/tech-notes.md`](docs/tech-notes.md).
 
@@ -364,6 +364,22 @@ conversation it was having, rather than starting a new one. Clear a session —
 keeps the old one, and gives the session its start prompt again, because that
 prompt is what tells one session's duty from another's.
 
+Ask the kit to clear or compact a session, rather than typing into its tab:
+
+```sh
+obk session clear   --bots /path/to/my-bots --bot api-bot --session daily
+obk session compact --bots /path/to/my-bots --bot api-bot --session daily
+```
+
+Each waits up to 30 s for the session to be idle, and types nothing into one
+that is busy or has a question on its screen. It types the harness's own
+command, checks the screen before it presses return, and then confirms the
+result: for a clear, the new conversation in the book; for a compact, the
+compaction in the harness's own record, within 5 minutes, or it says it is not
+confirmed yet. A harness that does not offer `/compact` is told so, and nothing
+is entered. A cleared session reads its `AGENTS.md` again, so a clear also
+brings it onto changed rules.
+
 A session paused before its first turn can have an id in the book and no
 conversation behind it: the harness has nothing on record for that id. There is
 nothing to resume, so it starts again with its duty, and the book moves the id
@@ -649,7 +665,7 @@ editor's runner, skips and says how to run it.
 JavaScript this branch changed against `main` — committed, still in the working
 tree, or not tracked yet — and reports the mutants the tests do not kill. It is
 an audit, not a step of every pull request
-([PRD 7.3](docs/prd.md#73-decided-rules-inside-the-skills)): the everyday
+([PRD 7.3](docs/prd/prd.md#prd-21-73-decided-rules-inside-the-skills)): the everyday
 check is the implementer's own hand check, and the tool runs over the whole
 suite at a milestone or when the owner asks, or once, narrowed to the changed
 logic, for a change at the core of the kit. A surviving mutant is a change to

package/package.json

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

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

@@ -368,8 +368,9 @@ already up even when a skill change would, and a session's model, effort or
 approval only changes when it is started again (`obk restart`, on the user's
 word, and then read its tabs as above). Say which you changed, and what that
 means for the sessions running now. `obk health` names each running session
-still on the older rules or on other settings, and what brings it up to date: on
-Claude Code a `/clear` reads the rules again, and a start does on both harnesses.
+still on the older rules or on other settings, and what brings it up to date: a
+clear reads the rules again (`obk session clear`), and so does a start, on both
+harnesses.
 Where everything needs restarting, remind
 them to do it from Bot Father's ops tab.
 

package/src/clear.js

@@ -0,0 +1,455 @@
+// `obk session clear` and `obk session compact` (#391): the kit, not the
+// harness, is asked to clear or compact a session, and does it safely.
+//
+// A clear is special because a cleared session has to be told its duty again.
+// That is the kit's hook's work already (src/record.js): it hears the new
+// conversation and answers with the start prompt. So this only types the
+// harness's own command, and only when that cannot cut off a turn or answer a
+// question: it waits for the session to be idle, types the command without a
+// return, reads the screen, and presses return only when the screen shows the
+// command and nothing else. Afterwards it confirms what happened from the
+// records, not from the screen: the book's new conversation for a clear, the
+// harness's own record of a compaction for a compact.
+
+import { realpathSync, statSync } from 'node:fs';
+import { setTimeout as pause } from 'node:timers/promises';
+
+import { readBook } 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 { 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). */
+const COMMANDS = {
+  clear: { claude: '/clear', codex: '/new' },
+  compact: { claude: '/compact', codex: '/compact' },
+};
+
+/** The pointer each harness starts its input line with (tech notes, section 1). */
+const POINTER = { claude: '❯', codex: '›' };
+
+/**
+ * The line typed into Codex after its `/new`, in the architect's words (#391).
+ * Codex reports a new conversation only at its first turn (tech notes, section
+ * 3), so without a turn the hook never hears of it and never re-briefs it.
+ */
+const RECORD_LINE = 'obk: this conversation was started by obk session clear, and this line is only so the kit can record it. Reply "ok"; nothing else is asked.';
+
+/** What Codex asks after `/new`, and the one answer the kit gives it: the bot home it runs in. */
+const WHERE_TO_RUN = 'Where should the new conversation run?';
+const CURRENT_CHECKOUT = /^ *› +1\. Current checkout\b/;
+
+/** Codex's empty input line: its pointer alone, or with its placeholder. */
+const CODEX_EMPTY = ['›', '› Ask Codex to do anything'];
+
+/**
+ * The Codex whose input line Orca's screen shows bare while its slash menu is
+ * open, whatever was typed (#391, live runs 2 to 4). On it alone, the menu's
+ * selected row stands for what Return will run: with the menu open, Return
+ * runs the selected command, and the menu is narrowed to what was typed
+ * (codex-rs/tui/src/bottom_pane/chat_composer.rs, rust-v0.160.0). The
+ * architect's ruling on #391, after live run 4.
+ */
+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 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). */
+const CLEAR_MS = 30_000;
+const COMPACT_MS = 300_000;
+/** How long each screen read is given before it counts as a screen that cannot be read. */
+const READ_MS = 5000;
+/** The pause between looks, and between looks at a record that may be large. */
+const ASK_MS = 500;
+const RECORD_ASK_MS = 2000;
+/**
+ * The gap between two characters of a command. Codex takes characters that come
+ * less than 8 ms apart as a paste, and flushes a paste after 60 ms without one
+ * (PASTE_BURST_CHAR_INTERVAL and PASTE_BURST_ACTIVE_IDLE_TIMEOUT in
+ * codex-rs/tui/src/bottom_pane/paste_burst.rs, rust-v0.160.0). A command it
+ * takes for a paste was seen to leave its input line bare (#391, live run 2),
+ * so the kit types well past both.
+ */
+const CHAR_GAP_MS = 100;
+
+/**
+ * A row that says the harness is at work on a turn, as seen live (#391): Codex
+ * 0.160.0's "• Working (8s • esc to interrupt)", and Claude Code 2.1.288's
+ * spinner row, "✳ Nucleating… (1m 8s · ↓ 131 tokens)": a glyph, a word that
+ * ends in "…", then the time. A finished turn's row, "✻ Churned for 13s · done
+ * 12:27 PM", has no "…".
+ */
+const AT_WORK = [/esc to interrupt/i, /^\s*\S\s+\S+…\s+\(\d/];
+
+/**
+ * Clear the session: `/clear` on Claude Code, `/new` on Codex. Returns
+ * `{ bot, session, harness, was, now }`, the conversation the book held before
+ * (or null) and the one it holds now.
+ */
+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');
+
+  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.`);
+    }
+  }
+
+  const until = Date.now() + CLEAR_MS;
+  for (;;) {
+    const now = readBook(it.home).sessions[session]?.session;
+    if (typeof now === 'string' && now !== was) return { bot, session, harness: it.harness, was, now };
+    if (Date.now() >= until) {
+      throw new Error(`${it.name}: ${command} went in, but after ${CLEAR_MS / 1000} s the book has no new conversation for it: it still holds ${was ?? 'none'}. Look at its tab.`);
+    }
+    await pause(ASK_MS);
+  }
+}
+
+/**
+ * Compact the session's conversation with the harness's `/compact`. Returns
+ * `{ bot, session, harness, conversation, confirmed }`: confirmed once the
+ * harness's own record of the conversation shows a compaction made after the
+ * command began, and not yet when COMPACT_MS passed without one.
+ */
+export async function compactSession(bots, { bot, session }) {
+  const it = sessionToType(bots, bot, session);
+  // What the record holds when /compact is typed is not this compact's: one
+  // 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', () => {
+    record = recordAt(it.harness, it.home, readBook(it.home).sessions[session]?.session ?? null);
+  });
+
+  const until = typedAt + COMPACT_MS;
+  for (;;) {
+    const conversation = readBook(it.home).sessions[session]?.session ?? null;
+    // A conversation the book did not hold when it was typed is read whole.
+    if (conversation !== record.id) record = { id: conversation, from: 0 };
+    record.file ??= recordFile(it.harness, it.home, conversation);
+    if (record.file !== undefined && compactedSince(it.harness, record, typedAt)) {
+      return { bot, session, harness: it.harness, conversation, confirmed: true };
+    }
+    if (Date.now() >= until) return { bot, session, harness: it.harness, conversation, confirmed: false };
+    await pause(RECORD_ASK_MS);
+  }
+}
+
+/**
+ * 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) {
+  botsNamed(bots, bot);
+  const home = realpathSync(botDir(bots, bot));
+  const known = readBot(home, bot);
+  const [settings] = sessionsOf(known, session);
+  const name = `${bot} ${session}`;
+  const unpause = `${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${bot}`;
+  if (known.paused === true) throw new Error(`${bot} is paused, so ${name} is not running and nothing was typed. Bring it back with ${unpause}.`);
+  if (settings.paused === true) throw new Error(`${name} is paused, so it is not running and nothing was typed. Bring it back with ${unpause} --session ${session}.`);
+
+  const tabId = readBook(home).sessions[session]?.tab;
+  // Orca refuses to list the tabs of a folder it has no project for (tech
+  // notes, section 1), so a bot never brought up is asked nothing.
+  const open = typeof tabId === 'string' && findProject(home) !== undefined && tabs(home).some((tab) => tab.tabId === tabId);
+  if (!open) {
+    throw new Error(`${name} has no tab open in Orca, so it is not running and nothing was typed. Bring it up with ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${bot} --session ${session}.`);
+  }
+  return { name, home, session, harness: harnessOf(settings, known.harness), tabId, restart: `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot} --session ${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.
+ */
+async function enter(it, verb, before = () => {}) {
+  const command = COMMANDS[verb][it.harness];
+  const { handle, rows } = await idleTab(it);
+  // 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 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)}`);
+    }
+  }
+  const version = it.harness === 'codex' ? codexVersion(readBook(it.home).sessions[it.session]?.session) : undefined;
+
+  before();
+  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
+  // (the architect's ruling on #391, after live run 2).
+  // 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).
+  let typed = 0;
+  const lookAgain = async () => {
+    await pause(CHAR_GAP_MS);
+    const look = lookAt(it, { idle: false });
+    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.`);
+  };
+  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)}`);
+  }
+  // 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 };
+}
+
+/**
+ * The handle of the session's tab once the session is idle, with nothing on
+ * its screen to answer, within IDLE_WAIT_MS. Busy is Orca's `tui-idle` not
+ * answering ok, or a screen that says it is at work: Orca can call a busy
+ * Codex idle. Throws when the tab holds no harness, and when the wait ran out.
+ */
+async function idleTab(it) {
+  const until = Date.now() + IDLE_WAIT_MS;
+  for (;;) {
+    const look = lookAt(it);
+    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).
+    if (why === undefined && Date.now() >= until) why = 'the look that found it idle came only after the wait was up';
+    if (why === undefined) return look;
+    if (Date.now() >= until) throw new Error(`${it.name}: nothing was typed, because after ${IDLE_WAIT_MS / 1000} s ${why}. Run this again once it is idle.`);
+    await pause(ASK_MS);
+  }
+}
+
+/**
+ * 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.
+ * Throws when the tab holds no harness.
+ */
+function lookAt(it, { idle = true } = {}) {
+  const found = tabToTypeInto(it.home, it.tabId, LOOK_MS);
+  if (found.blocked !== undefined) {
+    return {
+      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}`,
+    };
+  }
+  if (found.unsure !== undefined) return { why: found.unsure };
+  if (found.handle === undefined) {
+    throw new Error(`${it.name} is not running: its tab is open with no harness in front of it, so its harness quit or crashed, and nothing was typed. ${it.restart} brings it back.`);
+  }
+  if (found.agent !== it.harness) return { why: `Orca names ${found.agent} in it, and the session runs on ${it.harness}` };
+  // The gate has read the screen already: it saw no question on it.
+  const signal = signalIn(found.rows);
+  if (signal !== undefined) return { why: signal };
+  if (idle && !found.idle) return { why: 'it is busy with a turn: Orca\'s tui-idle did not answer ok' };
+  return { handle: found.handle, rows: found.rows };
+}
+
+/**
+ * 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
+ * takes a moment to draw what was typed.
+ */
+async function typedWrong(handle, harness, command, version) {
+  const until = Date.now() + SCREEN_MS;
+  for (;;) {
+    const seen = screenRows(handle, READ_MS);
+    // The screen that lets the return in has to pass the look too: a turn or
+    // 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);
+    if (wrong === undefined || Date.now() >= until) return wrong && { ...wrong, rows: seen.rows };
+    await pause(ASK_MS);
+  }
+}
+
+/** 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 (questionIn(rows)) return 'a question of its harness\'s own is on its screen';
+  return undefined;
+}
+
+function menuWrong(rows, harness, command, version) {
+  const at = rows.findLastIndex((row) => /^ *[›❯]/.test(row));
+  if (at < 0) return { why: 'its screen shows no input line' };
+  // Claude Code 2.1.288 puts a non-breaking space after its pointer (live run 4).
+  const line = rows[at].replaceAll('\u00a0', ' ').trim();
+  if (harness === 'codex') return codexMenuWrong(rows, at, line, command, version);
+  if (line !== `${POINTER[harness]} ${command}`) return { why: `its input line reads "${line}"` };
+  return claudeMenuWrong(rows, at, command);
+}
+
+/**
+ * Claude Code 2.1.288 draws its slash menu above its input box's top rule, a
+ * row of ─: a row per command, starting with it, its description wrapped onto
+ * rows set far in (live run 4). No pointer marks a selection, so the first
+ * command row there has to be the command.
+ */
+function claudeMenuWrong(rows, at, command) {
+  const rule = rows.slice(0, at).findLastIndex((row) => /^\s*─{3}/.test(row));
+  const menu = [];
+  for (let up = rule - 1; up >= 0 && (/^ {1,4}\/\S/.test(rows[up]) || /^ {20,}\S/.test(rows[up])); up -= 1) menu.unshift(rows[up]);
+  const first = menu.find((row) => /^ {1,4}\//.test(row));
+  if (rule < 0 || first === undefined) return { why: 'no menu of commands came up above its input box', menu: true };
+  if (first.trim().split(/\s+/)[0] !== command) return { why: `the first row of its menu is "${first.trim()}"`, menu: true };
+  return undefined;
+}
+
+/**
+ * Codex draws its slash menu above the input line: a row per command, the
+ * selected one starting with its pointer, then a blank row, then the input
+ * line (its own snapshot tests, chat_composer slash_popup_*.snap,
+ * rust-v0.160.0; live run 4). The menu has to hold one command row, the
+ * selected one, naming the command. The input line reads the command, or, on
+ * the Codex whose line Orca shows bare, its pointer alone.
+ */
+function codexMenuWrong(rows, at, line, command, version) {
+  const bare = line === '›' && version === CODEX_BARE_LINE;
+  if (line !== `› ${command}` && !bare) {
+    const why = line === '›' ? `its input line reads "›" and this Codex is ${version ?? 'of a version its record does not give'}, not ${CODEX_BARE_LINE}` : `its input line reads "${line}"`;
+    return { why };
+  }
+  const menu = [];
+  for (let up = at - 1; up >= 0 && (rows[up].trim() === '' || /^ *(?:› +)?\/\S/.test(rows[up])); up -= 1) menu.unshift(rows[up]);
+  const commands = menu.filter((row) => row.trim() !== '');
+  if (commands.length === 0) return { why: 'no menu of commands came up above its input line', menu: true };
+  if (commands.length > 1) return { why: `its menu offers more than one command: ${commands.map((row) => `"${row.trim()}"`).join(', ')}`, menu: true };
+  if (!/^ *› +/.test(commands[0])) return { why: `its menu's one row "${commands[0].trim()}" is not selected`, menu: true };
+  const selected = commands[0].replace(/^ *› +/, '');
+  if (selected.split(/\s+/)[0] !== command) return { why: `the selected row of its menu is "${selected.trim()}"`, menu: true };
+  return undefined;
+}
+
+/** The Codex version that wrote the rollout of `conversation`, from its session_meta line; undefined when that cannot be read. */
+function codexVersion(conversation) {
+  const file = typeof conversation === 'string' ? codexRollout(conversation) : undefined;
+  if (file === undefined) return undefined;
+  try {
+    const version = JSON.parse(firstLine(file) ?? 'null')?.payload?.cli_version;
+    return typeof version === 'string' ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Answer Codex's "Where should the new conversation run?" with "1. Current
+ * checkout", the bot home, when it comes up after `/new`. With its selection
+ * anywhere else it is backed out of with Esc: the kit never makes a worktree
+ * (PRD 6.2).
+ */
+async function answerWhereToRun(it, handle, command) {
+  const until = Date.now() + SCREEN_MS;
+  for (;;) {
+    const rows = screenRows(handle, READ_MS).rows ?? [];
+    if (rows.some((row) => row.includes(WHERE_TO_RUN))) {
+      const pointer = rows.findLast((row) => /^ *›/.test(row));
+      if (pointer === undefined || !CURRENT_CHECKOUT.test(pointer)) {
+        send(handle, '\x1b');
+        throw new Error(`${it.name}: after ${command}, Codex asked "${WHERE_TO_RUN}" with its selection on "${pointer?.trim() ?? 'nothing'}" rather than "1. Current checkout", so it was backed out of with Esc and nothing else was typed. Look at its tab.`);
+      }
+      send(handle, '\r');
+      return;
+    }
+    if (Date.now() >= until) return;
+    await pause(ASK_MS);
+  }
+}
+
+/** Where the harness keeps the record of `conversation`, or undefined when it has none yet. */
+function recordFile(harness, home, conversation) {
+  if (conversation === null) return undefined;
+  return harness === 'claude' ? claudeTranscript(home, conversation) : codexRollout(conversation);
+}
+
+/** The record of `conversation` as it is now: `{ id, file, from }`, `from` the byte it ends at. */
+function recordAt(harness, home, conversation) {
+  const file = recordFile(harness, home, conversation);
+  let from = 0;
+  try {
+    from = file === undefined ? 0 : statSync(file).size;
+  } catch {
+    // Not written yet: everything in it will be new.
+  }
+  return { id: conversation, file, from };
+}
+
+/**
+ * Whether the record holds, from its byte `from` on, a compaction made at
+ * `since` or later. Read a line at a time: a record can be larger than one
+ * string holds (#396).
+ */
+function compactedSince(harness, record, since) {
+  let found = false;
+  try {
+    eachLine(record.file, (line) => {
+      // Only a line that names a compaction is worth parsing.
+      if (line === undefined || !line.includes('compact')) return false;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        return false;
+      }
+      // Claude Code's marker, and Codex's (tech notes, sections 2 and 3).
+      const compaction = harness === 'claude'
+        ? entry?.type === 'system' && entry.subtype === 'compact_boundary'
+        : entry?.type === 'compacted';
+      found = compaction && Date.parse(entry.timestamp) >= since;
+      return found;
+    }, { from: record.from });
+  } catch {
+    return false;
+  }
+  return found;
+}
+
+/**
+ * The last rows of the screen with words in them, as a sentence for a refusal,
+ * so whoever reads it sees what the harness drew there.
+ */
+function shownEnd(rows) {
+  const shown = (rows ?? []).filter((row) => row.trim() !== '').slice(-SHOWN_ROWS);
+  return shown.length === 0 ? '' : ` Its screen ended: ${shown.map((row) => row.trimEnd()).join(' ⏎ ')}`;
+}
+
+/** How many rows of the screen a refusal shows. */
+const SHOWN_ROWS = 12;
+
+/** 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 harnessName = (harness) => (harness === 'claude' ? 'Claude Code' : 'Codex');

package/src/cli.js

@@ -23,6 +23,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 +205,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
@@ -296,6 +309,8 @@ 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'],
@@ -1136,6 +1151,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/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/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/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/up.js

@@ -408,12 +408,13 @@ const LIST_LOOK_MS = 2000;
 const LIST_ASK_MS = 500;
 
 /**
- * Type LIST_LINE into the tab `tabId` once the gate every typed line goes
- * through lets it: `{ typed: true }`, or `{ typed: false, why }` with the
- * gate's last reason once LIST_WAIT_MS is up. Nothing goes into a question, a
- * form or a menu (#329, #416), nor into a tab the kit cannot tell about.
+ * 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.
  */
-async function typeListLine(home, tabId) {
+export async function typeListLine(home, tabId, line = LIST_LINE) {
   const until = Date.now() + LIST_WAIT_MS;
   for (;;) {
     let found;
@@ -430,7 +431,7 @@ async function typeListLine(home, tabId) {
     }
     if (found.handle !== undefined) {
       try {
-        typeIntoTab(found.handle, LIST_LINE);
+        typeIntoTab(found.handle, line);
         return { typed: true };
       } catch (error) {
         return { typed: false, why: `Orca refused the line: ${error.message}` };