@eventmodelers/cli 1.0.58 → 1.0.59

package/README.md

@@ -220,27 +220,56 @@ reading its own `.eventmodelers/config.json`.
 
 Without `--standalone` the agent only ever answers direct messages. With it, the loop also
 subscribes to the board's own change channel — the same one the canvas and the build agents
-use — and when the board falls quiet after someone edits it, the agent gets a turn nobody
-asked for and decides for itself whether there's something a human collaborator would
-obviously have done: example data on a freshly placed element, a missing attribute on the
-rest of the chain, a screen for an empty SCREEN node, a question comment on a gap. It does at
-most one focused thing per change, adds rather than deletes, and answers `NOOP` when there's
-nothing worth doing (see the "Standalone board-change turns" section in
+use — and the agent becomes a background collaborator on the board: when it falls quiet after
+someone edits it, and again whenever the board has simply been sitting still for a while
+(`EVENTMODELERS_STANDALONE_IDLE_MS`), the agent gets a turn nobody asked for.
+
+What it does with that turn is *not* "react to the last event". The changed nodes are a
+notification telling it where to look. The agent itself analyses all of them against the model
+as a whole — each changed area in its slice and chain, plus whatever else is still obviously
+unfinished — and decides what needs doing. Then it fans the work out: **one subagent per piece
+of work that needs doing, all dispatched in parallel** (pieces sharing a slice or chain are
+merged into one agent, so no two agents write to the same area). The decision stays with the
+main agent; each subagent is an executor that carries out the one piece it was given, invoking
+the matching skill for its own target — example data on a freshly placed element, a missing
+attribute on the rest of the chain, a screen for an empty SCREEN node, a question comment on a
+gap. Nothing needing doing means no agents are spawned at all: the turn adds nothing and
+answers `NOOP` (see the "Standalone board-change turns" section in
 `.agent-modeling-kit/CLAUDE.md`).
 
-Its own writes come back on that same channel and the platform can't tell them apart from a
-human's, so the lane is deliberately damped: it waits for a quiet period, ignores everything
-that arrives while a turn runs or shortly after one ends, and never fires twice in quick
-succession. Override the three windows if the defaults don't suit your board:
+`--max-agents <n>` caps that fan-out, so an unattended turn's cost stays bounded — default 5:
+
+```bash
+npx @eventmodelers/cli run --standalone --board-id <uuid> --max-agents 3
+```
+
+Work sharing a slice or chain is merged into one agent first (that part is about not clobbering
+the board, not about the cap); if more pieces are still left than the cap allows, the agent
+dispatches the most valuable ones and leaves the rest for a later turn. `--max-agents 1` means
+no subagents at all: the turn does the single most valuable piece itself. The cap rides along in
+the turn's own instructions rather than being enforced from outside — the `claude` process is
+what spawns the agents — so it's a budget the agent is told to keep, not a hard ceiling.
+
+Every event that arrives is remembered until a turn carries it — including events that land
+while a turn is running. Its own writes come back on that same channel and the platform can't
+tell them apart from a human's, so those are *labelled* for the agent rather than discarded,
+and the lane is damped on timing instead: it waits for a quiet period (but not forever), waits
+out the echo window of its last turn, never fires twice in quick succession, and widens that
+floor each time it answers `NOOP`, so a finished board goes quiet by itself. Override the
+windows if the defaults don't suit your board:
 
 | Env var | Default | What it controls |
 |---|---|---|
-| `EVENTMODELERS_STANDALONE_DEBOUNCE_MS` | `8000` | quiet period before a board change turns into a turn |
-| `EVENTMODELERS_STANDALONE_ECHO_WINDOW_MS` | `20000` | after a turn, how long incoming changes are treated as the agent's own echo |
+| `EVENTMODELERS_STANDALONE_DEBOUNCE_MS` | `8000` | quiet period before buffered board changes turn into a turn |
+| `EVENTMODELERS_STANDALONE_MAX_WAIT_MS` | `90000` | cap on that quiet period, so a board being edited continuously still gets a turn |
+| `EVENTMODELERS_STANDALONE_ECHO_WINDOW_MS` | `20000` | after a turn, how long incoming changes are labelled as probably the agent's own echo |
 | `EVENTMODELERS_STANDALONE_MIN_INTERVAL_MS` | `60000` | floor between two self-directed turns |
+| `EVENTMODELERS_STANDALONE_BACKOFF_CAP_MS` | `900000` | ceiling that floor doubles up to while turns keep answering `NOOP` |
+| `EVENTMODELERS_STANDALONE_IDLE_MS` | `900000` | with nothing happening at all, how long before the agent reviews the model anyway (`0` disables it) |
 
-Direct prompts always outrank the agent's own initiative — a standalone turn waits while
-anything from the prompt queue is running.
+Direct prompts always outrank the agent's own initiative — a self-directed turn waits while
+anything from the prompt queue is running, and the changes it was about keep accumulating
+meanwhile.
 
 ### Installing skills globally
 

package/cli.js

@@ -393,6 +393,26 @@ async function promptPasteBlock() {
 // rather than silently disabling platform sync.
 const DEFAULT_BASE_URL = 'https://api.eventmodelers.ai';
 
+// How many subagents a self-directed --standalone turn may dispatch at once. It's a
+// budget, not a mechanism: the turn runs inside one `claude` process, which is what
+// actually spawns the agents, so the cap reaches it as part of the turn's instructions
+// (buildStandaloneTurn) rather than as something the CLI can enforce from outside. Five
+// keeps an unattended turn's cost in the same ballpark as a single prompt turn while
+// still covering the usual burst — a handful of nodes across a couple of slices.
+const DEFAULT_MAX_AGENTS = 5;
+
+// `--max-agents` is a cost guard, so a typo must not silently turn into "no limit" or
+// into the default: anything that isn't a positive integer is rejected outright.
+function parseMaxAgents(raw) {
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_MAX_AGENTS;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    console.error(`❌ --max-agents must be a positive integer (got "${raw}").`);
+    process.exit(1);
+  }
+  return n;
+}
+
 // This CLI's own version, stamped into every install manifest so the global modeling
 // install can tell whether it was written by the version now running (see ensureGlobalKit).
 const CLI_VERSION = readJsonSafe(join(__dirname, 'package.json')).version || '0.0.0';
@@ -1595,7 +1615,7 @@ async function ensureGlobalKit(baseUrl) {
 // question, sketch a screen. Without the flag that channel is still subscribed on
 // the same connection and every event on it is dropped, so the two modes differ by
 // one filter rather than by a whole second realtime stack.
-async function runModeling(kitDir, projectDir, verbose = false, standalone = false, overrides = null) {
+async function runModeling(kitDir, projectDir, verbose = false, standalone = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS) {
   const configLibPath = join(kitDir, 'lib', 'config.js');
   if (!existsSync(configLibPath)) {
     console.error(`❌ ${relative(process.cwd(), configLibPath)} not found — --modeling needs a kit installed via \`init --modeling\`.`);
@@ -1648,7 +1668,7 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
   function withSessionHeader(body) {
     if (!firstTurn) return body;
     firstTurn = false;
-    return `MODE=modeling token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}\n\n${QUESTIONING_RULE}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
+    return `MODE=modeling token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''}\n\n${QUESTIONING_RULE}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
   }
 
   function buildTurn(p) {
@@ -1731,7 +1751,9 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
       lastTurnEndedAt = Date.now();
       const turn = pending;
       pending = null;
-      if (turn) (msg.is_error ? turn.reject(new Error(msg.result || 'Claude turn errored')) : turn.resolve());
+      // The result text is what a standalone turn's NOOP/DONE answer rides in — the
+      // self-directed lane reads it to decide whether to back off (dispatchStandaloneTurn).
+      if (turn) (msg.is_error ? turn.reject(new Error(msg.result || 'Claude turn errored')) : turn.resolve(msg.result ?? ''));
     }
   }
 
@@ -1769,7 +1791,7 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
   spawnProcess();
   log(
     standalone
-      ? 'standalone: ON — reacting to direct prompts AND to board changes on its own initiative'
+      ? `standalone: ON — reacting to direct prompts AND to board changes on its own initiative (max ${maxAgents} subagent(s) per self-directed turn)`
       : 'standalone: off — reacting to direct prompts only (board changes are dropped)',
   );
 
@@ -1808,6 +1830,9 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
       }
     } finally {
       draining = false;
+      // A prompt turn counts as activity: the board isn't idle just because nobody edited
+      // it while the agent was busy answering someone.
+      armIdleReview();
     }
   }
 
