@assuredloop/orca-bot-kit 0.13.0 → 0.14.0

package/README.md

@@ -508,7 +508,7 @@ verdict: which of these matter, and in what order, is for you or for Bot Father.
 ## Sessions and bots that talk
 
 Ask the kit how to reach a session, and it answers with the road and the
-address ([ADR 0018](docs/adr/0018-messaging-transport.md)):
+address ([ADR 0030](docs/adr/0030-messaging-transport.md)):
 
 ```sh
 obk message to    --bots /path/to/my-bots --to api-bot/daily

package/package.json

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

package/rules/temporary.md

@@ -0,0 +1,21 @@
+---
+name: temporary
+title: Temporary sessions of your own
+applies: all
+---
+
+For a piece of work that wants a helper, a long-lived session may make a
+temporary session of its own bot, without asking Bot Father:
+`"${OBK_CLI:-obk}" temp make --bots <bots> --name <name> --prompt <the task>`,
+run in your own tab. It takes your settings unless you say otherwise, and gets
+a work dir, a tab and a mailbox.
+
+A new tab can stop on a first-run screen. Answer it yourself, from the table
+the command's output points to.
+
+Retire it when its work is done:
+`"${OBK_CLI:-obk}" temp retire --bots <bots> --name <name>`. Before you make
+another, first retire any of yours whose work is done.
+
+You manage only the temporary sessions you made; a temporary session makes
+none of its own. Every other session is Bot Father's to make, change or retire.

package/src/book.js

@@ -30,6 +30,9 @@ const HEADER = `# What Orca calls this bot on this machine, and where each of it
 #
 # \`retired\` holds what the book knew about each session \`obk retire\` took off
 # the bot, with when, so the conversations it had are still accounted for.
