@assuredloop/orca-bot-kit 0.17.0 → 0.19.0

package/src/groom.js

@@ -25,12 +25,20 @@
 // asked for, or none. Run in any order, the last one typed is what holds
 // (review of PR #322).
 //
+// A job can make its runs on Codex instead (#238, PRD 6.8): the session stays the
+// Claude Code one, the clock and the reader, and at each fire it makes the run
+// as a temporary Codex session of its own (`obk temp make`), with the job's
+// model and effort on the run's launch line. The run does the grooming, sends
+// its report back by the kit's mail and is retired by the session, which first
+// retires any run an earlier fire left. What the runs are on is in the job's
+// prompt and nowhere else, so the kit reads it back from there.
+//
 // Claude Code ends a recurring job a week after it was made, so the job's own
 // prompt ends by renewing it. A renewal that fails either way shows here: no
 // job means the fleet has quietly stopped being groomed, two mean it is groomed
 // twice, and both are said plainly.
 
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { botDir, readBot, requireBotsFolder } from './bot.js';
@@ -38,7 +46,7 @@ import { readBook } from './book.js';
 import { claudeTranscript } from './conversations.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 import { tabs, tabToTypeInto, typeIntoTab } from './orca.js';
-import { BOT_FATHER } from './up.js';
+import { BOT_FATHER, promptPath } from './up.js';
 import { lines } from './usage.js';
 
 /** Bot Father's session the grooming runs in. */
@@ -50,6 +58,12 @@ const AT = /^([01]\d|2[0-3]):([0-5]\d)$/;
 /** A daily cron as the kit writes one: minute, hour, every day. */
 const DAILY = /^(\d{1,2}) (\d{1,2}) \* \* \*$/;
 
+/** The harnesses a job can make its runs on, besides running them in the session itself (#238). */
+const RUN_ON = ['codex'];
+
+/** The name each run is given, filled in by the session at the fire it makes it. */
+const RUN_NAME = 'groom-<YYYYMMDD-HHMM>';
+
 /** How long Claude Code keeps a recurring job after it was made (tech notes, section 2). */
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -79,8 +93,9 @@ export const markerOf = (bots) => `obk grooming for ${bots}`;
  * (or null), the grooming jobs alive in its conversation as the command found
  * them, before anything it typed was done, and what it typed (or null).
  */
