@assuredloop/orca-bot-kit 0.26.1 → 0.28.0

package/src/conversations.js

@@ -6,11 +6,11 @@
 // the kit never recorded must not be mistaken for a session that never had one,
 // so when the book cannot say, the harness is asked instead.
 //
-// Both harnesses keep their own record of every conversation, per working
+// Every harness keeps its own record of every conversation, per working
 // directory, and every session starts at its bot home. Read only, never
 // written: these are the harness's files (tech notes, sections 2 and 3).
 
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 
@@ -22,6 +22,38 @@ const claudeDir = (home) => path.join(homedir(), '.claude', 'projects', slug(hom
 /** The folder's name is the working directory with everything else turned into a dash. */
 const slug = (home) => home.replaceAll(/[^A-Za-z0-9]/g, '-');
 
+/**
+ * Pi's sessions: one folder per working directory, named from its real path
+ * with the leading `/` taken off and `/`, `\` and `:` turned into dashes,
+ * between `--`; one `<time>_<id>.jsonl` per conversation (Pi 1.1.0,
+ * `getDefaultSessionDirPath`, tech notes, section 6).
+ */
+const piDir = (home) => path.join(homedir(), '.pi', 'agent', 'sessions', `--${realHome(home).replace(/^[/\\]/, '').replaceAll(/[/\\:]/g, '-')}--`);
+
+/** The folder as Pi sees it from inside: the real path, when there is one. */
+function realHome(home) {
+  try {
+    return realpathSync(home);
+  } catch {
+    return home;
+  }
+}
+
+/**
+ * A Pi session file's name, `<time>_<id>.jsonl`: the time is Pi's ISO time
+ * with `:` and `.` turned into dashes, and the id may hold a `_` of its own.
+ */
+const PI_FILE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z_(.+)\.jsonl$/;
+
+/** The id a Pi session file's name carries, or undefined for a file that is not one. */
+const piIdOf = (name) => PI_FILE.exec(name)?.[1];
+
+/** Where Pi keeps the conversation `id` of this bot home, or undefined when it has none yet. */
+const piSession = (home, id) => {
+  const name = files(piDir(home)).find((one) => piIdOf(one) === id);
+  return name === undefined ? undefined : path.join(piDir(home), name);
+};
+
 /** Codex's rollouts: a file per conversation, filed by the day it started. */
 const codexDir = () => path.join(homedir(), '.codex', 'sessions');
 
@@ -52,6 +84,7 @@ export function conversationsIn(harness, home, since) {
  */
 export function hasConversation(harness, home, id) {
   if (harness === 'claude') return existsSync(claudeTranscript(home, id));
+  if (harness === 'pi') return piSession(home, id) !== undefined;
   return codexRollout(id) !== undefined;
 }
 
@@ -120,7 +153,9 @@ export function claudeSubagentTranscripts(file) {
  */
 export function transcriptsIn(harness, home, since) {
   const from = since === undefined ? 0 : Date.parse(since);
-  const found = harness === 'claude' ? claudeConversations(home) : codexConversations(home, from);
+  const found = harness === 'claude' ? claudeConversations(home)
+    : harness === 'pi' ? piConversations(home)
+      : codexConversations(home, from);
   return found
     .filter((one) => Number.isNaN(from) || one.at >= from)
     .sort((left, right) => left.at - right.at)
@@ -159,43 +194,6 @@ export function heldAsUserTurn(harness, file, text) {
   return held;
 }
 
-/**
- * Where the harness keeps the conversation `id` of this bot home, and how long
- * that record is now: `{ harness, file, size }`, so a later look reads only
- * what was written after this moment. Undefined when there is no id, no
- * record, or it cannot be read (#509).
- */
-export function recordMark(harness, home, id) {
-  if (typeof id !== 'string' || id === '') return undefined;
-  try {
-    const file = harness === 'codex' ? codexRollout(id) : claudeTranscript(home, id);
-    if (file === undefined) return undefined;
-    const found = statSync(file);
-    return found.isFile() ? { harness, file, size: found.size } : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Whether a turn of the user's written after `mark` holds `text` anywhere in
- * it (#509). A record that cannot be read says no: not seeing a thing is not
- * seeing it.
- */
-export function userTurnSince(mark, text) {
-  if (mark === undefined || mark === null) return false;
-  let held = false;
-  try {
-    eachLine(mark.file, (line) => {
-      held = line !== undefined && userTexts(mark.harness, line).some((said) => said.includes(text));
-      return held;
-    }, { from: mark.size });
-  } catch {
-    return false;
-  }
-  return held;
-}
-
 /** The texts of one record line, when it is a turn of the user's. */
 function userTexts(harness, line) {
   let parsed;
@@ -210,6 +208,14 @@ function userTexts(harness, line) {
     if (typeof content === 'string') return [content];
     return Array.isArray(content) ? content.filter((block) => block?.type === 'text').map((block) => String(block.text)) : [];
   }
+  if (harness === 'pi') {
+    // A turn is a `message` line, and the user's are role `user` (Pi 1.1.0,
+    // docs/session-format.md).
+    const message = parsed?.type === 'message' ? parsed.message : undefined;
+    if (message?.role !== 'user') return [];
+    if (typeof message.content === 'string') return [message.content];
+    return Array.isArray(message.content) ? message.content.filter((block) => block?.type === 'text').map((block) => String(block.text)) : [];
+  }
   const item = parsed?.type === 'response_item' ? parsed.payload : undefined;
   if (item?.type !== 'message' || item.role !== 'user' || !Array.isArray(item.content)) return [];
   return item.content.filter((block) => block?.type === 'input_text').map((block) => String(block.text));
@@ -228,6 +234,33 @@ function claudeConversations(home) {
     });
 }
 
+/**
+ * Pi's conversations in this bot home. The first line of each is its header,
+ * `{ type: 'session', id, timestamp, cwd }`, and says which conversation it is
+ * and when it began; the file's name says the id too.
+ */
+function piConversations(home) {
+  return files(piDir(home))
+    .filter((name) => name.endsWith('.jsonl'))
+    .flatMap((name) => {
+      const file = path.join(piDir(home), name);
+      const header = piHeader(file);
+      const id = typeof header?.id === 'string' ? header.id : piIdOf(name);
+      const at = Date.parse(header?.timestamp ?? '') || startedAt(file);
+      return at === undefined || id === undefined || id === '' ? [] : [{ id, at, file }];
+    });
+}
+
+/** A Pi session's first line, when it is the header. */
+function piHeader(file) {
+  try {
+    const parsed = JSON.parse(firstLine(file) ?? '');
+    return parsed?.type === 'session' ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** When a transcript's first line says the conversation was, if it says at all. */
 function said(file) {
   try {

package/src/groom.js

@@ -44,7 +44,7 @@ import path from 'node:path';
 import { botDir, readBot, requireBotsFolder } from './bot.js';
 import { readBook, takeLineTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { claudeTranscript } from './conversations.js';
-import { harnessOf, ownCli, shellWord } from './launch.js';
+import { harnessOf, ownCli, promptFile, shellWord, startPrompt } from './launch.js';
 import { tabs, tabToTypeInto, typeIntoTab } from './orca.js';
 import { BOT_FATHER, promptPath } from './up.js';
 import { lines } from './usage.js';
@@ -123,7 +123,7 @@ export function grooming(bots, { at, ask, run } = {}) {
     ? groomingJobs(ofThisProcess(home, entry), markerOf(bots), Date.now())
     : [];
 
-  const line = ask === undefined ? undefined : lineFor(ask, { bots, session, jobs, at, run });
+  const line = ask === undefined ? undefined : lineFor(ask, { bots, home, found, 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.
@@ -135,7 +135,7 @@ export function grooming(bots, { at, ask, run } = {}) {
  * nothing to ask. Everything that makes the ask impossible refuses here, before
  * Orca is asked for anything.
  */
-function lineFor(ask, { bots, session, jobs, at, run }) {
+function lineFor(ask, { bots, home, found, 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;
@@ -165,7 +165,8 @@ function lineFor(ask, { bots, session, jobs, at, run }) {
   // 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);
+  const onRun = run ?? keep;
+  return onLine(bots, cronOf(when), jobs, onRun === undefined ? undefined : { ...onRun, task: writeRunTask(bots, ownPrompt(home, found)) });
 }
 
 /**
@@ -367,7 +368,7 @@ function runElsewhere(bots, onRun) {
     ...(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))}`,
+    `--prompt-file ${shellWord(onRun.task)}`,
   ].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- `
@@ -390,13 +391,29 @@ function readReport(bots) {
     + `Then retire the run with ${retire}, its name in place of ${RUN_NAME}. Schedule nothing then: the job renewed itself when it fired.`;
 }
 
+/**
+ * The grooming session's own prompt, as the user wrote it, or undefined when it
+ * has none: the standing duties a run on Codex carries too (#566). Without the
+ * work-dir note the session is launched with, since a run has a work dir of its
+ * own. Read when the line is typed, so a prompt changed since reaches the runs
+ * at the next `--on`.
+ */
+function ownPrompt(home, session) {
+  try {
+    return startPrompt(session, { home });
+  } catch (error) {
+    throw new Error(`${BOT_FATHER}'s ${GROOMING} session's prompt file ${promptFile(session, home)} cannot be read (${error.code ?? error.message}), and each grooming run on Codex carries that prompt. Nothing was typed. Put the file back, or change the session's prompt, then run this again.`);
+  }
+}
+
 /**
  * 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.
+ * grooming with the obk-grooming skill, and the grooming session's own duties
+ * when its prompt has any, 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) {
+function writeRunTask(bots, own) {
   const real = realHome(bots);
   const kit = shellWord(ownCli());
   const file = path.resolve(promptPath(real, BOT_FATHER, `${GROOMING}-run`));
@@ -405,6 +422,7 @@ function writeRunTask(bots) {
     + `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}. `
+    + (own === undefined ? '' : `The ${GROOMING} session's own prompt is this run's too. It follows, word for word as the user wrote it:\n\n${own}\n\n`)
     + `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';

package/src/health.js

@@ -18,22 +18,23 @@
 // is, the one thing to go and look at, and a sentence naming it — so that
 // somebody who cannot read code knows what was found and where.
 
-import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 
 import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
+import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, promptFile, sessionTrouble, set, SHELL_ENV, shellWord, workDirOf } from './launch.js';
 import { frontOfTab, orcaDefaultArgs, projects, runMissing, tabs, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
+import { processesIn } from './processes.js';
 import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
 import { settingsInUse } from './settings.js';
 import { skillsTrouble } from './skills.js';
 import { readSources, sourcesDir } from './sources.js';
-import { BOT_FATHER, botsNamed, promptPath } from './up.js';
+import { BOT_FATHER, botsNamed, oldPromptPath, promptPath } from './up.js';
 
 /**
  * Everything wrong with the setup at `bots`, in one list: what Orca's own
@@ -139,8 +140,20 @@ function leftBeside(bots) {
   let known = true;
   for (const name of botNames(bots)) {
     try {
-      for (const session of readBot(botDir(bots, name), name).sessions) {
+      const home = botDir(bots, name);
+      for (const session of readBot(home, name).sessions) {
         owned.add(promptPath(bots, name, session.name));
+        // The file a session names as its own prompt, which the kit reads to
+        // start it, and the file a link there leads to (#577).
+        if (set(session.prompt_file)) {
+          const file = promptFile(session, home);
+          owned.add(file);
+          const real = realpathOf(file);
+          if (real !== undefined) owned.add(real);
+        }
+        // Where a live session's prompt was before #534: nothing reads it once
+        // the session starts again, and its retire removes it.
+        owned.add(oldPromptPath(bots, name, session.name));
       }
     } catch {
       known = false;
@@ -148,9 +161,8 @@ function leftBeside(bots) {
   }
 
   if (known) {
-    for (const file of namesIn(`${bots}.prompts`)) {
-      const at = path.join(`${bots}.prompts`, file);
-      if (owned.has(at)) continue;
+    for (const at of promptFilesIn(`${bots}.prompts`)) {
+      if (owned.has(at) || owned.has(realpathOf(at))) continue;
       found.push(finding('leftover', at, `${at} is a start prompt the kit wrote beside your bots folder, and no session of any bot answers to it now. Nothing reads it.`));
     }
   }
@@ -196,9 +208,48 @@ function aboutBot(bots, name, setups, sessions) {
     ...permissionsTrouble(home, bot).map(said('config')),
     ...skillsTrouble(bots, home, bot).map(said('skill')),
     ...inOrca(bots, home, bot, setups, sessions),
+    ...leftRunning(home, bot),
   ];
 }
 
+/**
+ * What still runs in the work dir of a retired session (#537): a retire stops
+ * it, so this is one from before that, or one a retire could not stop. The
+ * book keeps a retired session's work dir; a temporary session retired before
+ * it did worked in `work/<name>`, where `obk temp make` puts it. A work dir a
+ * session in bot.yaml still uses is that session's, and not looked at, by its
+ * real path, so a link to it is not taken for a retired one (review of PR #543).
+ */
+function leftRunning(home, bot) {
+  let book;
+  try {
+    book = readBook(home);
+  } catch {
+    // A book that cannot be read is said where the book is read.
+    return [];
+  }
+  const real = (dir) => (dir === undefined ? undefined : realpathOf(dir));
+  const live = new Set(bot.sessions.map((session) => real(workDirOf(session, home))));
+  const dirs = [];
+  const seen = new Set();
+  for (const entry of Array.isArray(book.retired) ? book.retired : []) {
+    const named = typeof entry?.work_dir === 'string' && entry.work_dir !== '' ? entry.work_dir : undefined;
+    const dir = workDirOf({ work_dir: named ?? (entry?.temporary === undefined ? undefined : `work/${entry.name}`) }, home);
+    // One that is not there holds nothing.
+    const at = real(dir);
+    if (at === undefined || live.has(at) || seen.has(at)) continue;
+    seen.add(at);
+    dirs.push({ session: entry.name, dir });
+  }
+  if (dirs.length === 0) return [];
+
+  const read = processesIn(dirs);
+  if (read.unreadable !== undefined) {
+    return [finding('process', bookFile(home), `The kit cannot tell whether anything still runs in the work dirs of ${bot.name}'s retired sessions: ${read.unreadable}.`, bot.name)];
+  }
+  return read.running.map((one) => finding('process', one.dir, `pid ${one.pid} still runs in the work dir of ${bot.name}/${one.session}, which was retired: ${one.command}. Nothing of the kit's stops it now. If it is not wanted, stop it yourself:  kill ${one.pid}`, bot.name));
+}
+
 /** A session the kit would refuse to start, in the words `up` refuses it with. */
 function sessionSettings(home, bot) {
   const file = path.join(home, 'bot.yaml');
@@ -213,7 +264,7 @@ function sessionSettings(home, bot) {
 /** What is wrong with the roles the bot's temporary sessions are made in (#465). */
 function rolesTrouble(home, bot) {
   const where = path.join(home, 'bot.yaml');
-  // The widest approval they may be made at, the user's yes (ADR 0041).
+  // The widest approval they may be made at, the user's yes (ADR 0051).
   const level = bot.temp_approval;
   const approval = level === undefined || APPROVALS.includes(level) ? [] : [{
     where,
@@ -382,7 +433,7 @@ function inOrca(bots, home, bot, setups, sessions) {
 
   // What the harness has on record in this bot's folder, read once: it is a walk
   // through every conversation on the machine.
-  const onRecord = recordIn(real ?? home, bot);
+  const onRecord = recordIn(real ?? home, bot, book);
   // A conversation the harness marks as a subagent's was never a session's, so a
   // note that holds one is not a loose end for it (#287). The note stays as it is.
   const helpers = new Set(onRecord.filter((one) => one.subagent).map((one) => one.id));
@@ -451,16 +502,33 @@ function offTheBook(home, bot, book, onRecord) {
   return [finding('session', bookFile(home), `The harness has conversations on record in ${bot.name}'s folder that the book does not name: ${listed}. The kit's hook may have missed them: a clear it did not record, or a Codex hooks file trusted late. To give one to a session, write it into ${bookFile(home)} under that session as  session: <id>  and run obk up again.`, bot.name)];
 }
 
-/** Every conversation on record in the bot's folder, from every harness any of its sessions runs on, as `obk usage` reads them. */
-function recordIn(home, bot) {
+/** Every conversation on record in the bot's folder, from every harness any of its sessions runs on or a retired one may have, as `obk usage` reads them. */
+function recordIn(home, bot, book) {
   const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
   if (harnesses.size === 0) harnesses.add(bot.harness);
+  // The book does not say which harness a retired session ran on, so any is (#573).
+  if (Array.isArray(book.retired) && book.retired.length > 0) for (const harness of HARNESSES) harnesses.add(harness);
   return [...harnesses]
     .filter((harness) => HARNESSES.includes(harness))
     .flatMap((harness) => transcriptsIn(harness, home));
 }
 
 /** What a directory holds, and nothing at all when there is no directory. */
+/**
+ * The files in the kit's folder of start prompts: in each bot's own folder
+ * there (#534), and flat in the folder itself, where they were before.
+ */
+function promptFilesIn(dir) {
+  return namesIn(dir).flatMap((name) => {
+    const at = path.join(dir, name);
+    try {
+      return statSync(at).isDirectory() ? namesIn(at).map((file) => path.join(at, file)) : [at];
+    } catch {
+      return [];
+    }
+  });
+}
+
 function namesIn(dir) {
   try {
     return readdirSync(dir);

package/src/hooks.js

@@ -17,7 +17,11 @@ import { isDeepStrictEqual } from 'node:util';
 import { leadsOutside } from './bot.js';
 import { ownCli, shellWord } from './launch.js';
 
-/** Where each harness reads a project's hooks, inside the bot home. */
+/**
+ * Where each harness reads a project's hooks, inside the bot home. Pi has no
+ * hook of the kit's: the kit names a Pi session's id itself, on its launch
+ * line (#578).
+ */
 const HOOK_FILE = { claude: '.claude/settings.json', codex: '.codex/hooks.json' };
 
 /** The hooks file `harness` reads in the bot at `home`. */
@@ -58,36 +62,7 @@ export const sentCommand = (bots, bot, cli = ownCli()) =>
   `${shellWord(cli)} session sent --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
 /**
- * Claude Code's third kit hook: at each turn end, it tells the session once
- * about fleet mail the kit sent it that is still unread (#509, ADR 0035).
- * Claude Code only: on Codex a new hook entry puts every session on "Hooks
- * need review", and that waits for #511. It asks Orca only when the kit's hint
- * holds mail for the session, and gives Orca at most ten seconds of its thirty.
- */
-const MAIL_EVENT = 'Stop';
-const MAIL_TIMEOUT = 30;
-
-/** What the mail hook runs, by the kit's own path, as `hookCommand` does. */
-export const mailCommand = (bots, bot, cli = ownCli()) =>
-  `${shellWord(cli)} session mail --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
-
-/**
- * Codex's second kit hook: after each command its shell tool ran, outside
- * Codex's sandbox, it decides the mail nudges a send in that command could not
- * (#350, ADR 0034). Codex only, since only Codex runs its commands where `ps`
- * does not start. It types into another session's tab, which takes Orca a few
- * seconds a nudge, so it is given longer than the others.
- */
-const NUDGE_EVENT = 'PostToolUse';
-const NUDGE_MATCHER = 'Bash';
-const NUDGE_TIMEOUT = 30;
-
-/** What the nudge hook runs, by the kit's own path, as `hookCommand` does. */
-export const nudgeCommand = (bots, bot, cli = ownCli()) =>
-  `${shellWord(cli)} session nudge --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
-
-/**
- * Codex's third kit hook: at each turn end, the session's thread is named after
+ * Codex's second kit hook: at each turn end, the session's thread is named after
  * its bot and session, so its tab says which it is (#480). Async, so the turn
  * ends without waiting on it: it waits for the session to be idle, up to 30 s,
  * then types and confirms. A naming took 73 s live, each character waiting on
@@ -111,6 +86,7 @@ export const nameCommand = (bots, bot, cli = ownCli()) =>
  * the kit's own entry is written (PRD 6.3).
  */
 export function installHook(home, harness, { bots, bot }) {
+  if (HOOK_FILE[harness] === undefined) return;
   const file = path.join(home, HOOK_FILE[harness]);
   const away = outside(home, file);
   if (away !== undefined) throw new Error(away);
@@ -123,7 +99,9 @@ export function installHook(home, harness, { bots, bot }) {
   // longer asks about is taken out, and a hook of the user's beside the kit's
   // stays where they put it.
   const started = withKitHook(settings.hooks, file, mine);
-  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, started) };
+  // The Claude Code mail hook and the Codex nudge hook went with the kit's
+  // typed line (#555), so an entry of either is taken out.
+  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, withoutHooks(started, [KIT_MAIL, KIT_NUDGE])) };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -144,6 +122,7 @@ export function installHook(home, harness, { bots, bot }) {
  * nothing else says so — the book simply stops being true.
  */
 export function hookTrouble(home, harness, { bots, bot }) {
+  if (HOOK_FILE[harness] === undefined) return undefined;
   const file = path.join(home, HOOK_FILE[harness]);
   const stale = `Until it is there, nothing tells the book which conversation this bot's ${harness} sessions are running as, and the book goes stale.`;
 
@@ -171,9 +150,8 @@ export function hookTrouble(home, harness, { bots, bot }) {
     const program = running ?? ownCli();
     wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
     // The harness's other hooks are each judged on their own: the session hook
-    // may be right while the warning after a native message (ADR 0032), the
-    // nudge a Codex sender left (ADR 0034), or the naming of a Codex thread
-    // (#480) is missing.
+    // may be right while the warning after a native message (ADR 0032) or the
+    // naming of a Codex thread (#480) is missing.
     if (isDeepStrictEqual(settings, wanted)) {
       for (const tool of toolHooksOf(harness, bots, bot)) {
         const toolRunning = programIn(settings, tool.pattern);
@@ -267,24 +245,15 @@ function withKitHook(hooks, file, mine) {
 
 /** Each harness's kit hooks beside its session hook, as `toolHookOf` gives each. */
 const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
-  (harness === 'claude' ? ['sent', 'mail'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
+  (harness === 'claude' ? ['sent'] : ['name']).map((kind) => toolHookOf(kind, bots, bot, cli));
 
 /**
  * One of the kit's hooks beside its session hook: Claude Code's after a native
- * `SendMessage` (`sent`, ADR 0032), Codex's after its shell tool (`nudge`,
- * ADR 0034), and Codex's at a turn end (`name`, #480). The entry, where it
- * goes, how the kit knows its own, and what is lost without it.
+ * `SendMessage` (`sent`, ADR 0032), and Codex's at a turn end (`name`, #480).
+ * The entry, where it goes, how the kit knows its own, and what is lost
+ * without it.
  */
 function toolHookOf(kind, bots, bot, cli = ownCli()) {
-  if (kind === 'mail') {
-    return {
-      kind,
-      event: MAIL_EVENT,
-      pattern: KIT_MAIL,
-      mine: { type: 'command', command: mailCommand(bots, bot, cli), timeout: MAIL_TIMEOUT },
-      missing: 'a Claude session busy when fleet mail came is never told about it at the end of its turn, and nothing is typed into its tab either (#509)',
-    };
-  }
   if (kind === 'name') {
     return {
       kind,
@@ -294,26 +263,34 @@ function toolHookOf(kind, bots, bot, cli = ownCli()) {
       missing: "a Codex session's thread is never named after its bot and session, and its tab shows a topic Codex made up instead (#480)",
     };
   }
-  if (kind === 'sent') {
-    return {
-      kind,
-      event: SENT_EVENT,
-      matcher: SENT_MATCHER,
-      pattern: KIT_SENT,
-      mine: { type: 'command', command: sentCommand(bots, bot, cli), timeout: TIMEOUT },
-      missing: 'a session is never warned when its native message goes outside this bots folder (ADR 0032)',
-    };
-  }
   return {
     kind,
-    event: NUDGE_EVENT,
-    matcher: NUDGE_MATCHER,
-    pattern: KIT_NUDGE,
-    mine: { type: 'command', command: nudgeCommand(bots, bot, cli), timeout: NUDGE_TIMEOUT },
-    missing: "mail a session sends from inside Codex's sandbox never tells a receiver the kit could not see from there, such as a Claude session busy with a command (ADR 0034)",
+    event: SENT_EVENT,
+    matcher: SENT_MATCHER,
+    pattern: KIT_SENT,
+    mine: { type: 'command', command: sentCommand(bots, bot, cli), timeout: TIMEOUT },
+    missing: 'a session is never warned when its native message goes outside this bots folder (ADR 0032)',
   };
 }
 
+/**
+ * The hooks without the kit's entries of these patterns, the hooks it no
+ * longer writes, and everything else as the user left it. A group the kit
+ * empties goes, and an event left with no groups goes with it.
+ */
+function withoutHooks(hooks, patterns) {
+  return Object.fromEntries(Object.entries(hooks).flatMap(([event, groups]) => {
+    if (!Array.isArray(groups)) return [[event, groups]];
+    const kept = groups.flatMap((group) => {
+      if (!Array.isArray(group?.hooks)) return [group];
+      const entries = group.hooks.filter((hook) => patterns.every((pattern) => programOf(hook?.command, pattern) === undefined));
+      if (entries.length === group.hooks.length) return [group];
+      return entries.length === 0 ? [] : [{ ...group, hooks: entries }];
+    });
+    return kept.length === 0 ? [] : [[event, kept]];
+  }));
+}
+
 /**
  * The hooks with the kit's tool hook in a group of its event matched to its
  * tool (or with no matcher, for one that has none), and everything else as the
@@ -380,6 +357,7 @@ const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
 const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
 const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+/** The hooks the kit wrote before #555, and takes out. */
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_MAIL = new RegExp(String.raw`^(${WORD}) session mail --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
@@ -390,7 +368,7 @@ const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --
  * (#506). One that runs some other program, even another `obk`, is not.
  */
 export const runsThisKit = (hook, cli = ownCli()) =>
-  hook?.type === 'command' && [KIT_HOOK, KIT_SENT, KIT_NUDGE, KIT_NAME].some((pattern) => programOf(hook.command, pattern) === cli);
+  hook?.type === 'command' && [KIT_HOOK, KIT_SENT, KIT_NAME].some((pattern) => programOf(hook.command, pattern) === cli);
 
 /** The program a bot made before the kit named itself by path runs. */
 const BARE = 'obk';