+#
+# \`temporary\` marks a session another session of this bot made with
+# \`obk temp make\`: which session made it, and when. Its maker retires it.
 `;
 
 export const bookFile = (home) => path.join(home, 'sessions.yaml');

package/src/bot.js

@@ -21,7 +21,7 @@ export const botsDir = (bots) => path.join(bots, 'bots');
 export const botDir = (bots, name) => path.join(botsDir(bots), name);
 
 /** A bot's name: the folder it lives in, and safe to be one. */
-const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 /** The file that says what a bot is. A folder without one is not a bot. */
 const BOT_YAML = 'bot.yaml';

package/src/cli.js

@@ -17,8 +17,8 @@ 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';
-import { checkMail, lookUp, noMailboxYet, sendMessage } from './message.js';
-import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
+import { checkMail, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
+import { orcaCli, orcaTrouble, RELOAD_LINE, TERMINAL_ENV } from './orca.js';
 import { allowCommand, allowIn, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
@@ -28,6 +28,7 @@ import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
 import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
 import { addSource, fetchSources } from './sources.js';
+import { makeTemp, retireTemp } from './temp.js';
 import { readUsage } from './usage.js';
 import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 
@@ -95,6 +96,21 @@ Usage:
                             bot whose Orca project holds a tab your book does
                             not name, and moves the folder only once Orca no
                             longer lists the project.
+  obk temp make --bots <path> --name <session>
+                (--prompt <text> | --prompt-file <path>) [--harness claude|codex]
+                [--model <m>] [--effort <e>] [--context <c>]
+                [--approval ${APPROVALS.join('|')}]
+                            Run in a long-lived session's own tab: make a
+                            temporary session of that session's bot for a piece
+                            of work, and bring it up. It takes your harness,
+                            model, effort, context and approval unless you say
+                            otherwise, works in work/<session>, and has the task
+                            as its start prompt. The book records it as
+                            temporary, made by you.
+  obk temp retire --bots <path> --name <session>
+                            Run in the maker's own tab: retire a temporary
+                            session it made, as obk retire does. It refuses a
+                            long-lived session, or one another session made.
   obk rules build --bots <path> [--bot <bot>]
                             Build every bot's AGENTS.md from its charter and
                             the rule units it carries, or just the one you
@@ -242,6 +258,8 @@ const COMMANDS = {
   'message check': ['bots'],
   'session record': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
+  'temp make': ['bots', 'name'],
+  'temp retire': ['bots', 'name'],
 };
 
 /** What each flag is for, in the sentence a caller reads when it is missing. */
@@ -335,9 +353,9 @@ async function run(argv) {
     return 1;
   }
 
-  // `bot`, `rules`, `skills`, `session`, `source` and `message` are commands of
-  // two words; the rest are one.
-  const words = ['bot', 'rules', 'skills', 'session', 'source', 'message'].includes(positionals[0]) ? 2 : 1;
+  // `bot`, `rules`, `skills`, `session`, `source`, `message` and `temp` are
+  // commands of two words; the rest are one.
+  const words = ['bot', 'rules', 'skills', 'session', 'source', 'message', 'temp'].includes(positionals[0]) ? 2 : 1;
   const command = positionals.slice(0, words).join(' ');
   const extra = positionals.slice(words);
 
@@ -534,8 +552,6 @@ const commands = {
 
   async retire(bots, values) {
     refuseWhenOrcaIsDown();
-    const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab.name}  tab ${tab.tabId}  terminal ${tab.terminal}`);
-
     if (values.session !== undefined) {
       const retired = await retireSession(bots, { bot: values.bot, session: values.session });
       return {
@@ -543,6 +559,7 @@ const commands = {
         lines: [
           ...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`,
+          ...leftLines(retired.promptsLeft),
         ],
       };
     }
@@ -571,6 +588,39 @@ 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`,
+        ...leftLines(retired.promptsLeft),
+      ],
+    };
+  },
+
+  async 'temp make'(bots, values) {
+    const tab = callerTab(bots, true);
+    refuseWhenOrcaIsDown();
+    const given = { name: values.name };
+    for (const [flag, key] of [['harness', 'harness'], ['model', 'model'], ['effort', 'effort'], ['approval', 'approval'], ['prompt', 'prompt'], ['prompt-file', 'prompt_file']]) {
+      if (values[flag] !== undefined) given[key] = values[flag];
+    }
+    if (values.context !== undefined) given.context = asNumberOrText(values.context);
+    const made = await makeTemp(bots, { tab, ...given });
+    const { tabs, rules, skills, permissions, paused, projects } = made.up;
+    const answer = { bots, bot: made.bot, session: made.session, maker: made.maker, settings: made.settings, created: [], completed: [], rules, skills, permissions, tabs, paused, projects };
+    const retire = `${shellWord(ownCli())} temp retire --bots ${shellWord(bots)} --name ${made.session}`;
+    return {
+      answer,
+      lines: tabLines(answer, `Made ${made.bot}/${made.session}, a temporary session of ${made.maker}'s, working in work/${made.session}. Retire it when its work is done:  ${retire}`),
+    };
+  },
+
+  async 'temp retire'(bots, values) {
+    const tab = callerTab(bots, true);
+    refuseWhenOrcaIsDown();
+    const retired = await retireTemp(bots, { tab, name: values.name });
+    return {
+      answer: { bots, ...retired },
+      lines: [
+        ...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`,
+        ...leftLines(retired.promptsLeft),
       ],
     };
   },
@@ -832,11 +882,12 @@ const commands = {
   },
 
   'message send'(bots, values) {
+    const tab = callerTab(bots, values.from === undefined);
     refuseWhenOrcaIsDown();
     const answer = sendMessage(bots, {
       to: values.to,
       from: values.from,
-      tab: process.env[TAB_ENV],
+      tab,
       subject: values.subject,
       text: values.text,
       textFile: values['text-file'],
@@ -865,11 +916,13 @@ const commands = {
   },
 
   'message check'(bots, values) {
+    // Named or not, the mail is read as the caller's own terminal when it has one.
+    const tab = callerTab(bots, values.bot === undefined || process.env[TERMINAL_ENV] !== undefined);
     refuseWhenOrcaIsDown();
     const answer = checkMail(bots, {
       bot: values.bot,
       session: values.session,
-      tab: process.env[TAB_ENV],
+      tab,
       peek: values.peek === true,
     });
     const where = `${answer.bot}/${answer.session}`;
@@ -973,6 +1026,12 @@ function toLines(answer, bots, where) {
  * about the message.
  */
 function nudgeLine(answer, where) {
+  if (answer.nudged && answer.nudgeWatched === false) {
+    return `             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 '             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.';
+  }
   if (answer.nudged) return '             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.`;
@@ -1010,11 +1069,33 @@ function settingsOf(values) {
   return settings;
 }
 
+/** The tabs a command closed, one line each. */
+const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab.name}  tab ${tab.tabId}  terminal ${tab.terminal}`);
+
+/** What a retire could not remove, and how to: nothing reads these files now (#393). */
+const leftLines = (left = []) => left.flatMap(({ file, reason }) => [
+  `left       ${file}: it could not be removed (${reason}). Nothing reads it now.`,
+  `           Remove it with:  rm ${shellWord(file)}`,
+]);
+
 /** A context window written as a plain number stays one in the file. */
 const asNumberOrText = (value) => (/^\d+$/.test(value) ? Number(value) : value);
 
 const oneLine = (value) => (Array.isArray(value) ? value.join(' ') : String(value)).replace(/\s+/g, ' ').trim();
 
+/**
+ * The Orca tab this command runs in, with the caller taken to be the session
+ * there only once sessionInTab has shown it is, when the command takes its
+ * caller from the tab (#408). Asked before Orca is: a Codex that Orca brought
+ * back by itself may run in a sandbox that cannot reach Orca at all, and
+ * "Orca is not ready" would send its user the wrong way.
+ */
+function callerTab(bots, takesCaller) {
+  const tab = process.env[TAB_ENV];
+  if (takesCaller && tab !== undefined) sessionInTab(bots, tab);
+  return tab;
+}
+
 function refuseWhenOrcaIsDown() {
   const trouble = orcaTrouble();
   if (trouble !== undefined) throw new Error(trouble);
@@ -1264,6 +1345,7 @@ function sessionLines(session) {
     ...(book.tab === undefined
       ? []
       : [`             tab ${book.tab}${book.launched === undefined ? '' : `  launched ${book.launched}`}`]),
+    ...(book.temporary === undefined ? [] : [`             temporary, made by ${book.temporary.maker}${book.temporary.made === undefined ? '' : ` at ${book.temporary.made}`}`]),
     ...(book.session === undefined ? [] : [`             conversation ${book.session}`]),
     ...(book.history ?? [])
       .filter((was) => was?.session !== undefined)

package/src/health.js

@@ -281,7 +281,11 @@ function runningOn(bots, home, bot, book, handles, sessions) {
       // see may still match, by the harness's own defaults; the rest of what
       // bot.yaml asks for is not on it either way.
       const drift = off.length === 0 ? '' : ` ${parts}, as the harness's own record of its conversation ${conversation} says.`;
-      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} was not started by the kit: the harness in its tab ${entry.tab} carries nothing of the kit's launch line, as when Orca brings its tabs back by itself after a restart or an update. So it runs on the harness's own defaults and whatever Orca added, not on what ${path.join(home, 'bot.yaml')} asks for.${drift} ${restart} starts it on bot.yaml.`, bot.name));
+      // A Codex brought back this way also runs its commands in Codex's shared
+      // background server, under whichever tab started it (#408).
+      const daemon = harness !== 'codex' ? '' : ` Without the kit's line it also runs without --no-daemon, so its commands run in Codex's shared background server, under the tab of whichever session started that server: another tab's identity, not its own. So the kit refuses its commands that take the caller from its tab, such as reading its mail.`;
+      const held = harness !== 'codex' ? '' : ` If Codex then shows "This conversation is open in another app", Codex's shared background server still holds the conversation, and it can outlive the session that started it: once every such session is back on the kit's line, stop the server with Codex's own \`codex app-server daemon stop\`, then restart this session again. That stops the server for everything using it, Codex sessions outside the kit included, so first check that nothing else needs it.`;
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} was not started by the kit: the harness in its tab ${entry.tab} carries nothing of the kit's launch line, as when Orca brings its tabs back by itself after a restart or an update. So it runs on the harness's own defaults and whatever Orca added, not on what ${path.join(home, 'bot.yaml')} asks for.${drift}${daemon} ${restart} starts it on bot.yaml.${held}`, bot.name));
     } else if (off.length > 0) {
       found.push(finding('session', file, `${bot.name}'s session ${session.name} does not run on what ${path.join(home, 'bot.yaml')} asks for. ${parts}. That is what the harness's own record of its conversation ${conversation} says. A session takes these when it starts, so if bot.yaml changed after it started, ${restart} starts it on them; if not, something else set them, such as a default of the harness's own or a change made inside the session.`, bot.name));
     }

