@eventmodelers/cli 1.0.163 → 2.0.2

package/shared/build-kit/README.md

@@ -27,8 +27,6 @@ node .build-kit/ralph-claude.js /path/to/project
 | `ralph-claude.js` | Runs the full loop using Claude Code as the executor |
 | `ralph-local-ai.js` | Runs the full loop using a local/self-hosted model (Ollama, vLLM, LM Studio, llama.cpp) |
 | `ralph-exec.js` | Runs the full loop handing each prompt to an external agent command (Codex CLI, OpenCode, …) |
-| `ralph.sh` | Shell-based loop — alternative to the JS entry points |
-| `realtime-agent.js` | Standalone realtime agent — only needed to run it in a separate terminal |
 
 **Internals** (`lib/`):
 
@@ -36,16 +34,15 @@ node .build-kit/ralph-claude.js /path/to/project
 |------|---------|
 | `lib/ralph.js` | Shared library — realtime agent + loop logic; imported by the entry points |
 | `lib/local-ai-agent.js` | Local-AI executor — called by `ralph-local-ai.js`, can also run manually |
-| `lib/agent.sh` | Thin shell wrapper around `claude` — called by `ralph.sh` |
 | `lib/prompt.md` | Phase 1 prompt: tells Claude how to load a slice from the board |
 | `lib/backend-prompt.md` | Phase 2 prompt: tells Claude how to build a planned slice |
 | `lib/AGENT.md` | Agent instructions included in Claude's context |
 
 ## How it works
 
-**Phase 1** — triggered when `tasks.json` has entries:
-- The realtime agent writes a task to `tasks.json` each time a `slice:changed` event arrives from the board
-- The loop picks it up and runs Claude (or a local model) with `prompt.md`
+**Phase 1** — triggered when the task queue has entries (the queue is the event log in `.build-kit/events/`):
+- The realtime agent queues a task (`task-queued`) each time a `slice:changed` event arrives from the board; a newer change to the same slice replaces its queued task
+- The loop hands the oldest one to Claude (or a local model) with `prompt.md` and completes it (`task-done`) when the turn ends
 - Claude loads the slice data and updates `.slices/`
 
 **Phase 2** — triggered when any file in `.slices/` contains `"status": "Planned"`:
@@ -55,18 +52,6 @@ node .build-kit/ralph-claude.js /path/to/project
 
 Both phases run in a continuous loop with a 3-second idle sleep. The realtime agent runs concurrently in the same process.
 
-## Running the realtime agent separately
-
-If you want the board subscription in one terminal and the Claude loop in another:
-
-```bash
-# Terminal 1 — realtime agent only
-node .build-kit/realtime-agent.js
-
-# Terminal 2 — loop only (poll tasks.json without the realtime subscription)
-.build-kit/ralph.sh
-```
-
 ## Local-AI configuration
 
 `ralph-local-ai.js` drives any local or self-hosted model that can do tool calling.
@@ -78,7 +63,7 @@ Claude (`ralph-claude.js`) stays the default runner — this is opt-in.
 Planned. That is by design, not a bug:
 
 - **Planned slices are never handed to it.** `ralph-local-ai.js` gives `startRalph` no
-  `onPlannedSlice`, so the loop only feeds it `tasks.json` prompts.
+  `onPlannedSlice`, so the loop only feeds it queued tasks.
 - **It has no coding tools.** `lib/local-ai-agent.js` exposes only the board MCP tools:
   no file read/write, no shell, no git, no test run.
 - **Its system prompt forbids file and shell access.** Such a request is answered with

package/shared/build-kit/lib/agent-lock.js

