llm-orchestrator 1.2.5 → 1.2.7

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

package/README.md

@@ -365,7 +365,8 @@ more instructions:
   it, runs opened without a PlanShard count, runs that planned several shards but started no
   subagents, and runs still open.
 - 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
+  declared trivial that then edits a second file, touches tests, or keeps working past eight calls
+  (an investigation is not trivial) 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. Typed runs stay open across
   turns and close when the session ends (`SessionEnd`), so an unclosed run is never lost.
@@ -375,13 +376,14 @@ more instructions:
   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
+- 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 and the evidence is live — `ssh`, remote databases, cluster/cloud CLIs, HTTP; a few small local files are fine read inline), 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/bin/run.mjs

@@ -7,7 +7,7 @@
  * the project ledger; the command itself only validates and acknowledges, so it is
  * safe to call with or without the hooks installed.
  */
-import { parseRunArgs, TASK_TYPES } from '../lib/flow-gate.mjs';
+import { INLINE_REASON, parseRunArgs, TASK_TYPES } from '../lib/flow-gate.mjs';
 
 const USAGE = `Usage: llm-orchestrator run start --type <${TASK_TYPES.join('|')}> [--shards N] [--inline "stateful:<what>"]
        llm-orchestrator run start --trivial "<reason>"
@@ -18,7 +18,11 @@ if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
   process.stdout.write(`${USAGE}\n`);
 } else {
   const parsed = parseRunArgs(args);
-  if (!parsed) {
+  const inlineAt = args.indexOf('--inline');
+  if (!parsed && inlineAt !== -1 && !INLINE_REASON.test(args[inlineAt + 1] ?? '')) {
+    process.stderr.write('--inline must name the live state a subagent cannot inherit, as "stateful:<what state>" (a browser session mid-flow, an interactive shell). Independent reads are never inline — dispatch them.\n');
+    process.exitCode = 1;
+  } else if (!parsed) {
     process.stderr.write(`${USAGE}\n`);
     process.exitCode = 1;
   } else {

package/lib/flow-gate.mjs

@@ -35,7 +35,7 @@ export const NUDGE = nudgeFor();
  * none went to a subagent, and the main thread keeps doing the work itself.
  */
 export function dispatchNudgeFor(cli = 'llm-orchestrator', planned = 2, taskType = null) {
-  const roles = (FLOW_ROLES[taskType] ?? []).slice(0, 4);
+  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';
@@ -47,6 +47,11 @@ export function overreachNudgeFor(cli = 'llm-orchestrator', files = 2) {
   return `This task was declared trivial, but it now touches ${files} files or its tests. Reopen it as a typed run (\`${cli} run start --type <TYPE> --shards <n>\`) so it is classified, planned and verified like one.`;
 }
 
+/** A run declared trivial that has turned into an investigation. */
+export function overreachWorkNudgeFor(cli = 'llm-orchestrator', calls = 9) {
+  return `This task was declared trivial, but it has now made ${calls} work calls — trivial is a one-line change, not an investigation. Reopen it as a typed run (\`${cli} run start --type <TYPE> --shards <n>\`) so it is classified, planned and verified like one.`;
+}
+
 // Edit-shaped tools, per harness. Only a short hash of each path is kept.
 const EDIT_TOOLS = new Set(['edit', 'write', 'multiedit', 'notebookedit', 'str_replace_based_edit_tool', 'apply_patch', 'patch']);
 const TEST_PATH = /(^|\/)(test|tests|__tests__|spec|specs)\/|[._-](test|spec)\.[a-z0-9]+$|(^|\/)test_[^/]+\.py$|_spec\.rb$/i;
