@assuredloop/orca-bot-kit 0.6.0 → 0.7.0

package/README.md

@@ -340,7 +340,7 @@ with why that one ended and when
 
 The book stays true to the harness through a hook `obk up` puts in the bot's own
 folder — `.claude/settings.json` or `.codex/hooks.json`, never your user-level
-settings ([ADR 0020](docs/adr/0020-kit-hooks-live-in-the-bot-folder.md)). Your own
+settings ([ADR 0022](docs/adr/0022-kit-hooks-live-in-the-bot-folder.md)). Your own
 settings in those files are kept. Codex asks you to trust a hooks file the first
 time it sees one; answer its question in the tab.
 
@@ -545,6 +545,7 @@ failing quietly.
 npm test                      # the whole suite, in a few minutes
 npm run test:system           # what the system tests would drive, and nothing else
 npm run test:system -- --yes  # drive them, on this machine, for real
+npm run test:system -- --yes test/system/groom.test.js  # only the ones you name
 npm run mutate                # the mutation audit, on what your branch changed
 ```
 
@@ -570,7 +571,9 @@ which Orca, which files, and what they will do to it — and then stops without
 driving any of it, answering non-zero so that a run which did not run them
 cannot be read as one that passed. `-- --yes` is how you say you meant it. When
 Orca is not answering, the command says which Orca it asked and skips, rather
-than report a kit that is not broken.
+than report a kit that is not broken. Name files after it to run only those;
+each must be one of the `*.test.js` files under `test/system/`, links followed,
+and a name that is not is refused before anything runs.
 
 `npm run mutate` runs [StrykerJS](https://stryker-mutator.io) over the
 JavaScript this branch changed against `main` — committed, still in the working

package/SETUP.md

@@ -102,8 +102,9 @@ Ask both in one message, then wait.
 
 **Where the bots folder goes.** An absolute path. It becomes a git repository of
 theirs holding every bot's configuration: charters, rules, session settings, the
-book of sessions. It holds none of the kit's code. They may push it somewhere
-later; the kit never commits for them.
+book of sessions. It holds none of the kit's code. The bots commit their own
+changes to it; the kit's commands never commit, and pushing it somewhere is
+theirs to decide.
 
 **Which harness Bot Father runs on**, `claude` or `codex`. There is no default
 and the kit will not guess. It is Bot Father's own harness only; each bot they

package/package.json

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

package/rules/commit.md

@@ -0,0 +1,18 @@
+---
+name: commit
+title: Commit your changes
+applies: all
+---
+
+Commit your own changes to the bots repo often, as each piece of work there is
+done: what you changed, in whatever folder it is, and what the kit wrote in
+your own bot's folder (its files there and your book of sessions). Stage each
+file by name and name them in the commit too (`git commit -- <files>`), so
+nothing another session staged goes in with yours. What no bot owns (init's
+files, the defaults, the user's rules and skill lists) is Bot Father's to
+commit. Commit yours even when the repo has no commit yet or holds files that
+are not yours; leave those to their owner.
+
+Committing is not pushing: pushing is the user's call. A clone in your work dir
+follows its own repo's rules. When a commit fails, for example on another
+session's index lock, try again, and say so if it still fails.

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

@@ -214,8 +214,12 @@ index load at every start. Codex's memories belong to the user and are shared
 by every Codex session, so a Codex bot cannot have its own; say so before
 turning them on for one. It is a hand edit, and say that you made it.
 
-After each change, commit what it changed in the bots folder; the kit never
-commits by itself.
+After each change, commit what it changed in the bots folder, naming each
+file when you stage it and again in the commit. Commit with it what no bot
+owns and nobody has committed yet: `init`'s files, `defaults.yaml`,
+`skills.yaml`, and the user's `rules/` and `skills/`. What it changed
+includes the folder of a bot it made or changed. The kit never commits by
+itself.
 
 Do the reversible part and stop at the line. Making a bot, adding a session
 and linking skills add things and are safe to run again; closing a tab,

package/skills/obk-fleet-review/SKILL.md

@@ -251,6 +251,7 @@ identifiers, counts and paths that only show the work; where evidence matters,
 say where it is.
 
 Say what you did not look at. Where you changed anything in the bots folder,
-commit it; the kit never commits by itself.
+commit it, naming each file when you stage it and again in the commit; the
+kit never commits by itself.
 
 Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-grooming/SKILL.md

@@ -63,7 +63,8 @@ them says so and reads less, not everything.
 The open findings are what stops the same thing being reported every day:
 before filing an issue or sending feedback, look there, and where it is already
 open, add to it rather than raising it again. Take a finding off when it is
-fixed or no longer true. Commit these once a day, at the end of the run.
+fixed or no longer true. Commit these at the end of each run, naming each
+file when you stage it and again in the commit.
 
 ## Keep the run bounded
 

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 0020), and a link would make the one the other without a word. So the
+ * ADR 0022), 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

@@ -414,7 +414,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 0020).
+ * health check finds later; a session disturbed is the user's work (ADR 0022).
  */
 async function record(bots, bot) {
   try {

package/src/health.js

@@ -25,8 +25,9 @@ import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, shellWord } from './launch.js';
-import { frontOfTab, orcaDefaultArgs, projects, tabs } from './orca.js';
+import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
+import { frontOfTab, orcaDefaultArgs, projects, tabs, wordsOfProcess } from './orca.js';
+import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
 import { settingsInUse } from './settings.js';
 import { skillsTrouble } from './skills.js';
@@ -215,8 +216,9 @@ const hooksOf = (bots, home, bot) => [...new Set(bot.sessions.map((session) => h
 /**
  * Each session of this bot running in a tab Orca has, with what it runs on set
  * beside what the bot asks for now, added to `sessions`; a finding for each
- * one that runs on something else (#271, #272); and a finding for each one
- * whose tab is open with its harness gone from it (#300).
+ * one that runs on something else (#271, #272), or whose harness the kit's
+ * launch line did not start (#318); and a finding for each one whose tab is
+ * open with its harness gone from it (#300).
  *
  * Two questions, each answered from where the answer is written. The settings
  * from the harness's own record of the conversation the session is in now,
@@ -270,8 +272,15 @@ function runningOn(bots, home, bot, book, handles, sessions) {
     if (running !== 'yes') continue;
 
     const off = Object.entries(settings).filter(([, one]) => one.state === 'mismatch');
-    if (off.length > 0) {
-      const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+    const parts = off.map(([name, one]) => `${name}: bot.yaml asks for ${one.configured}, and it runs on ${one.observed}`).join('; ');
+    if (startedByKit(front.pid, entry.tab) === false) {
+      // Orca brings its tabs back by itself after a restart or an update, with
+      // a bare resume and none of the kit's launch line (#318). What health can
+      // see may still match, by the harness's own defaults; the rest of what
+      // bot.yaml asks for is not on it either way.
+      const drift = off.length === 0 ? '' : ` ${parts}, as the harness's own record of its conversation ${conversation} says.`;
+      found.push(finding('session', entry.tab, `${bot.name}'s session ${session.name} was not started by the kit: the harness in its tab ${entry.tab} carries nothing of the kit's launch line, as when Orca brings its tabs back by itself after a restart or an update. So it runs on the harness's own defaults and whatever Orca added, not on what ${path.join(home, 'bot.yaml')} asks for.${drift} ${restart} starts it on bot.yaml.`, bot.name));
+    } else if (off.length > 0) {
       found.push(finding('session', file, `${bot.name}'s session ${session.name} does not run on what ${path.join(home, 'bot.yaml')} asks for. ${parts}. That is what the harness's own record of its conversation ${conversation} says. A session takes these when it starts, so if bot.yaml changed after it started, ${restart} starts it on them; if not, something else set them, such as a default of the harness's own or a change made inside the session.`, bot.name));
     }
 
