@assuredloop/orca-bot-kit 0.27.0 → 0.28.0

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0034). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0046). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -106,6 +106,15 @@ export function orcaTrouble() {
   if (asked.error) return `could not run Orca at ${orcaCli()}: ${asked.error.message}. ${where}`;
 
   const answer = parse(asked.stdout);
+  // A CLI that dies with no answer has not reached the app at all: it can fail
+  // on its own, as on a current folder macOS will not let it read, while Orca
+  // runs (#556). So what it said is passed on, and nobody is sent to start Orca.
+  if (answer === undefined && asked.status !== 0) {
+    const exit = asked.status ?? `signal ${asked.signal}`;
+    return `the Orca CLI at ${orcaCli()} failed before it answered status (exit ${exit}; `
+      + `stdout ${said(asked.stdout)}; stderr ${said(asked.stderr)}). `
+      + 'Fix what it says and run the command again, or point OBK_ORCA at another Orca CLI.';
+  }
   // Orca knowing what is wrong beats the kit guessing, so its own words go
   // first when it gave any.
   if (answer !== null && typeof answer === 'object' && answer.ok !== true && answer.error?.message) {
@@ -319,7 +328,7 @@ const CLIENT_KILL_MS = 3000;
  *
  * Orca's window re-reads only when its runtime says the projects changed, and
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
- * changes does, and Orca's CLI does not offer it (ADR 0034). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0046). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -330,7 +339,7 @@ export const tellWindow = (projectId) => askRuntime('project.update', { projectI
  * runtime's answer, or undefined when there is none to be had.
  *
  * It goes through Orca's own runtime client out of the installed app, run by
- * Orca's binary the way its `bin/orca` runs its CLI (ADR 0034). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0046). None of that is
  * Orca's published interface, so anything that goes wrong is a quiet
  * undefined: it never throws and is never tried twice.
  */
@@ -367,7 +376,7 @@ const RELOAD_KILL_MS = 5000;
 
 /**
  * Have Orca's window force-reload itself, after a project was removed: true
- * only when it did (#343, ADR 0034).
+ * only when it did (#343, ADR 0046).
  *
  * The window keeps a removed project in its sidebar until it is rebuilt, and
  * `tellWindow` only relabels the row "Unknown" (stablyai/orca#23224; once a
@@ -524,7 +533,7 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Whether the rows of a rendered screen hold a question of the harness's own.
  *
  * Every one seen is a numbered list of choices with the harness's pointer on
- * one (tech notes, section 1; ADR 0034). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0046). The same pointer starts the harness's
  * input line and its echo of the user's past turns, and the input line is the
  * lowest of them whenever it is on screen, so the lowest pointer row is asked
  * about: a question counts while it stands in the input line's place, or
@@ -730,7 +739,7 @@ export const psCli = () => process.env.OBK_PS || '/bin/ps';
  *
  * `ps` is asked first. Where it cannot read the tab, as inside Codex's
  * sandbox, where it does not start at all, Orca's runtime is asked instead
- * (#298, ADR 0034). `readMs` bounds each call: a number, or a function that
+ * (#298, ADR 0046). `readMs` bounds each call: a number, or a function that
  * says what is left of a wait, asked before each one (#498). A `ps` that runs
  * out of it ends the look, `late`, with no runtime asked after it.
  */
@@ -770,7 +779,7 @@ function frontByOrca(handle, readMs) {
  * Who holds the terminal of the pane `ptyId`, as `ps` says it.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0034).
+ * gives that pid's terminal's foreground process group (ADR 0046).
  * On macOS the pane is `login` with the shell as its child, so the shell is in
  * front when the group is the pane's own or that of a child of a `login` pane.
  * `diagnostics memory` is a diagnostics command and may change, so everything

package/src/permissions.js

@@ -6,7 +6,7 @@
 // body beside the bots folder, commit. A matching allow rule is settled before
 // that check (Claude Code's permissions docs), so the kit gives every bot a
 // default set, spelled with its real CLI and bots folder, with nobody asked
-// (#527, ADR 0036). A rule beyond it is the user's yes, which
+// (#527, ADR 0050). A rule beyond it is the user's yes, which
 // `permission allow` keeps in bot.yaml's `allow`. The kit's code writes what
 // `allow` holds into `.claude/settings.json` in the bot folder, beside its hook
 // (ADR 0022). A model editing the file by hand may get the format wrong; code
@@ -24,7 +24,7 @@ import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync
 import path from 'node:path';
 
 import { allowRules, leadsOutside } from './bot.js';
-import { DEFAULT_COMMANDS, NO_LONGER_DEFAULT } from './commands.js';
+import { DEFAULT_COMMANDS, NO_LONGER_DEFAULT, REMOVED } from './commands.js';
 import { readSettings } from './hooks.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 
@@ -36,11 +36,10 @@ const CODEX_RULES = '.codex/rules';
 const CODEX_FILE = `${CODEX_RULES}/obk.rules`;
 
 /**
- * The rules every bot is given (ADR 0036): each of the kit's default commands,
- * and none kept back for the user's yes (ADR 0041), narrowed to this bots folder and
+ * The rules every bot is given (ADR 0050): each of the kit's default commands,
+ * and none kept back for the user's yes (ADR 0051), narrowed to this bots folder and
  * spelled as the kit prints them, which is what a bot runs; reading a long
- * message; committing; and the check Orca's mail notice tells a session to
- * run. `//` is Claude's form for an absolute path.
+ * message; and committing. `//` is Claude's form for an absolute path.
  */
 export function defaultRules(bots, cli = ownCli()) {
   const kit = shellWord(cli);
@@ -50,19 +49,27 @@ export function defaultRules(bots, cli = ownCli()) {
     `Read(/${bots}.messages/**)`,
     'Bash(git add:*)',
     'Bash(git commit:*)',
-    'Bash(orca orchestration check --run:*)',
   ];
 }
 
 /**
- * The rules of the commands that were defaults once and are kept back now
- * (#548), spelled as `defaultRules` spelled them, that the bot's `allow`
- * holds. The kit cannot tell its own old entry from a user's yes to the same
- * rule, so it names them and leaves them (ADR 0041).
+ * 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).
+ */
+const ORCA_CHECK = 'Bash(orca orchestration check --run:*)';
+
+/**
+ * The rules that were defaults once and are not now, that the bot's `allow`
+ * holds: those of the commands kept back (#548, #615) or gone from the kit (#555),
+ * spelled as `defaultRules` spelled them, and Orca's check (#564). The kit
+ * cannot tell its own old entry from a user's yes to the same rule, so it
+ * names them and leaves them (ADR 0051, ADR 0050).
  */
 export function heldRules(bots, home, bot, cli = ownCli()) {
   const allowed = allowOf(home, bot);
-  return NO_LONGER_DEFAULT.map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+  return [...NO_LONGER_DEFAULT, ...REMOVED].map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+    .concat(ORCA_CHECK)
     .filter((rule) => allowed.includes(rule));
 }
 
@@ -220,9 +227,16 @@ export const runsOnCodex = (bot) => bot.harness === 'codex'
  */
 function missingDefaults(bots, home, bot) {
   const allowed = allowOf(home, bot);
-  return defaultRules(bots)
-    .filter((rule) => runsOnClaude(bot) || codexForm(rule).line !== undefined)
-    .filter((rule) => !allowed.includes(rule));
+  return botDefaults(bots, bot).filter((rule) => !allowed.includes(rule));
+}
+
+/**
+ * The default rules a bot on Claude or Codex is given, in the default order:
+ * what `bot create` writes into a new bot's bot.yaml (#595).
+ */
+export function botDefaults(bots, bot) {
+  if (!runsOnClaude(bot) && !runsOnCodex(bot)) return [];
+  return defaultRules(bots).filter((rule) => runsOnClaude(bot) || codexForm(rule).line !== undefined);
 }
 
 /**
@@ -270,7 +284,7 @@ export function refuseNoCodexForm(bot, rules) {
 }
 
 /**
- * Add the default rules the bot is not allowed yet to its `allow` (ADR 0036),
+ * Add the default rules the bot is not allowed yet to its `allow` (ADR 0050),
  * then write what it is allowed into the files of the harnesses it runs on:
  * one entry per file, Claude's first, each with `defaults`, the rules this run
  * added, and `held`, the rules of commands no longer in the set that the bot

package/src/pi.js

@@ -0,0 +1,55 @@
+// Whether Pi is ready to start a session: it runs, it can use a model, and it
+// can use the one the session names (#578).
+//
+// The kit never handles Pi's credentials: the user signs in to Pi on their own,
+// and the kit only asks Pi what it can use. `pi auth check` is not asked, since
+// it does not know a provider an extension of Pi's brings, such as Cursor's;
+// `pi --list-models` lists the models Pi can use, those included (tech notes,
+// section 6).
+
+import { spawnSync } from 'node:child_process';
+
+/** How long each question to Pi is given. Each took about 0.3 s on Pi 1.1.0. */
+const ASK_MS = 30_000;
+
+/** Pi's thinking levels, which a model name may carry after a colon. */
+const THINKING = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+/**
+ * Why Pi cannot start these sessions, or undefined when it can. `models` are
+ * the models they name; a session that names none takes Pi's own default.
+ */
+export function piTrouble(models) {
+  const version = ask(['--version']);
+  if (version.error !== undefined || version.status !== 0) {
+    const why = version.error?.code === 'ENOENT' ? 'there is no pi on PATH' : (version.error?.message ?? ((version.stderr ?? '').trim() || `it exited with ${version.status}`));
+    return `Pi does not run here (${why}), so no Pi session was started. Install Pi, then run this again.`;
+  }
+
+  const any = ask(['--list-models']);
+  if (any.error !== undefined || any.status !== 0 || /^No models available\b/m.test(any.stdout ?? '')) {
+    return 'Pi has no model it can use: it is signed in to no provider. Sign in to Pi yourself (start pi and use /login, or set a provider\'s API key), then run this again. The kit never handles Pi\'s credentials.';
+  }
+
+  for (const model of new Set(models)) {
+    const found = ask(['--list-models', withoutThinking(model)]);
+    if (found.error !== undefined || found.status !== 0) {
+      const why = found.error?.message ?? ((found.stderr ?? '').trim() || `it exited with ${found.status ?? found.signal}`);
+      return `Pi cannot say whether it can use the model ${model}: pi --list-models ${withoutThinking(model)} failed (${why}), so no Pi session was started. Run that command yourself to see why, then run this again.`;
+    }
+    // Pi says it has no model at all before it searches, so the answer may be
+    // that one too, when a provider dropped out since the question above.
+    if (/^No models (matching|available)\b/m.test(found.stdout ?? '')) {
+      return `Pi cannot use the model ${model}: pi --list-models lists none matching it. Sign in to its provider in Pi yourself, or give the session a model Pi lists.`;
+    }
+  }
+  return undefined;
+}
+
+/** The model without a trailing `:<thinking level>`, which `--list-models` does not match. */
+function withoutThinking(model) {
+  const at = model.lastIndexOf(':');
+  return at > 0 && THINKING.includes(model.slice(at + 1)) ? model.slice(0, at) : model;
+}
+
+const ask = (args) => spawnSync('pi', args, { encoding: 'utf8', timeout: ASK_MS });

package/src/rules.js

@@ -20,7 +20,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 
-import { botDir, botNames, displayName, readBot } from './bot.js';
+import { botDir, botNames, displayName, readBot, refuseOutside } from './bot.js';
 import { ownCli, shellWord } from './launch.js';
 
 /** The kit's own units, inside the installed package. */
@@ -85,6 +85,7 @@ export function buildAgents(bots, home, bot) {
 
   let state;
   try {
+    refuseOutside(home, file);
     state = writeBlock(file, built.body);
   } catch (error) {
     return { bot: bot.name, file, state: 'conflict', trouble: error.message };
@@ -416,7 +417,9 @@ export function agentsTrouble(bots, home, bot) {
 /** Whether two paths are the same file in the end. One that leads nowhere is not. */
 function sameFile(one, other) {
   try {
-    return realpathSync(one) === realpathSync(other);
+    // Native, as in leadsOutside: the JS one takes `hop/..` away before `hop`
+    // is followed.
+    return realpathSync.native(one) === realpathSync.native(other);
   } catch {
     return false;
   }

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