@assuredloop/orca-bot-kit 0.2.0 → 0.4.0

package/skills/obk-tdd/SKILL.md

@@ -35,8 +35,12 @@ tests live and how they are named, what the tests next door already do, and
 which commands the project's own checks actually run. Never assume a default
 command because it is the usual one for the language.
 
-Use the focused command through the loop and the whole-suite command before you
-finish.
+Use the focused command through the loop. Before you finish, run what the
+project requires, plus the checks that cover the change and its credible effects
+elsewhere. The whole suite earns its cost on a broad or shared change and at a
+release gate; when you leave it out, name the coverage you ran instead and why it
+is enough. A gate the project requires is never waived, and a run still going is
+not a run that passed.
 
 ## Start from the requirement, not the code
 
@@ -306,8 +310,9 @@ A seam below that gives a green test and no protection. If no correct seam
 exists, that is itself the finding: report it, because the shape of the code is
 what is stopping the bug from being pinned down.
 
-Minimise the reproduction until every part of it is load-bearing, turn it into
-a failing test, watch it fail, fix the cause, watch it pass, then run the
+Minimise the reproduction until reducing it further would not improve the
+diagnosis or the regression check, and keep the evidence you stopped on. Turn it
+into a failing test, watch it fail, fix the cause, watch it pass, then run the
 original unminimised scenario again.
 
 Two tests are often better than one here: one at the interface, saying what a
@@ -316,15 +321,20 @@ lives. Get both to pass. The first is what stops the bug coming back in a way
 anyone would notice; the second says where it was.
 
 A regression test written after the fix has proved nothing yet. Prove it:
-revert the fix, run it and watch it fail, restore the fix, run it again.
+revert the fix, run it and watch it fail, restore the fix, run it again. A test
+that already failed on a named pre-fix baseline and passes with the fix, unchanged
+in between, has its proof: keep that receipt instead of reverting again. Where
+the test changed since, or its sensitivity is unproven, prove it again on the bad
+baseline in a disposable copy.
 
 When the bug is intermittent, make the test deterministic if you can, and say
 which signal you pinned down. When it is one of a class, land the test for the
 one in front of you first, then say what else has the same shape.
 
 When a failing test really is impractical, say so out loud, say why, and name
-the closest executable check you used instead. Quiet omission is the part that
-does damage: a reviewer treats a missing red receipt as a finding.
+the closest executable check you used instead. Naming a check you will run later
+is not having run one. Quiet omission is the part that does damage: a reviewer
+treats a missing red receipt as a finding.
 
 ## Tests that catch nothing
 
@@ -406,11 +416,13 @@ The question is the whole point: if a real mistake were made in this code,
 would a test fail? There is no score to reach.
 
 **Everyday: your own hand check.** Once per piece of work, at the end, only
-where it earns its place. Five to eight deliberate breaks in the risky logic
-the work changed (money, permissions, eligibility, safety, data that could be
-lost, and whatever else the requirement cares most about), chosen before you
-look at the tests, each one run, each one expected to make a test fail, each
-one put back. Reported in three lines.
+where it earns its place. A small representative set of distinct, plausible
+mistakes in the risky logic the work changed (money, permissions, eligibility,
+safety, data that could be lost, and whatever else the requirement cares most
+about), chosen before you look at the tests, each one run, each one expected to
+make a test fail, each one put back. Stop when another break would add no
+evidence, and say why the set you ran was enough: two meaningful breaks beat five
+padded ones. Reported in three lines.
 
 One break at a time, never two at once: note the original, apply the break, run
 the tests, record killed or survived, restore the code immediately, then the
@@ -429,8 +441,14 @@ removed so an absent value reaches further than it should; a call to a
 collaborator deleted.
 
 Skip it, and say that you skipped it, for work with no real logic in it: docs,
-config, wiring, renames, small fixes, prototypes, and code with no runnable
-tests.
+wiring, renames, prototypes. Size and file type do not decide whether logic is
+risky: a one-character permission fix is risky logic, and so is a configuration
+that decides who gets what.
+
+Code with no runnable tests is a different case: there is logic, and nothing to
+run it against. Report the missing automated coverage, the reason, the stand-in
+check you used and what is still uncertain. It is a finding when behaviour the
+requirement cares about lacks adequate verification.
 
 **A survivor**, a break no test objected to, gets the equivalence question
 first: is there any input for which the changed code returns a different value,
