@assuredloop/orca-bot-kit 0.26.1 → 0.28.0

package/src/bot.js

@@ -7,13 +7,14 @@
 // The files are the user's. A command that cannot do what was asked refuses and
 // writes nothing, rather than leave a bot half made or a bot.yaml half edited.
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { isSeq, parse, parseDocument, stringify } from 'yaml';
 
-import { DEFAULT_APPROVAL, HARNESSES, harnessOf, sessionTrouble } from './launch.js';
+import { takeBotTurn } from './book.js';
+import { defaultApproval, HARNESSES, harnessOf, ownCli, refuseApprovalArgs, sessionTrouble, set, shellWord, workDirOf } from './launch.js';
 
 /** Where the bots live inside the user's bots folder. */
 export const botsDir = (bots) => path.join(bots, 'bots');
@@ -75,10 +76,21 @@ export function leadsOutside(home, target) {
   }
   // Links that never settle lead nowhere the kit can vouch for.
   if (real === undefined) return `${target}, through links that never settle`;
-  const root = realpathSync(home);
+  const root = realpathSync.native(home);
   return real === root || real.startsWith(root + path.sep) ? undefined : real;
 }
 
+/**
+ * Refuse to write a bot's own file — its `bot.yaml`, its `AGENTS.md` — through a
+ * link that takes it out of the bot folder at `home`: what is there is the
+ * user's own file, not the bot's (#569).
+ */
+export function refuseOutside(home, file) {
+  const real = leadsOutside(home, file);
+  if (real === undefined) return;
+  throw new Error(`${file} leads outside the bot folder, to ${real}, through a link, and the kit writes a bot's files only inside the bot folder, so nothing was written. Replace the link with a file of the bot's own, then run the command again.`);
+}
+
 /** How many links deep a path is followed before it is taken to lead nowhere. */
 const HOPS = 40;
 
@@ -99,10 +111,16 @@ function whereItLeads(target) {
       at = path.dirname(at);
     }
     try {
-      return path.join(realpathSync(at), ...rest);
+      // The native call, which asks the file system: the JS one runs
+      // path.resolve first, which takes `hop/..` away before `hop` is followed.
+      return path.join(realpathSync.native(at), ...rest);
     } catch (error) {
       if (!lstatSync(at).isSymbolicLink()) throw error;
-      next = path.join(path.resolve(path.dirname(at), readlinkSync(at)), ...rest);
+      // Joined as text, not with path.join or path.resolve: they take `hop/..`
+      // away before `hop` is followed, and the file system follows it first
+      // (#569 review).
+      const text = readlinkSync(at);
+      next = [path.isAbsolute(text) ? text : `${path.dirname(at)}${path.sep}${text}`, ...rest].join(path.sep);
     }
   }
   return undefined;
