@assuredloop/orca-bot-kit 0.27.0 → 0.29.0

package/src/health.js

@@ -25,8 +25,8 @@ 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 { frontOfTab, orcaDefaultArgs, projects, runMissing, tabs, wordsOfProcess } from './orca.js';
+import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, promptFile, sessionTrouble, set, SHELL_ENV, shellWord, workDirOf } from './launch.js';
+import { frontOfTab, mailIn, orcaDefaultArgs, projects, runMissing, tabs, tabToTypeInto, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
 import { processesIn } from './processes.js';
 import { TAB_ENV } from './record.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));
@@ -450,6 +459,12 @@ function inOrca(bots, home, bot, setups, sessions) {
       found.push(finding('session', bookFile(home), `${bot.name}'s session ${name} has the mailbox ${entry.mailbox} in the book, and Orca has no Run of that id: it was made by another Orca, as on another machine, so mail sent to it is refused. The session's next start makes it a new one: ${fix}`, bot.name));
     }
 
+    // Mail Orca has not told a running session of (#630). A session that is
+    // paused or whose tab is gone reads no mail by design, or is named above.
+    if (typeof entry?.mailbox === 'string' && there.has(entry.tab) && !closed.has(name)) {
+      found.push(...unannounced(bots, home, bot, name, entry));
+    }
+
     const unclaimed = (Array.isArray(entry?.unclaimed) ? entry.unclaimed : []).filter((id) => !helpers.has(id));
     if (unclaimed.length > 0) {
       found.push(finding('leftover', bookFile(home), `The book notes conversations under ${bot.name}'s session ${name} that no session of this bot claims: ${unclaimed.join(', ')}. They ran in this bot's folder, and the kit will not say whose they were. To give one back, write it into ${bookFile(home)} under ${name} as  session: <id>  and run obk up again.`, bot.name));
@@ -472,6 +487,70 @@ function inOrca(bots, home, bot, setups, sessions) {
   return found;
 }
 
+/** How old an unread letter Orca has not rung for is before it counts as waiting (#630). */
+const WAITING_MS = 60 * 60 * 1000;
+
+/** How long the look at a session's tab waits for its harness to be idle. */
+const IDLE_LOOK_MS = 2000;
+
+/** How many of a mailbox's newest letters health reads: one read, whatever the mailbox holds. */
+const MAIL_READ = 100;
+
+/**
+ * The session `name`'s mail that Orca has not told it of, while its harness is
+ * idle now: one finding, or none (#630). Orca rings only a tab whose harness it
+ * has seen go idle since Orca last started, so a session that sat idle through
+ * an Orca restart or update is never told (tech notes, section 1). A busy one
+ * is told when its turn ends, so it is not named. Only flags and times are
+ * read: a letter's subject and text are the session's own. A mailbox or a tab
+ * Orca will not answer about leaves it unsaid.
+ *
+ * One read of the newest letters (review of PR #632). Orca hands mail to its
+ * reader oldest first, so a full read whose oldest letter is read is taken to
+ * hold every unread one. That misses an older letter left unread below a letter
+ * `orca orchestration reply` marked read out of order; the kit never runs it.
+ * A full read whose oldest letter is unread may have more below it, and the
+ * finding says so rather than count what it did not read.
+ */
+function unannounced(bots, home, bot, name, entry) {
+  let mail;
+  try {
+    mail = mailIn(entry.mailbox, MAIL_READ);
+  } catch {
+    return [];
+  }
+  const before = Date.now() - WAITING_MS;
+  const waiting = mail
+    .filter((one) => one.read === 0 && one.delivered_at == null && Date.parse(one.created_at) < before)
+    .sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+  const last = mail.at(-1);
+  const more = mail.length >= MAIL_READ && last.read === 0;
+  // Unread and never rung for, with more of the mailbox below it.
+  const below = more && last.delivered_at == null;
+  if (waiting.length === 0 && !below) return [];
+
+  // The gate the kit's own keys go through tells an idle harness from a busy
+  // one, a question on its screen or a shell; only its answer is kept.
+  let look;
+  try {
+    look = tabToTypeInto(home, entry.tab, IDLE_LOOK_MS);
+  } catch {
+    return [];
+  }
+  if (look.handle === undefined || look.idle !== true) return [];
+
+  const count = `${more ? 'at least ' : ''}${waiting.length}`;
+  const letters = waiting.length === 1 && !more ? '1 letter' : `${count} letters`;
+  const read = `Health reads the newest ${MAIL_READ} letters of a mailbox, and the oldest of those is unread too, so older letters may wait as well.`;
+  const what = waiting.length === 0
+    ? `has mail in its mailbox ${entry.mailbox} that Orca has not told it of: the oldest of the newest ${MAIL_READ} letters, from ${last.created_at}, is unread, and Orca has not rung for it. Older letters may wait below it, which health does not read.`
+    : more
+      ? `has ${letters} in its mailbox ${entry.mailbox} that it has not read and that Orca has not told it of, each more than an hour old; the oldest of them that health read is from ${waiting[0].created_at}. ${read}`
+      : `has ${letters} in its mailbox ${entry.mailbox} that it has not read and that Orca has not told it of, the oldest from ${waiting[0].created_at}, more than an hour ago.`;
+  const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${bot.name} --session ${name}`;
+  return [finding('mail', entry.mailbox, `${bot.name}'s session ${name} ${what} Its harness is idle now, and Orca tells an idle session of its mail within minutes, unless the session sat idle through an Orca restart or update: then Orca does not tell it until it takes a turn. ${restart} opens a new tab for it, which Orca tells. A restart drops what lives only in the old tab, such as Claude Code schedules, so the session makes them again.`, bot.name)];
+}
+
 /**
  * The conversations a harness has on record in this bot's folder that the book
  * does not name anywhere. The hook is how an id reaches the book, and when it
@@ -493,10 +572,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);
@@ -96,7 +101,7 @@ export function installHook(home, harness, { bots, bot }) {
   const started = withKitHook(settings.hooks, file, mine);
   // The Claude Code mail hook and the Codex nudge hook went with the kit's
   // typed line (#555), so an entry of either is taken out.
-  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, withoutHooks(started, [KIT_MAIL, KIT_NUDGE])) };
+  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, withoutHooks(started, REMOVED_HOOKS)) };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -107,6 +112,41 @@ export function installHook(home, harness, { bots, bot }) {
   return HOOK_FILE[harness];
 }
 
+/**
+ * Take the kit's hooks of commands it no longer has out of every hooks file the
+ * bot at `home` has, whatever its sessions run on now and whether or not it is
+ * paused (#613). `installHook` does this only for a harness a session runs on,
+ * so a file the kit wrote for a harness the bot has since left kept them.
+ * Returns the files it wrote, relative to the bot home.
+ *
+ * It adds nothing and changes no other entry. A file it cannot read, a hooks
+ * entry that is not a mapping of events, or a link out of the bot folder is
+ * left as it is: the kit cannot tell its entries there, and health and
+ * `installHook` speak for a harness that runs.
+ */
+export function dropRemovedHooks(home) {
+  return Object.values(HOOK_FILE).flatMap((relative) => {
+    const file = path.join(home, relative);
+    if (!existsSync(file) || outside(home, file) !== undefined) return [];
+    let settings;
+    try {
+      settings = readSettings(file);
+    } catch {
+      return [];
+    }
+    const { hooks } = settings;
+    if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) return [];
+    const kept = withoutHooks(hooks, REMOVED_HOOKS);
+    if (isDeepStrictEqual(hooks, kept)) return [];
+    try {
+      writeFileSync(file, `${JSON.stringify({ ...settings, hooks: kept }, null, 2)}\n`);
+    } catch (error) {
+      throw new Error(`${file} cannot be written (${error.code ?? error.message}), and it holds the kit's hook of a command the kit no longer has, which the kit takes out. Let the kit write it, then run the command again.`);
+    }
+    return [relative];
+  });
+}
+
 /**
  * Whether the kit's hook is in place for one harness, and what to say when it
  * is not: `{ where, says }`, or nothing when the file already holds it.
@@ -117,6 +157,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.`;
 
@@ -355,6 +396,7 @@ const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_MAIL = new RegExp(String.raw`^(${WORD}) session mail --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const REMOVED_HOOKS = [KIT_MAIL, KIT_NUDGE];
 
 /**
  * Whether a hook entry is one of the kit's own as this kit writes it: a

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)];
 };