package/src/init.js

@@ -86,8 +86,9 @@ charter: |
   Good looks like: every bot has a charter its owner recognises, the skills it
   needs and no more, and sessions that come back after a restart.
 
-  Ask first before: retiring a bot or a session, restarting anything, or
-  changing a bot's rules in a way its owner did not ask for.
+  Ask first before: retiring a bot or a long-lived session, restarting
+  anything, or changing a bot's rules in a way its owner did not ask for. A
+  temporary session is its maker's to retire, without asking.
 
   When the kit itself goes wrong (an obk command fails in a way its own message
   does not explain, or does something other than what it says), tell your owner

package/src/launch.js

@@ -51,7 +51,7 @@ export const harnessOf = (session, botHarness) => (set(session.harness) ? sessio
 
 /**
  * A session's name on Claude Code, which is also the address another Claude
- * session writes to (ADR 0018). It goes on the launch line as `-n`, and it is
+ * session writes to (ADR 0030). It goes on the launch line as `-n`, and it is
  * re-applied every time the session is started: a resume keeps the name by
  * itself (tech notes, section 2), and the kit does not depend on that.
  *
@@ -224,7 +224,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
 
   if (harness === 'claude') {
     // The name is the address other Claude sessions write to, so it goes on
-    // every launch line, a resume included (ADR 0018).
+    // every launch line, a resume included (ADR 0030).
     if (address !== undefined) words.push('-n', address);
     // The context window rides on the model name: `sonnet[1m]`.
     if (set(session.model)) words.push('--model', set(session.context) ? `${session.model}[${session.context}]` : session.model);

package/src/message.js

@@ -1,4 +1,4 @@
-// `obk message`: one session writing to another (PRD 6.9, ADR 0018).
+// `obk message`: one session writing to another (PRD 6.9, ADR 0030).
 //
 // Two roads, and the bot never picks. Claude to Claude in the same approval
 // class is the harness's own messaging, which no command line can send for it —
@@ -20,7 +20,7 @@ import path from 'node:path';
 
 import { MAILBOX_WAIT_MS, readBook, takeMailboxTurn } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
-import { harnessOf, isAddressOf, ownCli, reachesMail, shellWord } from './launch.js';
+import { harnessOf, isAddressOf, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
 import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, typeIntoTab, useMailbox } from './orca.js';
 
 /**
@@ -360,17 +360,37 @@ function whoIsWriting(bots, sender, tab, asked = '--from <bot>/<session>: which
   return found;
 }
 
-/** The session the book says is in this Orca tab, wherever in the fleet it is. */
-function sessionInTab(bots, tab) {
+/**
+ * The session the book says is in this Orca tab, wherever in the fleet it is,
+ * when the caller is that session.
+ *
+ * A Codex session is the caller only when the kit's launch line started the
+ * Codex it runs under: `shell` is the mark that line leaves, and everything the
+ * harness runs inherits it. A Codex that Orca brought back by itself has no
+ * mark and no `--no-daemon`, so it runs its commands in Codex's shared
+ * background server, whose every process carries the tab of whichever session
+ * started it (#408). Its tab then says nothing about who is asking. Inside
+ * Codex's sandbox `ps` does not run, so the environment is all there is to go
+ * on. A Claude session has no such server, and one Orca brought back is still
+ * the session in its tab.
+ */
+export function sessionInTab(bots, tab, shell = process.env[SHELL_ENV]) {
   for (const name of botNames(bots)) {
     const book = readBook(botDir(bots, name));
     for (const [session, entry] of Object.entries(book.sessions)) {
-      if (entry?.tab === tab) return findSession(bots, `${name}/${session}`);
+      if (entry?.tab !== tab) continue;
+      const found = findSession(bots, `${name}/${session}`);
+      if (found.harness === 'codex' && (shell === undefined || shell === '')) throw new Error(notTheCodexInTab(found, tab));
+      return found;
     }
   }
   return undefined;
 }
 
+/** Why a caller in a Codex session's tab is not taken to be that session, and what puts it right. */
+const notTheCodexInTab = (found, tab) =>
+  `this command takes its caller from the Orca tab it runs in, ${tab}, which is ${found.bot}/${found.session}'s, a Codex session; but it did not come from a Codex the kit started there: nothing of the kit's launch line is in its environment. A Codex that Orca brought back by itself, after a restart or an update, runs its commands in Codex's shared background server, under the tab of whichever session started that server, so the kit cannot tell which session is asking. Nothing was done. \`${shellWord(ownCli())} restart --bots ${shellWord(found.bots)} --bot <bot> --session <name>\` starts each such session on the kit's line; \`${shellWord(ownCli())} health --bots ${shellWord(found.bots)}\` names them. If Codex then shows "This conversation is open in another app", Codex's shared background server still holds that conversation, and it can outlive the session that started it: once every such session is back on the kit's line, stop the server with Codex's own \`codex app-server daemon stop\`, then restart the stuck session again. That stops the server for everything using it, Codex sessions outside the kit included, so first check that nothing else needs it.`;
+
 /**
  * The message as it will travel: the text itself when it is short enough, and
  * otherwise a file beside the bots folder with a body that names it.
@@ -442,11 +462,19 @@ function nudge(to, from, subject) {
     if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure };
     if (found.handle === undefined) return { nudged: false };
 
-    typeIntoTab(
+    const sent = typeIntoTab(
       found.handle,
       `Fleet mail from ${from.bot}/${from.session}: ${subject}. Read it with  ${shellWord(ownCli())} message check --bots ${shellWord(to.bots)} --bot ${shellWord(to.bot)} --session ${shellWord(to.session)}`,
+      { watch: true },
     );
-    return { nudged: true };
+    // Typed is not taken. A harness busy with a turn queues the line and gives
+    // it no turn of its own, and a line can be lost, and Orca's receipt looks
+    // the same for both: only a turn start it saw says the line landed (#394).
+    if (sent?.send?.prompt?.stages?.includes('turn_started')) return { nudged: true };
+    // Where Orca did not watch the line at all, as when its own notice has
+    // just started a turn in the tab, it saw nothing either way, and says so.
+    if (sent?.send?.prompt?.observation === 'unsupported') return { nudged: true, nudgeUnseen: unseen(sent), nudgeWatched: false };
+    return { nudged: true, nudgeUnseen: unseen(sent) };
   } catch (error) {
     // The message is already queued, and it is waiting whatever Orca says
     // about the tab. So this is reported rather than thrown: a send that ends
@@ -457,6 +485,14 @@ function nudge(to, from, subject) {
   }
 }
 
+/** Orca's words about a line it did not see start a turn, or what its receipt says when it gives none. */
+function unseen(sent) {
+  const warnings = Array.isArray(sent?.warnings) ? sent.warnings.filter((warning) => typeof warning === 'string') : [];
+  if (warnings.length > 0) return warnings.join(' ');
+  const stages = sent?.send?.prompt?.stages;
+  return `Orca's receipt shows ${Array.isArray(stages) ? stages.join(', ') : 'no stages'} and no turn start`;
+}
+
 /**
  * The look before the nudge. Orca now and then refuses a handle it has just
  * listed as stale, and a fresh listing hands out one that works (tech notes,

package/src/orca.js

@@ -584,20 +584,28 @@ export const closeTab = (handle) =>
  * The wait is short because the caller is telling a session it has mail, not
  * handing it work: mail that has to wait for the next check is a smaller cost
  * than a command that hangs for half a minute.
+ *
+ * With `watch`, the line is sent with that wait from the start, and Orca's
+ * receipt says whether it saw the line start a turn (#394). It gives back
+ * Orca's `result`: the receipt is in its `send.prompt`, and Orca's words about
+ * a turn it did not see in its `warnings`.
  */
-export function typeIntoTab(handle, text) {
+export function typeIntoTab(handle, text, { watch = false } = {}) {
   const args = ['terminal', 'send', '--terminal', handle, '--text', text, '--enter'];
-  const answer = ask(args);
-  if (answer.ok === true) return answer.result.send;
+  const answer = ask(watch ? [...args, '--wait-submit', String(SUBMIT_WAIT_S)] : args);
+  if (answer.ok === true) return answer.result;
 
   const again = answer.error?.data?.orchestrationRequestId;
   if (answer.error?.code !== 'agent_prompt_blocked' || typeof again !== 'string') {
     throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
   }
-  return orca([...args, '--retry-request', again, '--wait-submit', String(SUBMIT_WAIT_S)]).send;
+  return orca([...args, '--retry-request', again, '--wait-submit', String(SUBMIT_WAIT_S)]);
 }
 
-/** How long a re-issued line is given to be submitted before Orca gives up on it. */
+/**
+ * How long a watched or re-issued line is given to be submitted before Orca
+ * gives up on it. An idle harness started its turn in about 2 s, live (#394).
+ */
 const SUBMIT_WAIT_S = 5;
 
 /** Where Orca names the terminal a process runs in, in every pane it opens. */

package/src/retire.js

@@ -9,12 +9,15 @@
 // What goes is what the kit made for it: its tabs, closed one at a time by
 // their own handles; its Orca project, after the tabs and never before; its
 // start-prompt files beside the bots folder; and, for a bot, the skill links
-// the kit made in its folder. A tab the book does not name is the user's, so a
+// the kit made in its folder. A prompt file that cannot be removed, as under a
+// harness's sandbox that may not write beside the bots folder, does not stop a
+// retire halfway: nothing reads it once its session is gone, so the retire
+// finishes and names it, with how to remove it (#393). A tab the book does not name is the user's, so a
 // bot whose project holds one is not retired until they have dealt with it.
 //
 // Closing a tab here ends the conversation in it on purpose, so unlike a
 // restart or a pause it does not wait for the book to know which one it was.
-// The mailbox Runs stay: Orca has no way to remove one (ADR 0018).
+// The mailbox Runs stay: Orca has no way to remove one (ADR 0030).
 
 import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import path from 'node:path';
@@ -31,7 +34,8 @@ import { promptPath, sessionsOf } from './up.js';
 export const retiredDir = (bots) => path.join(bots, 'retired');
 
 /**
- * Retire the session `session` of the bot `bot`. Returns `{ bot, session, closed }`.
+ * Retire the session `session` of the bot `bot`. Returns `{ bot, session,
+ * closed }`, and `promptsLeft` when its prompt file could not be removed.
  */
 export async function retireSession(bots, { bot, session }) {
   const home = fleetMember(bots, bot, 'retire', session);
@@ -47,15 +51,16 @@ export async function retireSession(bots, { bot, session }) {
     delete book.sessions[session];
     book.retired = [...(Array.isArray(book.retired) ? book.retired : []), { name: session, ...entry, retired: at }];
   });
-  rmSync(promptPath(bots, bot, session), { force: true });
+  const left = removePrompts([promptPath(bots, bot, session)]);
 
-  return { bot, session, closed };
+  return { bot, session, closed, ...left };
 }
 
 /**
  * Retire the bot `bot`. Returns `{ bot, closed, project, windowReloaded, moved }`:
  * the tabs it closed, the Orca project it took away (if it had one), whether
- * Orca's window was reloaded after that, and where the bot is now.
+ * Orca's window was reloaded after that, and where the bot is now; and
+ * `promptsLeft` when a prompt file could not be removed.
  * When Orca does not confirm the project gone, it returns `{ bot, closed,
  * project, trouble }` instead, and the bot is left where it was.
  */
@@ -103,12 +108,28 @@ export async function retireBot(bots, { bot }) {
     windowReloaded = reloadWindow();
   }
 
-  for (const name of new Set([...known.sessions, ...booked].map((session) => session.name))) {
-    rmSync(promptPath(bots, bot, name), { force: true });
-  }
+  const names = new Set([...known.sessions, ...booked].map((session) => session.name));
+  const left = removePrompts([...names].map((name) => promptPath(bots, bot, name)));
   unlinkSkills(home);
   mkdirSync(retiredDir(bots), { recursive: true });
   renameSync(botDir(bots, bot), moved);
 
-  return { bot, closed, ...(project === undefined ? {} : { project: project.id, windowReloaded }), moved };
+  return { bot, closed, ...(project === undefined ? {} : { project: project.id, windowReloaded }), moved, ...left };
+}
+
+/**
+ * Remove start-prompt files, and say which could not be: `{ promptsLeft: [{
+ * file, reason }] }`, or nothing when every one went. One that is not there is
+ * nothing to remove.
+ */
+function removePrompts(files) {
+  const promptsLeft = files.flatMap((file) => {
+    try {
+      rmSync(file, { force: true });
+      return [];
+    } catch (error) {
+      return [{ file, reason: error.message }];
+    }
+  });
+  return promptsLeft.length === 0 ? {} : { promptsLeft };
 }

package/src/temp.js

@@ -0,0 +1,173 @@
+// `obk temp make` and `obk temp retire`: a session's own temporary sessions
+// (PRD 6.4, #227).
+//
+// Any long-lived session can make a temporary session of its own bot for a
+// piece of work, and retire it when the work is done, without Bot Father, who
+// stays the manager of long-lived sessions. A temporary session is an ordinary
+// session in every other way: in bot.yaml, brought up with a tab and a mailbox,
+// its conversations kept in the book. What makes it temporary is one field of
+// its book entry, `temporary: { maker, made }`, and the book is the one place
+// that says so (ADR 0012).
+//
+// The caller is the session whose tab this runs in, as the book records it: the
+// tab says who is calling now. The maker is kept by its session name, not its
+// tab, so it still owns what it made after a restart gives it a new tab.
+//
+// Everything that can refuse is checked before anything is written, so a
+// refusal leaves bot.yaml, the book and Orca as they were. The one write that
+// may fall outside what a harness's sandbox lets a session write, its start
+// prompt's file beside the bots folder, is made first, the way #383 puts the
+// risky write before bot.yaml: refused there, nothing else has changed, and the
+// same command run again with that access goes through.
+
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { readBook, updateBook } from './book.js';
+import { addSession, dropSession, NAME, readBot } from './bot.js';
+import { isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
+import { sessionInTab } from './message.js';
+import { retireSession } from './retire.js';
+import { bringUp, promptPath } from './up.js';
+
+/** The settings a temporary session takes from its maker unless told otherwise. */
+const INHERITED = ['model', 'effort', 'context', 'approval'];
+
+/**
+ * Make a temporary session of the caller's own bot and bring it up. `given`
+ * holds what the caller said: `name`, `prompt` or `prompt_file`, and any of
+ * `harness` and the inherited settings. Returns `{ bot, session, maker,
+ * settings, up }`, where `up` is what bringing it up answered.
+ */
+export async function makeTemp(bots, { tab, ...given }) {
+  const caller = callerIn(bots, tab, 'make');
+  if (caller.temporary !== undefined) {
+    throw new Error(`${caller.bot}/${caller.session} is a temporary session, and only a long-lived session makes one. Nothing was made.`);
+  }
+  // The name is a folder under work/ and a file beside the bots folder, so it
+  // is held to the rule a bot's name is: one plain name, never a path.
+  if (!NAME.test(given.name)) {
+    throw new Error(`${given.name} cannot be a session's name: a name is lower-case letters, digits and single hyphens, such as review-250. Nothing was made.`);
+  }
+  if (given.prompt === undefined && given.prompt_file === undefined) {
+    throw new Error(`temp make needs the task: --prompt <text> or --prompt-file <path>. Nothing was made.`);
+  }
+  if (given.prompt !== undefined && given.prompt_file !== undefined) {
+    throw new Error(`temp make was given the task twice, as --prompt and as --prompt-file, and a session is told its duty once. Give it one way. Nothing was made.`);
+  }
+
+  const bot = readBot(caller.home, caller.bot);
+  const maker = bot.sessions.find((session) => session.name === caller.session);
+  const settings = { name: given.name };
+  const harness = given.harness ?? maker?.harness;
+  if (harness !== undefined) settings.harness = harness;
+  for (const field of INHERITED) {
+    const value = given[field] ?? maker?.[field];
+    if (value !== undefined) settings[field] = value;
+  }
+  if (given.prompt !== undefined) settings.prompt = given.prompt;
+  else settings.prompt_file = given.prompt_file;
+  settings.work_dir = `work/${given.name}`;
+
+  const written = bot.sessions.some((session) => session.name === given.name) ? undefined : writePromptFirst(bots, caller, settings);
+  // Refuses a name the bot already has, and a setting that will not work,
+  // before it writes anything; the prompt written first goes with a refusal.
+  let added;
+  try {
+    added = addSession(bots, caller.bot, settings);
+  } catch (error) {
+    if (written !== undefined) rmSync(written, { force: true });
+    throw error;
+  }
+  const made = new Date().toISOString();
+  try {
+    await updateBook(caller.home, (book) => {
+      book.sessions[given.name] = { ...book.sessions[given.name], temporary: { maker: caller.session, made } };
+    });
+  } catch (error) {
+    // A session in bot.yaml that the book does not call temporary would be a
+    // long-lived one to everything that reads it, its maker's retire included,
+    // so it is taken back off rather than left that way.
+    const failed = `${caller.bot}/${given.name} could not be recorded in the book as temporary (${error.message})`;
+    try {
+      dropSession(bots, caller.bot, given.name);
+    } catch (undo) {
+      throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}`);
+    }
+    // Off bot.yaml, nothing is made; a prompt file that stays is only a file,
+    // and nothing reads it (#393).
+    try {
+      if (written !== undefined) rmSync(written, { force: true });
+    } catch (left) {
+      throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
+    }
+    throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Run this again once the book can be written.`);
+  }
+
+  let up;
+  try {
+    up = await bringUp(bots, { bot: caller.bot, session: given.name });
+  } catch (error) {
+    const cli = shellWord(ownCli());
+    throw new Error(`${caller.bot}/${given.name} is made, in bot.yaml and in the book as temporary with its maker ${caller.session}, and could not be brought up: ${error.message} Bring it up with  ${cli} up --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}  or retire it with  ${cli} temp retire --bots ${shellWord(bots)} --name ${given.name}`);
+  }
+  return { bot: caller.bot, session: given.name, maker: caller.session, settings: added.session, up };
+}
+
+/**
+ * Write the start prompt's file where bringing the session up will write it,
+ * when its prompt goes to the harness out of a file at all, and say where. A
+ * prompt that cannot be read yet is left to `addSession`, which refuses it in
+ * its own words.
+ */
+function writePromptFirst(bots, caller, settings) {
+  let prompt;
+  try {
+    prompt = startPrompt(settings, { home: caller.home, workDir: workDirOf(settings, caller.home) });
+  } catch {
+    return undefined;
+  }
+  if (isShortPrompt(prompt)) return undefined;
+
+  const file = promptPath(bots, caller.bot, settings.name);
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, prompt);
+  } catch (error) {
+    throw new Error(`${caller.bot}/${settings.name}'s start prompt could not be written to ${file} (${error.message}), and it is written first, so nothing was made. Run this again where that folder can be written: from a harness's sandbox, with the access to write it.`);
+  }
+  return file;
+}
+
+/**
+ * Retire a temporary session the caller made. Returns what `retireSession`
+ * does, with the maker.
+ */
+export async function retireTemp(bots, { tab, name }) {
+  const caller = callerIn(bots, tab, 'retire');
+  const bot = readBot(caller.home, caller.bot);
+  if (!bot.sessions.some((session) => session.name === name)) {
+    throw new Error(`${caller.bot} has no session called ${name}, so there is nothing of yours to retire. Nothing was retired.`);
+  }
+  const temporary = readBook(caller.home).sessions[name]?.temporary;
+  if (temporary === undefined) {
+    throw new Error(`${caller.bot}/${name} is a long-lived session, and those are Bot Father's to retire. Nothing was retired.`);
+  }
+  if (temporary.maker !== caller.session) {
+    throw new Error(`${caller.bot}/${name} is a temporary session ${temporary.maker} made, not ${caller.session}, so it is ${temporary.maker}'s to retire. Nothing was retired.`);
+  }
+  return { ...(await retireSession(bots, { bot: caller.bot, session: name })), maker: caller.session };
+}
+
+/**
+ * The session this runs in, as the book knows it, with its home and whether it
+ * is itself temporary.
+ */
+function callerIn(bots, tab, what) {
+  const found = tab === undefined ? undefined : sessionInTab(bots, tab);
+  if (found === undefined) {
+    throw new Error(`temp ${what} is run by a session in its own tab, and this is not one of the fleet's tabs, so there is no session here to ${what} it for. Nothing was done.`);
+  }
+  const entry = readBook(found.home).sessions[found.session] ?? {};
+  return { bot: found.bot, session: found.session, home: found.home, temporary: entry.temporary };
+}