@assuredloop/orca-bot-kit 0.13.0 → 0.15.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/SETUP.md

@@ -199,7 +199,7 @@ waiting for:
 | Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home) | Codex 0.157.1 |
 | Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; 0.157.1 has had no newer release to offer |
 | `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell | oh-my-zsh bf77e35 |
-| Claude Code's `Teach auto mode about your environment?` | `\x1b` | Esc, which is **Not now**: it would write settings of theirs | Not yet proven: Esc is Not now in Claude Code 2.1.283's code; last seen live on 2.1.278, answered with 2. Not now |
+| Claude Code's `Teach auto mode about your environment?` | `\x1b` | Esc, which cancels it. On 2.1.283 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live on 2.1.283 (#416); 2.1.278 showed a numbered list, answered with 2. Not now |
 
 Each key counts on where the selection starts, as it did on the version named.
 Read the screen in front of you before you send: if the selection is somewhere

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.13.0",
+  "version": "0.15.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/skills/obk-bot-building/SKILL.md

@@ -289,7 +289,7 @@ otherwise `/Applications/Orca.app/Contents/Resources/bin/orca`. A bare
 | Codex's `Where should the new conversation run?` | `\r` | **Current checkout** | Codex 0.157.1 |
 | Codex's update offer, `1. Update now` | `\r` | **Update now**, where it starts | Codex 0.156.1 |
 | `[oh-my-zsh] Would you like to update?` | `n` | no: the user updates it | oh-my-zsh bf77e35 |
-| Claude Code's `Teach auto mode…` | `\x1b` | Esc, **Not now** | Not yet proven, below |
+| Claude Code's `Teach auto mode…` | `\x1b` | Esc cancels; no return | Not yet proven, below |
 
 Each key counts on where the selection starts on the version named. Read the
 screen before you send: if the selection is elsewhere or the options have
@@ -298,9 +298,11 @@ return: on Codex's update offer that took the highlighted **Update now**,
 whatever the digit was. Codex's trust said `1. Yes, continue` on older
 versions. Its hooks review sometimes starts on `2` already: then return alone.
 0.157.1 has had no newer release to offer, so its update offer was proven on
-0.156.1. Claude Code's `Teach auto mode` has not been seen live on 2.1.283:
-Esc is Not now in its code, and 2.1.278 was answered with `2. Not now`.
-Not now, because Yes writes the user's settings. Codex's hooks
+0.156.1. Claude Code's `Teach auto mode` on 2.1.283 is a form, not a list,
+ending `Enter to continue · Esc to cancel`: never send it a return, since
+Enter is Continue, which scans the project, recent sessions and the machine's
+shell history. Esc cancels in its code; that is not yet proven live. On 2.1.278
+it was a numbered list, answered with `2. Not now`. Codex's hooks
 question matters most. The kit's hook is how the book learns which
 conversation the session is running, and until it is answered the
 conversation has not started. Codex's trust applies to the repository root,

package/skills/obk-debugging/SKILL.md

@@ -379,12 +379,16 @@ Write the regression test before the fix, at a seam where it exercises the bug
 the way it actually happened; if there is no correct seam, that is itself the
 finding.
 
-The test is the separate author's to write, as it is for any other behaviour,
-and your reproduction is what the brief is made from: `obk-tdd` has what that
-costs and how the brief goes. Two are often better than one: one at the
-interface saying what a caller should have got, and the smallest one that shows
-the fault where it lives. A test that now looks wrong goes back to its author;
-it is not edited to fit the fix.
+The test is the separate author's to write, as it is for any other behaviour:
+someone with a context of their own, such as a fresh subagent, another session
+or a person, never a fork of this conversation. Give them the requirement and
+what the correct result is, the public interface, and your reproduction as the
+worked example; not your fix, your diff or your plan. They return the tests, the
+command, and the failing output, failing because the bug is there rather than
+because of a typo. `obk-tdd` has more on the brief, if you can load it. Two are
+often better than one: one at the interface saying what a caller should have
+got, and the smallest one that shows the fault where it lives. A test that now
+looks wrong goes back to its author; it is not edited to fit the fix.
 
 Watch it fail. Fix. Watch it pass. Then run the original, unminimised scenario
 again, on the same surface the bug appeared on. A different surface, or an

package/skills/obk-fleet-review/SKILL.md

@@ -227,6 +227,18 @@ ask for and you do it.
 A grooming report is input to this review, not its end: check what it flags
 against the fleet, and recommend from there.
 
+When a grooming report names temporary sessions a bot left behind, offer the
+user one rule for that bot's charter, with the words ready to accept, such as:
+"Retire each temporary session you make as soon as its work is done, and
+before you end a piece of work, check that none of yours is left." On a yes,
+read the bot's charter, add the line, and set the whole with `obk bot change
+--bots <folder> --bot <bot> --charter <text>`, which replaces the charter, so
+what you pass is all of it. On a no, nothing changes, and it is not offered
+again for the same sessions: write the declined offer in grooming's open
+findings, next to those sessions, so it outlasts this conversation. Retire
+none of them yourself, and send nothing to their makers: the hint is for the
+user, and only a maker knows when its work is done.
+
 Sort the problem before you write it up. Something the kit does wrong, or
 cannot do, is filed where the kit's problems are filed, as one issue, in one
 step: no draft to approve first. Something a bot is doing wrong goes back to

package/skills/obk-grilling/NOTICE.md

@@ -73,7 +73,7 @@ words where they are quoted here:
   against the session log (19:12:40, 19:15:38), which is the fix the skill
   gives.
 
-Three deliberate departures from `grilling` and `domain-modeling`, so they are
+Five deliberate departures from `grilling` and `domain-modeling`, so they are
 not mistaken for consolidation:
 
 - **A round is three questions, not the whole frontier.** `grilling` says to

package/skills/obk-grooming/SKILL.md

@@ -185,6 +185,25 @@ Never edit a memory yourself, not even to cut it. The memory is the bot's, the
 harness keeps it, and a pass that rewrites what a bot remembers is a pass that
 decides what the bot knows.
 
+## Temporary sessions left behind
+
+A temporary session is one a bot's own session made for a piece of work with
+`obk temp make`, and its maker retires it when the work is done. Each bot's
+book, `sessions.yaml` in its folder, marks one on its entry as `temporary`,
+with its `maker` and when it was `made`. Read the books every run, a quiet one
+included: a session left behind does no work, so the usage index never shows
+it.
+
+Count one as left behind when its maker is no longer one of the bot's
+sessions, or when it was made more than a day ago. The report names each: the
+bot and session, its maker, saying so where the maker is gone, and how old it
+is. Put them in the open findings, so the next run says whether each is still
+there rather than reporting it as new.
+
+Retire none of them. Only the maker knows when the work is done: a review
+session can be waiting on an open pull request for a re-review. What to do
+about a bot that leaves them behind is the management session's to offer.
+
 ## Say whether this run was worth making
 
 Every run, record which of three things happened: it found something that

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

@@ -8,6 +8,7 @@
 // writes nothing, rather than leave a bot half made or a bot.yaml half edited.
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { parse, parseDocument, stringify } from 'yaml';
@@ -21,7 +22,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';
@@ -114,6 +115,25 @@ function whereItLeads(target) {
 export const displayName = (name) =>
   name.split('-').map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
 
+/**
+ * What Orca is asked to call a bot's project. A fleet whose bots folder is under
+ * the system's temp folder, as a system test's or a live check's is, gets a mark
+ * and the name of the first folder under the temp folder, so its Bot Father is
+ * never taken for the owner's in Orca's sidebar (#401). Every other fleet's
+ * project is called what it always was. Tab titles keep `displayName` either way.
+ */
+export function projectName(bots, name) {
+  let under;
+  try {
+    under = path.relative(realpathSync(os.tmpdir()), realpathSync(bots));
+  } catch {
+    return displayName(name);
+  }
+  // The temp folder itself, or anywhere outside it, is not a throwaway fleet's.
+  if (under === '' || under === '..' || under.startsWith(`..${path.sep}`) || path.isAbsolute(under)) return displayName(name);
+  return `${displayName(name)} · temp fleet ${under.split(path.sep)[0]}`;
+}
+
 /**
  * A bot's own file: which harness its sessions run on unless they say
  * otherwise, and the sessions it keeps.

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-reload.applescript

@@ -1,5 +1,5 @@
 -- Run by the kit as `osascript orca-reload.applescript <Orca.app path>`, after
--- a project was removed (#343, ADR 0025).
+-- a project was removed (#343, ADR 0031).
 --
 -- Orca's window keeps a removed project in its sidebar until the window is
 -- rebuilt (stablyai/orca#23224; once a release fixes it, this can go behind a

package/src/orca-runtime.cjs

@@ -2,7 +2,7 @@
 // CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-runtime.cjs <client> <method> <params> <wait>`.
 //
 // It makes one call to Orca's runtime, through Orca's own client, for a method
