llm-orchestrator 1.2.1 → 1.2.3

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

package/README.md

@@ -1,6 +1,22 @@
 <!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
 # llm-orchestrator
 
+I got tired of babysitting long AI coding tasks — splitting work manually, keeping agents in sync, and checking whether “done” actually meant done.
+So I built LLM Orchestrator.
+
+Write /task once.
+It:
+
+→ plans the work
+
+→ shards it across parallel subagents
+
+→ gates each phase
+
+→ verifies the result before claiming it’s done
+
+Built for the kind of tasks where one agent and one context window simply aren’t enough.
+
 ## License
 
 [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). Use, copy, adapt and redistribute freely, including commercially, as long as you credit **Bogdan-Gabriel Torcescu** (https://www.linkedin.com/in/bogdantorcescu/), link the license, note your changes and keep the embedded attribution markers. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
@@ -348,6 +364,10 @@ 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.
+- Trivial is the narrow exception — a one-line change such as a typo or a version bump. A run
+  declared trivial that then edits a second file or touches tests gets one reminder to reopen it as
+  a typed run, and counts as `trivial_overreach` in the audit. Trivial runs close at the end of the
+  turn (`Stop` hook), so single-prompt sessions still reach the history.
 - A run opened with two or more shards whose main thread keeps doing the work — six work calls, no
   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

package/adapters/hooks.mjs

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

package/hooks/hooks.json

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

package/lib/flow-gate.mjs

@@ -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, rmdir, stat, writeFile } from 'node:fs/promises';
+import { appendFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 /**
@@ -23,7 +23,7 @@ import { join } from 'node:path';
  * `llm-orchestrator` is not on PATH unless installed from npm.
  */
 export function nudgeFor(cli = 'llm-orchestrator') {
-  return `No orchestrate-core run is open for this task. Classify it and plan before continuing (\`${cli} run start --type <TYPE>\`), or declare it trivial (\`${cli} run start --trivial "<reason>"\`).`;
+  return `No orchestrate-core run is open for this task. Classify it and plan before continuing (\`${cli} run start --type <TYPE> --shards <n>\`). Declare it trivial (\`${cli} run start --trivial "<reason>"\`) only for a one-line change such as a typo or a version bump — a bug fix with a regression test, or work across two files, is a typed run.`;
 }
 
 export const NUDGE = nudgeFor();
@@ -36,6 +36,28 @@ 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>"\`).`;
 }
 
