@assuredloop/orca-bot-kit 0.26.1 → 0.28.0

package/src/cli.js

@@ -12,21 +12,21 @@ 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';
 import { initBots } from './init.js';
 import { nameSession } from './name.js';
 import { APPROVALS, harnessOf, HARNESSES, ownCli, refuseApprovalArgs, shellWord, workDirOf } from './launch.js';
-import { checkMail, decideLeftNudges, lookUp, noMailboxYet, sendMessage, sessionInTab, stillUnread, WATCH_MS } from './message.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';
 import { clearSession, compactSession } from './clear.js';
-import { retireBot, retireSession, unreadWords } from './retire.js';
+import { retireBot, retireSession } from './retire.js';
 import { sentWarning } from './sent.js';
 import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
@@ -43,18 +43,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 +88,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
@@ -109,7 +113,9 @@ Usage:
                             End a session: close its tab and take it off the
                             bot, keeping its conversations in the book, and
                             first do the same for the temporary sessions it
-                            made, and theirs. Or end a bot: close its tabs,
+                            made, and theirs. It stops what the session left
+                            running in its work dir, and names each process.
+                            Or end a bot: close its tabs,
                             remove its Orca project and move its folder to
                             retired/. It will not retire a bot whose Orca
                             project holds a tab your book does not name, and
@@ -207,13 +213,18 @@ Usage:
                             the Orca mailbox. Nothing is sent.
   obk message send --bots <path> --to <bot>[/<session>] [--from <bot>/<session>]
                    --subject <text> [--text <text> | --text-file <path>]
-                   [--thread <id>]
-                            Put a message in that session's Orca mailbox and
-                            tell its tab to look. A message too long to travel
+                   [--thread <id>] [--interrupt]
+                            Put a message in that session's Orca mailbox. Orca
+                            tells it to look once it is idle. --interrupt is
+                            for urgent mail: when the session is busy, the kit
+                            presses Escape once in its tab first, to end its
+                            turn, so it looks now. A message too long to travel
                             as itself is written to a file beside your bots
                             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
@@ -269,7 +280,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
@@ -305,17 +317,6 @@ Usage:
                             Claude session's native message, it warns the
                             session when the address was none of this bots
                             folder's own. It never stops a message.
-  obk session nudge --bots <path> --bot <bot>
-                            For the kit's own hook, not for typing: after a
-                            Codex session's shell command, it decides the mail
-                            nudges a send there left because it could not
-                            tell from inside Codex's sandbox, and types each
-                            one or says why not.
-  obk session mail --bots <path> --bot <bot>
-                            For the kit's own hook, not for typing: at the end
-                            of a Claude session's turn, it tells the session
-                            once about each fleet mail the kit sent it that is
-                            still unread. It types nothing into the tab.
   obk session name --bots <path> --bot <bot>
                             For the kit's own hook, not for typing: after a
                             Codex session's turn, it names the session's thread
