gcf-harness-aif-ext 0.9.0 → 0.9.2

package/README.md

@@ -33,7 +33,7 @@ This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-h
 ai-factory gcf-harness init    # per project: .claude/settings.json + .gitignore
 ```
 
-It is **per project**, not global — run it again in every game repository: it adds the readset-guard `PreToolUse` entry to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It also allows what an unattended `claude -p` run needs at least — `Edit`, `Write`, `Bash(git *)`, `Bash(ai-factory *)`, and the same two as `PowerShell(…)` rules, the tool the agent runs commands with on Windows — because print mode cannot ask and denies the rest; add your engine's tools yourself (for example `mcp__<editor-server>` for an editor driven over MCP). Commit `.claude/settings.json`: the rules apply to every Claude session in the project. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
+It is **per project**, not global — run it again in every game repository: it adds the readset-guard and implement-guard entries to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It also allows what an unattended `claude -p` run needs at least — `Edit`, `Write`, `Bash(git *)`, `Bash(ai-factory *)`, and the same two as `PowerShell(…)` rules, the tool the agent runs commands with on Windows — because print mode cannot ask and denies the rest; add your engine's tools yourself (for example `mcp__<editor-server>` for an editor driven over MCP). Commit `.claude/settings.json`: the rules apply to every Claude session in the project. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
 
 ## Upgrade
 
@@ -47,6 +47,18 @@ Updating keeps the hook entry valid — it points into the extension's install d
 
 0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
 
+0.9.2 holds `/gcf-run` to aif-implement. Run `ai-factory gcf-harness init` again after the update: it registers the new hook.
+- The implement guard: in a session that runs `/gcf-run`, a write to a code file is denied until the session invokes the aif-implement skill (gcf-run step 13), and so is a plan tick, which only aif-implement sets. Planning stays free: `gcf/`, `.ai-factory/`, `.gcf-session/` and any markdown file. After aif-implement every write is free, the fixes of a red DoD and of the review included. It works in the harness's runs and in an interactive `/gcf-run` alike, and touches no other session.
+- `/gcf-run` converges a plan when an improve pass finds nothing blocking: a wrong or missing behavior or task, a broken pillar invariant, a rule conflict, a task no check can prove. Polish (wording, splitting tasks, order) is applied, but no longer keeps the loop going. Before, a pass that changed any task asked for one more, and a fresh reviewer almost always changes something. The report row per pass gives the blocking and polish counts.
+- `/gcf-run` answers aif-plan's own questions (tests, logging, docs) itself, from the item, its DoD and the project's rules.
+- The run report marks an item whose session wrote code without aif-implement: `— code written outside aif-implement` on its line, `process` in `--json` and in its kept record. It reads the session's own events, its subagents' included, so it also covers a project without the guard registered. A write through Bash is seen by neither: the review of the diff is the check there.
+- Lessons (with core 0.7.10): after each agent session the run asks the same session, resumed, what got in its way - tools, rules, the framework, the project template - with the questions of `ai-factory gcf lessons prompt`. Its answers go to the inbox on main as lessons (`gcf lessons add`), and the board shows them on the card, in the drawer and in the inbox. The run passes `--no-lessons` to `/gcf-run`, so the agent carries no lessons instruction while it works. The turn follows a result, a handoff (before the fresh session), a timeout or an error; not a usage limit or a stop, and only for a `claude` agent with a session id. Another agent asks its lessons itself at the end of a run on main; in a worktree it records none. It takes up to 10 minutes; its cost goes on the item, and the report line says `, N lessons`. A failed lessons turn is logged and changes nothing else. A project that turns lessons off, or a core before 0.7.10, gets no turn and no flag.
+
+0.9.1 is a fix release:
+- A stopped session reads as `no result (stopped)`, and its kept record as `ended: stopped`: before, the kill's exit code (`agent exit 1` on Windows).
+- `gcf-harness stop <id>` never kills the run: a stop before the item's session starts (or between two sessions of a handoff) leaves `.gcf-session/runs/<id>.stop`, and that session is stopped as it starts. Before, a stop then killed the whole run with the other items of its batch. A run hung before its first session (in its worktree setup) is not stopped. On main, a stop marks the item too once the run has reached it. Known limit: a stop in the moment between a worktree run's claim of the item and its clearing of an old mark is lost.
+- A stop that comes while the session starts no longer misses it.
+
 0.9.0, to update together with core 0.7.6:
 - The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`.
 - A run loads the project's settings and MCP servers only (`--setting-sources project,local --strict-mcp-config --mcp-config .mcp.json`): the operator's plugins, hooks and claude.ai connectors stay out. So does `env` or `apiKeyHelper` in `~/.claude/settings.json`: an operator who logs in through them, not `claude login`, names the agent with `--agent`. The deny rules and the handoff guard come in `.gcf-session/runs/agent-settings.json` (`--settings`), so a worktree gets them without a commit.
