@assuredloop/orca-bot-kit 0.27.0 → 0.29.0

package/src/run.js

@@ -0,0 +1,155 @@
+// `obk run --timeout <seconds> -- <command…>`: one command run with a hard time
+// limit (#532). macOS has no `timeout`, and the fleet's form for a bounded run,
+// `perl -e 'alarm …; exec @ARGV' -- <command>`, cannot be allowed by a narrow
+// rule, since perl runs whatever its arguments say. A rule for this command
+// names the real command after `--`, and the kit judges that command as a rule
+// of its own (permissions.js). It runs whatever its arguments say too, so it is
+// never in the default set (ADR 0050).
+//
+// The command runs with no shell, in a process group of its own, so the time
+// limit stops what it started as well. Its exit code comes back as it is; one
+// ended by a signal the kit did not send comes back as 128 and the signal's
+// number, as a shell gives it.
+
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+
+/** The exit code of a run the time limit stopped, as GNU timeout gives it. */
+const TIMED_OUT = 124;
+
+/** The exit codes a shell gives a command it cannot find, and one it cannot run. */
+const NOT_FOUND = 127;
+const CANNOT_RUN = 126;
+
+/** How long the group has after SIGTERM before SIGKILL, as `retire` gives a session's processes (#537). */
+const GRACE_MS = 3000;
+
+/** How often the kit looks whether anything of the group still runs. */
+const LOOK_MS = 100;
+
+/** The longest time limit a timer holds, in seconds: about 24 days. */
+const LONGEST = Math.floor((2 ** 31 - 1) / 1000);
+
+/** The signals that end the kit and that it passes on to the command's group, so it is not left running. */
+const PASSED_ON = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+const USE = 'obk run takes --timeout <seconds>, then --, then the command: obk run --timeout 300 -- go test ./...';
+
+/**
+ * The time limit and the command from `obk run`'s arguments, or a refusal.
+ * Only `--timeout` goes before `--`; everything after it is the command's.
+ */
+export function parseRun(args) {
+  const end = args.indexOf('--');
+  const options = end === -1 ? args : args.slice(0, end);
+  let value;
+  for (let at = 0; at < options.length; at += 1) {
+    const option = options[at];
+    if (option === '--timeout' && at + 1 < options.length && value === undefined) {
+      value = options[at + 1];
+      at += 1;
+    } else if (option.startsWith('--timeout=') && value === undefined) {
+      value = option.slice('--timeout='.length);
+    } else {
+      throw new Error(`run does not take ${option}. ${USE}. Nothing was run.`);
+    }
+  }
+  if (value === undefined) throw new Error(`run needs --timeout <seconds>: how long the command may run. ${USE}. Nothing was run.`);
+  if (!/^\d+$/.test(value) || Number(value) === 0 || Number(value) > LONGEST) {
+    throw new Error(`run's --timeout is a whole number of seconds from 1 to ${LONGEST}, and got: ${value === '' ? 'nothing' : value}. Nothing was run.`);
+  }
+  const command = end === -1 ? [] : args.slice(end + 1);
+  if (command.length === 0) throw new Error(`run needs the command after --. ${USE}. Nothing was run.`);
+  return { seconds: Number(value), command };
+}
+
+/**
+ * Run the command with its time limit, its input and output the caller's, and
+ * give back the exit code `obk run` exits with. The run ends when nothing of
+ * the command's group runs any more: a process the command started and left
+ * running is held to the same limit, and to a signal the kit passes on.
+ */
+export function runBounded({ seconds, command }) {
+  return new Promise((resolve) => {
+    // `detached` makes the command the leader of a group of its own, so its
+    // pid, taken here at spawn, is the group's id.
+    const child = spawn(command[0], command.slice(1), { stdio: 'inherit', detached: true });
+    // The leader's exit code, once it has exited.
+    let exitCode;
+    let stopping = false;
+    let result;
+    let killAt;
+    let deadline;
+    let look;
+    const signal = (pid, name) => {
+      try {
+        process.kill(pid, name);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    // Each process of the group gets a signal once. The leader gets it by its
+    // own pid as well only when it may have left the group: when nothing is
+    // left in the group, or for SIGKILL, which no handler sees. And only
+    // while it has not exited, since its pid is free again after that.
+    const group = (name) => {
+      const sent = signal(-child.pid, name);
+      if (exitCode === undefined && name !== 0 && (!sent || name === 'SIGKILL')) signal(child.pid, name);
+      return sent;
+    };
+
+    const finish = (code) => {
+      clearTimeout(deadline);
+      clearTimeout(look);
+      for (const name of PASSED_ON) process.off(name, passOn);
+      resolve(code);
+    };
+
+    // Once the leader has exited or the group is being stopped: look until
+    // nothing of the group runs, and send SIGKILL when the grace is over.
+    const watch = () => {
+      if (exitCode !== undefined && !group(0)) return finish(result ?? exitCode);
+      if (killAt !== undefined && Date.now() >= killAt) {
+        group('SIGKILL');
+        killAt = undefined;
+      }
+      look = setTimeout(watch, LOOK_MS);
+      return undefined;
+    };
+
+    // Stop the group: `name` first, then SIGKILL to what still runs after the
+    // grace. obk run exits with `code`, or with the leader's own when it is
+    // undefined.
+    const stop = (name, code) => {
+      if (stopping) return;
+      stopping = true;
+      result = code;
+      clearTimeout(deadline);
+      group(name);
+      killAt = Date.now() + GRACE_MS;
+      clearTimeout(look);
+      watch();
+    };
+    const passOn = (name) => stop(name, undefined);
+
+    child.on('error', (error) => {
+      const missing = error.code === 'ENOENT';
+      process.stderr.write(`obk: run could not start ${command[0]}: ${missing ? 'there is no such command' : error.code ?? error.message}.\n`);
+      finish(missing ? NOT_FOUND : CANNOT_RUN);
+    });
+    if (child.pid === undefined) return;
+    for (const name of PASSED_ON) process.on(name, passOn);
+
+    child.on('exit', (code, name) => {
+      exitCode = code ?? 128 + constants.signals[name];
+      clearTimeout(look);
+      watch();
+    });
+
+    deadline = setTimeout(() => {
+      process.stderr.write(`obk: run stopped ${command.join(' ')}: it ran past its time limit of ${seconds} seconds, and its whole process group was stopped.\n`);
+      stop('SIGTERM', TIMED_OUT);
+    }, seconds * 1000);
+  });
+}

package/src/skills.js

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

package/src/sources.js

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

package/src/temp.js

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