@assuredloop/orca-bot-kit 0.27.0 → 0.29.0

package/src/cli.js

@@ -12,7 +12,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
-import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, disallowRules, leadsOutside, readBot, SESSION_FIELDS, setRoleCaps, setTempApproval } from './bot.js';
+import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, disallowRules, leadsOutside, readBot, refuseCodexOutside, SESSION_FIELDS, setRoleCaps, setTempApproval } from './bot.js';
 import { COMMANDS } from './commands.js';
 import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
@@ -21,7 +21,7 @@ import { nameSession } from './name.js';
 import { APPROVALS, harnessOf, HARNESSES, ownCli, refuseApprovalArgs, shellWord, workDirOf } from './launch.js';
 import { checkMail, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE, TERMINAL_ENV } from './orca.js';
-import { allowIn, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
+import { allowIn, beyondDefaults, botDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -34,6 +34,7 @@ import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
 import { addSource, fetchSources } from './sources.js';
 import { answerSession, answerTemp, listRoles, makeTemp, optionsLine, retireTemp, trustHooks, trustSessionHooks } from './temp.js';
 import { readUsage } from './usage.js';
+import { parseRun, runBounded } from './run.js';
 import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 
 const USAGE = `obk — Orca Bot Kit.
@@ -43,18 +44,19 @@ Usage:
                             Create your bots folder: a git repo holding your
                             bots' configuration, with Bot Father in it, and
                             open Bot Father in Orca.
-  obk bot create --bots <path> --name <bot> --harness claude|codex
+  obk bot create --bots <path> --name <bot> --harness claude|codex|pi
                  [--charter <text>]
                             Write a new bot in your bots folder. Nothing is
                             opened in Orca until you run obk up.
   obk session add --bots <path> --bot <bot> --name <session>
-                  [--harness claude|codex] [--model <m>] [--effort <e>]
+                  [--harness claude|codex|pi] [--model <m>] [--effort <e>]
                   [--context <c>]
                   [--prompt <text> | --prompt-file <path>] [--work-dir <path>]
                   [--extra-arg=<arg>]
                             Add a session to a bot. Anything left out is the
                             harness's own default; approval is auto, and only
-                            obk permission approval changes it. A long
+                            obk permission approval changes it. A session on
+                            Pi is dangerously-skip, the one level Pi has. A long
                             start prompt lives in a file in the bot home, and
                             --prompt-file names it.
                             A value of your own that starts with a dash is
@@ -87,15 +89,18 @@ Usage:
                             the bot's temporary sessions may be made at. A
                             running session takes it when it next starts.
   obk session change --bots <path> --bot <bot> --session <session>
+                  [--harness claude|codex|pi]
                   [--model <m>] [--effort <e>] [--context <c>]
                   [--prompt <text> | --prompt-file <path>] [--work-dir <path>]
                   [--extra-arg=<arg>]
                             Change a session's settings. What you leave out
                             stays as it is; a setting given empty, --model=,
                             goes back to the harness's own default. A running
-                            session takes the change when it next starts. A
-                            session keeps its harness: to move it, retire it
-                            and add another.
+                            session takes the change when it next starts. On
+                            another harness it starts a new conversation, the
+                            book keeps the old one in its history, and model,
+                            effort and context go back to the new harness's
+                            defaults unless given too.
   obk pause --bots <path> --bot <bot> [--session <name>]
                             Stop a bot, or one of its sessions, for now: close
                             its tabs and have obk up leave it closed. The book
@@ -219,6 +224,8 @@ Usage:
                             folder and named in the message. A pair the
                             harness's own messaging reaches is not carried:
                             the address to write to is answered instead.
+                            In a session's own tab it sends as that session,
+                            and --from may name only that one.
   obk message check --bots <path> [--bot <bot>] [--session <name>] [--peek]
                             Read what is waiting for a session and mark it
                             read. --peek leaves it unread. Run in a session's
@@ -274,7 +281,8 @@ Usage:
                             only while its tab is up in Orca. --run-on codex
                             makes each run a temporary Codex session of the
                             grooming session's, launched with --model, --effort
-                            and --extra-arg, which reports back by the kit's
+                            and --extra-arg, which carries the grooming
+                            session's own prompt, reports back by the kit's
                             mail and is retired.
   obk usage --bots <path> [--bot <bot>] [--session <name>] [--since <time>] [--until <time>]
                             Say what your sessions have used: the conversations
@@ -319,14 +327,28 @@ Usage:
                             For the kit's own launch line, not for typing: run
                             in the session's own tab, it gives the session its
                             mailbox, or binds the one it has, to that tab.
+  obk run --timeout <seconds> -- <command> [<arg> ...]
+                            Run one command with a hard time limit, with no
+                            shell, and exit with its exit code. When the time
+                            runs out, it stops the command and everything it
+                            started (SIGTERM, then SIGKILL after 3 s), says so
+                            on stderr, and exits 124. A command it cannot find
+                            exits 127. A rule can allow it for one command,
+                            such as Bash(obk run --timeout 300 -- go test:*).
+                            It needs no --bots, and takes no --json.
   obk --version             Print the kit's version.
   obk --help                Print this text.
 
 Every command is safe to run again. Most only add what is missing; the ones
 that close a tab or take something away say so above. Every bot is allowed
-the kit's commands by default, except obk permission, retire, pause and init,
-which keep the user's yes.
+the kit's commands by default, except obk permission, retire, pause, init and
+run, which keep the user's yes.
 Add --json to any of them for the same answer as JSON.
+
+For another build of Orca, OBK_ORCA names its CLI, and OBK_ORCA_DATA the full
+path of the folder it keeps its data in, such as
+$HOME/Library/Application Support/orca-lean.
+The kit reads Orca's launch arguments from the profiles folder there.
 `;
 
 
@@ -374,6 +396,10 @@ function version() {
 }
 
 async function run(argv) {
+  // What follows `obk run --timeout <n> --` is the command's own, flags and
+  // all, so it is read by `run` alone, before the kit reads its flags (#532).
+  if (argv[0] === 'run') return runBounded(parseRun(argv.slice(1)));
+
   const { values, positionals, tokens } = parseArgs({
     args: argv,
     allowPositionals: true,
@@ -435,7 +461,7 @@ async function run(argv) {
   }
 
   // A permission rule narrows a command to one bots folder by its first words,
-  // whatever comes after them (ADR 0036), and the last of two `--bots` would
+  // whatever comes after them (ADR 0050), and the last of two `--bots` would
   // win: so a second one is refused before anything runs.
   if (tokens.filter((token) => token.kind === 'option' && token.name === 'bots').length > 1) {
     throw new Error('--bots is given more than once. Give it once: one command works on one bots folder. Nothing was done.');
@@ -595,6 +621,8 @@ async function record(bots, bot) {
 
 const commands = {
   async init(bots, values) {
+    // Bot Father on Pi is not in the first slice of #547.
+    if (values.harness === 'pi') throw new Error('init does not take --harness pi yet: Bot Father runs on claude or codex, and its other bots may run on Pi. Nothing was written.');
     // Asked before anything is written, so an Orca that is down leaves the disk
     // exactly as it was and the caller can simply run the command again.
     refuseWhenOrcaIsDown();
@@ -827,7 +855,9 @@ const commands = {
   },
 
   'bot create'(bots, values) {
-    const made = createBot(bots, { name: values.name, harness: values.harness, charter: values.charter });
+    // The kit's default rules (ADR 0050) are in the bot's first bot.yaml.
+    const allow = botDefaults(bots, { harness: values.harness, sessions: [] });
+    const made = createBot(bots, { name: values.name, harness: values.harness, charter: values.charter, allow });
     // The bot's AGENTS.md is the rules build's, here as everywhere else, so
     // that a new bot's file and a rebuilt one are written by the same code.
     const rules = [buildAgents(bots, made.home, readBot(made.home))];
@@ -838,9 +868,10 @@ const commands = {
     // instructions, so `up` will not start it, and saying "give it a session"
     // would send the caller past the thing that needs settling first.
     const trouble = rules[0].trouble !== undefined;
-    // The kit's default rules (ADR 0036), for a bot that is set up to run: one
-    // with no instructions gets them at the rules build that gives it some.
-    const permissions = trouble ? [] : writePermissions(bots, made.home, readBot(made.home));
+    // The default rules go into the harness's files for a bot that is set up
+    // to run: one with no instructions gets them at the rules build that gives
+    // it some. They were added by this command, so its report names them.
+    const permissions = trouble ? [] : writePermissions(bots, made.home, readBot(made.home)).map((entry) => ({ ...entry, defaults: allow }));
     const answer = { bots, bot: made.bot, home: made.home, created: made.created, rules, skills, permissions };
     return {
       answer,
@@ -862,7 +893,7 @@ const commands = {
       throw new Error(`bot change does not change a bot's harness: its sessions' conversations belong to the harness they ran on. To move to ${values.harness}, give it a session on ${values.harness} with obk session add, or retire the bot with obk retire and create a new one.`);
     }
     // Permission changes have commands of their own, which keep the user's yes
-    // (ADR 0041): the old spelling refuses, and changes nothing.
+    // (ADR 0051): the old spelling refuses, and changes nothing.
     const moved = [['allow', 'permission allow'], ['disallow', 'permission disallow']].filter(([flag]) => values[flag] !== undefined);
     if (moved.length > 0) {
       throw new Error(`bot change no longer takes ${moved.map(([flag]) => `--${flag}`).join(' or ')}: permission rules change through ${moved.map(([, now]) => `${shellWord(ownCli())} ${now} --bots ${shellWord(bots)} --bot ${values.bot} --rule <rule>`).join(' and ')}, after the user's yes. Nothing was changed.`);
@@ -1069,7 +1100,7 @@ const commands = {
       ...(values.effort === undefined ? {} : { effort: values.effort }),
       ...(values['extra-arg'] === undefined ? {} : { extra_args: values['extra-arg'] }),
     };
-    // A run's launch may not widen its approval (ADR 0041).
+    // A run's launch may not widen its approval (ADR 0051).
     if (values['run-on'] === 'codex') refuseApprovalArgs('codex', values['extra-arg']);
     const groom = grooming(bots, { at: values.at, ask, run });
     return { answer: { bots, groom }, lines: groomLines(groom, bots) };
@@ -1132,7 +1163,8 @@ const commands = {
   },
 
   async 'message send'(bots, values) {
-    const tab = callerTab(bots, values.from === undefined);
+    // With --from too: in one of the fleet's tabs, the tab says who sends (#570).
+    const tab = callerTab(bots, true);
     refuseWhenOrcaIsDown();
     const answer = await sendMessage(bots, {
       to: values.to,
@@ -1204,6 +1236,7 @@ const commands = {
 
   'session add'(bots, values) {
     refuseApproval(bots, values, 'session add');
+    refuseOutsideWorkDir(bots, values);
     const added = addSession(bots, values.bot, settingsOf(values));
     const found = workDirFound(values, added.bot, added.home, added.session.name);
     const answer = { bots, bot: added.bot, home: added.home, session: added.session, found };
@@ -1233,21 +1266,23 @@ const commands = {
   },
 
   'session change'(bots, values) {
-    if (values.harness !== undefined) {
-      throw new Error(`session change does not change a session's harness: its conversations belong to the harness they ran on. To move it, retire it with obk retire and add one on ${values.harness} with obk session add.`);
-    }
     refuseApproval(bots, values, 'session change');
     const { name, ...settings } = settingsOf(values);
     const changed = changeSession(bots, values.bot, values.session, settings);
     const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${changed.bot} --session ${values.session}`;
     const found = workDirFound(values, changed.bot, changed.home, values.session);
+    const { moved } = changed;
     return {
-      answer: { bots, bot: changed.bot, home: changed.home, session: changed.session, restart, found },
+      answer: { bots, bot: changed.bot, home: changed.home, session: changed.session, ...(moved === undefined ? {} : { moved }), restart, found },
       lines: [
         `changed    session ${values.session} in ${path.join('bots', changed.bot, 'bot.yaml')}`,
         ...Object.entries(changed.session)
           .filter(([key]) => key !== 'name')
           .map(([key, value]) => `           ${key}  ${oneLine(value)}`),
+        ...(moved === undefined ? [] : [
+          `moved      from ${moved.from} to ${moved.to}: when it next starts, it starts a new conversation on ${moved.to}, and the book keeps its old one in the session's history.`,
+          ...(moved.defaults.length === 0 ? [] : [`           ${moved.defaults.join(', ')} went back to ${moved.to}'s own default${moved.defaults.length === 1 ? '' : 's'}.`]),
+        ]),
         ...foundLines(found),
         `A running session takes this when it next starts:  ${restart}`,
       ],
@@ -1290,7 +1325,7 @@ function toLines(answer, bots, where) {
     // says what to do instead, before the bot needs it (#521).
     return [
       `             Write to ${answer.address} with your own harness's messaging. The kit does not carry that road.`,
-      "             If your harness refuses that call, do not send the message again by another road. Tell your maker or your user that it was refused, with the harness's reason. A refusal can mean a missing permission rule, which they can add through the kit after the user's yes.",
+      "             If your harness refuses that call, do not send the message again by another road. Tell your maker or your user that it was refused, with the harness's reason. A refusal can mean a missing permission rule. Send the refusal to whoever adds your rules: your maker, your user or your fleet's manager.",
     ];
   }
   return [
@@ -1306,25 +1341,45 @@ function toLines(answer, bots, where) {
  * came to when one was asked for (#555).
  */
 function sentLines(answer, where) {
-  const road = "             it is in its Orca mailbox, and Orca's own notice tells it to look once it is idle.";
+  const road = noticeLines(answer);
   if (answer.interrupted === true) {
     return [
-      `${road.replace('once it is idle', 'now')}`,
+      ...(road.length === 1 ? [road[0].replace('once it is idle', 'now')] : road),
       `             it was busy, so the kit pressed Escape once in its tab to end its turn.${answer.to.harness === 'codex' ? ' Codex keeps a command it was running as a background terminal after an Escape.' : ''}`,
     ];
   }
   if (answer.interrupted === false) {
-    return [road, answer.idle ? `             it is idle, so it was not interrupted.` : `             it was not interrupted: ${answer.interruptTrouble}.`];
+    return [...road, answer.idle ? `             it is idle, so it was not interrupted.` : `             it was not interrupted: ${answer.interruptTrouble}.`];
+  }
+  return road;
+}
+
+/**
+ * Whether Orca's notice will tell the receiver of its letter. It will not while
+ * Orca lists the receiver's tab as orphaned, as after a window restart: the
+ * window has not loaded the tab (#579). A switch to the tab loads it, and is
+ * named as a fact with its cost, not run and not urged: it moves the user's view.
+ */
+function noticeLines(answer) {
+  if (answer.orphaned === true) {
+    return [
+      "             it is in its Orca mailbox, and it waits there: Orca lists its tab as orphaned, because the Orca window has not loaded that tab, and Orca will not tell it of the letter until the window loads it.",
+      `             ${shellWord(orcaCli())} terminal switch --terminal ${shellWord(answer.handle)} loads the tab. It also moves the user's view to that tab, so what the user types can land in it.`,
+    ];
+  }
+  if (answer.loadTrouble !== undefined) {
+    return [`             it is in its Orca mailbox. The kit could not tell whether the Orca window has loaded its tab (${answer.loadTrouble}), and Orca tells it of the letter only once the window has loaded the tab.`];
   }
-  return [road];
+  return ["             it is in its Orca mailbox, and Orca's own notice tells it to look once it is idle."];
 }
 
 /**
  * What there is to say about the work dir this command was given: one finding
  * when it leads out of the bot home, through `..` or a link or as a path
  * elsewhere, and nothing otherwise (#222). A bot's work and its clones belong
- * under its own `work/`. It is said, not refused: the user may ask for a folder
- * anywhere (PRD 6.3), and it is written as they gave it.
+ * under its own `work/`. For a Claude or Pi session it is said, not refused: a
+ * work dir is an instruction there (PRD 6.4), and it is written as given. A
+ * Codex session's is refused before this (refuseCodexOutside).
  */
 function workDirFound(values, bot, home, session) {
   const workDir = workDirOf({ work_dir: values['work-dir'] }, home);
@@ -1336,16 +1391,35 @@ function workDirFound(values, bot, home, session) {
   }];
 }
 
+/**
+ * Refuse a new Codex session a work dir outside its bot home (ADR 0045). A
+ * changed session is judged in changeSession, on what it writes (#585).
+ */
+function refuseOutsideWorkDir(bots, values) {
+  if (values['work-dir'] === undefined) return;
+  let bot;
+  try {
+    bot = readBot(botDir(bots, values.bot), values.bot);
+  } catch {
+    // A bot that is not there is the command's own to refuse.
+    return;
+  }
+  const session = { name: values.name, harness: values.harness, work_dir: values['work-dir'] };
+  refuseCodexOutside(values.bot, session, undefined, bot.harness, botDir(bots, values.bot), 'session add');
+}
+
 /**
  * Refuse what would change a session's approval through `session add` or
- * `session change` (ADR 0041): `--approval`, and an extra argument that sets
+ * `session change` (ADR 0051): `--approval`, and an extra argument that sets
  * it on the session's harness. Only `permission approval` changes it.
  */
 function refuseApproval(bots, values, command) {
   if (values.approval !== undefined) {
     throw new Error(`${command} no longer takes --approval: a session's approval changes through ${shellWord(ownCli())} permission approval --bots ${shellWord(bots)} --bot ${values.bot} --session ${values.session ?? values.name} --approval <level>, after the user's yes. Nothing was changed.`);
   }
-  if (values['extra-arg'] === undefined) return;
+  // A move to another harness keeps the extra arguments the session has, and
+  // one of them can set approval on the new harness (#565).
+  if (values['extra-arg'] === undefined && values.harness === undefined) return;
   let bot;
   try {
     bot = readBot(botDir(bots, values.bot), values.bot);
@@ -1354,7 +1428,7 @@ function refuseApproval(bots, values, command) {
     return;
   }
   const session = bot.sessions.find((one) => one.name === (values.session ?? values.name)) ?? {};
-  refuseApprovalArgs(harnessOf({ ...session, ...(values.harness === undefined ? {} : { harness: values.harness }) }, bot.harness), values['extra-arg']);
+  refuseApprovalArgs(harnessOf({ ...session, ...(values.harness === undefined ? {} : { harness: values.harness }) }, bot.harness), values['extra-arg'] ?? (command === 'session change' ? session.extra_args : undefined));
 }
 
 /**
@@ -1437,6 +1511,12 @@ function refuseWhenOrcaIsDown() {
 /** The one line that says which conversation this tab was given, and from where. */
 const howLines = (tab) => {
   if (tab.resumed === true) return ['             it was told to resume the session the book holds, with its conversation.'];
+  if (tab.harnessChanged !== undefined) {
+    return [
+      `             it was told to start a new session: the book's conversation ${tab.harnessChanged} ran on ${tab.ranOn},`,
+      "             and the session has moved from it, so it went into the session's history.",
+    ];
+  }
   if (tab.noConversation === undefined) return ['             it was told to start a new session: the book holds none for this one yet.'];
   return [
     `             it was told to start a new session: the book's conversation ${tab.noConversation} had nothing on record`,
@@ -1658,7 +1738,7 @@ function rosterLines(roster, bots) {
   }
 
   lines.push(roster.length === 0
-    ? `No bots yet. Make one:  ${shellWord(ownCli())} bot create --bots ${shellWord(bots)} --name <name> --harness claude|codex`
+    ? `No bots yet. Make one:  ${shellWord(ownCli())} bot create --bots ${shellWord(bots)} --name <name> --harness claude|codex|pi`
     : `${roster.length} bot${roster.length === 1 ? '' : 's'}. Your bots folder: ${bots}`);
   return lines;
 }
@@ -1725,9 +1805,9 @@ function charterRulesLines(bots, bot, rules) {
 
 /**
  * What became of each bot's permission rules: each of the kit's default rules
- * the run added to the bot, word for word (ADR 0036), each rule of a command no
+ * the run added to the bot, word for word (ADR 0050), each rule of a command no
  * longer in the set that the bot still holds, with the command that takes it
- * back (ADR 0041), and the file the allowed ones were written into. Nothing for
+ * back (ADR 0051), and the file the allowed ones were written into. Nothing for
  * a bot with nothing added, held or written.
  */
 function permissionsLines(permissions, bots) {

package/src/commands.js

@@ -1,7 +1,7 @@
 // The kit's commands, each with the flags it cannot do without, which `obk`
 // reads to parse a command line; and the two lists every command is on one of:
-// those every bot is allowed by default (#527, ADR 0036), and those kept back
-// for the user's yes (ADR 0041). A new command is on neither until someone
+// those every bot is allowed by default (#527, ADR 0050), and those kept back
+// for the user's yes (ADR 0051). A new command is on neither until someone
 // puts it on one, and a test holds every command to that choice.
 
 /** The commands, and the flags each one cannot do without. */
@@ -46,18 +46,19 @@ export const COMMANDS = {
   'temp retire': ['bots', 'name'],
   'temp trust-hooks': ['bots', 'name'],
   'temp answer': ['bots', 'name'],
+  run: ['timeout'],
 };
 
 /**
  * The commands every bot is allowed by default, each narrowed to its bots
- * folder (ADR 0036). Only a command named here is in the default set; one that
+ * folder (ADR 0050). Only a command named here is in the default set; one that
  * runs whatever its arguments say never is.
  */
 export const DEFAULT_COMMANDS = [
   'up', 'unpause', 'health', 'groom', 'roster', 'usage',
-  'bot change', 'rules build',
+  'rules build',
   'skills add', 'skills remove', 'skills build', 'skills fetch', 'skills update', 'source add',
-  'session add', 'session change', 'session clear', 'session compact',
+  'session clear', 'session compact',
   'message to', 'message send', 'message check',
   'session record', 'session sent', 'session name', 'session mailbox',
   'session trust-hooks', 'session answer',
@@ -66,17 +67,28 @@ export const DEFAULT_COMMANDS = [
 
 /**
  * The commands kept out of the default permission set, which keep the user's
- * yes (ADR 0041): the ones that change permissions, close a long-lived
- * session, make the bots folder, or make a bot, which the owner leaves to Bot
- * Father (#548).
+ * yes (ADR 0051): the ones that change permissions, close a long-lived
+ * session, make the bots folder, or make or change a bot or its sessions,
+ * which the owner leaves to Bot Father (#548, #615); and `run`, which runs
+ * whatever its arguments say, so a rule for it names its command (#532).
  */
 export const KEPT_BACK = [
   'init', 'retire', 'pause', 'restart', 'bot create',
+  'bot change', 'session add', 'session change',
   'permission allow', 'permission disallow', 'permission approval',
+  'run',
 ];
 
 /**
- * The commands kit 0.26.0 gave every bot by default and that are kept back now
- * (#548). A bot may still hold their rules, which the kit names and leaves.
+ * The commands the kit gave every bot by default and that are kept back now
+ * (#548, #615). A bot may still hold their rules, which the kit names and
+ * leaves.
  */
-export const NO_LONGER_DEFAULT = ['restart', 'bot create'];
+export const NO_LONGER_DEFAULT = ['restart', 'bot create', 'bot change', 'session add', 'session change'];
+
+/**
+ * The commands kit 0.26.0 gave every bot by default and that the kit no longer
+ * has (#555). A bot may still hold their rules, which the kit names and leaves
+ * (#564).
+ */
+export const REMOVED = ['session mail', 'session nudge'];

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)
@@ -173,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));
@@ -191,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';