@eventmodelers/cli 1.0.90 → 1.0.92

package/README.md

@@ -635,6 +635,8 @@ npx @eventmodelers/cli re-init --stack supabase      # override which stack to r
 
 `re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/`ralph.sh`/skills without re-scaffolding a project you've since built on top of.
 
+You don't have to remember to: on startup every command prints a 💡 hint (on stderr) when a newer CLI is on npm, or when a kit in the current directory was installed by an older CLI than the one running — naming the exact `re-init` command to run. The npm lookup happens at most once a day (cached in `~/.eventmodelers/update-check.json`, 1.5 s timeout, silent when offline). Set `EVENTMODELERS_NO_UPDATE_CHECK=1` to turn it off; it is also off when `CI` is set.
+
 Pass `--stack <name>` to override the stack instead of relying on the manifest — useful if the manifest is missing/stale, or you want to point a `.build-kit` install at a different built-in stack's templates. It's mutually exclusive with `--modeling`.
 
 Credentials are left alone unless you pass `--force` — same rule `init` already follows when everything required is already configured. `--global` defaults to however skills were originally installed; pass it explicitly to move them.

package/RELEASE_NOTES.md

@@ -9,6 +9,9 @@
 - The `anthropicBaseUrl` option no longer implies Ollama works behind it. That route keeps Claude Code and swaps only the endpoint, so the server has to speak Anthropic's own `/v1/messages`; Ollama does not, and pointing it at `localhost:11434` returns a 404. For Ollama, `--local-ai` is the supported route, and the README now says which of the two to reach for.
 - `LOCAL_AI_*` is documented for the first time — the `--local-ai` help text had been pointing at "the docs" for vars that appeared nowhere in the README.
 
+### Fixes
+- Chat messages are limited to 1000 characters, in both directions — the platform now rejects longer ones (`CHAT_TEXT_TOO_LONG`). The kit instructions say so, and the CLI's fallback reply (a chat turn's final text, posted when the turn didn't reply itself) is cut at the limit instead of failing with a 400 and leaving the message unanswered.
+
 ## v1.0.72
 
 ### Features

package/cli.js

@@ -21,6 +21,7 @@ import { randomUUID } from 'crypto';
 import { runFetch, FetchAuthError } from './lib/fetch.js';
 import { createModelingLocalAiRunner } from './lib/modeling-local-ai.js';
 import { run as runSpecKittyAdapter } from './lib/adapters/spec-kitty-adapter.js';
+import { latestPublishedVersion, updateHints } from './lib/update-check.js';
 // Not a root-level adapter like spec-kitty-adapter.js above: this is the one canonical
 // copy that every useShared:true stack also gets copied into its installed kit (see
 // copyDirContents in installStack) for ralph.js to import standalone — see
@@ -1282,6 +1283,11 @@ async function configureCredentials({ config, configPath, targetDir, requiredFie
 async function refreshSharedRuntime({ targetDir, kitDir, globalOpts, opts }) {
   console.log(`📦 Refreshing the shared runtime in ${relative(targetDir, kitDir)}/ (stack files untouched)...`);
   copyDirContents(join(__dirname, 'shared', 'build-kit'), kitDir);
+  // The kit is now this CLI's runtime — record that, so the startup "kit is outdated" hint stops.
+  const manifestPath = join(kitDir, '.eventmodelers', 'install-manifest.json');
+  if (existsSync(manifestPath)) {
+    writeFileSync(manifestPath, JSON.stringify({ ...readJsonSafe(manifestPath), version: CLI_VERSION }, null, 2));
+  }
   for (const script of ['ralph.sh', 'lib/agent.sh', 'ralph-claude.js', 'ralph-local-ai.js', 'ralph-exec.js']) {
     const p = join(kitDir, script);
     if (existsSync(p)) {
@@ -1861,7 +1867,9 @@ async function ensureGlobalKit(baseUrl) {
 // untargeted is handed straight back to the queue for another agent to take. It says
 // nothing about the standalone lane — a self-directed turn is nobody's task, so an
 // exclusive standalone agent still works the board on its own initiative.
-async function runModeling(kitDir, projectDir, { verbose = false, standalone = false, exclusive = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS, identity = {}, localAi = null } = {}) {
+async function runModeling(kitDir, projectDir, { verbose = false, standalone = false, exclusive = false, worker = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS, identity = {}, localAi = null } = {}) {
+  // --worker: only prompts — no chat, and no board-change turns (it has nowhere to propose).
+  const chat = !worker;
   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\`.`);
@@ -1931,7 +1939,10 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     'IMPORTANT: You are running autonomously — no human is available to answer questions. ' +
     'If you need clarification to proceed, do NOT pause or ask interactively. Instead, post your question ' +
     'as a QUESTION-type comment (via /handle-comment with action=place and type=QUESTION) on the most ' +