@@ -289,6 +298,19 @@ function runningOn(bots, home, bot, book, handles, sessions) {
   return found;
 }
 
+/**
+ * Whether the kit's launch line started the process `pid` in the tab `tab`:
+ * true when it carries the marker the line puts there, false when it carries
+ * that tab's id and no marker, and undefined when its environment cannot be
+ * read (tech notes, section 1). Only a whole word counts: an argument, such as
+ * a start prompt, can hold anything.
+ */
+function startedByKit(pid, tab) {
+  const words = pid === undefined ? undefined : wordsOfProcess(pid);
+  if (words === undefined || !words.includes(`${TAB_ENV}=${tab}`)) return undefined;
+  return words.some((word) => new RegExp(`^${SHELL_ENV}=[0-9]+$`).test(word));
+}
+
 /**
  * What Orca has of this bot against what the book says it should have: a
  * session whose tab is gone, a conversation nobody claims, and a tab in the
@@ -357,7 +379,7 @@ function inOrca(bots, home, bot, setups, sessions) {
 /**
  * The conversations a harness has on record in this bot's folder that the book
  * does not name anywhere. The hook is how an id reaches the book, and when it
- * fails it fails quietly (ADR 0020), so this is where a stale book shows: the
+ * fails it fails quietly (ADR 0022), so this is where a stale book shows: the
  * harness's own record set beside it (ADR 0012).
  */
 function offTheBook(home, bot, book, onRecord) {

package/src/hooks.js

@@ -1,4 +1,4 @@
-// The kit's own hook, in the bot's folder and nowhere else (ADR 0020).
+// The kit's own hook, in the bot's folder and nowhere else (ADR 0022).
 //
 // Both harnesses read a hooks file out of the folder a session starts in, and
 // every session starts at its bot home, so the bot folder is where the kit's
@@ -35,7 +35,7 @@ const TIMEOUT = 10;
  * What the hook runs: the CLI that wrote it, by its own path, so the session
  * reports to the kit that set it up and not to whatever `obk` PATH finds in the
  * harness's shell (#220). `|| true` and a quiet stderr because a hook must never
- * disturb the session it fires in (ADR 0020): a kit that is not there, or a book
+ * disturb the session it fires in (ADR 0022): a kit that is not there, or a book
  * that cannot be written, leaves the session alone and the health check finds
  * the stale book later.
  */
@@ -124,7 +124,7 @@ export function hookTrouble(home, harness, { bots, bot }) {
 /**
  * What to say about a hooks file that a link takes out of the bot folder, or
  * undefined when it stays in. The kit writes its hook in the bot folder and
- * nowhere else (ADR 0020); through a link like that it would be writing the
+ * nowhere else (ADR 0022); through a link like that it would be writing the
  * user's own settings, so it does not, and says why.
  */
 function outside(home, file) {

package/src/orca.js

@@ -346,8 +346,8 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
 
 /**
  * Who holds the terminal of the pane `ptyId`: `{ front: 'shell' }`,
- * `{ front: 'program', command }` with the name of the process leading the
- * group in front, or `{ unreadable: <why> }`.
+ * `{ front: 'program', command, pid }` with the name and pid of the process
+ * leading the group in front, or `{ unreadable: <why> }`.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
  * gives that pid's terminal's foreground process group (ADR 0021).
@@ -374,7 +374,20 @@ function frontOf(ptyId) {
   const front = psLine(own.tpgid);
   if (front === undefined) return { unreadable: `ps could not read the process in front, pid ${own.tpgid}` };
   const shell = front.ppid === pane && path.basename(own.comm) === 'login';
-  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm) };
+  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm), pid: own.tpgid };
+}
+
+/**
+ * The process `pid` as `ps -E` gives it, word by word: its command, its
+ * arguments, then its environment as `NAME=value` words. Undefined when it
+ * cannot be read. macOS gives a same-user harness's environment this way (tech
+ * notes, section 1); nothing in it says where the arguments end, so a caller
+ * looks for one whole word it knows.
+ */
+export function wordsOfProcess(pid) {
+  const asked = spawnSync(psCli(), ['-E', '-ww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+  if (asked.error || asked.status !== 0) return undefined;
+  return asked.stdout.trim().split(/\s+/);
 }
 
 /** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, or undefined. */

package/src/record.js

@@ -166,22 +166,26 @@ function unclaimedFor(book, home, bot, tabId, id) {
 }
 
 /**
- * Whether the harness that ran this hook is the session's own — the one the kit
- * typed into the tab — rather than a harness started inside the session.
+ * Whether the harness that ran this hook is the session's own — the one the
+ * tab's shell started — rather than a harness started inside the session.
  *
  * Proved live on both harnesses (tech notes, sections 2 and 3): a hook's process
  * is the harness's own child, or the child of the shell the harness ran the hook
  * command through. Either way the harness itself is the process just above, and
- * the session's harness is the child of the shell named in the launch line. A
- * harness started inside the session sits further down a longer chain, under
- * whatever shell the agent ran it from, so it can never answer this.
+ * the session's harness is the child of the tab's shell. A harness started
+ * inside the session sits further down a longer chain, under whatever shell the
+ * agent ran it from, so it can never answer this.
+ *
+ * The launch line names the tab's shell. A tab Orca brought back by itself has
+ * no launch line (#318), and there the tab's shell is the one `login` started
+ * for the pane, which is where Orca's own resume puts the harness too (tech
+ * notes, section 1).
  *
  * Anything it cannot establish is a no: a report that cannot be shown to be the
  * session's own is not written down.
  */
 export function startedTheSession(shellPid, pid = process.pid) {
-  if (!/^[0-9]+$/.test(String(shellPid ?? ''))) return false;
-  const shell = Number(shellPid);
+  if (shellPid !== undefined && !/^[0-9]+$/.test(String(shellPid))) return false;
 
   const tree = processTree();
   if (tree === undefined) return false;
@@ -190,11 +194,21 @@ export function startedTheSession(shellPid, pid = process.pid) {
   const parent = mine === undefined ? undefined : tree.get(mine.ppid);
   if (parent === undefined) return false;
 
-  if (parent.ppid === shell) return true;
-  if (!isShell(parent.command)) return false;
+  if (shellPid !== undefined) {
+    const shell = Number(shellPid);
+    if (parent.ppid === shell) return true;
+    if (!isShell(parent.command)) return false;
+
+    const above = tree.get(parent.ppid);
+    return above !== undefined && above.ppid === shell;
+  }
 
-  const above = tree.get(parent.ppid);
-  return above !== undefined && above.ppid === shell;
+  // With no shell named, which process is the harness has to be settled first:
+  // the one above the shell the hook ran through, or the hook's own parent.
+  const harness = isShell(parent.command) ? tree.get(parent.ppid) : parent;
+  const shell = harness === undefined ? undefined : tree.get(harness.ppid);
+  const pane = shell === undefined ? undefined : tree.get(shell.ppid);
+  return pane !== undefined && path.basename(pane.command) === 'login';
 }
 
 /** Every process on the machine, by pid: who its parent is and what it runs. */

package/src/skills.js

@@ -292,7 +292,7 @@ export function unlinkSkills(home) {
  * user made, or one of the kit's that they have since repointed, is theirs.
  *
  * It is the kit's own file and lives beside the hook files it already keeps in
- * the bot folder (ADR 0020). A record that cannot be read is treated as an
+ * the bot folder (ADR 0022). A record that cannot be read is treated as an
  * empty one: the worst that follows is that the kit leaves alone something it
  * would otherwise have tidied up, which is the safe way round.
  */

package/src/up.js

@@ -94,7 +94,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
  *
  * Separate from the tabs because the order matters twice over. A session reads
  * its rules, its skills and its hooks as it comes up, so all three have to be
- * there before the tab is (PRD 6.6, ADR 0020) — and a restart closes a tab in
+ * there before the tab is (PRD 6.6, ADR 0022) — and a restart closes a tab in
  * between, so everything that can refuse must have refused before that. It
  * refuses by throwing, exactly as `up` always has; a bot it leaves out of
  * `running` is one whose sessions must not be started.
@@ -140,7 +140,7 @@ export function prepareBots(bots, names, onlySession) {
 
   // And the kit's hook goes into every bot folder before Orca is asked for
   // anything, for the same reason: a harness reads its hooks when it comes up,
-  // so one written later would miss the session it was written for (ADR 0020),
+  // so one written later would miss the session it was written for (ADR 0022),
   // and a bot folder the kit cannot write it into stops the run with nothing
   // opened anywhere. Only the harnesses a bot actually runs on; a bot with no
   // sessions gets none.