@assuredloop/orca-bot-kit 0.7.0 → 0.8.0

package/README.md

@@ -431,6 +431,31 @@ retiring it again finishes the job. Bot
 Father itself, and its management session `daily`, are never paused or
 retired; its other sessions are like any bot's.
 
+## Daily grooming
+
+Grooming is an optional daily pass over the fleet: what each bot did, what it
+cost, and what to improve, sent as one short report to Bot Father's management
+session. It runs in a session of Bot Father's called `grooming`, on Claude
+Code's own scheduler, at the model and effort you give that session.
+
+```sh
+obk session add --bots /path/to/my-bots --bot bot-father --name grooming --model sonnet --effort medium
+obk up --bots /path/to/my-bots --bot bot-father
+obk groom --bots /path/to/my-bots --now           # run it once, by hand, and read it
+obk groom --bots /path/to/my-bots --on --at 04:00 # then schedule it
+obk groom --bots /path/to/my-bots                 # what is scheduled
+```
+
+It starts off, and Bot Father asks you before it turns it on, because it spends
+tokens every day. It fires only while its tab is open in Orca and Claude Code is
+idle there, up to half an hour after its time, and a day it misses is not made
+up. Each run renews its own schedule, which Claude Code would otherwise end
+after a week, and `--on --at` puts it back if it lapses. A `/clear` in its tab
+leaves it running until the session is next restarted; after that, `--on --at`
+puts it back.
+`obk groom --compact` compacts its conversation between runs. Grooming on Codex
+comes later: on a Codex Bot Father, add the session with `--harness claude`.
+
 ## When something is wrong
 
 ```sh

package/package.json

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

package/skills/obk-grooming/NOTICE.md

@@ -50,11 +50,13 @@ profile notes and that any bot may read them; and the routing, where something
 the kit does wrong is filed as an issue in one step and something a bot does
 wrong goes back to that bot's session as feedback.
 
-That grooming is the automation's own session rather than a tab in the book,
-and that what it must remember therefore lives in files, follows from a fact
-measured for this slice: an Orca automation cannot reuse a session it did not
-start, so it cannot be pointed at a tab the kit made. It is written down in
-the tech notes.
+Grooming runs in a session in the book, on Claude Code's own scheduler,
+because the owner decided on 2026-09-24 (#223) that scheduled work does not use
+an Orca automation: an automation cannot carry a model or an effort of its
+own. Its runs share one long conversation, which the owner accepted in the
+same decision ("just do /compact when needed, add to the skill"). What a run
+must remember still lives in files, because a compacted conversation keeps
+only a summary. The facts about Claude Code's scheduler are in the tech notes.
 
 ## Ideas taken from material with no licence
 
@@ -109,3 +111,17 @@ Sources and licences in full: [LICENSES.md](LICENSES.md).
   expected). The load limit and where the memory lives are the tech notes'
   facts, verified live on Claude Code 2.1.280; Codex's store is the user's and
   is left alone.
+
+## What moving to Claude Code's scheduler changed (#237)
+
+- Where it remembers: the runs share one conversation now, so the files are
+  kept because a compact leaves a summary and a `/clear` leaves nothing, rather
+  than because each run starts fresh.
+- Turning it on: a `grooming` session in the book with its own model and
+  effort, a run by hand with `obk groom --now`, then `--on --at` after the yes.
+  That it fires only while its tab is up, the week-long limit each run renews,
+  and what a `/clear` does are Claude Code's documented behaviour, in the tech
+  notes.
+- Compacting is new, from the owner's decision on #223. Who types `/compact`
+  (the management session, through the kit) is the architect's reading of it on
+  #237.

package/skills/obk-grooming/SKILL.md

@@ -53,11 +53,13 @@ say what was and was not looked at rather than taking the report's word for it.
 
 ## Where it remembers
 
-Each run is a fresh conversation, so everything it knows from the last one is
-in files in the bots folder: the window and the open findings in a `grooming/`
-folder unless the project already keeps them elsewhere, and the profile notes
-in `profiles/`, where the fleet's rules tell every bot to look. Say at the top
-of each what it is. A run that cannot find
+The runs share one long conversation, and a compacted conversation keeps a
+summary of the earlier runs, not their detail; a `/clear` keeps nothing. So
+everything a run needs from the last one is in files in the bots folder: the
+window and the open findings in a `grooming/` folder unless the project already
+keeps them elsewhere, and the profile notes in `profiles/`, where the fleet's
+rules tell every bot to look. Say at the top of each what it is. Trust the
+files over what the conversation seems to remember. A run that cannot find
 them says so and reads less, not everything.
 
 The open findings are what stops the same thing being reported every day:
@@ -213,11 +215,45 @@ places and sending one to the other loses it.
 
 ## Turning it on
 
-Do not schedule a pass nobody has watched. Run it by hand once, read what it
-produced, and fix the run rather than the report. So `obk groom --at <HH:MM>`
-creates it off, and `obk groom --on` turns it on after one explicit yes from
-the user who has read a run. Tell them what it will cost them each day before
-they say it. Make it through that command rather than by hand, so there is only
-ever one.
+The pass runs in a session of Bot Father's own, `grooming`, on Claude Code's
+own scheduler. Add it like any session, with the model and effort it is to run
+at: `obk session add --bots <folder> --bot bot-father --name grooming --model
+<m> --effort <e>`, with `--harness claude` where Bot Father runs on Codex, then
+`obk up`. Its launch line carries them, so they are what every run uses.
+
+Do not schedule a pass nobody has watched. `obk groom --now` runs it once in its
+tab; read what it produced, and fix the run rather than the report. Then, after
+one explicit yes from the user who has read a run, `obk groom --on --at <HH:MM>`
+schedules it. Tell them what it will cost them each day before they say it.
+Schedule it through that command rather than by hand, so there is one job and
+the kit can see it. `obk groom` says what is scheduled, and says so plainly
+when there is none or more than one.
+
+It fires only while its tab is open in Orca and Claude Code is idle in it, up to
+half an hour after its time, and a day it misses is not made up. Tell the user
+that before they rely on it. Claude Code ends a recurring job a week after it
+was made, so each run renews its own; a week with no run ends it, and then
+`obk groom --on --at <HH:MM>` puts back what the user agreed to. A `/clear` in
+its tab leaves it running: the job belongs to the running Claude Code, not to
+one conversation. It keeps running until the session is next restarted or
+Orca restores its tab: a resume brings back only the jobs of the conversation
+it resumes, so after a `/clear` and then a restart the job is gone. `obk groom`
+says so, and `--on --at` puts it back.
+
+## Compacting
+
+The runs share one conversation and each adds to it, so each run carries more
+than the last and costs more. A compact shrinks it to a summary. The run cannot
+do it: a scheduled run cannot type a built-in command, and a session cannot
+compact itself. So the report says when one is due, and the management session
+does it between runs with `obk groom --compact`.
+
+One is due when the run's calls carry about half the model's context window.
+`obk usage --bots <folder> --bot bot-father --session grooming --since <this
+run's start>` gives the run's calls and tokens: input, cache read and cache
+write together, divided by the calls, is roughly what each call carried.
+Claude Code also compacts on its own near the limit. That is the backstop, not
+the plan: it comes when the conversation is full, most likely in the middle of
+a run.
 
 Sources and licences: [NOTICE.md](NOTICE.md).

