@assuredloop/orca-bot-kit 0.3.0 → 0.5.0

package/src/settings.js

@@ -0,0 +1,158 @@
+// What a running session really runs with, set beside what its bot.yaml asks for.
+//
+// A session can run on settings other than the ones bot.yaml asks for: it
+// started before a change, a default of the user's own leaked in, or a flag was
+// dropped. Each harness writes down what it used (tech notes, sections 2 and 3),
+// so the two can be put side by side. Read only: these are the harness's files.
+//
+// Four answers, and only one of them is good news. A record that cannot be read,
+// or that does not carry the setting, is not agreement: it is `unknown`. A
+// setting the session never asked for is not a disagreement either, whatever the
+// harness chose: it is `not-asked-for`.
+
+import { DEFAULT_APPROVAL } from './launch.js';
+import { lines } from './usage.js';
+
+export const SETTINGS = ['model', 'effort', 'context', 'approval'];
+
+/**
+ * Each setting of `session` as `{ state, configured?, observed? }`, judged
+ * against `file`, the harness's record of the conversation the session is in
+ * now, from `since`, when the kit last started it. No file is no record, and
+ * every setting asked for is then unknown.
+ */
+export function settingsInUse(harness, session, file, since) {
+  const used = file === undefined ? {} : (harness === 'claude' ? fromClaude : fromCodex)(sinceStart(lines(file), since));
+  return Object.fromEntries(SETTINGS.map((name) => [name, judged(harness, name, asked(session, name), used[name])]));
+}
+
+/**
+ * What the record says since the kit last started the session. A start resumes
+ * the conversation it had, so the file still holds what the process before it
+ * wrote, and that says what that process ran with, not this one. Everything
+ * from the first line written at or after the start counts, a line with no time
+ * of its own included. With no start to go by, no line can be shown to be this
+ * process's, so none counts.
+ */
+function sinceStart(entries, since) {
+  const from = Date.parse(since ?? '');
+  if (Number.isNaN(from)) return [];
+  const first = entries.findIndex((entry) => Date.parse(entry.timestamp ?? '') >= from);
+  return first === -1 ? [] : entries.slice(first);
+}
+
+/** What the session asks for, as bot.yaml has it, or undefined when it asks for nothing. */
+function asked(session, name) {
+  const value = session[name];
+  const set = value !== undefined && value !== null && String(value).trim() !== '';
+  // The kit puts an approval level on every launch line, so a session always
+  // asks for one: the default, when it names none (ADR 0015).
+  if (name === 'approval') return set ? String(value).trim() : DEFAULT_APPROVAL;
+  return set ? String(value).trim() : undefined;
+}
+
+function judged(harness, name, configured, observed) {
+  const shown = observed === undefined ? {} : { observed: said(name, observed) };
+  if (configured === undefined) return { state: 'not-asked-for', ...shown };
+  const verdict = same(harness, name, configured, observed);
+  if (verdict === undefined) return { state: 'unknown', configured, ...shown };
+  return { state: verdict ? 'match' : 'mismatch', configured, ...shown };
+}
+
+/** Whether the record says what was asked for; undefined when it cannot say. */
+function same(harness, name, configured, observed) {
+  if (observed === undefined) return undefined;
+  if (name === 'model') return sameModel(configured, observed);
+  // Codex reports the window it was given at 95%, rounded down (tech notes,
+  // section 3): 200000 comes back as 190000.
+  if (name === 'context') return Number(observed) === Math.floor(Number(configured) * 0.95);
+  if (name === 'approval') return harness === 'claude' ? observed === CLAUDE_MODES[configured] : sameCodexApproval(configured, observed);
+  return observed === configured;
+}
+
+/**
+ * A model named without a dash is an alias, `sonnet`, and the harness writes the
+ * id it stands for, `claude-sonnet-5`: it matches an id it is one part of. A
+ * model with a dash is an id already, and has to be the one that ran. The
+ * context window Claude Code carries on the model name, `sonnet[1m]`, is not
+ * part of what it writes down.
+ */
+function sameModel(configured, observed) {
+  const model = configured.replace(/\[[^\]]*\]$/, '');
+  return model.includes('-') ? observed === model : observed.split('-').includes(model);
+}
+
+/** The permission mode Claude Code records for each level (tech notes, section 2). */
+const CLAUDE_MODES = { auto: 'auto', ask: 'default', 'dangerously-skip': 'bypassPermissions' };
+
+/**
+ * What Codex records for each level, and only the words that level decides: at
+ * `ask` the kit passes only the approval policy, so the sandbox is the user's
+ * own (ADR 0015), and at `dangerously-skip` nothing is reviewed (tech notes,
+ * section 3).
+ */
+const CODEX_WORDS = {
+  auto: { policy: 'on-request', reviewer: 'auto_review', sandbox: 'workspace-write' },
+  ask: { policy: 'on-request', reviewer: 'user' },
+  'dangerously-skip': { policy: 'never', sandbox: 'danger-full-access' },
+};
+
+function sameCodexApproval(configured, observed) {
+  const wanted = CODEX_WORDS[configured];
+  if (wanted === undefined) return false;
+  const pairs = Object.entries(wanted);
+  // A word the level decides and the record does not carry leaves it unsaid.
+  if (pairs.some(([key]) => observed[key] === undefined)) return undefined;
+  return pairs.every(([key, word]) => observed[key] === word);
+}
+
+/** A value the record carried, as the report shows it. */
+function said(name, observed) {
+  if (name !== 'approval' || typeof observed === 'string') return String(observed);
+  return [
+    `approval_policy ${observed.policy}`,
+    ...(observed.reviewer === undefined ? [] : [`approvals_reviewer ${observed.reviewer}`]),
+    ...(observed.sandbox === undefined ? [] : [`sandbox ${observed.sandbox}`]),
+  ].join(', ');
+}
+
+/**
+ * What a Claude Code transcript says it runs with, the latest of each: the
+ * model and effort on its replies, the permission mode wherever it is noted.
+ * Claude Code writes nothing that shows the context window.
+ */
+function fromClaude(entries) {
+  const used = {};
+  for (const entry of entries) {
+    if (entry.type === 'assistant' && entry.isSidechain !== true) {
+      const model = entry.message?.model;
+      if (typeof model === 'string' && model !== '<synthetic>') used.model = model;
+      if (typeof entry.effort === 'string') used.effort = entry.effort;
+    }
+    if (typeof entry.permissionMode === 'string') used.approval = entry.permissionMode;
+  }
+  return used;
+}
+
+/** What a Codex rollout says it runs with: its latest turn, and its latest count. */
+function fromCodex(entries) {
+  const used = {};
+  for (const entry of entries) {
+    const payload = entry.payload;
+    if (payload === null || typeof payload !== 'object') continue;
+    if (entry.type === 'turn_context') {
+      if (typeof payload.model === 'string') used.model = payload.model;
+      if (typeof payload.effort === 'string') used.effort = payload.effort;
+      if (typeof payload.approval_policy === 'string') {
+        used.approval = {
+          policy: payload.approval_policy,
+          reviewer: typeof payload.approvals_reviewer === 'string' ? payload.approvals_reviewer : undefined,
+          sandbox: typeof payload.sandbox_policy?.type === 'string' ? payload.sandbox_policy.type : undefined,
+        };
+      }
+    }
+    const window = payload.info?.model_context_window;
+    if (entry.type === 'event_msg' && payload.type === 'token_count' && typeof window === 'number') used.context = window;
+  }
+  return used;
+}