@@ -503,14 +521,27 @@ the work is handed on.
 
 ## Away from code
 
-The same three moves work on documentation, configuration, prompts and data,
-where no tool will help: state the check before you make the change, see the
-check fail first, and at the end break the artefact on purpose to find out
-whether the check notices.
-
-They apply where there is something that can be wrong: a configuration that
-decides who gets what, a prompt whose branches behave differently, a
-transformation over data. The skip rule is the same as for code, and prose
-written for people earns no test and no mutant.
+The same three moves work on configuration and data, where no tool will help:
+state the check before you make the change, see the check fail first, and at
+the end break the artefact on purpose to find out whether the check notices.
+
+They apply where there is something that can be wrong and a check that can be
+seen to fail: a configuration that decides who gets what, a transformation over
+data. The skip rule is the same as for code.
+
+Prose written for people is checked by review, not by a test: a test that matches
+its text buys nothing. Text written for a model, a prompt included, is checked the
+same way, with one addition: where the requirement is how the model behaves, a
+representative use earns its place, and it is the whole check, without the three
+moves above. A prompt that must hold an action until it is approved is exercised
+once with the approval and once without. Neither needs a manufactured red, and no
+wording edit needs a test of its own.
+
+A decision that cannot be driven locally, such as a CI workflow or a setting in
+someone else's service, is checked in two parts: its parsed structure and
+whatever of it can be executed, then the real run when that is authorised.
+Publishing, spending money or changing someone else's settings is never a
+mandatory step of a check. A real run put off for later names who triggers it and
+says what stays unverified until then.
 
 Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-teach/NOTICE.md

@@ -48,14 +48,14 @@ thanks:
 
 Made generic, which is what the owner asked for. The original is built on top
 of two other skills it invokes by name, and a kit skill carries what it needs
-rather than depending on another being loaded (ADR 0009); here getting
+rather than depending on another being loaded (ADR 0019); here getting
 oriented is part of the work, and where the reasons are the point that is
 named as its own kind of digging without requiring a particular skill. Its
 named image-generation tool is likewise described by what it produces rather
 than by the tool.
 
 One departure: the original keeps itself from being invoked on its own with
