@assuredloop/orca-bot-kit 0.3.0 → 0.5.0

package/README.md

@@ -263,12 +263,22 @@ name for a directory in `skills/` inside your bots folder, or anything with a
 `/` in it for a skill directory anywhere on disk. `obk up` links them before it
 opens a tab, and `bot create` gives a new bot what the lists already name.
 
+A bot whose sessions are running gets a changed list without a restart.
+When `skills build` links or takes away a skill, it tells each running
+session of that bot. A Claude Code session gets `/reload-skills` typed into
+its tab: Claude Code's own reload, which a busy session runs when its turn
+ends. Codex has no reload command and takes the change at the start of its
+next turn, so nothing is typed there. The kit prints the new skills'
+`SKILL.md` paths, and says that a restart would make a skill appear if it is
+still missing after that turn. A session the kit could not tell is named,
+with the reason.
+
 What lands in the bot is a symlink, never a copy
 ([ADR 0014](docs/adr/0014-skills-are-linked-never-copied.md)) — into
 `.claude/skills` and `.agents/skills` in the bot home, which is where each
 harness reads a project's skills from. So a kit skill is read where npm
-installed it, editing a skill is what a running session reads without a
-restart, and updating the kit updates every bot at once.
+installed it, a running session reads an edited skill the next time it loads
+it, and updating the kit updates every bot at once.
 
 The kit takes away only what it can prove it put there. It writes down every
 link it makes, in `.obk-skills.yaml` in the bot folder, and when no list names
@@ -404,7 +414,10 @@ same refusals, and `obk up` leaves what is paused closed until `obk unpause`
 brings it back with its conversations. Retiring a session takes it off the bot
 and keeps its conversations in the book under `retired`. Retiring a bot closes
 its tabs, removes its Orca project and moves its folder to `retired/`; it will
-not touch a bot whose Orca project holds a tab your book does not name. Bot
+not touch a bot whose Orca project holds a tab your book does not name. The
+folder moves only once Orca no longer lists the project; if Orca still lists it,
+or its list cannot be read, retire says so and leaves the bot where it is, and
+retiring it again finishes the job. Bot
 Father itself, and its management session `daily`, are never paused or
 retired; its other sessions are like any bot's.
 
@@ -430,10 +443,23 @@ What it looks for:
   go, and a link with nothing at the end of it;
 - **a session the book knows that Orca does not**: its tab was closed, or the
   machine was restarted, and `obk up` brings it back;
+- **a session whose tab is open and whose harness is gone**: only the tab's
+  shell is in front, because the harness quit or crashed. `obk up` leaves an
+  open tab alone, so the finding names the `obk restart … --session` that
+  brings it back; when the book names no conversation for it, restart would
+  refuse, and the finding says to close the tab in Orca and run
+  `obk up … --session`. A tab the kit cannot read is never called down;
 - **leftovers no book owns**: an Orca project inside your bots folder with no
   bot in it, a tab in a bot's project that the book does not name, a start
   prompt written for a session that has gone, a clone of a skills source you no
   longer list, and the conversations the kit found and would not assign;
+- **a session running on something other than its bot asks for**: a model,
+  effort, context or approval level that the harness's own record of the
+  conversation says differs from `bot.yaml`, and a session that started before
+  its bot's `AGENTS.md` last changed, with what brings it up to date. Beside the
+  findings, each running session gets a line saying, for each setting, whether
+  it matches, differs, was not asked for, or cannot be told from the record;
+  cannot be told is never taken for a match;
 - **Orca's own default launch arguments**. Orca adds these to the agents it
   launches, relaunches and resumes, so when they carry a permission bypass every
   session runs in that mode whatever the kit asked for. The kit never sets that

package/SETUP.md

@@ -145,8 +145,9 @@ different answers.
 
 `obk init` tells you which, for every tab it opened:
 