@@ -67,6 +72,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']);
@@ -85,8 +102,12 @@ 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 ?? {})
+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) {
@@ -97,6 +118,18 @@ export function roleKind(agentType) {
 
 const MAX_REASON = 200;
 
+export const INLINE_REASON = /^stateful:\s*\S/;
+
+// A: a trivial run is a one-line change, not an investigation.
+export const TRIVIAL_WORK_LIMIT = 8;
+
+// C: sources whose reads cost real time and live remotely — the reads that pay to fan out.
+const LIVE_SOURCE = /(^|[\s;&|(])(rtk\s+)?(ssh|scp|psql|mysql|mongosh|mongo|redis-cli|kubectl|docker\s+(exec|logs)|aws|gcloud|az|curl|wget|http|httpie)(\s|$)/;
+
+export function isLiveSource(command) {
+  return typeof command === 'string' && LIVE_SOURCE.test(command);
+}
+
 // Reading the orchestration instructions is the intended first step, so it must
 // never count as starting work without a run.
 const INSTRUCTION_PATH = /(^|\/)(SKILL|AGENTS|CLAUDE|protocol)\.md$|\/orchestrate-core\/|(^|\/)(policies|workflows|registries)\/[^/]+\.(md|json)$/;
@@ -192,10 +225,12 @@ export function parseRunArgs(args) {
     if (flag === '--type' && value) { type = value.toUpperCase(); index += 1; }
     else if (flag === '--shards' && value) { shards = Number.parseInt(value, 10); index += 1; }
     else if (flag === '--trivial' && value !== undefined) { trivial = value.slice(0, MAX_REASON); index += 1; }
-    else if (flag === '--inline' && value) { inline = value.slice(0, MAX_REASON); index += 1; }
+    else if (flag === '--inline' && value !== undefined) { inline = value.slice(0, MAX_REASON); index += 1; }
   }
   if (trivial !== null) return { action: 'start', trivial: true, reason: trivial || null, type: null, shards: null, inline: null };
   if (!TASK_TYPES.includes(type)) return null;
+  // Inline is for live state a subagent cannot inherit; the reason has to name it.
+  if (inline !== null && !INLINE_REASON.test(inline)) return null;
   return { action: 'start', trivial: false, reason: null, type, shards: Number.isInteger(shards) && shards > 0 ? shards : null, inline };
 }
 
@@ -241,6 +276,7 @@ export function normalizePayload(raw) {
     nonWork: NON_WORK_TOOLS.has(toolName.toLowerCase()),
     loadsEntrypoint,
     readOnly,
+    live: isLiveSource(command),
     edits: editedPaths(toolName, input).map((editedPath) => ({ hash: pathHash(editedPath), test: TEST_PATH.test(editedPath) })),
   };
 }
@@ -267,6 +303,8 @@ 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),
+    live_calls: fields.live_calls ?? 0,
     role_dispatches: fields.role_dispatches ?? 0,
     generic_dispatches: fields.generic_dispatches ?? 0,
     closed_by: fields.closed_by,
@@ -369,6 +407,9 @@ export function decide(previous, event, now) {
       subagent_ids: [],
       role_dispatches: 0,
       generic_dispatches: 0,
+      dispatch_nudges: 0,
+      live_calls: 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;
@@ -390,16 +431,29 @@ export function decide(previous, event, now) {
     if (current.trivial) {
       current.edited_files = [...new Set([...(current.edited_files ?? []), ...event.edits.map((entry) => entry.hash)])];
       current.touched_tests = Boolean(current.touched_tests) || event.edits.some((entry) => entry.test);
-      if (!current.overreach_nudged && (current.edited_files.length >= 2 || current.touched_tests)) {
+      const grewByEdits = current.edited_files.length >= 2 || current.touched_tests;
+      const grewByWork = current.main_work_calls > TRIVIAL_WORK_LIMIT;
+      if (!current.overreach_nudged && (grewByEdits || grewByWork)) {
         current.overreach_nudged = true;
-        output = { additionalContext: overreachNudgeFor(undefined, current.edited_files.length), kind: 'overreach', files: current.edited_files.length };
+        output = grewByEdits
+          ? { additionalContext: overreachNudgeFor(undefined, current.edited_files.length), kind: 'overreach', files: current.edited_files.length }
+          : { additionalContext: overreachWorkNudgeFor(undefined, current.main_work_calls), kind: 'overreach', calls: current.main_work_calls };
       }
       return { session, output, history };
     }
+    if (event.live) current.live_calls = (current.live_calls ?? 0) + 1;
+    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);
+    // The follow-up is for live evidence; a few small local files are fine read inline.
+    const allowed = evidence && (current.live_calls ?? 0) > 0 ? 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, current.task_type), kind: 'dispatch', planned: current.planned_shards, taskType: current.task_type };
+      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 };
   }
