llm-orchestrator 1.2.0 → 1.2.2

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.2",
   "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,17 @@ 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
+  `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/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/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/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, writeFile } from 'node:fs/promises';
+import { appendFile, mkdir, readdir, readFile, rename, rmdir, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 /**
@@ -23,11 +23,47 @@ 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();
 
+/**
+ * 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>"\`).`;
+}
+
+/** 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;
+
+// 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 +82,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 +158,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) {
@@ -151,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 ?? '');
@@ -174,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) })),
   };
 }
 
@@ -196,6 +236,9 @@ 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),
+    overreach: Boolean(fields.overreach_nudged),
     closed_by: fields.closed_by,
   };
 }
@@ -206,7 +249,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);
@@ -240,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;
@@ -259,6 +311,12 @@ 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,
+      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;
@@ -271,7 +329,26 @@ 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.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;
+      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 +357,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 +403,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 +444,29 @@ 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)
+    : result.output.kind === 'overreach' ? overreachNudgeFor(cli, result.output.files)
+      : nudgeFor(cli);
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
 }
 
 export async function readHistory(project) {
@@ -391,5 +509,8 @@ 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,
+    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.0",
+  "version": "1.2.2",
   "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,9 +36,17 @@ 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.
+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"],
+      "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] },
@@ -17,7 +17,13 @@
         "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" },
+        "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": {
@@ -39,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", "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"] },
@@ -53,7 +59,10 @@
         "subagents_started": { "type": "integer", "minimum": 0 },
         "started_outside_flow": { "type": "boolean" },
         "skipped_flow": { "type": "boolean" },
-        "closed_by": { "enum": ["run_close", "next_prompt", "succession"] }
+        "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"] }
       }
     }
   }