-- *the harness was typed in and came up* — it is running. It may still be asking
-  something of its own; that is the table below.
+- *the harness was typed in and is running. The kit cannot see whether a screen
+  in it is waiting for an answer* — look at it: Orca does not flag every first-run
+  screen, so it may still be asking something of its own. That is the table below.
 - *the harness was typed in and came up, waiting on: …* — running and blocked on
   a question. The table below.
 - *the harness was typed in, and no session came up in the tab* — **the line did

package/package.json

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

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

@@ -273,24 +273,39 @@ again and check a session is running before you call the bot ready.
 ## When the bot is already running
 
 Changing a bot whose sessions are up is the ordinary case rather than the
-awkward one. Both harnesses read a skill through the link and notice a change
-to the skills directory while a session is running, so putting a skill on a
-bot, or taking one off, reaches a live session without restarting it.
-
-Noticing is not the same as confirmed. Check that the session can actually see
-the skill before telling anyone it is there, and check by asking that session
-rather than by looking again at the disk you just wrote: what you wrote is not
-evidence about what another process has loaded. Where it has not appeared, say
-so and say what would make it appear. A restart is the user's to ask for, and
-taking one because it is the quick way ends a conversation they were in the
-middle of.
+awkward one. Putting a skill on a bot or taking one off reaches its running
+sessions without a restart, and `obk skills build` says, session by session,
+how:
+
+- Claude Code: the kit types `/reload-skills` into the session's tab. That is
+  Claude Code's own reload. A busy session queues it and runs it as a command
+  when its turn ends, so it never reaches the model as text.
+- Codex: nothing is typed, because Codex has no reload command. It takes the
+  change at the start of its next turn, not in the middle of the one it is on.
+
+The kit reports a session it could not tell, and why: not up, or on a screen
+waiting for an answer. A session that is not up reads its skills when it
+starts.
+
+Told is not the same as confirmed. Before telling anyone a skill is there,
+check that the session can use it: ask it to load the skill. Do not look
+again at the disk you just wrote, since that says nothing about what another
+process has loaded. Do not ask a Codex session whether the skill is in its
+list: it has answered "none" while its list held the skill. Where a skill has
+not appeared after the next turn, say so. A restart would make it appear, and
+meanwhile the session can read the skill's `SKILL.md` by the path the kit
+printed. A restart is the user's to ask for. Taking one because it is quick
+ends a conversation they were in the middle of.
 
 Instructions are not skills. A session is working from the rules it read when
 it started, so a change to a bot's `AGENTS.md` may not reach one that is
 already up even when a skill change would, and a session's model, effort or
 approval only changes when it is started again (`obk restart`, on the user's
 word, and then read its tabs as above). Say which you changed, and what that
-means for the sessions running now. Where everything needs restarting, remind
+means for the sessions running now. `obk health` names each running session
+still on the older rules or on other settings, and what brings it up to date: on
+Claude Code a `/clear` reads the rules again, and a start does on both harnesses.
+Where everything needs restarting, remind
 them to do it from Bot Father's ops tab.
 
 And tell them. A bot's sessions share its rules and its skills, so a change

package/src/book.js

@@ -25,6 +25,9 @@ const HEADER = `# What Orca calls this bot on this machine, and where each of it
 # and kept, because an address that is a tab dies with the tab. \`address\` is what
 # a Claude session is called, which is what another Claude session writes to.
 #
+# \`rules\` is a stamp of the bot's AGENTS.md as the session last read it, so a
+# change to it after the session started can be told apart.
+#
 # \`retired\` holds what the book knew about each session \`obk retire\` took off
 # the bot, with when, so the conversations it had are still accounted for.
 `;

package/src/cli.js

@@ -18,7 +18,7 @@ import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
 import { checkMail, lookUp, sendMessage } from './message.js';
-import { orcaCli, orcaTrouble } from './orca.js';
+import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -83,7 +83,8 @@ Usage:
                             a bot: close its tabs, remove its Orca project and
                             move its folder to retired/. It will not retire a
                             bot whose Orca project holds a tab your book does
-                            not name.
+                            not name, and moves the folder only once Orca no
+                            longer lists the project.
   obk rules build --bots <path> [--bot <bot>]
                             Build every bot's AGENTS.md from its charter and
                             the rule units it carries, or just the one you
