llm-orchestrator 1.2.0 → 1.2.1

package/.claude-plugin/marketplace.json

@@ -1,5 +1,6 @@
 {
   "name": "tbogdan",
+  "description": "llm-orchestrator: write /task once and the agent plans, shards across parallel subagents, gates every phase and verifies before claiming done.",
   "owner": {
     "name": "Bogdan-Gabriel Torcescu",
     "url": "https://www.linkedin.com/in/bogdantorcescu/"

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

package/README.md

@@ -348,6 +348,13 @@ more instructions:
   `flow.adherence`: runs, trivial declarations, tasks that skipped the flow, runs started outside
   it, runs opened without a PlanShard count, runs that planned several shards but started no
   subagents, and runs still open.
+- A run opened with two or more shards whose main thread keeps doing the work — six work calls, 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).
 - 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

@@ -9,7 +9,7 @@
  */
 import { parseRunArgs, TASK_TYPES } from '../lib/flow-gate.mjs';
 
-const USAGE = `Usage: llm-orchestrator run start --type <${TASK_TYPES.join('|')}> [--shards N]
+const USAGE = `Usage: llm-orchestrator run start --type <${TASK_TYPES.join('|')}> [--shards N] [--inline "stateful:<what>"]
        llm-orchestrator run start --trivial "<reason>"
        llm-orchestrator run close`;
 
@@ -22,6 +22,6 @@ if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
     process.stderr.write(`${USAGE}\n`);
     process.exitCode = 1;
   } else {
-    process.stdout.write(`${JSON.stringify({ run: parsed.action, ...(parsed.action === 'start' ? { type: parsed.type, trivial: parsed.trivial, shards: parsed.shards, reason: parsed.reason } : {}) })}\n`);
+    process.stdout.write(`${JSON.stringify({ run: parsed.action, ...(parsed.action === 'start' ? { type: parsed.type, trivial: parsed.trivial, shards: parsed.shards, reason: parsed.reason, inline: parsed.inline } : {}) })}\n`);
   }
 }

package/lib/flow-gate.mjs

@@ -14,7 +14,7 @@
  * tool inputs or file contents. `doctor` reads it back as the adherence audit.
  */
 import { createHash, randomUUID } from 'node:crypto';
-import { appendFile, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { appendFile, mkdir, readdir, readFile, rename, rmdir, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 /**
@@ -28,6 +28,20 @@ export function nudgeFor(cli = 'llm-orchestrator') {
 
 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>"\`).`;
+}
+
+// Main-thread work calls tolerated after run start before the dispatch nudge.
+export const DISPATCH_THRESHOLD = 6;
+
+// Evidence-gathering flows: their first phase fans out across independent sources.
+const EVIDENCE_TYPES = new Set(['INCIDENT', 'INVESTIGATION', 'RESEARCH']);
+
 export const TASK_TYPES = ['INCIDENT', 'FEATURE', 'BUG_FIX', 'REFACTOR', 'INVESTIGATION', 'DEPLOY', 'CONFIG', 'REVIEW', 'RESEARCH'];
 
 export const LEDGER_DIRECTORY = '.orchestrator-run';