@@ -1823,55 +1848,91 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
   // later adds to these payloads lands here without a client change.
   const BOARD_CHANGE_EVENTS = ['node:created', 'node:changed', 'node:deleted', 'edge:added', 'edge:removed', 'board:cleared'];
 
-  // Three guards, because a board event can't tell you who caused it: the platform
+  // Four knobs, because a board event can't tell you who caused it: the platform
   // attributes an API token's writes to the org owner's user_id, so on this channel the
-  // agent's own edits are indistinguishable from the human's.
+  // agent's own edits are indistinguishable from the human's. They all govern *when* a
+  // self-directed turn fires — never whether an event is remembered. Everything that
+  // arrives is buffered (see onBoardEvent): an event seen while a turn runs, or inside the
+  // echo window, is only *marked* as possibly the agent's own write, so a burst that
+  // straddles a turn boundary still reaches the next turn instead of being thrown away and
+  // leaving the agent looking at whichever single event happened to land last.
   //   DEBOUNCE     — one gesture (place a node, drag a column) fans out into several
   //                  events; wait for the board to fall quiet, then send a single turn.
-  //   ECHO_WINDOW  — anything arriving while a turn runs, or within this long after one
-  //                  ends, is assumed to be that turn's own writes coming back, and dropped.
+  //   MAX_WAIT     — cap on that quiet period: a board someone keeps editing never falls
+  //                  quiet, and the debounce alone would slide forever.
+  //   ECHO_WINDOW  — how long after a turn its own writes are expected back; changes in
+  //                  that window are labelled, and the next turn waits it out.
   //   MIN_INTERVAL — a floor between self-directed turns, so a mistake upstream can't
