@assuredloop/orca-bot-kit 0.1.0 → 0.3.0

package/src/conversations.js

@@ -0,0 +1,150 @@
+// What the harness itself knows, for when the book's own record is incomplete.
+//
+// The kit's hook is the way a session's id reaches the book, and it can miss:
+// on Codex a hooks file must be trusted before any hook runs, and trusting it
+// does not replay the event it missed (tech notes, section 3). A conversation
+// 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
+// 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 { readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+/** Claude Code's transcripts: one folder per working directory, one file per session. */
+const claudeDir = (home) => path.join(homedir(), '.claude', 'projects', slug(home));
+
+/** 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, '-');
+
+/** Codex's rollouts: a file per conversation, filed by the day it started. */
+const codexDir = () => path.join(homedir(), '.codex', 'sessions');
+
+/**
+ * Every conversation the harness has on record for this bot home, oldest first,
+ * and when each began. `since` leaves out anything older than the moment the kit
+ * started a harness in the tab: what came before belongs to an earlier run.
+ *
+ * An unreadable record says nothing rather than throwing: the caller's answer is
+ * then that it does not know, which is the honest one.
+ */
+export function conversationsIn(harness, home, since) {
+  return transcriptsIn(harness, home, since).map((one) => ({ id: one.id, at: one.at }));
+}
+
+/**
+ * The same conversations, each with the file the harness keeps it in, for a
+ * caller that has to read what is inside one rather than only know it is there.
+ */
+export function transcriptsIn(harness, home, since) {
+  const from = since === undefined ? 0 : Date.parse(since);
+  const found = harness === 'claude' ? claudeConversations(home) : codexConversations(home, from);
+  return found
+    .filter((one) => Number.isNaN(from) || one.at >= from)
+    .sort((left, right) => left.at - right.at)
+    .map((one) => ({ id: one.id, at: new Date(one.at).toISOString(), file: one.file }));
+}
+
+function claudeConversations(home) {
+  return files(claudeDir(home))
+    .filter((name) => name.endsWith('.jsonl'))
+    .flatMap((name) => {
+      const file = path.join(claudeDir(home), name);
+      // What the transcript says about itself first, and the file's own age only
+      // where it says nothing: a line of its own is the harness talking, and a
+      // file's times can be set by anything that touches it.
+      const at = said(file) ?? startedAt(file);
+      return at === undefined ? [] : [{ id: name.slice(0, -'.jsonl'.length), at, file }];
+    });
+}
+
+/** When a transcript's first line says the conversation was, if it says at all. */
+function said(file) {
+  try {
+    const first = readFileSync(file, 'utf8').split('\n', 1)[0];
+    const when = Date.parse(JSON.parse(first)?.timestamp ?? '');
+    return Number.isNaN(when) ? undefined : when;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Codex files its rollouts by day, and each one says which folder it was in.
+ * The folders are walked rather than guessed at: a conversation from today may
+ * sit under yesterday's date in another time zone.
+ */
+function codexConversations(home, from) {
+  return rollouts(codexDir())
+    // A rollout is written while its conversation runs, so one last touched
+    // before the kit started this harness cannot be its conversation. Asked of
+    // the file system, which is cheap, before the file is opened, which is not:
+    // a machine with years of conversations answers this in one walk.
+    .filter((file) => Number.isNaN(from) || (startedAt(file) ?? 0) >= from || lastTouched(file) >= from)
+    .flatMap((file) => {
+      const meta = sessionMeta(file);
+      return meta?.cwd === home && typeof meta.id === 'string'
+        ? [{ id: meta.id, at: Date.parse(meta.timestamp ?? '') || startedAt(file) || 0, file }]
+        : [];
+    });
+}
+
+/** Every rollout file under Codex's sessions folder, however deep it files them. */
+function rollouts(dir, depth = 0) {
+  if (depth > 4) return [];
+  return files(dir).flatMap((name) => {
+    const full = path.join(dir, name);
+    if (name.endsWith('.jsonl')) return [full];
+    return isDir(full) ? rollouts(full, depth + 1) : [];
+  });
+}
+
+/** A rollout's first line says what the conversation is: its id, folder and time. */
+function sessionMeta(file) {
+  try {
+    const first = readFileSync(file, 'utf8').split('\n', 1)[0];
+    const parsed = JSON.parse(first);
+    return parsed?.type === 'session_meta' ? parsed.payload : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** When a file was last written, for leaving out what is plainly too old. */
+function lastTouched(file) {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/** When a conversation's own file came into being, as the file system has it. */
+function startedAt(file) {
+  try {
+    const stat = statSync(file);
+    return stat.birthtimeMs > 0 ? stat.birthtimeMs : stat.mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+function files(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    // No folder means no conversations on record, which is an answer.
+    return [];
+  }
+}
+
+const isDir = (full) => {
+  try {
+    return statSync(full).isDirectory();
+  } catch {
+    return false;
+  }
+};

package/src/groom.js

@@ -0,0 +1,159 @@
+// 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 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.
+//
+// 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.
+
+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 { BOT_FATHER } from './up.js';
+
+/** What the kit calls its own grooming automation. */
+const NAME = 'obk 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}.`;
+
+/**
+ * Say what the grooming is, and make it so when asked.
+ * Returns `{ exists }`, and `{ exists, enabled, at, id }` once there is one.
+ *
+ * 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.
+ */
+export function grooming(bots, { at, on } = {}) {
+  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.
+  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.`);
+  }
+  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.`);
+  }
+
+  // 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();
+  }
+}
+
+/** 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]);
+  }
+
+  if (on !== undefined && mine !== undefined) {
+    orca(['automations', 'edit', '--id', mine.id, on ? '--enabled' : '--disabled']);
+  }
+
+  // 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 kit's own grooming automation for this Bot Father, if there is one.
+ *
+ * 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.
+ */
+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.`);
+  }
+  return found[0];
+}
+
+/** A bot home as the file system knows it, or as it was given when it is not there. */
+function realHome(home) {
+  try {
+    return realpathSync(home);
+  } catch {
+    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

@@ -0,0 +1,309 @@
+// `obk health`: what is wrong with the setup, said in facts.
+//
+// PRD 4.12 names what it has to find — configuration that will not work, a
+// skill that is not where its list says, a session the book knows that Orca
+// does not, and leftovers no book owns — and PRD 6.5 adds Orca's own default
+// launch arguments on top of them.
+//
+// Two rules hold it together.
+//
+// It reports and never repairs. The kit's code reports facts; judging them and
+// proposing a fix is the skill's job (PRD 6.8). So nothing here writes: no
+// AGENTS.md built, no skill linked, no book touched, and of Orca it asks only
+// the things that tell it something. Every check is the read-only half of a
+// command that does the writing, and lives beside that command rather than
+// here, so the two cannot drift apart.
+//
+// And a finding has to be worth reading. Each one says which kind of trouble it
+// 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 path from 'node:path';
+
+import { bookFile, readBook, tabIdsIn } from './book.js';
+import { botDir, botNames, botsDir, readBot } from './bot.js';
+import { transcriptsIn } from './conversations.js';
+import { hookTrouble } from './hooks.js';
+import { bypassFlags, harnessOf, HARNESSES, sessionTrouble } from './launch.js';
+import { orcaDefaultArgs, projects, tabs } from './orca.js';
+import { agentsTrouble } from './rules.js';
+import { skillsTrouble } from './skills.js';
+import { readSources, sourcesDir } from './sources.js';
+import { BOT_FATHER, botsNamed, promptPath } from './up.js';
+
+/**
+ * Everything wrong with the setup at `bots`, in one list: what Orca's own
+ * settings do to every session, what is lying about that no book owns, and then
+ * each bot in name order. `bot` narrows the per-bot checks to one; what the
+ * whole fleet lives under is reported whichever bot was named.
+ */
+export function checkHealth(bots, { bot: onlyBot } = {}) {
+  const names = botsNamed(bots, onlyBot);
+  const setups = projects();
+
+  const found = [...orcaSettingFindings(), ...leftInOrca(bots, setups), ...leftBeside(bots)];
+  for (const name of names) found.push(...aboutBot(bots, name, setups));
+  return found;
+}
+
+/** One finding, as the report and the `--json` answer carry it. */
+const finding = (kind, where, says, bot) => ({ kind, ...(bot === undefined ? {} : { bot }), where, says });
+
+/**
+ * What Orca adds to an agent of its own accord, when it is a permission bypass.
+ *
+ * Every session Orca relaunches or resumes takes these, whatever the kit asked
+ * for, so this is said every time it is true (PRD 6.5) — and a setting the kit
+ * could not read is said too, because silence here would be read as a clean
+ * bill of health.
+ *
+ * Exported because the PRD asks for it in two places: here, and in the setup
+ * that makes a fleet, which is where the user is still standing when they can
+ * put it right.
+ */
+export function orcaSettingFindings() {
+  const { dir, profiles } = orcaDefaultArgs();
+  if (profiles.length === 0) return [unreadableSettings(dir)];
+
+  return profiles.flatMap(({ file, args }) => {
+    if (args === undefined) return [unreadableSettings(file)];
+
+    return HARNESSES.flatMap((harness) => {
+      const flags = bypassFlags(harness);
+      // A missing entry is Orca's own default, and Orca's own default is the
+      // bypass (tech notes, section 1), so it is read as one.
+      const recorded = typeof args[harness] === 'string' ? args[harness] : undefined;
+      const effective = recorded ?? flags.join(' ');
+      const bypass = flags.filter((flag) => carries(effective, flag));
+      if (bypass.length === 0) return [];
+
+      const how = recorded === undefined
+        ? `${file} records no default launch arguments for ${harness}, and Orca's own default for it is ${bypass.join(' ')}.`
+        : `${file} gives ${harness} the default launch arguments ${recorded.trim()}.`;
+      return [finding('orca', file, `${how} Every ${harness} session Orca launches, relaunches or resumes runs with a permission bypass, whatever approval level the kit asked for, so a session meant to ask first will not. Change it to something safer in Orca's settings; the kit does not touch that setting itself.`)];
+    });
+  });
+}
+
+const unreadableSettings = (where) => finding(
+  'orca',
+  where,
+  `The kit could not read Orca's own settings at ${where}, so it cannot say whether Orca adds default launch arguments of its own. When those carry a permission bypass, every session Orca launches, relaunches or resumes runs in that mode whatever approval level the kit asked for.`,
+);
+
+/** Whether a line of arguments carries `flag` as a word of its own. */
+const carries = (args, flag) =>
+  new RegExp(`(^|\\s)${flag.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\s|$)`).test(args);
+
+/**
+ * Orca projects inside the bots folder that are no longer a bot: the bot was
+ * moved or deleted and its Orca project stayed behind. Anything outside the
+ * bots folder is the user's own work and is not looked at.
+ */
+function leftInOrca(bots, setups) {
+  const dir = botsDir(bots);
+  const dirs = [...new Set([dir, realpathOf(dir)].filter((one) => one !== undefined))];
+
+  return setups.flatMap((setup) => {
+    const under = dirs.find((one) => setup.path.startsWith(`${one}${path.sep}`));
+    if (under === undefined) return [];
+
+    const name = path.relative(under, setup.path);
+    if (!name.includes(path.sep) && existsSync(path.join(dir, name, 'bot.yaml'))) return [];
+
+    return [finding('leftover', setup.path, `Orca has a project for ${setup.path}, which is inside your bots folder, and there is no bot there. Its Orca project is ${setup.id}. Close its tabs before the project goes: a project taken away before its tabs leaves tabs that nothing can close from the command line.`)];
+  });
+}
+
+/**
+ * What the kit keeps beside the bots folder that nothing answers to any more:
+ * a start prompt written for a session that has gone, and a clone of a skills
+ * source `skills.yaml` no longer lists.
+ */
+function leftBeside(bots) {
+  const found = [];
+
+  // Every start-prompt file the sessions of every bot would be given. A bot the
+  // kit cannot read has sessions it cannot name, and a file called a leftover
+  // on that footing might be a live session's duty, so the check waits until
+  // the bot.yaml beside it is settled.
+  const owned = new Set();
+  let known = true;
+  for (const name of botNames(bots)) {
+    try {
+      for (const session of readBot(botDir(bots, name), name).sessions) {
+        owned.add(promptPath(bots, name, session.name));
+      }
+    } catch {
+      known = false;
+    }
+  }
+
+  if (known) {
+    for (const file of namesIn(`${bots}.prompts`)) {
+      const at = path.join(`${bots}.prompts`, file);
+      if (owned.has(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.`));
+    }
+  }
+
+  const file = path.join(bots, 'skills.yaml');
+  let listed;
+  try {
+    listed = new Set(readSources(file).map((source) => source.name));
+  } catch (error) {
+    return [...found, finding('config', file, error.message)];
+  }
+
+  for (const name of namesIn(sourcesDir(bots))) {
+    if (listed.has(name)) continue;
+    const at = path.join(sourcesDir(bots), name);
+    found.push(finding('leftover', at, `${at} is a clone of a skills source, and ${file} lists no source called ${name}. Nothing links skills out of it now.`));
+  }
+
+  return found;
+}
+
+/** Everything wrong with one bot. */
+function aboutBot(bots, name, setups) {
+  const home = botDir(bots, name);
+
+  let bot;
+  try {
+    bot = readBot(home, name);
+  } catch (error) {
+    // Nothing else about this bot can be asked: what it carries, what its
+    // sessions are and which harness they run on are all in the file that
+    // cannot be read. The other bots are reported as usual.
+    return [finding('config', path.join(home, 'bot.yaml'), error.message, name)];
+  }
+
+  const said = (kind) => ({ where, says }) => finding(kind, where, says, name);
+  return [
+    ...sessionSettings(home, bot).map(said('config')),
+    ...agentsTrouble(bots, home, bot).map(said('config')),
+    ...hooksOf(bots, home, bot).map(said('config')),
+    ...skillsTrouble(bots, home, bot).map(said('skill')),
+    ...inOrca(home, bot, setups),
+  ];
+}
+
+/** 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');
+  return bot.sessions.flatMap((session) => {
+    const trouble = sessionTrouble(session, harnessOf(session, bot.harness), home);
+    return trouble === undefined
+      ? []
+      : [{ where: file, says: `${file}: ${trouble} obk up will not start ${bot.name} until that is settled.` }];
+  });
+}
+
+/** The kit's own hook, in the file of every harness this bot's sessions run on. */
+const hooksOf = (bots, home, bot) => [...new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)))]
+  .filter((harness) => HARNESSES.includes(harness))
+  .map((harness) => hookTrouble(home, harness, { bots, bot: bot.name }))
+  .filter((trouble) => trouble !== undefined);
+
+/**
+ * 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
+ * bot's project that the book does not name.
+ */
+function inOrca(home, bot, setups) {
+  // The book is read where it is read, and a book nothing can parse is a
+  // finding like any other: it says which tab each session is in and which
+  // conversation it is running, so without it nothing else here can be asked —
+  // but the findings already made, and the bots still to come, are none of its
+  // business.
+  let book;
+  try {
+    book = readBook(home);
+  } catch (error) {
+    return [finding('config', bookFile(home), `${bookFile(home)} cannot be read (${error.message}), and it is where the kit keeps this bot's sessions: which Orca tab each one is in and which conversation it is running. Until it is readable the kit cannot say either. Fix it, or move it aside and let obk up write a new one.`, bot.name)];
+  }
+
+  const real = realpathOf(home);
+  const project = setups.find((setup) => setup.path === real || setup.path === home);
+  // Orca refuses to list the tabs of a folder it has no project for, rather
+  // than answering with none (tech notes, section 1), so it is asked only when
+  // there is one.
+  const live = project === undefined ? [] : tabs(project.path);
+  const there = new Set(live.map((tab) => tab.tabId));
+
+  // A paused bot or session was closed on purpose, and its tab being gone is
+  // what paused means rather than something lost.
+  const closed = new Set(bot.sessions.filter((session) => bot.paused === true || session.paused === true).map((session) => session.name));
+
+  const found = [];
+  for (const [name, entry] of Object.entries(book.sessions)) {
+    if (typeof entry?.tab === 'string' && !there.has(entry.tab) && !closed.has(name)) {
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${name} is in the book with tab ${entry.tab}, and Orca has no tab of that id: the tab was closed, or the machine was restarted. The conversation is in the book, and obk up opens a tab and brings it back.`, bot.name));
+    }
+
+    const unclaimed = Array.isArray(entry?.unclaimed) ? entry.unclaimed : [];
+    if (unclaimed.length > 0) {
+      found.push(finding('leftover', bookFile(home), `The book notes conversations under ${bot.name}'s session ${name} that no session of this bot claims: ${unclaimed.join(', ')}. They ran in this bot's folder, and the kit will not say whose they were. To give one back, write it into ${bookFile(home)} under ${name} as  session: <id>  and run obk up again.`, bot.name));
+    }
+  }
+
+  found.push(...offTheBook(real ?? home, bot, book));
+
+  // A tab outside the book is somebody else's, and in Bot Father's project it
+  // is the ops tab: the one tab the kit deliberately keeps no record of, so it
+  // cannot be a leftover (PRD 6.2).
+  if (bot.name !== BOT_FATHER) {
+    const known = tabIdsIn(book);
+    for (const tab of live.filter((one) => !known.has(one.tabId))) {
+      found.push(finding('leftover', tab.tabId, `Orca has a tab in ${bot.name}'s Orca project, ${tab.tabId}, that the book does not name, so it is none of this bot's sessions. The kit did not open it and does not touch it.`, bot.name));
+    }
+  }
+
+  return found;
+}
+
+/**
+ * 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
+ * harness's own record set beside it (ADR 0012).
+ */
+function offTheBook(home, bot, book) {
+  const named = new Set();
+  for (const entry of Object.values(book.sessions)) {
+    if (typeof entry?.session === 'string') named.add(entry.session);
+    for (const was of Array.isArray(entry?.history) ? entry.history : []) named.add(was?.session);
+    for (const id of Array.isArray(entry?.unclaimed) ? entry.unclaimed : []) named.add(id);
+  }
+
+  // Every harness any of its sessions runs on, as `obk usage` reads them.
+  const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
+  if (harnesses.size === 0) harnesses.add(bot.harness);
+  const stray = [...harnesses]
+    .filter((harness) => HARNESSES.includes(harness))
+    .flatMap((harness) => transcriptsIn(harness, home))
+    .filter((one) => !named.has(one.id));
+  if (stray.length === 0) return [];
+
+  const listed = stray.map((one) => `${one.id} (begun ${one.at})`).join(', ');
+  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)];
+}
+
+/** What a directory holds, and nothing at all when there is no directory. */
+function namesIn(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** Where a path really leads, or undefined when it leads nowhere. */
+function realpathOf(at) {
+  try {
+    return realpathSync(at);
+  } catch {
+    return undefined;
+  }
+}