@@ -409,6 +410,7 @@ async function run(argv) {
       'text-file': { type: 'string' },
       thread: { type: 'string' },
       peek: { type: 'boolean' },
+      interrupt: { type: 'boolean' },
       charter: { type: 'string' },
       allow: { type: 'string', multiple: true },
       disallow: { type: 'string', multiple: true },
@@ -440,7 +442,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.');
@@ -476,8 +478,6 @@ async function run(argv) {
   // The send hook is quiet whatever it is given, a bots folder that is not
   // there included, so it goes before anything that can complain (ADR 0032).
   if (command === SENT) return sent(path.resolve(values.bots));
-  if (command === NUDGE) return nudgeLeft();
-  if (command === MAIL) return mailHook(path.resolve(values.bots), values.bot);
   if (command === NAME) return nameThread(path.resolve(values.bots), values.bot);
 
   // One fleet, one identity, whatever spelling of its path was given (#164).
@@ -548,8 +548,6 @@ const ANSWER_IT = [
 /** The commands a harness runs rather than a person: the kit's hooks. */
 const RECORD = 'session record';
 const SENT = 'session sent';
-const NUDGE = 'session nudge';
-const MAIL = 'session mail';
 const NAME = 'session name';
 
 /**
@@ -569,45 +567,6 @@ function sent(bots) {
   return 0;
 }
 
-/**
- * What the kit's Codex hook does after a shell command: decide the nudges a
- * send in this tab left for it, outside Codex's sandbox, and say to the session
- * what became of each, as Codex's `additionalContext` (#350, ADR 0034). Silent
- * when nothing was left, never a decision, and never anything but exit 0.
- */
-async function nudgeLeft() {
-  try {
-    const said = JSON.parse(readFileSync(0, 'utf8'));
-    if (said?.hook_event_name !== 'PostToolUse') return 0;
-    const decided = await decideLeftNudges(process.env[TAB_ENV]);
-    if (decided.length > 0) {
-      const words = decided.map((one) => `Your mail "${one.subject}" to ${one.to}: ${one.nudged ? "the kit's hook nudged its tab, from outside Codex's sandbox:" : "the kit's hook looked at its tab from outside Codex's sandbox, and"} ${nudgeLine(one, one.to).trim()}`);
-      process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: words.join('\n') } })}\n`);
-    }
-  } catch {
-    // Nothing: a hook does not disturb the session it runs in.
-  }
-  return 0;
-}
-
-/**
- * What the kit's Claude Code Stop hook does at a turn end (#509, ADR 0035): tell
- * the session once about fleet mail still unread, as the Stop event's
- * additional context, which the session goes on with. Not a block: Claude Code
- * 2.1.296 draws a block's reason in red as "Stop hook error", and its additional
- * context as "Stop hook feedback". Nothing typed into the tab; never anything
- * but exit 0; silent whenever it cannot be sure.
- */
-function mailHook(bots, bot) {
-  try {
-    const reason = stillUnread(sameFleet(bots), bot, JSON.parse(readFileSync(0, 'utf8')), process.env[TAB_ENV], process.env[TERMINAL_ENV]);
-    if (reason !== undefined) process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'Stop', additionalContext: reason } })}\n`);
-  } catch {
-    // Nothing: a hook does not disturb the session it runs in.
-  }
-  return 0;
-}
-
 /**
  * What the kit's Codex Stop hook does at a turn end: name the session's thread
  * after its bot and session, once it is idle (#480). Silent, never a decision,
@@ -643,6 +602,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();
@@ -737,7 +698,7 @@ const commands = {
           ...withLines(retired.retiredWith, retired.session),
           ...closedLines(retired.closed),
           `retired    ${retired.bot} ${retired.session}: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
-          ...unreadLines(retired.unread),
+          ...processLines(retired.processes),
           ...leftLines(retired.promptsLeft),
         ],
       };
@@ -749,6 +710,7 @@ const commands = {
         answer: { bots, ...retired },
         lines: [
           ...closedLines(retired.closed),
+          ...processLines(retired.processes),
           `${'trouble'.padEnd(9)}  Orca project ${retired.project}`,
           `             ${retired.trouble}`,
           `Retire it again:  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${retired.bot}`,
@@ -767,7 +729,7 @@ const commands = {
           retired.windowReloaded ? "reloaded   Orca's window, so its sidebar no longer shows the project" : RELOAD_LINE,
         ]),
         `retired    ${retired.bot}: moved to ${path.relative(bots, retired.moved)}, with its book, charter and memory`,
-        ...(retired.unread ?? []).flatMap((one) => unreadLines(one, `${retired.bot}/${one.session}`)),
+        ...processLines(retired.processes),
         ...leftLines(retired.promptsLeft),
       ],
     };
@@ -824,7 +786,7 @@ const commands = {
         ...withLines(retired.retiredWith, retired.session),
         ...closedLines(retired.closed),
         `retired    ${retired.bot} ${retired.session}, a temporary session of ${retired.maker}'s: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
-        ...unreadLines(retired.unread),
+        ...processLines(retired.processes),
         ...leftLines(retired.promptsLeft),
       ],
     };
@@ -874,7 +836,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))];
@@ -885,9 +849,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,
@@ -909,7 +874,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.`);
@@ -1116,7 +1081,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) };
@@ -1179,7 +1144,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,
@@ -1189,6 +1155,7 @@ const commands = {
       text: values.text,
       textFile: values['text-file'],
       thread: values.thread,
+      interrupt: values.interrupt === true,
     });
     const where = `${answer.to.bot}/${answer.to.session}`;
 
@@ -1207,7 +1174,7 @@ const commands = {
         ...(answer.file === undefined
           ? []
           : [`             it was too long to travel as itself, so it went as a file:  ${answer.file}`]),
-        ...[nudgeLine(answer, where)],
+        ...sentLines(answer, where),
       ],
     };
   },
@@ -1250,6 +1217,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 };
@@ -1279,21 +1247,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}`,
       ],
@@ -1336,7 +1306,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 [
@@ -1348,52 +1318,49 @@ function toLines(answer, bots, where) {
 }
 
 /**
- * What became of the line that tells the receiver to look. The message is in
- * its mailbox whatever this says, so each of these is about the tab and not
- * about the message.
+ * What the send says after `sent`: the road it took, and what the interrupt
+ * came to when one was asked for (#555).
  */
