@eventmodelers/cli 2.0.1 → 2.0.3

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

@@ -51,6 +51,8 @@ function describe(e) {
       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 'info-recorded':
+      return [e.slice, `[${e.kind ?? 'note'}] ${oneLine(e.text, 160)}`];
     case 'prompt-received':
       return [e.prompt?.id, `"${oneLine(e.prompt?.text, 80)}"${e.prompt?.priority ? ', priority' : ''}, pid ${e.pid}`];
     case 'prompt-action':
@@ -85,10 +87,23 @@ export function formatPayload(e) {
   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; last keeps the final N that remain.
-export function filterEvents(events, { types, slice, tag, board, last } = {}, titles = {}) {
-  let out = events;
+// 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) {

package/shared/build-kit/lib/ralph.js

@@ -15,11 +15,12 @@ import { randomUUID } from 'crypto';
 import { createRealtimeAdapter, keepSubscribed } from './adapters/realtime-adapter.js';
 import { backoffMs, sleep } from './backoff.js';
 import { adoptAgentEdits, observeBoard, projectStatus, statusOf } from './slice-projection.js';
-import { fold } from './slice-state.js';
+import { fold, statusKey } from './slice-state.js';
 import { readEvents } from './slice-events.js';
 import { claimSlice, recordEvent, settleSlice, settleLeftoverClaims } from './slice-run.js';
 import { isTreeClean } from './slice-git.js';
 import { syncLearnings } from './slice-learnings.js';
+import { createBuildLogShare, kitTypeOf, SYNC_STATE_FILE } from './build-log-share.js';
 import { curateIfDue } from './slice-curation.js';
 import { queueTask, workNextTask } from './slice-tasks.js';
 import { defaultAgentName, withInstanceSuffix } from './agent-name.js';
@@ -273,8 +274,8 @@ export async function fetchAndPersistSlices(cfg, kitDir) {
   if (!activeCtx || !contexts[activeCtx]) {
     // First run (or the current context disappeared): seed with a context that
     // has planned work, else the first one. This is the ONLY place we choose it.
-    const pickup = readPickupStatus(kitDir).toLowerCase();
-    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => (s.status || '').toLowerCase() === pickup));
+    const pickup = statusKey(readPickupStatus(kitDir));
+    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => statusKey(s.status) === pickup));
     activeCtx = plannedCtx || Object.keys(contexts)[0] || 'default';
     writeFileSync(ctxPath, JSON.stringify({ name: activeCtx }, null, 2), 'utf-8');
   }
@@ -377,9 +378,9 @@ async function handleSliceChanged(payload, cfg, kitDir) {
   await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
     console.error('[agent] Slice persist error:', err),
   );
-  // Slices in the kit's pickup status (Planned, or Handover for UI kits) are handled by
+  // Slices in the kit's pickup status (Planned, or Waiting for UI kits) are handled by
   // onPlannedSlice directly — no task needed.