package/src/skills.js

@@ -3,25 +3,30 @@
 //
 // Linked, never copied, in both directions. Inwards: what lands in the bot home
 // is a symlink to the skill's own directory, so a kit skill is read where the
-// package installed it and an edit to a skill is what a running session reads —
-// both harnesses follow a symlinked skill folder and pick a change up without a
-// restart (tech notes, sections 2 and 3). Outwards: the kit takes away only the
-// links it put there, and never the skill one was pointing at.
+// package installed it, and both harnesses follow the link. A running session
+// reads an edited skill the next time it loads it. A skill linked in or taken
+// away reaches it without a restart. Claude Code takes it through its own
+// `/reload-skills`, which `obk skills build` types into the session's tab.
+// Codex has no such command and takes it at the start of its next turn (tech
+// notes, sections 2 and 3). Outwards: the kit takes away only the links it put
+// there, and never the skill one was pointing at.
 //
 // An entry names one of four shelves: the kit's own (`kit:<name>`), an online
 // source `skills.yaml` lists (`<source>:<name>`, read from its clone beside the
 // bots folder), the user's common folder (a bare name), or a path to anywhere
 // on disk.
 
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { parse, parseDocument, stringify } from 'yaml';
 
+import { bookFile, readBook } from './book.js';
 import { botDir, botNames, changesExactly, leadsOutside, readBot, YAML_OUT } from './bot.js';
