llm-orchestrator 1.2.4 → 1.2.6

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.4",
+  "version": "1.2.6",
   "author": {
     "name": "Bogdan-Gabriel Torcescu",
     "url": "https://www.linkedin.com/in/bogdantorcescu/"

package/README.md

@@ -369,14 +369,20 @@ more instructions:
   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. 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.
-- A run opened with two or more shards whose main thread keeps doing the work — two work calls per planned shard, no
+- 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 (one per shard in incident, investigation and research flows, whose reads *are* the shards, with one firmer follow-up if the first reminder is ignored), 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
   live state a subagent cannot inherit (a browser mid-flow, an interactive shell); independent reads
-  are never inline. The audit adds `inline_declared` and `below_fan_out` (incident, investigation or
-  research runs opened with fewer than two shards).
+  are never inline. The audit adds `inline_declared`, `inline_after_nudge` (an `--inline` declared only
+  after a dispatch reminder — a retroactive justification) and `below_fan_out` (incident, investigation
+  or research runs opened with fewer than two shards).
 - Once the entrypoint is loaded, read-only discovery (reading files, `grep`, `git status`, tool
   version checks) before `run start` is SKILL.md steps 2–3, not a deviation. An edit, a write, a
   dispatch or any other shell command before the run is.

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/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/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 = (EVIDENCE_TYPES.has(taskType) ? EVIDENCE_ROLES[taskType] : 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. */
@@ -61,6 +67,18 @@ function pathHash(path) {
 // 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 flows: the reads are the shards, so waiting two calls per shard lets the
+// main thread read everything before the reminder arrives. One call per shard there,
+// and one firmer follow-up if the first reminder is ignored.
+export const EVIDENCE_CALLS_PER_SHARD = 1;
+const MAX_DISPATCH_NUDGES = 2;
+
+/** The follow-up for an evidence flow whose first dispatch reminder was ignored. */
+export function dispatchFollowupFor(cli = 'llm-orchestrator', planned = 2, taskType = null) {
+  const roles = (EVIDENCE_ROLES[taskType] ?? []).slice(0, 3);
+  const who = roles.length > 0 ? ` (${roles.join(', ')})` : '';
+  return `The dispatch reminder was not acted on, and the main thread is still gathering evidence itself. In an evidence flow those reads are the ${planned} planned shards — independent, W-tier, meant for subagents${who}. Dispatch the remaining sources now, or declare why they must stay inline (\`${cli} run start --type <TYPE> --inline "stateful:<what state>"\`).`;
+}
 
 // Evidence-gathering flows: their first phase fans out across independent sources.
 const EVIDENCE_TYPES = new Set(['INCIDENT', 'INVESTIGATION', 'RESEARCH']);
@@ -69,6 +87,30 @@ 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 TASK_FLOWS = readRegistry('registries/routing-matrix.json')?.task_flows ?? {};
+const FLOW_ROLES = Object.fromEntries(Object.entries(TASK_FLOWS)
+  .map(([type, flow]) => [type, [...new Set(flow.phases.flatMap((phase) => phase.roles ?? []))].filter((role) => role !== 'orchestrator')]));
+// The evidence phase of each flow: who gathers, as opposed to who fixes later.
+const EVIDENCE_ROLES = Object.fromEntries(Object.entries(TASK_FLOWS)
+  .map(([type, flow]) => [type, (flow.phases[0]?.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
@@ -189,7 +231,7 @@ 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)), agent: 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 };
@@ -241,6 +283,9 @@ function historyLine(session, fields, now) {
     inline_reason: fields.inline_reason ?? null,
     dispatch_nudged: Boolean(fields.dispatch_nudged),
     overreach: Boolean(fields.overreach_nudged),
+    inline_after_nudge: Boolean(fields.inline_after_nudge),
+    role_dispatches: fields.role_dispatches ?? 0,
+    generic_dispatches: fields.generic_dispatches ?? 0,
     closed_by: fields.closed_by,
   };
 }
@@ -312,6 +357,8 @@ export function decide(previous, event, now) {
       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 };
@@ -337,6 +384,10 @@ export function decide(previous, event, now) {
       touched_tests: false,
       overreach_nudged: false,
       subagent_ids: [],
+      role_dispatches: 0,
+      generic_dispatches: 0,
+      dispatch_nudges: 0,
+      inline_after_nudge: Boolean(event.run.inline && session.run?.dispatch_nudged),
     };
     // The work already done is accounted for on the run itself now.
     session.worked_without_run = false;
@@ -364,10 +415,17 @@ export function decide(previous, event, now) {
       }
       return { session, output, history };
     }
+    const evidence = EVIDENCE_TYPES.has(current.task_type);
+    const step = (evidence ? EVIDENCE_CALLS_PER_SHARD : DISPATCH_CALLS_PER_SHARD) * (current.planned_shards ?? 0);
+    const nudges = current.dispatch_nudges ?? (current.dispatch_nudged ? 1 : 0);
+    const allowed = evidence ? MAX_DISPATCH_NUDGES : 1;
     if ((current.planned_shards ?? 0) >= 2 && current.subagents_started === 0 && !current.inline_reason
-      && !current.dispatch_nudged && current.main_work_calls >= DISPATCH_CALLS_PER_SHARD * current.planned_shards) {
+      && nudges < allowed && current.main_work_calls >= step * (nudges + 1)) {
       current.dispatch_nudged = true;
-      output = { additionalContext: dispatchNudgeFor(undefined, current.planned_shards), kind: 'dispatch', planned: current.planned_shards };
+      current.dispatch_nudges = nudges + 1;
+      output = nudges === 0
+        ? { additionalContext: dispatchNudgeFor(undefined, current.planned_shards, current.task_type), kind: 'dispatch', planned: current.planned_shards, taskType: current.task_type }
+        : { additionalContext: dispatchFollowupFor(undefined, current.planned_shards, current.task_type), kind: 'dispatch_followup', planned: current.planned_shards, taskType: current.task_type };
     }
     return { session, output, history };
   }
@@ -505,7 +563,8 @@ 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 === 'dispatch_followup' ? dispatchFollowupFor(cli, result.output.planned, result.output.taskType)
     : result.output.kind === 'overreach' ? overreachNudgeFor(cli, result.output.files)
       : nudgeFor(cli);
   return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
@@ -552,7 +611,11 @@ export function adherenceSummary(lines) {
     planned_but_not_dispatched: lines.filter((line) => (line.planned_shards ?? 0) > 1 && line.subagents_started === 0).length,
     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,
+    inline_after_nudge: lines.filter((line) => line.inline_after_nudge).length,
     trivial_overreach: lines.filter((line) => line.trivial && line.overreach).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.4",
+  "version": "1.2.6",
   "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", "subagent_ids"],
+      "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", "dispatch_nudges", "inline_after_nudge"],
       "properties": {
         "task_id": { "type": "string", "minLength": 1 },
         "task_type": { "type": ["string", "null"], "enum": ["INCIDENT", "FEATURE", "BUG_FIX", "REFACTOR", "INVESTIGATION", "DEPLOY", "CONFIG", "REVIEW", "RESEARCH", null] },
@@ -24,7 +24,11 @@
         "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" },
-        "subagent_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{12}$" }, "description": "Short hashes of the distinct subagents started under this run." }
+        "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, …)." },
+        "dispatch_nudges": { "type": "integer", "minimum": 0, "maximum": 2, "description": "Dispatch reminders sent: one, or two for evidence flows whose first was ignored." },
+        "inline_after_nudge": { "type": "boolean", "description": "This run replaced one that had already received a dispatch reminder, and declared --inline: a retroactive justification." }
       }
     },
     "session": {
@@ -46,7 +50,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", "inline_after_nudge", "role_dispatches", "generic_dispatches", "closed_by"],
       "properties": {
         "session": { "type": "string", "minLength": 1 },
         "task_id": { "type": ["string", "null"] },
@@ -63,6 +67,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." },
+        "inline_after_nudge": { "type": "boolean" },
+        "role_dispatches": { "type": "integer", "minimum": 0 },
+        "generic_dispatches": { "type": "integer", "minimum": 0 },
         "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end", "session_end"] }
       }
     }