@assuredloop/orca-bot-kit 0.27.0 → 0.28.0

package/src/health.js

@@ -25,7 +25,7 @@ import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord, workDirOf } from './launch.js';
+import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, promptFile, sessionTrouble, set, SHELL_ENV, shellWord, workDirOf } from './launch.js';
 import { frontOfTab, orcaDefaultArgs, projects, runMissing, tabs, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
 import { processesIn } from './processes.js';
@@ -140,8 +140,17 @@ function leftBeside(bots) {
   let known = true;
   for (const name of botNames(bots)) {
     try {
-      for (const session of readBot(botDir(bots, name), name).sessions) {
+      const home = botDir(bots, name);
+      for (const session of readBot(home, name).sessions) {
         owned.add(promptPath(bots, name, session.name));
+        // The file a session names as its own prompt, which the kit reads to
+        // start it, and the file a link there leads to (#577).
+        if (set(session.prompt_file)) {
+          const file = promptFile(session, home);
+          owned.add(file);
+          const real = realpathOf(file);
+          if (real !== undefined) owned.add(real);
+        }
         // Where a live session's prompt was before #534: nothing reads it once
         // the session starts again, and its retire removes it.
         owned.add(oldPromptPath(bots, name, session.name));
@@ -153,7 +162,7 @@ function leftBeside(bots) {
 
   if (known) {
     for (const at of promptFilesIn(`${bots}.prompts`)) {
-      if (owned.has(at)) continue;
+      if (owned.has(at) || owned.has(realpathOf(at))) continue;
       found.push(finding('leftover', at, `${at} is a start prompt the kit wrote beside your bots folder, and no session of any bot answers to it now. Nothing reads it.`));
     }
   }
@@ -255,7 +264,7 @@ function sessionSettings(home, bot) {
 /** What is wrong with the roles the bot's temporary sessions are made in (#465). */
 function rolesTrouble(home, bot) {
   const where = path.join(home, 'bot.yaml');
-  // The widest approval they may be made at, the user's yes (ADR 0041).
+  // The widest approval they may be made at, the user's yes (ADR 0051).
   const level = bot.temp_approval;
   const approval = level === undefined || APPROVALS.includes(level) ? [] : [{
     where,
@@ -424,7 +433,7 @@ function inOrca(bots, home, bot, setups, sessions) {
 
   // What the harness has on record in this bot's folder, read once: it is a walk
   // through every conversation on the machine.
-  const onRecord = recordIn(real ?? home, bot);
+  const onRecord = recordIn(real ?? home, bot, book);
   // A conversation the harness marks as a subagent's was never a session's, so a
   // note that holds one is not a loose end for it (#287). The note stays as it is.
   const helpers = new Set(onRecord.filter((one) => one.subagent).map((one) => one.id));
@@ -493,10 +502,12 @@ function offTheBook(home, bot, book, onRecord) {
   return [finding('session', bookFile(home), `The harness has conversations on record in ${bot.name}'s folder that the book does not name: ${listed}. The kit's hook may have missed them: a clear it did not record, or a Codex hooks file trusted late. To give one to a session, write it into ${bookFile(home)} under that session as  session: <id>  and run obk up again.`, bot.name)];
 }
 
-/** Every conversation on record in the bot's folder, from every harness any of its sessions runs on, as `obk usage` reads them. */
-function recordIn(home, bot) {
+/** Every conversation on record in the bot's folder, from every harness any of its sessions runs on or a retired one may have, as `obk usage` reads them. */
+function recordIn(home, bot, book) {
   const harnesses = new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)));
   if (harnesses.size === 0) harnesses.add(bot.harness);
+  // The book does not say which harness a retired session ran on, so any is (#573).
+  if (Array.isArray(book.retired) && book.retired.length > 0) for (const harness of HARNESSES) harnesses.add(harness);
   return [...harnesses]
     .filter((harness) => HARNESSES.includes(harness))
     .flatMap((harness) => transcriptsIn(harness, home));

package/src/hooks.js

@@ -17,7 +17,11 @@ import { isDeepStrictEqual } from 'node:util';
 import { leadsOutside } from './bot.js';
 import { ownCli, shellWord } from './launch.js';
 
-/** Where each harness reads a project's hooks, inside the bot home. */
+/**
+ * Where each harness reads a project's hooks, inside the bot home. Pi has no
+ * hook of the kit's: the kit names a Pi session's id itself, on its launch
+ * line (#578).
+ */
 const HOOK_FILE = { claude: '.claude/settings.json', codex: '.codex/hooks.json' };
 
 /** The hooks file `harness` reads in the bot at `home`. */
@@ -82,6 +86,7 @@ export const nameCommand = (bots, bot, cli = ownCli()) =>
  * the kit's own entry is written (PRD 6.3).
  */
 export function installHook(home, harness, { bots, bot }) {
+  if (HOOK_FILE[harness] === undefined) return;
   const file = path.join(home, HOOK_FILE[harness]);
   const away = outside(home, file);
   if (away !== undefined) throw new Error(away);
@@ -117,6 +122,7 @@ export function installHook(home, harness, { bots, bot }) {
  * nothing else says so — the book simply stops being true.
  */
 export function hookTrouble(home, harness, { bots, bot }) {
+  if (HOOK_FILE[harness] === undefined) return undefined;
   const file = path.join(home, HOOK_FILE[harness]);
   const stale = `Until it is there, nothing tells the book which conversation this bot's ${harness} sessions are running as, and the book goes stale.`;
 

package/src/init.js

@@ -10,7 +10,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync,
 import path from 'node:path';
 import { parseDocument } from 'yaml';
 
-import { BOT_GITIGNORE, changesExactly, YAML_OUT } from './bot.js';
+import { BOT_GITIGNORE, changesExactly, refuseOutside, withBotTurn, writeWhole, YAML_OUT } from './bot.js';
 import { RECORD, SKILL_DIRS } from './skills.js';
 
 /**
@@ -266,6 +266,11 @@ function checkBotFather(file, harness) {
   if (bot.sessions !== undefined && bot.sessions !== null && !Array.isArray(bot.sessions)) {
     throw new Error(`${file} has a sessions entry that is not a list, so init cannot add Bot Father's daily session to it. Fix it, then run init again.`);
   }
+  // One init would complete is refused here, before init writes anything, when a
+  // link takes it out of the bot folder (#569).
+  if (bot.harness === undefined || !Array.isArray(bot.sessions) || bot.sessions.length === 0) {
+    refuseOutside(path.dirname(file), file);
+  }
 }
 
 /**
@@ -281,35 +286,37 @@ function checkBotFather(file, harness) {
  * are theirs, and `up` brings up what it finds.
  */
 function completeBotFather(file, harness) {
-  const source = readFileSync(file, 'utf8');
-  const doc = parseDocument(source);
-
-  // What is missing is settled from the document, not from the text it is
-  // written back as: a file that needs nothing is not rewritten, however the
-  // library would have laid it out.
-  const sessions = doc.get('sessions', true);
-  const needsSession = sessions?.items === undefined || sessions.items.length === 0;
-  const needsHarness = doc.get('harness') === undefined;
-  if (!needsSession && !needsHarness) return [];
-
-  if (sessions?.items === undefined) {
-    doc.set('sessions', [{ name: DAILY_SESSION }]);
-  } else if (needsSession) {
-    sessions.flow = false;
-    doc.addIn(['sessions'], { name: DAILY_SESSION });
-  }
-  if (needsHarness) doc.set('harness', harness);
+  return withBotTurn(path.dirname(file), () => {
+    const source = readFileSync(file, 'utf8');
+    const doc = parseDocument(source);
+
+    // What is missing is settled from the document, not from the text it is
+    // written back as: a file that needs nothing is not rewritten, however the
+    // library would have laid it out.
+    const sessions = doc.get('sessions', true);
+    const needsSession = sessions?.items === undefined || sessions.items.length === 0;
+    const needsHarness = doc.get('harness') === undefined;
+    if (!needsSession && !needsHarness) return [];
+
+    if (sessions?.items === undefined) {
+      doc.set('sessions', [{ name: DAILY_SESSION }]);
+    } else if (needsSession) {
+      sessions.flow = false;
+      doc.addIn(['sessions'], { name: DAILY_SESSION });
+    }
+    if (needsHarness) doc.set('harness', harness);
 
-  const text = doc.toString(YAML_OUT);
+    const text = doc.toString(YAML_OUT);
 
-  if (!changesExactly(source, text, (was) => ({
-    ...was,
-    harness: was.harness ?? harness,
-    sessions: was.sessions?.length > 0 ? was.sessions : [{ name: DAILY_SESSION }],
-  }))) {
-    throw new Error(`${file} cannot be completed without changing something else in it, so nothing was written. Give it a harness and a session by hand, then run init again.`);
-  }
+    if (!changesExactly(source, text, (was) => ({
+      ...was,
+      harness: was.harness ?? harness,
+      sessions: was.sessions?.length > 0 ? was.sessions : [{ name: DAILY_SESSION }],
+    }))) {
+      throw new Error(`${file} cannot be completed without changing something else in it, so nothing was written. Give it a harness and a session by hand, then run init again.`);
+    }
 
-  writeFileSync(file, text);
-  return [BOT_FATHER_YAML];
+    writeWhole(file, text);
+    return [BOT_FATHER_YAML];
+  });
 }

package/src/launch.js

@@ -2,7 +2,7 @@
 // the harness up and carries the session's start prompt with it.
 //
 // The flag mapping is PRD 6.4 and ADR 0015, re-checked against the installed
-// CLIs (Claude Code 2.1.278, Codex 0.155.1). Every session is given its
+// CLIs (Claude Code 2.1.278, Codex 0.155.1, Pi 1.1.0). Every session is given its
 // approval level explicitly, so a user's own global harness defaults cannot
 // leak into a bot. The kit names no model: a session that sets none gets the
 // harness's own.
@@ -27,6 +27,11 @@ const APPROVAL = {
     ask: ['-a', 'on-request'],
     'dangerously-skip': ['--dangerously-bypass-approvals-and-sandbox'],
   },
+  // Pi asks before no tool call and has no rule for each command, so it has
+  // one level, and no flag for it (the owner, #547).
+  pi: {
+    'dangerously-skip': [],
+  },
 };
 
 export const APPROVALS = Object.keys(APPROVAL.claude);
@@ -44,32 +49,179 @@ export const HARNESSES = Object.keys(APPROVAL);
 export const approvalRank = (level) => ['ask', 'auto', 'dangerously-skip'].indexOf(level);
 
 /**
- * The harness flags that set approval or permissions, which only
- * `obk permission approval` may change, not an extra argument (ADR 0041).
- * Codex's `-a` and `-s` take their value glued on too.
+ * The harness flags that set approval or permissions, or widen what a session
+ * may write or run, which only `obk permission approval` may change, not an
+ * extra argument (ADR 0051, ADR 0049). Codex's short flags take their value
+ * glued on too. Pi's `--approve` and `-a` make it trust the folder's own
+ * files, which the kit's `--no-approve` keeps it from (#578).
  */
 const APPROVAL_FLAGS = {
-  claude: ['--permission-mode', '--dangerously-skip-permissions', '--allow-dangerously-skip-permissions', '--allowedTools', '--allowed-tools'],
-  codex: ['-a', '--ask-for-approval', '--approve-for-me', '--dangerously-bypass-approvals-and-sandbox', '-s', '--sandbox'],
+  claude: [
+    '--permission-mode', '--dangerously-skip-permissions', '--allow-dangerously-skip-permissions', '--allowedTools', '--allowed-tools',
+    '--add-dir', '--settings', '--setting-sources', '--plugin-dir', '--plugin-url', '--mcp-config', '--agents', '--agent', '--debug-file', '--bare', '--restricted',
+  ],
+  codex: [
+    '-a', '--ask-for-approval', '--approve-for-me', '--dangerously-bypass-approvals-and-sandbox', '-s', '--sandbox',
+    '--add-dir', '-C', '--cd', '-p', '--profile', '--enable', '--disable', '--remote', '--remote-auth-token-env',
+  ],
+  pi: ['--approve', '-a'],
+};
+
+/**
+ * The Codex `-c` keys an extra argument may set, with any value or with only
+ * the values named. Every other key is refused: Codex 0.163.0's config has
+ * dozens that widen a session, and more in each release (ADR 0049).
+ */
+const CONFIG_KEYS = {
+  model: true,
+  model_reasoning_effort: true,
+  model_reasoning_summary: true,
+  model_verbosity: true,
+  model_context_window: true,
+  model_auto_compact_token_limit: true,
+  plan_mode_reasoning_effort: true,
+  service_tier: true,
+  hide_agent_reasoning: true,
+  show_raw_agent_reasoning: true,
+  tool_output_token_limit: true,
+  'tui.animations': true,
+  'tui.show_tooltips': true,
+  'tui.notifications': true,
+  'tui.notification_method': true,
+  'tui.notification_condition': true,
+  'tui.alternate_screen': true,
+  'tui.theme': true,
+  'tui.vim_mode_default': true,
+  'tui.status_line': true,
+  'tui.terminal_title': true,
+  'tui.raw_output_mode': true,
+  'tui.disable_paste_burst': true,
+  'tui.fullscreen_transcript': true,
+  'tui.mouse_scroll_speed': true,
+  'tui.show_server_version_notice': true,
+  // The network the kit turns on, which a user may turn off (NETWORK_ACCESS).
+  'sandbox_workspace_write.network_access': ['true', 'false'],
+  // These only narrow: `false` is Codex's default.
+  'sandbox_workspace_write.exclude_tmpdir_env_var': ['true', 'false'],
+  'sandbox_workspace_write.exclude_slash_tmp': ['true', 'false'],
+  'features.sleep_tool': ['false'],
+  // No update check at start, so no update offer (#581).
+  check_for_update_on_startup: ['false'],
 };
 
+/**
+ * The one trust a `-c` may give: one folder, an absolute path in a TOML basic
+ * string, trusted. It is what the kit's own answer to Codex's trust screen
+ * gives, for that run only and with nothing written to config.toml (ADR 0049).
+ */
+const TRUST = /^\{[ \t]*"([^"\\\x00-\x1f\x7f]*)"[ \t]*=[ \t]*\{[ \t]*trust_level[ \t]*=[ \t]*"trusted"[ \t]*\}[ \t]*\}$/;
+
+/** Whether a Codex `-c` value, `key=value`, sets only what an extra argument may. */
+function allowedConfig(setting) {
+  const at = setting.indexOf('=');
+  if (at === -1) return false;
+  const key = setting.slice(0, at).trim();
+  const value = setting.slice(at + 1).trim();
+  if (key === 'projects') {
+    const folder = TRUST.exec(value)?.[1];
+    return folder !== undefined && folder.startsWith('/') && !folder.split('/').includes('..');
+  }
+  if (!/^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/.test(key) || !Object.hasOwn(CONFIG_KEYS, key)) return false;
+  return CONFIG_KEYS[key] === true || CONFIG_KEYS[key].includes(value);
+}
+
 /**
  * Refuse extra arguments that set a session's approval or permissions on
- * `harness`, before anything is written, naming the command that does it.
+ * `harness`, or widen what it may write or run, before anything is written,
+ * naming the command that does it (ADR 0051, ADR 0049).
+ * `args` is a list, or, as a user may write `extra_args` by hand, one string
+ * of shell text. The kit types such a string into the tab's shell as it
+ * stands, so the guard takes it only when it can be sure of the words the
+ * shell makes of it, and refuses it otherwise (#565).
  */
 export function refuseApprovalArgs(harness, args) {
-  const found = (args ?? []).find((arg) => (APPROVAL_FLAGS[harness] ?? []).some((flag) => arg === flag
-    || arg.startsWith(`${flag}=`)
-    || (/^-[as]$/.test(flag) && arg.startsWith(flag) && !arg.startsWith('--'))));
-  if (found === undefined) return;
-  throw new Error(`--extra-arg=${found} sets the session's approval or permissions on ${harness}, and only obk permission approval changes those, after the user's yes. Nothing was changed.`);
+  const words = Array.isArray(args) ? args.map(String) : set(args) ? sureWords(String(args)) : [];
+  if (words === undefined) {
+    throw new Error(`extra_args is written as one string, ${quoted(String(args))}, with shell syntax the kit cannot be sure of the words of, so it cannot tell whether it sets the session's approval or permissions. Write extra_args as a list, one --extra-arg for each argument. Nothing was changed.`);
+  }
+  for (let at = 0; at < words.length; at += 1) {
+    const arg = words[at];
+    if ((APPROVAL_FLAGS[harness] ?? []).some((flag) => arg === flag
+      || arg.startsWith(`${flag}=`)
+      || (/^-[asCp]$/.test(flag) && arg.startsWith(flag) && !arg.startsWith('--')))) {
+      throw new Error(`--extra-arg=${arg} sets the session's approval or permissions on ${harness}, or widens what it may write or run, and only obk permission approval changes those, after the user's yes. Nothing was changed.`);
+    }
+    // Codex's config override: the value is the next word, or after `=`, or glued on.
+    const setting = harness !== 'codex' ? undefined
+      : arg === '-c' || arg === '--config' ? (at += 1, words[at] ?? '')
+        : arg.startsWith('--config=') ? arg.slice('--config='.length)
+          : arg.startsWith('-c') && !arg.startsWith('--') ? arg.slice(2).replace(/^=/, '')
+            : undefined;
+    if (setting !== undefined && !allowedConfig(setting)) {
+      throw new Error(`--extra-arg=-c ${setting} sets a Codex setting that an extra argument may not set: the kit takes -c only for the model, the display, the network switch and a few settings that narrow (ADR 0049). Set the others in your own ~/.codex/config.toml; the session's approval and sandbox change only through obk permission approval, after the user's yes. Nothing was changed.`);
+    }
+  }
+}
+
+/**
+ * The words of the shell text `text`, when the kit can be sure they are the
+ * ones the tab's shell makes of it, and undefined when it cannot (#565). Sure
+ * means plain words of the characters `quoted` leaves bare, separated by
+ * spaces, with no unquoted `=` before any other character of its word, empty
+ * quotes included (zsh's equals expansion makes `''=sh` into /bin/sh); single quotes with no
+ * backslash (fish reads `\'` and `\\` there) and no control character; and
+ * double quotes with none of `$`, backquote, backslash or `!`, and no control
+ * character. Read so, it is the same words in zsh, bash and fish. Everything
+ * else, a newline or a tab included, is shell syntax this does not read.
+ */
+function sureWords(text) {
+  const words = [];
+  let word;
+  let quote;
+  for (const char of text) {
+    if (/[\x00-\x1f\x7f]/.test(char)) return undefined;
+    if (quote === "'") {
+      if (char === '\\') return undefined;
+      if (char === "'") quote = undefined;
+      else word += char;
+    } else if (quote === '"') {
+      if ('$`\\!'.includes(char)) return undefined;
+      if (char === '"') quote = undefined;
+      else word += char;
+    } else if (char === ' ') {
+      if (word !== undefined) words.push(word);
+      word = undefined;
+    } else if (char === "'" || char === '"') {
+      word ??= '';
+      quote = char;
+    } else if (/^[A-Za-z0-9,._+:@%/=-]$/.test(char) && !(char === '=' && !word)) {
+      word = (word ?? '') + char;
+    } else {
+      return undefined;
+    }
+  }
+  if (quote !== undefined) return undefined;
+  if (word !== undefined) words.push(word);
+  return words;
 }
 
 /** The level a session that names none runs at (ADR 0015). */
 export const DEFAULT_APPROVAL = 'auto';
 
+/** The level a session on `harness` is written with when it names none: Pi has only one (#547). */
+export const defaultApproval = (harness) => (harness === 'pi' ? 'dangerously-skip' : DEFAULT_APPROVAL);
+
+/**
+ * Why a level is refused on Pi, or undefined when it is taken there. The
+ * owner's decision (#547): every Pi session counts as dangerously-skip.
+ */
+export function piApprovalTrouble(level, who = 'this session') {
+  if (!set(level) || level === 'dangerously-skip') return undefined;
+  return `${who} runs on Pi and is set to approval ${level}. Pi has no approval prompt and no permission rules, so every Pi session runs as dangerously-skip (the owner's decision, #547); auto and ask are refused on Pi. Set it to dangerously-skip, or run the session on claude or codex.`;
+}
+
 /** A setting the user left out. An empty string is one too: it means the harness's own. */
-const set = (value) => value !== undefined && value !== null && String(value).trim() !== '';
+export const set = (value) => value !== undefined && value !== null && String(value).trim() !== '';
 
 /** Which harness a session runs on: its own, or the bot's. */
 export const harnessOf = (session, botHarness) => (set(session.harness) ? session.harness : botHarness);
@@ -201,6 +353,22 @@ export function sessionTrouble(session, harness, home) {
   if (set(session.approval) && !APPROVALS.includes(session.approval)) {
     return `${where(session)} is set to approval ${session.approval}, and the levels are ${APPROVALS.join(', ')}.`;
   }
+  if (harness === 'pi') {
+    const trouble = piApprovalTrouble(session.approval, where(session));
+    if (trouble !== undefined) return trouble;
+    // Pi has no context setting: a model's own name carries it, as in
+    // cursor/claude-opus-5-5@1m (tech notes, section 6).
+    if (set(session.context)) {
+      return `${where(session)} sets a context of ${session.context} on Pi, and Pi has no context setting: the model's name carries it, as in cursor/claude-opus-5-5@1m. Name such a model, or leave the context out.`;
+    }
+    // Pi 1.1.0 reads a word after `--` that starts with `@` as a file to
+    // attach, and has no escape for it, so such a prompt cannot arrive as
+    // written (tech notes, section 6). It is checked trimmed, as it is sent.
+    const said = set(session.prompt_file) ? readFileSync(promptFile(session, home), 'utf8') : session.prompt;
+    if (set(said) && String(said).trim().startsWith('@')) {
+      return `${where(session)} runs on Pi, and its prompt begins with @. Pi would read the prompt as a file to attach, not as text. Give it a prompt that does not begin with @.`;
+    }
+  }
   // Codex is given the context window as a number of tokens. `1m` is what a
   // Claude session would say, and copying it here does not fail at the kit but
   // in Codex, which exits with a type error the moment it starts.
@@ -231,16 +399,21 @@ const where = (session) => (set(session.name) ? `session ${session.name}` : 'thi
  * send would land on that list and answer it. A prompt given as an argument is
  * held by the harness until it is ready for it (tech notes, section 1).
  */
-export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address, kit }) {
+export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address, kit, sessionId, name }) {
   const trouble = sessionTrouble(session, harness, home);
   if (trouble !== undefined) throw new Error(trouble);
+  // Pi is told which conversation it is, a new one too: the kit names it, and
+  // that is how the book knows it (tech notes, section 6).
+  if (harness === 'pi' && resume === undefined && sessionId === undefined) {
+    throw new Error(`${where(session)} runs on Pi, and a Pi session is started with the id the book gives it, so the kit names one before it launches. None was given.`);
+  }
 
   const words = [harness];
   // Codex resumes through a subcommand, which has to come first; Claude Code
   // resumes through a flag, which goes with the session id at the end. Both
   // take every other flag exactly as a fresh session does.
   if (resume !== undefined && harness === 'codex') words.push('resume');
-  words.push(...APPROVAL[harness][set(session.approval) ? session.approval : DEFAULT_APPROVAL]);
+  words.push(...APPROVAL[harness][set(session.approval) ? session.approval : defaultApproval(harness)]);
   // Codex 0.157 shares one background server between sessions by default, and
   // a resume through it was seen to fail; without it Codex runs as 0.156 did
   // (tech notes, section 3, #330). Codex refuses the flag twice, so the user's
@@ -254,6 +427,16 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     // 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);
     if (set(session.effort)) words.push('--effort', String(session.effort));
+  } else if (harness === 'pi') {
+    // Pi trusts none of the folder's own files (`.pi/`, `.agents/skills`), so it
+    // shows no trust screen and runs nothing the kit has not looked at (#578).
+    words.push('--no-approve');
+    // The id the book holds, resumed or new: Pi opens the conversation with it,
+    // and makes it when there is none (tech notes, section 6).
+    words.push('--session-id', resume ?? sessionId);
+    if (name !== undefined) words.push('--name', name);
+    if (set(session.model)) words.push('--model', session.model);
+    if (set(session.effort)) words.push('--thinking', String(session.effort));
   } else {
     // Without this the Orca CLI cannot reach Orca from inside the sandbox, so
     // the session is in no fleet at all. The user's own setting of it wins.
@@ -313,7 +496,7 @@ export function startPrompt(session, { home, workDir }) {
 }
 
 /** Where a session's prompt file is: in the bot home, where the user put it. */
-export const promptFile = (session, home) => path.resolve(home, session.prompt_file);
+export const promptFile = (session, home) => path.resolve(home, String(session.prompt_file));
 
 /**
  * A prompt short and simple enough to type into the launch line as it is: one
@@ -336,10 +519,11 @@ function promptWords(prompt, fromFile) {
 
 /**
  * The session the harness is told to pick up again, when there is one: a flag
- * on Claude Code, the argument of the `resume` subcommand on Codex.
+ * on Claude Code, the argument of the `resume` subcommand on Codex. Pi's is
+ * its `--session-id`, which goes with its other flags.
  */
 const resumeWords = (harness, resume) => {
-  if (resume === undefined) return [];
+  if (resume === undefined || harness === 'pi') return [];
   return harness === 'claude' ? ['--resume', quoted(resume)] : [quoted(resume)];
 };
 

package/src/message.js

@@ -13,7 +13,8 @@
 // One road and one signal (#555, ADR 0042): the letter goes into the
 // receiver's mailbox, and Orca's own notice tells the receiver to look once it
 // is idle. The kit types nothing into the receiver's tab, except the one
-// Escape a sender asks for with --interrupt.
+// Escape a sender asks for with --interrupt. Orca gives no notice to a tab its
+// window has not loaded, so the send says when the receiver's is one (#579).
 
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
@@ -126,7 +127,7 @@ export function lookUp(bots, { to: target, from: sender, tab }) {
  * nothing, which is the whole of "the bot never picks the transport".
  */
 export async function sendMessage(bots, { to: target, from: sender, tab, subject, text, textFile, thread, interrupt = false }) {
-  const from = whoIsWriting(bots, sender, tab);
+  const from = whoIsSending(bots, sender, tab);
   const to = findSession(bots, target);
   const road = roadBetween(from, to);
 
@@ -159,6 +160,8 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
   }
 
   const written = bodyOf(bots, { from, to, subject, text, textFile });
+  // Looked at before the post, which is the send's last call to Orca (PRD 6.9).
+  const shown = loaded(to);
   // The Escape goes first, so the turn has ended when the letter is in.
   const interrupted = interrupt ? interruptBusy(to) : {};
   const message = postMessage({
@@ -176,9 +179,30 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
     thread: message.thread_id ?? thread,
     file: written.file,
     ...interrupted,
+    ...shown,
   };
 }
 
+/**
+ * Whether Orca's window has loaded the receiver's tab, looked at just before
+ * the letter goes in. Orca gives its notice only to a pane the window has loaded,
+ * and lists one it has not as orphaned, as after a window restart (#579; tech
+ * notes, section 1). So an orphaned tab is said, with its handle, and a
+ * listing that cannot be read is said too, rather than taken for a loaded tab.
+ * The look is made once: a tab orphaned after the send is not seen here.
+ */
+function loaded(to) {
+  if (to.tab === undefined) return {};
+  let listed;
+  try {
+    listed = tabs(to.home, { timeoutMs: LOOK_MS });
+  } catch (error) {
+    return { loadTrouble: error.message };
+  }
+  const tab = listed.find((one) => one.tabId === to.tab);
+  return tab?.orphaned === true ? { orphaned: true, handle: tab.handle } : {};
+}
+
 /**
  * What is waiting for a session, and the reading of it.
  *
@@ -364,6 +388,22 @@ function whoIsWriting(bots, sender, tab, asked = '--from <bot>/<session>: which
   return found;
 }
 
+/**
+ * The session that is sending. In one of this fleet's tabs it is the tab's own
+ * session, and `--from` may name only that one: otherwise a bot could send as
+ * another, and the reply and the receiver's check would take it for that one
+ * (#570). Outside the fleet's tabs `--from` says who is writing, as before.
+ */
+function whoIsSending(bots, sender, tab) {
+  const caller = tab === undefined ? undefined : sessionInTab(bots, tab);
+  if (caller === undefined) return whoIsWriting(bots, sender, tab);
+  if (sender === undefined) return caller;
+
+  const named = findSession(bots, sender);
+  if (named.bot === caller.bot && named.session === caller.session) return caller;
+  throw new Error(`this command runs in ${caller.bot}/${caller.session}'s Orca tab, ${tab}, so it sends as ${caller.bot}/${caller.session} and not as ${named.bot}/${named.session}. Nothing was sent. Leave out --from, or name ${caller.bot}/${caller.session}.`);
+}
+
 /**
  * The session the book says is in this Orca tab, wherever in the fleet it is,
  * when the caller is that session.

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 0034).
+-- a project was removed (#343, ADR 0046).
 --
 -- 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 0034): `project.update`, which makes Orca's
+// Orca's CLI does not offer (ADR 0046): `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