-`disable-model-invocation: true`, which is not portable frontmatter (ADR 0009
+`disable-model-invocation: true`, which is not portable frontmatter (ADR 0019
 and PRD 7.2: these run on purpose, never automatically). The description
 carries that instead: the phrases that ask for it, and the note that answering
 a question in passing is not this.

package/skills/obk-why/NOTICE.md

@@ -60,7 +60,7 @@ confidence tiers and the null-result discipline in the skill itself, and leaves
 how the work is divided up to whoever is doing it.
 
 One departure: the original keeps itself from being invoked on its own with
-`disable-model-invocation: true`, which is not portable frontmatter (ADR 0009
+`disable-model-invocation: true`, which is not portable frontmatter (ADR 0019
 and PRD 7.2: these run on purpose, never automatically). The description
 carries that instead: the phrases that ask for it, and the note that it is not
 something to start unasked before an ordinary change.

package/skills/obk-why/SKILL.md

@@ -46,14 +46,15 @@ hangs off that anchor, and an investigation that never had one tends to answer
 a question nobody asked.
 
 Where the project keeps its history, start there. Who last touched these
-lines and in what change; the whole life of the file, including through
-renames; what the change said about itself; and whatever discussion is attached
-to it, which is usually where the reason actually is.
+lines and in what change; as much of the file's life, through renames, as it
+takes to reach the change that answers the question; what the change said about
+itself; and whatever discussion is attached to it, which is usually where the
+reason actually is.
 
 ## Then look where else this project keeps its reasons
 
 Different reasons live in different places, and which of these exist varies by
-project. Use the ones it has:
+project. Use the ones it has, as far as the question needs:
 
 - **The history and its discussion**, where the project keeps them. Best for
   the reason given at the time by the person doing it, under review. For a
@@ -72,11 +73,15 @@ project. Use the ones it has:
   Best for defensive code: a guard, a retry, a limit, a special case usually
   exists because something happened.
 
-Look in them in parallel where you can, one pass per source with its own
-question. Where a source does not exist or you cannot reach it, that is a
-finding: write down that you could not look there. Skipping something because
-it is probably irrelevant is not the same as it being provably irrelevant, and
-the first one belongs in the write-up as a gap.
+How many of them to open depends on what is still unanswered: once a change
+and its discussion settle the reason, the rest adds nothing unless something
+contradicts it, and they need neither a look nor a line in the write-up. While
+the answer is open, look in the sources that could still change it, in parallel
+where you can, one pass per source with its own question. Where one of those does
+not exist or you cannot reach it, that is a finding: write down that you could
+not look there. Skipping one of those because it is probably irrelevant is not
+the same as it being provably irrelevant, and the first belongs in the write-up
+as a gap.
 
 Watch for the newest change looking authoritative. The shape you are asking
 about is usually the accumulation of several decisions, and the most recent one
@@ -150,12 +155,18 @@ explanation of it.
 
 ## What you hand back
 
+These are the questions the hand-back answers, not headings to print: a one-line
+answer is one line, and it still carries its citation and any uncertainty or
+search limit that would change how it is used.
+
 - **The question**, as you understood it.
 - **The code**, so the reader knows what is being explained.
 - **What was actually recorded**, cited.
 - **What follows from it**, marked as reasoning.
 - **Other explanations that fit**, where more than one does.
-- **What nobody wrote down**, with what you searched.
+- **What nobody wrote down**, with what you searched: where the search
+  stopped, what settled it, and the places that could matter which you left
+  unchecked.
 - **Where you looked**, one line per source, including the ones that held
   nothing and the ones you could not reach, with the reason.
 - **How sure you are overall**, in a line.

package/src/book.js

@@ -1,5 +1,5 @@
 // The book: `sessions.yaml` in a bot's home. It is the authority for what the
-// kit knows about a bot's sessions (ADR 0002) — Orca forgets a tab's resume
+// kit knows about a bot's sessions (ADR 0012) — Orca forgets a tab's resume
 // record the moment the tab is closed, so the kit keeps its own record.
 //
 // It is an ordinary file of the user's bots repo: committed, readable, and
@@ -254,7 +254,7 @@ const asRecord = (value) => (value !== null && typeof value === 'object' && !Arr
 /**
  * The session entry to keep once a harness has named the session it is running
  * as. The id the harness gave replaces the one the book held, and the one it
- * held goes into the history with the reason it was replaced (ADR 0002): old
+ * held goes into the history with the reason it was replaced (ADR 0012): old
  * ids are what recall, auditing and finops read later.
  *
  * The same id come back is a session resumed, not a new one, so nothing moves.

package/src/bot.js

@@ -59,7 +59,7 @@ export function botNames(bots) {
  * link the user made takes it out of that folder; undefined when it stays in.
  *
  * The kit writes only in the bot folder, never in user-level settings (PRD 6.3,
- * ADR 0010), and a link would make the one the other without a word. So the
+ * ADR 0020), and a link would make the one the other without a word. So the
  * answer is the file system's, not the spelling's: see `whereItLeads`.
  */
 export function leadsOutside(home, target) {

package/src/cli.js

@@ -9,15 +9,16 @@
 
 import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
-import { addSession, changeBot, changeSession, createBot, readBot, SESSION_FIELDS } from './bot.js';
+import { addSession, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
 import { grooming } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
-import { APPROVALS, HARNESSES, shellWord } from './launch.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';
@@ -82,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
@@ -102,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
@@ -380,6 +385,21 @@ function sameFleet(bots) {
  */
 const lookAt = (terminal) => `${shellWord(orcaCli())} terminal read --terminal ${terminal} --screen`;
 
+/** The SETUP.md shipped with the running kit, whose section 5 has the answers. */
+const SETUP = fileURLToPath(new URL('../SETUP.md', import.meta.url));
+
+/**
+ * Who answers a tab left on a screen: the caller, not the user (PRD 6.5). The
+ * kit names where the answers are rather than carrying them, because which
+ * keys answer which screen is judgment that changes with every harness
+ * release, and that belongs in the skill (ADR 0016).
+ */
+const ANSWER_IT = [
+  `             Answer what is on screen yourself, without asking the user: section 5 of ${SETUP}`,
+  '             and the obk-bot-building skill have the keys for the usual screens.',
+  '             Anything you do not recognise gets no keypress: take it to the user.',
+];
+
 /** The one command a harness runs rather than a person: the kit's hook. */
 const RECORD = 'session record';
 
@@ -389,7 +409,7 @@ const RECORD = 'session record';
  * A hook runs inside the user's own session, so this one stays out of the way:
  * it writes on standard output only what the harness is to read as JSON, and
  * whatever goes wrong, it goes wrong quietly. A book left stale is a thing the
- * health check finds later; a session disturbed is the user's work (ADR 0010).
+ * health check finds later; a session disturbed is the user's work (ADR 0020).
  */
 async function record(bots, bot) {
   try {
@@ -409,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}`
@@ -448,8 +468,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,
@@ -470,7 +490,7 @@ const commands = {
       lines: [
         ...paused.closed.map((tab) => `closed     ${tab.bot} ${tab.name}  tab ${tab.tabId}  terminal ${tab.terminal}`),
         `${paused.changed ? 'paused' : 'there'.padEnd(6)}     ${what}${paused.changed ? '' : ' was paused already'}`,
-        `obk up leaves it closed, and the book keeps its conversations. Bring it back:  obk unpause --bots ${bots} --bot ${values.bot}${back}`,
+        `obk up leaves it closed, and the book keeps its conversations. Bring it back:  ${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${values.bot}${back}`,
       ],
     };
   },
@@ -502,11 +522,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`,
       ],
     };
@@ -532,8 +566,8 @@ const commands = {
         ...rulesLines(rules, bots),
         ...skillsLines(skills),
         trouble
-          ? `${made.bot} is written, and its rules are not. Settle what the line above says, then:  obk rules build --bots ${bots} --bot ${made.bot}`
-          : `${made.bot} is written. Give it a session:  obk session add --bots ${bots} --bot ${made.bot} --name <name>`,
+          ? `${made.bot} is written, and its rules are not. Settle what the line above says, then:  ${shellWord(ownCli())} rules build --bots ${shellWord(bots)} --bot ${made.bot}`
+          : `${made.bot} is written. Give it a session:  ${shellWord(ownCli())} session add --bots ${shellWord(bots)} --bot ${made.bot} --name <name>`,
       ],
       code: trouble ? 1 : 0,
     };
@@ -554,7 +588,7 @@ const commands = {
         `changed    the charter in ${path.join('bots', changed.bot, 'bot.yaml')}`,
         ...rulesLines(rules, bots),
         trouble
-          ? `${changed.bot}'s charter is written, and its rules are not. Settle what the line above says, then:  obk rules build --bots ${bots} --bot ${changed.bot}`
+          ? `${changed.bot}'s charter is written, and its rules are not. Settle what the line above says, then:  ${shellWord(ownCli())} rules build --bots ${shellWord(bots)} --bot ${changed.bot}`
           : `${changed.bot}'s charter is changed. A session that is running read the old one when it started; it reads this one when it next starts.`,
       ],
       code: trouble ? 1 : 0,
@@ -584,7 +618,7 @@ const commands = {
         added.state === 'added'
           ? `added      ${added.skill} to ${path.join('bots', added.bot, 'bot.yaml')}`
           : `there      ${added.skill} is on ${added.bot}'s list already, and nothing was written`,
-        `Link it:   obk skills build --bots ${bots} --bot ${added.bot}`,
+        `Link it:   ${shellWord(ownCli())} skills build --bots ${shellWord(bots)} --bot ${added.bot}`,
       ],
     };
   },
@@ -597,7 +631,7 @@ const commands = {
         removed.state === 'removed'
           ? `removed    ${removed.skill} from ${path.join('bots', removed.bot, 'bot.yaml')}`
           : `absent     ${removed.skill} is not on ${removed.bot}'s list, and nothing was written`,
-        `Unlink it: obk skills build --bots ${bots} --bot ${removed.bot}`,
+        `Unlink it: ${shellWord(ownCli())} skills build --bots ${shellWord(bots)} --bot ${removed.bot}`,
       ],
     };
   },
@@ -611,7 +645,7 @@ const commands = {
         ...Object.entries(source)
           .filter(([key]) => key !== 'name')
           .map(([key, value]) => `           ${key.padEnd(5)}  ${value}`),
-        `Fetch it:  obk skills fetch --bots ${bots} --source ${source.name}`,
+        `Fetch it:  ${shellWord(ownCli())} skills fetch --bots ${shellWord(bots)} --source ${source.name}`,
       ],
     };
   },
