@xhulz/nina 0.36.0 → 0.38.0

package/src/gate.mjs

@@ -9,15 +9,15 @@
  * the verdict a dispatch answers may not be on disk when the dispatch is about to go out, and the file
  * is mostly replay: a session resumed over a bridge rewrites its history, three quarters of the bytes
  * in the one measured. The gate keeps its own ledger instead — one small file per session, metadata
- * only, with the ids a report gave its issues as the one thing a model wrote — written by the hooks
+ * only, with the ids a report gave its issues and the name an agent was launched with as the only things a
+ * model wrote — written by the hooks
  * that see each fact as it happens:
  *
  *   PostToolUse on SubagentHandback   the report a stage handed back, verbatim — its verdict
  *   SubagentStop                      the same, for a stage that wrote its report as its last message
  *   PreToolUse / PostToolUse on Agent, Task, SendMessage
  *                                     a dispatch launched, and the agent it launched
- *   UserPromptSubmit (human text only), an AskUserQuestion answer
- *                                     the owner spoke, and every count starts over
+ *   UserPromptSubmit (human text only) the owner spoke, and every open loop gets one round more
  *   PreToolUse on Agent, Task, SendMessage
  *                                     the decision: let it through, or send the round past the cap to
  *                                     the owner to confirm
@@ -41,7 +41,13 @@
  * belongs to that round; a pass cancels a rejection only if a fix went out between the two — a later
  * review that saw the fix — and closes the loop only if it began after the latest fix with no rejection
  * running beside it; a pass from the stage the source hands its work on to (qa, after the reviewer)
- * closes the source's loops; and the owner speaking empties everything. Guessed verdicts never count.
+ * closes the source's loops; and the owner speaking gives every loop still open one round more than its cap —
+ * it used to empty everything, and since the owner speaks every few minutes no loop ever reached a cap: over
+ * two days of one project, sixty resets and not one question. Guessed verdicts never count.
+ *
+ * A loop is its source's verdict, whichever stage the orchestrator sends the fix to: a rejection routed to
+ * the architect one round and to the implementer the next was counted once on each edge, and went round
+ * twice its cap before anything asked. Each edge's own cap still decides the round that goes to it.
  *
  * It fails open, and it only acts where the project pins a version that ships it. Any error lets the
  * call through and is logged where `nina gate --selftest`, a detector every project runs, reports it: a
@@ -53,7 +59,8 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { TERMINALS, declaredTokens, parseGraph } from './graph.mjs';
 import { gateDir, slugFor } from './paths.mjs';