-  //                  become a self-feeding loop burning tokens unattended.
+  //                  become a self-feeding loop burning tokens unattended. Doubles per
+  //                  consecutive NOOP up to BACKOFF_CAP, and resets as soon as a turn
+  //                  actually does something.
+  //   IDLE         — with nothing at all happening on the board, how long before the agent
+  //                  looks the model over anyway (a BOARD_REVIEW turn). 0 disables it, and
+  //                  it answers to the same MIN_INTERVAL backoff, so a board with nothing
+  //                  left to do goes quiet by itself rather than being swept every IDLE ms.
   const envMs = (name, fallback) => {
     const raw = Number(process.env[name]);
     return Number.isFinite(raw) && raw >= 0 ? raw : fallback;
   };
   const STANDALONE_DEBOUNCE_MS = envMs('EVENTMODELERS_STANDALONE_DEBOUNCE_MS', 8_000);
+  const STANDALONE_MAX_WAIT_MS = envMs('EVENTMODELERS_STANDALONE_MAX_WAIT_MS', 90_000);
   const STANDALONE_ECHO_WINDOW_MS = envMs('EVENTMODELERS_STANDALONE_ECHO_WINDOW_MS', 20_000);
   const STANDALONE_MIN_INTERVAL_MS = envMs('EVENTMODELERS_STANDALONE_MIN_INTERVAL_MS', 60_000);
-
-  const observed = new Map(); // node_id (or '(board)') -> event types seen since the last standalone turn
+  const STANDALONE_BACKOFF_CAP_MS = envMs('EVENTMODELERS_STANDALONE_BACKOFF_CAP_MS', 15 * 60_000);
+  const STANDALONE_IDLE_MS = envMs('EVENTMODELERS_STANDALONE_IDLE_MS', 15 * 60_000);
+
+  // node_id (or '(board)') -> { types: Set<string>, count: number, maybeOwn: boolean }
+  // for everything seen since the last self-directed turn. `maybeOwn` stays true only
+  // while every event for that node arrived while a turn was running or inside the echo
+  // window — one event from outside that window and the node is a real change again.
+  const observed = new Map();
   let observedCount = 0;
   let seqLo = null;
   let seqHi = null;
   let standaloneTimer = null;
+  let firstObservedAt = 0; // start of the current burst — MAX_WAIT is measured from here
   let lastStandaloneAt = 0;
+  let noopStreak = 0;
+
+  // The floor between self-directed turns, widened while the agent keeps finding nothing
+  // to do. A quiet board therefore costs a turn every MIN_INTERVAL, then 2×, 4×, … up to
+  // BACKOFF_CAP, instead of one per interval forever.
+  function minIntervalMs() {
+    return Math.min(STANDALONE_MIN_INTERVAL_MS * 2 ** noopStreak, STANDALONE_BACKOFF_CAP_MS);
+  }
 
   function onBoardEvent(type, payload) {
     if (!standalone) {
       if (verbose) log(`board event ${type} dropped — not running with --standalone`);
       return;
     }
-    if (pending || draining) {
-      if (verbose) log(`board event ${type} dropped — a turn is in flight (assumed own write)`);
-      return;
-    }
     const sinceTurn = Date.now() - lastTurnEndedAt;
-    if (lastTurnEndedAt && sinceTurn < STANDALONE_ECHO_WINDOW_MS) {
-      if (verbose) log(`board event ${type} dropped — ${Math.round(sinceTurn / 1000)}s after a turn (assumed own write)`);
-      return;
-    }
+    const inEchoWindow = !!lastTurnEndedAt && sinceTurn < STANDALONE_ECHO_WINDOW_MS;
+    const maybeOwn = !!pending || draining || inEchoWindow;
     const nodeId = payload?.node_id ?? '(board)';
-    if (!observed.has(nodeId)) observed.set(nodeId, new Set());
-    observed.get(nodeId).add(type);
+    const entry = observed.get(nodeId) ?? { types: new Set(), count: 0, maybeOwn };
+    entry.types.add(type);
+    entry.count += 1;
+    if (!maybeOwn) entry.maybeOwn = false;
+    observed.set(nodeId, entry);
     observedCount += 1;
+    if (!firstObservedAt) firstObservedAt = Date.now();
     const seq = Number(payload?.seq);
     if (Number.isFinite(seq)) {
       if (seqLo === null || seq < seqLo) seqLo = seq;
       if (seqHi === null || seq > seqHi) seqHi = seq;
     }
-    log(`board change: ${type} node=${nodeId}${Number.isFinite(seq) ? ` seq=${seq}` : ''}`);
-    armStandaloneTurn(STANDALONE_DEBOUNCE_MS);
+    log(`board change: ${type} node=${nodeId}${Number.isFinite(seq) ? ` seq=${seq}` : ''}${maybeOwn ? ' (maybe own write)' : ''}`);
+    armStandaloneTurn(nextDelayMs());
+  }
+
+  // Debounce, but never past MAX_WAIT from the first event of the burst, and never before
+  // the echo window of the last turn has run out.
+  function nextDelayMs() {
+    const waitedSoFar = firstObservedAt ? Date.now() - firstObservedAt : 0;
+    const debounce = Math.max(0, Math.min(STANDALONE_DEBOUNCE_MS, STANDALONE_MAX_WAIT_MS - waitedSoFar));
+    const echoLeft = lastTurnEndedAt ? STANDALONE_ECHO_WINDOW_MS - (Date.now() - lastTurnEndedAt) : 0;
+    return Math.max(debounce, echoLeft, 0);
   }
 
   function armStandaloneTurn(delayMs) {
@@ -1882,51 +1943,140 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     }, delayMs);
   }
 