-    'relevant slice or column node on the board, then continue with your best interpretation of the prompt.\n\n';
+    'relevant slice or column node on the board, then continue with your best interpretation of the prompt. ' +
+    'The one exception is a CHAT turn: there a person is waiting in the chat, so you ask back with post_chat_message ' +
+    '(see "Chat turns" in .agent-modeling-kit/CLAUDE.md), and never by pausing the session. ' +
+    'A chat message is at most 1000 characters.\n\n';
 
   // Sent once, on the first turn only — it's what tells the agent to follow
   // .agent-modeling-kit/CLAUDE.md's per-turn steps for this warm session (instead
@@ -1943,13 +1954,16 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // board-change turn can just as well be the first turn a (re)spawned process
   // ever sees, so both turn builders go through this rather than buildTurn owning it.
   function withSessionHeader(body) {
+    // token= names the env var, never its value: claudeEnv already carries EVENTMODELERS_TOKEN,
+    // and a literal token here would sit in every session transcript (the connect skill treats
+    // the reference as an inline token — see its Step 0).
     // Nothing to prepend for a local model: it has no CLAUDE.md to read and no /connect to run
     // (its tools are already authenticated), and handing it the raw token would put credentials
     // in a context that has no way to use them.
     if (localRunner) return body;
     if (!firstTurn) return body;
     firstTurn = false;
-    return `MODE=modeling token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\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=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\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) {
@@ -1960,13 +1974,15 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
       p.timeline_id ? `timeline_id=${p.timeline_id}` : null,
       p.comment_id ? `comment_id=${p.comment_id}` : null,
       p.node_id ? `node_id=${p.node_id}` : null,
+      // Work the agent created out of a chat message: where to report back when it's done.
+      p.origin_session_id ? `origin_session_id=${p.origin_session_id}` : null,
+      p.origin_message_id ? `origin_message_id=${p.origin_message_id}` : null,
     ].filter(Boolean).join(' ');
     // What the user had selected and on screen when they submitted (selectedCell,
     // selectedNodes, timelineId, focusArea). CLAUDE.md's step 3 resolves CELL_ID/NODE_ID/
-    // TIMELINE_ID from it in preference to the flat fields above, and a canvas "poke" —
-    // whose prompt text is the bare word `Focus` — is nothing BUT this context: drop it and
-    // the turn says "Focus" and names nowhere to look. Sent as JSON on its own line because
-    // it is structured, unlike the flat k=v fields.
+    // TIMELINE_ID from it in preference to the flat fields above, and it is what "this" or
+    // "here" in the prompt refers to. Sent as JSON on its own line because it is structured,
+    // unlike the flat k=v fields.
     const context = p.context && typeof p.context === 'object' && Object.keys(p.context).length
       ? `\ncontext=${JSON.stringify(p.context)}`
       : '';
@@ -1987,6 +2003,21 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   let proc = null;
   let stdoutBuffer = '';
   let pending = null; // one in-flight turn at a time
+  // The last message of each session this process has handed to Claude. A session the process has
+  // never seen is read whole; after that only what came since — each message enters the warm
+  // session's context once. Cleared whenever the process is (re)spawned: a fresh process has read
+  // nothing.
+  const chatCursor = new Map();
+  // --modeling: the people this agent has taken a chat message from — the only ones whose board
+  // edits it proposes on. Everyone else's edits cost no turn: an agent one person started must not
+  // spend their money reacting to the whole board, nor write to people who never talked to it. Kept
+  // across respawns (it is about people, not the Claude process), lost when the CLI restarts.
+  const chatPartners = new Set();
+  // When each partner was last sent a proposal. The backend lets an unanswered proposal stand for
+  // UNPROMPTED_COOLDOWN_MS before another; waiting here keeps a turn from being spent on one it
+  // would refuse. Cleared when the person writes in the chat.
+  const lastProposalAt = new Map();
+
   let lastTurnEndedAt = 0; // when the last turn finished — the standalone lane's echo window (see below)
   let warmUp = null; // this process's session warm-up turn (see warmUpSession) — null until one is started
   let warmingUp = false; // the in-flight turn is the warm-up: it only reads, so its writes can't echo
@@ -2056,6 +2087,7 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     proc = spawn('claude', claudeArgs, { cwd: projectDir, env: claudeEnv, stdio: ['pipe', 'pipe', 'inherit'] });
     stdoutBuffer = '';
     warmUp = null; // a fresh process has connected to nothing and read nothing
+    chatCursor.clear(); // …and has read no chat session either
     proc.stdout.on('data', (chunk) => {
       stdoutBuffer += chunk.toString();
       const lines = stdoutBuffer.split('\n');
@@ -2154,8 +2186,11 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   log(
     standalone
       ? `standalone: ON — reacting to direct prompts AND to board changes on its own initiative (${localRunner ? 'work is done inline — a local model has no subagents' : `max ${maxAgents} subagent(s) per self-directed turn`})`
-      : 'standalone: off — reacting to direct prompts only (board changes are dropped)',
+      : worker
+        ? 'worker: ON — working prompts only (no chat, board changes are dropped)'
+        : 'standalone: off — board changes get a proposal in the chat, nothing is changed without a yes',
   );
+  log(chat ? 'chat: ON — answering chat messages addressed to this agent' : 'chat: off (--worker)');
   if (exclusive) {
     log(`exclusive: ON — only prompts addressed to ${cfg.agentId} are worked; every untargeted prompt is handed back to the queue`);
     // A global/standalone run mints its id per run (see resolveModelingCredentials), so an id
@@ -2198,6 +2233,92 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     if (!res.ok) throw new Error(`prompts/${promptId}/status: HTTP ${res.status}`);
   }
 
+  // ── Chat ───────────────────────────────────────────────────────────────────
+  //
+  // Chat messages are conversation, not work: a person talks to this agent in the board's chat
+  // panel, and each message addressed to it is claimed here (`chat/next` flips it to picked_up)
+  // and handed to Claude as a CHAT turn. Claude decides — answer, ask back, or create prompts for
+  // the work — and replies with post_chat_message; any prompts it creates are addressed to this
+  // agent and worked by the same drain pass right after. Off with --worker.
+  async function fetchNextChatMessage(jwtToken) {
+    try {
+      const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/chat/next?board_id=${encodeURIComponent(cfg.boardId)}`, {
+        headers: { 'x-token': cfg.token, Authorization: `Bearer ${jwtToken}`, ...agentHeaders(cfg) },
+      });
+      // 404 is "nothing waiting" — and also what a backend without chat answers, which is fine.
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    } catch (err) {
+      // Never let chat take the prompt queue down with it: log, skip chat for this pass.
+      log(`chat/next failed, skipping chat this pass: ${err.message}`);
+      return null;
+    }
+  }
+
+  function buildChatTurn(m) {
+    const after = chatCursor.get(m.sessionId);
+    const fields = [
+      `CHAT message_id=${m.id}`,
+      `session_id=${m.sessionId}`,
+      `board_id=${cfg.boardId}`,
+      `organization_id=${cfg.organizationId}`,
+      after ? `after_message_id=${after}` : 'first_read=true',
+      m.nodeId ? `node_id=${m.nodeId}` : null,
+      m.commentId ? `comment_id=${m.commentId}` : null,
+    ].filter(Boolean).join(' ');
+    const context = m.context && typeof m.context === 'object' && Object.keys(m.context).length
+      ? `\ncontext=${JSON.stringify(m.context)}`
+      : '';
+    return withSessionHeader(`${fields}${context}\n\n${m.text}`);
+  }
+
+  // The backend rejects a chat message over this many characters (CHAT_TEXT_TOO_LONG).
+  const CHAT_TEXT_MAX_LENGTH = 1000;
+
+  // Posted only if the turn didn't answer — the backend checks (only_if_unanswered), so a reply
+  // the agent did post is never doubled. What makes "every message gets an answer" hold even for a
+  // turn that errored or forgot its post_chat_message.
+  async function replyIfUnanswered(m, text) {
+    try {
+      const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${encodeURIComponent(cfg.boardId)}/chat/agent-messages`, {
+        method: 'POST',
+        headers: { 'x-token': cfg.token, 'Content-Type': 'application/json', ...agentHeaders(cfg) },
+        // A turn's final text can run long; cut it rather than lose the reply to a 400.
+        body: JSON.stringify({
+          text: text.length > CHAT_TEXT_MAX_LENGTH ? `${text.slice(0, CHAT_TEXT_MAX_LENGTH - 1)}…` : text,
+          reply_to: m.id,
+          only_if_unanswered: true,
+        }),
+      });
+      if (!res.ok) log(`chat fallback reply failed: HTTP ${res.status}`);
+      else if (res.status === 201) log(`chat turn left message ${m.id} unanswered — posted its final text as the reply`);
+    } catch (err) {
+      log(`chat fallback reply failed: ${err.message}`);
+    }
+  }
+
+  async function runChatTurn(m) {
+    log(`chat message received: "${oneLine(m.text, 80)}" (session=${m.sessionId})`);
+    if (m.userId) {
+      chatPartners.add(m.userId);
+      lastProposalAt.delete(m.userId);
+    }
+    let result = '';
+    let failed = false;
+    try {
+      result = await runTurn(buildChatTurn(m));
+    } catch (err) {
+      failed = true;
+      log(`chat turn failed: ${err.message}`);
+    }
+    chatCursor.set(m.sessionId, m.id);
+    const text = String(result ?? '').replace(/<promise>[^<]*<\/promise>/g, '').trim();
+    await replyIfUnanswered(m, text && !failed ? text : 'Sorry — I could not finish that just now. Please try again.');
+    // Edits they made while their last proposal waited for this answer get their turn now.
+    if (m.userId && proposalBuffer.has(m.userId)) armProposalTurn(STANDALONE_DEBOUNCE_MS);
+  }
+
   let realtimeToken = await getRealtimeToken();
 
   let draining = false;
@@ -2208,8 +2329,16 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     // handed back once the pass is over (see below).
     const handBack = [];
     try {
-      let p;
-      while ((p = await fetchNextPrompt(realtimeToken)) !== null) {
+      for (;;) {
+        // A person waiting in the chat goes first; a prompt the chat turn created is picked up
+        // by the fetch below on this same pass.
+        const m = chat ? await fetchNextChatMessage(realtimeToken) : null;
+        if (m) {
+          await runChatTurn(m);
+          continue;
+        }
+        const p = await fetchNextPrompt(realtimeToken);
+        if (p === null) break;
         // The queue can't filter by addressee for us: `prompts/next` hands an agent both the
         // prompts addressed to it and every untargeted one (`agent_id IS NULL`) — claiming is
         // what reveals which kind arrived — so an exclusive run claims as usual and gives back
@@ -2323,8 +2452,18 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // session rather than by another agent. It is what lets a human's edit skip the
   // MIN_INTERVAL floor: a person cannot be this agent's feedback loop, whereas two agents on
   // one board can ping-pong, so another agent's write keeps waiting its turn.
+  // Whether board changes get a turn at all, and what that turn may do. --standalone acts on its
+  // own initiative, on everyone's edits. A plain --modeling agent only proposes, and only to the
+  // people talking to it in the chat — about their own edits (the propose lane below). A --worker
+  // takes neither: it only works prompts.
+  const boardLane = standalone || chat;
+  const proposeOnly = !standalone;
+
   const observed = new Map();
   let observedCount = 0;
+  // --standalone: the person behind the latest human edit in the buffer — who a blocking question
+  // may be put to in the chat.
+  let lastChangedBy = null;
   let seqLo = null;
   let seqHi = null;
   let standaloneTimer = null;
@@ -2347,11 +2486,12 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     seqLo = null;
     seqHi = null;
     firstObservedAt = 0;
+    lastChangedBy = null;
   }
 
   function onBoardEvent(type, payload) {
-    if (!standalone) {
-      if (verbose) log(`board event ${type} dropped — not running with --standalone`);
+    if (!boardLane) {
+      if (verbose) log(`board event ${type} dropped — a --worker only works prompts`);
       return;
     }
     const sinceTurn = Date.now() - lastTurnEndedAt;
@@ -2366,6 +2506,10 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     // editing while this agent worked had their change written off as an echo of it.
     const writerAgent = payload?.agent_id || null;
     const writerUser = payload?.user_id || null;
+    if (proposeOnly) {
+      onProposableEvent(type, payload, writerUser, writerAgent);
+      return;
+    }
     const origin =
       writerAgent && cfg.agentId && writerAgent === cfg.agentId
         ? 'own'
@@ -2380,7 +2524,10 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     entry.count += 1;
     entry[origin] += 1;
     // A browser session id and no agent id: a human at the canvas.
-    if (writerUser && !writerAgent) entry.person += 1;
+    if (writerUser && !writerAgent) {
+      entry.person += 1;
+      lastChangedBy = writerUser;
+    }
     observed.set(nodeId, entry);
     observedCount += 1;
     if (!firstObservedAt) firstObservedAt = Date.now();
@@ -2474,6 +2621,111 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     `actually needs doing, and then ${FAN_OUT} If the model genuinely needs nothing right now, spawn ` +
     'nothing, change nothing and reply <promise>NOOP</promise>.';
 
+  // --modeling: the same judgement as a standalone turn, but it changes nothing — it puts what it
+  // would do to the person in the chat and waits. A "yes" comes back as a CHAT turn, which is where
+  // the work is actually created (as prompts).
+  const PROPOSE_TASK =
+    'Nobody asked you for this — the board just changed, and you are a modeling agent that proposes rather ' +
+    'than acts: you may NOT change the board in this turn, and you dispatch no Agents. The change list above ' +
+    'is a notification, not the task. Judge the changed areas in their context (slice, chain, timeline) the ' +
+    'way .agent-modeling-kit/CLAUDE-STANDALONE.md describes — read it now if you have not this session, and ' +
+    'follow its "Propose mode" section. Read what this needs and no more: every nodeId above in one get_nodes, ' +
+    'plus one get_board_outline per chapter you have not read this session. Every change above is by one person, ' +
+    'changed_by, who is talking to you in the chat. ALWAYS post ONE short chat message to them with ' +
+    'post_chat_message (no sessionId, no replyTo, preferUserId = changed_by; at most 1000 characters) — never stay silent after their ' +
+    'edit. A fresh, half-finished element (placeholder name, no ' +
+    'fields, names still changing) is the reason to speak, not to wait. Something worth doing → say concretely ' +
+    'what you would do (element names) and ask whether to go ahead. Nothing concrete → say what you saw and ' +
+    'that you are not sure what to do with it, and ask ("You renamed Orders to take — not sure what to do with ' +
+    'it yet. Want fields on it?"). Fold anything your earlier unanswered message proposed into this one instead ' +
+    'of repeating it. One to three sentences. Only CHAT_NO_ACTIVE_SESSION (they cleared the conversation or ' +
+    'switched to another agent) or CHAT_AWAITING_REPLY (you wrote to them less than 3 minutes ago) keep you ' +
+    'silent: then change nothing and reply <promise>NOOP</promise>.';
+
+  // ── Propose lane (--modeling) ─────────────────────────────────────────────
+  //
+  // Per person: what each chat partner changed since their last proposal. Each gets their own turn
+  // and their own proposal, about their own edits only — nobody hears about someone else's work.
+  const PROPOSAL_COOLDOWN_MS = 3 * 60_000; // the backend's UNPROMPTED_COOLDOWN_MS
+  const proposalBuffer = new Map(); // userId -> Map(nodeId -> { types: Set<string>, count })
+  let proposalFirstAt = 0; // start of the current burst — MAX_WAIT is measured from here
+  let proposalTimer = null;
+
+  function onProposableEvent(type, payload, writerUser, writerAgent) {
+    const nodeId = payload?.node_id ?? '(board)';
+    // Only a person at the canvas who is talking to this agent. Agents' writes (this one's
+    // included) and unattributed ones name nobody to propose to.
+    if (!writerUser || writerAgent || !chatPartners.has(writerUser)) {
+      if (verbose) log(`board change: ${type} node=${nodeId} — ignored, not by a person chatting with this agent`);
+      return;
+    }
+    const nodes = proposalBuffer.get(writerUser) ?? new Map();
+    const entry = nodes.get(nodeId) ?? { types: new Set(), count: 0 };
+    entry.types.add(type);
+    entry.count += 1;
+    nodes.set(nodeId, entry);
+    proposalBuffer.set(writerUser, nodes);
+    if (!proposalFirstAt) proposalFirstAt = Date.now();
+    log(`board change: ${type} node=${nodeId} — by a chat partner`);
+    armProposalTurn(Math.max(0, Math.min(STANDALONE_DEBOUNCE_MS, STANDALONE_MAX_WAIT_MS - (Date.now() - proposalFirstAt))));
+  }
+
+  function armProposalTurn(delayMs) {
+    if (proposalTimer) clearTimeout(proposalTimer);
+    proposalTimer = setTimeout(() => {
+      proposalTimer = null;
+      dispatchProposals().catch((err) => log(`proposal dispatch error: ${err.message}`));
+    }, delayMs);
+  }
+
+  function buildProposalTurn(userId, nodes) {
+    const lines = [...nodes.entries()].map(([nodeId, entry]) => `- ${nodeId}: ${[...entry.types].join(', ')} (${entry.count}×)`);
+    const events = [...nodes.values()].reduce((sum, entry) => sum + entry.count, 0);
+    const header = [
+      'BOARD_CHANGE',
+      'mode=propose',
+      `changed_by=${userId}`,
+      `board_id=${cfg.boardId}`,
+      `organization_id=${cfg.organizationId}`,
+      `events=${events}`,
+      `nodes=${nodes.size}`,
+    ].join(' ');
+    return withSessionHeader(`${header}\nchanged:\n${lines.join('\n')}\n\n${PROPOSE_TASK}`);
+  }
+
+  async function dispatchProposals() {
+    // A direct message always outranks the agent's own initiative.
+    if (pending || draining) {
+      armProposalTurn(STANDALONE_DEBOUNCE_MS);
+      return;
+    }
+    const now = Date.now();
+    const due = [];
+    let waitMs = Infinity;
+    for (const [userId, nodes] of proposalBuffer) {
+      // Their last proposal is still unanswered: keep collecting, fold it all into the next one.
+      const left = (lastProposalAt.get(userId) ?? 0) + PROPOSAL_COOLDOWN_MS - now;
+      if (left > 0) {
+        waitMs = Math.min(waitMs, left);
+        continue;
+      }
+      due.push([userId, nodes]);
+      proposalBuffer.delete(userId);
+    }
+    if (!proposalBuffer.size) proposalFirstAt = 0;
+    for (const [userId, nodes] of due) {
+      log(`propose turn: ${nodes.size} node(s) changed by ${userId.slice(0, 8)}`);
+      lastProposalAt.set(userId, Date.now());
+      try {
+        await runTurn(buildProposalTurn(userId, nodes));
+      } catch (err) {
+        log(`propose turn failed: ${err.message}`);
+      }
+    }
+    // Still waiting out a cooldown, or edits that arrived while these turns ran.
+    if (proposalBuffer.size) armProposalTurn(Number.isFinite(waitMs) && !due.length ? waitMs : STANDALONE_DEBOUNCE_MS);
+  }
+
   function buildStandaloneTurn() {
     const lines = [...observed.entries()].map(([nodeId, entry]) => {
       const origin =
@@ -2488,6 +2740,8 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     });
     const header = [
       'BOARD_CHANGE',
+      'mode=act',
+      lastChangedBy ? `changed_by=${lastChangedBy}` : null,
       `board_id=${cfg.boardId}`,
       `organization_id=${cfg.organizationId}`,
       seqLo !== null ? `seq=${seqLo}${seqHi !== seqLo ? `..${seqHi}` : ''}` : null,
@@ -2650,6 +2904,12 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
       'prompt:created': () => {
         drain().catch((err) => log(`drain error: ${err.message}`));
       },
+      // Sent for every chat message on the org; only one addressed to this agent on this board
+      // is worth a drain pass.
+      'chat:created': (payload) => {
+        if (!chat || payload?.agent_id !== cfg.agentId || payload?.board_id !== cfg.boardId) return;
+        drain().catch((err) => log(`drain error: ${err.message}`));
+      },
     },
     (status) => {
       log(`channel "${channelName}": ${status}`);
@@ -2670,7 +2930,7 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     boardChannelName,
     Object.fromEntries(BOARD_CHANGE_EVENTS.map((event) => [event, (payload) => onBoardEvent(event, payload)])),
     (status) => {
-      log(`channel "${boardChannelName}": ${status}${standalone ? '' : ' (events dropped — no --standalone)'}`);
+      log(`channel "${boardChannelName}": ${status}${boardLane ? '' : ' (events dropped — --worker)'}`);
       if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
         refreshRealtimeToken(status).catch(() => {});
       }
@@ -2688,7 +2948,10 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
       const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${realtimeToken}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: 'MODELING', agent_id: cfg.agentId, ...(cfg.agentName ? { agent_name: cfg.agentName } : {}) }),
+        // chat_enabled tells the board this agent answers chat messages (the panel only offers chat
+        // with one that does); a --worker reports false, and older CLIs send nothing, which the
+        // backend reads as false too.
+        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: 'MODELING', agent_id: cfg.agentId, chat_enabled: chat, ...(cfg.agentName ? { agent_name: cfg.agentName } : {}) }),
         signal: AbortSignal.timeout(10_000),
       });
       if (!res.ok) log(`ping failed: ${res.status} ${await res.text().catch(() => '')}`);
@@ -2705,7 +2968,7 @@ const program = new Command();
 program
   .name('eventmodelers')
   .description('Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack')
-  .version('1.0.0')
+  .version(CLI_VERSION)
   .option('--config <path>', 'Path to an explicit config.json, overriding directory-based resolution (individual fields can also be set via EVENTMODELERS_* env vars, which always win)')
   .option('--print', 'Print follow-up commands (e.g. claude mcp add) instead of prompting to run them');
 
@@ -2725,6 +2988,21 @@ program
 // than this generic gate can.
 const NO_INIT_REQUIRED = new Set(['init', 'init-config', 'stacks', 'status', 'config', 'uninstall', 'fetch', 'activate-context', 'set-slice-status', 'release-notes', 'run']);
 
+// Commands that install or refresh the kit themselves — a "your kit is outdated" hint in
+// front of them would only be noise.
+const NO_KIT_UPDATE_HINT = new Set(['init', 're-init', 'uninstall']);
+
+// Startup hint when this CLI is behind npm, or an installed kit here is behind this CLI.
+// Best effort and on stderr, so it never breaks piped output; EVENTMODELERS_NO_UPDATE_CHECK
+// (or CI) turns it off.
+program.hook('preAction', async (_thisCommand, actionCommand) => {
+  if (process.env.EVENTMODELERS_NO_UPDATE_CHECK || process.env.CI) return;
+  const latestVersion = await latestPublishedVersion({ cachePath: join(GLOBAL_DIR, 'update-check.json') });
+  const kitDirs = NO_KIT_UPDATE_HINT.has(actionCommand.name()) ? [] : findAllInstalledKitDirs(process.cwd());
+  const hints = updateHints({ currentVersion: CLI_VERSION, latestVersion, kitDirs });
+  if (hints.length) console.error(`${hints.join('\n')}\n`);
+});
+
 program.hook('preAction', (_thisCommand, actionCommand) => {
   if (NO_INIT_REQUIRED.has(actionCommand.name())) return;
   if (findInstalledKitDir(process.cwd())) return;
@@ -3197,9 +3475,10 @@ credentialFlags(program
   .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent. With agent tracing on, include the harness\'s JSON output flag (codex exec --json, opencode run --format json, gemini --output-format stream-json) — without it no slice cost is recorded.')
   .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('--non-interactive', 'Never ask anything: take the board and credentials that resolve from flags, EVENTMODELERS_* env vars and the config files, and fail with the reason if they are incomplete instead of interviewing for them. A TTY was previously the only signal — right for CI or a supervisor, wrong for a loop started from a terminal, where stdin is a TTY nobody is watching and the run stops on a question. Only affects the modeling loop (--modeling/--standalone/--global).')
-  .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, specs for a new command or read model, a missing attribute along a chain, a screen, a question comment). Filling that detail in while the human keeps modeling is the point — it does not wait for the board to be finished. Implies --modeling.')
+  .option('--non-interactive', 'Never ask anything: take the board and credentials that resolve from flags, EVENTMODELERS_* env vars and the config files, and fail with the reason if they are incomplete instead of interviewing for them. A TTY was previously the only signal — right for CI or a supervisor, wrong for a loop started from a terminal, where stdin is a TTY nobody is watching and the run stops on a question. Only affects the modeling loop (--modeling/--standalone/--worker/--global).')
+  .option('--standalone', 'Let the modeling agent act on board changes on its own initiative, without asking: it subscribes to the board\'s change channel and, whenever the board goes quiet after an edit — or has simply been idle for a while — it takes a turn nobody asked for, judges the model as a whole and fans the work out over parallel subagents, one per changed area (examples on a new node, specs for a new command or read model, a missing attribute along a chain, a screen, a question). Filling that detail in while the human keeps modeling is the point. A plain --modeling agent only proposes, and only to the people chatting with it: after their edits it says in the chat what it would do and waits for a yes; everyone else\'s edits are ignored. 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('--worker', 'A modeling agent that only works prompts: it neither takes part in the board\'s chat (the heartbeat reports chat_enabled=false, so the chat panel does not offer it) nor reacts to board changes — it waits for prompts and does them. For a dedicated agent a supervisor or another agent feeds, often paired with --exclusive and --id. Implies --modeling; cannot be combined with --standalone.')
   .option('--exclusive', 'Work only the prompts addressed to this agent\'s id — the board\'s "preferred agent" (the star in the prompts panel) — and hand every untargeted prompt straight back to the queue for another agent to take. Without it an agent also works everything nobody addressed to anyone, which is what you want for a single agent and exactly what you do not want for a dedicated one (a board with a general agent plus a specialist, or an agent a supervisor drives by id). Pair it with --id so the same agent is addressable across restarts — --global/--standalone otherwise mint a fresh id per run, and prompts addressed to the previous run\'s id are never claimed. Leaves --standalone alone: a self-directed turn is nobody\'s prompt, so an exclusive standalone agent still works the board on its own initiative.')
   .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)')
@@ -3219,8 +3498,14 @@ credentialFlags(program
     }
     // The build-kit runners claim their work from the same queue but have no addressee
     // filter, so the flag would silently do nothing there rather than half of what it says.
-    if (opts.exclusive && !(opts.modeling || opts.standalone || opts.global)) {
-      console.log('ℹ️  --exclusive only applies to the modeling loop (--modeling/--standalone/--global); ignoring it here.');
+    if (opts.exclusive && !(opts.modeling || opts.standalone || opts.worker || opts.global)) {
+      console.log('ℹ️  --exclusive only applies to the modeling loop (--modeling/--standalone/--worker/--global); ignoring it here.');
+    }
+    // A worker is defined by what it doesn't do on its own — --standalone is exactly that, so the
+    // two contradict each other rather than one quietly winning.
+    if (opts.worker && opts.standalone) {
+      console.error('❌ --worker and --standalone are mutually exclusive — a worker never acts on board changes.');
+      process.exit(1);
     }
     // --id/--name are what the platform will see for this run, so a blank one is a
     // mistake worth failing on rather than silently falling back to the stored identity.
@@ -3262,8 +3547,8 @@ credentialFlags(program
     // was never a second thing it could have selected, and requiring both flags only made
     // the shorter, more obvious command fail. --global picks the modeling loop too — it has
     // no meaning for a build kit, which is scaffolded per project by definition.
-    if (opts.modeling || opts.standalone || opts.global) {
-      const picked = opts.modeling ? '--modeling' : opts.standalone ? '--standalone' : '--global';
+    if (opts.modeling || opts.standalone || opts.worker || opts.global) {
+      const picked = opts.modeling ? '--modeling' : opts.standalone ? '--standalone' : opts.worker ? '--worker' : '--global';
       // --bash/--exec stay build-kit only: they drive the cold-spawn tasks.json loop, which the
       // modeling loop has no equivalent of. --local-ai is different — it names a *model*, not a
       // queue, and the modeling loop has its own runner for one (lib/modeling-local-ai.js).
@@ -3313,7 +3598,7 @@ credentialFlags(program
       const runnerLabel = modelingLocalAi ? 'local model' : 'warm Claude process';
       await new Promise((res) => process.stdout.write(`▶ Starting modeling loop (${runnerLabel}) for ${shown && !shown.startsWith('..') ? shown : kitDir}...\n\n`, res));
       try {
-        await runModeling(kitDir, projectDir, { verbose: !!opts.verbose, standalone: !!opts.standalone, exclusive: !!opts.exclusive, overrides, maxAgents, identity, localAi: modelingLocalAi });
+        await runModeling(kitDir, projectDir, { verbose: !!opts.verbose, standalone: !!opts.standalone, exclusive: !!opts.exclusive, worker: !!opts.worker, overrides, maxAgents, identity, localAi: modelingLocalAi });
       } catch (err) {
         console.error('[modeling] Fatal:', err);
         process.exit(1);

package/lib/update-check.js

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { basename, dirname, join, relative } from 'path';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/@eventmodelers/cli/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+
+// Kit dirs `re-init` can refresh, and how to ask it to.
+const REINIT_COMMANDS = {
+  '.build-kit': 'eventmodelers re-init',
+  '.agent-modeling-kit': 'eventmodelers re-init --modeling',
+};
+
+// Numeric compare of x.y.z versions — negative when a < b. Pre-release suffixes are ignored.
+export function compareVersions(a, b) {
+  const pa = String(a).split('-')[0].split('.').map(Number);
+  const pb = String(b).split('-')[0].split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return {}; }
+}
+
+// The latest published version, asked of the npm registry at most once a day — in between,
+// the answer cached at cachePath is reused. Best effort: offline, slow or broken registry
+// responses just yield whatever was cached last (or null).
+export async function latestPublishedVersion({ cachePath, now = Date.now(), fetchImpl = fetch } = {}) {
+  const cache = readJson(cachePath);
+  if (cache.latest && now - (cache.checkedAt || 0) < CHECK_INTERVAL_MS) return cache.latest;
+
+  try {
+    const res = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!res.ok) return cache.latest || null;
+    const { version } = await res.json();
+    if (!version) return cache.latest || null;
+    try {
+      mkdirSync(dirname(cachePath), { recursive: true });
+      writeFileSync(cachePath, JSON.stringify({ latest: version, checkedAt: now }));
+    } catch {}
+    return version;
+  } catch {
+    return cache.latest || null;
+  }
+}
+
+// Hint lines for everything that's behind: this CLI against npm, and each installed kit
+// against the CLI running now (its install manifest records the version that wrote it).
+export function updateHints({ currentVersion, latestVersion, kitDirs = [], cwd = process.cwd() }) {
+  const hints = [];
+  if (latestVersion && compareVersions(currentVersion, latestVersion) < 0) {
+    hints.push(`💡 A new eventmodelers CLI is available: ${currentVersion} → ${latestVersion}. Update with: npm i -g @eventmodelers/cli@latest (or use npx @eventmodelers/cli@latest)`);
+  }
+  for (const kitDir of kitDirs) {
+    const reinit = REINIT_COMMANDS[basename(kitDir)];
+    const manifestPath = join(kitDir, '.eventmodelers', 'install-manifest.json');
+    if (!reinit || !existsSync(manifestPath)) continue;
+    const kitVersion = readJson(manifestPath).version;
+    if (kitVersion && compareVersions(kitVersion, currentVersion) >= 0) continue;
+    hints.push(`💡 ${relative(cwd, kitDir) || kitDir}/ was installed by CLI ${kitVersion || '(unknown version)'} — refresh it to ${currentVersion} with: ${reinit}`);
+  }
+  return hints;
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.90",
+  "version": "1.0.92",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {
     "eventmodelers": "cli.js"
   },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "files": [
     "cli.js",
     "lib",