@assuredloop/orca-bot-kit 0.34.0 → 0.35.0

package/README.md

@@ -394,6 +394,15 @@ address that is none of your bots folder's sessions, the hook tells it so, and
 names the address `obk message to` would have given. The message goes either
 way ([ADR 0032](docs/adr/0032-a-native-message-outside-the-fleet-is-warned-about.md)).
 
+A Claude bot's `.claude/settings.json` also gets
+`"skillOverrides": { "auto-mode-setup": "off" }`, so no session of the bot stops
+on Claude Code's `Teach auto mode about your environment?` form. Your other
+skill overrides are kept. The cost: `/auto-mode-setup` is off in that bot's
+sessions, and your own sessions outside the bots folder keep it. To use it in a
+bot's sessions, set `"auto-mode-setup": "on"` under `skillOverrides` in the bot's
+`.claude/settings.local.json`, which wins over the kit's entry. The kit never
+writes that file.
+
 So: kill a tab, or reboot, and `obk up` brings the session back with the
 conversation it was having, rather than starting a new one. Clear a session —
 `/clear` on Claude Code, `/new` on Codex — and the kit writes down the new id,
@@ -616,7 +625,7 @@ verdict: which of these matter, and in what order, is for you or for Bot Father.
 ## Sessions and bots that talk
 
 Ask the kit how to reach a session, and it answers with the road and the
-address ([ADR 0042](docs/adr/0042-messaging-transport.md)):
+address ([ADR 0053](docs/adr/0053-messaging-transport.md)):
 
 ```sh
 obk message to    --bots /path/to/my-bots --to api-bot/daily
@@ -640,6 +649,13 @@ token, `<bot>.<session>`: `message to` answers the mailbox road for it, never
 that name, until the kit's launch line next starts it (`obk restart`, or
 `obk up` after its tab is gone), which gives it a token name of its own.
 
+It also includes a Claude session that the sender's own Claude Code does not
+list as live. Claude Code's messaging reaches only the sessions in its own
+registry, under its config folder (`CLAUDE_CONFIG_DIR`, or `~/.claude`). After
+a Claude account switch, Orca starts new tabs under a config folder of its own,
+so a session started before the switch and one started after it cannot reach
+each other that way. `message to` and `message send` then take the mailbox.
+
 A session's mailbox is made the first time the kit starts it, and written in
 the book beside its tab. It is an Orca Run rather than the session's tab,
 because a tab's address dies with the tab and a Run does not — so a message sent
@@ -669,7 +685,7 @@ keeps a command it was running as a background terminal after an Escape. A
 receiver reads its mail with `obk message check`, which marks it read: a bare
 `orca orchestration check` leaves it unread, and Orca then gives no more
 notices for that mailbox
-([ADR 0042](docs/adr/0042-messaging-transport.md)).
+([ADR 0053](docs/adr/0053-messaging-transport.md)).
 
 A message longer than 4 KiB is written to a file beside your bots folder and
 named in the message, so a long one arrives whole without landing a document in

package/SETUP.md

@@ -222,7 +222,7 @@ answers that screen, by the command and its arguments below the table.
 | Codex's `/new`: `Where should the new conversation run?` | `\r` | return: its selection starts on **Current checkout** (bot home); on 0.162.0 it is called **1. Use current Git worktree** (Keep using the current working directory). Never **Create new Git worktree** | Codex 0.160.0; Codex 0.162.0 (#516) |
 | Codex's update offer, `1. Update now` | `\r` | return: its selection starts on **Update now**, which accepts it | Codex 0.156.1; seen on 0.157.1 (offering 0.158.0) with the selection on **Update now**, not pressed; 0.158.0 offered 0.160.0, taken on 2026-10-02 by Bot Father's restarts |
 | `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell | oh-my-zsh bf77e35 |