@@ -0,0 +1,75 @@
+// One agent id, one live process. An agent keeps its stable id (see ensureAgentId); a second process that would
+// share it — two `run`s in one project, two standalone runs from one repo — gets a fresh id instead. Sharing one
+// would make them fight over a single heartbeat row and a single chat, and the second one's start-up recovery
+// would hand back the first one's prompts.
+//
+// The id is claimed with an exclusive lock file (`<id>.lock`, holding the pid) that the process removes on exit. It
+// is written complete under a private name and then hard-linked into place, so a competitor never finds it empty
+// and mistakes a lock being taken for one left over.
+// A lock left by a process that is gone — a crash, kill -9 — is taken over. A lock problem never stops an agent:
+// if locking is impossible the stable id is simply kept.
+
+import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { join } from 'path';
+import { isProcessAlive } from './slice-run.js';
+
+const answers = new Map(); // lock file path → the answer given in this process, so asking twice is one decision
+const owned = new Set(); // lock files this process holds
+let exitHooked = false;
+
+function release() {
+  for (const path of owned) {
+    try {
+      if (JSON.parse(readFileSync(path, 'utf-8')).pid === process.pid) rmSync(path, { force: true });
+    } catch { /* already gone */ }
+  }
+  owned.clear();
+}
+
+// true: the lock is ours; false: a live process of another pid holds it.
+function lock(path, pid, isAlive) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const mine = `${path}.${pid}.${randomUUID()}.tmp`;
+      writeFileSync(mine, JSON.stringify({ pid, startedAt: new Date().toISOString() }));
+      try {
+        linkSync(mine, path); // EEXIST when someone holds it — atomically, and never half written
+      } finally {
+        rmSync(mine, { force: true });
+      }
+      owned.add(path);
+      if (!exitHooked) { exitHooked = true; process.on('exit', release); }
+      return true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') return true; // cannot lock here (permissions, odd filesystem): do not get in the way
+      let holder = null;
+      try { holder = JSON.parse(readFileSync(path, 'utf-8')).pid; } catch { /* unreadable: left over */ }
+      if (holder === pid) return true;
+      if (holder !== null && isAlive(holder)) return false;
+      rmSync(path, { force: true }); // left over by a process that is gone — take it over
+    }
+  }
+  return true;
+}
+
+// `stableId` is the id this agent keeps. Returns { agentId, fellBack }: the stable id when this process got the
+// lock, else a fresh one. Decided once per process and lock directory.
+export function acquireAgentId({ lockDir, stableId, mint = randomUUID, isAlive = isProcessAlive, pid = process.pid }) {
+  const path = join(lockDir, `${stableId}.lock`);
+  if (answers.has(path)) return answers.get(path);
+  let taken = true;
+  try {
+    mkdirSync(lockDir, { recursive: true });
+    taken = lock(path, pid, isAlive);
+  } catch { /* cannot lock here: keep the stable id */ }
+  const answer = taken ? { agentId: stableId, fellBack: false } : { agentId: mint(), fellBack: true };
+  answers.set(path, answer);
+  return answer;
+}
+
+// Releases this process's locks and forgets what it decided — for tests, and a clean shutdown.
+export function forgetAgentLocks() {
+  release();
+  answers.clear();
+}

package/shared/build-kit/lib/agent-name.js

@@ -0,0 +1,27 @@
+// The name an agent shows on the board when nobody gave it one: the repository it runs in and what it is
+// ("cart-service (build)"). Derived on every start, so it is stable for as long as the repo is, and never
+// written into the project's config — `agentName` there (init --name) and `run --name` still win.
+
+import { execFileSync } from 'child_process';
+import { basename } from 'path';
+
+// `git@github.com:acme/cart-service.git`, `https://host/acme/cart-service/`, `ssh://git@host:2222/a/b.git` →
+// the last path segment without `.git`.
+function repoNameFromRemote(url) {
+  const last = url.trim().replace(/\/+$/, '').split(/[/:]/).pop() ?? '';
+  return last.replace(/\.git$/, '');
+}
+
+export function defaultAgentName(projectDir, agentType = 'BUILD') {
+  let repo = '';
+  try {
+    repo = repoNameFromRemote(execFileSync('git', ['config', '--get', 'remote.origin.url'], { cwd: projectDir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }));
+  } catch { /* no remote, or not a git repo */ }
+  return `${repo || basename(projectDir)} (${agentType.toLowerCase()})`;
+}
+
+// A second agent in the same repo gets a fresh id (see agent-lock.js); its default name says which instance it is,
+// so the board does not show two rows of the same name.
+export function withInstanceSuffix(name, agentId) {
+  return `${name} · ${String(agentId).slice(0, 4)}`;
+}

package/shared/build-kit/lib/event-prune.js