-// Orca's CLI does not offer (ADR 0025): `project.update`, which makes Orca's
+// Orca's CLI does not offer (ADR 0031): `project.update`, which makes Orca's
 // window read its projects again (#224), and `terminal.inspectProcess`, which
 // says who is in front of a tab where `ps` cannot (#298). `params` is JSON. It
 // prints the runtime's answer as JSON and exits 0 only when the runtime took

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0025). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0031). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -13,6 +13,9 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { SHELL_ENV } from './launch.js';
+import { TAB_ENV } from './record.js';
+
 // The Orca that works for a normal user: `/usr/local/bin/orca` is a root-only
 // symlink on this machine (tech notes, section 1). OBK_ORCA overrides it, for a
 // machine that keeps Orca somewhere else.
@@ -40,10 +43,14 @@ export function orca(args, { timeoutMs } = {}) {
 /** What an error carries when Orca was given a time and did not answer in it. */
 export const TIMED_OUT = 'orca_timed_out';
 
-/** Orca's refusal as an error, with its code on it, so a caller can tell a stale handle from the rest (#294). */
+/**
+ * Orca's refusal as an error, with its code on it, so a caller can tell a stale
+ * handle from the rest (#294), and its own message as `reason`, so a caller
+ * that goes by the message reads Orca's words rather than the kit's (#405).
+ */
 const refusal = (args, answer) => Object.assign(
   new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`),
-  { code: answer.error?.code },
+  { code: answer.error?.code, reason: answer.error?.message },
 );
 
 /** One Orca command, and the whole envelope back, refusals included. */
@@ -195,7 +202,7 @@ const CLIENT_KILL_MS = 3000;
  *
  * Orca's window re-reads only when its runtime says the projects changed, and
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
- * changes does, and Orca's CLI does not offer it (ADR 0025). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0031). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -206,7 +213,7 @@ export const tellWindow = (projectId) => askRuntime('project.update', { projectI
  * runtime's answer, or undefined when there is none to be had.
  *
  * It goes through Orca's own runtime client out of the installed app, run by
- * Orca's binary the way its `bin/orca` runs its CLI (ADR 0025). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0031). None of that is
  * Orca's published interface, so anything that goes wrong is a quiet
  * undefined: it never throws and is never tried twice.
  */
@@ -243,7 +250,7 @@ const RELOAD_KILL_MS = 5000;
 
 /**
  * Have Orca's window force-reload itself, after a project was removed: true
- * only when it did (#343, ADR 0025).
+ * only when it did (#343, ADR 0031).
  *
  * The window keeps a removed project in its sidebar until it is rebuilt, and
  * `tellWindow` only relabels the row "Unknown" (stablyai/orca#23224; once a
@@ -369,6 +376,9 @@ function screenOf(handle) {
 /** A row the harness starts with its selection pointer: `›` on Codex, `❯` on Claude Code. */
 const POINTER_ROW = /^ *[›❯]/;
 
+/** How a harness's form says it is answered, as Claude Code 2.1.283 draws its foot (#416). */
+const FORM_FOOT = /Enter to (?:continue|confirm|select)\b.*Esc to cancel/i;
+
 /** That pointer on a numbered choice, and the column its number starts in. */
 const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
 
@@ -376,7 +386,7 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Whether the rows of a rendered screen hold a question of the harness's own.
  *
  * Every one seen is a numbered list of choices with the harness's pointer on
- * one (tech notes, section 1; ADR 0025). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0031). The same pointer starts the harness's
  * input line and its echo of the user's past turns, and the input line is the
  * lowest of them whenever it is on screen, so only the lowest pointer row is
  * asked about: a question counts while it stands in the input line's place.
@@ -385,6 +395,13 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  */
 export function questionIn(rows) {
   const at = rows.findLastIndex((row) => POINTER_ROW.test(row));
+  // A form of the harness's own has no numbers but a foot that says how to
+  // answer it: Claude Code 2.1.283's "Teach auto mode" ends `Enter to continue
+  // · Esc to cancel`, and a return there is Continue, which starts a scan
+  // (#416). It counts on or below the lowest pointer row, or anywhere when
+  // there is none: under old words of one in the history, the input line is
+  // the lowest pointer, and nothing below it is a foot.
+  if (rows.slice(Math.max(at, 0)).some((row) => FORM_FOOT.test(row))) return true;
   const pointer = at < 0 ? null : ON_A_CHOICE.exec(rows[at]);
   if (pointer === null) return false;
   const column = pointer[1].length;
@@ -431,9 +448,12 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   // there. The program in front has to be the agent Orca names. With no name
   // it may be a harness a few seconds into its launch; under another name it
   // may be a pager started after the harness quit, under an identity Orca has
-  // not let go of (tech notes, section 1). A harness run through a wrapper such
-  // as `node` lands here too, until #261.
-  if (seen.front === undefined || seen.agent === undefined || seen.command !== seen.agent) {
+  // not let go of (tech notes, section 1). A harness run under another name,
+  // such as `node` for an npm install, passes on the kit's own mark instead
+  // (#261).
+  // Either way Orca has to name an agent there: a harness it has not named yet
+  // may be seconds into its launch and not ready for a line.
+  if (seen.front === undefined || seen.agent === undefined || (seen.command !== seen.agent && !launchedHere(seen.pid, tabId))) {
     const why = seen.front === undefined
       ? seen.unreadable
       : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
@@ -449,6 +469,25 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   return { handle: live.handle, agent: seen.agent };
 }
 
+/**
+ * Whether the process `pid`, in front of the tab `tabId`, is the harness the
+ * kit's launch line started there, whatever it is called (#261). The line sets
+ * `OBK_TAB_SHELL` to the tab's shell's pid, for the harness alone and not
+ * exported, so the harness carries it, with its parent that shell. A program
+ * the shell starts later, such as `less` after the harness quit (#232), has no
+ * mark. A program the harness starts carries the mark, and its parent is the
+ * harness. A tab Orca restored by itself has no mark at all. Only whole words
+ * of the environment count, and anything unread is a no.
+ */
+function launchedHere(pid, tabId) {
+  if (pid === undefined) return false;
+  const words = wordsOfProcess(pid);
+  if (words === undefined || !words.includes(`${TAB_ENV}=${tabId}`)) return false;
+  const marks = words.filter((word) => new RegExp(`^${SHELL_ENV}=[0-9]+$`).test(word));
+  const own = psLine(pid);
+  return marks.length === 1 && own !== undefined && Number(marks[0].slice(SHELL_ENV.length + 1)) === own.ppid;
+}
+
 /**
  * Who holds the terminal of the tab `handle`, as `frontOf` answers, without
  * waiting on the tab: for a caller that asks about every tab and has nothing
@@ -475,7 +514,7 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  *
  * `ps` is asked first. Where it cannot read the tab, as inside Codex's
  * sandbox, where it does not start at all, Orca's runtime is asked instead
- * (#298, ADR 0025).
+ * (#298, ADR 0031).
  */
 function frontOf(handle, ptyId) {
   const read = frontByPs(ptyId);
@@ -511,7 +550,7 @@ function frontByOrca(handle) {
  * Who holds the terminal of the pane `ptyId`, as `ps` says it.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0025).
+ * gives that pid's terminal's foreground process group (ADR 0031).
  * On macOS the pane is `login` with the shell as its child, so the shell is in
  * front when the group is the pane's own or that of a child of a `login` pane.
  * `diagnostics memory` is a diagnostics command and may change, so everything
@@ -563,14 +602,25 @@ function psLine(pid) {
 /**
  * Close one tab, by the handle Orca issued for it.
  *
- * The only place in the kit that takes anything away, and it takes away one
- * tab: `--terminal <handle> --tab`. Orca's other form, `--worktree <sel> --all`,
+ * With `closeTerminal` below, the only place in the kit that takes anything
+ * away, and each takes away one tab: `--terminal <handle> --tab`. Orca's other
+ * form, `--worktree <sel> --all`,
  * closes every tab of a project with its layouts and resume records, which are
  * the user's work and not the kit's to end (tech notes, section 1).
  */
 export const closeTab = (handle) =>
   orca(['terminal', 'close', '--terminal', handle, '--tab']).close;
 
+/**
+ * Close one terminal without `--tab`: for a tab of one pane, as every tab the
+ * kit opens is, Orca then closes that tab by its id and stops its process (read
+ * in the 1.4.215 bundle). Only for a tab `--tab` could not find (#405): Orca
+ * looks a `--tab` close up in a tab snapshot of its own, which a tab it still
+ * lists can be missing from after a restart, and answers `tab_not_found`.
+ */
+export const closeTerminal = (handle) =>
+  orca(['terminal', 'close', '--terminal', handle]).close;
+
 /**
  * Type `text` into a tab and press return.
  *
@@ -584,20 +634,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/pause.js

@@ -14,7 +14,7 @@ import { realpathSync } from 'node:fs';
 
 import { botDir, markPaused, readBot } from './bot.js';
 import { DAILY_SESSION } from './init.js';
-import { closeTabs, tabsToClose } from './restart.js';
+import { closeTabs, commandLine, tabsToClose } from './restart.js';
 import { BOT_FATHER, botsNamed, bringUp, sessionsOf } from './up.js';
 
 /**
@@ -30,7 +30,7 @@ export async function pauseSessions(bots, { bot, session }) {
   // they were.
   const going = tabsToClose(bots, bot, home, sessions);
   const changed = markPaused(bots, bot, session, true);
-  const closed = await closeTabs(home, going, bots, bot);
+  const closed = await closeTabs(home, going, bots, bot, commandLine('pause', bots, bot, session));
   return { bot, session, changed, closed };
 }
 

package/src/restart.js

@@ -34,7 +34,7 @@ import { setTimeout as pause } from 'node:timers/promises';
 import { bookFile, readBook } from './book.js';
 import { botDir, readBot } from './bot.js';
 import { ownCli, shellWord } from './launch.js';
-import { closeTab, findProject, frontOfTab, tabs } from './orca.js';
+import { closeTab, closeTerminal, findProject, frontOfTab, orcaCli, tabs } from './orca.js';
 import { botsNamed, bringUp, prepareBots, sessionsOf } from './up.js';
 
 /**
@@ -68,7 +68,7 @@ export async function restartSessions(bots, { bot: name, session: onlySession }
   }
 
   const going = tabsToClose(bots, name, home, sessions.filter((session) => session.paused !== true), { quit: true });
-  const closed = await closeTabs(home, going, bots, name);
+  const closed = await closeTabs(home, going, bots, name, commandLine('restart', bots, name, onlySession));
   return { closed, ...(await bringUp(bots, { bot: name, session: onlySession })) };
 }
 
@@ -113,12 +113,14 @@ export function tabsToClose(bots, name, home, sessions, { keepless = false, quit
 /**
  * Close the tabs `tabsToClose` gave, one at a time by their own handles, and
  * wait until Orca's listing agrees they are gone. Returns one entry per tab.
+ * `again` is the command that asked, as the user would run it again: what to do
+ * once a tab Orca would not close has been closed by hand.
  */
-export async function closeTabs(home, going, bots, name) {
+export async function closeTabs(home, going, bots, name, again) {
   const closed = [];
   for (const { name: session, tab } of going) {
     try {
-      closeTab(tab.handle);
+      closeWhole(tab.handle, again);
     } catch (error) {
       // A tab that would not close still holds its session, so nothing is
       // opened after this: two harnesses on one conversation is worse than a
@@ -132,6 +134,41 @@ export async function closeTabs(home, going, bots, name) {
   return closed;
 }
 
+/**
+ * Close one session's tab. Orca finds a `--tab` close in a tab snapshot of its
+ * own, which a tab it still lists can be missing from after a restart, and then
+ * answers `tab_not_found` (#405, read in the 1.4.215 bundle). The same terminal
+ * closed without `--tab` closes its one-pane tab by id, so that is done instead,
+ * and `gone` checks the tab went as it does after any close. Every other
+ * refusal stops the restart as it did.
+ */
+function closeWhole(handle, again) {
+  try {
+    closeTab(handle);
+  } catch (error) {
+    if (!notFound(error)) throw error;
+    try {
+      closeTerminal(handle);
+    } catch (second) {
+      // With the tab closed by hand there is nothing left for the command to
+      // close, so running it again finishes it, whichever command it was.
+      throw new Error(`${error.message}, and then ${second.message}. Close it by hand, then run the same command again: ${shellWord(orcaCli())} terminal close --terminal ${shellWord(handle)}  then  ${again}`);
+    }
+  }
+}
+
+/**
+ * Whether Orca refused a `--tab` close for a tab it could not find: its code,
+ * or its 1.4.215 form of code `runtime_error` with exactly that message. Orca's
+ * own words, never the kit's wrapped text, and no other form (#405).
+ */
+const notFound = (error) =>
+  error.code === 'tab_not_found' || (error.code === 'runtime_error' && error.reason === 'tab_not_found');
+
+/** A command of the kit's as the user would type it, for a message to name. */
+export const commandLine = (verb, bots, bot, session) =>
+  `${shellWord(ownCli())} ${verb} --bots ${shellWord(bots)} --bot ${bot}${session === undefined ? '' : ` --session ${session}`}`;
+
 /** How long Orca is given to stop listing a tab it has closed, and how often it is asked. */
 const SETTLED_MS = 5000;
 const ASK_MS = 100;

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';
@@ -23,7 +26,7 @@ import { readBook, tabIdsIn, updateBook } from './book.js';
 import { botDir, dropSession, readBot } from './bot.js';
 import { deleteProject, findProject, projects, reloadWindow, tabs } from './orca.js';
 import { fleetMember } from './pause.js';
-import { closeTabs, tabsToClose } from './restart.js';
+import { closeTabs, commandLine, tabsToClose } from './restart.js';
 import { unlinkSkills } from './skills.js';
 import { promptPath, sessionsOf } from './up.js';
 
@@ -31,13 +34,14 @@ 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);
   const sessions = sessionsOf(readBot(home, bot), session);
 
-  const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot);
+  const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, commandLine('retire', bots, bot, session));
   dropSession(bots, bot, session);
 
   const at = new Date().toISOString();
@@ -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.
  */
@@ -81,7 +86,7 @@ export async function retireBot(bots, { bot }) {
   // taken away with one of them still open. `closeTabs` waits until Orca agrees
   // they are gone.
   const booked = Object.keys(readBook(home).sessions).map((name) => ({ name }));
-  const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot);
+  const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot, commandLine('retire', bots, bot));
   let windowReloaded;
   if (project !== undefined) {
     deleteProject(project.id);
@@ -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 };
+}

package/src/up.js

@@ -9,7 +9,7 @@ import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
 import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, sessionIdsIn, tabIdsIn, takeMailboxTurn, updateBook, withUnclaimed } from './book.js';
-import { botDir, botNames, displayName, readBot } from './bot.js';
+import { botDir, botNames, displayName, projectName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { writePermissions } from './permissions.js';
@@ -211,7 +211,7 @@ async function bringUpBot(bots, home, bot, onlySession) {
   // Orca is asked first and the book is written after: nothing that takes time
   // happens while the book is held, because a session's own hook may be writing
   // its id into that same file at any moment.
-  const { change, ...orca } = orcaProject(home, title);
+  const { change, ...orca } = orcaProject(home, projectName(bots, name));
   await updateBook(home, (book) => { book.orca = orca; });
   // Orca's window does not see a project made or renamed on the command line
   // until it is told (#224).