llm-orchestrator 1.2.2 → 1.2.4

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

package/README.md

@@ -367,8 +367,10 @@ more instructions:
 - 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
+  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
   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/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', 'Stop'];
+export const FLOW_EVENTS = ['UserPromptSubmit', 'PreToolUse', 'SubagentStart', 'Stop', 'SessionEnd'];
 
 /** Spell the runtime path through $HOME when it lives there, so committed settings stay portable. */
 export function runtimeCliPath(runtimeRoot) {
@@ -166,6 +166,8 @@ export const OrchestrateFlow = async ({ directory }) => {
         }
         const idle = event?.properties?.sessionID;
         if (event?.type === "session.idle" && idle && !parentOf.has(idle)) gate({ hook_event_name: "Stop", session_id: idle });
+        const ended = info?.id;
+        if (event?.type === "session.deleted" && ended && !parentOf.has(ended)) gate({ hook_event_name: "SessionEnd", session_id: ended });
       } catch {}
     },
     "chat.message": async (input) => {

package/hooks/hooks.json

@@ -44,6 +44,17 @@
           }
         ]
       }
+    ],
+    "SessionEnd": [
+      {
+        "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';
 
 /**
@@ -58,8 +58,9 @@ 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;
+// 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-gathering flows: their first phase fans out across independent sources.
 const EVIDENCE_TYPES = new Set(['INCIDENT', 'INVESTIGATION', 'RESEARCH']);
@@ -188,8 +189,9 @@ 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)) };
+  if (eventName === 'SubagentStart') return { kind: 'subagent', session, isSubagent, key: keyOf(eventName, id(payload.agent_id)), agent: id(payload.agent_id) };
   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 };
 
   const toolName = String(payload.tool_name ?? '');
@@ -283,6 +285,15 @@ export function decide(previous, event, now) {
     return { session, output, history };
   }
 
+  if (event.kind === 'session_end') {
+    // Typed runs outlive turns but not the session: close them so they reach history.
+    if (session.run) {
+      history.push(closeRun(session, now, 'session_end'));
+      session.run = null;
+    }
+    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) {
@@ -293,8 +304,16 @@ export function decide(previous, event, now) {
   }
 
   if (event.kind === 'subagent') {
-    if (session.run) session.run.subagents_started += 1;
-    else session.subagents_without_run += 1;
+    if (session.run) {
+      // Count distinct agents: a resumed subagent fires SubagentStart again, possibly
+      // long after its first start has left the seen-window.
+      const ids = Array.isArray(session.run.subagent_ids) ? session.run.subagent_ids : [];
+      const agentHash = event.agent ? pathHash(event.agent) : null;
+      if (!agentHash || !ids.includes(agentHash)) {
+        session.run.subagents_started += 1;
+        if (agentHash) session.run.subagent_ids = [...ids, agentHash];
+      }
+    } else session.subagents_without_run += 1;
     return { session, output, history };
   }
 
@@ -317,6 +336,7 @@ export function decide(previous, event, now) {
       edited_files: [],
       touched_tests: false,
       overreach_nudged: false,
+      subagent_ids: [],
     };
     // The work already done is accounted for on the run itself now.
     session.worked_without_run = false;
@@ -345,7 +365,7 @@ export function decide(previous, event, now) {
       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 && current.main_work_calls >= DISPATCH_CALLS_PER_SHARD * current.planned_shards) {
       current.dispatch_nudged = true;
       output = { additionalContext: dispatchNudgeFor(undefined, current.planned_shards), kind: 'dispatch', planned: current.planned_shards };
     }
@@ -412,18 +432,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');
@@ -433,13 +472,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);
@@ -511,6 +553,7 @@ export function adherenceSummary(lines) {
     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,
+    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.2",
+  "version": "1.2.4",
   "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/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"],
+      "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"],
       "properties": {
         "task_id": { "type": "string", "minLength": 1 },
         "task_type": { "type": ["string", "null"], "enum": ["INCIDENT", "FEATURE", "BUG_FIX", "REFACTOR", "INVESTIGATION", "DEPLOY", "CONFIG", "REVIEW", "RESEARCH", null] },
@@ -23,7 +23,8 @@
         "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" }
+        "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." }
       }
     },
     "session": {
@@ -62,7 +63,7 @@
         "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." },
-        "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end"] }
+        "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end", "session_end"] }
       }
     }
   }