llm-orchestrator 1.2.3 → 1.2.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llm-orchestrator",
   "description": "Write /task once — it plans the work, shards it across parallel subagents, gates every phase and verifies before claiming done. Claude Code, Codex, OpenCode, Kilo.",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "author": {
     "name": "Bogdan-Gabriel Torcescu",
     "url": "https://www.linkedin.com/in/bogdantorcescu/"

package/README.md

@@ -367,8 +367,15 @@ more instructions:
 - Trivial is the narrow exception — a one-line change such as a typo or a version bump. A run
   declared trivial that then edits a second file or touches tests gets one reminder to reopen it as
   a typed run, and counts as `trivial_overreach` in the audit. Trivial runs close at the end of the
-  turn (`Stop` hook), so single-prompt sessions still reach the history.
-- A run opened with two or more shards whose main thread keeps doing the work — six work calls, no
+  turn (`Stop` hook), so single-prompt sessions still reach the history. Typed runs stay open across
+  turns and close when the session ends (`SessionEnd`), so an unclosed run is never lost.
+- Subagents are counted once each: resuming one (SendMessage) is not a new dispatch. Each is also
+  classified by its agent type — one of the orchestrator's roles, or a generic agent such as
+  `general-purpose` — and the dispatch reminder names the roles of the task's flow. The audit
+  reports `role_dispatches`, `generic_dispatches` and `runs_without_roles`. The Claude Code plugin
+  ships the roles as agents (`llm-orchestrator:<role>`), so they are available without a project
+  install.
+- A run opened with two or more shards whose main thread keeps doing the work — two work calls per planned shard, no
   subagent started — gets one more sentence: dispatch the independent shards (searching for the
   Agent tool if it is deferred), or declare the chain inline with
   `run start --type <T> --shards <n> --inline "stateful:<what>"`. Work is inline only while it holds

package/adapters/agents.mjs

@@ -26,7 +26,7 @@ description: ${role.description}
 ---
 ${MD_MARKER}
 
-Mandatory — before acting, load and follow \`.agents/skills/orchestrate/SKILL.md\`.
+Mandatory — before acting, load and follow the \`orchestrate-core\` skill (\`.agents/skills/orchestrate/SKILL.md\` in a project install). You work inside the parent's run: never open or close one.
 ${profileLine}
 Best for: ${role.best_for}
 Never bypass a mandatory capability without declaring the gap first.

package/adapters/hooks.mjs

@@ -11,7 +11,7 @@ import { relative, isAbsolute } from 'node:path';
 /** Marks the hook entries this package owns inside a user's hooks JSON. */
 export const FLOW_MARKER = 'orchestrate-core:flow';
 
-export const FLOW_EVENTS = ['UserPromptSubmit', 'PreToolUse', 'SubagentStart', 'Stop'];
+export const FLOW_EVENTS = ['UserPromptSubmit', 'PreToolUse', 'SubagentStart', 'Stop', 'SessionEnd'];
 
 /** Spell the runtime path through $HOME when it lives there, so committed settings stay portable. */
 export function runtimeCliPath(runtimeRoot) {
@@ -166,6 +166,8 @@ export const OrchestrateFlow = async ({ directory }) => {
         }
         const idle = event?.properties?.sessionID;
         if (event?.type === "session.idle" && idle && !parentOf.has(idle)) gate({ hook_event_name: "Stop", session_id: idle });
+        const ended = info?.id;
+        if (event?.type === "session.deleted" && ended && !parentOf.has(ended)) gate({ hook_event_name: "SessionEnd", session_id: ended });
       } catch {}
     },
     "chat.message": async (input) => {

package/agents/adversarial-skeptic.md

@@ -0,0 +1,10 @@
+---
+name: adversarial-skeptic
+description: Independently challenges a conclusion, diagnosis, or diff before it ships.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+Best for: Money, auth, migration, and frozen-build-shaped review seats.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/backend-fixer.md

@@ -0,0 +1,10 @@
+---
+name: backend-fixer
+description: Implements bounded backend changes: a bug fix behind a validated hypothesis, or a feature/config change behind a failing test.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Backend implementation shards — bug fixes with a validated hypothesis, and the build phase of a feature or config flow.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/code-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: code-reviewer
+description: Performs the review pass at the task's review risk floor.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+Best for: The review seat on every review-gated task.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/code-simplifier.md

@@ -0,0 +1,10 @@
+---
+name: code-simplifier
+description: Simplifies and clarifies recently changed code without changing behavior.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Post-implementation cleanup passes.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/db-concurrency-specialist.md

@@ -0,0 +1,10 @@
+---
+name: db-concurrency-specialist
+description: Reviews transactional/locking correctness and concurrency-sensitive schema/code.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+Best for: Race conditions, stale claims, lock ordering, transactional boundaries.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/db-migration-author.md

@@ -0,0 +1,10 @@
+---
+name: db-migration-author
+description: Sole authority for authoring SQL schema migrations.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Any new migration file; never hand-write one outside this role.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/explore.md

@@ -0,0 +1,10 @@
+---
+name: explore
+description: Read-only breadth search across a codebase: where something is defined, what calls it, which files are involved.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+Best for: Broad read-only location work before a decision; never edits.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/frontend-fixer.md

@@ -0,0 +1,10 @@
+---
+name: frontend-fixer
+description: Implements bounded frontend changes: a bug fix behind a validated hypothesis, or a feature change behind a failing test.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Frontend/UI implementation shards — bug fixes with a validated hypothesis, and the build phase of a feature flow.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/frontend-specialist.md

@@ -0,0 +1,10 @@
+---
+name: frontend-specialist
+description: Implements frontend changes that touch shared state, realtime or a native bridge, respecting shipped-client compatibility.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Complex frontend state, realtime surfaces and native-bridge implementation work.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/general.md

@@ -0,0 +1,10 @@
+---
+name: general
+description: General-purpose bounded worker for tasks that fit no specialist role.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Bounded work with no specialist owner; escalate rather than widen scope.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/orchestrator.md

@@ -0,0 +1,10 @@
+---
+name: orchestrator
+description: Plans work, resolves capabilities, dispatches bounded shards, integrates results.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: ORCHESTRATOR — Plans, dispatches, and integrates; owns the overall session state.
+Best for: Any nontrivial task needing more than one shard or a risk-floor review seat.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/production-telemetry-collector.md

@@ -0,0 +1,10 @@
+---
+name: production-telemetry-collector
+description: Collects production logs/metrics/traces before an incident hypothesis is formed.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+Best for: Incident evidence gathering; never forms a fix on its own.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/provider-webhook-specialist.md

@@ -0,0 +1,10 @@
+---
+name: provider-webhook-specialist
+description: Implements and reviews payment/webhook provider integrations (Stripe, Apple, Google).
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Webhook signature/idempotency, provider state reconciliation, refund delivery.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/route-data-flow-tracer.md

@@ -0,0 +1,10 @@
+---
+name: route-data-flow-tracer
+description: Traces a request/data path across layers (frontend, API, DB, provider) read-only.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+Best for: Symptoms that cross architectural layers.
+Never bypass a mandatory capability without declaring the gap first.

package/agents/test-engineer.md

@@ -0,0 +1,10 @@
+---
+name: test-engineer
+description: Writes and maintains behavioral/regression tests.
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
+Permission profile: RW — Read-write within an assigned bounded shard.
+Best for: Coverage gaps, regression tests for bug fixes, refactor safety nets.
+Never bypass a mandatory capability without declaring the gap first.

package/hooks/hooks.json

@@ -44,6 +44,17 @@
           }
         ]
       }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/llm-orchestrator.mjs\" gate 2>/dev/null || true # orchestrate-core:flow",
+            "timeout": 3
+          }
+        ]
+      }
     ]
   }
 }

package/lib/flow-gate.mjs

@@ -15,7 +15,9 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { appendFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /**
  * The one sentence the model gets. `cli` is how to invoke this package from the
@@ -32,8 +34,12 @@ export const NUDGE = nudgeFor();
  * The second, and last, sentence the model can get per run: the plan has shards,
  * none went to a subagent, and the main thread keeps doing the work itself.
  */
-export function dispatchNudgeFor(cli = 'llm-orchestrator', planned = 2) {
-  return `This run planned ${planned} shards and none has been dispatched to a subagent; the main thread is doing the work itself. Dispatch the independent shards (Claude Code: the Agent tool — search for it if it is deferred; Codex: spawn_agent; OpenCode/Kilo: task), or declare why this must stay inline (\`${cli} run start --type <TYPE> --inline "stateful:<what state>"\`).`;
+export function dispatchNudgeFor(cli = 'llm-orchestrator', planned = 2, taskType = null) {
+  const roles = (FLOW_ROLES[taskType] ?? []).slice(0, 4);
+  const to = roles.length > 0
+    ? ` to this flow's roles (${roles.join(', ')}), not a general-purpose agent`
+    : ' to the orchestrator\'s roles, not a general-purpose agent';
+  return `This run planned ${planned} shards and none has been dispatched to a subagent; the main thread is doing the work itself. Dispatch the independent shards${to} (Claude Code: the Agent tool — search for it if it is deferred; Codex: spawn_agent; OpenCode/Kilo: task), or declare why this must stay inline (\`${cli} run start --type <TYPE> --inline "stateful:<what state>"\`).`;
 }
 
 /** A run declared trivial has outgrown the declaration. */
@@ -58,8 +64,9 @@ function pathHash(path) {
   return createHash('sha256').update(path).digest('hex').slice(0, 12);
 }
 
-// Main-thread work calls tolerated after run start before the dispatch nudge.
-export const DISPATCH_THRESHOLD = 6;
+// Main-thread work calls tolerated per planned shard before the dispatch nudge: a
+// two-shard task that is finished inline in three calls never reached a fixed six.
+export const DISPATCH_CALLS_PER_SHARD = 2;
 
 // Evidence-gathering flows: their first phase fans out across independent sources.
 const EVIDENCE_TYPES = new Set(['INCIDENT', 'INVESTIGATION', 'RESEARCH']);
@@ -68,6 +75,26 @@ export const TASK_TYPES = ['INCIDENT', 'FEATURE', 'BUG_FIX', 'REFACTOR', 'INVEST
 
 export const LEDGER_DIRECTORY = '.orchestrator-run';
 
+// The orchestrator's own roles, and the roles each task flow dispatches to, read from
+// the registries this runtime ships with. A missing registry only weakens the audit.
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+function readRegistry(path) {
+  try { return JSON.parse(readFileSync(join(PACKAGE_ROOT, path), 'utf8')); } catch { return null; }
+}
+const ROLE_IDS = new Set([
+  ...(readRegistry('registries/agent-roles.json')?.roles ?? []).map((role) => role.id),
+  ...(readRegistry('registries/preferred-tools.json')?.tools ?? []).filter((tool) => tool.kind === 'agent_role').map((tool) => tool.id),
+]);
+const FLOW_ROLES = Object.fromEntries(Object.entries(readRegistry('registries/routing-matrix.json')?.task_flows ?? {})
+  .map(([type, flow]) => [type, [...new Set(flow.phases.flatMap((phase) => phase.roles ?? []))].filter((role) => role !== 'orchestrator')]));
+
+/** 'role' for an orchestrator role (plugin-namespaced ids too), 'generic' otherwise, null when unknown. */
+export function roleKind(agentType) {
+  if (typeof agentType !== 'string' || !agentType) return null;
+  // `plugin:role` (Claude Code plugin agents) and `plugin-role` (preferred-tools ids) both resolve.
+  return ROLE_IDS.has(agentType.split(':').pop()) || ROLE_IDS.has(agentType.replaceAll(':', '-')) ? 'role' : 'generic';
+}
+
 const MAX_REASON = 200;
 
 // Reading the orchestration instructions is the intended first step, so it must
@@ -188,8 +215,9 @@ export function normalizePayload(raw) {
   // plugin and a CLI install; the harness's own event id lets the second be ignored.
   const id = (value) => (typeof value === 'string' && value ? value : null);
   if (eventName === 'UserPromptSubmit') return { kind: 'prompt', session, isSubagent, key: keyOf(eventName, id(payload.prompt_id) ?? id(payload.turn_id)) };
-  if (eventName === 'SubagentStart') return { kind: 'subagent', session, isSubagent, key: keyOf(eventName, id(payload.agent_id)) };
+  if (eventName === 'SubagentStart') return { kind: 'subagent', session, isSubagent, key: keyOf(eventName, id(payload.agent_id)), agent: id(payload.agent_id), role: roleKind(payload.agent_type) };
   if (eventName === 'Stop') return { kind: 'stop', session, isSubagent };
+  if (eventName === 'SessionEnd') return { kind: 'session_end', session, isSubagent };
   if (eventName !== 'PreToolUse') return { kind: 'other', session, isSubagent };
 
   const toolName = String(payload.tool_name ?? '');
@@ -239,6 +267,8 @@ function historyLine(session, fields, now) {
     inline_reason: fields.inline_reason ?? null,
     dispatch_nudged: Boolean(fields.dispatch_nudged),
     overreach: Boolean(fields.overreach_nudged),
+    role_dispatches: fields.role_dispatches ?? 0,
+    generic_dispatches: fields.generic_dispatches ?? 0,
     closed_by: fields.closed_by,
   };
 }
@@ -283,6 +313,15 @@ export function decide(previous, event, now) {
     return { session, output, history };
   }
 
+  if (event.kind === 'session_end') {
+    // Typed runs outlive turns but not the session: close them so they reach history.
+    if (session.run) {
+      history.push(closeRun(session, now, 'session_end'));
+      session.run = null;
+    }
+    return { session, output, history };
+  }
+
   if (event.kind === 'stop') {
     // A trivial run lasts one turn; closing it here keeps single-prompt sessions in history.
     if (session.run?.trivial && !event.isSubagent) {
@@ -293,8 +332,18 @@ export function decide(previous, event, now) {
   }
 
   if (event.kind === 'subagent') {
-    if (session.run) session.run.subagents_started += 1;
-    else session.subagents_without_run += 1;
+    if (session.run) {
+      // Count distinct agents: a resumed subagent fires SubagentStart again, possibly
+      // long after its first start has left the seen-window.
+      const ids = Array.isArray(session.run.subagent_ids) ? session.run.subagent_ids : [];
+      const agentHash = event.agent ? pathHash(event.agent) : null;
+      if (!agentHash || !ids.includes(agentHash)) {
+        session.run.subagents_started += 1;
+        if (agentHash) session.run.subagent_ids = [...ids, agentHash];
+        if (event.role === 'role') session.run.role_dispatches = (session.run.role_dispatches ?? 0) + 1;
+        if (event.role === 'generic') session.run.generic_dispatches = (session.run.generic_dispatches ?? 0) + 1;
+      }
+    } else session.subagents_without_run += 1;
     return { session, output, history };
   }
 
@@ -317,6 +366,9 @@ export function decide(previous, event, now) {
       edited_files: [],
       touched_tests: false,
       overreach_nudged: false,
+      subagent_ids: [],
+      role_dispatches: 0,
+      generic_dispatches: 0,
     };
     // The work already done is accounted for on the run itself now.
     session.worked_without_run = false;
@@ -345,9 +397,9 @@ export function decide(previous, event, now) {
       return { session, output, history };
     }
     if ((current.planned_shards ?? 0) >= 2 && current.subagents_started === 0 && !current.inline_reason
-      && !current.dispatch_nudged && current.main_work_calls >= DISPATCH_THRESHOLD) {
+      && !current.dispatch_nudged && current.main_work_calls >= DISPATCH_CALLS_PER_SHARD * current.planned_shards) {
       current.dispatch_nudged = true;
-      output = { additionalContext: dispatchNudgeFor(undefined, current.planned_shards), kind: 'dispatch', planned: current.planned_shards };
+      output = { additionalContext: dispatchNudgeFor(undefined, current.planned_shards, current.task_type), kind: 'dispatch', planned: current.planned_shards, taskType: current.task_type };
     }
     return { session, output, history };
   }
@@ -485,7 +537,7 @@ export async function handleHook({ payload, project, now = Date.now(), cli = 'll
   });
   if (!result.output) return null;
   // decide() speaks in the default CLI spelling; the hook swaps in the runnable path.
-  const text = result.output.kind === 'dispatch' ? dispatchNudgeFor(cli, result.output.planned)
+  const text = result.output.kind === 'dispatch' ? dispatchNudgeFor(cli, result.output.planned, result.output.taskType)
     : result.output.kind === 'overreach' ? overreachNudgeFor(cli, result.output.files)
       : nudgeFor(cli);
   return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
@@ -533,6 +585,10 @@ export function adherenceSummary(lines) {
     runs_without_plan: lines.filter((line) => !line.skipped_flow && !line.trivial && line.planned_shards === null).length,
     inline_declared: lines.filter((line) => Boolean(line.inline_reason)).length,
     trivial_overreach: lines.filter((line) => line.trivial && line.overreach).length,
-    below_fan_out: lines.filter((line) => EVIDENCE_TYPES.has(line.task_type) && !line.inline_reason && (line.planned_shards ?? 0) < 2).length,
+    role_dispatches: lines.reduce((sum, line) => sum + (line.role_dispatches ?? 0), 0),
+    generic_dispatches: lines.reduce((sum, line) => sum + (line.generic_dispatches ?? 0), 0),
+    runs_without_roles: lines.filter((line) => (line.subagents_started ?? 0) > 0 && line.role_dispatches === 0 && (line.generic_dispatches ?? 0) > 0).length,
+    below_fan_out: lines.filter((line) => EVIDENCE_TYPES.has(line.task_type) && !line.inline_reason
+      && (line.planned_shards ?? 0) < 2 && (line.subagents_started ?? 0) < 2).length,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-orchestrator",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Write /task once — it plans the work, shards it across parallel subagents, gates every phase and verifies before claiming done. Claude Code, Codex, OpenCode, Kilo.",
   "type": "module",
   "engines": {
@@ -48,6 +48,7 @@
     "NOTICE",
     "skills",
     "hooks",
+    "agents",
     ".claude-plugin"
   ],
   "scripts": {

package/schemas/flow-ledger.schema.json

@@ -8,7 +8,7 @@
     "run": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["task_id", "task_type", "trivial", "reason", "opened_at", "planned_shards", "subagents_started", "started_outside_flow", "inline_reason", "main_work_calls", "dispatch_nudged", "edited_files", "touched_tests", "overreach_nudged"],
+      "required": ["task_id", "task_type", "trivial", "reason", "opened_at", "planned_shards", "subagents_started", "started_outside_flow", "inline_reason", "main_work_calls", "dispatch_nudged", "edited_files", "touched_tests", "overreach_nudged", "subagent_ids", "role_dispatches", "generic_dispatches"],
       "properties": {
         "task_id": { "type": "string", "minLength": 1 },
         "task_type": { "type": ["string", "null"], "enum": ["INCIDENT", "FEATURE", "BUG_FIX", "REFACTOR", "INVESTIGATION", "DEPLOY", "CONFIG", "REVIEW", "RESEARCH", null] },
@@ -23,7 +23,10 @@
         "dispatch_nudged": { "type": "boolean" },
         "edited_files": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{12}$" }, "description": "Short hashes of edited paths — never the paths themselves." },
         "touched_tests": { "type": "boolean" },
-        "overreach_nudged": { "type": "boolean" }
+        "overreach_nudged": { "type": "boolean" },
+        "subagent_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{12}$" }, "description": "Short hashes of the distinct subagents started under this run." },
+        "role_dispatches": { "type": "integer", "minimum": 0, "description": "Subagents started as one of the orchestrator's roles." },
+        "generic_dispatches": { "type": "integer", "minimum": 0, "description": "Subagents started as a generic agent type (general-purpose, Explore, …)." }
       }
     },
     "session": {
@@ -45,7 +48,7 @@
     "historyLine": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["session", "task_id", "task_type", "trivial", "reason", "opened_at", "closed_at", "duration_s", "planned_shards", "subagents_started", "started_outside_flow", "skipped_flow", "inline_reason", "dispatch_nudged", "overreach", "closed_by"],
+      "required": ["session", "task_id", "task_type", "trivial", "reason", "opened_at", "closed_at", "duration_s", "planned_shards", "subagents_started", "started_outside_flow", "skipped_flow", "inline_reason", "dispatch_nudged", "overreach", "role_dispatches", "generic_dispatches", "closed_by"],
       "properties": {
         "session": { "type": "string", "minLength": 1 },
         "task_id": { "type": ["string", "null"] },
@@ -62,7 +65,9 @@
         "inline_reason": { "type": ["string", "null"] },
         "dispatch_nudged": { "type": "boolean" },
         "overreach": { "type": "boolean", "description": "A trivial run that edited two or more files or its tests." },
-        "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end"] }
+        "role_dispatches": { "type": "integer", "minimum": 0 },
+        "generic_dispatches": { "type": "integer", "minimum": 0 },
+        "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end", "session_end"] }
       }
     }
   }