-| Claude Code's `Teach auto mode about your environment?` | `obk session answer`, or `obk temp answer` for a temporary session | the kit sends Esc, which cancels it (**Not now**). On 2.1.283 and 2.1.302 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. On 2.1.283 the foot starts `←/→ to change usage`, and on 2.1.302 it starts `←/→ to change`. The values after the three settings can differ: `Also scan shell history` showed `true` on 2.1.283, and both `false` and `true` on 2.1.302. The kit sends Esc whatever the values are. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live twice on 2.1.283, in #261's live test and #239's live run 1 (#416); 2.1.278 showed a numbered list, answered with 2. Not now; the 2.1.302 form was seen live twice, in #604 and in #646, where it showed `Also scan shell history` on `true` and one Esc sent by hand removed it |
+| Claude Code's `Teach auto mode about your environment?` | `obk session answer`, or `obk temp answer` for a temporary session | the kit sends Esc, which cancels it (**Not now**). On 2.1.283, 2.1.302 and 2.1.310 it is a form, not a list: `How you use Claude here`, `Also scan shell history`, `Also scan your other repos`, `Continue`, and `Enter to continue · Esc to cancel`. On 2.1.283 the foot starts `←/→ to change usage`, and on 2.1.302 and 2.1.310 it starts `←/→ to change`. Its description wraps to the tab's width, on one row or more. The values after the three settings can differ: `Also scan shell history` showed `true` on 2.1.283, and both `false` and `true` on 2.1.302. The kit sends Esc whatever the values are. **Never send a return**: Enter is **Continue**, which starts a scan of the project, recent Claude sessions and, by default, the machine's shell history | Not yet proven: Esc cancels in Claude Code 2.1.283's code, not yet seen live (#370); the form was seen live twice on 2.1.283, in #261's live test and #239's live run 1 (#416); 2.1.278 showed a numbered list, answered with 2. Not now; the 2.1.302 form was seen live twice, in #604 and in #646, where it showed `Also scan shell history` on `true` and one Esc sent by hand removed it; the 2.1.310 form was seen live in #701, its description on one row, and one Esc sent by hand removed it |
 | Claude Code 2.1.289's `Teach auto mode about your environment?`, a numbered list: `1. Yes`, `2. Not now`, `3. Don't show again`, and `Enter to confirm · Esc to cancel`, above the input box | `obk session answer`, or `obk temp answer` for a temporary session | the kit goes down, then returns, to **2. Not now**: its selection starts on **1. Yes**. The kit reads the screen after the down arrow, and sends the return only with the selection on **2. Not now**. Never **1. Yes**, which starts the teach scan, and never **3. Don't show again** | Not yet proven: the list was seen live on 2.1.289 with its selection on 1. Yes, in #489's live run 1, and was not answered there |
 
 Each key counts on where the selection starts, as it did on the version named.

package/package.json

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

package/skills/obk-bot-building/SKILL.md

@@ -327,7 +327,8 @@ selection on 1. Yes (seen live, not answered, in #489). The kit goes down to
 form again, with `Also scan shell history` on `false` and a foot that starts
 `←/→ to change` (seen live in #604), and later with it on `true` (#646). The
 values of its three settings can differ, and the kit sends it Esc whatever
-they are. Codex's hooks
+they are. On 2.1.310 it is the same form, its description wrapped to the
+tab's width, on one row in a wide tab (#701). Codex's hooks
 question matters most. The kit's hook is how the book learns which
 conversation the session is running, and until it is answered the
 conversation has not started. Codex's trust applies to the repository root,
@@ -344,7 +345,7 @@ permission rule can allow that one command, where it cannot allow keys sent
 into any tab. The same goes for Claude Code's `Teach auto mode` screen on a
 temporary session you made: answer it with `obk temp answer --bots <bots>
 --name <session>`. It answers only a shape in the table exactly as the kit
-knows it (Esc on the 2.1.283 and 2.1.302 forms, 2. Not now on the 2.1.289 list, the return
+knows it (Esc on the 2.1.283, 2.1.302 and 2.1.310 forms, 2. Not now on the 2.1.289 list, the return
 only after a second look), refuses any other screen, and checks that it went. The kit's
 default set allows it, as it allows `obk temp trust-hooks`.
 

package/src/book.js

@@ -341,6 +341,23 @@ export function takeBotTurn(home) {
 /** Beside the book's lock, with the bot's name: the lock files of its sessions carry one more part. */
 const botLockFile = (home) => path.join(botLocks(home), `${encodeURIComponent(path.basename(realpathSync(home)))}.bot.lock`);
 
+/**
+ * The right to find or make the bot's Orca project (#712), held by `up` from
+ * its look for a `.git` a dead run left in the bot home until the project is
+ * there. Two runs of `up` for one bot then never take away the `.git` that
+ * the other is registering the home with. A lock goes with its process, so a
+ * run that died holds no turn.
+ */
+export function takeProjectTurn(home) {
+  const file = botLockFile(home).replace(/\.bot\.lock$/, '.project.lock');
+  try {
+    return lockOn(file, MAILBOX_WAIT_MS);
+  } catch (error) {
+    if (error instanceof LockNotWritable) throw error;
+    throw new Error(`waited ${MAILBOX_WAIT_MS / 1000} seconds for another run to finish making ${home}'s Orca project and it did not (${error.message}). Nothing was changed. Try again; if nothing is running, remove ${file}, which is where runs take their turn.`);
+  }
+}
+
 /**
  * One session's turn at its mailbox (#321): held by `session mailbox` for its
  * whole step, by `message check` in the session's own tab for its bind, read and

package/src/clear.js

@@ -230,10 +230,12 @@ async function enter(it, verb, before = () => {}) {
  * runs just before the command is typed; `cannot` adds to a refusal what a
  * wrong screen means; `close`, `{ key, check }`, is one more key typed once
  * `check` passes, and its own check of the screen before the return; past
- * `deadline`, a time, what was typed is taken back and nothing is entered.
+ * `deadline`, a time, what was typed is taken back and nothing is entered;
+ * `whole` sends the command in one write and not a character a send; `last`
+ * runs after the last look, given it, with nothing between it and the first key.
  * Returns the command, the handle it went into, and when it was typed.
  */