+  // The changed-node list is a *pointer*, not the job: it says which corners of the board
+  // someone just touched. The turn's actual task is for the agent to analyse all of them
+  // against the model as a whole and then fan out — a subagent per piece of work that really
+  // needs doing, running in parallel. Without that framing the agent treats the last event as
+  // its work item and does one narrow thing (or nothing) even when the model needs something
+  // else entirely, which is exactly what a burst of events on several nodes used to degrade
+  // into.
+  // The fan-out budget (`--max-agents`). A turn nobody asked for still costs money, so the
+  // cap is stated in the turn itself — the `claude` process is what spawns the agents, and
+  // the CLI has no way to count them from out here.
+  const AGENT_BUDGET =
+    maxAgents > 1
+      ? `Dispatch at most ${maxAgents} Agents in this turn (--max-agents=${maxAgents}). Merge pieces that share a slice or ` +
+        'chain first — that is a correctness rule, not a way to fit the cap — and if more than that is still left, ' +
+        'take the most valuable pieces up to the cap and leave the rest; a later turn will see them again.'
+      : 'Do not dispatch any Agents in this turn (--max-agents=1) — that budget overrides the fan-out above: do ' +
+        'the single most valuable piece of work yourself, inline, and leave the rest for a later turn.';
+
+  const STANDALONE_TASK =
+    'Nobody asked you for this — you are working on this board in the background, on your own initiative. ' +
+    'The change list above is a notification, not the task: it tells you where something just happened and ' +
+    'which parts of the model to look at first. The task is to judge the model as a whole — each changed area ' +
+    'in its context (its slice, its chain, the timeline around it), plus anything still obviously unfinished ' +
+    'elsewhere — and then get the useful work done. Do not stop at the last event, and do not treat the ' +
+    'nodeId list as the boundary of the work. You do the analysis: look at every entry above, decide what ' +
+    'actually needs doing, and then work in parallel rather than serially — dispatch one Agent per piece of ' +
+    'work that needs doing, all in a single message, merging pieces that share a slice or chain so no two ' +
+    `agents write to the same area. ${AGENT_BUDGET} Follow the "Standalone board-change turns" section of ` +
+    '.agent-modeling-kit/CLAUDE.md, and if the model genuinely needs nothing right now, spawn nothing, change ' +
+    'nothing and reply <promise>NOOP</promise>.';
+
   function buildStandaloneTurn() {
-    const lines = [...observed.entries()].map(([nodeId, types]) => `- ${nodeId}: ${[...types].join(', ')}`);
+    const lines = [...observed.entries()].map(
+      ([nodeId, entry]) =>
+        `- ${nodeId}: ${[...entry.types].join(', ')} (${entry.count}×)${entry.maybeOwn ? ' — possibly your own earlier write' : ''}`,
+    );
     const header = [
       'BOARD_CHANGE',
       `board_id=${cfg.boardId}`,
       `organization_id=${cfg.organizationId}`,
       seqLo !== null ? `seq=${seqLo}${seqHi !== seqLo ? `..${seqHi}` : ''}` : null,
       `events=${observedCount}`,
+      `nodes=${observed.size}`,
     ].filter(Boolean).join(' ');
+    return withSessionHeader(`${header}\nchanged:\n${lines.join('\n')}\n\n${STANDALONE_TASK}`);
+  }
+
+  // No events at all — the board has been sitting still. Same self-directed turn, with the
+  // whole model as its subject instead of a changed corner of it.
+  function buildIdleReviewTurn() {
+    const header = [
+      'BOARD_REVIEW',
+      `board_id=${cfg.boardId}`,
+      `organization_id=${cfg.organizationId}`,
+      `idle_for=${Math.round(STANDALONE_IDLE_MS / 1000)}s`,
+    ].join(' ');
     return withSessionHeader(
-      `${header}\nchanged:\n${lines.join('\n')}\n\n` +
-        'Nobody asked you for this — the board itself changed and you are acting on your own initiative. ' +
-        'Follow the "Standalone board-change turns" section of .agent-modeling-kit/CLAUDE.md: look at what changed, ' +
-        'decide whether there is genuinely useful modeling work to do, do at most one focused piece of it, and if ' +
-        'there is nothing worth doing, change nothing and reply <promise>NOOP</promise>.',
+      `${header}\nchanged: nothing — the board has been quiet.\n\n` +
+        'Nobody asked you for this and nothing changed: you are working on this board in the background, on ' +
+        'your own initiative. Look over the model as a whole and decide what it still needs; for each piece of ' +
+        'work that needs doing, dispatch one Agent, all in a single message so they run in parallel, exactly ' +
+        `as the "Standalone board-change turns" section of .agent-modeling-kit/CLAUDE.md describes. ${AGENT_BUDGET} ` +
+        'If the model needs nothing, spawn nothing, change nothing and reply <promise>NOOP</promise>.',
     );
   }
 