+/** A run declared trivial has outgrown the declaration. */
+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.`;
+}
+
+// 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;
+const PATCH_FILE = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
+
+function editedPaths(toolName, input) {
+  if (!EDIT_TOOLS.has(toolName.toLowerCase())) return [];
+  const command = commandOf(input);
+  if (command && command.includes('*** Begin Patch')) return [...command.matchAll(PATCH_FILE)].map((match) => match[1].trim());
+  const path = filePathOf(input);
+  return path ? [path] : [];
+}
+
+function pathHash(path) {
+  return createHash('sha256').update(path).digest('hex').slice(0, 12);
+}
+
 // Main-thread work calls tolerated after run start before the dispatch nudge.
 export const DISPATCH_THRESHOLD = 6;
 
@@ -167,6 +189,7 @@ export function normalizePayload(raw) {
   const id = (value) => (typeof value === 'string' && value ? value : null);
   if (eventName === 'UserPromptSubmit') return { kind: 'prompt', session, isSubagent, key: keyOf(eventName, id(payload.prompt_id) ?? id(payload.turn_id)) };
   if (eventName === 'SubagentStart') return { kind: 'subagent', session, isSubagent, key: keyOf(eventName, id(payload.agent_id)) };
+  if (eventName === 'Stop') return { kind: 'stop', session, isSubagent };
   if (eventName !== 'PreToolUse') return { kind: 'other', session, isSubagent };
 
   const toolName = String(payload.tool_name ?? '');
@@ -190,6 +213,7 @@ export function normalizePayload(raw) {
     nonWork: NON_WORK_TOOLS.has(toolName.toLowerCase()),
     loadsEntrypoint,
     readOnly,
+    edits: editedPaths(toolName, input).map((editedPath) => ({ hash: pathHash(editedPath), test: TEST_PATH.test(editedPath) })),
   };
 }
 
@@ -214,6 +238,7 @@ function historyLine(session, fields, now) {
     skipped_flow: Boolean(fields.skipped_flow),
     inline_reason: fields.inline_reason ?? null,
     dispatch_nudged: Boolean(fields.dispatch_nudged),
+    overreach: Boolean(fields.overreach_nudged),
     closed_by: fields.closed_by,
   };
 }
@@ -258,6 +283,15 @@ export function decide(previous, event, now) {
     return { session, output, history };
   }
 
+  if (event.kind === 'stop') {
+    // A trivial run lasts one turn; closing it here keeps single-prompt sessions in history.
+    if (session.run?.trivial && !event.isSubagent) {
+      history.push(closeRun(session, now, 'turn_end'));
+      session.run = null;
+    }
+    return { session, output, history };
+  }
+
   if (event.kind === 'subagent') {
     if (session.run) session.run.subagents_started += 1;
     else session.subagents_without_run += 1;
@@ -280,6 +314,9 @@ export function decide(previous, event, now) {
       inline_reason: event.run.inline,
       main_work_calls: 0,
       dispatch_nudged: false,
+      edited_files: [],
+      touched_tests: false,
+      overreach_nudged: false,
     };
     // The work already done is accounted for on the run itself now.
     session.worked_without_run = false;
@@ -298,6 +335,15 @@ export function decide(previous, event, now) {
   if (session.run) {
     const current = session.run;
     current.main_work_calls = (current.main_work_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)) {
+        current.overreach_nudged = true;
+        output = { additionalContext: overreachNudgeFor(undefined, current.edited_files.length), kind: 'overreach', files: current.edited_files.length };
+      }
+      return { session, output, history };
+    }
     if ((current.planned_shards ?? 0) >= 2 && current.subagents_started === 0 && !current.inline_reason
       && !current.dispatch_nudged && current.main_work_calls >= DISPATCH_THRESHOLD) {
       current.dispatch_nudged = true;
@@ -366,18 +412,37 @@ const LOCK_STALE_MS = 5000;
  * 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.
  */
+/** A lock whose recorded owner process no longer exists was left by a killed handler. */
+async function ownerIsDead(lock) {
+  try {
+    const pid = Number.parseInt(await readFile(join(lock, 'owner'), 'utf8'), 10);
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return error.code === 'ESRCH';
+  }
+}
+
+async function releaseLock(lock) {
+  await rm(lock, { recursive: true, force: true }).catch(() => {});
+}
+
 async function withSessionLock(path, work) {
   const lock = `${path}.lock`;
   const deadline = Date.now() + LOCK_WAIT_MS;
   while (true) {
     try {
       await mkdir(lock);
+      await writeFile(join(lock, 'owner'), `${process.pid}\n`).catch(() => {});
       break;
     } catch (error) {
       if (error.code !== 'EEXIST') throw error;
+      // Harnesses kill hooks that overrun their timeout; a lock they held must not
+      // swallow every event behind it until the stale timeout.
       const held = await stat(lock).then((info) => Date.now() - info.mtimeMs).catch(() => 0);
-      if (held > LOCK_STALE_MS) {
-        await rmdir(lock).catch(() => {});
+      if (held > LOCK_STALE_MS || await ownerIsDead(lock)) {
+        await releaseLock(lock);
         continue;
       }
       if (Date.now() > deadline) throw new Error('ledger session is locked');
@@ -387,13 +452,16 @@ async function withSessionLock(path, work) {
   try {
     return await work();
   } finally {
-    await rmdir(lock).catch(() => {});
+    await releaseLock(lock);
   }
 }
 
 export async function handleHook({ payload, project, now = Date.now(), cli = 'llm-orchestrator' }) {
   const event = normalizePayload(payload);
   if (event.kind === 'other') return null;
+  // Subagent tool calls change nothing (they work under the parent's run), so they
+  // take no lock and do no I/O — a busy subagent must not starve the parent's events.
+  if (event.kind === 'tool' && event.isSubagent) return null;
   // An explicit run command opts the project in; anything else needs the project to use the core.
   if (!event.run && !(await projectUsesOrchestrator(project))) return null;
   const directory = await ensureLedger(project);
@@ -417,7 +485,9 @@ 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) : nudgeFor(cli);
+  const text = result.output.kind === 'dispatch' ? dispatchNudgeFor(cli, result.output.planned)
+    : result.output.kind === 'overreach' ? overreachNudgeFor(cli, result.output.files)
+      : nudgeFor(cli);
   return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
 }
 
@@ -462,6 +532,7 @@ 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,
+    trivial_overreach: lines.filter((line) => line.trivial && line.overreach).length,
     below_fan_out: lines.filter((line) => EVIDENCE_TYPES.has(line.task_type) && !line.inline_reason && (line.planned_shards ?? 0) < 2).length,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-orchestrator",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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/protocol.md

@@ -43,7 +43,10 @@ are still dispatched — see "A shard ends where state ends" in [dispatch](polic
 
 **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.
+declaration and its reason are recorded; an undeclared skip is recorded as a skipped flow. A bug
+fix that needs a regression test, or any change across two or more files, is **not** trivial — it
+is a typed run. A trivial run that grows past that line gets one reminder to reopen it as a typed
+run, and the audit counts it as `trivial_overreach`. A trivial run lasts one turn.
 
 ```json
 {

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"],
+      "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"],
       "properties": {
         "task_id": { "type": "string", "minLength": 1 },
         "task_type": { "type": ["string", "null"], "enum": ["INCIDENT", "FEATURE", "BUG_FIX", "REFACTOR", "INVESTIGATION", "DEPLOY", "CONFIG", "REVIEW", "RESEARCH", null] },
@@ -20,7 +20,10 @@
         "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" }
+        "dispatch_nudged": { "type": "boolean" },
+        "edited_files": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{12}$" }, "description": "Short hashes of edited paths — never the paths themselves." },
+        "touched_tests": { "type": "boolean" },
+        "overreach_nudged": { "type": "boolean" }
       }
     },
     "session": {
@@ -42,7 +45,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", "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", "closed_by"],
       "properties": {
         "session": { "type": "string", "minLength": 1 },
         "task_id": { "type": ["string", "null"] },
@@ -58,7 +61,8 @@
         "skipped_flow": { "type": "boolean" },
         "inline_reason": { "type": ["string", "null"] },
         "dispatch_nudged": { "type": "boolean" },
-        "closed_by": { "enum": ["run_close", "next_prompt", "succession"] }
+        "overreach": { "type": "boolean", "description": "A trivial run that edited two or more files or its tests." },
+        "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end"] }
       }
     }
   }