@@ -77,11 +89,11 @@ To remove the extension:
 ai-factory extension remove gcf-harness-aif-ext
 ```
 
-Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry whose command ends in `# gcf-readset-guard` by hand, or every Read, Grep and Glob will report a hook error.
+Removal does not touch `.claude/settings.json`: delete the entries whose command ends in `# gcf-readset-guard` or `# gcf-implement-guard` (under `PreToolUse` and `UserPromptSubmit`) by hand, or the tools they match will report a hook error.
 
 ## What it adds
 
-**`/gcf-run <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass that changes no task ends the loop. A plan still changing after `plan_passes` passes, or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is `ai-factory gcf verify <id>` — the gate's checks, the item's `live:` delta, and the project's `dod.build` and `dod.test` commands from `gcf/config.yml` — plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
+**`/gcf-run <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass with no blocking finding (a wrong or missing behavior or task, a broken pillar invariant, a rule conflict, an unprovable task) ends the loop. A blocking finding left after `plan_passes` passes (3 by default), or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is `ai-factory gcf verify <id>` — the gate's checks, the item's `live:` delta, and the project's `dod.build` and `dod.test` commands from `gcf/config.yml` — plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
 
 **`ai-factory gcf-harness gate <item-id…>`** — the `/gcf-run` gate as code. It reads one `gcf audit --json` report and exits 1 with a one-line reason when the items may not go: a core older than 0.4.0, a `schema:` other than 1 in `gcf/config.yml`, an id with no work item, a feature (run its children; the feature closes when they are finished), an item that is not `ready`, an unplayed dependency, no WIP room for the batch (items awaiting a verdict + the batch's `gate: verdict` items over `wip_built_limit`), or two items of the batch touching the same system unless both say `parallel: ok`. The tune limit is not a gate rule: `verdict tune` itself refuses at the limit, and an item tuned up to it still gets its last build. The skill runs it and stops on a non-zero exit — no model compares the numbers.
 
@@ -91,6 +103,8 @@ Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry wh
 
 **readset-guard** — a `PreToolUse` hook on Read/Grep/Glob. While a run manifest exists at `.gcf-session/readset.json`, a path inside `gcf/` that is not in the readset is denied, and so is a Grep from the project root (no `path`, or a `path` above `gcf/`) unless its `glob` starts with a literal directory other than `gcf` (`src/**`, not `**/*.md`), because such a content search would read the whole tree past the gate. Glob and Greps scoped to the game code are never restricted. No manifest means no restriction: manual work is never gated. An honest limit — `cat` through Bash still bypasses it. This is a discipline tool, not a security perimeter.
 
+**implement-guard** — a `UserPromptSubmit` and `PreToolUse` hook (Skill, the write tools, Bash and PowerShell). A session that starts `/gcf-run` (typed, passed to `claude -p`, or invoked as a skill) gets a state in `.gcf-session/guard/<session_id>.json`; until it invokes the aif-implement skill, Edit, Write, MultiEdit and NotebookEdit are denied outside `gcf/`, `.ai-factory/`, `.gcf-session/` and markdown, and a markdown write that adds a `- [x]` tick is denied too. Any other session is never touched, and an error lets the call through. The move that ends the item (`gcf block`, `submit` or `close`, through Bash or PowerShell) lets the session go, so the operator's own edits after a blocked run are free again. A plugin's skill (`<plugin>:aif-implement`) counts too. Limits: the flag is per session, so in a batch the first item's aif-implement frees the rest; a write through Bash is not seen, by the run report either.
+
 ## Docs
 
 [Harness-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/Harness-PRD.md) is the spec: pipeline stages, gates, execution surfaces, the guard's contract.

package/commands/activity.js

@@ -109,10 +109,13 @@ function limitIn(text, whole = true) {
  * @param {string} line
  * The main agent's turns also carry `context`, the tokens its window holds (a subagent's turns,
  * `parent_tool_use_id` set, fill a window of their own); the init names the `model`, the result
- * the `windows` of its models, and a compaction says `compacted`.
+ * the `windows` of its models, and a compaction says `compacted`. A turn's tool calls give
+ * `implement` (the aif-implement skill) and `writes` (the files written, by call id); a tool
+ * result gives `failed`, the calls that wrote nothing.
  * @returns {{lines: string[], cost?: Cost, session_id?: string, limit?: {resets: string | null},
  *   context?: number, turn?: string, model?: string, windows?: Record<string, number>,
- *   compacted?: boolean}}
+ *   compacted?: boolean, implement?: boolean, writes?: {id: string, file: string}[],
+ *   failed?: string[]}}
  */
 export function activity(line, now = new Date()) {
   let e;
@@ -128,12 +131,18 @@ export function activity(line, now = new Date()) {
   const content = Array.isArray(e.message?.content) ? e.message.content : [];
   if (e.type === 'system') return system(e, at);
   if (e.type === 'assistant') return { ...said(content, at), ...contextOf(e) };
-  if (e.type === 'user')
+  if (e.type === 'user') {
+    const errors = content.filter((b) => b.type === 'tool_result' && b.is_error);
+
     return {
-      lines: content
-        .filter((b) => b.type === 'tool_result' && b.is_error)
-        .map((b) => `${at} tool error: ${cut(firstLines(resultText(b.content), 1), 300)}`),
+      lines: errors.map(
+        (b) => `${at} tool error: ${cut(firstLines(resultText(b.content), 1), 300)}`,
+      ),
+      // A refused or failed call wrote nothing: its write does not count.
+      ...(errors.length ? { failed: errors.map((b) => String(b.tool_use_id)) } : {}),
     };
+  }
+
   if (e.type === 'result') return ended(e, at);
 
   return { lines: [] };
@@ -167,12 +176,32 @@ function contextOf(e) {
   return { context: tokens, ...(e.message.id ? { turn: String(e.message.id) } : {}) };
 }
 
+const WRITES = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+
+/**
+ * What a turn's tool calls tell of gcf-run step 13: `implement` when one invokes the aif-implement
+ * skill, `writes` the files its write tools name. A subagent's turns count too.
+ */
+function steps(uses) {
+  const writes = uses
+    .filter((u) => WRITES.includes(u.name))
+    .map((u) => ({ id: String(u.id), file: u.input?.file_path ?? u.input?.notebook_path }))
+    .filter((w) => typeof w.file === 'string');
+  // A plugin's skill comes as <plugin>:aif-implement.
+  const implement = uses.some(
+    (u) => u.name === 'Skill' && /(^|:)aif-implement$/.test(String(u.input?.skill ?? '')),
+  );
+
+  return { ...(implement ? { implement } : {}), ...(writes.length ? { writes } : {}) };
+}
+
 /** An assistant turn: its tool calls and its text, which may be the usage-limit message. */
 function said(content, at) {
   const texts = content.filter((b) => b.type === 'text').map((b) => b.text);
 
   return {
     ...(texts.map((t) => limitIn(t)).find((l) => l.limit) ?? {}),
+    ...steps(content.filter((b) => b.type === 'tool_use')),
     lines: content.flatMap((b) => {
       if (b.type === 'tool_use') return [`${at} ${toolLine(b)}`];
       const text = b.type === 'text' ? cut(firstLines(b.text, 2), 300) : '';
@@ -192,11 +221,13 @@ function ended(e, at) {
 
   // The window of each model the session used: its subagents may run on another.
   const windows = Object.entries(e.modelUsage ?? {})
-    .map(([m, u]) => [m, Number(u?.contextWindow)])
+    .map(([m, u]) => /** @type {[string, number]} */ ([m, Number(u?.contextWindow)]))
     .filter(([, n]) => n > 0);
 
   return {
     lines: [...text, `${at} ${summary(e, cost, Boolean(limit.limit))}`],
+    // The reply itself: a lessons turn answers with its JSON here.
+    ...(typeof e.result === 'string' ? { result: e.result } : {}),
     cost,
     ...limit,
     ...(windows.length ? { windows: Object.fromEntries(windows) } : {}),

package/commands/harness.js

@@ -1,4 +1,4 @@
-// `ai-factory gcf-harness init` — registers the readset-guard PreToolUse hook in the
+// `ai-factory gcf-harness init` — registers the readset-guard and implement-guard hooks in the
 // project's .claude/settings.json (the AIF manifest cannot install Claude Code hooks —
 // same decision as gcf hooks-install for git hooks). Idempotent by marker comment. It also
 // allows what a headless agent run needs (AGENT_ALLOW).
@@ -11,7 +11,6 @@ import { fileURLToPath } from 'node:url';
 import { run, cliCore, DEFAULT_AGENT, DEFAULT_TIMEOUT_MIN, MAIN_RUN, stopOf } from './run.js';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
-const MARKER = 'gcf-readset-guard';
 const SCHEMA = 1; // the only gcf/config.yml schema this harness drives
 const SESSION_RULE = /^(\/|\*\*\/)?\.gcf-session\/?$/;
 
@@ -185,20 +184,62 @@ async function readSettings(settingsFile) {
   }
 }
 
+// The hooks `init` registers: the file, the event, its matcher (none for a prompt event).
+/** @type {Array<{name: string, event: string, matcher?: string}>} */
+const GUARDS = [
+  { name: 'readset-guard', event: 'PreToolUse', matcher: 'Read|Grep|Glob' },
+  {
+    name: 'implement-guard',
+    event: 'PreToolUse',
+    // Bash and PowerShell: a `gcf block|submit|close` ends the run, and the guard lets go.
+    matcher: 'Skill|Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell',
+  },
+  { name: 'implement-guard', event: 'UserPromptSubmit' },
+];
+
+const hooksOf = (e) => (Array.isArray(e?.hooks) ? e.hooks : []);
+
+/**
+ * A newer version may watch more tools. An entry of ours alone takes the new matcher; one we
+ * share with the operator's own hooks keeps theirs, and ours moves to an entry of its own, at
+ * most one: a hook copied into several entries, or one already moved, makes no second. Returns
+ * how many entries changed.
+ */
+function widen(list, matcher, ours, command) {
+  const before = JSON.stringify(list);
+  const holding = list.filter((x) => hooksOf(x).some((h) => ours.includes(h)));
+  const alone = (e) => e.hooks.every((h) => ours.includes(h));
+  // Ours alone, the right matcher first; else a new one. It keeps one hook of ours, with the
+  // operator's own settings on it (a timeout).
+  let own = holding.find((e) => e.matcher === matcher && alone(e)) ?? holding.find(alone);
+  if (own) own.hooks = own.hooks.slice(0, 1);
+  else list.push((own = { hooks: [{ ...ours[0], command }] }));
+  own.matcher = matcher;
+  for (const e of holding) if (e !== own) e.hooks = e.hooks.filter((h) => !ours.includes(h));
+  // An entry that held only ours is empty now: it goes.
+  for (const e of holding) if (e !== own && !e.hooks.length) list.splice(list.indexOf(e), 1);
+
+  return JSON.stringify(list) === before ? 0 : 1;
+}
+
 /**
- * Adds the guard entry, or repoints an existing one: a moved or cloned project keeps the old
- * absolute path under the marker, and the registered hook would keep launching a missing file.
- * Returns what happened, or null when the settings already hold the right command.
+ * Adds the guard entry of `event`, or repoints an existing one: a moved or cloned project keeps
+ * the old absolute path under the marker, and the registered hook would keep launching a missing
+ * file. Returns what happened, or null when the settings already hold the right command.
+ * @param {Record<string, any>} settings
+ * @param {{event: string, matcher?: string}} guard
+ * @param {string} marker
+ * @param {string} command
  */
-function registerGuard(settings, command) {
+function registerGuard(settings, { event, matcher }, marker, command) {
   settings.hooks ??= {};
-  settings.hooks.PreToolUse ??= [];
-  const ours = settings.hooks.PreToolUse.flatMap((e) => e?.hooks ?? []).filter(
-    (h) => typeof h?.command === 'string' && h.command.includes(MARKER),
-  );
+  settings.hooks[event] ??= [];
+  const ours = settings.hooks[event]
+    .flatMap(hooksOf)
+    .filter((h) => typeof h?.command === 'string' && h.command.includes(marker));
   if (!ours.length) {
-    settings.hooks.PreToolUse.push({
-      matcher: 'Read|Grep|Glob',
+    settings.hooks[event].push({
+      ...(matcher ? { matcher } : {}),
       hooks: [{ type: 'command', command }],
     });
 
@@ -207,8 +248,9 @@ function registerGuard(settings, command) {
 
   const stale = ours.filter((h) => h.command !== command);
   for (const h of stale) h.command = command;
+  const widened = matcher ? widen(settings.hooks[event], matcher, ours, command) : 0;
 
-  return stale.length ? 'repointed' : null;
+  return stale.length || widened ? 'repointed' : null;
 }
 
 // What a headless `claude -p` run needs at least: it cannot ask, so anything not allowed is
@@ -258,18 +300,22 @@ async function init(program) {
 
   const projectDir = process.cwd();
   const settingsFile = path.join(projectDir, '.claude', 'settings.json');
-  const guard = path.join(EXT_ROOT, 'hooks', 'readset-guard.js').replaceAll('\\', '/');
   const settings = await readSettings(settingsFile);
-  const change = registerGuard(settings, `node "${guard}" # ${MARKER}`);
+  const changes = GUARDS.map((g) => {
+    const file = path.join(EXT_ROOT, 'hooks', `${g.name}.js`).replaceAll('\\', '/');
+    const marker = `gcf-${g.name}`;
+    const change = registerGuard(settings, g, marker, `node "${file}" # ${marker}`);
+
+    return change && `${g.name} (${g.event}) ${change}`;
+  }).filter(Boolean);
   const allowed = allowAgent(settings);
-  if (change || allowed.length) {
+  if (changes.length || allowed.length) {
     await mkdir(path.dirname(settingsFile), { recursive: true });
     await writeFile(settingsFile, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
   }
 
-  console.log(
-    change ? `readset-guard ${change} → ${settingsFile}` : 'readset-guard already registered',
-  );
+  for (const c of changes) console.log(`${c} → ${settingsFile}`);
+  if (!changes.length) console.log('readset-guard and implement-guard already registered');
   if (allowed.length) console.log(`agent runs may now: ${allowed.join(', ')}`);
 
   await ignoreSession(projectDir);
@@ -291,7 +337,8 @@ export function register(program) {
   harness
     .command('init')
     .description(
-      'Initialize the harness in this project: readset-guard hook, agent permissions (idempotent)',
+      'Initialize the harness in this project: readset and implement guards, agent permissions ' +
+        '(idempotent)',
     )
     .action(() => init(program));
 
@@ -329,7 +376,7 @@ export function register(program) {
     });
   harness
     .command('stop <id>')
-    .description('Stop the run that drives an item, with every session it started; it stays ready')
+    .description('Stop the session that works an item; the run goes on, the item stays ready')
     .action((id) => console.log(stopRun(process.cwd(), id)));
 }
 
@@ -360,12 +407,12 @@ function lockOf(file) {
   }
 }
 
-/** Kill a process and everything under it: a tree on Windows, its own group elsewhere. */
-function killTree(pid, group) {
+/** Kill a session and everything under it: a tree on Windows, its own group elsewhere. */
+function killTree(pid) {
   if (WIN) spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
   else {
     try {
-      process.kill(group ? -pid : pid, group ? 'SIGKILL' : 'SIGTERM');
+      process.kill(-pid, 'SIGKILL');
     } catch {
       // Gone already.
     }
@@ -375,37 +422,44 @@ function killTree(pid, group) {
 /**
  * Stop the session that works `id`: the one its own lock names (worktree mode), or the main
  * checkout's run when that run works this very item (main mode). Only that session goes: the
- * run records it as no result and goes on with the rest. A run that has not started a session
- * yet goes down whole. The item stays ready and its work in progress is kept.
+ * run records it as stopped and goes on with the rest. The item stays ready and its work in
+ * progress is kept.
  */
 export function stopRun(projectDir, id, core = cliCore(projectDir)) {
   const runs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
-  const main = lockOf(path.join(runs, `${MAIN_RUN}.lock`));
-  const lock = lockOf(path.join(runs, `${id}.lock`)) ?? (main?.item === id ? main : null);
-  // Between two sessions of the item (a context handoff) the lock names none: the mark keeps
-  // the run from starting the next one.
-  if (lock?.item === id)
-    writeFileSync(
-      stopOf(runs, id),
-      `${Date.now()}
-`,
-    );
-  if (lock && lock.session && alive(lock.session)) killTree(lock.session, true);
-  else if (lock && lock.item !== id) killTree(lock.run, false);
+  const lockFor = () => {
+    const main = lockOf(path.join(runs, `${MAIN_RUN}.lock`));
+
+    return lockOf(path.join(runs, `${id}.lock`)) ?? (main?.item === id ? main : null);
+  };
+
+  // The mark says the session ended by a stop, and stops the next one as it starts: the lock
+  // names none before the item's first session, or between two of a handoff. Read again after
+  // the mark: a session that started meanwhile did not see it.
+  const lock = lockFor();
+  if (lock) writeFileSync(stopOf(runs, id), `${Date.now()}\n`);
+  const session = lock && lockFor()?.session;
+  if (session && alive(session)) killTree(session);
   core(['release', id]);
 
   return lock ? `stopped the run of ${id}; it stays ready` : `no run drives ${id}`;
 }
 
+/**
+ * An item's line of the run report: its result, why, a skipped step of the process, and the
+ * lessons its sessions left in the inbox.
+ */
+export const itemLine = (i) =>
+  [`${i.id}: ${i.result}`, i.reason ?? i.conflict ?? i.error ?? i.skipped, i.process]
+    .filter(Boolean)
+    .join(' — ') + (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
+
 /** The run report a human reads, then the playtest sheet of what now waits for play. */
 function printRun(r) {
   for (const o of r.orphans)
     console.log(`orphan ${o.id}: ${o.move ?? o.conflict ?? o.error ?? o.skipped}`);
   if (r.gate) console.error(`gcf gate: ${r.gate}`);
-  for (const i of r.items) {
-    const why = i.reason ?? i.conflict ?? i.error ?? i.skipped;
-    console.log(`${i.id}: ${i.result}${why ? ` — ${why}` : ''}`);
-  }
+  for (const i of r.items) console.log(itemLine(i));
 
   if (!r.gate) console.log(`\n${cliCore(process.cwd())(['playtest', 'session']).out.trim()}`);
 }