-function nudgeLine(answer, where) {
-  const seconds = answer.watchedMs === undefined ? '' : ` in ${Math.max(Math.round(answer.watchedMs / 1000), 1)} s`;
-  if (answer.signal === 'orca') return `             Orca's notice reached it${seconds}, so no line was typed: it reads the mail from there.`;
-  if (answer.signal === 'hook') {
-    return answer.because === 'busy'
-      ? "             it is busy with a turn, so nothing was typed into its tab: its own hook tells it about the mail when that turn ends."
-      : `             a turn of other work started in its tab${seconds}, not Orca's notice, so nothing was typed: its own hook tells it about the mail when that turn ends.`;
-  }
-  const why = {
-    'no-turn': `no turn started in its tab in ${WATCH_SECONDS} s, so the kit's line was typed`,
-    busy: "it is busy with a turn, and Codex takes a line into the turn it is having, so the kit's line was typed",
-    'other-turn': "a turn of other work started in its tab, not Orca's notice, so the kit's line was typed",
-  }[answer.because];
-  const head = why === undefined ? '             ' : `             ${why}: `;
-  if (answer.nudged && answer.nudgeWatched === false) {
-    return `${head}its tab was typed into, and Orca could not say whether it was taken: ${answer.nudgeUnseen} The message waits in its mailbox for its next check either way.`;
-  }
-  if (answer.nudged && answer.nudgeUnseen !== undefined) {
-    return `${head}its tab was typed into, but Orca did not see the line start a turn: it may be queued behind the work in hand, or lost. The message waits in its mailbox for its next check either way.`;
+function sentLines(answer, where) {
+  const road = noticeLines(answer);
+  if (answer.interrupted === true) {
+    return [
+      ...(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.nudged) return `${head}its tab was told to look; it will read it when it is done with what it is doing.`;
-  if (answer.blocked !== undefined) {
-    return `             its tab has something waiting to be answered (${answer.blocked}), so nothing was typed into it. Settle that, and the mail is there.`;
+  if (answer.interrupted === false) {
+    return [...road, answer.idle ? `             it is idle, so it was not interrupted.` : `             it was not interrupted: ${answer.interruptTrouble}.`];
   }
-  if (answer.nudgeLeft) {
-    return `             it is queued, and its tab could not be told to look from here: ${answer.nudgeTrouble}. So the nudge is left for this session's hook, which looks at the tab from outside Codex's sandbox when this command is done, and says what it did.`;
+  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.nudgeTrouble !== undefined) {
-    return `             it is queued, and its tab could not be told to look: ${answer.nudgeTrouble}`;
+  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 `             ${where} is not up, so nothing was typed anywhere: the message waits in its mailbox.`;
+  return ["             it is in its Orca mailbox, and Orca's own notice tells it to look once it is idle."];
 }
 
-/** The watch before the kit's line, as the send says it (#509, ADR 0035). */
-const WATCH_SECONDS = WATCH_MS / 1000;
-
 /**
  * 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);
@@ -1405,16 +1372,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);
@@ -1423,7 +1409,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));
 }
 
 /**
@@ -1459,12 +1445,19 @@ const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab
 const withLines = (retiredWith, session) => retiredWith.flatMap((gone) => [
   ...closedLines(gone.closed),
   `retired    ${gone.bot} ${gone.session}, a temporary session of ${gone.maker}'s, along with ${session}: off ${path.join('bots', gone.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
-  ...unreadLines(gone.unread),
+  ...processLines(gone.processes),
   ...leftLines(gone.promptsLeft),
 ]);
 
-/** The mail a retired session did not read, as far as the kit knows (#509). */
-const unreadLines = (unread, who = 'it') => (unread === undefined ? [] : [`unread     ${unreadWords(unread, who)}`]);
+/** What a retire stopped of what its sessions left running, and what it named and left (#537). */
+function processLines(processes) {
+  if (processes === undefined) return [];
+  if (processes.unreadable !== undefined) return [`processes  the kit cannot tell which processes were left running in the work dir, so it stopped none: ${processes.unreadable}`];
+  return [
+    ...processes.stopped.map((one) => `stopped    pid ${one.pid} of ${one.session}, with ${one.signal}: ${one.command}${one.cwd === null ? '' : `  in ${one.cwd}`}`),
+    ...processes.left.map((one) => `left       pid ${one.pid} in ${one.cwd ?? 'a folder lsof did not name'}: ${one.command}. Not stopped: ${one.why}.`),
+  ];
+}
 
 /** What a retire could not remove, and how to: nothing reads these files now (#393). */
 const leftLines = (left = []) => left.flatMap(({ file, reason }) => [
@@ -1499,6 +1492,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`,
@@ -1720,7 +1719,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;
 }
@@ -1787,9 +1786,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. */
@@ -37,8 +37,6 @@ export const COMMANDS = {
   'message check': ['bots'],
   'session record': ['bots', 'bot'],
   'session sent': ['bots', 'bot'],
-  'session nudge': ['bots', 'bot'],
-  'session mail': ['bots', 'bot'],
   'session name': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
   'session trust-hooks': ['bots', 'bot', 'session'],
@@ -52,33 +50,42 @@ export const COMMANDS = {
 
 /**
  * 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 nudge', 'session mail', 'session name', 'session mailbox',
+  'session record', 'session sent', 'session name', 'session mailbox',
   'session trust-hooks', 'session answer',
   'temp make', 'temp roles', 'temp retire', 'temp trust-hooks', 'temp answer',
 ];
 
 /**
  * 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).
  */
 export const KEPT_BACK = [
   'init', 'retire', 'pause', 'restart', 'bot create',
+  'bot change', 'session add', 'session change',
   'permission allow', 'permission disallow', 'permission approval',
 ];
 
 /**
- * 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'];