-import { ownCli, shellWord } from './launch.js';
+import { harnessOf, ownCli, shellWord } from './launch.js';
+import { orcaCli, orcaTrouble, tabToTypeInto, typeIntoTab } from './orca.js';
 import { listIn } from './rules.js';
 import { cloneDir, isCloned, readSources, skillsIn, wrongClone } from './sources.js';
 
@@ -130,7 +135,7 @@ export function removeSkill(bots, bot, ref) {
 
 /**
  * Give one bot the skills its lists name. Returns what there is to report:
- * `{ bot, skills, removed }` for a bot whose links are in place, and
+ * `{ bot, skills, linked, removed }` for a bot whose links are in place, and
  * `{ bot, skills, trouble }` for one whose list the kit could not follow.
  *
  * A list with one entry the kit cannot follow links nothing at all: half a
@@ -210,6 +215,7 @@ export function linkSkills(bots, home, bot) {
   // something to throw through `prepareBots` and stop the fleet. What was
   // linked before it went wrong is still written down, so the next run knows it
   // for the kit's own.
+  const linked = [];
   const removed = [];
   try {
     for (const harness of Object.keys(SKILL_DIRS)) {
@@ -218,8 +224,8 @@ export function linkSkills(bots, home, bot) {
         held.set(harness, heldIn(path.join(home, SKILL_DIRS[harness]), record[harness]));
         continue;
       }
-      const done = link(path.join(home, SKILL_DIRS[harness]), wanted, record[harness]);
-      removed.push(...done.removed);
+      // Filled as it goes, so what was changed before a failure is still known.
+      const done = link(path.join(home, SKILL_DIRS[harness]), wanted, record[harness], linked, removed);
       held.set(harness, done.held);
     }
   } catch (error) {
@@ -232,6 +238,9 @@ export function linkSkills(bots, home, bot) {
     return {
       bot: bot.name,
       skills: heldBy(home, [], held),
+      // What did change before it went wrong, so the sessions it reaches are told.
+      linked: [...new Set(linked)].sort(),
+      removed: [...new Set(removed)].sort(),
       trouble: `${bot.name}'s skills could not be linked: ${error.message}. Nothing of yours was changed; put right what is named there, then build again.`,
     };
   }
@@ -243,6 +252,7 @@ export function linkSkills(bots, home, bot) {
     return {
       bot: bot.name,
       skills,
+      linked: [...new Set(linked)].sort(),
       removed: [...new Set(removed)].sort(),
       trouble: [...away].map(([harness, real]) => `${path.join(home, SKILL_DIRS[harness])} leads outside the bot folder, to ${real}, through a link, and the kit links skills only inside the bot folder, so ${harness} does not get the skills the lists name. Replace the link with a directory of the bot's own, then build again.`).join(' '),
     };
@@ -251,6 +261,7 @@ export function linkSkills(bots, home, bot) {
   return {
     bot: bot.name,
     skills,
+    linked: [...new Set(linked)].sort(),
     removed: [...new Set(removed)].sort(),
     // A name the lists ask for that the bot has something else under. The user's
     // own is never written over, so what they have to know is that the list did
@@ -391,7 +402,8 @@ function namesIn(dir) {
 
 /**
  * Give every bot in the folder its skills, or the one named, in name order.
- * This is the whole of `obk skills build`: it writes links and asks Orca nothing.
+ * This is the whole of `obk skills build`: it writes links, and a bot whose
+ * links changed has its running sessions told (`tellSessions`).
  */
 export function buildSkills(bots, { bot: onlyBot } = {}) {
   const names = botNames(bots);
@@ -401,11 +413,89 @@ export function buildSkills(bots, { bot: onlyBot } = {}) {
 
   return (onlyBot === undefined ? names : [onlyBot]).map((name) => {
     const home = botDir(bots, name);
+    let bot;
+    let entry;
     try {
-      return linkSkills(bots, home, readBot(home, name));
+      bot = readBot(home, name);
+      entry = linkSkills(bots, home, bot);
     } catch (error) {
       return { bot: name, skills: [], trouble: error.message };
     }
+    const changed = (entry.linked?.length ?? 0) + (entry.removed?.length ?? 0) > 0;
+    return changed ? { ...entry, sessions: tellSessions(home, bot, entry.linked) } : entry;
+  });
+}
+
+/** How long Orca is given to say what is in a session's tab. */
+const LOOK_MS = 2000;
+
+/**
+ * Tell each session of a bot whose skill links just changed, through its
+ * harness's own means (PRD 6.5: changes reach running sessions without a
+ * restart, and the sessions a change affects are told). Returns one entry per
+ * session, in the bot's order: `{ session, harness, state }`, where the state
+ * is `reloaded`, `next-turn` (with `read`), `not-up`, `blocked` (with
+ * `blocked`) or `unknown` (with `trouble`).
+ *
+ * Claude Code gets `/reload-skills` typed into its tab, through the same gate
+ * as the mail nudge. A busy session queues it and runs it as a command when
+ * its turn ends, so it never reaches the model as text. Codex has no reload
+ * command and takes the change at the start of its next turn by itself, so
+ * nothing is typed, and the caller is given the SKILL.md of each skill linked
+ * in, for the session to read if the skill has not appeared (tech notes,
+ * sections 2 and 3). Nothing is ever restarted.
+ */
+function tellSessions(home, bot, linked) {
+  let book;
+  try {
+    book = readBook(home).sessions;
+  } catch (error) {
+    // The links are made; which tab is whose is what cannot be known.
+    const trouble = `${bookFile(home)} cannot be read (${error.message}), so the kit could not tell which tab is this session's, and nothing was typed`;
+    return bot.sessions.map((session) => ({ session: session.name, harness: harnessOf(session, bot.harness), state: 'unknown', trouble }));
+  }
+  // Resolved, because Orca is asked about this folder by path and does not
+  // follow a link to it (tech notes, section 1).
+  let real;
+  try {
+    real = realpathSync(home);
+  } catch {
+    real = home;
+  }
+  // An Orca whose runtime is not there still answers some commands from what
+  // it last knew, so it is asked whether it is up before it is asked anything
+  // about a tab.
+  const down = bot.sessions.some((session) => typeof book[session.name]?.tab === 'string') ? orcaTrouble() : undefined;
+
+  return bot.sessions.map((session) => {
+    const harness = harnessOf(session, bot.harness);
+    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` };
+    try {
+      const found = tabToTypeInto(real, tab, LOOK_MS);
+      if (found.blocked !== undefined) return { ...told, state: 'blocked', blocked: found.blocked };
+      if (found.unsure !== undefined) return { ...told, state: 'unknown', trouble: found.unsure };
+      if (found.handle === undefined) return { ...told, state: 'not-up' };
+      // The book's tab, now running the other harness: its reload is not this one's.
+      if (found.agent !== harness) {
+        return { ...told, state: 'unknown', trouble: `Orca names ${found.agent} in its tab, not ${harness}, so nothing was typed` };
+      }
+
+      if (harness === 'codex') {
+        // Only what Codex can actually read: a link can fail for one harness
+        // alone, and a skills directory that is the user's gets none.
+        const read = linked.map((name) => path.join(home, SKILL_DIRS.codex, name, MANIFEST)).filter((file) => existsSync(file));
+        return { ...told, state: 'next-turn', read };
+      }
+      typeIntoTab(found.handle, '/reload-skills');
+      return { ...told, state: 'reloaded' };
+    } catch (error) {
+      // The links are made whatever Orca says, so this is reported, not
+      // thrown: the build did what it was asked, and the session was not told.
+      return { ...told, state: 'unknown', trouble: error.message };
+    }
   });
 }
 
@@ -489,7 +579,9 @@ function follow(bots, ref, sources) {
 
 /**
  * Make one harness's skills directory hold what `wanted` says, as far as the
- * kit is allowed to. Returns `{ removed, held }` — the names it took away, and
+ * kit is allowed to. Returns `{ linked, removed, held }` — the names it linked
+ * in or repointed, the names it took away (added to the lists given, as it
+ * goes, so a caller whose run throws still has them), and
  * what is in the directory afterwards.
  *
  * The kit acts only where the entry on disk is still the link it wrote, which
@@ -497,12 +589,10 @@ function follow(bots, ref, sources) {
  * link the very same skill by hand — so the kit remembers what it made rather
  * than guessing from where a link points (PRD 6.7).
  */
-function link(dir, wanted, record) {
+function link(dir, wanted, record, linked = [], removed = []) {
   // The directory is there: `linkSkills` makes both before it calls this.
 
   const keep = new Map(wanted.map((skill) => [skill.name, skill]));
-  const removed = [];
-
   // What the lists no longer name. The kit takes back only its own, and only
   // while it is untouched; anything else it forgets about and leaves.
   for (const name of Object.keys(record)) {
@@ -541,9 +631,10 @@ function link(dir, wanted, record) {
     // repo, and the link has to reach out of the repo to find it (ADR 0014).
     symlinkSync(skill.dir, at);
     record[skill.name] = skill.dir;
+    linked.push(skill.name);
   }
 
-  return { removed, held: heldIn(dir, record) };
+  return { linked, removed, held: heldIn(dir, record) };
 }
 
 /**

package/src/up.js

@@ -6,14 +6,15 @@
 
 import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { setTimeout as pause } from 'node:timers/promises';
 
 import { forgetClaimed, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, readBot } from './bot.js';
-import { conversationsIn } from './conversations.js';
+import { conversationsIn, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isShortPrompt, launchCommand, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, typeIntoTab, useMailbox } from './orca.js';
-import { buildAgents } from './rules.js';
+import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { buildAgents, rulesStamp } from './rules.js';
 import { linkSkills } from './skills.js';
 
 /** The one bot with a tab beside its sessions: the ops tab (PRD 6.2). */
@@ -35,6 +36,7 @@ const SECOND_LOOK_MS = 2000;
  * Bring bots up in Orca. Returns `{ tabs, rules }`: one tab entry per tab it
  * looked at — the sessions the book knows, and, for Bot Father, whatever else
  * is open in its project — and one rules entry and one skills entry per bot.
+ * `projects` has one entry per Orca project this run made or renamed.
  *
  * With no name it is every bot in the folder, in name order. `bot` brings up
  * one bot and `session` one of its sessions, for a caller that wants one thing
@@ -58,11 +60,14 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
   const { running, rules, skills } = prepareBots(bots, names, onlySession);
 
   const report = [];
+  const projects = [];
   for (const { bot, home } of running) {
     for (const session of sessionsOf(bot, onlySession)) {
       if (session.paused === true) paused.push({ bot: bot.name, session: session.name });
     }
-    report.push(...await bringUpBot(bots, home, bot, onlySession));
+    const up = await bringUpBot(bots, home, bot, onlySession);
+    report.push(...up.tabs);
+    if (up.project !== undefined) projects.push(up.project);
   }
 
   // A bot whose rules would not build is reported here rather than in the
@@ -78,6 +83,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
     })),
     skills,
     paused,
+    projects,
   };
 }
 
@@ -197,8 +203,11 @@ async function bringUpBot(bots, home, bot, onlySession) {
   // Orca is asked first and the book is written after: nothing that takes time
   // happens while the book is held, because a session's own hook may be writing
   // its id into that same file at any moment.
-  const orca = orcaProject(home, title);
+  const { change, ...orca } = orcaProject(home, title);
   await updateBook(home, (book) => { book.orca = orca; });
+  // Orca's window does not see a project made or renamed on the command line
+  // until it is told (#224).
+  if (change !== undefined) tellWindow(orca.project);
 
   const live = new Map(tabs(home).map((tab) => [tab.tabId, tab]));
   const report = [];
@@ -217,7 +226,7 @@ async function bringUpBot(bots, home, bot, onlySession) {
       : spare.map((tab) => entry(tab, { bot: name, name: null, created: false }))));
   }
 
-  return report;
+  return { tabs: report, project: change === undefined ? undefined : { bot: name, project: orca.project, change } };
 }
 
 async function bringUpSession(bots, home, live, session, bot, title) {
@@ -292,12 +301,17 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // started a harness in it, and a conversation taken over from the harness's
   // own record are new.
   const launched = new Date().toISOString();
+  // Which instructions it is about to read: the AGENTS.md this run has just
+  // built, noted so that health can say when the file moves on and the session
+  // does not (#272).
+  const rules = rulesStamp(home);
   await updateBook(home, (current) => {
     // What the harness has in this folder that nobody claims goes on the record,
     // for a person or Bot Father to settle — added to whatever was already noted,
     // because this run's scan cannot see what an earlier one found. The kit never
     // settles it itself.
-    const entry = { ...current.sessions[session.name], tab: made.tabId, launched };
+    const entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
+    if (rules === undefined) delete entry.rules;
     current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
     forgetClaimed(current);
   });
@@ -326,24 +340,54 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   const tui = first.running ? lookFor(made.handle, SECOND_LOOK_MS) : first;
 
   // The start prompt went in with that line, as the harness's own prompt
-  // argument, so it is the harness that holds it until it is ready — through
-  // its folder-trust question and its update offer. What is still worth saying
-  // is whether the line took at all: a shell that swallowed it swallowed the
-  // duty with it, and nobody has been told anything.
-  const promptSent = prompt === undefined ? undefined : tui.running === true;
+  // argument, and a harness running in the tab is not yet a session told its
+  // duty: one held on a first-run screen, or one that refused the argument, has
+  // been told nothing. So it is received only when the session's own record
+  // holds it as a user turn, and otherwise not confirmed (#274).
+  const promptReceived = prompt === undefined
+    ? undefined
+    : await heldInRecord(home, session.name, harness, prompt, { launched, running: tui.running === true });
 
   return entry(made, {
     bot: bot.name,
     name: session.name,
     created: true,
     ...tui,
-    promptSent,
+    promptReceived,
     promptFile,
     resumed: resume !== undefined,
     unclaimed: which.unclaimed,
   });
 }
 
+/**
+ * How long a running harness's own record is given to show the start prompt.
+ * Seen live (Claude Code 2.1.282, a trusted folder): the hook's id and the
+ * user turn landed about as the second look ended, so one read there comes a
+ * moment too early. A harness held on a first-run screen costs the whole wait.
+ */
+const RECORD_MS = 5000;
+const RECORD_ASK_MS = 250;
+
+/**
+ * Whether the conversation the book names for this session holds `prompt` as a
+ * user turn in the harness's own record. The name comes from the session's own
+ * hook, so a harness that has not reported one — held on a first-run screen,
+ * say — has no record to be read, and the answer is that it is not confirmed.
+ * Another conversation in the same folder is never asked: it may be a sister
+ * session told the same words.
+ */
+async function heldInRecord(home, name, harness, prompt, { launched, running }) {
+  const until = Date.now() + (running ? RECORD_MS : 0);
+  for (;;) {
+    const id = readBook(home).sessions[name]?.session;
+    const record = typeof id === 'string' ? transcriptsIn(harness, home, launched).find((one) => one.id === id) : undefined;
+    if (record !== undefined && heldAsUserTurn(harness, record.file, prompt)) return true;
+    if (Date.now() >= until) return false;
+    await pause(RECORD_ASK_MS);
+  }
+}
+
 /**
  * One look at a tab the kit just typed a launch line into: whether a harness
  * is running there, and what it is waiting on if Orca says.
@@ -455,7 +499,8 @@ function whichConversation(book, home, bot, session, was, harness) {
 }
 
 /**
- * A bot's Orca project, made if it is not there yet.
+ * A bot's Orca project, made if it is not there yet, with `change` saying
+ * whether this run `made` it, `renamed` it or left it as it was (undefined).
  *
  * It has to be a folder workspace. Registering a folder that sits inside the
  * bots repo gets it recorded as a git one, which Orca gives no workspace at
@@ -463,12 +508,12 @@ function whichConversation(book, home, bot, session, was, harness) {
  */
 function orcaProject(home, title) {
   const found = findProject(home);
-  const setup = found === undefined
-    ? makeProject(home, title)
-    : (found.kind === 'folder' ? found : asFolderProject(found.id, title));
-  return { project: setup.projectId, setup: setup.id };
+  if (found === undefined) return ids(makeProject(home, title), 'made');
+  return found.kind === 'folder' ? ids(found) : ids(asFolderProject(found.id, title), 'renamed');
 }
 
+const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, change });
+
 /**
  * Where the kit leaves a prompt for the launch line to pick up: a folder of its
  * own beside the bots repo, the way skill-source clones sit beside it (PRD 6.3)
@@ -481,7 +526,7 @@ function orcaProject(home, title) {
 export const promptPath = (bots, bot, session) =>
   path.join(`${bots}.prompts`, `${encodeURIComponent(bot)}.${encodeURIComponent(session)}.txt`);
 
-function entry(tab, { bot, name, created, running = false, blockedReason, promptSent, promptFile, resumed, unclaimed }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, unclaimed }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // Whether this run picked the session up where it was or started a new one.
   // Only for a tab this run opened: a tab that was already there was left alone.
@@ -493,7 +538,7 @@ function entry(tab, { bot, name, created, running = false, blockedReason, prompt
   // claims: the caller is told, because the kit will not pick one.
   if (unclaimed !== undefined && unclaimed.length > 0) made.unclaimed = unclaimed;
   // Only for a session this run started that had something to be told.
-  if (promptSent !== undefined) made.promptSent = promptSent;
+  if (promptReceived !== undefined) made.promptReceived = promptReceived;
   // And the file it was told it out of, when it was too long for the line.
   if (promptFile !== undefined) made.promptFile = promptFile;
   return made;