-  async function dispatchStandaloneTurn() {
-    if (!observed.size) return;
+  let idleTimer = null;
+  function armIdleReview() {
+    if (!standalone || !STANDALONE_IDLE_MS) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      idleTimer = null;
+      // A buffer that filled meanwhile has its own timer — let that turn carry the work.
+      if (observed.size || standaloneTimer || pending || draining) {
+        armIdleReview();
+        return;
+      }
+      dispatchStandaloneTurn({ idle: true }).catch((err) => log(`idle review dispatch error: ${err.message}`));
+    }, STANDALONE_IDLE_MS);
+  }
+
+  async function dispatchStandaloneTurn({ idle = false } = {}) {
+    if (!idle && !observed.size) return;
     // A direct message always outranks the agent's own initiative — re-arm instead of
     // queueing behind the prompt lane, so the buffer just keeps collecting meanwhile.
     if (pending || draining) {
-      armStandaloneTurn(STANDALONE_DEBOUNCE_MS);
+      if (idle) armIdleReview();
+      else armStandaloneTurn(nextDelayMs());
       return;
     }
-    const waitLeft = STANDALONE_MIN_INTERVAL_MS - (Date.now() - lastStandaloneAt);
+    const waitLeft = minIntervalMs() - (Date.now() - lastStandaloneAt);
     if (lastStandaloneAt && waitLeft > 0) {
-      armStandaloneTurn(waitLeft);
+      if (idle) armIdleReview();
+      else armStandaloneTurn(waitLeft);
       return;
     }
-    const text = buildStandaloneTurn();
-    log(`standalone turn: ${observedCount} board event(s) on ${observed.size} node(s)`);
+    const text = idle ? buildIdleReviewTurn() : buildStandaloneTurn();
+    if (idle) {
+      log(`standalone review turn: board quiet for ${Math.round(STANDALONE_IDLE_MS / 1000)}s`);
+    } else {
+      const ownOnly = [...observed.values()].every((entry) => entry.maybeOwn);
+      log(
+        `standalone turn: ${observedCount} board event(s) on ${observed.size} node(s)` +
+          `${ownOnly ? ' (all possibly own writes)' : ''}`,
+      );
+    }
     observed.clear();
     observedCount = 0;
     seqLo = null;
     seqHi = null;
+    firstObservedAt = 0;
     lastStandaloneAt = Date.now();
     try {
-      await runClaudeWarm(text);
+      const result = await runClaudeWarm(text);
+      // NOOP is the agent saying the board needs nothing — widen the floor so a finished
+      // board isn't revisited at full rate. Any real contribution resets it.
+      if (/NOOP/.test(String(result ?? ''))) {
+        noopStreak += 1;
+        log(`standalone turn: NOOP (${noopStreak} in a row — next no sooner than ${Math.round(minIntervalMs() / 1000)}s)`);
+      } else {
+        noopStreak = 0;
+      }
     } catch (err) {
       log(`standalone turn failed: ${err.message}`);
+    } finally {
+      // Events that arrived while this turn ran are still in the buffer — give them a turn
+      // of their own once the echo window has passed, instead of waiting for the next edit.
+      if (observed.size) armStandaloneTurn(nextDelayMs());
+      armIdleReview();
     }
   }
 
+  armIdleReview();
+
   const channelName = `org:${cfg.organizationId}`;
   const realtime = await createRealtimeAdapter(cfg, realtimeToken);
 
