@assuredloop/orca-bot-kit 0.6.0 → 0.8.0

package/src/groom.js

@@ -1,145 +1,312 @@
 // The daily grooming run (PRD 6.8): an optional pass that reads what the bots
 // have been doing, works out what it cost, and tells Bot Father.
 //
-// It is an Orca automation rather than a tab in the book, and that is forced by
-// how Orca works rather than chosen: an automation can only reuse a session it
-// started itself, so it cannot be pointed at a tab the kit made (tech notes,
-// section 1). So grooming is the automation's own session, and whatever it has
-// to remember between runs lives in files, which is what the profile notes are.
+// It runs on Claude Code's own scheduler, in a session of Bot Father's called
+// `grooming`, because the owner decided that scheduled work does not use an
+// Orca automation: an automation cannot carry a model or an effort of its own,
+// and a session's launch line can (#223). The user adds that session like any
+// other, with the model and effort it is to run at, and brings it up; the kit
+// never makes, starts or closes it.
 //
-// It is created off. It spends tokens every day, and a routine nobody has
-// watched should not be running unwatched, so it waits for one explicit yes.
+// So the kit schedules nothing itself. The job is the session's: its own
+// `CronCreate`, which lives in the running Claude Code and only while its tab is
+// up, comes back on a resume, and outlives a `/clear` (tech notes, section 2).
+// The kit reads which grooming jobs there are out of the transcripts of the
+// conversations that process has had, and when asked it types one line into the
+// grooming tab: schedule, unschedule, run once, or compact. It keeps no copy of
+// what is scheduled, so what it reports is what the conversation holds.
 //
-// The one thing this must get right is that there is never more than one.
-// Orca does not deduplicate an automation by name: asked twice, it makes two,
-// and a user with two of these is groomed twice a day for ever. So the kit
-// looks for its own before it creates anything, and the looking is by both the
-// name it gives its own and the folder it attached it to, because a user's own
-// automation can live in the same project and must be left alone.
+// A line typed into the tab is run when the session gets to it, which may be
+// after the kit has typed another, so what the kit read from the transcript
+// when it typed can be out of date: an `--on` not yet run leaves no job to see.
+// So the lines that schedule and unschedule say what the schedule is to be
+// rather than what to change: when the session runs one, it looks at what it
+// has itself (CronList), removes every grooming job, and then makes the one
+// asked for, or none. Run in any order, the last one typed is what holds
+// (review of PR #322).
+//
+// 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 path from 'node:path';
 
 import { botDir, readBot, requireBotsFolder } from './bot.js';
-import { readBook, takeLock } from './book.js';
-import { ownCli, shellWord } from './launch.js';
-import { orca } from './orca.js';
+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 { lines } from './usage.js';
 
-/** What the kit calls its own grooming automation. */
-const NAME = 'obk grooming';
+/** Bot Father's session the grooming runs in. */
+export const GROOMING = 'grooming';
 
 /** A time of day, as a person writes one. */
 const AT = /^([01]\d|2[0-3]):([0-5]\d)$/;
 