@@ -0,0 +1,58 @@
+// Pruning the event log. The log only grows, and most of it is the prompt journal — a received/finished pair per
+// board prompt, plus every tool call of a `--verbose` run — which nothing reads once the prompt is finished. What
+// the state is derived from (claims, settles, learnings, the task queue, prompts still open) is never touched.
+// Before anything is deleted the state is folded from what would be left and compared with the state folded from
+// the whole log; a difference aborts the prune.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { isDeepStrictEqual } from 'util';
+import { join } from 'path';
+import { EVENTS_DIR, INDEX_FILE, readEvents } from './slice-events.js';
+import { fold } from './slice-state.js';
+
+export const PRUNE_EVERY = 1000;
+const ASKED_FILE = '.prune-asked'; // inside events/, which readEvents never lists and the kit's git rules already cover
+
+const JOURNAL_TYPES = new Set(['prompt-received', 'prompt-finished', 'prompt-action', 'tool-call']);
+
+// The events of prompts that have finished (and of nothing else).
+export function prunableEvents(events) {
+  const finished = new Set(events.filter((e) => e?.type === 'prompt-finished').map((e) => e.prompt));
+  return events.filter((e) => e && JOURNAL_TYPES.has(e.type) && finished.has(e.type === 'prompt-received' ? e.prompt?.id : e.prompt));
+}
+
+// Deletes them: their files, then their lines from the index (rewritten whole and renamed into place). Returns
+// { removed, kept }; removes nothing when there is nothing to remove, and throws without touching the log when
+// the state folded from the rest would differ.
+export function pruneLog(kitDir) {
+  const events = readEvents(kitDir);
+  const doomed = new Set(prunableEvents(events).map((e) => e.id));
+  if (!doomed.size) return { removed: 0, kept: events.length };
+  const rest = events.filter((e) => !doomed.has(e.id));
+  if (!isDeepStrictEqual(fold(rest), fold(events))) throw new Error('pruning would change the state the log folds to — nothing was deleted');
+
+  for (const id of doomed) rmSync(join(kitDir, EVENTS_DIR, `${id}.json`), { force: true });
+  const index = join(kitDir, INDEX_FILE);
+  const lines = readFileSync(index, 'utf-8').split('\n').filter((l) => l.trim() && !doomed.has(l.trim()));
+  const tmp = `${index}.tmp`;
+  writeFileSync(tmp, lines.length ? `${lines.join('\n')}\n` : '', 'utf-8');
+  renameSync(tmp, index);
+  return { removed: doomed.size, kept: rest.length };
+}
+
+// Asked when the log has reached a multiple of PRUNE_EVERY it has not been asked at yet — 1000, then 2000, … — so a
+// "no" is not repeated on every start. `remember` records the size the answer was given at.
+const askedPath = (kitDir) => join(kitDir, EVENTS_DIR, ASKED_FILE);
+const bucket = (n) => Math.floor(n / PRUNE_EVERY);
+
+export function shouldOfferPrune(kitDir, count) {
+  if (bucket(count) < 1) return false;
+  let asked = 0;
+  try { asked = Number(readFileSync(askedPath(kitDir), 'utf-8')) || 0; } catch { /* never asked */ }
+  return bucket(count) > bucket(asked);
+}
+
+export function rememberPruneAnswer(kitDir, count) {
+  if (!existsSync(join(kitDir, EVENTS_DIR))) mkdirSync(join(kitDir, EVENTS_DIR), { recursive: true });
+  writeFileSync(askedPath(kitDir), String(count), 'utf-8');
+}

package/shared/build-kit/lib/events-view.js