package/src/book.js

@@ -122,9 +122,7 @@ export async function updateBook(home, change) {
 /**
  * The right to change what belongs to one bot, held from before it is read until
  * after it is written — a SQLite write transaction on a file of its own beside
- * the book. The book is what it usually guards, and `obk groom` takes it too,
- * for the one thing Orca will not do for us: look for an automation and make one
- * if it is missing, without a second run doing the same between the two.
+ * the book.
  *
  * SQLite is in Node itself and does this with the operating system's own file
  * locks. That matters for one reason: the lock belongs to the process, so it is
@@ -142,7 +140,7 @@ export async function updateBook(home, change) {
  * The lock file holds no data — it is opened, locked and closed — so it stays
  * empty and leaves no journal beside it.
  */
-export function takeLock(home) {
+function takeLock(home) {
   const file = lockFile(home);
   mkdirSync(path.dirname(file), { recursive: true });
 

package/src/cli.js

@@ -13,7 +13,7 @@ import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
 import { addSession, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
-import { grooming } from './groom.js';
+import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
@@ -164,13 +164,18 @@ Usage:
                             with its settings, its tab and the conversation it
                             is in. It reads your files and reports them as they
                             stand; what to make of them is yours.
-  obk groom --bots <path> [--at <HH:MM>] [--on | --off]
-                            Say whether the daily grooming exists, when it runs
-                            and whether it is on, and set it up or change it
-                            when you ask. --at makes one, in Bot Father's Orca
-                            project. It is made off, because it spends tokens
-                            every day: run it by hand once, read what it gives
-                            you, then --on.
+  obk groom --bots <path> [--on [--at <HH:MM>] | --at <HH:MM> | --off | --now | --compact]
+                            Say what the daily grooming is: Bot Father's session
+                            grooming, and the job scheduled in it on Claude
+                            Code's own scheduler. Add that session like any
+                            other, with the model and effort each run is to use.
+                            --now asks it to run the grooming once. --on --at
+                            asks it to schedule it daily, and each run renews
+                            it; it starts off, because it spends tokens every
+                            day, so run it by hand once and read it first. --at
+                            moves it, --off unschedules it, and --compact
+                            compacts its conversation between runs. It fires
+                            only while its tab is up in Orca.
   obk usage --bots <path> [--bot <bot>] [--session <name>] [--since <time>] [--until <time>]
                             Say what your sessions have used: the conversations
                             each one had, their calls and tokens, the models and
@@ -281,6 +286,8 @@ async function run(argv) {
       at: { type: 'string' },
       on: { type: 'boolean' },
       off: { type: 'boolean' },
+      now: { type: 'boolean' },
+      compact: { type: 'boolean' },
       skill: { type: 'string' },
       repo: { type: 'string' },
       ref: { type: 'string' },
@@ -355,7 +362,7 @@ async function run(argv) {
 /**
  * The bots folder as the file system knows it. A folder reached through a
  * symlink is the same fleet: the harnesses file their transcripts under the real
- * path, Orca records an automation's workspace by it, and what the kit keeps
+ * path, and what the kit keeps
  * beside the folder (the skill sources, the start prompts, the messages) is
  * named after it. Asked by one spelling and then another, a fleet would
  * otherwise have two of each, and a pin set through one is undone through the
@@ -658,11 +665,16 @@ const commands = {
 
   groom(bots, values) {
     refuseWhenOrcaIsDown();
-    if (values.on === true && values.off === true) {
-      throw new Error('groom takes --on or --off, and got both. Say which one you want.');
+    const asks = ['on', 'off', 'now', 'compact'].filter((flag) => values[flag] === true);
+    if (asks.length > 1) {
+      throw new Error(`groom asks for one thing at a time, and got ${asks.map((flag) => `--${flag}`).join(' and ')}. Say which one you want.`);
     }
-    const on = values.on === true ? true : (values.off === true ? false : undefined);
-    const groom = grooming(bots, { at: values.at, on });
+    if (values.at !== undefined && asks.length === 1 && asks[0] !== 'on') {
+      throw new Error(`--at is the time grooming runs at, and goes with --on, not with --${asks[0]}.`);
+    }
+    // --at on its own moves grooming that is on to another time.
+    const ask = asks[0] ?? (values.at === undefined ? undefined : 'move');
+    const groom = grooming(bots, { at: values.at, ask });
     return { answer: { bots, groom }, lines: groomLines(groom, bots) };
   },
 
@@ -1023,26 +1035,81 @@ function conversationLine(one) {
 }
 
 /**
- * What there is to say about the daily grooming: whether it exists, when it
- * runs, and whether it is on. A grooming that is off is not a fault, so this
- * says what is there and what the next step would be rather than warning.
+ * What there is to say about the daily grooming: the session it runs in, the
+ * jobs scheduled there, and what this run asked of it. Grooming that is off is
+ * not a fault, so this says what is there and what the next step would be;
+ * no job where one was expected, or more than one, is said plainly, because
+ * either means the fleet is groomed a different number of times a day than
+ * anyone decided.
  */
-function groomLines(groom, bots) {
-  if (!groom.exists) {
+function groomLines({ session, jobs, asked }, bots) {
+  const head = 'groom'.padEnd(9);
+  const more = ' '.repeat(11);
+  const said = asked === null ? [] : [ASKED[asked]];
+
+  if (session === null) {
+    return [
+      ...said,
+      `${head}  off: Bot Father has no session called grooming, which is where it runs`,
+      `${more}It runs in that session, on Claude Code's own scheduler. Give the session`,
+      `${more}--model and --effort for what each run is to use.`,
+      `Add it:    ${addCommand(bots)}`,
+      `Then:      ${upCommand(bots)}`,
+    ];
+  }
+  if (session.harness !== 'claude') {
     return [
-      `${'groom'.padEnd(9)}  there is no daily grooming yet`,
-      `Make one:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --at 04:00`,
+      ...said,
+      `${head}  off: Bot Father's grooming session runs on ${session.harness}, and grooming runs`,
+      `${more}on Claude Code's own scheduler, so it has to be a Claude Code session: retire`,
+      `${more}it and add it again with --harness claude.`,
     ];
   }
 
+  const lines = [...said];
+  if (!session.up) {
+    lines.push(`${head}  Bot Father's grooming session is not up, so nothing fires`);
+    lines.push(`Bring it up:  ${upCommand(bots)}`);
+  }
+  if (asked === null) lines.push(...jobLines(jobs, bots, session.up ? head : more));
+  lines.push(`${more}It fires only while its tab is up in Orca and Claude Code is idle there, up to`);
+  lines.push(`${more}half an hour after its time, and a run it misses is not made up.`);
+  return lines;
+}
+
+/** What is scheduled in the grooming session's conversation. */
+function jobLines(jobs, bots, head) {
+  const more = ' '.repeat(11);
+  if (jobs.length === 0) {
+    return [
+      `${head}  off: its conversation has no grooming job`,
+      `${more}It spends tokens every day. Run it by hand first:  ${groomCommand(bots)} --now`,
+      `Turn it on, once the user has read a run and said yes:  ${groomCommand(bots)} --on --at 04:00`,
+    ];
+  }
+  if (jobs.length === 1) {
+    const [job] = jobs;
+    return [
+      `${head}  on, daily at ${job.at ?? job.cron}  job ${job.id}`,
+      `${more}Each run renews it; with no run, Claude Code ends it at ${job.expires}.`,
+      `Turn it off:  ${groomCommand(bots)} --off`,
+    ];
+  }
+  const times = [...new Set(jobs.map((job) => job.at))];
   return [
-    `${'groom'.padEnd(9)}  daily at ${groom.at}  ${groom.enabled ? 'on' : 'off'}`,
-    groom.enabled
-      ? `It runs every day at ${groom.at} and spends tokens each time. Turn it off with:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --off`
-      : `It is not running yet. Try it by hand, read what it gives you, then:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --on`,
+    `${head}  ${jobs.length} grooming jobs, so the fleet is groomed ${jobs.length} times a day: ${jobs.map((job) => `${job.id} at ${job.at ?? job.cron}`).join(', ')}`,
+    `Back to one:  ${groomCommand(bots)} --on${times.length === 1 && times[0] !== undefined ? '' : ' --at <HH:MM>'}`,
   ];
 }
 
+/** What each ask typed into the grooming tab, as the line that says so. */
+const ASKED = {
+  on: `${'asked'.padEnd(9)}  the grooming session to schedule the grooming, in a line typed into its tab. It is listed once the session has done it.`,
+  off: `${'asked'.padEnd(9)}  the grooming session to delete its grooming jobs, in a line typed into its tab.`,
+  now: `${'asked'.padEnd(9)}  the grooming session to run the grooming once, now. Its report goes to Bot Father's management session.`,
+  compact: `${'asked'.padEnd(9)}  the grooming session to compact its conversation: /compact was typed into its tab.`,
+};
+
 /** The settings a session carries, in the order a session is written down. */
 const SHOWN = SESSION_FIELDS.filter((field) => field !== 'name' && field !== 'harness');
 

package/src/conversations.js

@@ -49,10 +49,16 @@ export function conversationsIn(harness, home, since) {
  * is opened, however many conversations the machine has.
  */
 export function hasConversation(harness, home, id) {
-  if (harness === 'claude') return existsSync(path.join(claudeDir(home), `${id}.jsonl`));
+  if (harness === 'claude') return existsSync(claudeTranscript(home, id));
   return rollouts(codexDir()).some((file) => path.basename(file).endsWith(`-${id}.jsonl`));
 }
 
+/**
+ * Where Claude Code keeps the conversation `id` of this bot home, whether or
+ * not it has written it yet.
+ */
+export const claudeTranscript = (home, id) => path.join(claudeDir(home), `${id}.jsonl`);
+
 /**
  * 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,

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/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.
 

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0021). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0023). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -192,7 +192,7 @@ const CLIENT_KILL_MS = 3000;
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
  * changes does, and Orca's CLI does not offer it, so this goes through Orca's
  * own runtime client out of the installed app, run by Orca's binary the way
- * its `bin/orca` runs its CLI (ADR 0021). None of that is Orca's published
+ * its `bin/orca` runs its CLI (ADR 0023). None of that is Orca's published
  * interface, so anything that goes wrong is a quiet false: it never throws and
  * is never tried twice, and the caller prints `RELOAD_LINE` either way.
  */
@@ -262,7 +262,9 @@ export const retitleTab = (handle, title) =>
  * undefined when that cannot be read, with `unreadable` saying why. `answered` (an `ok` from `tui-idle`) and
  * `agent` are Orca's own hints, for a caller that has nothing better.
  * `blockedReason` is Orca saying something on screen wants answering, which is
- * for the caller to deal with, not the kit.
+ * for the caller to deal with, not the kit. `question` is the kit's own look at
+ * the screen, as `questionIn` answers, and `screenUnreadable` says why there
+ * was none.
  */
 export function harnessInTab(handle, timeoutMs) {
   const args = ['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)];
@@ -281,9 +283,59 @@ export function harnessInTab(handle, timeoutMs) {
     blockedReason: answer.result?.wait?.blockedReason,
     agent,
     ...frontOf(shown?.ptyId),
+    ...screenOf(handle),
   };
 }
 
+/** The kit's word for a tab whose screen shows a question of its harness's own (#329). */
+export const QUESTION_ON_SCREEN = 'question-on-screen';
+
+/**
+ * What the tab `handle` renders: `{ question }`, true when it shows a question
+ * of its harness's own, or `{ screenUnreadable: <why> }`. Orca refusing is an
+ * answer that cannot be read, not an error, and so is anything that is not the
+ * rendered screen: accumulated output comes back in fragments (tech notes,
+ * section 1).
+ */
+function screenOf(handle) {
+  let read;
+  try {
+    read = orca(['terminal', 'read', '--terminal', handle, '--screen']).terminal;
+  } catch (error) {
+    return { screenUnreadable: `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 { question: questionIn(read.tail) };
+}
+
+/** A row the harness starts with its selection pointer: `›` on Codex, `❯` on Claude Code. */
+const POINTER_ROW = /^ *[›❯]/;
+
+/** That pointer on a numbered choice, and the column its number starts in. */
+const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
+
+/**
+ * Whether the rows of a rendered screen hold a question of the harness's own.
+ *
+ * Every one seen is a numbered list of choices with the harness's pointer on
+ * one (tech notes, section 1; ADR 0023). The same pointer starts the harness's
+ * input line and its echo of the user's past turns, and the input line is the
+ * lowest of them whenever it is on screen, so only the lowest pointer row is
+ * asked about: a question counts while it stands in the input line's place.
+ * Unnumbered lists do not count. Codex puts a status row right under its input
+ * line, lined up with it, and by its layout that is one.
+ */
+export function questionIn(rows) {
+  const at = rows.findLastIndex((row) => POINTER_ROW.test(row));
+  const pointer = at < 0 ? null : ON_A_CHOICE.exec(rows[at]);
+  if (pointer === null) return false;
+  const column = pointer[1].length;
+  const choice = (row) => typeof row === 'string' && row.slice(0, column).trim() === '' && /^\d+\. /.test(row.slice(column));
+  return choice(rows[at - 1]) || choice(rows[at + 1]);
+}
+
 /**
  * Whether the kit may type a line into `tabId`, the tab the book holds for a
  * session in the Orca project at `home`, and the handle to type into when it
@@ -323,6 +375,13 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
       : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
     return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed` };
   }
+  // Orca's reason does not cover every question: it called Codex's update
+  // offer idle, and a return typed into it took "Update now" (#329). So the
+  // screen is read too, and one that cannot be read is not a reason to type.
+  if (seen.question === true) return { blocked: QUESTION_ON_SCREEN };
+  if (seen.question === undefined) {
+    return { unsure: `the kit could not tell whether a question is waiting on its screen (${seen.screenUnreadable}), so nothing was typed` };
+  }
   return { handle: live.handle, agent: seen.agent };
 }
 
@@ -350,7 +409,7 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  * leading the group in front, or `{ unreadable: <why> }`.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0021).
+ * gives that pid's terminal's foreground process group (ADR 0023).
  * On macOS the pane is `login` with the shell as its child, so the shell is in
  * front when the group is the pane's own or that of a child of a `login` pane.
  * `diagnostics memory` is a diagnostics command and may change, so everything

package/src/up.js

@@ -13,7 +13,7 @@ import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isAddressOf, isShortPrompt, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, tabs, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
 import { TAB_ENV } from './record.js';
 import { buildAgents, rulesStamp } from './rules.js';
 import { linkSkills } from './skills.js';
@@ -440,7 +440,7 @@ async function heldInRecord(home, name, harness, prompt, { launched, running })
 
 /**
  * One look at a tab the kit just typed a launch line into: whether a harness
- * is running there, and what it is waiting on if Orca says.
+ * is running there, and what it is waiting on if Orca or its screen says.
  *
  * The harness is up when something other than the shell holds the tab's
  * terminal, busy or not, or when Orca sees a question on its screen. Orca's
@@ -452,7 +452,10 @@ function lookFor(handle, timeoutMs) {
   const seen = harnessInTab(handle, timeoutMs);
   const running = seen.blockedReason !== undefined
     || (seen.front === undefined ? seen.answered || seen.agent !== undefined : seen.front === 'program');
-  return { running, blockedReason: seen.blockedReason };
+  // A question the kit sees on the screen of a harness that is running, where
+  // Orca named none (#329).
+  const question = running && seen.question === true ? QUESTION_ON_SCREEN : undefined;
+  return { running, blockedReason: seen.blockedReason ?? question };
 }
 
 /**