@@ -2458,7 +2608,8 @@ credentialFlags(program
   .option('--ollama', 'Use ralph-ollama.js instead of the default Claude runner (build-kit stacks only)')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
   .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
-  .option('--standalone', 'Let the modeling agent act on its own initiative: on top of direct prompts it subscribes to the board\'s change channel (like the build agents do) and, whenever the board goes quiet after an edit, decides for itself what a human collaborator would do next — fill in examples on a new node, post a comment, sketch a screen. Implies --modeling.')
+  .option('--standalone', 'Let the modeling agent work the board in the background, on its own initiative: on top of direct prompts it subscribes to the board\'s change channel (like the build agents do) and, whenever the board goes quiet after an edit — or has simply been idle for a while — it takes a turn nobody asked for. Changed nodes are a notification, not the task: it judges the model as a whole and fans the work out over parallel subagents, one per changed area (examples on a new node, a missing attribute along a chain, a screen, a question comment). Implies --modeling.')
+  .option('--max-agents <n>', 'Cap how many subagents a self-directed --standalone turn may dispatch at once, to bound what an unattended agent can spend per turn. The agent merges work that shares a slice or chain first, then takes the most valuable pieces up to this many and leaves the rest for a later turn. 1 makes it do the single most valuable piece itself, without spawning anything. Default 5. Ignored without --standalone — prompt turns are one piece of work by definition.', '5')
   .option('--global', 'Run the modeling agent from the global install (~/.eventmodelers/kit), initializing it on first use, and ignore any kit in this directory. This is also what --modeling/--standalone fall back to on their own when nothing is installed here — pass it explicitly to prefer the global install over a local one. Credentials come from the flags below, EVENTMODELERS_* env vars, or ~/.eventmodelers/boards/<board>.json, so nothing is written into the current directory.')
   .option('--local', 'Skip platform config/credential lookup entirely and run the local-only loop (no board sync, no realtime agent) — even if .eventmodelers/config.json has credentials (build-kit stacks only)')
   .option('--verbose', 'Log every tool call\'s full input (commands, skill args, file paths) and assistant reasoning text. Default is condensed, high-level per-step logging only.')
@@ -2466,6 +2617,13 @@ credentialFlags(program
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
     const cwd = process.cwd();
+    // Validated up front, before any runner is selected: a cost guard given as garbage
+    // should fail on the spot, not once the loop is already up — and a cap passed where
+    // nothing will read it is worth saying out loud rather than ignoring silently.
+    const maxAgents = parseMaxAgents(opts.maxAgents);
+    if (command.getOptionValueSource('maxAgents') === 'cli' && !opts.standalone) {
+      console.log('ℹ️  --max-agents only applies to --standalone turns; ignoring it here.');
+    }
     // Both kit dirs can be installed side by side (e.g. running a build-kit and a
     // modeling-kit agent from the same project). findInstalledKitDir only ever
     // returns its first fixed-order match, which would silently prefer one stack
@@ -2529,7 +2687,7 @@ credentialFlags(program
       const shown = relative(cwd, kitDir);
       await new Promise((res) => process.stdout.write(`▶ Starting modeling loop (warm Claude process) for ${shown && !shown.startsWith('..') ? shown : kitDir}...\n\n`, res));
       try {
-        await runModeling(kitDir, projectDir, !!opts.verbose, !!opts.standalone, overrides);
+        await runModeling(kitDir, projectDir, !!opts.verbose, !!opts.standalone, overrides, maxAgents);
       } catch (err) {
         console.error('[modeling] Fatal:', err);
         process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.58",
+  "version": "1.0.59",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/stacks/modeling-kit/templates/kit/CLAUDE.md

@@ -18,10 +18,12 @@ every later turn just because a new prompt came in. The same applies to other on
 setup; see step 2 below for `/connect`.
 
 When the loop runs with `--standalone`, the CLI also subscribes to the board's own change
-channel, so you get a second kind of turn on top of prompts: a **board-change turn**, whose
-first line starts with `BOARD_CHANGE` instead of `prompt_id=`. Nobody asked you for anything
-in those turns — you decide whether there's useful modeling work to do and do it, the way a
-human collaborator glancing at the board would. They follow their own steps; see
+channel, so you get a second kind of turn on top of prompts: a **self-directed turn**, whose
+first line starts with `BOARD_CHANGE` (the board changed) or `BOARD_REVIEW` (nothing has
+changed for a while) instead of `prompt_id=`. Nobody asked you for anything in those turns —
+you are a background collaborator on this board: you judge the model as a whole, decide
+what it needs, and fan the work out over parallel subagents. The listed changes are a
+notification pointing at an area, never the task itself. They follow their own steps; see
 "Standalone board-change turns" below. The session header's `standalone=on|off` tells you
 whether this session gets them at all.
 
@@ -65,17 +67,30 @@ skip to "Standalone board-change turns" instead.
 
 ## Standalone board-change turns
 
-Only in a `standalone=on` session. Such a turn looks like this:
+Only in a `standalone=on` session. These turns come in two shapes, and both are
+self-directed — nobody asked you for anything:
 
 ```
-BOARD_CHANGE board_id=<uuid> organization_id=<uuid> seq=118..124 events=4
+BOARD_CHANGE board_id=<uuid> organization_id=<uuid> seq=118..124 events=9 nodes=3
 changed:
-- 9f3c…: node:created, node:changed
-- a12b…: node:changed
+- 9f3c…: node:created, node:changed (4×)
+- a12b…: node:changed (2×) — possibly your own earlier write
+- c771…: edge:added (3×)
 ```
 
-It means: those nodes changed on the board, the board has since gone quiet, and nobody
-asked you for anything. You are acting on your own initiative.
+```
+BOARD_REVIEW board_id=<uuid> organization_id=<uuid> idle_for=900s
+changed: nothing — the board has been quiet.
+```
+
+**The change list is a notification, not the work item.** It tells you that something
+happened and which corner of the board to look at first — nothing more. It is not a task
+list, not a boundary, and the last line of it is not "the" change to react to. A burst of
+40 events on 6 nodes and a single `node:created` get the same treatment: you look at the
+model, not at the event. A `BOARD_REVIEW` turn is the same job with no starting hint at all.
+Nodes marked *possibly your own earlier write* are changes that landed while you were
+working or just after — usually your own echo, so weigh them accordingly, but don't assume:
+a human may well have been editing at the same time.
 
 **There is no `prompt_id` in these turns — never call `/update-prompt-status` in one** (not
 `IN_PROGRESS`, not `DONE`; the "exactly two calls per turn" rule is about prompt turns only).
@@ -83,46 +98,95 @@ There is nothing to sanitize either — a board change is not user text.
 
 Steps:
 
-1. **Look at what actually changed.** Fetch each listed node (`mcp__eventmodelers__get_node`,
-   or the REST equivalent) and enough of its surroundings — its cell, its slice, its
-   connections — to judge it. The payload only carries ids; the node itself tells you its
-   type, name, fields and whether it's still half-finished. `mcp__eventmodelers__get_board_events`
-   with the `seq` range from the header fills in what the change actually was, when the
-   node's current state doesn't make that obvious.
-2. **Decide whether there is genuinely useful work here — the default answer is no.** Do
-   something only when a human collaborator would obviously have done it too:
-   - a new EVENT/COMMAND/READMODEL with fields but no example data → `/examples`
+1. **Get the whole picture, not just the changed nodes.** Start at the listed nodes
+   (`mcp__eventmodelers__get_node`, or the REST equivalent) and widen out to what they sit
+   in — their cell, their slice, the chain they belong to, the timeline around them.
+   `mcp__eventmodelers__get_board_events` with the header's `seq` range tells you what the
+   change actually was when the node's current state doesn't make it obvious. Then judge the
+   board as a whole: run `/analyze-existing-model` once per session to get that picture and
+   keep it in mind across turns, refreshing it when a turn's changes invalidate it. On a
+   `BOARD_REVIEW` turn that model-wide picture *is* the starting point.
+2. **Decide what the model needs — plural, and not necessarily where the change was.** List
+   the candidate contributions you can actually see evidence for, each with its own target
+   (node/cell/slice) and the skill that does it. A changed node is a reason to look; it is
+   not automatically the thing to work on, and work you spot two slices away counts just as
+   much. The usual candidates:
+   - an EVENT/COMMAND/READMODEL with fields but no example data → `/examples`
    - a field added to one element that its chain neighbours are missing → `/attributes`
    - an empty SCREEN node → `/html-screen`
-   - a timeline element that clearly should be sliced and isn't → `/eventmodeling-slicing-event-models`
-   - a change that raises a real business question (a gap, an unhandled case) → one
-     `/wdyt`-style QUESTION comment on that node, via `/handle-comment` with `action=place`
-   Do **nothing** for: a node that merely moved or was resized, a rename, a change inside
-   something you yourself just wrote, a node that already has the thing you'd add, or a node
-   someone is visibly still working on.
-3. **Do at most one focused piece of work**, through the matching skill from the Skill
-   Selection table (same rule as step 5 of a prompt turn: invoke the skill, don't substitute
-   raw MCP calls). One change → one contribution. Never take a single board change as licence
-   to sweep the whole board — if you spot five other things worth doing, that's a `/wdyt`
-   comment, not five edits.
-4. **Never undo or overwrite human work.** You add to the board; you don't delete, rename,
-   restructure timelines, or move slice statuses on your own initiative. If the right move
-   would be destructive, post a comment saying so instead.
-5. **If you already said it, don't say it again.** Before posting a comment, read the node's
-   existing comments — an unresolved question you (or anyone) already posted there means your
-   contribution for this change is already on the board.
-6. **Write no progress entry.** A board-change turn is modeling, not tracked progress —
+   - a timeline element that clearly should be sliced and isn't →
+     `/eventmodeling-slicing-event-models`
+   - a gap or unhandled case that raises a real business question → one QUESTION comment via
+     `/handle-comment` with `action=place`
+   Nothing is a candidate when it's cosmetic (a node moved, resized or renamed), when the
+   target already has the thing you'd add, when it's inside something you yourself just
+   wrote, or when someone is visibly still working on it. An empty candidate list is a
+   perfectly good outcome — see step 8.
+3. **Spawn a subagent for each piece of work that needs doing — and only where one does.** The
+   analysis in steps 1–2 is yours: you look at every entry in `changed:` yourself, in the
+   context of the model, and decide what (if anything) needs to happen. Then, for each
+   candidate that survived that judgment, dispatch one subagent via the `Agent` tool, **with
+   all of them in a single message** so they run in parallel. Entries that need nothing spawn
+   nothing; a turn where nothing needs doing spawns nothing at all and ends in a `NOOP`. What
+   you must never do is work the candidates one after another in your own turn, or pick one
+   out of five and drop the rest — nine events on three nodes that each need something are
+   three agents working at once. You analyse and coordinate; the agents do the work.
+   Each subagent prompt must be self-contained, because a subagent is a fresh session that
+   inherits none of this one's state:
+   - `token=`, `org=`, `baseUrl=` from this session's first message, and the instruction to
+     run `/connect` first;
+   - `board_id`, plus the exact target ids (`node_id`/`cellName`/`timelineId`/slice) it owns
+     — never "the node that changed";
+   - what you concluded in step 2: the specific piece of work, and enough of the surrounding
+     model for the agent to do it well;
+   - the one skill from the Skill Selection table to invoke, and the same rule that applies to
+     you: invoke the skill, don't substitute raw MCP calls;
+   - the standing constraints of step 4 and step 5 below.
+   **Stay inside the agent budget.** The session header carries `max_agents=<n>` (default 5)
+   and every self-directed turn restates it: that is the most Agents you may dispatch in one
+   turn, because a turn nobody asked for still costs money. Merge by area first (step 4) —
+   that's a correctness rule, not a way to fit the budget — and if more pieces are still left
+   than the cap allows, dispatch the most valuable ones and leave the rest; the board doesn't
+   forget, and a later turn will see them again. With `max_agents=1`, spawn nothing at all and
+   do the single most valuable piece yourself, inline.
+   **The decision stays with you.** A subagent is an executor, not a second judge: it carries
+   out the piece of work you decided on, on the target you named, and nothing else. It does
+   not re-open the question of whether the work is worth doing, does not widen its scope, and
+   does not go looking for other things on the board. If it finds the work doesn't apply after
+   all — the node already has what you'd add, someone is mid-edit — it reports that back to
+   you instead of substituting work of its own, and you decide what happens next.
+   Do the work inline yourself only when exactly one candidate survived and it is small (one
+   comment, one `/examples` call) — spawning a single agent for a single small thing is pure
+   overhead.
+4. **Give every agent its own territory — merge before you dispatch, never split a slice.**
+   Two agents writing into the same node, chain or slice will clobber each other and the board
+   has no merge. So the mapping from step 3 is subject to one rule: candidates that live in
+   the same slice or the same chain are handled by **one** agent that owns that whole area,
+   with all of their work in its brief, not one agent each. That also keeps a big burst sane —
+   work on 30 changed nodes across 4 slices is 4 agents, well inside the default budget. Merge
+   first, then prioritize: a candidate is only ever deferred to a later turn because the budget
+   ran out, never because it was inconvenient to merge.
+5. **Never undo or overwrite human work** — you and every agent you dispatch. You add to the
+   board; you don't delete, rename, restructure timelines, or move slice statuses on your own
+   initiative. If the right move would be destructive, post a comment saying so instead.
+6. **If you already said it, don't say it again.** Before posting a comment — or having a
+   subagent post one — read the node's existing comments. An unresolved question already
+   there means that contribution is on the board.
+7. **Write no progress entry.** A self-directed turn is modeling, not tracked progress —
    nothing goes into `progress.txt` here (that file belongs to prompt turns, which answer to
    someone who asked). Still promote anything reusable to `.agent-modeling-kit/AGENTS.md`
-   (same as step 9 of a prompt turn).
-7. Reply `<promise>DONE</promise>` if you changed something, or — when the answer at step 2
-   was "nothing worth doing" — change nothing at all and reply `<promise>NOOP</promise>`. A
-   NOOP is a perfectly good outcome.
-
-Keep these turns small and finished within the turn. Everything you write to the board comes
-back to this same channel as another change; the CLI suppresses your own echo for a short
-window after each turn, so work that trails off and lands later can wake you up again for no
-reason.
+   (same as step 9 of a prompt turn), including anything a subagent reported back.
+8. Reply `<promise>DONE</promise>`, naming what you dispatched and what each agent did, or —
+   when step 2 turned up nothing worth doing — change nothing at all and reply
+   `<promise>NOOP</promise>`. A NOOP is a perfectly good outcome, and the CLI widens the gap
+   before the next self-directed turn each time you answer one, so a finished board goes
+   quiet by itself. Don't manufacture work to avoid a NOOP.
+
+Keep these turns finished within the turn: wait for the subagents you dispatched, don't leave
+work trailing. Everything you and they write to the board comes back on this same channel as
+another change; the CLI labels changes that arrive in that echo window rather than dropping
+them, so you'll see your own writes listed on a later turn — recognize them and don't rework
+them.
 
 ## Skill Selection