@@ -0,0 +1,134 @@
+// The slice-state event log, decoded for a terminal (`eventmodelers events`): one plain-text line per event, the
+// filters that go with it, and a summary of the state the log folds to. Colour is the command's business.
+
+const short = (id) => (id ? String(id).slice(0, 8) : '');
+const oneLine = (text, max) => {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// slice id → title, from what the log itself knows (a claim records the slice's title).
+export function sliceTitles(events) {
+  const titles = {};
+  for (const e of events) if (e.type === 'claimed' && e.slice && e.title) titles[e.slice] = e.title;
+  return titles;
+}
+
+// How long a call took, and that it failed — nothing for an event without a duration.
+const took = (e) => (typeof e.durationMs === 'number' ? ` (${e.durationMs < 1000 ? `${e.durationMs}ms` : `${(e.durationMs / 1000).toFixed(1)}s`}${e.error ? ', failed' : ''})` : '');
+
+// [subject, detail] — what the event is about, and what it says.
+function describe(e) {
+  const tags = e.tags?.length ? ` ${e.tags.map((t) => `#${t}`).join(' ')}` : '';
+  switch (e.type) {
+    case 'board-observed': case 'agent-recorded': case 'settled':
+      return [e.slice, e.status ?? ''];
+    case 'claimed': {
+      const tree = e.cleanTree === true ? 'clean tree' : e.cleanTree === false ? 'dirty tree' : 'not a git tree';
+      return [e.slice, `pid ${e.pid}, ${tree}${e.base ? `, ${e.base.branch}@${String(e.base.head).slice(0, 8)}` : ''}${e.ticketNumber ? `, ticket ${e.ticketNumber}` : ''}${e.assignee ? `, assignee ${e.assignee}` : ''}`];
+    }
+    case 'claim-confirmed':
+      return [e.slice, ''];
+    case 'released':
+      return [e.slice, e.reason ?? ''];
+    case 'attempt-failed': {
+      const files = String(e.changed ?? '').split('\n').filter((l) => l.trim()).length;
+      const parts = [e.reason, e.status ? `back to ${e.status}` : '', files ? plural(files, 'file') : '', e.branch ?? ''].filter(Boolean);
+      return [e.slice, `${parts.join(', ')}${e.lastReply ? `: ${oneLine(e.lastReply, 80)}` : ''}`];
+    }
+    case 'blocked':
+      return [e.slice, oneLine(e.reason, 120)];
+    case 'task-queued':
+      return [e.payload?.sliceId, e.payload?.sliceStatus ?? ''];
+    case 'task-done':
+      return [e.task, ''];
+    case 'learning-recorded':
+      return ['', `[${e.topic ?? 'General'}] ${oneLine(e.text, 160)} (${e.scope ?? 'repo'}${tags})`];
+    case 'learning-retracted':
+      return [e.learning, e.reason ? oneLine(e.reason, 120) : ''];
+    case 'learning-merged':
+      return ['', `${plural(e.sources?.length ?? e.learnings?.length ?? 0, 'learning')} → ${oneLine(e.text, 120)}${e.reason ? ` — ${oneLine(e.reason, 80)}` : ''}`];
+    case 'learnings-curated':
+      return ['', ''];
+    case 'prompt-received':
+      return [e.prompt?.id, `"${oneLine(e.prompt?.text, 80)}"${e.prompt?.priority ? ', priority' : ''}, pid ${e.pid}`];
+    case 'prompt-action':
+      return [e.prompt, `${e.action ?? ''}${e.detail ? ` ${oneLine(e.detail, 140)}` : ''}${took(e)}`];
+    case 'tool-call':
+      return [e.prompt, `${oneLine(e.detail ?? e.tool, 140)}${took(e)}`];
+    case 'prompt-finished':
+      return [e.prompt, `${e.outcome ?? ''}${e.reason ? ` — ${oneLine(e.reason, 80)}` : ''}`];
+    default: {
+      const { type, id, at, meta, slice, ...rest } = e;
+      return [slice, oneLine(JSON.stringify(rest), 160)];
+    }
+  }
+}
+
+// One line: date and time (UTC, as logged), type, subject (a slice with its title when known), detail, and the first four characters of the
+// agent that wrote it with its type (build or modeling) — a log shared by several agents says who did what.
+export function formatEvent(e, { titles = {} } = {}) {
+  const time = typeof e.at === 'string' && e.at.length >= 19 ? `${e.at.slice(0, 10)} ${e.at.slice(11, 19)}` : '-'.repeat(19);
+  const [rawSubject, detail] = describe(e);
+  const title = titles[rawSubject];
+  const subject = rawSubject ? `${short(rawSubject)}${title ? ` "${title}"` : ''}` : '';
+  const agent = [e.meta?.agent_id ? String(e.meta.agent_id).slice(0, 4) : '', String(e.meta?.agent_type ?? '').toLowerCase()].filter(Boolean).join(' ');
+  return [time, String(e.type).padEnd(18), subject, detail, agent].filter((p, i) => i < 2 || p).join('  ');
+}
+
+// What an event carries beyond its line, indented under it: every field but the ones the line already shows
+// (type, id, time, who). Empty when there is nothing more to say.
+export function formatPayload(e) {
+  const { type, id, at, meta, ...rest } = e;
+  if (!Object.keys(rest).length) return '';
+  return JSON.stringify(rest, null, 2).split('\n').map((l) => `    ${l}`).join('\n');
+}
+
+// The kit's first look at each slice: its first `board-observed` event. A fresh kit records every slice already on
+// the board this way, which says nothing happened — the ids to leave out of the default view of the log.
+export function baselineIds(events) {
+  const seen = new Set();
+  const ids = new Set();
+  for (const e of events) {
+    if (e.type !== 'board-observed' || !e.slice || seen.has(e.slice)) continue;
+    seen.add(e.slice);
+    ids.add(e.id);
+  }
+  return ids;
+}
+
+// types / slice (an id prefix or part of a title) / tag / board (an id prefix — a global kit's log mixes boards) narrow
+// the log; omit is a set of event ids to leave out (see baselineIds); last keeps the final N that remain.
+export function filterEvents(events, { types, slice, tag, board, last, omit } = {}, titles = {}) {
+  let out = omit?.size ? events.filter((e) => !omit.has(e.id)) : events;
+  if (board) out = out.filter((e) => String(e.meta?.board_id ?? '').toLowerCase().startsWith(board.toLowerCase()));
+  if (types?.length) out = out.filter((e) => types.includes(e.type));
+  if (slice) {
+    const wanted = slice.toLowerCase();
+    out = out.filter((e) => {
+      const id = e.slice ?? e.payload?.sliceId;
+      return !!id && (String(id).toLowerCase().startsWith(wanted) || String(titles[id] ?? '').toLowerCase().includes(wanted));
+    });
+  }
+  if (tag) out = out.filter((e) => e.tags?.includes(tag));
+  return last ? out.slice(-last) : out;
+}
+
+// What the log folds to: slices (status, holder, attempts), the queue, prompts in hand, learnings.
+export function summarize(state, titles = {}) {
+  const lines = [];
+  const slices = Object.entries(state.slices);
+  if (!slices.length) lines.push('no slices in the log');
+  for (const [id, s] of slices) {
+    const claim = s.claim ? `  claimed by pid ${s.claim.pid}${s.claim.confirmed ? '' : ' (unconfirmed)'}` : '';
+    const name = titles[id] ?? s.claim?.title;
+    const title = name ? ` "${name}"` : '';
+    const attempts = s.attempts ? `  ${plural(s.attempts, 'failed attempt')}` : '';
+    const blocked = s.blocked ? `  blocked: ${oneLine(s.blocked.reason, 80)}` : '';
+    lines.push(`${short(id)}${title}  ${s.status ?? 'unknown'}${claim}${attempts}${blocked}`);
+  }
+  lines.push('');
+  lines.push(`${plural(state.tasks.length, 'task')} waiting · ${plural(state.prompts.length, 'prompt')} open · ${plural(state.learnings.length, 'learning')}`);
+  return lines.join('\n');
+}

package/shared/build-kit/lib/local-ai-agent.js

@@ -6,16 +6,17 @@
 //   ollama  — Ollama's native POST /api/chat
 //   openai  — the OpenAI-compatible POST /v1/chat/completions that vLLM, LM Studio,
 //             llama.cpp-server, TGI, SGLang (and hosted gateways) all speak
-// Everything above the transport — the MCP tool loop, the tasks.json queue, the
+// Everything above the transport — the MCP tool loop, the
 // security prompt — is identical for both, which is why this is one file and not
 // one kit per vendor.
 //
 // Usage: node local-ai-agent.js [model]
 //        LOCAL_AI_TARGET=vllm node local-ai-agent.js
 //        LOCAL_AI_URL=http://gpu-box:8000/v1 LOCAL_AI_MODEL=Qwen/Qwen3-8B node local-ai-agent.js
-// Reads tasks.json, picks the next task, and passes its prompts to the model.
+// The run loop (lib/ralph.js) picks the oldest queued task and hands it over as the prompt on stdin — one task
+// per run, completed by the loop when this process exits cleanly. There is no queue file to read.
 
-import { readFileSync, writeFileSync } from 'fs';
+import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -254,28 +255,15 @@ async function runAgent(userPrompt, boardId) {
   return 'Max tool iterations reached.';
 }
 
-async function runNextTask() {
-  const tasksPath = resolve(__dirname, '..', 'tasks.json');
-  let tasks = [];
-  try { tasks = JSON.parse(readFileSync(tasksPath, 'utf8')); } catch {}
-
-  const blocked = tasks.filter(t => t.blocked === true || t.blockedBy?.length > 0);
-  if (blocked.length > 0) {
-    console.error(`[local-ai] removing ${blocked.length} blocked task(s): ${blocked.map(t => t.id).join(', ')}`);
-    tasks = tasks.filter(t => !blocked.includes(t));
-    writeFileSync(tasksPath, JSON.stringify(tasks, null, 2));
-  }
-
-  const task = tasks[0];
-  if (!task) return;
-
-  console.error(`[local-ai] task=${task.id} prompts=${task.prompts.length}`);
-
-  for (const p of task.prompts) {
-    console.log(await runAgent(p.prompt, p.board_id || defaultBoardId));
-  }
-
-  writeFileSync(tasksPath, JSON.stringify(tasks.slice(1), null, 2));
+async function readStdin() {
+  let text = '';
+  for await (const chunk of process.stdin) text += chunk;
+  return text;
 }
 
-await runNextTask();
+const prompt = await readStdin();
+if (!prompt.trim()) {
+  console.error('[local-ai] no prompt on stdin — this agent is started by the run loop with the task as its prompt');
+  process.exit(1);
+}
+console.log(await runAgent(prompt, defaultBoardId));

package/shared/build-kit/lib/mcp-register.js

@@ -3,6 +3,7 @@
 // loop (ralph-exec.js).
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
 
@@ -12,6 +13,18 @@ export function shellQuote(s) {
   return `'${String(s).replace(/'/g, `'\\''`)}'`;
 }
 
+// Older OpenCode releases have no `run --standalone`; passing it makes `opencode run` print its
+// usage and exit 1, so every turn fails. Ask the installed binary once. Overridable for tests.
+let standaloneSupported = null;
+export function opencodeSupportsStandalone() {
+  if (standaloneSupported === null) {
+    const r = spawnSync('opencode', ['run', '--help'], { encoding: 'utf8' });
+    standaloneSupported = /--standalone\b/.test(`${r.stdout || ''}${r.stderr || ''}`);
+  }
+  return standaloneSupported;
+}
+export function setOpencodeStandaloneSupport(value) { standaloneSupported = value; }
+
 // Adds or refreshes one key in a project JSON config, leaving everything else in it alone. A file
 // that isn't plain JSON (a JSONC one with comments) is not rewritten — returns false instead, and
 // the caller says what to add by hand.
@@ -50,7 +63,10 @@ const MCP_REGISTRATIONS = {
     // A plain `opencode run` hands the turn to opencode's shared background service, which was
     // started with some other env: {env:EVENTMODELERS_TOKEN} resolves to nothing there and the
     // server refuses every call. --standalone runs a private server that inherits this one's env.
-    const standalone = /\s--(standalone|server)\b/.test(` ${command}`) ? command : `${command} --standalone`;
+    // A binary without the flag runs the turn in-process already, so the flag is dropped, not added.
+    const supported = opencodeSupportsStandalone();
+    const standalone = !supported ? command.replace(/\s--standalone\b/, '')
+      : /\s--(standalone|server)\b/.test(` ${command}`) ? command : `${command} --standalone`;
     return { command: standalone, file: ok ? 'opencode.json' : null, manual: ok ? null : `add mcp.eventmodelers = ${JSON.stringify(entry)} to opencode.json` };
   },
   gemini: (command, projectDir, url) => {

package/shared/build-kit/lib/prompt-journal.js

@@ -0,0 +1,191 @@
+// The modeling agent's journal of the board prompts it takes: `prompt-received` when it claims one, then
+// `prompt-finished` with the outcome. The platform decides who gets a prompt (an atomic claim); this is the
+// agent's own record of what it had in hand.
+
+import { appendEvent, readEvents } from './slice-events.js';
+import { fold } from './slice-state.js';
+import { redactString } from './redact.js';
+
+// What identifies the prompt and what `replay` needs to submit it again (text, timeline, canvas context) — not the
+// platform's own columns (status, claim, timestamps).
+export function journalPromptReceived({ kitDir, prompt, meta }) {
+  if (!prompt?.id) return;
+  appendEvent(kitDir, {
+    type: 'prompt-received',
+    pid: process.pid,
+    prompt: {
+      id: prompt.id,
+      text: String(prompt.prompt ?? ''),
+      board_id: prompt.board_id,
+      timeline_id: prompt.timeline_id,
+      ...(prompt.context ? { context: prompt.context } : {}),
+      priority: prompt.priority,
+      agent_id: prompt.agent_id ?? null,
+      node_id: prompt.node_id,
+      comment_id: prompt.comment_id,
+    },
+  }, meta);
+}
+
+// outcome: worked | released | already-settled | gone. A turn that failed is not finished: its entry stays
+// open, and the next start recovers it.
+export function journalPromptFinished({ kitDir, id, outcome, reason, meta }) {
+  appendEvent(kitDir, { type: 'prompt-finished', prompt: id, outcome, ...(reason ? { reason } : {}) }, meta);
+}
+
+// ── what a turn did on the board ────────────────────────────────────────────────
+// `prompt-received` and `prompt-finished` say a prompt was taken and a turn ended; they cannot say what happened in
+// between. Each board write the turn makes is journaled as it streams past — a comment, a slice moved to Blocked,
+// nodes placed — so the log reads as what the agent did, and a turn that dies half way still shows how far it got.
+// Reads are not journaled. Only what the runner can see is: a write made through curl in Bash is not.
+
+const oneLine = (text, max) => {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+const count = (list) => (Array.isArray(list) ? list.length : 1);
+
+// tool → what to journal; null for a tool that writes nothing to the board.
+const BOARD_WRITES = {
+  add_comment: ({ comments = [] }) => {
+    const nodes = new Set(comments.map((c) => c?.nodeId).filter(Boolean)).size;
+    const first = oneLine(comments[0]?.text, 100);
+    return { action: 'commented', detail: `${plural(comments.length, 'comment')} on ${plural(nodes, 'node')}${first ? `: "${first}"` : ''}` };
+  },
+  update_comment: ({ action, commentId }) => ({ action: `comment-${action === 'delete' ? 'deleted' : 'resolved'}`, detail: String(commentId ?? '').slice(0, 8) }),
+  update_slice_status: ({ newStatus, sliceId, sliceTitle }) => ({ action: 'slice-status', detail: `${sliceTitle ? `"${oneLine(sliceTitle, 60)}"` : String(sliceId ?? '').slice(0, 8)} → ${newStatus}` }),
+  submit_node_events: ({ events = [] }) => {
+    const by = {};
+    for (const e of events) by[e?.type ?? 'event'] = (by[e?.type ?? 'event'] ?? 0) + 1;
+    return { action: 'nodes-changed', detail: Object.entries(by).map(([t, n]) => `${n} ${t}`).join(', ') };
+  },
+  place_element: ({ elements }) => ({ action: 'placed', detail: plural(count(elements), 'element') }),
+  delete_node: ({ nodeIds }) => ({ action: 'nodes-deleted', detail: plural(count(nodeIds), 'node') }),
+  create_slice: ({ type, status }) => ({ action: 'slice-created', detail: [type, status].filter(Boolean).join(', ') }),
+  create_chapter: ({ title }) => ({ action: 'chapter-created', detail: title ? `"${oneLine(title, 60)}"` : '' }),
+  add_column: ({ count: n = 1 }) => ({ action: 'columns-added', detail: String(n) }),
+  add_lane: ({ lanes }) => ({ action: 'lanes-added', detail: String(count(lanes)) }),
+  add_scenario: ({ scenarios }) => ({ action: 'scenarios-added', detail: String(count(scenarios)) }),
+  add_storyline: ({ storylines }) => ({ action: 'storylines-added', detail: String(count(storylines)) }),
+  set_connection: ({ connections }) => ({ action: 'connections-changed', detail: String(count(connections)) }),
+  link_element: () => ({ action: 'linked', detail: '' }),
+  create_screen: ({ screens }) => ({ action: 'screens-created', detail: String(count(screens)) }),
+  post_chat_message: ({ text }) => ({ action: 'chat-posted', detail: `"${oneLine(text, 100)}"` }),
+};
+
+// The journal entry for a tool call, or null when it is not a board write.
+export function describeBoardAction(toolName, input) {
+  const describe = BOARD_WRITES[String(toolName).split('__').pop()];
+  return describe ? describe(input ?? {}) : null;
+}
+
+// Under `verbose` every call leaves exactly one entry: a board write as its action, any other call (a read, Bash, a
+// skill) as a `tool-call` with `detail` — the caller's one-line account of its input — and both carry the call's full
+// `input`, so `events --verbose` can show what was actually sent. The input is stored with the API token and anything
+// JWT-shaped masked: a skill's arguments can hold credentials, and this log is a plain file.
+//
+// A call is journaled when it ends, as one entry: stamped with when it started, and carrying `durationMs` and, when the
+// tool reported one, `error`. Timing costs nothing beyond a clock read at each end (createCallTracker).
+export function journalPromptAction({ kitDir, id, toolName, input, verbose = false, detail, secrets = [], startedAt, durationMs, error = false, meta }) {
+  if (!id) return;
+  const done = describeBoardAction(toolName, input);
+  if (!done && !verbose) return;
+  const payload = verbose && input !== undefined ? { input: JSON.parse(redactString(JSON.stringify(input), secrets)) } : {};
+  const timing = { ...(startedAt ? { at: startedAt } : {}), ...(durationMs !== undefined ? { durationMs } : {}), ...(error ? { error: true } : {}) };
+  if (done) appendEvent(kitDir, { type: 'prompt-action', prompt: id, ...done, ...timing, ...payload }, meta);
+  else appendEvent(kitDir, { type: 'tool-call', prompt: id, tool: toolName, ...(detail ? { detail } : {}), ...timing, ...payload }, meta);
+}
+
+// Which calls are in flight, and for how long. `begin` and `end` are a Map operation and a clock read; calls that are
+// never going to be journaled should not be begun (shouldJournalCall). `drain` returns what never ended — a turn that
+// died mid-call — without a duration.
+export const shouldJournalCall = (toolName, input, verbose) => verbose || describeBoardAction(toolName, input) !== null;
+
+export function createCallTracker({ now = () => performance.now(), clock = () => new Date().toISOString() } = {}) {
+  const open = new Map();
+  return {
+    begin(id, call) { open.set(id, { ...call, startedAt: clock(), t0: now() }); },
+    end(id, { isError = false } = {}) {
+      const call = open.get(id);
+      if (!call) return null;
+      open.delete(id);
+      const { t0, ...rest } = call;
+      return { ...rest, durationMs: Math.round(now() - t0), error: !!isError };
+    },
+    drain() {
+      const rest = [...open.values()].map(({ t0, ...call }) => call);
+      open.clear();
+      return rest;
+    },
+  };
+}
+
+export function openPrompts(kitDir) {
+  return fold(readEvents(kitDir)).prompts;
+}
+
+// ── restart recovery ────────────────────────────────────────────────────────────
+// The platform records who holds a prompt (`claimed_by`, the agent id) and never re-queues one by itself. A
+// freshly started agent holds nothing, so whatever the platform still shows as CLAIMED / IN_PROGRESS under its
+// own id is what an earlier run left behind — handed back at start. (Prompts of an agent that never comes back
+// are the platform's to release, once its heartbeat has lapsed.) Two live processes must not share one agent
+// id: the second would hand back the first one's prompts.
+
+const REASON = 'recovered after a restart';
+
+// `fetchHeld(agentId)` → [{ id, status }] the platform shows as held by that agent; `release(id)` puts a prompt
+// back on the queue and throws an error carrying `status` when the platform refuses. The journal's open entries
+// are closed along the way: released ones as 'released', the rest as 'already-settled'. Whatever cannot be
+// settled now (platform unreachable, a 5xx on a hand-back) stays open and is tried again at the next start.
+export async function recoverOwnPrompts({ kitDir, meta, agentId, fetchHeld, release }) {
+  const open = openPrompts(kitDir);
+  const result = { released: 0, settled: 0, left: 0 };
+  if (!agentId) return { ...result, left: open.length };
+
+  let held;
+  try {
+    held = await fetchHeld(agentId);
+  } catch (err) {
+    console.error(`[modeling] could not ask the platform which prompts this agent was holding${open.length ? ` — leaving ${open.length} unfinished for the next start` : ''}:`, err.message);
+    return { ...result, left: open.length };
+  }
+
+  const finish = (id, outcome) => journalPromptFinished({ kitDir, id, outcome, reason: REASON, meta });
+  const isOpen = (id) => open.some((p) => p.id === id);
+  for (const { id } of held) {
+    try {
+      await release(id);
+      if (isOpen(id)) finish(id, 'released');
+      result.released++;
+    } catch (err) {
+      // 409: it is already back on the queue; 404: it was deleted — nothing left to hand back.
+      if (err?.status === 409 || err?.status === 404) {
+        if (isOpen(id)) finish(id, err.status === 404 ? 'gone' : 'already-settled');
+        result.settled++;
+      } else {
+        console.error(`[modeling] could not hand prompt ${id} back — it stays held for the next start:`, err.message);
+        result.left++;
+      }
+    }
+  }
+  // Entries the platform does not show as held any more finished (or went) after all.
+  const heldIds = new Set(held.map((h) => h.id));
+  for (const p of open) {
+    if (heldIds.has(p.id)) continue;
+    finish(p.id, 'already-settled');
+    result.settled++;
+  }
+  return result;
+}
+
+// What asks the platform which prompts an agent holds: GET /prompts?claimed_by=, which reads and claims nothing.
+// Like the other prompt routes it needs the API token *and* an authenticated user — the realtime JWT the agent
+// already holds for /prompts/next.
+export function heldPromptsRequest({ baseUrl, organizationId, boardId, token, jwt, agentId }) {
+  const query = new URLSearchParams({ board_id: boardId, claimed_by: agentId, status: 'CLAIMED,IN_PROGRESS', limit: '500' });
+  return {
+    url: `${baseUrl}/api/org/${organizationId}/prompts?${query}`,
+    headers: { 'x-token': token, Authorization: `Bearer ${jwt}`, 'x-agent-id': agentId },
+  };
+}