@@ -46,7 +60,7 @@ const RUN_COMMAND = /(^|[\s/"'])llm-orchestrator(?:\.mjs)?["']?\s+run\s+(start|c
 // come before the run is opened at step 4. Once the entrypoint is loaded, these do not
 // count as starting work; edits, writes, dispatches and other shell commands still do.
 const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob', 'ls', 'view', 'list', 'notebookread', 'webfetch', 'websearch']);
-const READ_ONLY_COMMAND = /^\s*(rtk\s+)?(cat|head|tail|less|bat|ls|tree|find|grep|rg|ag|wc|file|stat|pwd|which|type|command\s+-v|git\s+(status|diff|log|show|ls-files|branch|rev-parse|remote))(\s|$)|--version\b/;
+const READ_ONLY_COMMAND = /^\s*(rtk\s+)?(cat|head|tail|less|bat|ls|tree|find|grep|rg|ag|wc|file|stat|pwd|which|type|echo|printf|sort|uniq|command\s+-v|git\s+(status|diff|log|show|ls-files|branch|rev-parse|remote))(\s|$)|--version\b/;
 const LOAD_SKILL = /(^|\/)orchestrate(-core)?(\/SKILL\.md)?$/;
 
 /** Every segment of a compound command reads; nothing is redirected into a file. */
@@ -122,16 +136,18 @@ export function parseRunArgs(args) {
   let type = null;
   let shards = null;
   let trivial = null;
+  let inline = null;
   for (let index = 0; index < rest.length; index += 1) {
     const flag = rest[index];
     const value = rest[index + 1];
     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; }
   }
-  if (trivial !== null) return { action: 'start', trivial: true, reason: trivial || null, type: null, shards: null };
+  if (trivial !== null) return { action: 'start', trivial: true, reason: trivial || null, type: null, shards: null, inline: null };
   if (!TASK_TYPES.includes(type)) return null;
-  return { action: 'start', trivial: false, reason: null, type, shards: Number.isInteger(shards) && shards > 0 ? shards : null };
+  return { action: 'start', trivial: false, reason: null, type, shards: Number.isInteger(shards) && shards > 0 ? shards : null, inline };
 }
 
 function keyOf(eventName, value) {
@@ -196,6 +212,8 @@ function historyLine(session, fields, now) {
     subagents_started: fields.subagents_started ?? 0,
     started_outside_flow: Boolean(fields.started_outside_flow),
     skipped_flow: Boolean(fields.skipped_flow),
+    inline_reason: fields.inline_reason ?? null,
+    dispatch_nudged: Boolean(fields.dispatch_nudged),
     closed_by: fields.closed_by,
   };
 }
@@ -206,7 +224,7 @@ function closeRun(session, now, closedBy) {
 
 /**
  * Pure state transition: (session, event, now) → { session, output, history }.
- * `output` is either null or `{ additionalContext }`; it has no other shape.
+ * `output` is null or `{ additionalContext, kind }` — a steering sentence, never a decision.
  */
 export function decide(previous, event, now) {
   const session = structuredClone(previous);
@@ -259,6 +277,9 @@ export function decide(previous, event, now) {
       planned_shards: event.run.shards,
       subagents_started: 0,
       started_outside_flow: session.worked_without_run,
+      inline_reason: event.run.inline,
+      main_work_calls: 0,
+      dispatch_nudged: false,
     };
     // The work already done is accounted for on the run itself now.
     session.worked_without_run = false;
@@ -271,7 +292,17 @@ export function decide(previous, event, now) {
   }
 
   if (event.loadsEntrypoint) session.entrypoint_loaded = true;
-  if (event.isSubagent || event.instruction || event.orchestratorCall || event.nonWork || event.loadsEntrypoint || session.run) {
+  if (event.isSubagent || event.instruction || event.orchestratorCall || event.nonWork || event.loadsEntrypoint) {
+    return { session, output, history };
+  }
+  if (session.run) {
+    const current = session.run;
+    current.main_work_calls = (current.main_work_calls ?? 0) + 1;
+    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 = true;
+      output = { additionalContext: dispatchNudgeFor(undefined, current.planned_shards), kind: 'dispatch', planned: current.planned_shards };
+    }
     return { session, output, history };
   }
   // Following the entrypoint: discovery reads before the run opens are step 2–3, not a skip.
@@ -280,7 +311,7 @@ export function decide(previous, event, now) {
   session.worked_without_run = true;
   if (!session.nudged) {
     session.nudged = true;
-    output = { additionalContext: NUDGE };
+    output = { additionalContext: NUDGE, kind: 'start' };
   }
   return { session, output, history };
 }
@@ -326,6 +357,40 @@ export async function projectUsesOrchestrator(project) {
   return false;
 }
 
+const LOCK_WAIT_MS = 2000;
+const LOCK_STALE_MS = 5000;
+
+/**
+ * Claude Code runs matching hooks in parallel, so a plugin install and a CLI
+ * install both handle every event at the same moment. Serialise per session with
+ * an atomic mkdir lock; a lock older than LOCK_STALE_MS belongs to a crashed
+ * handler and is taken over. Failing to lock in time throws — the gate fails open.
+ */
+async function withSessionLock(path, work) {
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  while (true) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const held = await stat(lock).then((info) => Date.now() - info.mtimeMs).catch(() => 0);
+      if (held > LOCK_STALE_MS) {
+        await rmdir(lock).catch(() => {});
+        continue;
+      }
+      if (Date.now() > deadline) throw new Error('ledger session is locked');
+      await new Promise((resolve) => setTimeout(resolve, 5 + Math.random() * 20));
+    }
+  }
+  try {
+    return await work();
+  } finally {
+    await rmdir(lock).catch(() => {});
+  }
+}
+
 export async function handleHook({ payload, project, now = Date.now(), cli = 'llm-orchestrator' }) {
   const event = normalizePayload(payload);
   if (event.kind === 'other') return null;
@@ -333,22 +398,27 @@ export async function handleHook({ payload, project, now = Date.now(), cli = 'll
   if (!event.run && !(await projectUsesOrchestrator(project))) return null;
   const directory = await ensureLedger(project);
   const path = join(directory, 'sessions', sessionFileName(event.session));
-  let session;
-  try {
-    session = JSON.parse(await readFile(path, 'utf8'));
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-    session = emptySession(event.session);
-  }
-  const result = decide(session, event, now);
-  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
-  await writeFile(temporary, `${JSON.stringify(result.session)}\n`);
-  await rename(temporary, path);
-  if (result.history.length > 0) {
-    await appendFile(join(directory, 'history.jsonl'), result.history.map((line) => `${JSON.stringify(line)}\n`).join(''));
-  }
+  const result = await withSessionLock(path, async () => {
+    let session;
+    try {
+      session = JSON.parse(await readFile(path, 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      session = emptySession(event.session);
+    }
+    const next = decide(session, event, now);
+    const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(next.session)}\n`);
+    await rename(temporary, path);
+    if (next.history.length > 0) {
+      await appendFile(join(directory, 'history.jsonl'), next.history.map((line) => `${JSON.stringify(line)}\n`).join(''));
+    }
+    return next;
+  });
   if (!result.output) return null;
-  return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: result.output.additionalContext === NUDGE ? nudgeFor(cli) : result.output.additionalContext } };
+  // 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) : nudgeFor(cli);
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
 }
 
 export async function readHistory(project) {
@@ -391,5 +461,7 @@ export function adherenceSummary(lines) {
     started_outside_flow: lines.filter((line) => line.started_outside_flow).length,
     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,
+    below_fan_out: lines.filter((line) => EVIDENCE_TYPES.has(line.task_type) && !line.inline_reason && (line.planned_shards ?? 0) < 2).length,
   };
 }

package/package.json

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

@@ -282,3 +282,24 @@ Parallel work requires disjoint ownership and a real critical-path reduction; do
 beyond the minimums to satisfy an appearance of breadth, and do not fall below them when independent
 scopes exist. A serial fallback is valid only where no required independence is lost — a reviewer's
 independence is never negotiable.
+
+### A shard ends where state ends
+
+"No independent work exists" is the claim that most often excuses skipping dispatch, so it has a
+definition. Work is **inline** only while it holds live state a fresh subagent cannot inherit — a
+browser session mid-flow (cookies, a half-filled form, an open modal), an interactive SSH shell with
+context, a REPL, a booted simulator — **and** each step depends on the result of the one before.
+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.
+- "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
+  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/protocol.md

@@ -36,6 +36,11 @@ can target it.
 No dispatch, edit or shell command may precede this object. Opening the run
 (`llm-orchestrator run start --type <TASK_TYPE>`) follows it immediately.
 
+**Inline shards.** A run whose shards must stay in the main thread because they hold live state
+(a browser session, an interactive shell, a simulator) says so when it opens:
+`run start --type <T> --shards <n> --inline "stateful:<what>"`. Independent reads around that state
+are still dispatched — see "A shard ends where state ends" in [dispatch](policies/dispatch.md).
+
 **Trivial tasks.** A one-line, obviously scoped change (a typo, a version bump) may skip the full
 flow, but only by declaring it: `llm-orchestrator run start --trivial "<reason>"`. The
 declaration and its reason are recorded; an undeclared skip is recorded as a skipped flow.

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"],
+      "required": ["task_id", "task_type", "trivial", "reason", "opened_at", "planned_shards", "subagents_started", "started_outside_flow", "inline_reason", "main_work_calls", "dispatch_nudged"],
       "properties": {
         "task_id": { "type": "string", "minLength": 1 },
         "task_type": { "type": ["string", "null"], "enum": ["INCIDENT", "FEATURE", "BUG_FIX", "REFACTOR", "INVESTIGATION", "DEPLOY", "CONFIG", "REVIEW", "RESEARCH", null] },
@@ -17,7 +17,10 @@
         "opened_at": { "type": "number" },
         "planned_shards": { "type": ["integer", "null"], "minimum": 1 },
         "subagents_started": { "type": "integer", "minimum": 0 },
-        "started_outside_flow": { "type": "boolean" }
+        "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." },
+        "main_work_calls": { "type": "integer", "minimum": 0 },
+        "dispatch_nudged": { "type": "boolean" }
       }
     },
     "session": {
@@ -39,7 +42,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", "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", "closed_by"],
       "properties": {
         "session": { "type": "string", "minLength": 1 },
         "task_id": { "type": ["string", "null"] },
@@ -53,6 +56,8 @@
         "subagents_started": { "type": "integer", "minimum": 0 },
         "started_outside_flow": { "type": "boolean" },
         "skipped_flow": { "type": "boolean" },
+        "inline_reason": { "type": ["string", "null"] },
+        "dispatch_nudged": { "type": "boolean" },
         "closed_by": { "enum": ["run_close", "next_prompt", "succession"] }
       }
     }