-/** What the automation's session is told to do when it wakes. */
-const prompt = (bots) =>
-  '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 ${shellWord(ownCli())} usage --since <last end> --until <this end>, and write this `
-  + 'end down for the next run. Work out what it cost with obk-finops, keep '
-  + 'each bot\'s profile notes, and send one short report to Bot Father\'s '
-  + `management session. The kit here is ${shellWord(ownCli())}: run it wherever a skill says obk. `
-  + `The bots folder is ${bots}.`;
+/** A daily cron as the kit writes one: minute, hour, every day. */
+const DAILY = /^(\d{1,2}) (\d{1,2}) \* \* \*$/;
+
+/** How long Claude Code keeps a recurring job after it was made (tech notes, section 2). */
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 
 /**
- * Say what the grooming is, and make it so when asked.
- * Returns `{ exists }`, and `{ exists, enabled, at, id }` once there is one.
+ * What the session looks for in its own CronList to find its grooming jobs.
+ * Only the start of the marker: CronList shows a prompt cut short, and the
+ * grooming session is one Bot Father's, so its jobs are all this fleet's.
+ */
+const PREFIX = 'obk grooming';
+
+/** How long Orca is given to say what is in the grooming tab. */
+const LOOK_MS = 2000;
+
+/**
+ * What every grooming job's prompt starts with, which is how the kit and the
+ * session tell it from a job of the user's own in the same conversation.
+ */
+export const markerOf = (bots) => `obk grooming for ${bots}`;
+
+/**
+ * Say what the grooming is, and ask the grooming session for a change when
+ * told to. `ask` is one of `on`, `move` (a new time for grooming that is on),
+ * `off`, `now` and `compact`, or undefined to only report; `at` is a time of
+ * day, `HH:MM`.
  *
- * Reading and setting are one command because they are one question: a caller
- * that has just moved the time wants to be told what it is now, and what it is
- * now is whatever Orca says rather than whatever the kit last asked for.
+ * Returns `{ session, jobs, asked }`: the grooming session as the book has it
+ * (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, on } = {}) {
+export function grooming(bots, { at, ask } = {}) {
   requireBotsFolder(bots);
 
-  // The folder as the file system knows it, the way `restart` and `message`
-  // take it: Orca records an automation's workspace by its real path, so a
-  // spelling that is not the canonical one finds nothing and offers to make a
-  // second of what is already there.
+  // 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.
   const home = realHome(botDir(bots, BOT_FATHER));
   if (!existsSync(path.join(home, 'bot.yaml'))) {
-    throw new Error(`there is no ${BOT_FATHER} in ${bots}, and the grooming runs in its Orca project. Run obk init first.`);
+    throw new Error(`there is no ${BOT_FATHER} in ${bots}, and the grooming runs in a session of its. Run obk init first.`);
   }
   if (at !== undefined && !AT.test(at)) {
     throw new Error(`--at is a time of day as 24 hours, such as 04:00, and got: ${at}`);
   }
 
   const bot = readBot(home, BOT_FATHER);
-  const book = readBook(home);
-  if (book.orca.project === undefined) {
-    throw new Error(`${BOT_FATHER} has no Orca project yet, so there is nothing for the grooming to run in. Run ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${BOT_FATHER} first.`);
+  const found = bot.sessions.find((one) => one.name === GROOMING);
+  const entry = readBook(home).sessions[GROOMING] ?? {};
+  const tab = typeof entry.tab === 'string' ? entry.tab : undefined;
+  const conversation = typeof entry.session === 'string' ? entry.session : null;
+
+  const session = found === undefined ? null : {
+    name: GROOMING,
+    harness: harnessOf(found, bot.harness),
+    up: tab !== undefined && tabs(home).some((one) => one.tabId === tab),
+    conversation,
+  };
+  const jobs = session?.harness === 'claude' && conversation !== null
+    ? groomingJobs(ofThisProcess(home, entry), markerOf(bots), Date.now())
+    : [];
+
+  const line = ask === undefined ? undefined : lineFor(ask, { bots, session, jobs, at });
+  if (line !== undefined) typeInto(bots, home, session, tab, line);
+
+  // A move is turning it on at another time, and is typed as one.
+  return { session, jobs, asked: line === undefined ? null : (ask === 'move' ? 'on' : ask) };
+}
+
+/**
+ * The line that asks the grooming session for `ask`, or undefined when there is
+ * nothing to ask. Everything that makes the ask impossible refuses here, before
+ * Orca is asked for anything.
+ */
+function lineFor(ask, { bots, session, jobs, at }) {
+  // 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;
+  if (session === null) {
+    throw new Error(`${BOT_FATHER} has no ${GROOMING} session, so there is nothing to ask. Add it: ${addCommand(bots)}, then ${upCommand(bots)}.`);
+  }
+  if (session.harness !== 'claude') {
+    throw new Error(`${BOT_FATHER}'s ${GROOMING} session runs on ${session.harness}, and grooming runs on Claude Code's own schedule, so its session has to be a Claude Code one. Retire it and add it again: ${retireCommand(bots)}, then ${addCommand(bots)} --harness claude.`);
   }
 
-  // Looking and making are one turn. Orca will not stop two runs creating two
-  // automations for one fleet, and two of these means being groomed twice a day
-  // for ever, so the lock the kit already uses for a bot's own file is held
-  // across the pair (src/book.js).
-  const lock = takeLock(home);
-  try {
-    return settle(bots, home, bot, { at, on });
-  } finally {
-    lock.release();
+  if (ask === 'off') return offLine(jobs);
+  if (ask === 'now') return nowLine(bots);
+  if (ask === 'compact') return '/compact';
+
+  if (ask === 'move' && jobs.length === 0) {
+    throw new Error(`grooming is off, so there is no job to move. Turning it on at that time is ${groomCommand(bots)} --on --at ${at}, once the user has said yes.`);
   }
-}
 
-/** The looking and the making, with the turn already taken. */
-function settle(bots, home, bot, { at, on }) {
-  let mine = ours(home);
-
-  if (mine === undefined && at !== undefined) {
-    orca([
-      'automations', 'create',
-      '--name', NAME,
-      '--provider', bot.harness,
-      '--trigger', 'daily',
-      '--time', at,
-      '--prompt', prompt(bots),
-      '--workspace', `path:${home}`,
-      '--workspace-mode', 'existing',
-      // Off, whatever else was asked for: turning it on is a separate decision
-      // and is made below, so that the one path into "it runs daily" is the
-      // same whether it was made just now or a month ago.
-      '--disabled',
-    ]);
-    mine = ours(home);
-  } else if (mine !== undefined && at !== undefined && at !== timeOf(mine)) {
-    // Orca refuses a time on its own, so the trigger goes with it every time.
-    orca(['automations', 'edit', '--id', mine.id, '--trigger', 'daily', '--time', at]);
+  // On: at the time given, or at the one time every job there already has.
+  const times = [...new Set(jobs.map((job) => job.at))];
+  const when = at ?? (times.length === 1 ? times[0] : undefined);
+  if (when === undefined) {
+    throw new Error(jobs.length === 0
+      ? `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);
+}
 
-  if (on !== undefined && mine !== undefined) {
-    orca(['automations', 'edit', '--id', mine.id, on ? '--enabled' : '--disabled']);
+/**
+ * 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.
+ */
+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.`);
+  }
+  typeIntoTab(found.handle, line);
+}
 
-  // Asked again rather than assumed: the user can move it or switch it in
-  // Orca's own interface, and what this prints has to be what is there.
-  const now = ours(home);
-  return now === undefined
-    ? { exists: false }
-    : { exists: true, enabled: now.enabled === true, at: timeOf(now), id: now.id };
+/**
+ * The transcript lines of every conversation the grooming session's running
+ * Claude Code has had, oldest conversation first.
+ *
+ * A job lives in the process, not in one conversation: seen live, a `/clear`
+ * left the job made before it running, and the new conversation's CronList
+ * still answered it. So the conversation the book holds now is read, and before
+ * it each one it cleared, back through the book's history, until the one where
+ * this process began: the kit's own SessionStart hook leaves a line in every
+ * conversation it sees start, and `startup` or `resume` there means a process
+ * started with it (a fresh start, the kit's restart, or Orca restoring the tab).
+ * Whatever came before that belonged to a process that has gone.
+ */
+function ofThisProcess(home, entry) {
+  const history = Array.isArray(entry.history) ? entry.history : [];
+  const read = [];
+  let id = entry.session;
+  for (let back = history.length - 1; ; back -= 1) {
+    const those = lines(claudeTranscript(home, id));
+    read.unshift(those);
+    if (those.some(beganHere)) break;
+    const was = history[back];
+    if (was === null || typeof was !== 'object' || was.ended !== 'clear' || typeof was.session !== 'string') break;
+    id = was.session;
+  }
+  return read.flat();
 }
 
+/** Whether a transcript line is the kit's hook seeing a process start on this conversation. */
+const beganHere = (line) => line.type === 'attachment'
+  && ['SessionStart:startup', 'SessionStart:resume'].includes(line.attachment?.hookName);
+
 /**
- * The kit's own grooming automation for this Bot Father, if there is one.
+ * The grooming jobs alive in transcript lines at `now`, oldest first:
+ * `{ id, at, cron, made, expires }`.
  *
- * Both halves are needed. The folder alone would adopt whatever the user set up
- * in the same project, and the name alone would collide across two bots folders
- * on one machine, which each have a Bot Father of their own.
+ * A job is made by a CronCreate that succeeded, recurring (Claude Code's
+ * default), with a prompt that starts with the marker. It ends at a CronDelete
+ * of its id that succeeded, or a week after it was made. A call is matched to
+ * its answer by the tool call's id; an answer that failed is a string, not the
+ * job, and makes or ends nothing.
  */
-function ours(home) {
-  const listed = orca(['automations', 'list']).automations ?? [];
-  const found = listed.filter((one) => one?.name === NAME && one?.runContext?.path === home);
-
-  // More than one is not a thing to pick from. Whichever were chosen, the other
-  // would go on running unseen, and this command is where the user would have
-  // looked for it. So it says what it found and leaves both alone.
-  if (found.length > 1) {
-    throw new Error(`${home} has ${found.length} groomings rather than one: ${found.map((one) => one.id).join(', ')}. Remove the ones you do not want in Orca, then run this again.`);
+export function groomingJobs(entries, marker, now) {
+  const calls = new Map();
+  const alive = new Map();
+  for (const entry of entries) {
+    const content = Array.isArray(entry.message?.content) ? entry.message.content : [];
+    for (const item of content) {
+      if (entry.type === 'assistant' && item?.type === 'tool_use') calls.set(item.id, item);
+      if (entry.type !== 'user' || item?.type !== 'tool_result' || item.is_error === true) continue;
+
+      const call = calls.get(item.tool_use_id);
+      const result = entry.toolUseResult;
+      if (call === undefined || result === null || typeof result !== 'object' || typeof result.id !== 'string') continue;
+      if (call.name === 'CronDelete') alive.delete(result.id);
+      if (call.name !== 'CronCreate') continue;
+
+      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 });
+    }
   }
-  return found[0];
+  return [...alive.values()]
+    .filter((job) => job.expires > now)
+    .sort((left, right) => left.made - right.made)
+    .map((job) => ({ ...job, made: new Date(job.made).toISOString(), expires: new Date(job.expires).toISOString() }));
+}
+
+/** `HH:MM` as the daily cron Claude Code takes: `04:00` is `0 4 * * *`. */
+const cronOf = (at) => {
+  const [, hour, minute] = AT.exec(at);
+  return `${Number(minute)} ${Number(hour)} * * *`;
+};
+
+/** A daily cron read back as `HH:MM`, or undefined for any other shape. */
+function timeOf(cron) {
+  const found = DAILY.exec(String(cron ?? ''));
+  if (found === null) return undefined;
+  return `${found[2].padStart(2, '0')}:${found[1].padStart(2, '0')}`;
 }
 
+/** The grooming run itself: what a job does each day, and what `--now` asks for once. */
+const run = (bots) =>
+  `${markerOf(bots)}: 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 ${shellWord(ownCli())} usage --since <last end> --until <this end>, and write this `
+  + 'end down for the next run. Work out what it cost with obk-finops, keep '
+  + 'each bot\'s profile notes, and send one short report to Bot Father\'s '
+  + `management session. The kit here is ${shellWord(ownCli())}: run it wherever a skill says obk. `
+  + `The bots folder is ${bots}.`;
+
+/**
+ * A job's prompt: the run, and then its own renewal, since Claude Code ends a
+ * recurring job a week after it was made. The renewal copies the prompt it was
+ * 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: `
+  + `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 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.
+ */
+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) =>
+  `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)}`;
+
+const offLine = (jobs) =>
+  `obk groom asks you to turn the daily grooming off: ${clearing(jobs)}. `
+  + 'Schedule nothing in their place, and say in one line what you cancelled.';
+
+const nowLine = (bots) => `obk groom asks you to run the daily grooming once, now, and to schedule nothing. ${run(bots)}`;
+
+/** The command that adds the grooming session, for a caller to run. */
+export const addCommand = (bots) =>
+  `${shellWord(ownCli())} session add --bots ${shellWord(bots)} --bot ${BOT_FATHER} --name ${GROOMING}`;
+
+/** The command that brings Bot Father's sessions up. */
+export const upCommand = (bots) => `${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${BOT_FATHER}`;
+
+/** This command again, for a caller to add its flags to. */
+export const groomCommand = (bots) => `${shellWord(ownCli())} groom --bots ${shellWord(bots)}`;
+
+const retireCommand = (bots) => `${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${BOT_FATHER} --session ${GROOMING}`;
+
+const restartCommand = (bots) => `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${BOT_FATHER} --session ${GROOMING}`;
+
 /** A bot home as the file system knows it, or as it was given when it is not there. */
 function realHome(home) {
   try {
@@ -148,12 +315,3 @@ function realHome(home) {
     return home;
   }
 }
-
-/** When an automation runs, read out of Orca's own recurrence rule. */
-function timeOf(automation) {
-  const rule = String(automation?.rrule ?? '');
-  const hour = /BYHOUR=(\d+)/.exec(rule)?.[1];
-  const minute = /BYMINUTE=(\d+)/.exec(rule)?.[1];
-  if (hour === undefined || minute === undefined) return undefined;
-  return `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`;
-}

package/src/health.js

@@ -25,8 +25,9 @@ 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, shellWord } from './launch.js';
-import { frontOfTab, orcaDefaultArgs, projects, tabs } from './orca.js';
+import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
+import { frontOfTab, orcaDefaultArgs, projects, tabs, wordsOfProcess } from './orca.js';
+import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
 import { settingsInUse } from './settings.js';
 import { skillsTrouble } from './skills.js';
@@ -215,8 +216,9 @@ const hooksOf = (bots, home, bot) => [...new Set(bot.sessions.map((session) => h
 /**
  * Each session of this bot running in a tab Orca has, with what it runs on set
  * beside what the bot asks for now, added to `sessions`; a finding for each
- * one that runs on something else (#271, #272); and a finding for each one
- * whose tab is open with its harness gone from it (#300).
+ * one that runs on something else (#271, #272), or whose harness the kit's
+ * launch line did not start (#318); and a finding for each one whose tab is
+ * open with its harness gone from it (#300).
  *
  * Two questions, each answered from where the answer is written. The settings
  * from the harness's own record of the conversation the session is in now,
@@ -270,8 +272,15 @@ function runningOn(bots, home, bot, book, handles, sessions) {
     if (running !== 'yes') continue;
 
     const off = Object.entries(settings).filter(([, one]) => one.state === 'mismatch');
-    if (off.length > 0) {
-      const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+    const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+    if (startedByKit(front.pid, entry.tab) === false) {
+      // Orca brings its tabs back by itself after a restart or an update, with
+      // a bare resume and none of the kit's launch line (#318). What health can
+      // see may still match, by the harness's own defaults; the rest of what
+      // bot.yaml asks for is not on it either way.
+      const drift = off.length === 0 ? '' : ` ${parts}, as the harness's own record of its conversation ${conversation} says.`;
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} was not started by the kit: the harness in its tab ${entry.tab} carries nothing of the kit's launch line, as when Orca brings its tabs back by itself after a restart or an update. So it runs on the harness's own defaults and whatever Orca added, not on what ${path.join(home, 'bot.yaml')} asks for.${drift} ${restart} starts it on bot.yaml.`, bot.name));
+    } else if (off.length > 0) {
       found.push(finding('session', file, `${bot.name}'s session ${session.name} does not run on what ${path.join(home, 'bot.yaml')} asks for. ${parts}. That is what the harness's own record of its conversation ${conversation} says. A session takes these when it starts, so if bot.yaml changed after it started, ${restart} starts it on them; if not, something else set them, such as a default of the harness's own or a change made inside the session.`, bot.name));
     }
 
@@ -289,6 +298,19 @@ function runningOn(bots, home, bot, book, handles, sessions) {
   return found;
 }
 
+/**
+ * Whether the kit's launch line started the process `pid` in the tab `tab`:
+ * true when it carries the marker the line puts there, false when it carries
+ * that tab's id and no marker, and undefined when its environment cannot be
+ * read (tech notes, section 1). Only a whole word counts: an argument, such as
+ * a start prompt, can hold anything.
+ */
+function startedByKit(pid, tab) {
+  const words = pid === undefined ? undefined : wordsOfProcess(pid);
+  if (words === undefined || !words.includes(`${TAB_ENV}=${tab}`)) return undefined;
+  return words.some((word) => new RegExp(`^${SHELL_ENV}=[0-9]+$`).test(word));
+}
+
 /**
  * What Orca has of this bot against what the book says it should have: a
  * session whose tab is gone, a conversation nobody claims, and a tab in the
@@ -357,7 +379,7 @@ function inOrca(bots, home, bot, setups, sessions) {
 /**
  * The conversations a harness has on record in this bot's folder that the book
  * does not name anywhere. The hook is how an id reaches the book, and when it
- * fails it fails quietly (ADR 0020), so this is where a stale book shows: the
+ * fails it fails quietly (ADR 0022), so this is where a stale book shows: the
  * harness's own record set beside it (ADR 0012).
  */
 function offTheBook(home, bot, book, onRecord) {

package/src/hooks.js

@@ -1,4 +1,4 @@
-// The kit's own hook, in the bot's folder and nowhere else (ADR 0020).
+// The kit's own hook, in the bot's folder and nowhere else (ADR 0022).
 //
 // Both harnesses read a hooks file out of the folder a session starts in, and
 // every session starts at its bot home, so the bot folder is where the kit's
@@ -35,7 +35,7 @@ const TIMEOUT = 10;
  * What the hook runs: the CLI that wrote it, by its own path, so the session
  * reports to the kit that set it up and not to whatever `obk` PATH finds in the
  * harness's shell (#220). `|| true` and a quiet stderr because a hook must never
- * disturb the session it fires in (ADR 0020): a kit that is not there, or a book
+ * disturb the session it fires in (ADR 0022): a kit that is not there, or a book
  * that cannot be written, leaves the session alone and the health check finds
  * the stale book later.
  */
@@ -124,7 +124,7 @@ export function hookTrouble(home, harness, { bots, bot }) {
 /**
  * What to say about a hooks file that a link takes out of the bot folder, or
  * undefined when it stays in. The kit writes its hook in the bot folder and
- * nowhere else (ADR 0020); through a link like that it would be writing the
+ * nowhere else (ADR 0022); through a link like that it would be writing the
  * user's own settings, so it does not, and says why.
  */
 function outside(home, file) {

package/src/message.js

@@ -350,13 +350,15 @@ const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '
  * into one of those is not a message: it is an answer to whatever question is
  * up. That is not a worry, it is a thing that happened — in slice 03 a second
  * line went into a tab on Claude Code's folder-trust list, confirmed its
- * default, `No, exit`, and the harness quit (tech notes, section 1). So where
- * Orca says a tab is blocked, nothing is typed and the mail waits.
+ * default, `No, exit`, and the harness quit (tech notes, section 1). And in
+ * #329 a return took Codex's "Update now". So where Orca says a tab is
+ * blocked, or the kit sees a numbered choice list of the harness's own on its
+ * screen, nothing is typed and the mail waits.
  *
- * Orca's `blockedReason` catches Codex's screens and not Claude Code's, which
- * answer as idle with nothing said, so this narrows the case rather than
- * closing it. What closes it is nobody sending to a session before its first
- * screens are answered, which is the caller's work either way.
+ * That narrows the case rather than closing it: a question drawn any other way,
+ * such as Claude Code's unnumbered trust list, is seen by neither. What closes
+ * it is nobody sending to a session before its first screens are answered,
+ * which is the caller's work either way.
  */
 function nudge(to, from, subject) {
   if (to.tab === undefined) return { nudged: false };

package/src/orca-window.cjs

@@ -3,7 +3,7 @@
 //
 // It asks Orca's runtime, through Orca's own client, for `project.update` with
 // no changes on one project. That is the call that makes Orca's window read its
-// projects again, and Orca's CLI does not offer it (#224, ADR 0021). It exits 0
+// projects again, and Orca's CLI does not offer it (#224, ADR 0023). It exits 0
 // only when the runtime took the call; anything else is a non-zero exit, and
 // the kit reads every non-zero exit the same way.