-export async function typeCommand(it, command, { before = () => {}, check = menuWrong, cannot = () => '', close, deadline = Infinity } = {}) {
+export async function typeCommand(it, command, { before = () => {}, check = menuWrong, cannot = () => '', close, deadline = Infinity, whole = false, last = () => {} } = {}) {
   // Nothing may be in the input line before: no draft for the command to join.
   // Orca gives a draft in the line beside the screen, and the screen's line
   // then reads the pointer alone (#510, #516). Where it gives none, Codex's
@@ -262,6 +264,7 @@ export async function typeCommand(it, command, { before = () => {}, check = menu
   const ready = lookAt(it);
   if (ready.why !== undefined) throw new Error(`${it.name}: nothing was typed, because ${ready.why}.`);
   emptyLine(ready);
+  last(ready);
   const { handle } = ready;
   const typedAt = Date.now();
   // One character a send, each after a look through the gate, so nothing goes
@@ -297,22 +300,26 @@ export async function typeCommand(it, command, { before = () => {}, check = menu
     takeBack();
     throw new Error(`${it.name}: ${command} was being typed, and after ${sofar} ${look.why}, so what was typed was taken back and nothing was entered.`);
   };
-  const typeKey = (char) => {
+  const typeKey = (keys) => {
     try {
-      send(handle, char);
+      send(handle, keys);
     } catch (error) {
       // A send Orca did not answer in time may have gone in all the same.
       // Counted only where the line was empty before the first key, so the
       // one backspace too many can take nothing of the user's (#480 review).
-      if (error.code === TIMED_OUT && (it.harness === 'codex' || it.harness === 'pi')) typed += 1;
+      if (error.code === TIMED_OUT && (it.harness === 'codex' || it.harness === 'pi')) typed += [...keys].length;
       throw error;
     }
-    typed += 1;
+    typed += [...keys].length;
   };
   try {
-    for (const char of command) {
-      if (typed > 0) await lookAgain();
-      typeKey(char);
+    // Whole, a write Orca's own notice cannot land inside (#713).
+    if (whole) typeKey(command);
+    else {
+      for (const char of command) {
+        if (typed > 0) await lookAgain();
+        typeKey(char);
+      }
     }
     await lookAgain();
     let wrong = await typedWrong(handle, it.harness, command, version, check);

package/src/cli.js

@@ -1319,6 +1319,9 @@ function toLines(answer, bots, where) {
     ...(answer.unnamed === true
       ? [`             ${where} is a Claude session running under no name the kit gave it: it was started before the kit named sessions, and nothing renames a live harness. It gets one the next time it starts. Until then the mailbox is the road that reaches it.`]
       : []),
+    ...(answer.unlisted === true
+      ? [`             ${where} is a Claude session of your approval class, but your own Claude Code does not list it among the live sessions its messaging reaches: it runs under another Claude config folder, or it is not running. So the mailbox is the road that reaches it.`]
+      : []),
     `             Send it:  ${shellWord(ownCli())} message send --bots ${shellWord(bots)} --to ${shellWord(where)} --subject <text> --text <text>`,
   ];
 }

package/src/hooks.js

@@ -101,7 +101,8 @@ 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, REMOVED_HOOKS)) };
+  const hooked = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, withoutHooks(started, REMOVED_HOOKS)) };
+  const wanted = harness === 'claude' ? { ...hooked, skillOverrides: withTeachOff(settings.skillOverrides, file) } : hooked;
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -278,6 +279,29 @@ function withKitHook(hooks, file, mine) {
   return { ...events, [EVENT]: [...(events[EVENT] ?? []), { hooks: [mine] }] };
 }
 
+/**
+ * The file's skill overrides with Claude Code's `auto-mode-setup` off, so no
+ * session of the bot stops on its "Teach auto mode about your environment?"
+ * form (#708, teach-form-off/R1). Claude Code 2.1.310 shows the form only when
+ * the merged settings leave that command on, and a project file counts (tech
+ * notes). Every other override is the user's and stays. A user who wants the
+ * command in the bot's sessions turns it on in `.claude/settings.local.json`,
+ * which wins over this file and which the kit never writes.
+ *
+ * Anything there that is not a mapping is theirs, and is refused rather than
+ * written over, as a `hooks` entry is.
+ */
+function withTeachOff(overrides, file) {
+  if (overrides === undefined) return { [TEACH_SKILL]: 'off' };
+  if (overrides === null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    throw new Error(`${file} has a skillOverrides entry that is not a mapping of skill names, and the kit turns Claude Code's ${TEACH_SKILL} off in there. Fix it or move it aside, then run the command again.`);
+  }
+  return { ...overrides, [TEACH_SKILL]: 'off' };
+}
+
+/** Claude Code's command behind its Teach auto mode form. */
+const TEACH_SKILL = 'auto-mode-setup';
+
 /** Each harness's kit hooks beside its session hook, as `toolHookOf` gives each. */
 const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
   (harness === 'claude' ? ['sent'] : ['name']).map((kind) => toolHookOf(kind, bots, bot, cli));

package/src/launch.js

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

package/src/message.js

@@ -1,4 +1,4 @@
-// `obk message`: one session writing to another (PRD 6.9, ADR 0042).
+// `obk message`: one session writing to another (PRD 6.9, ADR 0053).
 //
 // Two roads, and the bot never picks. Claude to Claude in the same approval
 // class is the harness's own messaging, which no command line can send for it —
@@ -10,20 +10,21 @@
 // refuses a send once the pane is gone. A Run survives the tab, the relaunch
 // and the restart, so a session's address is its Run (tech notes, section 1).
 //
-// One road and one signal (#555, ADR 0042): the letter goes into the
+// One road and one signal (#555, ADR 0053): 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. 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 { mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
 import { MAILBOX_WAIT_MS, readBook, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
 import { harnessOf, isAddressOf, kitFolders, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
-import { ackMailbox, coordinatorOf, listedOrphaned, loadInWindow, postMessage, pressEscape, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, useMailbox } from './orca.js';
+import { ackMailbox, coordinatorOf, isRunning, listedOrphaned, loadInWindow, postMessage, pressEscape, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -89,11 +90,16 @@ export function findSession(bots, target) {
  */
 export function roadBetween(from, to) {
   const pair = from.harness === 'claude' && to.harness === 'claude' && from.approval === to.approval;
-  if (pair && to.address !== undefined) return { transport: 'native', address: to.address };
+  const mailbox = to.mailbox === undefined ? undefined : `run:${to.mailbox}`;
+  if (pair && to.address !== undefined) {
+    // Native only to a session the sender's own Claude Code lists: its
+    // messaging reaches no other, and the mailbox does (#700).
+    return listedLive(to.address) ? { transport: 'native', address: to.address } : { transport: 'orca', address: mailbox, unlisted: true };
+  }
 
   return {
     transport: 'orca',
-    address: to.mailbox === undefined ? undefined : `run:${to.mailbox}`,
+    address: mailbox,
     // A Claude pair that the native road cannot carry, because the receiver is
     // running under no name the kit gave it: it was started before the kit
     // named sessions, or before it gave them names of their own (#286), and
@@ -104,6 +110,38 @@ export function roadBetween(from, to) {
   };
 }
 
+/**
+ * Whether the sender's own Claude Code lists `address` as a live session. Its
+ * messaging reaches only the sessions in its own registry, one
+ * `<pid>.json` for each, in `sessions` under its config dir, and two Claude
+ * Codes with two config dirs do not see each other: Orca starts a tab under a
+ * Claude profile of its own after an account switch, and a session started
+ * before it is in `~/.claude` (#700; tech notes, section 2). The command runs
+ * in the sender's environment, so its CLAUDE_CONFIG_DIR is the sender's. An
+ * entry counts when its `name` is the address, unless `ps` says its pid is not
+ * there: a check that cannot tell keeps the entry, so a slow `ps` opens no
+ * second road to a session the sender can reach (review of PR #702). A folder
+ * or a file that cannot be read lists nobody.
+ */
+function listedLive(address) {
+  const registry = path.join(process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), '.claude'), 'sessions');
+  let files;
+  try {
+    files = readdirSync(registry).filter((file) => file.endsWith('.json'));
+  } catch {
+    return false;
+  }
+  return files.some((file) => {
+    let entry;
+    try {
+      entry = JSON.parse(readFileSync(path.join(registry, file), 'utf8'));
+    } catch {
+      return false;
+    }
+    return entry?.name === address && Number.isInteger(entry.pid) && entry.pid > 0 && isRunning(entry.pid, LOOK_MS) !== false;
+  });
+}
+
 /** What `obk message to` answers: the road, the address, and who is at each end. */
 export function lookUp(bots, { to: target, from: sender, tab }) {
   const from = whoIsWriting(bots, sender, tab);

package/src/name.js

@@ -19,6 +19,7 @@ import { readBook, takeNameTurn, takeTypingTurn } from './book.js';
 import { botDir, readBot } from './bot.js';
 import { sessionToType, typeCommand } from './clear.js';
 import { harnessOf } from './launch.js';
+import { mailIn } from './orca.js';
 import { sessionsOf } from './up.js';
 
 /**
@@ -40,6 +41,9 @@ const DEADLINE_MS = 240_000;
 const CONFIRM_MS = 10_000;
 const ASK_MS = 500;
 
+/** How many of a mailbox's newest letters are read, as `obk health` reads them. */
+const MAIL_READ = 100;
+
 /**
  * Name the thread that just ended a turn in the tab `tabId`, as Codex's Stop
  * hook `said` it, when that tab is a Codex session of `bot` and its thread does
@@ -85,8 +89,27 @@ export async function nameSession(bots, bot, said, tabId) {
       typing = takeTypingTurn(home, session, 0);
       if (typing === undefined) throw new Error(`${it.name}: nothing was typed, because the kit is typing into its tab already.`);
     };
+    // Orca types its notice into an idle tab, the input line or not, and a
+    // notice inside the command became the thread's name (#713). A letter not
+    // delivered yet is one Orca is about to ring for: name later. Read last
+    // of all before the write.
+    let footer;
+    const last = (ready) => {
+      footer = rowUnder(ready.rows);
+      const mailbox = entry.mailbox;
+      if (mailbox === undefined) return;
+      let letters;
+      try {
+        letters = mailIn(mailbox, MAIL_READ);
+      } catch (error) {
+        throw new Error(`${it.name}: nothing was typed, because its mailbox could not be read: ${error.message}`);
+      }
+      if (letters.some((letter) => !letter.read && letter.delivered_at == null)) {
+        throw new Error(`${it.name}: nothing was typed, because Orca has yet to tell it of mail.`);
+      }
+    };
     try {
-      await typeCommand(it, `/rename ${name}`, { check: renameWrong, deadline, before });
+      await typeCommand(it, `/rename ${name}`, { check: renameWrong(() => footer), deadline, before, last, whole: true });
     } finally {
       typing?.release();
     }
@@ -119,6 +142,12 @@ function nameOf(thread) {
   return name;
 }
 
+/** The first row with text under the input line, the lowest row Codex's pointer starts, or undefined. */
+function rowUnder(rows) {
+  const at = rows.findLastIndex((row) => /^ *›/.test(row));
+  return rows.slice(at + 1).find((row) => row.trim() !== '')?.trimEnd();
+}
+
 /**
  * Why the screen does not show `command` typed and ready, or undefined when it
  * does: the input line, the lowest row Codex's pointer starts, reads the
@@ -127,13 +156,18 @@ function nameOf(thread) {
  * `sync_command_popup`, rust-v0.160.0), so a menu still open means the line is
  * not what it seems. Where Orca gives a draft, the draft is the line's text:
  * Codex 0.162.0's line on the screen then reads its pointer alone (#516).
+ * Under the line, the first row with text is the one that stood there before
+ * the write, `footer()`: Codex's status row, whatever the user set it to show.
  */
-function renameWrong(rows, _harness, command, _version, draft) {
+const renameWrong = (footer) => (rows, _harness, command, _version, draft) => {
   const at = rows.findLastIndex((row) => /^ *›/.test(row));
   if (at < 0) return { why: 'its screen shows no input line' };
   const line = draft === undefined ? rows[at].replaceAll(' ', ' ').trim() : `› ${draft}`;
   if (line !== `› ${command}`) return { why: `its input line reads "${line}"` };
   const above = rows.slice(0, at).findLast((row) => row.trim() !== '');
   if (above !== undefined && /^ *(?:› +)?\/\S/.test(above)) return { why: `a menu of commands stands above its input line: "${above.trim()}"` };
+  // Any other row there is more of the line: Orca's notice, for one (#713).
+  const under = rowUnder(rows);
+  if (under !== footer()) return { why: `text stands under its input line: "${under?.trim()}"` };
   return undefined;
-}
+};

package/src/orca.js

@@ -8,7 +8,7 @@
 // handed to Orca on the command line.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
@@ -290,12 +290,63 @@ function argsIn(read) {
  * repo as git kind, which Orca gives no workspace at all, so no tab can be
  * created in it. `setup-update` turns it into the folder workspace a bot needs
  * and names the project in one go.
+ *
+ * Orca 1.4.236 and later register the top folder of the git repo that holds
+ * the folder they are given: for a bot home, the whole bots folder (#712). So
+ * for the time of `repo add` the home gets a `.git` of its own, which makes it
+ * its own top folder, and that `.git` goes straight after. One that was there
+ * before is the user's, and stays as it was.
  */
 export function makeProject(home, title) {
-  const setupId = orca(['repo', 'add', '--path', home]).repo.id;
+  const made = gitOfItsOwn(home);
+  let setupId;
+  try {
+    setupId = orca(['repo', 'add', '--path', home]).repo.id;
+  } finally {
+    if (made) rmSync(path.join(home, '.git'), { recursive: true, force: true });
+  }
   return asFolderProject(setupId, title);
 }
 
+/** The file inside a `.git` that says the kit made it for one `repo add`. */
+const KIT_GIT_MARK = 'obk-made-for-orca';
+
+/**
+ * Give `home` a `.git` of its own: true when this call made it, false when one
+ * is there already. The mkdir fails on anything already there, so the kit
+ * never takes over a `.git` it did not make, and the mark goes in before git
+ * fills it, so one left by a run that died is known as the kit's.
+ */
+function gitOfItsOwn(home) {
+  const git = path.join(home, '.git');
+  try {
+    mkdirSync(git);
+  } catch (error) {
+    if (error.code === 'EEXIST') return false;
+    throw error;
+  }
+  try {
+    writeFileSync(path.join(git, KIT_GIT_MARK), 'obk made this for one `orca repo add` and takes it away after.\n');
+    const result = spawnSync('git', ['init', '--quiet', home], { encoding: 'utf8' });
+    if (result.error) throw new Error(`could not run git: ${result.error.message}`);
+    if (result.status !== 0) throw new Error(`git init failed in ${home}: ${(result.stderr || '').trim()}`);
+  } catch (error) {
+    rmSync(git, { recursive: true, force: true });
+    throw error;
+  }
+  return true;
+}
+
+/**
+ * Take away the `.git` that a run which died during `makeProject` left in
+ * `home`. Only one that holds the kit's mark: any other is the user's.
+ */
+export function dropLeftGit(home) {
+  const git = path.join(home, '.git');
+  const stat = lstatSync(git, { throwIfNoEntry: false });
+  if (stat?.isDirectory() && existsSync(path.join(git, KIT_GIT_MARK))) rmSync(git, { recursive: true, force: true });
+}
+
 /** Make an existing registration a folder workspace called `title`. */
 export function asFolderProject(setupId, title) {
   return orca(['project', 'setup-update', '--setup', setupId, '--kind', 'folder', '--display-name', title])
@@ -1048,9 +1099,25 @@ export function wordsOfProcess(pid) {
   return asked.stdout.trim().split(/\s+/);
 }
 
+/**
+ * Whether the process `pid` runs now, as `ps` answers for it: false only when
+ * `ps` says no process has that pid, and undefined when it cannot tell: `ps`
+ * did not start, failed, ran out of time or printed a line it cannot read.
+ * macOS's `ps` answers a pid that is not there with exit 1 and nothing on
+ * stdout or stderr (seen on macOS 27.0.1), and it exits 1 on an error of its
+ * own too, with the error on stderr (review of PR #702).
+ */
+export function isRunning(pid, readMs) {
+  const asked = askPs(pid, readMs);
+  if (asked.error === undefined && asked.status === 1 && asked.stdout.trim() === '' && asked.stderr.trim() === '') return false;
+  return psLine(pid, readMs, asked)?.comm === undefined ? undefined : true;
+}
+
+const askPs = (pid, readMs) =>
+  spawnSync(PS, ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8', ...(readMs === undefined ? {} : { timeout: readMs }) });
+
 /** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, `{ late: true }` past `readMs`, or undefined. */
-function psLine(pid, readMs) {
-  const asked = spawnSync(PS, ['-o', 'pid=,ppid=,tpgid=,comm=', '-p', String(pid)], { encoding: 'utf8', ...(readMs === undefined ? {} : { timeout: readMs }) });
+function psLine(pid, readMs, asked = askPs(pid, readMs)) {
   if (asked.error?.code === 'ETIMEDOUT') return { late: true };
   if (asked.error || asked.status !== 0) return undefined;
   const line = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(.+?)\s*$/.exec(asked.stdout);

package/src/permissions.js

@@ -55,7 +55,7 @@ export function defaultRules(bots, cli = ownCli()) {
 /**
  * Orca's check, which the set held until #564: the kit's rules tell a bot to
  * read its mail with `obk message check`, never with the bare check, which
- * leaves it unread (ADR 0042).
+ * leaves it unread (ADR 0053).
  */
 const ORCA_CHECK = 'Bash(orca orchestration check --run:*)';
 

package/src/retire.js

@@ -17,7 +17,7 @@
 //
 // Closing a tab here ends the conversation in it on purpose, so unlike a
 // restart or a pause it does not wait for the book to know which one it was.
-// The mailbox Runs stay: Orca has no way to remove one (ADR 0042).
+// The mailbox Runs stay: Orca has no way to remove one (ADR 0053).
 //
 // What a session started in its work dir and left running is stopped once its
 // tab is closed, and named (#537): see processes.js.

package/src/sent.js

@@ -8,11 +8,14 @@
 // has gone either way. Nothing here decides anything about it, and anything it
 // cannot read is silence (ADR 0022: a hook never disturbs the session).
 //
-// It reads the send from its fields, never from its wording. Seen on Claude
-// Code 2.1.283: a send to an in-process teammate answers with a `routing`
-// object, and one to another session without it; the input's `to` names the
-// target, as a session's name with an optional ` [xxxxxx]` reference, or as a
-// `uds:` socket path when answering a message, which no book can map.
+// It reads the send from its fields, never from its wording. Seen in the
+// transcripts of Claude Code 2.1.281 to 2.1.310 (#705): a send to another
+// session that went answers with a `msg_id` and with neither `routing` nor
+// `pin`. A send to a subagent or teammate inside the process has `routing` or
+// `pin`, or no `msg_id`. The transcript also has a `display`, but the copy the
+// model reads does not, and the hook may get either. The input's `to` names
+// the target, as a session's name with an optional ` [xxxxxx]` reference, or
+// as a `uds:` socket path when answering a message, which no book can map.
 
 import { readBook } from './book.js';
 import { botDir, botNames } from './bot.js';
@@ -28,9 +31,8 @@ export function sentWarning(bots, said) {
   if (said?.tool_name !== 'SendMessage') return undefined;
   const to = said.tool_input?.to;
   if (typeof to !== 'string') return undefined;
-  const result = resultOf(said);
-  // A teammate in the same session, or a send that did not go: not this.
-  if (result === undefined || result.success !== true || 'routing' in result) return undefined;
+  // A subagent or teammate in the same session, or a send that did not go: not this.
+  if (!wentToAnotherSession(resultOf(said))) return undefined;
   if (/^(uds|bridge):/.test(to)) return undefined;
 
   const name = to.replace(/\s*\[[^\]]*\]\s*$/, '').trim();
@@ -70,6 +72,12 @@ function roadTo(bots, meant, ask) {
   return `If you meant ${who}, its session address is ${meant.address}; ${ask} says which road to take from your session.`;
 }
 
+/** Whether the send answered as one that went to another session. */
+function wentToAnotherSession(result) {
+  return result !== undefined && result.success === true && 'msg_id' in result
+    && !('routing' in result) && !('pin' in result);
+}
+
 /** What the send answered, as an object: Claude Code hands it over as one, or as its JSON. */
 function resultOf(said) {
   const raw = said.tool_output ?? said.tool_response;

package/src/temp.js

@@ -552,11 +552,17 @@ const TEACH_FOOT = /Enter to .*· Esc to cancel/;
  */
 const setting = (name) => ({ name, fits: (row) => row.startsWith(name) && /^ +\S/.test(row.slice(name.length)) });
 
+/**
+ * Text Claude Code wraps at word breaks to the tab's width, on one row or
+ * more: its words, in order, and nothing else (#701). Claude Code 2.1.310
+ * holds the Teach form's description as one string (read in its code).
+ */
+const wrapped = (text) => ({ text });
+
 /** The Teach form's rows, from its title to its foot, with `foot`. */
 const teachForm = (foot) => [
   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.',
+  wrapped('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.'),
   setting('How you use Claude here'),
   setting('Also scan shell history'),
   setting('Also scan your other repos'),
@@ -568,11 +574,12 @@ const teachForm = (foot) => [
  * The known shapes of the Teach screen, from its title to its foot, each as
  * captured live, with what answers it. Rows are compared trimmed, the pointer
  * `❯` taken out, so the pointer may sit on any one of them. A setting row
- * matches by its name, whatever its value.
+ * matches by its name, whatever its value, and the form's description by its
+ * words, on as many rows as the tab's width wraps it onto (#701).
  *
- * 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
+ * Claude Code 2.1.283's form (#261's live test, #416) and 2.1.302's (#604),
+ * which 2.1.310 draws too (#701), 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).
  */
@@ -599,10 +606,30 @@ const NOT_NOW_CHOICE = '2. Not now';
 const unpointed = (row) => row.replace('❯', ' ').trim();
 
 /** Whether a shape's row `want` is the screen's `row`, as unpointed gives it. */
-const fitsRow = (want, row) => (typeof want === 'string' ? row === want : want.fits(row));
+const fitsRow = (want, row) => (typeof want === 'string' ? row === want : want.text !== undefined ? row === want.text : want.fits(row));
 
 /** A shape's row as a refusal names it. */
-const shapeRow = (want) => (typeof want === 'string' ? want : `${want.name} and a value`);
+const shapeRow = (want) => (typeof want === 'string' ? want : want.text ?? `${want.name} and a value`);
+
+/**
+ * `block` with the first run of rows that is `shape`'s wrapped text, joined
+ * with single spaces, put on one row, unpointed; `block` as it is when there
+ * is no such run.
+ */
+function unwrapped(block, shape) {
+  const text = shape.rows.find((want) => want.text !== undefined)?.text;
+  if (text === undefined) return block;
+  for (let from = 0; from < block.length; from += 1) {
+    let joined = unpointed(block[from]);
+    for (let to = from; text.startsWith(joined); ) {
+      if (joined === text) return [...block.slice(0, from), text, ...block.slice(to + 1)];
+      to += 1;
+      if (to === block.length) break;
+      joined = `${joined} ${unpointed(block[to])}`;
+    }
+  }
+  return block;
+}
 
 /** The full-width rule Claude Code draws right above the screen's title: `─` in 2.1.289, `▔` in 2.1.283. */
 const ABOVE_TITLE = /^(?:─+|▔+)$/;
@@ -637,13 +664,14 @@ function teachScreen(rows) {
   const misfits = TEACH_SHAPES.map((shape) => {
     const pointers = block.filter((row) => row.includes('❯')).length;
     if (pointers !== 1) return `${pointers} rows with the pointer ❯, where ${shape.name} has one`;
-    const odd = block.find((row) => !shape.rows.some((want) => fitsRow(want, unpointed(row))));
+    const folded = unwrapped(block, shape);
+    const odd = folded.find((row) => !shape.rows.some((want) => fitsRow(want, unpointed(row))));
     if (odd !== undefined) return `a row ${shape.name} does not have: ${odd.trim()}`;
-    const missing = shape.rows.find((want) => !block.some((row) => fitsRow(want, unpointed(row))));
+    const missing = shape.rows.find((want) => !folded.some((row) => fitsRow(want, unpointed(row))));
     if (missing !== undefined) return `no row ${shapeRow(missing)}, which ${shape.name} has`;
-    if (block.length !== shape.rows.length) return `${block.length} rows, where ${shape.name} has ${shape.rows.length}`;
-    const moved = block.findIndex((row, at) => !fitsRow(shape.rows[at], unpointed(row)));
-    if (moved >= 0) return `the row ${block[moved].trim()} where ${shape.name} has ${shapeRow(shape.rows[moved])}`;
+    if (folded.length !== shape.rows.length) return `${folded.length} rows, where ${shape.name} has ${shape.rows.length}`;
+    const moved = folded.findIndex((row, at) => !fitsRow(shape.rows[at], unpointed(row)));
+    if (moved >= 0) return `the row ${folded[moved].trim()} where ${shape.name} has ${shapeRow(shape.rows[moved])}`;
     return undefined;
   });
   const fits = misfits.findIndex((misfit) => misfit === undefined);

package/src/up.js

@@ -9,14 +9,14 @@ 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, rememberSession, 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, takeProjectTurn, TYPING_HELD, TYPING_WAIT_MS, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { dropRemovedHooks, installHook } from './hooks.js';
 import { writePermissions } from './permissions.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, loadInWindow, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, runMissing, screenRows, shellInTab, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { addressOf, HARNESSES, harnessOf, isAddressOf, isShortPrompt, kitFolders, launchCommand, mailboxStep, ownCli, reachesMail, sessionTrouble, shellWord, startPrompt, workDirOf } from './launch.js';
+import { asFolderProject, coordinatorOf, dropLeftGit, findProject, harnessInTab, loadInWindow, 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';
 import { linkSkills } from './skills.js';
@@ -151,12 +151,14 @@ export function prepareBots(bots, names, onlySession) {
   // and a bot folder the kit cannot write it into stops the run with nothing
   // opened anywhere. Only the harnesses a bot actually runs on; a bot with no
   // sessions gets none. The hooks of commands the kit no longer has go from
-  // every hooks file the bot has, of a harness it has left too (#613).
+  // every hooks file the bot has, of a harness it has left too (#613). That
+  // comes after the kit's own hooks, which take them out of the files they
+  // write anyway, so a file the kit refuses is left as the user wrote it (#708).
   for (const { bot, home } of running) {
-    dropRemovedHooks(home);
     for (const harness of new Set(awake(sessionsOf(bot, onlySession)).map((session) => harnessOf(session, bot.harness)))) {
       installHook(home, harness, { bots, bot: bot.name });
     }
+    dropRemovedHooks(home);
   }
 
   // And the permission rules the user allowed, beside the hook and for the same
@@ -433,7 +435,7 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // 0.157.1 (#226). So it is given one line, through the same gate as a mail
   // notice, which the owner allowed. A fresh start's first turn is its prompt.
   const list = harness === 'codex' && launch.resume !== undefined && tui.running === true
-    ? await typeListLine(home, session.name, made.tabId)
+    ? await typeListLine(home, session.name, made.tabId, { line: listLine(bots) })
     : undefined;
 
   return entry(made, {
@@ -503,8 +505,15 @@ async function shellNotReady(handle) {
     : `the shell is asking: ${last.trim()} (${wait})`;
 }
 
-/** The line a resumed Codex session is typed so Orca lists it, in the architect's words (#226). */
-const LIST_LINE = 'obk: this session was resumed in a new tab, and this line is only so Orca lists it. Reply "ok"; nothing else is asked.';
+/**
+ * The line a resumed Codex session is typed so Orca lists it, in the
+ * architect's words (#226). It names the kit's mail check as the bot's rules
+ * do, because a restart often comes for mail that is waiting (#630), and a line
+ * that asked for "ok" alone had the session drop the mail it had just read (#709).
+ */
+const listLine = (bots) => 'obk: this session was resumed in a new tab, and the kit types this line so Orca lists it.'
+  + ` Read your mail with \`${shellWord(ownCli())} message check --bots ${shellWord(bots)}\`, and do what it asks.`
+  + ' That includes mail you read just before this line. If there is none, reply "ok".';
 
 /**
  * How long a resumed Codex tab is given to be one the kit may type into: live,
@@ -516,15 +525,15 @@ const LIST_LOOK_MS = 2000;
 const LIST_ASK_MS = 500;
 
 /**
- * Type `line`, LIST_LINE unless told otherwise, into the tab `tabId` of
- * `session` once the gate every typed line goes through lets it:
+ * Type `line` into the tab `tabId` of `session` once the gate every typed
+ * line goes through lets it:
  * `{ typed: true }`, or `{ typed: false, why }` with the gate's last reason
  * once LIST_WAIT_MS is up. Nothing goes into a question, a form or a menu
  * (#329, #416), nor into a tab the kit cannot tell about. Each look and its
  * line are taken in the session's turn for a line (#482), unless the caller
  * says it holds the session's typing turn already (`held`).
  */
-export async function typeListLine(home, session, tabId, { line = LIST_LINE, held = false } = {}) {
+export async function typeListLine(home, session, tabId, { line, held = false }) {
   const until = Date.now() + LIST_WAIT_MS;
   for (;;) {
     let turn;
@@ -926,9 +935,15 @@ const setAside = (entry, which) => (which.ranOn === undefined
  * all, so no tab can be opened in it.
  */
 function orcaProject(home, title) {
-  const found = findProject(home);
-  if (found === undefined) return ids(makeProject(home, title), 'made');
-  return found.kind === 'folder' ? ids(found) : ids(asFolderProject(found.id, title), 'renamed');
+  const turn = takeProjectTurn(home);
+  try {
+    dropLeftGit(home);
+    const found = findProject(home);
+    if (found === undefined) return ids(makeProject(home, title), 'made');
+    return found.kind === 'folder' ? ids(found) : ids(asFolderProject(found.id, title), 'renamed');
+  } finally {
+    turn.release();
+  }
 }
 
 const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, change });