@@ -162,7 +180,7 @@ export function readBot(home, name = path.basename(home)) {
     // The roles its temporary sessions can be made in, judged by tempRoles.
     ...(bot.temp_roles === undefined ? {} : { temp_roles: bot.temp_roles }),
     // The widest approval its temporary sessions may be made at, the user's yes
-    // kept by `permission approval --temps` (ADR 0041).
+    // kept by `permission approval --temps` (ADR 0051).
     ...(bot.temp_approval === undefined ? {} : { temp_approval: bot.temp_approval }),
     // A paused bot is one `obk up` leaves closed; its sessions keep their book.
     ...(bot.paused === true ? { paused: true } : {}),
@@ -182,9 +200,11 @@ export function readBot(home, name = path.basename(home)) {
  *
  * The bot's own files, and no more: its `AGENTS.md` is built from this
  * `bot.yaml` and the rule units, which is the rules build's job and is reported
- * as one (PRD 6.6).
+ * as one (PRD 6.6). `allow` is the kit's default rules for it, written in the
+ * same first write, so that no later read and write of the file can lose a
+ * change another command makes at the same time (#595).
  */
-export function createBot(bots, { name, harness, charter }) {
+export function createBot(bots, { name, harness, charter, allow = [] }) {
   if (!NAME.test(name)) {
     throw new Error(`${name} cannot be a bot's name: a name is lower-case letters, digits and single hyphens, such as api-bot.`);
   }
@@ -201,7 +221,7 @@ export function createBot(bots, { name, harness, charter }) {
 
   const text = charter?.trim() ? `${charter.trim()}\n` : PLACEHOLDER_CHARTER(name);
   const files = [
-    [BOT_YAML, botYaml(name, harness, text)],
+    [BOT_YAML, botYaml(name, harness, text, allow)],
     ['.gitignore', BOT_GITIGNORE],
   ];
 
@@ -232,35 +252,39 @@ export function addSession(bots, bot, settings) {
   if (!existsSync(file)) {
     throw new Error(`there is no bot called ${bot} in ${bots}: ${file} is not there. Create it with obk bot create.`);
   }
+  refuseOutside(home, file);
 
-  const known = readBot(home, bot);
-  if (known.sessions.some((session) => session.name === settings.name)) {
-    throw new Error(`${bot} already has a session called ${settings.name}, and session add never writes over one.`);
-  }
-
-  const session = ordered({ ...settings, approval: settings.approval ?? DEFAULT_APPROVAL });
-  const trouble = sessionTrouble(session, harnessOf(session, known.harness), home);
-  if (trouble !== undefined) throw new Error(trouble);
+  return withBotTurn(home, () => {
+    const known = readBot(home, bot);
+    if (known.sessions.some((session) => session.name === settings.name)) {
+      throw new Error(`${bot} already has a session called ${settings.name}, and session add never writes over one.`);
+    }
 
-  const source = readFileSync(file, 'utf8');
-  const doc = parseDocument(source);
-  const sessions = doc.get('sessions', true);
-  if (sessions?.items === undefined) {
-    // No list to add to: an empty `sessions:`, or no sessions key at all.
-    doc.set('sessions', [session]);
-  } else {
-    // A list written inline is written out as a block list from here on, which
-    // is the one shape a session with a prompt in it reads well in.
-    sessions.flow = false;
-    doc.addIn(['sessions'], session);
-  }
+    // Pi has one level, and the session says so in bot.yaml (#547).
+    const session = ordered({ ...settings, approval: settings.approval ?? defaultApproval(harnessOf(settings, known.harness)) });
+    const trouble = sessionTrouble(session, harnessOf(session, known.harness), home);
+    if (trouble !== undefined) throw new Error(trouble);
+
+    const source = readFileSync(file, 'utf8');
+    const doc = parseDocument(source);
+    const sessions = doc.get('sessions', true);
+    if (sessions?.items === undefined) {
+      // No list to add to: an empty `sessions:`, or no sessions key at all.
+      doc.set('sessions', [session]);
+    } else {
+      // A list written inline is written out as a block list from here on, which
+      // is the one shape a session with a prompt in it reads well in.
+      sessions.flow = false;
+      doc.addIn(['sessions'], session);
+    }
 
-  const text = doc.toString(YAML_OUT);
-  if (!changesExactly(source, text, (was) => ({ ...was, sessions: [...(was.sessions ?? []), session] }))) {
-    throw new Error(`${file} cannot have a session added to it without changing something else in it, so nothing was written. Add ${settings.name} to its sessions list by hand.`);
-  }
-  writeFileSync(file, text);
-  return { bot, home, session };
+    const text = doc.toString(YAML_OUT);
+    if (!changesExactly(source, text, (was) => ({ ...was, sessions: [...(was.sessions ?? []), session] }))) {
+      throw new Error(`${file} cannot have a session added to it without changing something else in it, so nothing was written. Add ${settings.name} to its sessions list by hand.`);
+    }
+    writeWhole(file, text);
+    return { bot, home, session };
+  });
 }
 
 /**
@@ -274,8 +298,10 @@ export function changeBot(bots, bot, { charter }) {
   if (charter.trim() === '') throw new Error('--charter is empty, and a bot with no charter has no boundary to act inside. Give it one.');
 
   const text = `${charter.trim()}\n`;
-  editBot(bots, bot, `give ${bot} a new charter`, (doc) => doc.set('charter', text), (was) => ({ ...was, charter: text }));
-  return { bot, home: botDir(bots, bot), charter: text };
+  return withBotTurn(existingBot(bots, bot), () => {
+    editBot(bots, bot, `give ${bot} a new charter`, (doc) => doc.set('charter', text), (was) => ({ ...was, charter: text }));
+    return { bot, home: botDir(bots, bot), charter: text };
+  });
 }
 
 /**
@@ -306,13 +332,15 @@ export function allowedNow(bots, bot, rules, flag = '--rule') {
  * false it only refuses what the edit would refuse, and writes nothing.
  */
 export function allowRules(bots, bot, rules, { write = true } = {}) {
-  const { home, was } = allowedNow(bots, bot, rules);
-  const added = [...new Set(rules)].filter((rule) => !was.includes(rule));
-  const allow = [...was, ...added];
-  if (added.length > 0) {
-    editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
-  }
-  return { bot, home, allow, added };
+  return withBotTurn(existingBot(bots, bot), () => {
+    const { home, was } = allowedNow(bots, bot, rules);
+    const added = [...new Set(rules)].filter((rule) => !was.includes(rule));
+    const allow = [...was, ...added];
+    if (added.length > 0) {
+      editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
+    }
+    return { bot, home, allow, added };
+  });
 }
 
 /**
@@ -323,21 +351,29 @@ export function allowRules(bots, bot, rules, { write = true } = {}) {
  * false it only refuses what the edit would refuse, and writes nothing.
  */
 export function disallowRules(bots, bot, rules, { write = true } = {}) {
-  const { home, was } = allowedNow(bots, bot, rules);
-  const disallowed = [...new Set(rules)];
-  const allow = was.filter((rule) => !disallowed.includes(rule));
-  editBot(bots, bot, `take back ${disallowed.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
-  return { bot, home, allow, disallowed };
+  return withBotTurn(existingBot(bots, bot), () => {
+    const { home, was } = allowedNow(bots, bot, rules);
+    const disallowed = [...new Set(rules)];
+    const allow = was.filter((rule) => !disallowed.includes(rule));
+    editBot(bots, bot, `take back ${disallowed.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
+    return { bot, home, allow, disallowed };
+  });
 }
 
 /**
  * Change the settings of the session `name` of the bot `bot`. Returns
- * { bot, home, session } — the session as it now reads.
+ * { bot, home, session, moved } — the session as it now reads, and, when it
+ * moved to another harness, `{ from, to, defaults }`.
  *
  * A setting given replaces the one there, and one given empty is taken out,
  * which leaves it to the harness's own default. A start prompt is written one
  * way or the other, so giving one takes the other away. The result is held to
  * the rules `session add` holds a new session to.
+ *
+ * A move to another harness takes out the model, effort and context the
+ * session had, which belong to the harness it is leaving, unless the same call
+ * gives them (#565). The book is not touched: the session's conversation is
+ * set aside when it next starts on the new harness.
  */
 export function changeSession(bots, bot, name, settings) {
   const changes = { ...settings };
@@ -347,26 +383,69 @@ export function changeSession(bots, bot, name, settings) {
   if (changes.prompt !== undefined && changes.prompt_file === undefined) changes.prompt_file = '';
   if (changes.prompt_file !== undefined && changes.prompt === undefined) changes.prompt = '';
 
-  const { home, known, index } = sessionAt(bots, bot, name);
-  const was = known.sessions[index];
-  // Every key the entry had stays, a pause mark or one of the user's own among
-  // them; only the settings given change.
-  const session = Object.fromEntries(Object.entries({ ...was, ...changes })
-    .filter(([, value]) => value !== '' && !(Array.isArray(value) && value.every((one) => one === ''))));
-  const trouble = sessionTrouble(session, harnessOf(session, known.harness), home);
-  if (trouble !== undefined) throw new Error(trouble);
+  return withBotTurn(existingBot(bots, bot), () => {
+    const { home, known, index } = sessionAt(bots, bot, name);
+    const was = known.sessions[index];
+    const from = harnessOf(was, known.harness);
+    let moved;
+    if (changes.harness !== undefined && changes.harness !== from) {
+      const defaults = ['model', 'effort', 'context'].filter((key) => changes[key] === undefined && ![undefined, null, ''].includes(was[key]));
+      for (const key of defaults) changes[key] = '';
+      moved = { from, to: changes.harness, defaults };
+    }
+    // Every key the entry had stays, a pause mark or one of the user's own among
+    // them; only the settings given change.
+    const session = Object.fromEntries(Object.entries({ ...was, ...changes })
+      .filter(([, value]) => value !== '' && !(Array.isArray(value) && value.every((one) => one === ''))));
+    const trouble = sessionTrouble(session, harnessOf(session, known.harness), home);
+    if (trouble !== undefined) throw new Error(trouble);
+    // A session with no approval runs at its harness's default, auto on claude
+    // and codex, and dangerously-skip on Pi: a move to Pi would widen it with
+    // nobody asked (ADR 0051, #589).
+    if (moved?.to === 'pi' && !set(session.approval) && defaultApproval(from) !== 'dangerously-skip') {
+      throw new Error(`${bot}'s session ${name} has no approval in bot.yaml, so on ${from} it runs at ${defaultApproval(from)}. Every Pi session runs as dangerously-skip, and session change widens no approval. After the user's yes, Bot Father sets it with ${shellWord(ownCli())} permission approval --bots ${shellWord(bots)} --bot ${bot} --session ${name} --approval dangerously-skip; then the session can move to Pi. Nothing was changed.`);
+    }
+    // Judged on the session as it is written, which is the whole session, so a
+    // change another command made in between cannot be combined with this one.
+    refuseCodexOutside(bot, session, was, known.harness, home, 'session change');
+    // The same for an extra argument that sets approval on the session's
+    // harness: the caller's check read bot.yaml before this turn (#589).
+    if (changes.harness !== undefined || changes.extra_args !== undefined) {
+      refuseApprovalArgs(harnessOf(session, known.harness), session.extra_args);
+    }
 
-  editSession(bots, bot, index, session, `change ${bot}'s session ${name}`);
-  return { bot, home, session };
+    editSession(bots, bot, index, session, `change ${bot}'s session ${name}`);
+    return { bot, home, session, ...(moved === undefined ? {} : { moved }) };
+  });
+}
+
+/**
+ * Refuse a session that would run on Codex with a work dir outside its bot
+ * home (ADR 0045): Codex is launched with `--add-dir` for it, which lets the
+ * session write there, and `session add` and `session change` were in every
+ * bot's default set (#585), and a bot may still hold their rules (#615). Outside is by the spelling, which the launch line
+ * names, or by where links really lead. `was` is the session before the
+ * change: one already on Codex with the same work dir widens nothing.
+ */
+export function refuseCodexOutside(bot, session, was, botHarness, home, command) {
+  if (harnessOf(session, botHarness) !== 'codex') return;
+  const workDir = workDirOf(session, home);
+  if (workDir === undefined) return;
+  const spelledIn = workDir === home || workDir.startsWith(home + path.sep);
+  if (spelledIn && leadsOutside(home, workDir) === undefined) return;
+  if (was !== undefined && harnessOf(was, botHarness) === 'codex' && workDirOf(was, home) === workDir) return;
+  throw new Error(`${command} would give ${bot}/${session.name}, a Codex session, the work dir ${workDir}, which is outside ${bot}'s folder, ${home}. Codex would then be allowed to write that folder. A Codex session's work dir stays in its bot folder, such as work/${session.name}. Nothing was changed.`);
 }
 
 /**
  * Record the widest approval the bot's temporary sessions may be made at,
- * `level`, as `temp_approval` (ADR 0041). Returns { bot, home, level }.
+ * `level`, as `temp_approval` (ADR 0051). Returns { bot, home, level }.
  */
 export function setTempApproval(bots, bot, level) {
-  editBot(bots, bot, `let ${bot}'s temporary sessions be made at ${level}`, (doc) => doc.set('temp_approval', level), (was) => ({ ...was, temp_approval: level }));
-  return { bot, home: botDir(bots, bot), level };
+  return withBotTurn(existingBot(bots, bot), () => {
+    editBot(bots, bot, `let ${bot}'s temporary sessions be made at ${level}`, (doc) => doc.set('temp_approval', level), (was) => ({ ...was, temp_approval: level }));
+    return { bot, home: botDir(bots, bot), level };
+  });
 }
 
 /**
@@ -379,37 +458,39 @@ export function setTempApproval(bots, bot, level) {
  */
 export function setRoleCaps(bots, bot, caps, { write = true } = {}) {
   const home = existingBot(bots, bot);
-  const roles = readBot(home, bot).temp_roles;
-  const file = path.join(home, BOT_YAML);
-  for (const [role] of caps) {
-    if (roles === null || typeof roles !== 'object' || Array.isArray(roles) || !Object.hasOwn(roles, role)) {
-      const has = roles !== null && typeof roles === 'object' && !Array.isArray(roles) ? Object.keys(roles) : [];
-      throw new Error(`${bot} has no temporary-session role called ${role} in ${file}${has.length === 0 ? ', and no temp_roles at all' : `. It has: ${has.join(', ')}`}. Nothing was changed.`);
-    }
-  }
-  const capped = (written, cap) => {
-    const { cap: was, ...rest } = Array.isArray(written) ? { options: written } : written;
-    return cap === undefined ? rest : { ...rest, cap };
-  };
-  editBot(bots, bot, `set the caps of ${caps.map(([role]) => role).join(', ')}`, (doc) => {
-    for (const [role, cap] of caps) {
-      const node = doc.getIn(['temp_roles', role], true);
-      if (isSeq(node)) {
-        doc.setIn(['temp_roles', role], doc.createNode(capped(node.toJSON(), cap)));
-      } else if (cap === undefined) {
-        doc.deleteIn(['temp_roles', role, 'cap']);
-      } else {
-        doc.setIn(['temp_roles', role, 'cap'], cap);
+  return withBotTurn(home, () => {
+    const roles = readBot(home, bot).temp_roles;
+    const file = path.join(home, BOT_YAML);
+    for (const [role] of caps) {
+      if (roles === null || typeof roles !== 'object' || Array.isArray(roles) || !Object.hasOwn(roles, role)) {
+        const has = roles !== null && typeof roles === 'object' && !Array.isArray(roles) ? Object.keys(roles) : [];
+        throw new Error(`${bot} has no temporary-session role called ${role} in ${file}${has.length === 0 ? ', and no temp_roles at all' : `. It has: ${has.join(', ')}`}. Nothing was changed.`);
       }
     }
-  }, (was) => ({
-    ...was,
-    temp_roles: Object.fromEntries(Object.entries(was.temp_roles).map(([role, written]) => {
-      const asked = caps.findLast(([one]) => one === role);
-      return [role, asked === undefined ? written : capped(written, asked[1])];
-    })),
-  }), write);
-  return { bot, home, caps };
+    const capped = (written, cap) => {
+      const { cap: was, ...rest } = Array.isArray(written) ? { options: written } : written;
+      return cap === undefined ? rest : { ...rest, cap };
+    };
+    editBot(bots, bot, `set the caps of ${caps.map(([role]) => role).join(', ')}`, (doc) => {
+      for (const [role, cap] of caps) {
+        const node = doc.getIn(['temp_roles', role], true);
+        if (isSeq(node)) {
+          doc.setIn(['temp_roles', role], doc.createNode(capped(node.toJSON(), cap)));
+        } else if (cap === undefined) {
+          doc.deleteIn(['temp_roles', role, 'cap']);
+        } else {
+          doc.setIn(['temp_roles', role, 'cap'], cap);
+        }
+      }
+    }, (was) => ({
+      ...was,
+      temp_roles: Object.fromEntries(Object.entries(was.temp_roles).map(([role, written]) => {
+        const asked = caps.findLast(([one]) => one === role);
+        return [role, asked === undefined ? written : capped(written, asked[1])];
+      })),
+    }), write);
+    return { bot, home, caps };
+  });
 }
 
 /**
@@ -417,33 +498,37 @@ export function setRoleCaps(bots, bot, caps, { write = true } = {}) {
  * the file changed. A paused bot or session is one `obk up` leaves closed.
  */
 export function markPaused(bots, bot, name, paused) {
-  if (name === undefined) {
-    const known = readBot(botDir(bots, bot), bot);
-    if ((known.paused === true) === paused) return false;
-    editBot(
-      bots, bot, `${paused ? 'pause' : 'unpause'} ${bot}`,
-      (doc) => (paused ? doc.set('paused', true) : doc.delete('paused')),
-      ({ paused: none, ...was }) => (paused ? { ...was, paused: true } : was),
-    );
-    return true;
-  }
+  return withBotTurn(existingBot(bots, bot), () => {
+    if (name === undefined) {
+      const known = readBot(botDir(bots, bot), bot);
+      if ((known.paused === true) === paused) return false;
+      editBot(
+        bots, bot, `${paused ? 'pause' : 'unpause'} ${bot}`,
+        (doc) => (paused ? doc.set('paused', true) : doc.delete('paused')),
+        ({ paused: none, ...was }) => (paused ? { ...was, paused: true } : was),
+      );
+      return true;
+    }
 
-  const { known, index } = sessionAt(bots, bot, name);
-  const was = known.sessions[index];
-  if ((was.paused === true) === paused) return false;
-  const { paused: none, ...rest } = was;
-  editSession(bots, bot, index, paused ? { ...rest, paused: true } : rest, `${paused ? 'pause' : 'unpause'} ${bot}'s session ${name}`);
-  return true;
+    const { known, index } = sessionAt(bots, bot, name);
+    const was = known.sessions[index];
+    if ((was.paused === true) === paused) return false;
+    const { paused: none, ...rest } = was;
+    editSession(bots, bot, index, paused ? { ...rest, paused: true } : rest, `${paused ? 'pause' : 'unpause'} ${bot}'s session ${name}`);
+    return true;
+  });
 }
 
 /** Take the session `name` off the bot `bot`'s list. */
 export function dropSession(bots, bot, name) {
-  const { index } = sessionAt(bots, bot, name);
-  editBot(
-    bots, bot, `take the session ${name} off ${bot}`,
-    (doc) => doc.deleteIn(['sessions', index]),
-    (was) => ({ ...was, sessions: was.sessions.filter((one, at) => at !== index) }),
-  );
+  withBotTurn(existingBot(bots, bot), () => {
+    const { index } = sessionAt(bots, bot, name);
+    editBot(
+      bots, bot, `take the session ${name} off ${bot}`,
+      (doc) => doc.deleteIn(['sessions', index]),
+      (was) => ({ ...was, sessions: was.sessions.filter((one, at) => at !== index) }),
+    );
+  });
 }
 
 /** Where a session sits in its bot's list, refusing a bot or a session that is not there. */
@@ -484,7 +569,11 @@ function editSession(bots, bot, index, session, what) {
  * `write` is not false.
  */
 function editBot(bots, bot, what, edit, expected, write = true) {
-  const file = path.join(existingBot(bots, bot), BOT_YAML);
+  const home = existingBot(bots, bot);
+  const file = path.join(home, BOT_YAML);
+  // Before the dry run too, so a command that writes elsewhere first is
+  // refused before it writes anything.
+  refuseOutside(home, file);
   const source = readFileSync(file, 'utf8');
   const doc = parseDocument(source);
   edit(doc);
@@ -497,7 +586,45 @@ function editBot(bots, bot, what, edit, expected, write = true) {
     throw refusal;
   }
   if (!changesExactly(source, text, expected)) throw refusal;
-  if (write && text !== source) writeFileSync(file, text);
+  if (write && text !== source) writeWhole(file, text);
+}
+
+/**
+ * Write `text` over the bot.yaml `file` in one step, as the book is written:
+ * to a file of this process's own beside it, then moved over it. Two commands
+ * that write it at once leave one whole text or the other, never the one with
+ * the end of the other after it, which can read as a session neither command
+ * wrote (#585). A link to it is written through, to the file it names, and the
+ * file keeps its mode. A file the user made read-only is refused, as a write in
+ * place would be, though a move over it would go through. Whatever is already
+ * at the new file's name is taken away and the file is made new, never written
+ * through: a link a session left there would take the text out of the bot
+ * folder, and the move would make bot.yaml that link.
+ */
+export function writeWhole(file, text) {
+  const real = realpathSync(file);
+  accessSync(real, constants.W_OK);
+  const half = `${real}.${process.pid}.part`;
+  rmSync(half, { force: true });
+  writeFileSync(half, text, { flag: 'wx', mode: statSync(real).mode & 0o777 });
+  renameSync(half, real);
+}
+
+/**
+ * Run `change`, which reads the bot's bot.yaml and writes it, while this
+ * command holds the bot's turn (#595): the read and the write are then of the
+ * same file, and another command's change cannot fall between them and be
+ * written over. Every kit change of a bot.yaml that is there is made in here;
+ * `bot create` writes its first whole, with no read before. Not taken twice:
+ * the commands that take it call only what does not.
+ */
+export function withBotTurn(home, change) {
+  const turn = takeBotTurn(home);
+  try {
+    return change();
+  } finally {
+    turn.release();
+  }
 }
 
 /** A bot that is there, by its home, or the refusal a caller who named another is owed. */
@@ -537,9 +664,10 @@ export function changesExactly(source, text, expected) {
 }
 
 /** The bot.yaml of a bot nobody has edited yet. */
-function botYaml(name, harness, charter) {
+function botYaml(name, harness, charter, allow) {
   const header = `# ${displayName(name)}. Ask Bot Father for changes rather than editing this file.\n\n`;
-  return header + stringify({ name, harness, charter, rules: [], skills: [], sessions: [] }, YAML_OUT);
+  const bot = { name, harness, charter, rules: [], skills: [], sessions: [] };
+  return header + stringify(allow.length === 0 ? bot : { ...bot, allow }, YAML_OUT);
 }
 
 /**

package/src/clear.js

@@ -105,7 +105,7 @@ const AT_WORK = [/esc to interrupt/i, /^\s*\S\s+\S+…\s+\(\d/];
  * (or null) and the one it holds now.
  */
 export async function clearSession(bots, { bot, session }) {
-  const it = sessionToType(bots, bot, session);
+  const it = sessionToType(bots, bot, session, 'clear');
   const was = readBook(it.home).sessions[session]?.session ?? null;
   const { command, handle, typing } = await enter(it, 'clear');
 
@@ -141,7 +141,7 @@ export async function clearSession(bots, { bot, session }) {
  * command began, and not yet when COMPACT_MS passed without one.
  */
 export async function compactSession(bots, { bot, session }) {
-  const it = sessionToType(bots, bot, session);
+  const it = sessionToType(bots, bot, session, 'compact');
   // What the record holds when /compact is typed is not this compact's: one
   // that ends while the kit waits for the session to be idle is the one
   // before it (review of PR #466). So only what is written after counts.
@@ -168,13 +168,17 @@ export async function compactSession(bots, { bot, session }) {
 /**
  * The session as something to type into, once everything that refuses before
  * Orca is asked to type has been asked: `{ name, home, session, harness, tabId }`.
+ * A `verb`, clear or compact, is refused on Pi until a later slice of #547.
  */
-export function sessionToType(bots, bot, session) {
+export function sessionToType(bots, bot, session, verb) {
   botsNamed(bots, bot);
   const home = realpathSync(botDir(bots, bot));
   const known = readBot(home, bot);
   const [settings] = sessionsOf(known, session);
   const name = `${bot} ${session}`;
+  if (verb !== undefined && harnessOf(settings, known.harness) === 'pi') {
+    throw new Error(`${name} runs on Pi, and obk session ${verb} does not work on a Pi session yet: a later slice of #547 adds it. Nothing was typed.`);
+  }
   const unpause = `${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${bot}`;
   if (known.paused === true) throw new Error(`${bot} is paused, so ${name} is not running and nothing was typed. Bring it back with ${unpause}.`);
   if (settings.paused === true) throw new Error(`${name} is paused, so it is not running and nothing was typed. Bring it back with ${unpause} --session ${session}.`);