@@ -746,7 +780,8 @@ const commands = {
 
   'session add'(bots, values) {
     const added = addSession(bots, values.bot, settingsOf(values));
-    const answer = { bots, bot: added.bot, home: added.home, session: added.session };
+    const found = workDirFound(values, added.bot, added.home, added.session.name);
+    const answer = { bots, bot: added.bot, home: added.home, session: added.session, found };
     return {
       answer,
       lines: [
@@ -754,7 +789,8 @@ const commands = {
         ...Object.entries(added.session)
           .filter(([key]) => key !== 'name')
           .map(([key, value]) => `           ${key}  ${oneLine(value)}`),
-        `Bring it up:  obk up --bots ${bots} --bot ${added.bot}`,
+        ...foundLines(found),
+        `Bring it up:  ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${added.bot}`,
       ],
     };
   },
@@ -765,14 +801,16 @@ const commands = {
     }
     const { name, ...settings } = settingsOf(values);
     const changed = changeSession(bots, values.bot, values.session, settings);
-    const restart = `obk restart --bots ${bots} --bot ${changed.bot} --session ${values.session}`;
+    const restart = `${shellWord(ownCli())} restart --bots ${shellWord(bots)} --bot ${changed.bot} --session ${values.session}`;
+    const found = workDirFound(values, changed.bot, changed.home, values.session);
     return {
-      answer: { bots, bot: changed.bot, home: changed.home, session: changed.session, restart },
+      answer: { bots, bot: changed.bot, home: changed.home, session: changed.session, restart, found },
       lines: [
         `changed    session ${values.session} in ${path.join('bots', changed.bot, 'bot.yaml')}`,
         ...Object.entries(changed.session)
           .filter(([key]) => key !== 'name')
           .map(([key, value]) => `           ${key}  ${oneLine(value)}`),
+        ...foundLines(found),
         `A running session takes this when it next starts:  ${restart}`,
       ],
     };
@@ -794,7 +832,7 @@ function toLines(answer, bots, where) {
     ...(answer.unnamed === true
       ? [`             ${where} is a Claude session running under no name the kit gave it: it was started before the kit named sessions, and nothing renames a live harness. It gets one the next time it starts. Until then the mailbox is the road that reaches it.`]
       : []),
-    `             Send it:  obk message send --bots ${bots} --to ${where} --subject <text> --text <text>`,
+    `             Send it:  ${shellWord(ownCli())} message send --bots ${shellWord(bots)} --to ${shellWord(where)} --subject <text> --text <text>`,
   ];
 }
 
@@ -814,6 +852,23 @@ function nudgeLine(answer, where) {
   return `             ${where} is not up, so nothing was typed anywhere: the message waits in its mailbox.`;
 }
 
+/**
+ * What there is to say about the work dir this command was given: one finding
+ * when it leads out of the bot home, through `..` or a link or as a path
+ * elsewhere, and nothing otherwise (#222). A bot's work and its clones belong
+ * under its own `work/`. It is said, not refused: the user may ask for a folder
+ * anywhere (PRD 6.3), and it is written as they gave it.
+ */
+function workDirFound(values, bot, home, session) {
+  const workDir = workDirOf({ work_dir: values['work-dir'] }, home);
+  if (workDir === undefined || leadsOutside(home, workDir) === undefined) return [];
+  return [{
+    kind: 'work-dir',
+    where: workDir,
+    says: `${workDir} is outside ${bot}'s folder, ${home}. A session's work and every clone it needs go under the bot's work/, as work/${session}, unless you asked for this place in plain words. It is written as given, and nothing was moved.`,
+  }];
+}
+
 /** The settings a `session add` was given, as they go into bot.yaml. */
 function settingsOf(values) {
   const settings = { name: values.name };
@@ -938,15 +993,15 @@ function groomLines(groom, bots) {
   if (!groom.exists) {
     return [
       `${'groom'.padEnd(9)}  there is no daily grooming yet`,
-      `Make one:  obk groom --bots ${bots} --at 04:00`,
+      `Make one:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --at 04:00`,
     ];
   }
 
   return [
     `${'groom'.padEnd(9)}  daily at ${groom.at}  ${groom.enabled ? 'on' : 'off'}`,
     groom.enabled
-      ? `It runs every day at ${groom.at} and spends tokens each time. Turn it off with:  obk groom --bots ${bots} --off`
-      : `It is not running yet. Try it by hand, read what it gives you, then:  obk groom --bots ${bots} --on`,
+      ? `It runs every day at ${groom.at} and spends tokens each time. Turn it off with:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --off`
+      : `It is not running yet. Try it by hand, read what it gives you, then:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --on`,
   ];
 }
 
@@ -980,7 +1035,7 @@ function rosterLines(roster, bots) {
   }
 
   lines.push(roster.length === 0
-    ? `No bots yet. Make one:  obk bot create --bots ${bots} --name <name> --harness claude|codex`
+    ? `No bots yet. Make one:  ${shellWord(ownCli())} bot create --bots ${shellWord(bots)} --name <name> --harness claude|codex`
     : `${roster.length} bot${roster.length === 1 ? '' : 's'}. Your bots folder: ${bots}`);
   return lines;
 }
@@ -1047,9 +1102,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
@@ -1058,7 +1128,7 @@ 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) {
+function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], projects = [], found = [] }, summary) {
   const lines = [
     ...created.map((entry) => `created    ${entry}`),
     ...completed.map((entry) => `completed  ${entry}`),
@@ -1073,12 +1143,15 @@ function tabLines({ bots, created, completed, rules, skills, tabs, paused = [],
   for (const one of paused) {
     const what = one.session === undefined ? one.bot : `${one.bot} ${one.session}`;
     const back = one.session === undefined ? '' : ` --session ${one.session}`;
-    lines.push(`${'paused'.padEnd(9)}  ${what}  left closed. Bring it back:  obk unpause --bots ${bots} --bot ${one.bot}${back}`);
+    lines.push(`${'paused'.padEnd(9)}  ${what}  left closed. Bring it back:  ${shellWord(ownCli())} unpause --bots ${shellWord(bots)} --bot ${one.bot}${back}`);
   }
 
   // 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;
 }
 
@@ -1103,15 +1176,26 @@ function harnessLines(tab, bots) {
       ...how,
       '             the harness was typed in, and no session came up in the tab.',
       `             Look at it:  ${lookAt(tab.terminal)}`,
+      ...ANSWER_IT,
     ];
   }
 
+  // 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}`,
       `             Look at it:  ${lookAt(tab.terminal)}`,
+      ...ANSWER_IT,
     ];
 
   if (tab.promptSent === true) lines.push('             the start prompt was typed in.');

package/src/groom.js

@@ -22,6 +22,7 @@ import path from 'node:path';
 
 import { botDir, readBot, requireBotsFolder } from './bot.js';
 import { readBook, takeLock } from './book.js';
+import { ownCli, shellWord } from './launch.js';
 import { orca } from './orca.js';
 import { BOT_FATHER } from './up.js';
 
@@ -35,10 +36,11 @@ const AT = /^([01]\d|2[0-3]):([0-5]\d)$/;
 const prompt = (bots) =>
   'Run the daily grooming for this fleet, with the obk-grooming skill. Fix this '
   + 'run\'s end now and read what has happened since the last run\'s end up to it, '
-  + 'counting with obk usage --since <last end> --until <this end>, and write this '
+  + `counting with ${shellWord(ownCli())} usage --since <last end> --until <this end>, and write this `
   + 'end down for the next run. Work out what it cost with obk-finops, keep '
   + 'each bot\'s profile notes, and send one short report to Bot Father\'s '
-  + `management session. The bots folder is ${bots}.`;
+  + `management session. The kit here is ${shellWord(ownCli())}: run it wherever a skill says obk. `
+  + `The bots folder is ${bots}.`;
 
 /**
  * Say what the grooming is, and make it so when asked.
@@ -66,7 +68,7 @@ export function grooming(bots, { at, on } = {}) {
   const bot = readBot(home, BOT_FATHER);
   const book = readBook(home);
   if (book.orca.project === undefined) {
-    throw new Error(`${BOT_FATHER} has no Orca project yet, so there is nothing for the grooming to run in. Run obk up --bots ${bots} --bot ${BOT_FATHER} first.`);
+    throw new Error(`${BOT_FATHER} has no Orca project yet, so there is nothing for the grooming to run in. Run ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${BOT_FATHER} first.`);
   }
 
   // Looking and making are one turn. Orca will not stop two runs creating two