llm-orchestrator 1.2.6 → 1.2.8

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.6",
+  "version": "1.2.8",
   "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, queries a live source twice, 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,7 +376,7 @@ 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 (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
+- 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

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

@@ -47,6 +47,16 @@ 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.`;
+}
+
+/** A run declared trivial that is querying live sources. */
+export function overreachLiveNudgeFor(cli = 'llm-orchestrator', live = 2) {
+  return `This task was declared trivial, but it has now queried live sources ${live} times — an investigation over production evidence is not trivial. Reopen it as a typed run (\`${cli} run start --type INCIDENT|INVESTIGATION --shards <n>\`), where independent live sources are shards for collectors.`;
+}
+
 // 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;
@@ -113,6 +123,20 @@ 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;
+// Querying a live source more than once is an investigation, however few calls it takes.
+export const TRIVIAL_LIVE_LIMIT = 2;
+
+// 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)$/;
@@ -208,10 +232,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 };
 }
 
@@ -257,6 +283,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) })),
   };
 }
@@ -284,6 +311,7 @@ function historyLine(session, fields, now) {
     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,
@@ -387,6 +415,7 @@ export function decide(previous, event, now) {
       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.
@@ -406,19 +435,29 @@ export function decide(previous, event, now) {
   if (session.run) {
     const current = session.run;
     current.main_work_calls = (current.main_work_calls ?? 0) + 1;
+    // Live reads count on every run, trivial ones included — they are what fan-out is for.
+    if (event.live) current.live_calls = (current.live_calls ?? 0) + 1;
     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;
+      const grewByLive = (current.live_calls ?? 0) >= TRIVIAL_LIVE_LIMIT;
+      if (!current.overreach_nudged && (grewByEdits || grewByWork || grewByLive)) {
         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 }
+          : grewByLive
+            ? { additionalContext: overreachLiveNudgeFor(undefined, current.live_calls), kind: 'overreach', live: current.live_calls }
+            : { additionalContext: overreachWorkNudgeFor(undefined, current.main_work_calls), kind: 'overreach', calls: current.main_work_calls };
       }
       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;
+    // 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
       && nudges < allowed && current.main_work_calls >= step * (nudges + 1)) {
       current.dispatch_nudged = true;
@@ -565,7 +604,8 @@ export async function handleHook({ payload, project, now = Date.now(), cli = 'll
   // 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 === 'dispatch_followup' ? dispatchFollowupFor(cli, result.output.planned, result.output.taskType)
-    : result.output.kind === 'overreach' ? overreachNudgeFor(cli, result.output.files)
+    : result.output.kind === 'overreach' ? (result.output.live ? overreachLiveNudgeFor(cli, result.output.live)
+      : result.output.calls ? overreachWorkNudgeFor(cli, result.output.calls) : overreachNudgeFor(cli, result.output.files))
       : nudgeFor(cli);
   return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
 }
@@ -616,7 +656,7 @@ export function adherenceSummary(lines) {
     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.6",
+  "version": "1.2.8",
   "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", "dispatch_nudges", "inline_after_nudge"],
+      "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." },
@@ -28,7 +28,8 @@
         "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." }
+        "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": {
@@ -50,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", "inline_after_nudge", "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"] },
@@ -68,6 +69,7 @@
         "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"] }