-export function grooming(bots, { at, ask } = {}) {
+export function grooming(bots, { at, ask, run } = {}) {
   requireBotsFolder(bots);
+  refuseRun(run, ask);
 
   // The folder as the file system knows it: Claude Code files a transcript
   // under the real path, and Orca knows a tab's project by it.
@@ -108,7 +123,7 @@ export function grooming(bots, { at, ask } = {}) {
     ? groomingJobs(ofThisProcess(home, entry), markerOf(bots), Date.now())
     : [];
 
-  const line = ask === undefined ? undefined : lineFor(ask, { bots, session, jobs, at });
+  const line = ask === undefined ? undefined : lineFor(ask, { bots, session, jobs, at, run });
   if (line !== undefined) typeInto(bots, home, session, tab, line);
 
   // A move is turning it on at another time, and is typed as one.
@@ -120,7 +135,7 @@ export function grooming(bots, { at, ask } = {}) {
  * nothing to ask. Everything that makes the ask impossible refuses here, before
  * Orca is asked for anything.
  */
-function lineFor(ask, { bots, session, jobs, at }) {
+function lineFor(ask, { bots, session, jobs, at, run }) {
   // Nothing to turn off is an answer, unless a session is there to be told: an
   // `--on` typed a moment ago may still be waiting in its tab.
   if (ask === 'off' && jobs.length === 0 && !(session?.harness === 'claude' && session.up)) return undefined;
@@ -147,7 +162,28 @@ function lineFor(ask, { bots, session, jobs, at }) {
       ? `grooming is off, so there is no time to keep. Say when: ${groomCommand(bots)} --on --at <HH:MM>.`
       : `the grooming jobs there run at different times (${times.join(', ')}). Say which one to keep: ${groomCommand(bots)} --on --at <HH:MM>.`);
   }
-  return onLine(bots, cronOf(when), jobs);
+  // A move keeps what the runs are on, when every job there says the same.
+  const runs = [...new Set(jobs.map((job) => JSON.stringify(job.run ?? null)))];
+  const keep = ask === 'move' && runs.length === 1 ? JSON.parse(runs[0]) ?? undefined : undefined;
+  return onLine(bots, cronOf(when), jobs, run ?? keep);
+}
+
+/**
+ * Refuse what the run was given before anything else is looked at: its flags
+ * go with --on, --run-on takes codex, and a model, an effort or an extra
+ * argument is the run's, so it goes with --run-on codex.
+ */
+function refuseRun(run, ask) {
+  if (run === undefined) return;
+  if (run.harness === undefined) {
+    throw new Error('--model, --effort and --extra-arg are what each grooming run is launched with when it runs on Codex, and go with --run-on codex. The grooming session\'s own runs use its own settings. Nothing was typed.');
+  }
+  if (!RUN_ON.includes(run.harness)) {
+    throw new Error(`--run-on takes codex: grooming runs either in its Claude Code session, as it does without --run-on, or as a temporary Codex session made at each fire. Got: ${run.harness === '' ? 'nothing' : run.harness}. Nothing was typed.`);
+  }
+  if (ask !== 'on') {
+    throw new Error('--run-on says what the grooming runs are on, and goes with --on. Nothing was typed.');
+  }
 }
 
 /**
@@ -230,7 +266,8 @@ export function groomingJobs(entries, marker, now) {
       const { cron, prompt, recurring } = call.input ?? {};
       const made = Date.parse(entry.timestamp ?? '');
       if (recurring === false || typeof prompt !== 'string' || !prompt.startsWith(marker) || Number.isNaN(made)) continue;
-      alive.set(result.id, { id: result.id, at: timeOf(cron), cron, made, expires: made + WEEK_MS });
+      const run = runIn(prompt);
+      alive.set(result.id, { id: result.id, at: timeOf(cron), cron, made, expires: made + WEEK_MS, ...(run === undefined ? {} : { run }) });
     }
   }
   return [...alive.values()]
@@ -239,6 +276,32 @@ export function groomingJobs(entries, marker, now) {
     .map((job) => ({ ...job, made: new Date(job.made).toISOString(), expires: new Date(job.expires).toISOString() }));
 }
 
+/**
+ * What a job's runs are on, read out of its prompt: the harness, model and
+ * effort its \`temp make\` is given, each left out when it was not; undefined
+ * for a job whose runs are the session's own.
+ */
+function runIn(prompt) {
+  const make = / temp make ([^`]*)`/.exec(prompt);
+  if (make === null) return undefined;
+  const value = (flag) => {
+    const found = new RegExp(`(?:^| )--${flag}(?:=| )('[^']*'|\\S+)`).exec(make[1]);
+    return found === null ? undefined : found[1].replace(/^'(.*)'$/, '$1');
+  };
+  const run = { harness: value('harness') };
+  if (run.harness === undefined) return undefined;
+  for (const field of ['model', 'effort']) {
+    const got = value(field);
+    if (got !== undefined) run[field] = got;
+  }
+  // Each extra argument as the job wrote it, one shell word, read back to what
+  // it was given as, so a move keeps them all (review of PR #439).
+  const extra = [...make[1].matchAll(/(?:^| )--extra-arg=('(?:[^']|'\\'')*'|[A-Za-z0-9,._+:@%/=-]+)/g)]
+    .map((found) => (found[1].startsWith('\'') ? found[1].slice(1, -1).replaceAll(`'\\''`, '\'') : found[1]));
+  if (extra.length > 0) run.extra_args = extra;
+  return run;
+}
+
 /** `HH:MM` as the daily cron Claude Code takes: `04:00` is `0 4 * * *`. */
 const cronOf = (at) => {
   const [, hour, minute] = AT.exec(at);
@@ -268,11 +331,81 @@ const run = (bots) =>
  * fired with, so the job carries itself on; the one that fired is then the
  * older of the two.
  */
-const jobPrompt = (bots, cron) =>
-  `${run(bots)} When the report is sent, renew this schedule, which Claude Code ends a week after it was made: `
+const jobPrompt = (bots, cron, onRun) => (onRun === undefined
+  ? `${run(bots)} When the report is sent, ${renewal(cron)}`
+  // A run on Codex reports in a later turn, and may never: the job renews at
+  // the fire, once the run is made, so a run that never reports does not end
+  // the schedule with it (review of PR #439).
+  : `${runElsewhere(bots, onRun)} Then ${renewal(cron)} Then end your turn. ${readReport(bots)}`);
+
+/** The part of a job that renews it, which Claude Code would otherwise end a week after it was made. */
+const renewal = (cron) =>
+  'renew this schedule, which Claude Code ends a week after it was made: '
   + `call CronCreate with cron "${cron}", recurring true, and this whole prompt, word for word, as its prompt; `
   + `then call CronList and CronDelete every other job there whose prompt starts with "${PREFIX}".`;
 
+/**
+ * The part of a job whose runs are on Codex (#238): clear what an earlier run
+ * left, make this fire's run, and read its report when it comes. Each command
+ * is the kit by its own path, as the run above names it, because a Claude Code
+ * allow rule matches a command as written (#344). The run's task goes in a file
+ * the kit writes now, beside the bots folder, as it leaves every prompt.
+ */
+function runElsewhere(bots, onRun) {
+  const kit = shellWord(ownCli());
+  const folder = shellWord(bots);
+  const retire = `\`${kit} temp retire --bots ${folder} --name ${RUN_NAME}\``;
+  const make = [
+    `${kit} temp make --bots ${folder} --name ${RUN_NAME} --harness ${onRun.harness}`,
+    ...(onRun.model === undefined ? [] : [`--model ${shellWord(onRun.model)}`]),
+    ...(onRun.effort === undefined ? [] : [`--effort ${shellWord(onRun.effort)}`]),
+    ...(onRun.extra_args ?? []).map((arg) => `--extra-arg=${shellWord(arg)}`),
+    `--prompt-file ${shellWord(writeRunTask(bots))}`,
+  ].join(' ');
+  return `${markerOf(bots)}: the daily grooming for this fleet, run on ${onRun.harness} as a temporary session of yours `
+    + `that does the work and reports back to you. First, if any of your temporary sessions whose names start with groom- `
+    + `is still there (${BOT_FATHER}'s bot.yaml lists them), a run an earlier fire left, retire each with ${retire}, `
+    + `its own name in place of ${RUN_NAME}. Then make this fire's run with \`${make}\`, `
+    + `where ${RUN_NAME} is this fire's date and time. Its tab can stop on Codex's first-run screens: answer its folder trust `
+    + 'yourself, as the make\'s output and your rules say, and the review of its hooks with '
+    + `\`${kit} temp trust-hooks --bots ${folder} --name ${RUN_NAME}\`, its name in place of ${RUN_NAME}.`;
+}
+
+/** The part of a Codex job for the later turn its run's report comes in: read it, send it on, retire the run. */
+function readReport(bots) {
+  const retire = `\`${shellWord(ownCli())} temp retire --bots ${shellWord(bots)} --name ${RUN_NAME}\``;
+  const road = `\`${shellWord(ownCli())} message to --bots ${shellWord(bots)} --to ${BOT_FATHER}/<that session>\``;
+  // Claude Code's own messaging reaches every session on the machine, so a
+  // name that only looks right can be another fleet's session (#450).
+  return `When a line comes saying fleet mail from that run is waiting, read the mail the way the line says: it is the grooming report. `
+    + `Send it on, as it is, to ${BOT_FATHER}'s management session, as a grooming run's report goes: to exactly the address or mailbox `
+    + `${road} answers, and to no other. If your messaging does not list that address, send the report nowhere else, and say so. `
+    + `Then retire the run with ${retire}, its name in place of ${RUN_NAME}. Schedule nothing then: the job renewed itself when it fired.`;
+}
+
+/**
+ * Write the task a Codex run is started with, and answer where: do the daily
+ * grooming with the obk-grooming skill, send the report to the grooming session
+ * by the kit's mail, and stop. It schedules nothing: the schedule is the
+ * grooming session's.
+ */
+function writeRunTask(bots) {
+  const real = realHome(bots);
+  const kit = shellWord(ownCli());
+  const file = path.resolve(promptPath(real, BOT_FATHER, `${GROOMING}-run`));
+  const task = `You are one run of the daily grooming of the fleet in ${real}, made by ${BOT_FATHER}'s ${GROOMING} session. `
+    + 'Run the daily grooming for this fleet, with the obk-grooming skill. Fix this run\'s end now and read what has happened '
+    + `since the last run's end up to it, counting with ${kit} usage --since <last end> --until <this end>, and write this end down for the next run. `
+    + 'Work out what it cost with obk-finops, and keep each bot\'s profile notes. '
+    + `The kit here is ${kit}: run it wherever a skill says obk. The bots folder is ${real}. `
+    + `When the grooming is done, send one short report to ${BOT_FATHER}/${GROOMING} by the kit's mail: `
+    + `ask for the road with ${kit} message to --bots ${shellWord(real)} --to ${BOT_FATHER}/${GROOMING}, then send it with the message send command its answer names. `
+    + 'Then stop: schedule nothing, make no session, and say nothing more.\n';
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, task);
+  return file;
+}
+
 /**
  * The part of a line that clears the grooming jobs the session has when it runs
  * the line, which is not always what the kit saw when it typed it.
@@ -281,11 +414,11 @@ const clearing = (jobs) =>
   `call CronList, and call CronDelete on every job there whose prompt starts with "${PREFIX}"`
   + (jobs.length === 0 ? '' : ` (when this was typed they were ${jobs.map((job) => job.id).join(', ')})`);
 
-const onLine = (bots, cron, jobs) =>
+const onLine = (bots, cron, jobs, onRun) =>
   `obk groom asks you to schedule the daily grooming. First ${clearing(jobs)}. `
   + `Then call CronCreate once, with cron "${cron}", recurring true, and as its prompt everything after "Prompt:" `
   + 'at the end of this line, word for word. Do not run the grooming now; say in one line what you scheduled. '
-  + `Prompt: ${jobPrompt(bots, cron)}`;
+  + `Prompt: ${jobPrompt(bots, cron, onRun)}`;
 
 const offLine = (jobs) =>
   `obk groom asks you to turn the daily grooming off: ${clearing(jobs)}. `

package/src/health.js

@@ -25,7 +25,7 @@ import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
+import { bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
 import { frontOfTab, orcaDefaultArgs, projects, tabs, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
 import { TAB_ENV } from './record.js';
@@ -259,7 +259,26 @@ function runningOn(bots, home, bot, book, handles, sessions) {
     // that is not its own harness, or a front that cannot be read, leaves it
     // unsaid, and nothing unsaid is a finding.
     const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
+    // A Claude session is written to by its name, and Claude Code's own
+    // messaging reaches every session on the machine. One under a name the kit
+    // did not make, such as the bare <bot>.<session> every fleet had before
+    // #286, can be written to by another fleet's session (#450). Its next start
+    // through the kit gives it a name of its own; one that Orca brought back,
+    // or that has run since, keeps the old one until then.
     const front = frontOfTab(handle);
+    const address = entry.address;
+    if (harnessOf(session, bot.harness) === 'claude' && typeof address === 'string' && address !== '' && !isAddressOf(bot.name, session.name, address)) {
+      const shared = address === `${bot.name}.${session.name}`
+        ? `the name every fleet's ${bot.name}/${session.name} was given before #286, so it is shared: a Claude session of another fleet with that bot and session can write to it, thinking it is its own`
+        : `not one the kit made for it, so it may not be this session's alone: another session, in this fleet or another, can go by it too`;
+      // A restart closes the tab, and with no conversation in the book it
+      // refuses rather than end one that is running, so the fix starts there.
+      // With only the shell in front there is nothing to end, and it goes.
+      const fix = typeof entry.session === 'string' || front.front === 'shell'
+        ? `${restart} starts it on an address of its own, <bot>.<session> and a token.`
+        : `The book does not say which conversation it is running, and a restart refuses until it does: write the id into ${bookFile(home)} under ${session.name} as  session: <id>, then ${restart} starts it on an address of its own, <bot>.<session> and a token.`;
+      found.push(finding('session', bookFile(home), `${bot.name}'s session ${session.name} goes by the address ${address}, ${shared}. ${fix}`, bot.name));
+    }
     if (front.front === 'shell') {
       found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} is not running: its tab ${entry.tab} is open with only the tab's shell in front, so its harness quit or crashed. obk up finds the tab open and types nothing into it, so it does not bring the session back; ${restart} does.`, bot.name));
       continue;

package/src/lines.js

@@ -0,0 +1,77 @@
+// A transcript read a line at a time, whatever its size (#396).
+//
+// A harness's record of a conversation can outgrow what one string holds: a
+// Codex rollout of 1.28 GB was seen on a live fleet, and reading it whole
+// threw, so the conversation dropped out of the book's lookup and its usage
+// without a word. So nothing here reads a file whole. The first line is read
+// from the start of the file alone, and a whole transcript goes through a
+// chunk at a time, its text decoded across the chunks so that a character
+// split between two of them stays whole.
+//
+// A line longer than any record the kit reads is not held: it comes through as
+// `undefined`, for the caller to count as a line it could not read. A file cut
+// short and padded (a sparse run of NUL bytes, one enormous "line") is read
+// through to its end without being held either.
+
+import { closeSync, openSync, readSync } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+
+/** How much is read at a time. */
+const CHUNK = 64 * 1024;
+
+/** The longest line held whole. */
+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.
+ */
+export function eachLine(file, onLine) {
+  const fd = openSync(file, 'r');
+  try {
+    const decoder = new StringDecoder('utf8');
+    const buffer = Buffer.allocUnsafe(CHUNK);
+    let pending = '';
+    let tooLong = false;
+    for (;;) {
+      const read = readSync(fd, buffer, 0, CHUNK, null);
+      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)) {
+        const line = tooLong ? undefined : pending + text.slice(start, at);
+        pending = '';
+        tooLong = false;
+        start = at + 1;
+        if (onLine(line) === true) return;
+      }
+      const rest = text.slice(start);
+      if (!tooLong) {
+        if (pending.length + rest.length > LONGEST) {
+          tooLong = true;
+          pending = '';
+        } else {
+          pending += rest;
+        }
+      }
+      if (read === 0) {
+        if (tooLong) onLine(undefined);
+        else if (pending !== '') onLine(pending);
+        return;
+      }
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** The first line of `file`, read from its start alone; `undefined` for an empty file or a first line too long to hold. */
+export function firstLine(file) {
+  let first;
+  eachLine(file, (line) => {
+    first = line;
+    return true;
+  });
+  return first;
+}

package/src/orca.js

@@ -65,11 +65,25 @@ function ask(args, timeoutMs) {
 
   const answer = parse(asked.stdout);
   if (answer === null || typeof answer !== 'object') {
-    throw new Error(`Orca answered ${args.join(' ')} with something that is not JSON.`);
+    // What Orca did say, so the failure shows its cause (#438): its exit, and
+    // each stream cut short and on one line, so a stack trace in it reads as
+    // text and not as the kit's own.
+    const exit = asked.status ?? `signal ${asked.signal}`;
+    throw new Error(`Orca answered ${args.join(' ')} with something that is not JSON (exit ${exit}; `
+      + `stdout ${said(asked.stdout)}; stderr ${said(asked.stderr)}).`);
   }
   return answer;
 }
 
+/** How much of each of Orca's streams an error carries. */
+const SAID = 500;
+
+/** A stream of Orca's as an error carries it: its lines folded into one, cut short with an ellipsis, in quotes. */
+const said = (text) => {
+  const one = String(text ?? '').trim().replace(/\s*\r?\n\s*/g, ' ⏎ ');
+  return `"${one.length > SAID ? `${one.slice(0, SAID)}…` : one}"`;
+};
+
 function parse(text) {
   try {
     return JSON.parse(text);
@@ -369,16 +383,26 @@ export const QUESTION_ON_SCREEN = 'question-on-screen';
  * section 1).
  */
 function screenOf(handle, readMs) {
+  const read = screenRows(handle, readMs);
+  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows) };
+}
+
+/**
+ * The rows the tab `handle` renders, `{ rows }`, or `{ unreadable: <why> }`.
+ * Orca refusing, or answering with anything but the rendered screen, is a
+ * screen that cannot be read, not an error.
+ */
+export function screenRows(handle, readMs) {
   let read;
   try {
     read = orca(['terminal', 'read', '--terminal', handle, '--screen'], { timeoutMs: readMs }).terminal;
   } catch (error) {
-    return { screenUnreadable: `Orca would not read its screen: ${error.message}` };
+    return { unreadable: `Orca would not read its screen: ${error.message}` };
   }
   if (read?.source !== 'screen' || !Array.isArray(read.tail)) {
-    return { screenUnreadable: `Orca gave no rendered screen for it (source: ${read?.source ?? 'none'})` };
+    return { unreadable: `Orca gave no rendered screen for it (source: ${read?.source ?? 'none'})` };
   }
-  return { question: questionIn(read.tail) };
+  return { rows: read.tail };
 }
 
 /** A row the harness starts with its selection pointer: `›` on Codex, `❯` on Claude Code. */

package/src/temp.js

@@ -1,5 +1,6 @@
 // `obk temp make` and `obk temp retire`: a session's own temporary sessions
-// (PRD 6.4, #227).
+// (PRD 6.4, #227). And `obk temp trust-hooks`, the one answer a maker gives its
+// Codex run's hooks review (#238).
 //
 // Any long-lived session can make a temporary session of its own bot for a
 // piece of work, and retire it when the work is done, without Bot Father, who
@@ -22,11 +23,13 @@
 
 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 { addSession, dropSession, NAME, readBot } from './bot.js';
-import { isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
+import { harnessOf, isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
 import { sessionInTab } from './message.js';
+import { orca, screenRows, tabs } from './orca.js';
 import { retireSession } from './retire.js';
 import { bringUp, promptPath } from './up.js';
 
@@ -61,10 +64,14 @@ export async function makeTemp(bots, { tab, ...given }) {
   const settings = { name: given.name };
   const harness = given.harness ?? maker?.harness;
   if (harness !== undefined) settings.harness = harness;
+  // On another harness than its maker's, the model, the effort and the context
+  // are that harness's own, and only the approval carries over (#238, PRD 6.4).
+  const same = (harness ?? bot.harness) === harnessOf(maker ?? {}, bot.harness);
   for (const field of INHERITED) {
-    const value = given[field] ?? maker?.[field];
+    const value = given[field] ?? (same || field === 'approval' ? maker?.[field] : undefined);
     if (value !== undefined) settings[field] = value;
   }
+  if (given.extra_args !== undefined) settings.extra_args = given.extra_args;
   if (given.prompt !== undefined) settings.prompt = given.prompt;
   else settings.prompt_file = given.prompt_file;
   settings.work_dir = `work/${given.name}`;
@@ -145,28 +152,110 @@ function writePromptFirst(bots, caller, settings) {
  */
 export async function retireTemp(bots, { tab, name }) {
   const caller = callerIn(bots, tab, 'retire');
+  ownTemp(caller, name, 'retire', 'Nothing was retired.');
+  return { ...(await retireSession(bots, { bot: caller.bot, session: name })), maker: caller.session };
+}
+
+/**
+ * The caller's own temporary session `name`, from bot.yaml, or a refusal: one
+ * the bot does not have, a long-lived one, or one another session made.
+ * `verb` finishes "to <verb>", and `nothing` is the sentence that ends each.
+ */
+function ownTemp(caller, name, verb, nothing) {
   const bot = readBot(caller.home, caller.bot);
-  if (!bot.sessions.some((session) => session.name === name)) {
-    throw new Error(`${caller.bot} has no session called ${name}, so there is nothing of yours to retire. Nothing was retired.`);
+  const session = bot.sessions.find((one) => one.name === name);
+  if (session === undefined) {
+    throw new Error(`${caller.bot} has no session called ${name}, so there is nothing of yours to ${verb}. ${nothing}`);
   }
   const temporary = readBook(caller.home).sessions[name]?.temporary;
   if (temporary === undefined) {
-    throw new Error(`${caller.bot}/${name} is a long-lived session, and those are Bot Father's to retire. Nothing was retired.`);
+    throw new Error(`${caller.bot}/${name} is a long-lived session, and those are Bot Father's to ${verb}. ${nothing}`);
   }
   if (temporary.maker !== caller.session) {
-    throw new Error(`${caller.bot}/${name} is a temporary session ${temporary.maker} made, not ${caller.session}, so it is ${temporary.maker}'s to retire. Nothing was retired.`);
+    throw new Error(`${caller.bot}/${name} is a temporary session ${temporary.maker} made, not ${caller.session}, so it is ${temporary.maker}'s to ${verb}. ${nothing}`);
   }
-  return { ...(await retireSession(bots, { bot: caller.bot, session: name })), maker: caller.session };
+  return { bot, session };
+}
+
+/** Codex's hooks review, and the one of its choices this kit answers it with (tech notes, section 3). */
+const HOOKS_REVIEW = 'Hooks need review';
+const TRUST_ALL = 'Trust all and continue';
+
+/** How long the review is given to go once answered, looked at every half second. */
+const REVIEW_GONE_MS = 5000;
+
+/**
+ * Answer the hooks review of a Codex run the caller made with "Trust all and
+ * continue", and confirm the review went (#238, the owner's choice (b)). The
+ * one answer a permission rule of its own can allow: a raw `orca terminal
+ * send` cannot be narrowed to a tab or to these keys. Everything that can
+ * refuse is checked before a key is sent. Returns `{ bot, session, maker }`.
+ */
+export async function trustHooks(bots, { tab, name }) {
+  const caller = callerIn(bots, tab, 'trust-hooks', "answer a run's hooks review");
+  const nothing = 'Nothing was typed.';
+  const { bot, session } = ownTemp(caller, name, 'answer for', nothing);
+  const run = `${caller.bot}/${name}`;
+  const harness = harnessOf(session, bot.harness);
+  if (harness !== 'codex') {
+    throw new Error(`${run} runs on ${harness}, and temp trust-hooks answers a Codex run's "${HOOKS_REVIEW}" alone. ${nothing}`);
+  }
+  const tabId = readBook(caller.home).sessions[name]?.tab;
+  const handle = tabId === undefined ? undefined : tabs(caller.home).find((one) => one.tabId === tabId)?.handle;
+  if (handle === undefined) {
+    throw new Error(`${run} has no tab open in Orca, so there is no review of its to answer. ${nothing}`);
+  }
+  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]);
+  for (let waited = 0; ; waited += 500) {
+    const after = screenRows(handle);
+    if (after.rows !== undefined && !after.rows.some((row) => row.includes(HOOKS_REVIEW))) break;
+    if (waited >= REVIEW_GONE_MS) {
+      const still = after.rows === undefined ? `its screen could not be read again (${after.unreadable})` : `its screen still shows "${HOOKS_REVIEW}"`;
+      throw new Error(`${run}: "${TRUST_ALL}" was chosen on its hooks review, but ${REVIEW_GONE_MS / 1000} seconds later ${still}. Look at its tab.`);
+    }
+    await pause(500);
+  }
+  return { bot: caller.bot, session: name, maker: caller.session };
+}
+
+/**
+ * The keys that take Codex's hooks review to "2. Trust all and continue" and
+ * answer it, from wherever its pointer is: arrows, then return, never a digit
+ * (a digit and return once took whatever was highlighted). Undefined when the
+ * rows show no such review with the pointer on one of its choices.
+ */
+function keysToTrustAll(rows) {
+  if (!rows.some((row) => row.includes(HOOKS_REVIEW))) return undefined;
+  if (!rows.some((row) => new RegExp(`^ *(?:› +)?2\\. ${TRUST_ALL}`).test(row))) return undefined;
+  const pointer = rows.map((row) => /^ *› +(\d+)\. /.exec(row)).findLast((found) => found !== null);
+  if (pointer === undefined) return undefined;
+  const moves = 2 - Number(pointer[1]);
+  return (moves > 0 ? '\x1b[B'.repeat(moves) : '\x1b[A'.repeat(-moves)) + '\r';
+}
+
+/** What a screen shows, on one line: its rows with words in them, cut short. */
+function shown(rows) {
+  const text = rows.map((row) => row.trim()).filter((row) => row !== '').join(' ⏎ ');
+  return text.length > 500 ? `${text.slice(0, 500)}…` : text;
 }
 
 /**
  * The session this runs in, as the book knows it, with its home and whether it
  * is itself temporary.
  */
-function callerIn(bots, tab, what) {
+function callerIn(bots, tab, what, doing = `${what} it`) {
   const found = tab === undefined ? undefined : sessionInTab(bots, tab);
   if (found === undefined) {
-    throw new Error(`temp ${what} is run by a session in its own tab, and this is not one of the fleet's tabs, so there is no session here to ${what} it for. Nothing was done.`);
+    throw new Error(`temp ${what} is run by a session in its own tab, and this is not one of the fleet's tabs, so there is no session here to ${doing} for. Nothing was done.`);
   }
   const entry = readBook(found.home).sessions[found.session] ?? {};
   return { bot: found.bot, session: found.session, home: found.home, temporary: entry.temporary };