@assuredloop/orca-bot-kit 0.26.1 → 0.28.0

package/src/skills.js

@@ -24,11 +24,11 @@ import { fileURLToPath } from 'node:url';
 import { parse, parseDocument, stringify } from 'yaml';
 
 import { bookFile, readBook, takeLineTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
-import { botDir, botNames, changesExactly, leadsOutside, readBot, YAML_OUT } from './bot.js';
+import { botDir, botNames, changesExactly, leadsOutside, readBot, refuseOutside, withBotTurn, writeWhole, YAML_OUT } from './bot.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
-import { orcaCli, orcaTrouble, tabToTypeInto, typeIntoTab } from './orca.js';
+import { orcaTrouble, tabToTypeInto, typeIntoTab } from './orca.js';
 import { listIn } from './rules.js';
-import { cloneDir, isCloned, readSources, skillsIn, wrongClone } from './sources.js';
+import { cloneDir, isCloned, leavesClone, readSources, skillsIn, wrongClone } from './sources.js';
 
 /** The kit's own skills, inside the installed package. */
 const KIT_SKILLS = fileURLToPath(new URL('../skills', import.meta.url));
@@ -84,25 +84,28 @@ export function addSkill(bots, bot, ref) {
     throw new Error(`there is no bot called ${bot} in ${bots}: ${file} is not there. Create it with obk bot create.`);
   }
 
-  if (listIn(file, 'skills').includes(ref)) return { bot, home, skill: ref, state: 'there' };
-
-  const was = readFileSync(file, 'utf8');
-  const doc = parseDocument(was);
-  const listed = doc.get('skills', true);
-  if (listed?.items === undefined) {
-    // No list to add to: an empty `skills:`, or no skills key at all.
-    doc.set('skills', [ref]);
-  } else {
-    listed.flow = false;
-    doc.addIn(['skills'], ref);
-  }
+  return withBotTurn(home, () => {
+    if (listIn(file, 'skills').includes(ref)) return { bot, home, skill: ref, state: 'there' };
+    refuseOutside(home, file);
 
-  const text = doc.toString(YAML_OUT);
-  if (!changesExactly(was, text, (had) => ({ ...had, skills: [...(had.skills ?? []), ref] }))) {
-    throw new Error(`${file} cannot have a skill added to it without changing something else in it, so nothing was written. Add ${ref} to its skills list by hand.`);
-  }
-  writeFileSync(file, text);
-  return { bot, home, skill: ref, state: 'added' };
+    const was = readFileSync(file, 'utf8');
+    const doc = parseDocument(was);
+    const listed = doc.get('skills', true);
+    if (listed?.items === undefined) {
+      // No list to add to: an empty `skills:`, or no skills key at all.
+      doc.set('skills', [ref]);
+    } else {
+      listed.flow = false;
+      doc.addIn(['skills'], ref);
+    }
+
+    const text = doc.toString(YAML_OUT);
+    if (!changesExactly(was, text, (had) => ({ ...had, skills: [...(had.skills ?? []), ref] }))) {
+      throw new Error(`${file} cannot have a skill added to it without changing something else in it, so nothing was written. Add ${ref} to its skills list by hand.`);
+    }
+    writeWhole(file, text);
+    return { bot, home, skill: ref, state: 'added' };
+  });
 }
 
 /**
@@ -118,19 +121,22 @@ export function removeSkill(bots, bot, ref) {
     throw new Error(`there is no bot called ${bot} in ${bots}: ${file} is not there.`);
   }
 
-  const index = listIn(file, 'skills').indexOf(ref);
-  if (index === -1) return { bot, home, skill: ref, state: 'absent' };
+  return withBotTurn(home, () => {
+    const index = listIn(file, 'skills').indexOf(ref);
+    if (index === -1) return { bot, home, skill: ref, state: 'absent' };
+    refuseOutside(home, file);
 
-  const was = readFileSync(file, 'utf8');
-  const doc = parseDocument(was);
-  doc.deleteIn(['skills', index]);
+    const was = readFileSync(file, 'utf8');
+    const doc = parseDocument(was);
+    doc.deleteIn(['skills', index]);
 
-  const text = doc.toString(YAML_OUT);
-  if (!changesExactly(was, text, (had) => ({ ...had, skills: had.skills.filter((one, at) => at !== index) }))) {
-    throw new Error(`${file} cannot have a skill taken off it without changing something else in it, so nothing was written. Take ${ref} off its skills list by hand.`);
-  }
-  writeFileSync(file, text);
-  return { bot, home, skill: ref, state: 'removed' };
+    const text = doc.toString(YAML_OUT);
+    if (!changesExactly(was, text, (had) => ({ ...had, skills: had.skills.filter((one, at) => at !== index) }))) {
+      throw new Error(`${file} cannot have a skill taken off it without changing something else in it, so nothing was written. Take ${ref} off its skills list by hand.`);
+    }
+    writeWhole(file, text);
+    return { bot, home, skill: ref, state: 'removed' };
+  });
 }
 
 /**
@@ -438,7 +444,7 @@ const LOOK_MS = 2000;
  * `blocked`) or `unknown` (with `trouble`).
  *
  * Claude Code gets `/reload-skills` typed into its tab, through the same gate
- * as the mail nudge. A busy session queues it and runs it as a command when
+ * as the mail interrupt. A busy session queues it and runs it as a command when
  * its turn ends, so it never reaches the model as text. Codex has no reload
  * command and takes the change at the start of its next turn by itself, so
  * nothing is typed, and the caller is given the SKILL.md of each skill linked
@@ -472,7 +478,10 @@ function tellSessions(home, bot, linked) {
     const told = { session: session.name, harness };
     const tab = typeof book[session.name]?.tab === 'string' ? book[session.name].tab : undefined;
     if (tab === undefined) return { ...told, state: 'not-up' };
-    if (down !== undefined) return { ...told, state: 'unknown', trouble: `Orca is not answering at ${orcaCli()}, so the kit could not look at its tab, and nothing was typed` };
+    // Skills reach a Pi session in a later slice (#547), and nothing is typed
+    // into its tab before then.
+    if (harness === 'pi') return { ...told, state: 'unknown', trouble: 'it runs on Pi, and the kit does not give a Pi session skills yet, so nothing was typed' };
+    if (down !== undefined) return { ...told, state: 'unknown', trouble: `the kit could not look at its tab, and nothing was typed: ${down}` };
     let turn;
     try {
       // The session's turn for a line (#482), for the look and its line. Codex
@@ -564,7 +573,14 @@ function follow(bots, ref, sources) {
       }
       const wrong = wrongClone(bots, source);
       if (wrong !== undefined) throw new Error(`${ref}: ${wrong}`);
-      return path.join(skillsIn(bots, source), after);
+      // The pinned clone is the only place a source's skill comes from. A path,
+      // a skill name or a link the repo committed can lead out of it (#571).
+      const inClone = path.join(skillsIn(bots, source), after);
+      const real = leavesClone(bots, named, inClone);
+      if (real !== undefined) {
+        throw new Error(`${ref} leads outside the clone of the source ${named}, to ${real}, and a skill from a source comes only from the version skills.yaml pins for it. Name a skill inside ${cloneDir(bots, named)} with no link out of it.`);
+      }
+      return inClone;
     },
     common: () => path.join(bots, 'skills', ref),
     // The user's own spelling: absolute, at their home, or read from the bots

package/src/sources.js

@@ -14,11 +14,11 @@
 // file, so the difference is theirs to see.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseDocument } from 'yaml';
 
-import { changesExactly, requireBotsFolder, YAML_OUT } from './bot.js';
+import { changesExactly, leadsOutside, requireBotsFolder, YAML_OUT } from './bot.js';
 import { ownCli, shellWord } from './launch.js';
 
 /** The user's file that lists where skills come from. */