@@ -103,7 +104,10 @@ Usage:
                             skills folder, or any path, and take away a link
                             it made that no list names any more. What you put
                             in a bot's skills directory yourself is left alone
-                            and shown as yours. It does not touch Orca.
+                            and shown as yours. A bot whose links changed has
+                            its running sessions told: Claude Code gets
+                            /reload-skills typed in, and Codex takes the
+                            change at its next turn.
   obk skills fetch --bots <path> [--source <name>]
                             Clone the online sources skills.yaml lists, beside
                             your bots folder and never inside it, each at the
@@ -425,19 +429,19 @@ const commands = {
     const seeded = initBots(bots, values.harness);
     // The typed path was for making the folder and naming it in a refusal; from
     // here on it is the fleet, and the fleet is its real path (#164).
-    const { tabs, rules, skills, paused } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
+    const { tabs, rules, skills, paused, projects } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
     // Setup is the other place the PRD asks for Orca's own launch arguments to
     // be looked at (6.5), and the one where the user is still standing in front
     // of the fleet they are making. Only that one check: a folder init has just
     // made has nothing else to say about itself.
-    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, tabs, paused, found: orcaSettingFindings() };
+    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, tabs, paused, projects, found: orcaSettingFindings() };
     return { answer, lines: tabLines(answer, `Bot Father is up in Orca. Your bots folder: ${seeded.bots}`) };
   },
 
   async up(bots, values) {
     refuseWhenOrcaIsDown();
-    const { tabs, rules, skills, paused } = await bringUp(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused };
+    const { tabs, rules, skills, paused, projects } = await bringUp(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects };
     const up = [...new Set(tabs.map((tab) => tab.bot))];
     const summary = up.length === 0
       ? `Nothing was brought up in Orca. Your bots folder: ${bots}`
@@ -447,11 +451,12 @@ const commands = {
 
   health(bots, values) {
     refuseWhenOrcaIsDown();
-    const found = checkHealth(bots, { bot: values.bot });
+    const { found, sessions } = checkHealth(bots, { bot: values.bot });
     return {
-      answer: { bots, found },
+      answer: { bots, found, sessions },
       lines: [
         ...foundLines(found),
+        ...sessions.map(settingsLine),
         found.length === 0
           ? `Nothing to report: everything the kit keeps is where it should be. Your bots folder: ${bots}`
           : `${found.length} thing${found.length === 1 ? '' : 's'} to look at above. What to do about each is yours to decide. Your bots folder: ${bots}`,
@@ -464,8 +469,8 @@ const commands = {
 
   async restart(bots, values) {
     refuseWhenOrcaIsDown();
-    const { closed, tabs, rules, skills, paused } = await restartSessions(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, closed };
+    const { closed, tabs, rules, skills, paused, projects } = await restartSessions(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects, closed };
     const what = values.session === undefined ? values.bot : `${values.bot} ${values.session}`;
     return {
       answer,
@@ -518,11 +523,25 @@ const commands = {
     }
 
     const retired = await retireBot(bots, { bot: values.bot });
+    if (retired.trouble !== undefined) {
+      return {
+        answer: { bots, ...retired },
+        lines: [
+          ...closedLines(retired.closed),
+          `${'trouble'.padEnd(9)}  Orca project ${retired.project}`,
+          `             ${retired.trouble}`,
+          `Retire it again:  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${retired.bot}`,
+        ],
+        code: 1,
+      };
+    }
     return {
       answer: { bots, ...retired },
       lines: [
         ...closedLines(retired.closed),
-        ...(retired.project === undefined ? [] : [`removed    Orca project ${retired.project}`]),
+        // After every removal, whatever the window was told: Orca's window can
+        // keep a removed project's row even after it re-reads (stablyai/orca#20102).
+        ...(retired.project === undefined ? [] : [`removed    Orca project ${retired.project}`, RELOAD_LINE]),
         `retired    ${retired.bot}: moved to ${path.relative(bots, retired.moved)}, with its book, charter and memory`,
       ],
     };
@@ -938,12 +957,15 @@ function usageLines(usage, bots) {
     lines.push(`${'bot'.padEnd(9)}  ${entry.bot}`);
     for (const session of entry.sessions) {
       lines.push(`${'session'.padEnd(9)}  ${session.name}`);
+      const notCounted = notCountedLine(session.not_counted);
       lines.push(...session.conversations.map(conversationLine));
-      if (session.conversations.length === 0) lines.push('             nothing on record');
+      if (session.conversations.length === 0 && notCounted.length === 0) lines.push('             nothing on record');
+      lines.push(...notCounted);
     }
-    if (entry.unclaimed.length > 0) {
+    if (entry.unclaimed.length > 0 || notCountedLine(entry.unclaimed_not_counted).length > 0) {
       lines.push(`${'unclaimed'.padEnd(9)}  ${entry.bot}: no session of this bot claims these`);
       lines.push(...entry.unclaimed.map(conversationLine));
+      lines.push(...notCountedLine(entry.unclaimed_not_counted));
     }
   }
 
@@ -953,6 +975,19 @@ function usageLines(usage, bots) {
   return lines;
 }
 
+/** What could not be counted, as one line, or no line when everything was. */
+function notCountedLine(gaps) {
+  const said = [
+    [gaps.unreadable_transcripts, 'transcript', 'transcripts', 'unreadable'],
+    [gaps.broken_lines, 'line', 'lines', 'broken'],
+    [gaps.records_without_numbers, 'record', 'records', 'with no usable number'],
+    [gaps.records_without_time, 'record', 'records', 'with no time'],
+  ]
+    .filter(([count]) => count > 0)
+    .map(([count, one, many, why]) => `${count} ${count === 1 ? one : many} ${why}`);
+  return said.length === 0 ? [] : [`             not counted: ${said.join(', ')}`];
+}
+
 /** One conversation: what it is, what it ran as, and what it used. */
 function conversationLine(one) {
   const ran = [...one.models, ...one.efforts].join(' ');
@@ -1084,9 +1119,24 @@ function skillsLines(skills) {
     ...(entry.trouble === undefined ? [] : [`  ${'trouble'.padEnd(9)}  ${entry.trouble}`]),
     ...entry.skills.map((skill) => `  ${(skill.managed ? 'linked' : 'yours').padEnd(9)}  ${skill.name.padEnd(24)}  ${skill.from ?? 'no list names it; the kit leaves it alone'}`),
     ...(entry.removed ?? []).map((name) => `  ${'removed'.padEnd(9)}  ${name.padEnd(24)}  no list names it now`),
+    ...(entry.sessions ?? []).map((one) => toldLine(entry.bot, one)),
   ]);
 }
 
+/** What `skills build` did about one running session of a bot whose skills changed. */
+function toldLine(bot, { session, harness, state, read, blocked, trouble }) {
+  const who = `${bot}/${session}`;
+  const after = harness === 'claude' ? 'Once that is settled, type /reload-skills in its tab.' : 'Its next turn takes the change by itself.';
+  const [word, says] = {
+    reloaded: ['reloaded', '/reload-skills was typed into its tab; a busy session runs it when its turn ends'],
+    'next-turn': ['next turn', `Codex takes the change at the start of its next turn. If a skill is not there then, a restart makes it appear${read?.length > 0 ? `; meanwhile it can read ${read.join(', ')}` : ''}`],
+    'not-up': ['not told', 'not up; it reads its skills when it starts'],
+    blocked: ['not told', `its tab is waiting for an answer (${blocked}), so nothing was typed. ${after}`],
+    unknown: ['not told', `${trouble}. ${after}`],
+  }[state];
+  return `  ${word.padEnd(9)}  ${who.padEnd(24)}  ${says}`;
+}
+
 /**
  * What a check found, two lines each: what kind of trouble it is and the one
  * thing to go and look at, then the sentence about it. The same shape wherever
@@ -1095,7 +1145,26 @@ function skillsLines(skills) {
 const foundLines = (found) =>
   found.flatMap((one) => [`${one.kind.padEnd(9)}  ${one.where}`, `             ${one.says}`]);
 
-function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], found = [] }, summary) {
+/**
+ * What one running session runs on, in a line: each setting's state, with what
+ * was asked for and what the harness recorded, and its rules.
+ */
+function settingsLine({ bot, session, running, settings, rules }) {
+  const each = Object.entries(settings).map(([name, one]) => {
+    const values = [
+      ...(one.configured === undefined ? [] : [`asked ${one.configured}`]),
+      ...(one.observed === undefined ? [] : [`runs ${one.observed}`]),
+    ];
+    return `${name} ${one.state}${values.length === 0 ? '' : ` (${values.join(', ')})`}`;
+  });
+  // A session whose harness the kit cannot see in its tab is not called running.
+  const [word, who] = running === 'yes'
+    ? ['running', `${bot} ${session}`]
+    : ['unsure', `${bot} ${session}  cannot tell whether its harness is running:`];
+  return `${word.padEnd(9)}  ${who}  ${each.join('  ')}  rules ${rules.state}`;
+}
+
+function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], projects = [], found = [] }, summary) {
   const lines = [
     ...created.map((entry) => `created    ${entry}`),
     ...completed.map((entry) => `completed  ${entry}`),
@@ -1115,7 +1184,10 @@ function tabLines({ bots, created, completed, rules, skills, tabs, paused = [],
 
   // Last before the summary, because what a check found is about the setup the
   // run has just left behind rather than about any one thing it did.
-  lines.push(...foundLines(found), summary);
+  lines.push(...foundLines(found));
+  // Hedged, because nothing here can see whether the window was told (#224).
+  if (projects.length > 0) lines.push(RELOAD_LINE);
+  lines.push(summary);
   return lines;
 }
 
@@ -1141,11 +1213,21 @@ function harnessLines(tab, bots) {
       '             the harness was typed in, and no session came up in the tab.',
       `             Look at it:  ${lookAt(tab.terminal)}`,
       ...ANSWER_IT,
+      ...promptLines(tab),
     ];
   }
 
+  // Orca naming no reason does not mean nothing is on screen: on 1.4.209 it
+  // names none for Codex's trust and hooks screens, nor for Claude Code's trust
+  // list (tech notes, section 1, #288). So the kit says what it cannot see.
   const lines = tab.blockedReason === undefined
-    ? [...how, '             the harness was typed in and came up.']
+    ? [
+      ...how,
+      '             the harness was typed in and is running. The kit cannot see whether a screen',
+      '             in it is waiting for an answer.',
+      `             Look at it:  ${lookAt(tab.terminal)}`,
+      ...ANSWER_IT,
+    ]
     : [
       ...how,
       `             the harness was typed in and came up, waiting on: ${tab.blockedReason}`,
@@ -1153,14 +1235,21 @@ function harnessLines(tab, bots) {
       ...ANSWER_IT,
     ];
 
-  if (tab.promptSent === true) lines.push('             the start prompt was typed in.');
-  if (tab.promptSent === false) {
-    lines.push('             the start prompt was not typed in: the tab was not ready for it.');
-  }
+  lines.push(...promptLines(tab));
   if (tab.unclaimed !== undefined) lines.push(...unclaimedLines(tab, bots));
   return lines;
 }
 
+/**
+ * Whether the session got its start prompt, as its own record has it (#274):
+ * received, or not confirmed yet. Nothing for a session that was told nothing.
+ */
+function promptLines(tab) {
+  if (tab.promptReceived === true) return ['             the start prompt was received: the session\'s own record holds it.'];
+  if (tab.promptReceived === false) return ['             the start prompt is not confirmed: the session\'s own record does not hold it yet.'];
+  return [];
+}
+
 try {
   process.exitCode = await run(process.argv.slice(2));
 } catch (error) {

package/src/conversations.js

@@ -32,12 +32,17 @@ const codexDir = () => path.join(homedir(), '.codex', 'sessions');
  * then that it does not know, which is the honest one.
  */
 export function conversationsIn(harness, home, since) {
-  return transcriptsIn(harness, home, since).map((one) => ({ id: one.id, at: one.at }));
+  // A subagent's conversation ran in the folder too, but no session had it: the
+  // harness says it is a helper's, so it is never offered to one to claim.
+  return transcriptsIn(harness, home, since)
+    .filter((one) => !one.subagent)
+    .map((one) => ({ id: one.id, at: one.at }));
 }
 
 /**
  * The same conversations, each with the file the harness keeps it in, for a
- * caller that has to read what is inside one rather than only know it is there.
+ * caller that has to read what is inside one rather than only know it is there,
+ * and whether the harness marks it as a subagent's.
  */
 export function transcriptsIn(harness, home, since) {
   const from = since === undefined ? 0 : Date.parse(since);
@@ -45,7 +50,47 @@ export function transcriptsIn(harness, home, since) {
   return found
     .filter((one) => Number.isNaN(from) || one.at >= from)
     .sort((left, right) => left.at - right.at)
-    .map((one) => ({ id: one.id, at: new Date(one.at).toISOString(), file: one.file }));
+    .map((one) => ({ id: one.id, at: new Date(one.at).toISOString(), file: one.file, subagent: one.subagent === true }));
+}
+
+/**
+ * Whether a conversation's own record holds `text` as a turn of the user's:
+ * what the harness itself wrote down as said to it, not a screen that was up.
+ *
+ * Only the user's turns count. Claude Code writes them as `user` lines, and its
+ * own meta lines and tool results in that same shape are not the user's. Codex
+ * writes each as a `user` message item; its `user_message` event is missing
+ * from many rollouts, and the item is in every one (tech notes, section 3).
+ * Its AGENTS.md goes in as a `user` item too, and cannot be the text asked about.
+ */
+export function heldAsUserTurn(harness, file, text) {
+  let lines;
+  try {
+    lines = readFileSync(file, 'utf8').split('\n');
+  } catch {
+    return false;
+  }
+  const wanted = text.trim();
+  return lines.some((line) => userTexts(harness, line).some((said) => said.trim() === wanted));
+}
+
+/** The texts of one record line, when it is a turn of the user's. */
+function userTexts(harness, line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return [];
+  }
+  if (harness === 'claude') {
+    if (parsed?.type !== 'user' || parsed.isMeta === true) return [];
+    const content = parsed.message?.content;
+    if (typeof content === 'string') return [content];
+    return Array.isArray(content) ? content.filter((block) => block?.type === 'text').map((block) => String(block.text)) : [];
+  }
+  const item = parsed?.type === 'response_item' ? parsed.payload : undefined;
+  if (item?.type !== 'message' || item.role !== 'user' || !Array.isArray(item.content)) return [];
+  return item.content.filter((block) => block?.type === 'input_text').map((block) => String(block.text));
 }
 
 function claudeConversations(home) {
@@ -87,7 +132,7 @@ function codexConversations(home, from) {
     .flatMap((file) => {
       const meta = sessionMeta(file);
       return meta?.cwd === home && typeof meta.id === 'string'
-        ? [{ id: meta.id, at: Date.parse(meta.timestamp ?? '') || startedAt(file) || 0, file }]
+        ? [{ id: meta.id, at: Date.parse(meta.timestamp ?? '') || startedAt(file) || 0, file, subagent: isSubagent(meta) }]
         : [];
     });
 }
@@ -113,6 +158,15 @@ function sessionMeta(file) {
   }
 }
 
+/**
+ * Codex marks a conversation it ran as a subagent under `source`: its own
+ * auto-review is `{ subagent: { other: 'guardian' } }`, and one a session spawned
+ * is `{ subagent: { thread_spawn: … } }`. A session's own is a plain word, such as
+ * `cli` or `exec` (tech notes, section 3).
+ */
+const isSubagent = (meta) =>
+  meta.source !== null && typeof meta.source === 'object' && 'subagent' in meta.source;
+
 /** When a file was last written, for leaving out what is plainly too old. */
 function lastTouched(file) {
   try {