@@ -538,7 +592,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, result.output.taskType)
-    : result.output.kind === 'overreach' ? overreachNudgeFor(cli, result.output.files)
+    : result.output.kind === 'dispatch_followup' ? dispatchFollowupFor(cli, result.output.planned, result.output.taskType)
+    : result.output.kind === 'overreach' ? (result.output.calls ? overreachWorkNudgeFor(cli, result.output.calls) : overreachNudgeFor(cli, result.output.files))
       : nudgeFor(cli);
   return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
 }
@@ -584,11 +639,12 @@ 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
+    below_fan_out: lines.filter((line) => EVIDENCE_TYPES.has(line.task_type) && !line.inline_reason && (line.live_calls ?? 0) > 0
       && (line.planned_shards ?? 0) < 2 && (line.subagents_started ?? 0) < 2).length,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-orchestrator",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "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": {

package/policies/dispatch.md

@@ -294,12 +294,18 @@ Everything around that chain is still sharded:
 - Independent reads are never inline: log, metric and database queries, code search, config
   lookups. An SSH query that only reads is a stateless command, not a session — five of them are
   five W-tier evidence shards, not one inline chain.
+- Size the fan-out to the evidence, not to the task type. **Live or large sources** — anything
+  behind `ssh`, a remote database, a cluster or cloud CLI, an HTTP API, or logs too long to read
+  whole — are where parallel W-tier collectors pay, and where the incident/investigation/research
+  minimums apply. A handful of small local files is read faster inline than dispatched; plan it as
+  one shard and do not pad the fan-out to look thorough.
 - "Cheaper inline" is not a reason. The main thread runs at the flow's highest tier; the same reads
   on a W-tier subagent cost less per token and keep the orchestrator's context for synthesis.
 - A tool that is not visible is not absent. On Claude Code the Agent tool can be deferred — search
   for it (`tool.discovery`) before concluding dispatch is unavailable.
 - Declare the inline chain when opening the run: `run start --type <T> --shards <n> --inline
-  "stateful:<what state>"`. Undeclared, a planned multi-shard run whose main thread keeps working
+  "stateful:<what state>"`. The reason must name the live state; `run start` rejects any other
+  reason, and an `--inline` declared only after a dispatch reminder is recorded as retroactive. Undeclared, a planned multi-shard run whose main thread keeps working
   with no subagent started gets one reminder from the flow hooks, and the audit counts it.
 - Name the real seam you will split at, e.g. iOS simulator vs Android emulator: independent devices
   with independent state are parallel shards even when each one is inline inside.

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", "role_dispatches", "generic_dispatches"],
+      "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", "live_calls"],
       "properties": {
         "task_id": { "type": "string", "minLength": 1 },
         "task_type": { "type": ["string", "null"], "enum": ["INCIDENT", "FEATURE", "BUG_FIX", "REFACTOR", "INVESTIGATION", "DEPLOY", "CONFIG", "REVIEW", "RESEARCH", null] },
@@ -18,7 +18,7 @@
         "planned_shards": { "type": ["integer", "null"], "minimum": 1 },
         "subagents_started": { "type": "integer", "minimum": 0 },
         "started_outside_flow": { "type": "boolean" },
-        "inline_reason": { "type": ["string", "null"], "description": "Why the shards stay inline, e.g. stateful:browser — a live state no subagent can inherit." },
+        "inline_reason": { "type": ["string", "null"], "pattern": "^stateful:\\s*\\S", "description": "Why the shards stay inline, e.g. stateful:browser — a live state no subagent can inherit." },
         "main_work_calls": { "type": "integer", "minimum": 0 },
         "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." },
@@ -26,7 +26,10 @@
         "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, …)." }
+        "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." },
+        "live_calls": { "type": "integer", "minimum": 0, "description": "Main-thread calls that read a live source (ssh, remote databases, cluster/cloud CLIs, HTTP clients)." }
       }
     },
     "session": {
@@ -48,7 +51,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", "role_dispatches", "generic_dispatches", "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", "live_calls", "role_dispatches", "generic_dispatches", "closed_by"],
       "properties": {
         "session": { "type": "string", "minLength": 1 },
         "task_id": { "type": ["string", "null"] },
@@ -65,6 +68,8 @@
         "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" },
+        "live_calls": { "type": "integer", "minimum": 0 },
         "role_dispatches": { "type": "integer", "minimum": 0 },
         "generic_dispatches": { "type": "integer", "minimum": 0 },
         "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end", "session_end"] }