-import { declaredIssues, isLoopBack } from './transcripts.mjs';
+import { declaredIssues, isLoopBack, saidToAgent } from './transcripts.mjs';
+import { lessonIndex } from './lessons.mjs';
 
 /** The package this runs from: its releases say whether a pinned version ships the gate at all. */
 const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -266,7 +273,9 @@ function append(path, entry) {
  *   too, the round's number is its most-repeated issue's instead — one more than the rounds that issue
  *   was in since then — and the edge's own number is kept beside it, against a ceiling of twice the cap.
  *   A late sibling's issues are counted in the round it belongs to;
- * - a pass from the stage the source hands passing work on to closes the source's loops outright.
+ * - a pass from the stage the source hands passing work on to closes the source's loops outright;
+ * - the owner speaking gives each loop still open one round more — its `grace` — and closes nothing. A
+ *   model's own question to the owner (`AskUserQuestion`) is not the owner speaking.
  *
  * @param {object[]} entries - The ledger, oldest first.
  * @param {ReturnType<typeof loopEdges>} loops - The capped loop-back edges.
@@ -307,6 +316,8 @@ export function replay(entries, loops, forward = new Map()) {
    * @type {Map<string, {n: number, agents?: string[], at?: number, blind?: boolean, edge?: number}>}
    */
   const streak = new Map();
+  /** `${source}|${token}` → the rounds the owner has given the loop past its cap, by speaking while it was open. */
+  const grace = new Map();
   /** Where each source's latest round went out: a pass must begin after it to say the fix passed. */
   const lastFix = new Map();
   /** Completions a dispatch already acted on: a late copy of one is not new. */
@@ -315,7 +326,7 @@ export function replay(entries, loops, forward = new Map()) {
   const reportedAt = new Map();
   const made = [];
   const close = (source) => {
-    for (const key of [...streak.keys()]) if (key.startsWith(`${source}|`)) streak.delete(key);
+    for (const map of [streak, grace]) for (const key of [...map.keys()]) if (key.startsWith(`${source}|`)) map.delete(key);
   };
 
   const effect = (to, at) => {
@@ -329,7 +340,7 @@ export function replay(entries, loops, forward = new Map()) {
       const closes = passes.some((p) => p.launch > (lastFix.get(source) ?? -1) && !live.some((v) => v.launch < p.at));
       const routed = live.filter((v) => byToken.get(v.verdict)?.has(to));
       const fresh = routed.filter((v) => {
-        const last = streak.get(`${source}|${to}|${v.verdict}`);
+        const last = streak.get(`${source}|${v.verdict}`);
         return closes || !last || v.launch > last.at;
       });
       // A late sibling belongs to the round it was running in, so its issues do too: each is counted in
@@ -338,7 +349,7 @@ export function replay(entries, loops, forward = new Map()) {
       const adopted = new Map();
       const blinded = new Set();
       for (const v of routed.filter((r) => !fresh.includes(r))) {
-        const key = `${source}|${to}|${v.verdict}`;
+        const key = `${source}|${v.verdict}`;
         const edge = streak.get(key);
         if (!edge) continue;
         if (!(v.issues?.length > 0)) blinded.add(key);
@@ -349,21 +360,22 @@ export function replay(entries, loops, forward = new Map()) {
       }
       if (fresh.length > 0) {
         const token = fresh.at(-1).verdict;
-        const key = `${source}|${to}|${token}`;
-        const max = byToken.get(token).get(to);
+        const key = `${source}|${token}`;
+        const given = grace.get(key) ?? 0;
+        const max = byToken.get(token).get(to) + given;
         const before = closes ? { n: 0, agents: [] } : (streak.get(key) ?? { n: 0, agents: [] });
         const agents = [...new Set([...(before.agents ?? []), ...fresh.map((v) => v.agent)])];
         // Counted by issue only while every round since the loop last closed named its issues: a round
         // that named nothing advanced no issue's count, so from then on only the edge's count is whole.
         const named = !before.blind && !blinded.has(key) && fresh.every((v) => v.issues?.length > 0);
-        const round = { key, source, target: to, token, round: before.n + 1, max, edgeRound: before.n + 1, ceiling: max, blind: !named, agents, at };
+        const round = { key, source, target: to, token, round: before.n + 1, max, edgeRound: before.n + 1, ceiling: max, blind: !named, agents, at, given };
         if (named) {
           const issues = [...new Set(fresh.flatMap((v) => v.issues))].map((id) => ({
             id,
             round: (closes ? 0 : ((adopted.get(`${key}|${id}`) ?? streak.get(`${key}|${id}`))?.n ?? 0)) + 1,
           }));
           const worst = issues.reduce((a, b) => (b.round > a.round ? b : a));
-          Object.assign(round, { round: worst.round, issue: worst.id, issues, ceiling: max * EDGE_CEILING });
+          Object.assign(round, { round: worst.round, issue: worst.id, issues, ceiling: (max - given) * EDGE_CEILING + given });
         }
         rounds.push(round);
       }
@@ -374,9 +386,9 @@ export function replay(entries, loops, forward = new Map()) {
 
   entries.forEach((e, i) => {
     if (e.k === 'reset') {
-      pending.clear();
-      streak.clear();
-      lastFix.clear();
+      // Ledgers written before the model's own questions stopped counting as the owner speaking hold those too.
+      if (e.why === 'ask') return;
+      for (const key of streak.keys()) if (key.split('|').length === 2) grace.set(key, (grace.get(key) ?? 0) + 1);
       return;
     }
     if (e.k === 'verdict' && e.declared && e.agent) {
@@ -463,25 +475,25 @@ function withoutRef(to) {
 }
 
 /**
- * Who a SendMessage goes to: an agent id the ledger has seen, or — since the tool tells the model to
- * prefer names — a name, which in this pipeline is the stage's own, with or without the ` [ref]` a
- * listing appends.
+ * Who a SendMessage goes to: an agent id the ledger has seen, or a name, with or without the ` [ref]` a
+ * listing appends. A name is the one an agent was launched with, or — launched with none — its stage's; and,
+ * as Claude Code resolves it, the latest agent to go by it is the one reached. A fixer launched as `fixer` and
+ * resumed by that name was seen only after it went out, so no resume of it was ever asked about.
  *
  * @returns {{agent: string|null, role: string|null}}
  */
 function recipient(entries, project, to) {
-  const agent = withoutRef(to) || null;
-  const role = roleOf(entries, agent) ?? (agent && project.graph.stages.has(agent) ? agent : null);
+  const said = withoutRef(to) || null;
+  const goesBy = (e) => e.name ?? (e.via === 'SendMessage' ? null : e.role);
+  const named = said ? entries.findLast((e) => e.k === 'dispatch' && e.agent && goesBy(e) === said) : null;
+  const agent = named?.agent ?? said;
+  const role = roleOf(entries, agent) ?? (said && project.graph.stages.has(said) ? said : null);
   return { agent, role };
 }
 
-/** Where this agent's current completion starts in the ledger: after its latest launch. */
+/** Where this agent's current completion starts in the ledger: after its latest launch. A `pre` names no agent. */
 function currentLaunch(entries, agent) {
-  let at = -1;
-  entries.forEach((e, i) => {
-    if ((e.k === 'dispatch' || e.k === 'pre') && e.agent === agent) at = i;
-  });
-  return at;
+  return entries.findLastIndex((e) => e.k === 'dispatch' && e.agent === agent);
 }
 
 /**
@@ -513,8 +525,10 @@ function handbackIn(path) {
       continue;
     }
     const content = row?.message?.content;
-    // A new prompt — the resume of a finished agent — starts a new completion; its handback is later.
-    if (row?.type === 'user' && (typeof content === 'string' || (Array.isArray(content) && content.some((b) => b?.type === 'text')))) message = null;
+    // A new prompt — the resume of a finished agent — starts a new completion; its handback is later. What
+    // counts as one is the parser's: a reminder Claude Code slips in after the handback is not, and read as one
+    // it threw away the handback the stop was looking for.
+    if (saidToAgent(row)) message = null;
     if (!Array.isArray(content)) continue;
     for (const block of content) {
       if (block?.type === 'tool_use' && block.name === 'SubagentHandback' && typeof block.input?.message === 'string') message = block.input.message;
@@ -566,10 +580,6 @@ function onPost(input, project, path, at) {
   }
   // A dispatch made inside a subagent is not the pipeline's: its stages are dispatched by the orchestrator.
   if (input.agent_id) return null;
-  if (tool === 'AskUserQuestion') {
-    append(path, { k: 'reset', at, why: 'ask' });
-    return null;
-  }
   if (!DISPATCH.has(tool)) return null;
   const response = input.tool_response && typeof input.tool_response === 'object' ? input.tool_response : {};
   let role;
@@ -584,7 +594,9 @@ function onPost(input, project, path, at) {
   }
   if (!role || !project.graph.stages.has(role)) return null;
   const resumed = tool === 'SendMessage' ? Boolean(response.resumedAgentId) : undefined;
-  append(path, { k: 'dispatch', at, role, agent, via: tool, id: input.tool_use_id ?? null, ...(resumed === undefined ? {} : { resumed }) });
+  // The name an agent was launched with, if any: a later SendMessage may reach it by that name alone.
+  const name = tool !== 'SendMessage' && typeof input.tool_input?.name === 'string' ? input.tool_input.name.slice(0, 80) : null;
+  append(path, { k: 'dispatch', at, role, agent, via: tool, id: input.tool_use_id ?? null, ...(name ? { name } : {}), ...(resumed === undefined ? {} : { resumed }) });
   return null;
 }
 
@@ -599,9 +611,10 @@ const excess = (r) => Math.max(r.round - r.max, r.edgeRound - r.ceiling);
 function confirmation(r) {
   const from = r.agents.length > 0 ? ` The rounds so far came from ${r.agents.join(', ')}.` : '';
   const edge = `${r.source} → ${r.target} (${r.token})`;
-  let why = `this would be round ${r.round} on ${edge}, and .claude/graph.md caps that loop at ${r.max}.`;
+  const cap = r.given ? `${r.max - r.given}, and your ${r.given} repl${r.given === 1 ? 'y' : 'ies'} since it opened gave it ${r.given} more` : `${r.max}`;
+  let why = `this would be round ${r.round} on ${edge}, and .claude/graph.md caps that loop at ${cap}.`;
   if (r.issue && r.round > r.max) {
-    why = `this would be round ${r.round} of the issue \`${r.issue}\` on ${edge}, and .claude/graph.md caps that loop at ${r.max}.`;
+    why = `this would be round ${r.round} of the issue \`${r.issue}\` on ${edge}, and .claude/graph.md caps that loop at ${cap}.`;
   } else if (r.issue) {
     why =
       `this would be round ${r.edgeRound} on ${edge} with no approval between them. No issue has passed the cap of ${r.max}, ` +
@@ -706,6 +719,15 @@ export function handle(input, { root, now = new Date(), pkg = PACKAGE }) {
         return null;
       case 'SubagentStop':
         return onStop(input, project, path, at);
+      case 'SubagentStart': {
+        // Not the loop's business, but the one hook every stage passes through as it begins: its lessons. Claude
+        // Code reads `additionalContext` from this event's `hookSpecificOutput` into the subagent's context as it
+        // starts — its hook schema and handler say so in 2.1.283, and the handler in 2.1.158 — though the help text
+        // it prints for a malformed hook output does not list the event.
+        const role = input.agent_type;
+        const text = role && project.graph.stages.has(role) ? lessonIndex(root, role) : null;
+        return text ? { hookSpecificOutput: { hookEventName: 'SubagentStart', additionalContext: text } } : null;
+      }
       case 'PostToolUse':
         return onPost(input, project, path, at);
       case 'PreToolUse':

package/src/graph.mjs

@@ -158,8 +158,44 @@ export function validateGraph(graph, specs, roles = new Set()) {
     if (isLoopBack(e.token) && !TERMINALS.has(e.to) && e.max === null) {
       problems.push(`graph.md:${e.line}: loop-back \`${e.from}\` → \`${e.to}\` has no cap — add "· max N"`);
     }
+    // A cap of none sends every round to the owner: the edge is one to `human`, said another way.
+    if (e.max !== null && e.max < 1) problems.push(`graph.md:${e.line}: \`${e.from}\` → \`${e.to}\` is capped at ${e.max} — a cap is one round or more`);
+    if (TERMINALS.has(e.from)) problems.push(`graph.md:${e.line}: an edge leaves \`${e.from}\`, where work ends`);
   }
 
+  // The shape of the whole. Each of these held in every graph composed so far and nothing checked it: a
+  // cycle through verdicts that pass work on has no cap and never ends; a stage no edge touches is never
+  // dispatched; and one from which no chain of edges reaches `done` or `human` is where work stops unseen.
+  const forward = new Map();
+  for (const e of edges) if (!isLoopBack(e.token) && stages.has(e.from) && stages.has(e.to)) forward.set(e.from, [...(forward.get(e.from) ?? []), e.to]);
+  const state = new Map();
+  const cycle = (stage, path) => {
+    state.set(stage, 'open');
+    for (const next of forward.get(stage) ?? []) {
+      if (state.get(next) === 'open') return [...path.slice(path.indexOf(next)), next];
+      if (!state.has(next)) {
+        const found = cycle(next, [...path, next]);
+        if (found) return found;
+      }
+    }
+    state.set(stage, 'done');
+    return null;
+  };
+  for (const s of stages) {
+    const found = state.has(s) ? null : cycle(s, [s]);
+    if (found) {
+      problems.push(`the graph goes round ${found.map((x) => `\`${x}\``).join(' → ')} on verdicts that pass work on — a loop with no cap`);
+      break;
+    }
+  }
+  for (const s of stages) if (!edges.some((e) => e.from === s || e.to === s)) problems.push(`stage \`${s}\` has no edge in or out — nothing dispatches it`);
+  const ends = new Set(TERMINALS);
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const e of edges) if (ends.has(e.to) && !ends.has(e.from)) grew = ends.add(e.from) && true;
+  }
+  for (const s of stages) if (edges.some((e) => e.from === s) && !ends.has(s)) problems.push(`no chain of edges from \`${s}\` reaches \`done\` or \`human\` — work there never ends`);
+
   // The loop gate reads one cap per edge. Two lines naming the same edge with different caps would
   // leave it guessing which one holds; it would take the larger, but a graph should not need a
   // tie-breaker.

package/src/lessons.mjs

@@ -0,0 +1,55 @@
+/**
+ * The lessons a stage is handed as it starts: the list of its active pills, each with the trigger that says
+ * when it applies, given to the subagent by the `SubagentStart` hook.
+ *
+ * Every spec told its stage to read its pills, and a stage found them by opening files: every pill in its own
+ * directory, and every shared one to see whether its `applies_to` named it. So a reviewer read one in only
+ * seven of fifteen runs while twelve applied to it, and a stage no pill named opened them in two runs of three.
+ * Handed the list, a stage opens the ones whose trigger matches its task, and nothing else.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { frontmatter, list } from './commands/pills.mjs';
+
+/** How much of a trigger goes in the list: enough to say when, not the lesson. */
+const TRIGGER_CHARS = 160;
+
+/**
+ * A stage's lessons as the text handed to it, or null when it has none.
+ *
+ * @param {string} root - The project directory.
+ * @param {string} role - The stage.
+ * @returns {string|null}
+ */
+export function lessonIndex(root, role) {
+  const found = [];
+  for (const sub of [role, 'shared']) {
+    let files = [];
+    try {
+      files = readdirSync(join(root, '.claude', 'pills', sub)).filter((f) => f.endsWith('.md')).sort();
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      let fields = null;
+      try {
+        fields = frontmatter(readFileSync(join(root, '.claude', 'pills', sub, file), 'utf8'));
+      } catch {
+        continue;
+      }
+      if (!fields || fields.status === 'retired') continue;
+      const applies = list(fields.applies_to);
+      // A shared pill is this stage's when it names it; one in the stage's own directory, unless it names others.
+      if (sub === 'shared' ? !applies.includes(role) : applies.length > 0 && !applies.includes(role)) continue;
+      const trigger = String(fields.trigger ?? '').replace(/\s+/g, ' ').trim();
+      const when = trigger ? `when ${trigger.length > TRIGGER_CHARS ? `${trigger.slice(0, TRIGGER_CHARS - 1)}…` : trigger}` : 'on every task';
+      found.push(`- \`.claude/pills/${sub}/${file}\` — ${when}`);
+    }
+  }
+  if (found.length === 0) return null;
+  return [
+    `Your lessons in this project, ${found.length}: before acting, open each one whose trigger matches this task, and only those.`,
+    ...found,
+  ].join('\n');
+}

package/src/transcripts.mjs

@@ -317,7 +317,7 @@ const handsBack = (row) =>
  * @param {object|null} row - A parsed transcript row.
  * @returns {boolean}
  */
-const saidToAgent = (row) => {
+export const saidToAgent = (row) => {
   if (row?.type !== 'user') return false;
   const content = row.message?.content;
   if (Array.isArray(content) && content.some((b) => b?.type === 'tool_result')) return false;

package/src/wiring.mjs

@@ -109,7 +109,7 @@ const previousCommands = (h) => [command(h.script, h.mode), ...EARLIER_CANNOT_ST
  * The harness check has two: `Stop` tells the person what a turn left behind, `UserPromptSubmit` puts
  * the same findings in the model's context before it answers — the only one of the two it reads. The
  * loop gate has four, one per fact it keeps: a verdict, a dispatch, the owner speaking, and the
- * decision itself.
+ * decision itself; and a fifth, as each stage starts, that hands the stage its lessons (`src/lessons.mjs`).
  */
 export const HOOKS = [
   {
@@ -125,13 +125,14 @@ export const HOOKS = [
       },
     }),
   },
-  { event: 'UserPromptSubmit', script: GATE, timeout: 10, why: "the owner's reply never starts a loop's count over" },
+  { event: 'UserPromptSubmit', script: GATE, timeout: 10, why: "the owner's reply never gives an open loop its round more" },
   {
     event: 'PreToolUse', matcher: 'Agent|Task|SendMessage', script: GATE, timeout: 10, why: 'the caps in .claude/graph.md stay instructions nothing holds',
     crash: (cannot) => ({ systemMessage: `NINA: the loop gate could not start, so the caps in .claude/graph.md are not held — ${cannot}` }),
   },
   { event: 'PostToolUse', matcher: 'Agent|Task|SendMessage|AskUserQuestion|SubagentHandback', script: GATE, timeout: 10, why: 'the gate never learns which rounds went out, or that the owner answered' },
   { event: 'SubagentStop', script: GATE, timeout: 10, why: 'the gate misses the verdict of a stage that wrote its report as its last message' },
+  { event: 'SubagentStart', script: GATE, timeout: 10, why: 'a stage is not handed its lessons, and opens every shared pill to find them, or none' },
   {
     event: 'PreToolUse', matcher: 'Edit|Write|MultiEdit|NotebookEdit', script: GUARD, timeout: 10, why: 'a hand edit to a composed file is found only after the turn, as drift, and the next compose overwrites it',
     crash: (cannot) => ({ systemMessage: `NINA: the edit guard could not start, so composed files can be edited in place — ${cannot}` }),