@@ -65,6 +65,9 @@ export function addSource(bots, { name, repo, ref, path: inside }) {
   if (TAKEN.includes(name)) {
     throw new Error(`${name} is the kit's own shelf, which a bot names kit:<name>, so a source cannot be called that. Call it something else.`);
   }
+  if (inside !== undefined && !staysInRepo(inside)) {
+    throw new Error(`${inside} cannot be the path of the source ${name}: it leads out of the repo, and a path is a subfolder inside it, such as skills.`);
+  }
 
   const file = path.join(bots, SKILLS_YAML);
   // Read through the same reader every other command uses, so a file this one
@@ -151,7 +154,6 @@ function bring(bots, source, moving) {
     const wrong = wrongClone(bots, source);
     if (wrong !== undefined) {
       if (!moving) throw new Error(wrong);
-      rmSync(dir, { recursive: true, force: true });
       return clone(bots, source, source.ref, false);
     }
 
@@ -174,11 +176,16 @@ function bring(bots, source, moving) {
  * Clone a source and check it out out of the way, and put it in place only once
  * both have worked. `<name>.fetching` is where it happens; a run that cannot
  * finish leaves that behind and not a source.
+ *
+ * A clone already there, from a repository the file no longer names, stays
+ * where it is until the new one is ready (#568). It may hold the user's own
+ * files, and a replacement that fails must not cost them.
  */
 function clone(bots, source, rev, recorded) {
   mkdirSync(sourcesDir(bots), { recursive: true });
   const dir = cloneDir(bots, source.name);
   const fetching = `${dir}.fetching`;
+  const replaced = `${dir}.replaced`;
 
   try {
     rmSync(fetching, { recursive: true, force: true });
@@ -186,7 +193,25 @@ function clone(bots, source, rev, recorded) {
     // repository and never one of git's own options, whatever it begins with.
     git(['clone', '--quiet', '--', source.repo, fetching], undefined, `${source.name}: ${source.repo} could not be cloned`);
     checkout(fetching, source, rev, recorded);
-    renameSync(fetching, dir);
+    if (existsSync(dir)) {
+      rmSync(replaced, { recursive: true, force: true });
+      renameSync(dir, replaced);
+      try {
+        renameSync(fetching, dir);
+      } catch (error) {
+        renameSync(replaced, dir);
+        throw error;
+      }
+      // The new clone is in place, so the update has worked. An old copy that
+      // will not go stays beside it, where health names it as a leftover.
+      try {
+        rmSync(replaced, { recursive: true, force: true });
+      } catch {
+        // Nothing to undo.
+      }
+    } else {
+      renameSync(fetching, dir);
+    }
   } finally {
     rmSync(fetching, { recursive: true, force: true });
   }
@@ -250,6 +275,47 @@ function git(args, cwd, trouble) {
   return result.stdout.trim();
 }
 
+/**
+ * Whether a source's path, as written, names a folder inside its repo: not an
+ * absolute path, and no `..` that climbs above the top (#571). A link inside the
+ * clone can still lead out; `skills build` follows it before linking.
+ */
+const staysInRepo = (inside) => !path.isAbsolute(inside) && path.normalize(inside).split(path.sep)[0] !== '..';
+
+/**
+ * Where a source's skill at `dir` really leads when a link takes it, or anything
+ * in it, out of the source's clone; undefined when all of it stays inside (#571).
+ * A harness reads any file in a skill, so the whole folder is walked, through
+ * the links that stay inside as well.
+ */
+export function leavesClone(bots, name, dir) {
+  const clone = cloneDir(bots, name);
+  const seen = new Set();
+  const walk = (at) => {
+    const real = leadsOutside(clone, at);
+    if (real !== undefined) return real;
+    let entries;
+    try {
+      const where = realpathSync.native(at);
+      // A folder reached twice, through a link back into the skill, is walked once.
+      if (seen.has(where) || !statSync(where).isDirectory()) return undefined;
+      seen.add(where);
+      entries = readdirSync(where);
+    } catch (error) {
+      // Nothing there: whatever links it says so.
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return undefined;
+      // A folder the kit may not read can hold a link out, and nothing shows it.
+      throw new Error(`${name}: the kit could not read ${at} (${error.code ?? error.message}), so it cannot tell whether anything in the skill leads out of the source's clone, and it links nothing from there.`);
+    }
+    for (const entry of entries) {
+      const found = walk(path.join(at, entry));
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  return walk(dir);
+}
+
 /** Where a source's skills sit inside its clone: its root, or the subfolder it names. */
 export const skillsIn = (bots, source) => path.join(cloneDir(bots, source.name), source.path ?? '');
 
@@ -331,6 +397,9 @@ export function readSources(file) {
     if (source.path !== undefined && typeof source.path !== 'string') {
       throw new Error(`${file}: the source ${name} has a path that is not a subfolder inside the repo.`);
     }
+    if (source.path !== undefined && !staysInRepo(source.path)) {
+      throw new Error(`${file}: the source ${name} has the path ${source.path}, which leads out of the repo, and a path is a subfolder inside it, such as skills.`);
+    }
     return source;
   });
 }

package/src/temp.js

@@ -75,6 +75,9 @@ export async function makeTemp(bots, { tab, ...given }) {
 
   const maker = bot.sessions.find((session) => session.name === caller.session);
   const { settings, chosen } = settingsFor(bot, maker, role?.option ?? {}, given);
+  if (chosen.harness.value === 'pi') {
+    throw new Error(`${name} would run on Pi, and a temporary session on Pi comes in a later slice of #547. Make it on claude or codex. Nothing was made.`);
+  }
   refuseWiderApproval(bots, caller, bot, maker, given.approval);
   refuseApprovalArgs(chosen.harness.value, given.extra_args);
   settings.name = name;
@@ -83,27 +86,42 @@ export async function makeTemp(bots, { tab, ...given }) {
   else settings.prompt_file = given.prompt_file ?? role.prompt_file;
   settings.work_dir = `work/${name}`;
 
-  const written = bot.sessions.some((session) => session.name === name) ? undefined : writePromptFirst(bots, caller, settings);
   // bot.yaml and the book are written under the book's lock, so that a second
   // make from the same maker waits, and then sees this one (#464). addSession
   // refuses a name the bot already has, and a setting that will not work,
   // before it writes anything.
   const made = new Date().toISOString();
   let locked = false;
+  let written;
   let added;
   try {
     await updateBook(caller.home, (book) => {
       locked = true;
       refuseNested(bots, caller, book);
       if (role !== undefined) refuseCap(caller, role, book);
-      added = addSession(bots, caller.bot, settings);
+      // The prompt file is written under the lock too, and only for a name the
+      // bot does not have yet: a make of the same name that waited on this one
+      // writes nothing, so it has nothing of this one's to remove (#572).
+      written = readBot(caller.home, caller.bot).sessions.some((session) => session.name === name) ? undefined : writePromptFirst(bots, caller, settings);
+      try {
+        added = addSession(bots, caller.bot, settings);
+      } catch (error) {
+        // Taken back while the lock is held: once it is let go, another make
+        // of this name may write the same file.
+        const left = removeWritten(written);
+        if (left !== undefined) throw promptLeft(error.message.replace(/ ?Nothing was made\.$/, ''), written, left);
+        throw error;
+      }
       const kind = role === undefined ? {} : { role: role.name, option: role.option.name };
       book.sessions[name] = { ...book.sessions[name], temporary: { maker: caller.session, made, ...kind } };
     });
   } catch (error) {
-    // A refusal under the lock has written nothing but the prompt file.
-    const refused = locked && added === undefined;
+    // A refusal under the lock has written nothing, or taken its prompt file back.
+    if (locked && added === undefined) throw error;
     const failed = `${caller.bot}/${name} could not be recorded in the book as temporary (${error.message})`;
+    // The prompt file goes while the session is still in bot.yaml, where it
+    // keeps any other make of its name from writing that file.
+    const left = removeWritten(written);
     // 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.
@@ -114,15 +132,8 @@ export async function makeTemp(bots, { tab, ...given }) {
         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 ${name}`);
       }
     }
-    // Off bot.yaml, nothing is made; a prompt file that stays is only a file,
-    // and nothing reads it (#393).
-    const why = refused ? error.message.replace(/ ?Nothing was made\.$/, '') : `${failed}${added === undefined ? '.' : ', so it was taken back off bot.yaml.'}`;
-    try {
-      if (written !== undefined) rmSync(written, { force: true });
-    } catch (left) {
-      throw new Error(`${why} Nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
-    }
-    if (refused) throw error;
+    const why = `${failed}${added === undefined ? '.' : ', so it was taken back off bot.yaml.'}`;
+    if (left !== undefined) throw promptLeft(why, written, left);
     throw new Error(`${why} Nothing was made. Run this again once the book can be written.`);
   }
 
@@ -178,7 +189,7 @@ function settingsFor(bot, maker, option, given) {
 /**
  * Refuse an approval wider than the widest of the maker's own and the bot's
  * `temp_approval`, which only the user's yes through `permission approval
- * --temps` widens (ADR 0041).
+ * --temps` widens (ADR 0051).
  */
 function refuseWiderApproval(bots, caller, bot, maker, asked) {
   if (asked === undefined) return;
@@ -316,6 +327,24 @@ function writePromptFirst(bots, caller, settings) {
   return file;
 }
 
+/** Remove the start prompt's file `written`, when there is one, and answer why it could not be. */
+function removeWritten(written) {
+  try {
+    if (written !== undefined) rmSync(written, { force: true });
+  } catch (error) {
+    return error;
+  }
+  return undefined;
+}
+
+/**
+ * The refusal `why` for a make whose start prompt's file `written` could not
+ * be removed (`left`). Off bot.yaml, nothing is made; a prompt file that stays
+ * is only a file, and nothing reads it (#393).
+ */
+const promptLeft = (why, written, left) =>
+  new Error(`${why} Nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
+
 /**
  * Retire a temporary session the caller made. Returns what `retireSession`
  * does, with the maker.
@@ -506,10 +535,11 @@ const TEACH_FOOT = /Enter to .*· Esc to cancel/;
  * captured live, with what answers it. Rows are compared trimmed, the pointer
  * `❯` taken out, so the pointer may sit on any one of them.
  *
- * Claude Code 2.1.283's form (#261's live test, #416) is answered with Esc,
- * which cancels it (Not now), never a return, which is Continue. Claude Code
- * 2.1.289's numbered list (#489's live run 1) is answered with "2. Not now",
- * never "1. Yes" or "3. Don't show again" (the architect's ruling on #489).
+ * Claude Code 2.1.283's form (#261's live test, #416) and 2.1.302's (#604) are
+ * answered with Esc, which cancels them (Not now), never a return, which is
+ * Continue. Claude Code 2.1.289's numbered list (#489's live run 1) is
+ * answered with "2. Not now", never "1. Yes" or "3. Don't show again" (the
+ * architect's ruling on #489).
  */
 const TEACH_SHAPES = [
   {
@@ -524,6 +554,21 @@ const TEACH_SHAPES = [
       'Continue',
       '←/→ to change usage · Enter to continue · Esc to cancel',
     ],
+    escape: true,
+  },
+  {
+    name: 'the 2.1.302 form',
+    rows: [
+      TEACH_TITLE,
+      'Claude Code reads this project, your recent Claude sessions, and optionally your shell history and other',
+      'repositories. Claude analyzes this data and customizes auto mode to make better decisions.',
+      'How you use Claude here     Mixed',
+      'Also scan shell history     false',
+      'Also scan your other repos  false',
+      'Continue',
+      '←/→ to change · Enter to continue · Esc to cancel',
+    ],
+    escape: true,
   },
   {
     name: 'the 2.1.289 list',
@@ -597,7 +642,7 @@ const wholeScreen = (rows) => rows.filter((row) => row.trim() !== '').map((row)
 /**
  * Answer the first-run screen of a temporary session the caller made (#489):
  * Claude Code's Teach auto mode screen, in one of the shapes the kit knows,
- * matched exactly. The 2.1.283 form gets Esc. The 2.1.289 list gets arrows to
+ * matched exactly. The 2.1.283 and 2.1.302 forms get Esc. The 2.1.289 list gets arrows to
  * "2. Not now" where needed, a second look that the pointer is there and the
  * list is otherwise as it was, and only then a return. Anything else is refused with
  * nothing typed. Like `trustHooks`, it is one command a permission rule of its
@@ -628,7 +673,7 @@ function answerTeach(target, kind) {
         const hooks = rows.some((row) => row.includes(HOOKS_REVIEW)) ? ` A Codex session's "${HOOKS_REVIEW}" is answered with ${kind} trust-hooks.` : '';
         throw new Error(`${run}'s screen is not one ${kind} answer answers: ${seen.misfit}.${hooks} ${nothing} It shows:\n${wholeScreen(rows)}`);
       }
-      if (seen.shape === TEACH_SHAPES[0]) {
+      if (seen.shape.escape) {
         send('\x1b');
         return 'Esc (Not now)';
       }

package/src/up.js

@@ -4,16 +4,18 @@
 // conversation and Orca's resume record with it. Run it twice and the second
 // run does nothing.
 
+import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
-import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, sessionIdsIn, tabIdsIn, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS, updateBook, withUnclaimed } from './book.js';
+import { forgetClaimed, forgetSession, MAILBOX_WAIT_MS, readBook, rememberSession, sessionIdsIn, tabIdsIn, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS, updateBook, withUnclaimed } from './book.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';
-import { addressOf, harnessOf, isAddressOf, isShortPrompt, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
+import { piTrouble } from './pi.js';
+import { addressOf, HARNESSES, harnessOf, isAddressOf, isShortPrompt, kitFolders, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
 import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, runMissing, screenRows, shellInTab, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
 import { TAB_ENV } from './record.js';
 import { buildAgents, rulesStamp } from './rules.js';
@@ -110,6 +112,7 @@ export function prepareBots(bots, names, onlySession) {
     return { home, bot: readBot(home, name) };
   });
   for (const { bot, home } of chosen) refuseWhatCannotStart(bot, home, onlySession);
+  refuseWhenPiIsNotReady(chosen, onlySession);
 
   // Every bot's AGENTS.md is built before Orca is asked for anything, because a
   // session reads that file as it starts: a build landing after the tab was
@@ -170,7 +173,7 @@ export function prepareBots(bots, names, onlySession) {
 export function botsNamed(bots, onlyBot) {
   const names = botNames(bots);
   if (names.length === 0) {
-    throw new Error(`there are no bots in ${bots} yet: make one with obk bot create --bots <path> --name <name> --harness claude|codex.`);
+    throw new Error(`there are no bots in ${bots} yet: make one with obk bot create --bots <path> --name <name> --harness claude|codex|pi.`);
   }
   if (onlyBot !== undefined && !names.includes(onlyBot)) {
     throw new Error(`there is no bot called ${onlyBot} in ${bots}. The bots there are: ${names.join(', ')}.`);
@@ -185,6 +188,23 @@ function refuseWhatCannotStart(bot, home, onlySession) {
   }
 }
 
+/**
+ * Refuse the run before Orca is asked for anything when it would start a Pi
+ * session and Pi cannot start one: Pi does not run, can use no model, or
+ * cannot use the one a session names (#578). The user signs in to Pi on their
+ * own. A run with no Pi session does not ask Pi anything.
+ */
+function refuseWhenPiIsNotReady(chosen, onlySession) {
+  const onPi = chosen.flatMap(({ bot }) => awake(sessionsOf(bot, onlySession))
+    .filter((session) => harnessOf(session, bot.harness) === 'pi')
+    .map((session) => ({ bot, session })));
+  if (onPi.length === 0) return;
+  const trouble = piTrouble(onPi.map(({ session }) => session.model).filter((model) => typeof model === 'string' && model.trim() !== ''));
+  if (trouble !== undefined) {
+    throw new Error(`${trouble} It would start ${onPi.map(({ bot, session }) => `${bot.name} ${session.name}`).join(', ')}.`);
+  }
+}
+
 /**
  * The sessions that are not paused. A paused session is left out of a run
  * altogether, so what it is set to asks nothing of the ones that will start;
@@ -273,12 +293,18 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // Asked before the book is held, because it reads a folder of the harness's
   // own files: nothing slow happens under the lock.
   let which = whichConversation(book, home, bot, session, was, harness);
-  const launchOf = (chosen) => launchFor(bots, bot, session, harness, home, workDir, chosen.resume, was?.address);
+  // A Pi session is told which conversation to be, and a new one is named here:
+  // the book is where that name is kept (ADR 0012, tech notes, section 6).
+  const fresh = harness === 'pi' ? randomUUID() : undefined;
+  const launchOf = (chosen) => launchFor(bots, bot, session, harness, home, workDir, chosen.resume, was?.address, fresh);
   let launch = launchOf(which);
 
   // A work dir is a plain folder, made for the session before it is told about
   // it (PRD 6.4). Nothing here is a git worktree.
   if (workDir !== undefined) mkdirSync(workDir, { recursive: true });
+  // The kit's own folders for the bot, which a Codex launch line names for its
+  // sandbox to write, are there before the line is (#534).
+  if (harness === 'codex') for (const folder of Object.values(kitFolders(bots, bot.name))) mkdirSync(folder, { recursive: true });
   writePrompt(launch);
 
   const made = openTab(home, tabTitle);
@@ -314,10 +340,16 @@ async function bringUpSession(bots, home, live, session, bot, title) {
       // gets, and trust-hooks asks what this one got (#506).
       let entry = { ...current.sessions[session.name], tab: made.tabId, launched, launched_with: session.extra_args ?? [], rules };
       if (rules === undefined) delete entry.rules;
+      // Only Claude Code answers to an address. One left from a Claude run
+      // before a move to another harness would draw mail to nobody (#565).
+      if (harness !== 'claude') delete entry.address;
       held = entry.session;
       // Before the line is typed, so the hook finds no id here and takes the one
       // it reports for a start rather than a clear, which would tell the duty twice.
-      if (which.noConversation !== undefined && held === which.noConversation) entry = forgetSession(entry, 'no conversation');
+      if (which.noConversation !== undefined && held === which.noConversation) entry = setAside(entry, which);
+      // The id a new Pi conversation is started under, written before the line
+      // that starts it, as a hook writes Claude Code's and Codex's.
+      if (fresh !== undefined && launch.resume === undefined) entry = rememberSession(entry, fresh);
       current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
       forgetClaimed(current);
     });
@@ -328,13 +360,15 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // The old tab's hook can name another conversation while the tab is being
   // opened. A fresh start chosen before that is chosen again from the id the
   // book holds now: resumed if the harness has it, and otherwise set aside the
-  // same way (review of PR #310).
-  if (which.noConversation !== undefined && typeof held === 'string' && held !== which.noConversation) {
-    which = hasConversation(harness, home, held) ? { resume: held } : { noConversation: held };
+  // same way (review of PR #310). A Pi session has no hook, and the id this run
+  // named for it is the one the book now holds.
+  if (fresh === undefined && which.noConversation !== undefined && typeof held === 'string' && held !== which.noConversation) {
+    which = hasConversation(harness, home, held) ? { resume: held } : notHere(harness, home, held);
     if (which.noConversation !== undefined) {
+      const chosen = which;
       await updateBook(home, (current) => {
         const entry = current.sessions[session.name];
-        if (entry?.session === held) current.sessions[session.name] = forgetSession(entry, 'no conversation');
+        if (entry?.session === held) current.sessions[session.name] = setAside(entry, chosen);
       });
     }
     launch = launchOf(which);
@@ -399,7 +433,9 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     promptReceived,
     promptFile: launch.promptFile,
     resumed: launch.resume !== undefined,
-    noConversation: which.noConversation,
+    noConversation: which.ranOn === undefined ? which.noConversation : undefined,
+    harnessChanged: which.ranOn === undefined ? undefined : which.noConversation,
+    ranOn: which.ranOn,
     unclaimed: which.unclaimed,
     listLine: list?.typed,
     listLineTrouble: list?.why,
@@ -529,7 +565,7 @@ function lookAndType(home, tabId, line, until) {
  * The line that starts this session: resuming `resume`, or, with none, a fresh
  * start carrying its duty. Returns `{ resume, prompt, promptFile, command, address }`.
  */
-function launchFor(bots, bot, session, harness, home, workDir, resume, held) {
+function launchFor(bots, bot, session, harness, home, workDir, resume, held, fresh) {
   const prompt = resume === undefined ? startPrompt(session, { home, workDir }) : undefined;
   // Anything longer than a line goes to the harness out of a file, rather than
   // through the tab's shell a character at a time.
@@ -550,6 +586,10 @@ function launchFor(bots, bot, session, harness, home, workDir, resume, held) {
     promptFile,
     resume,
     address,
+    kit: kitFolders(bots, bot.name),
+    // A new Pi conversation's id, and the name its tab and session list show,
+    // `<bot>.<session>` as a Codex thread is named (#480).
+    ...(harness === 'pi' ? { sessionId: resume === undefined ? fresh : undefined, name: `${bot.name}.${session.name}` } : {}),
   });
   // The session's mailbox first, from inside its own tab (#317), and the
   // harness whatever became of it.
@@ -827,7 +867,7 @@ function whichConversation(book, home, bot, session, was, harness) {
     // it: a session paused before its first turn is one. There is nothing to
     // resume, so it starts again with its duty, and the book keeps the id in the
     // history with the reason (#295).
-    return { noConversation: was.session };
+    return notHere(harness, home, was.session);
   }
   // No tab: nothing has ever run for this session, so there is nothing to find.
   if (typeof was?.tab !== 'string') return {};
@@ -847,6 +887,22 @@ function whichConversation(book, home, bot, session, was, harness) {
   return { unclaimed: known.map((one) => one.id) };
 }
 
+/**
+ * An id the book holds that this harness has no conversation behind, so the
+ * session starts fresh: `{ noConversation: id }`, and `ranOn`, the harness that
+ * does have it, when the session has moved to another harness since it ran
+ * (#565). That conversation is not lost, only not this harness's to resume.
+ */
+function notHere(harness, home, id) {
+  const ranOn = HARNESSES.find((other) => other !== harness && hasConversation(other, home, id));
+  return ranOn === undefined ? { noConversation: id } : { noConversation: id, ranOn };
+}
+
+/** The entry with the id `which` set aside moved into its history, with why. */
+const setAside = (entry, which) => (which.ranOn === undefined
+  ? forgetSession(entry, 'no conversation')
+  : forgetSession(entry, 'harness changed', { harness: which.ranOn }));
+
 /**
  * A bot's Orca project, made if it is not there yet, with `change` saying
  * whether this run `made` it, `renamed` it or left it as it was (undefined).
@@ -870,12 +926,19 @@ const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, cha
  *
  * Beside *this* bots folder, and not in a shared temp directory: two bots
  * folders may each hold an api-bot with a daily session, and one file for both
- * of them is one bot's duty handed to another's session.
+ * of them is one bot's duty handed to another's session. In the bot's own
+ * folder there, which a Codex session of the bot may write and no other bot's
+ * may: a temporary session's maker writes its prompt from inside its sandbox
+ * (#534).
  */
 export const promptPath = (bots, bot, session) =>
+  path.join(kitFolders(bots, bot).prompts, `${encodeURIComponent(session)}.txt`);
+
+/** Where a session's start prompt was before #534, flat beside the others: removed with the session. */
+export const oldPromptPath = (bots, bot, session) =>
   path.join(`${bots}.prompts`, `${encodeURIComponent(bot)}.${encodeURIComponent(session)}.txt`);
 
-function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, unclaimed, noMailbox = false, listLine, listLineTrouble, notLaunched }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, harnessChanged, ranOn, unclaimed, noMailbox = false, listLine, listLineTrouble, notLaunched }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // A tab whose shell was not ready for the launch line, and why: nothing was
   // typed into it (#498).
@@ -889,6 +952,9 @@ function entry(tab, { bot, name, created, running = false, blockedReason, prompt
   if (listLineTrouble !== undefined) made.listLineTrouble = listLineTrouble;
   // The id the book held that had no conversation behind it, now in the history.
   if (noConversation !== undefined) made.noConversation = noConversation;
+  // The id the book held that ran on another harness, the one this session
+  // has since moved from, now in the history (#565).
+  if (harnessChanged !== undefined) Object.assign(made, { harnessChanged, ranOn });
   // Orca's own words for what is on screen waiting to be answered, when it
   // gave any: the caller acts on it, the kit only passes it on.
   if (blockedReason !== undefined) made.blockedReason = blockedReason;