-  if ((payload.sliceStatus || '').toLowerCase() !== readPickupStatus(kitDir).toLowerCase()) {
+  if (statusKey(payload.sliceStatus) !== statusKey(readPickupStatus(kitDir))) {
     try {
       queueTask({ kitDir, payload, meta: eventMeta(cfg) });
       console.log(`[agent] Task queued — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
@@ -490,15 +491,19 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', createAdap
 // ── Ralph loop ────────────────────────────────────────────────────────────────
 
 // The slice status this kit claims work from. A stack declares it in `lib/kit.json`
-// ({ "pickupStatus": "Handover" } for the UI kits, which build what a backend kit handed over);
+// ({ "pickupStatus": "Waiting" } for the UI kits, which build what a backend kit handed over);
 // absent means "Planned", the backend default. `run --status-trigger <status>` (RALPH_STATUS_TRIGGER)
 // overrides either for that run.
+// `Handover` was renamed `Waiting`; a kit.json or --status-trigger written before that still says it,
+// and a board served by an older platform still reports it.
+const canonicalStatus = (s) => (statusKey(s) === 'waiting' ? 'Waiting' : s);
+
 export function readPickupStatus(kitDir) {
   const override = (process.env.RALPH_STATUS_TRIGGER || '').trim();
-  if (override) return override;
+  if (override) return canonicalStatus(override);
   try {
     const s = JSON.parse(readFileSync(join(kitDir, 'lib', 'kit.json'), 'utf-8')).pickupStatus;
-    if (typeof s === 'string' && s.trim()) return s.trim();
+    if (typeof s === 'string' && s.trim()) return canonicalStatus(s.trim());
   } catch {}
   return 'Planned';
 }
@@ -533,14 +538,14 @@ function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
   try {
     others = readdirSync(slicesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
   } catch {}
-  const pickup = readPickupStatus(kitDir).toLowerCase();
+  const pickup = statusKey(readPickupStatus(kitDir));
   const candidates = [...(currentCtx ? [currentCtx] : []), ...others.filter((c) => c !== currentCtx)];
   for (const ctx of candidates) {
     const indexPath = join(slicesDir, ctx, 'index.json');
     if (!existsSync(indexPath)) continue;
     try {
       const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
-      const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === pickup && !skipIds.has(s.id));
+      const planned = slices && slices.find((s) => statusKey(s.status) === pickup && !skipIds.has(s.id));
       if (!planned) continue;
       if (ctx !== currentCtx) {
         writeFileSync(join(slicesDir, 'current_context.json'), JSON.stringify({ name: ctx }, null, 2), 'utf-8');
@@ -555,14 +560,14 @@ function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
 // Ids of every slice currently waiting for pickup, across all contexts.
 function listPlannedIds(kitDir) {
   const slicesDir = join(kitDir, '.slices');
-  const pickup = readPickupStatus(kitDir).toLowerCase();
+  const pickup = statusKey(readPickupStatus(kitDir));
   const ids = new Set();
   try {
     for (const d of readdirSync(slicesDir, { withFileTypes: true })) {
       if (!d.isDirectory()) continue;
       try {
         const { slices } = JSON.parse(readFileSync(join(slicesDir, d.name, 'index.json'), 'utf-8'));
-        for (const s of slices ?? []) if ((s.status || '').toLowerCase() === pickup) ids.add(s.id);
+        for (const s of slices ?? []) if (statusKey(s.status) === pickup) ids.add(s.id);
       } catch {}
     }
   } catch {}
@@ -666,7 +671,7 @@ async function runWithRetry(label, fn) {
 // alone, the agent read it as background, answered "what would you like me to help with?" with
 // no tool calls, and a Planned slice stayed Planned until the stuck-slice guard blocked it. So
 // every turn ends with the concrete request — here, once, for every runner.
-// Whether a backend kit finishes UI-bearing slices at `Handover` instead of `Done`: this run's
+// Whether a backend kit finishes UI-bearing slices at `Waiting` instead of `Done`: this run's
 // `run --handover` (RALPH_HANDOVER) over the project's `handover` setting in config.json.
 export function resolveHandover(cfg) {
   return process.env.RALPH_HANDOVER === '1' || cfg?.handover === true;
@@ -720,8 +725,8 @@ function taskRequest(planned = null, cfg = null, pickupStatus = 'Planned', queue
     ? `build the ${pickupStatus} slice "${planned.title}" (id=${planned.id}, context="${planned.ctx}")`
     : `process this queued task (id=${queued?.id}) — the slice change that queued it: ${JSON.stringify(queued?.payload ?? {})}`;
   // Stated explicitly so the agent never has to work it out from config.json: this run's effective
-  // value, which is what the `ui-contract` skill (Step 4) follows. UI kits (pickup Handover) ignore it.
-  const handover = planned && pickupStatus.toLowerCase() !== 'handover' ? `\nHandover: ${resolveHandover(cfg) ? 'on' : 'off'}\n` : '';
+  // value, which is what the `ui-contract` skill (Step 4) follows. UI kits (pickup Waiting) ignore it.
+  const handover = planned && statusKey(pickupStatus) !== 'waiting' ? `\nHandover: ${resolveHandover(cfg) ? 'on' : 'off'}\n` : '';
   return `\n\n---\n\nYour task now: ${task}, following the instructions above. Start immediately.\n${handover}`;
 }
 
@@ -735,7 +740,7 @@ function ensureLearningsGitRules(kitDir) {
   const projectDir = dirname(kitDir);
   if (!existsSync(join(projectDir, '.git'))) return;
   const rules = [
-    ['info/exclude', [`${basename(kitDir)}/events/`, `${basename(kitDir)}/events.log`]],
+    ['info/exclude', [`${basename(kitDir)}/events/`, `${basename(kitDir)}/events.log`, `${basename(kitDir)}/events.seq`, `${basename(kitDir)}/${SYNC_STATE_FILE}`]],
     ['info/attributes', [`${basename(kitDir)}/AGENTS.md merge=union`]],
   ];
   for (const [name, lines] of rules) {
@@ -765,6 +770,10 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false,
   const board = credentialed ? createBoard(cfg) : null;
   const meta = eventMeta(cfg);
   ensureLearningsGitRules(kitDir);
+  // Sharing the event log with the board (`run --sync`): needs the board, so never with --local.
+  const share = createBuildLogShare({ kitDir, cfg, meta, agentType: cfg?.agentType ?? 'BUILD', kitType: kitTypeOf(readPickupStatus(kitDir)), sync: process.env.RALPH_SYNC === '1', enabled: credentialed, log: (line) => console.log(`[ralph] ${line}`) });
+  if (process.env.RALPH_SYNC === '1' && !credentialed) console.log('[ralph] --sync needs board credentials — the build log stays local.');
+  share.start();
   let lastIdleCtx;
   // The build agent's final reply on the most recent planned-slice turn — quoted in the Blocked note.
   let lastReply = null;
@@ -827,6 +836,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false,
         }
       }
       lastReply = null;
+      if (planned.id) share.iterationStarted(planned);
       const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, async () => { lastReply = await onPlannedSlice(prompt, {
         sliceId: planned.id,
         sliceTitle: planned.title,
@@ -838,6 +848,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false,
       }); });
       if (built) console.log(`[ralph] Slice build complete — waiting for next slice`);
       if (planned.id) await settleSlice({ kitDir, planned, board, meta, pickupStatus: readPickupStatus(kitDir), details: { built, lastReply } });
+      if (planned.id) await share.iterationClosed(planned, built ? 'ok' : 'error');
       if (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
     }

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

@@ -11,6 +11,7 @@ import { join } from 'path';
 
 export const EVENTS_DIR = 'events';
 export const INDEX_FILE = 'events.log';
+export const SEQ_FILE = 'events.seq';
 
 const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
@@ -49,10 +50,41 @@ export function normalizeMeta(meta) {
   return clean;
 }
 
+// The last sequence number handed out is remembered next to the index (SEQ_FILE), so numbers keep climbing
+// when events are pruned or the log is rebuilt. A kit that has no such file yet (a log written before events
+// were numbered) continues from its newest event: its own `seq`, or how many events precede it. Two processes
+// appending in the same instant can draw the same number — nothing enforces uniqueness, here or on the server:
+// the index order decides, and readEvents renumbers so a reader still sees a strictly increasing sequence.
+function newestEventSeq(kitDir) {
+  const index = join(kitDir, INDEX_FILE);
+  if (!existsSync(index)) return 0;
+  const ids = readFileSync(index, 'utf-8').split('\n').map((l) => l.trim()).filter((l) => ID.test(l));
+  for (let i = ids.length - 1; i >= 0; i--) {
+    try {
+      const { seq } = JSON.parse(readFileSync(join(kitDir, EVENTS_DIR, `${ids[i]}.json`), 'utf-8'));
+      return Number.isInteger(seq) ? seq : i + 1;
+    } catch { /* unreadable — look at the one before */ }
+  }
+  return 0;
+}
+
+// Takes the next number and remembers it.
+function nextSeq(kitDir) {
+  const file = join(kitDir, SEQ_FILE);
+  let remembered = 0;
+  try { remembered = Number.parseInt(readFileSync(file, 'utf-8'), 10) || 0; } catch { /* none yet */ }
+  const seq = Math.max(remembered, newestEventSeq(kitDir)) + 1;
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, String(seq), 'utf-8');
+  renameSync(tmp, file);
+  return seq;
+}
+
 // The event file is written whole (temp file, then rename) before its id is indexed, so a reader that
 // finds the id finds a complete file. The index line is one short append-mode write, so lines from
 // concurrent processes never interleave however large the event. After a torn index line the new id
-// starts on a fresh line instead of being glued onto the fragment. Returns the event id.
+// starts on a fresh line instead of being glued onto the fragment. Every event gets the next sequence number
+// (`seq`), which — not the timestamp — defines the order. Returns the event id.
 export function appendEvent(kitDir, event, meta) {
   const dir = join(kitDir, EVENTS_DIR);
   mkdirSync(dir, { recursive: true });
@@ -67,6 +99,7 @@ export function appendEvent(kitDir, event, meta) {
     ...rest,
     ...(cleanTags.length ? { tags: cleanTags } : {}),
     ...(Object.keys(cleanMeta).length ? { meta: cleanMeta } : {}),
+    seq: nextSeq(kitDir),
     id,
   }, null, 2), 'utf-8');
   renameSync(tmp, join(dir, `${id}.json`));
@@ -75,7 +108,7 @@ export function appendEvent(kitDir, event, meta) {
   return id;
 }
 
-// All events in index order; with `tag`, only those carrying it.
+// All events in index order, each with its `seq`; with `tag`, only those carrying it.
 export function readEvents(kitDir, { tag } = {}) {
   const index = join(kitDir, INDEX_FILE);
   if (!existsSync(index)) return [];
@@ -89,5 +122,12 @@ export function readEvents(kitDir, { tag } = {}) {
       events.push(JSON.parse(readFileSync(join(kitDir, EVENTS_DIR, `${id}.json`), 'utf-8')));
     } catch { /* indexed but missing or unreadable — skipped */ }
   }
+  // Strictly increasing in index order: an event from before numbering, or one that drew the same number as its
+  // predecessor, takes the next free one.
+  let prev = 0;
+  for (const e of events) {
+    if (!Number.isInteger(e.seq) || e.seq <= prev) e.seq = prev + 1;
+    prev = e.seq;
+  }
   return tag === undefined ? events : events.filter((e) => e.tags?.includes(tag));
 }

package/shared/build-kit/lib/slice-info.js

@@ -0,0 +1,52 @@
+// Info events: what an agent reports that is not a reusable learning — "I can't change X because Y", a
+// decision it took, a note for whoever reads the board. A learning is true of the codebase or the model for
+// every later build (slice-learnings.js); an info is about this slice, now. Infos feed no projection — the
+// event is the record — and are also posted as a comment on the slice, so the board shows them.
+
+import { appendEvent } from './slice-events.js';
+
+export const INFO_KINDS = ['limitation', 'decision', 'note'];
+const MAX_INFO_LENGTH = 500;
+
+export function recordInfo({ kitDir, text, kind = 'note', slice, tags, meta }) {
+  const clean = String(text ?? '').trim();
+  if (!clean) throw new Error('the info is empty');
+  if (!INFO_KINDS.includes(kind)) throw new Error(`kind must be ${INFO_KINDS.join(', ')}, not "${kind}"`);
+  const id = appendEvent(kitDir, { type: 'info-recorded', kind, text: clean.slice(0, MAX_INFO_LENGTH), ...(slice ? { slice } : {}), tags }, meta);
+  return { id, text: clean.slice(0, MAX_INFO_LENGTH), kind };
+}
+
+// The comment the board shows for an info.
+export function infoComment({ kind, text }) {
+  return `[${kind}] ${text}`;
+}
+
+// ── infos a turn states in its reply ────────────────────────────────────────────
+// Same contract as learnings: the locked-down modeling agent ends a reply with `Info [<kind>]: <line>` and
+// the CLI records it. At most five per reply, each capped, so what a board collaborator can talk the agent
+// into saying stays small.
+const MAX_TURN_INFOS = 5;
+const TURN_INFO = /^\s*(?:[-*]\s+)?info(?:\s*\[([^\]]{1,20})\])?:\s*(.*?)\s*$/i;
+
+export function parseTurnInfos(reply) {
+  const found = [];
+  let fenced = false;
+  for (const line of String(reply ?? '').split('\n')) {
+    if (line.trim().startsWith('```')) { fenced = !fenced; continue; }
+    if (fenced) continue;
+    const m = TURN_INFO.exec(line);
+    if (!m) continue;
+    const text = m[2];
+    if (!text || /^none\.?$/i.test(text) || text.length > MAX_INFO_LENGTH) continue;
+    const kind = m[1]?.trim().toLowerCase();
+    found.push({ kind: INFO_KINDS.includes(kind) ? kind : 'note', text });
+    if (found.length === MAX_TURN_INFOS) break;
+  }
+  return found;
+}
+
+export function recordTurnInfos({ kitDir, reply, meta }) {
+  const infos = parseTurnInfos(reply);
+  for (const { kind, text } of infos) recordInfo({ kitDir, text, kind, tags: ['modeling'], meta });
+  return infos.length;
+}

package/shared/build-kit/lib/slice-run.js

@@ -6,7 +6,7 @@
 // no board (--local): nothing is pushed or read, the log alone decides.
 
 import { appendEvent, readEvents } from './slice-events.js';
-import { fold, decideSettle, decideRecovery } from './slice-state.js';
+import { fold, decideSettle, decideRecovery, statusKey } from './slice-state.js';
 import { adoptAgentEdits, projectStatus } from './slice-projection.js';
 import { discardUnfinishedWork, gitBase } from './slice-git.js';
 
@@ -71,7 +71,7 @@ export async function claimSlice({ kitDir, planned, board, meta, cleanTree, pid
       console.error(`[ralph] Could not read the board before claiming "${planned.title}":`, err.message);
       return 'lost';
     }
-    if (current && current.toLowerCase() !== pickupStatus.toLowerCase()) {
+    if (current && statusKey(current) !== statusKey(pickupStatus)) {
       console.log(`[ralph] "${planned.title}" is ${current} on the board, not ${pickupStatus} — someone else got there first.`);
       recordEvent(kitDir, { type: 'board-observed', slice: planned.id, status: current }, meta);
       return 'lost';

package/shared/build-kit/lib/slice-state.js

@@ -4,7 +4,7 @@
 //
 // Events (one writer per type): board-observed, claimed, claim-confirmed, agent-recorded, settled,
 // released, attempt-failed, blocked, learning-recorded, learning-retracted, learning-merged, learnings-curated,
-// task-queued, task-done, prompt-received, prompt-finished. Unknown types are ignored, so a
+// info-recorded (read by nothing here — it is the record), task-queued, task-done, prompt-received, prompt-finished. Unknown types are ignored, so a
 // newer loop's log is readable.
 
 const emptySlice = () => ({
@@ -18,7 +18,9 @@ const emptySlice = () => ({
   blocked: null,
 });
 
-const same = (a, b) => typeof a === 'string' && typeof b === 'string' && a.toLowerCase() === b.toLowerCase();
+// `Handover` is the old name of `Waiting`: boards and files written before the rename still hold it.
+export const statusKey = (s) => { const k = (s || '').toLowerCase(); return k === 'handover' ? 'waiting' : k; };
+const same = (a, b) => typeof a === 'string' && typeof b === 'string' && statusKey(a) === statusKey(b);
 
 const apply = {
   // While a claim is open the board's view is recorded but does not touch `status`: a refresh that
@@ -29,7 +31,7 @@ const apply = {
     if (s.claim) return;
     s.status = e.status;
     // Attempts count builds that failed to move the slice off the status it was put back to (Planned, or
-    // Handover for UI kits); any other status means it moved. Any status but Blocked lifts a block.
+    // Waiting for UI kits); any other status means it moved. Any status but Blocked lifts a block.
     if (!same(e.status, s.retryStatus ?? 'Planned')) { s.attempts = 0; s.lastFailure = null; }
     if (!same(e.status, 'Blocked')) s.blocked = null;
   },
@@ -150,7 +152,7 @@ export function renderLearnings(state) {
 
 // What to do with a claimed slice once its build is over. `boardStatus` is the board's current status
 // for it (null when unknown or there is no board); `pickupStatus` is what an unfinished slice goes back
-// to (Planned, or Handover for UI kits). Actions: discard {base, skip}, push {status}, release {reason} —
+// to (Planned, or Waiting for UI kits). Actions: discard {base, skip}, push {status}, release {reason} —
 // the loop appends `settled` after a successful push and `released` for a release. A failed push appends
 // nothing, so the claim stays open and the next iteration settles it again.
 export function decideSettle(state, sliceId, { boardStatus = null, pickupStatus = 'Planned' } = {}) {

package/shared/scaffold/LICENSE-em-scaffold

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Mowat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.