@eventmodelers/cli 1.0.162 → 2.0.1

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

@@ -0,0 +1,181 @@
+// The run loop's shell around the pure slice-state core: claim a slice, settle it after the build, and
+// release claims a dead process left behind. Every step appends events and re-projects status for the
+// build agent; `decide*` (slice-state.js) says what to do, this executes it.
+//
+// `board` is injected: { setStatus(sliceId, status), readStatus(sliceId) → status | null }. null means
+// 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 { adoptAgentEdits, projectStatus } from './slice-projection.js';
+import { discardUnfinishedWork, gitBase } from './slice-git.js';
+
+// Appends an event and re-projects status, so the files the agent reads never lag the log.
+export function recordEvent(kitDir, event, meta) {
+  appendEvent(kitDir, event, meta);
+  const state = fold(readEvents(kitDir));
+  projectStatus(kitDir, state);
+  return state;
+}
+
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM'; // exists, just not ours; ESRCH means gone
+  }
+}
+
+// The build agent's side (behind `eventmodelers slice-status`): it records the outcome of the slice the
+// loop has claimed, instead of editing index.json. The loop pushes it to the board when the build ends.
+// The slice is the one open claim, or the one named by id or title. Appends `agent-recorded` and
+// projects straight away — the file the agent reads must never lag the log, or the next refresh would
+// take the stale file for an edit.
+export function recordAgentStatus({ kitDir, status, sliceId, meta }) {
+  const claimed = Object.entries(fold(readEvents(kitDir)).slices).filter(([, s]) => s.claim);
+  let match;
+  if (sliceId) {
+    const wanted = sliceId.trim().toLowerCase();
+    match = claimed.find(([id, s]) => id === sliceId || s.claim.title?.toLowerCase() === wanted);
+    if (!match) throw new Error(`slice "${sliceId}" is not claimed by the run loop — only a slice the loop is building has its status recorded here`);
+  } else if (claimed.length === 1) {
+    match = claimed[0];
+  } else if (claimed.length > 1) {
+    throw new Error(`${claimed.length} slices are claimed (${claimed.map(([, s]) => s.claim.title).join(', ')}) — name one with --slice`);
+  } else {
+    throw new Error('no slice is claimed by the run loop. For a task from tasks.json, set the status with the update-slice-status skill instead');
+  }
+  const [id, { claim }] = match;
+  recordEvent(kitDir, { type: 'agent-recorded', slice: id, status }, meta);
+  return { slice: id, title: claim.title ?? id, status };
+}
+
+// Claims a slice before it is built. The log is the local arbiter (the first claim wins); the board is
+// the cross-agent one — it rejects a move into the status a slice is already in, and a claim first checks the slice is
+// still in the pickup status. Returns 'won', 'held'
+// (another live process owns it in this kit) or 'lost' (the board refused; nothing was built).
+export async function claimSlice({ kitDir, planned, board, meta, cleanTree, pid = process.pid, pickupStatus = 'Planned' }) {
+  const open = fold(readEvents(kitDir)).slices[planned.id]?.claim;
+  if (open && open.pid !== pid && isProcessAlive(open.pid)) return 'held';
+  // Look at the board before claiming. Its same-status guard only turns away an InProgress over an InProgress, so an
+  // agent working from a stale view (Planned, while another has already built and finished it) would otherwise move
+  // a Done slice back to InProgress and build it twice. What the board really shows is recorded, which also puts the
+  // loop's stale local view right. (Two claims in the same instant are still decided by that same-status guard.)
+  if (board) {
+    let current;
+    try {
+      current = await board.readStatus(planned.id);
+    } catch (err) {
+      console.error(`[ralph] Could not read the board before claiming "${planned.title}":`, err.message);
+      return 'lost';
+    }
+    if (current && current.toLowerCase() !== pickupStatus.toLowerCase()) {
+      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';
+    }
+  }
+  const state = recordEvent(kitDir, {
+    type: 'claimed', slice: planned.id, ctx: planned.ctx, title: planned.title, pid, base: gitBase(kitDir), cleanTree,
+    // What the board says about the slice at build time, when it says anything: both can change between builds.
+    ...(planned.ticketNumber ? { ticketNumber: planned.ticketNumber } : {}),
+    ...(planned.assignee ? { assignee: planned.assignee } : {}),
+  }, meta);
+  if (state.slices[planned.id].claim?.pid !== pid) return 'held';
+  if (board) {
+    try {
+      await board.setStatus(planned.id, 'InProgress');
+    } catch (err) {
+      console.error(`[ralph] Could not claim "${planned.title}" on the board:`, err.message);
+      recordEvent(kitDir, { type: 'released', slice: planned.id, reason: 'lost' }, meta);
+      // Counted like any attempt that did not move the slice, so one the board keeps refusing is switched away from.
+      recordEvent(kitDir, { type: 'attempt-failed', slice: planned.id, reason: 'claim-lost', lastReply: null }, meta);
+      return 'lost';
+    }
+  }
+  recordEvent(kitDir, { type: 'claim-confirmed', slice: planned.id }, meta);
+  return 'won';
+}
+
+// Executes what decideSettle / decideRecovery returned for one slice. false when the board refused the
+// push — no `settled` is appended then, so the claim stays open and the next iteration settles it again.
+async function runActions({ kitDir, planned, board, meta, actions, details }) {
+  const unfinished = actions.some((a) => a.type === 'discard');
+  let discarded = null;
+  for (const a of actions) {
+    if (a.type === 'discard') {
+      discarded = discardUnfinishedWork(kitDir, planned, !a.skip, a.base);
+    } else if (a.type === 'push') {
+      if (board) {
+        try {
+          await board.setStatus(planned.id, a.status);
+        } catch (err) {
+          console.error(`[ralph] Could not settle the status of "${planned.title}":`, err.message);
+          return false;
+        }
+      }
+      recordEvent(kitDir, { type: 'settled', slice: planned.id, status: a.status }, meta);
+      console.log(`[ralph] "${planned.title}" InProgress → ${a.status}.`);
+    } else if (a.type === 'release') {
+      recordEvent(kitDir, { type: 'released', slice: planned.id, reason: a.reason }, meta);
+    }
+  }
+  // Counted once the slice is actually back, so a retried settle cannot count the attempt twice.
+  if (unfinished) {
+    recordEvent(kitDir, {
+      type: 'attempt-failed',
+      slice: planned.id,
+      reason: details.built === false ? 'turn-failed' : 'no-outcome',
+      status: actions.find((a) => a.type === 'push')?.status,
+      lastReply: details.lastReply ?? null,
+      ...(discarded ?? {}),
+    }, meta);
+    console.log(`[ralph] "${planned.title}" ended without an outcome.`);
+  }
+  return true;
+}
+
+// After a build: the outcome the agent recorded is pushed to the board; no outcome means unfinished —
+// its work is discarded and the slice goes back to `pickupStatus`. Returns true once settled; false when
+// it could not be (the claim stays open and the loop tries again at the top of its next iteration).
+export async function settleSlice({ kitDir, planned, board, meta, pickupStatus = 'Planned', details = {} }) {
+  const state = adoptAgentEdits(kitDir, fold(readEvents(kitDir)), meta);
+  if (!state.slices[planned.id]?.claim) return true;
+  let boardStatus = null;
+  if (board) {
+    try {
+      boardStatus = await board.readStatus(planned.id);
+    } catch (err) {
+      console.error(`[ralph] Could not read the board to settle "${planned.title}":`, err.message);
+      return false;
+    }
+  }
+  const actions = decideSettle(state, planned.id, { boardStatus, pickupStatus });
+  return runActions({ kitDir, planned, board, meta, actions, details });
+}
+
+// Claims still open at the top of an iteration are leftovers: the process died mid-build, or settling
+// failed last time. Each is settled like a finished build; one held by another live process is left alone.
+export async function settleLeftoverClaims({ kitDir, board, meta, pickupStatus = 'Planned', selfPid = process.pid, isAlive = isProcessAlive }) {
+  const state = adoptAgentEdits(kitDir, fold(readEvents(kitDir)), meta);
+  const boardStatuses = {};
+  const unreadable = new Set();
+  for (const [id, s] of Object.entries(state.slices)) {
+    if (!s.claim || !board || (s.claim.pid !== selfPid && isAlive(s.claim.pid))) continue;
+    try {
+      boardStatuses[id] = await board.readStatus(id);
+    } catch (err) {
+      console.error(`[ralph] Could not read the board to settle the leftover claim on "${s.claim.title ?? id}":`, err.message);
+      unreadable.add(id);
+    }
+  }
+  for (const { slice, actions } of decideRecovery(state, { isAlive, selfPid, boardStatuses, pickupStatus })) {
+    if (unreadable.has(slice)) continue;
+    const claim = state.slices[slice].claim;
+    const planned = { id: slice, title: claim.title ?? slice, ctx: claim.ctx };
+    console.log(`[ralph] Found an unsettled claim on "${planned.title}" — settling it.`);
+    await runActions({ kitDir, planned, board, meta, actions, details: { built: false } });
+  }
+}

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

@@ -0,0 +1,182 @@
+// Local slice state as an event log: `fold` derives it, `decide*` turn it into actions. Both are pure —
+// the run loop appends the events, executes the actions and appends what came of them.
+// Design and the precedence rule: slice-state-test-design.md.
+//
+// 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
+// newer loop's log is readable.
+
+const emptySlice = () => ({
+  status: undefined,
+  claim: null,
+  pendingOutcome: null,
+  lastBoardStatus: undefined,
+  attempts: 0,
+  retryStatus: undefined,
+  lastFailure: null,
+  blocked: null,
+});
+
+const same = (a, b) => typeof a === 'string' && typeof b === 'string' && a.toLowerCase() === b.toLowerCase();
+
+const apply = {
+  // While a claim is open the board's view is recorded but does not touch `status`: a refresh that
+  // still shows InProgress must not revert the outcome the agent recorded. Attempts reset only between
+  // builds — our own claim moving the board to InProgress is not the slice leaving Planned.
+  'board-observed'(s, e) {
+    s.lastBoardStatus = e.status;
+    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.
+    if (!same(e.status, s.retryStatus ?? 'Planned')) { s.attempts = 0; s.lastFailure = null; }
+    if (!same(e.status, 'Blocked')) s.blocked = null;
+  },
+  // First claim wins: while one is open a second `claimed` for the slice is ignored.
+  claimed(s, e) {
+    if (s.claim) return;
+    s.claim = { pid: e.pid, confirmed: false, base: e.base ?? null, cleanTree: e.cleanTree, ctx: e.ctx, title: e.title, prevStatus: s.status };
+    s.pendingOutcome = null;
+    s.status = 'InProgress';
+  },
+  'claim-confirmed'(s) {
+    if (s.claim) s.claim.confirmed = true;
+  },
+  'agent-recorded'(s, e) {
+    s.status = e.status;
+    if (s.claim) s.pendingOutcome = e.status;
+  },
+  settled(s, e) {
+    s.claim = null;
+    s.pendingOutcome = null;
+    s.status = e.status;
+    s.lastBoardStatus = e.status;
+  },
+  // The claim ended without anything pushed: the slice shows what the board last said (someone else may
+  // have moved it meanwhile), or what it was before the claim if the board was never observed.
+  released(s) {
+    if (!s.claim) return;
+    s.status = s.lastBoardStatus ?? s.claim.prevStatus;
+    s.claim = null;
+    s.pendingOutcome = null;
+  },
+  'attempt-failed'(s, e) {
+    s.attempts += 1;
+    s.retryStatus = e.status ?? 'Planned';
+    // What the next build is told about the one that failed.
+    s.lastFailure = { at: e.at, reason: e.reason, lastReply: e.lastReply ?? null, branch: e.branch ?? null, created: e.created ?? [], changed: e.changed ?? '' };
+  },
+  // A block starts the count afresh: an unblocked slice gets a full budget again.
+  blocked(s, e) {
+    s.blocked = { reason: e.reason, at: e.at };
+    s.status = 'Blocked';
+    s.attempts = 0;
+    s.lastFailure = null;
+  },
+};
+
+// The curator's merge: the known sources are replaced by one learning, in the slot of the first of them.
+function mergeLearnings(learnings, e) {
+  const sources = learnings.filter((l) => e.learnings?.includes(l.id));
+  if (!sources.length) return learnings;
+  const tags = [...new Set([...sources.flatMap((l) => l.tags), ...(e.tags ?? [])])];
+  const merged = { id: e.id, text: e.text, topic: e.topic ?? sources[0].topic, slice: undefined, scope: e.scope ?? sources[0].scope, tags, curated: true };
+  return learnings.flatMap((l) => (l === sources[0] ? [merged] : sources.includes(l) ? [] : [l]));
+}
+
+export function fold(events) {
+  const slices = {};
+  let learnings = [];
+  let tasks = [];
+  const prompts = new Map(); // board prompts the modeling agent took and has not finished, in the order received
+  for (const e of events) {
+    if (!e) continue;
+    if (e.type === 'prompt-received' && e.prompt?.id) {
+      const { id, text, board_id, priority, agent_id } = e.prompt;
+      prompts.set(id, { id, pid: e.pid, at: e.at, text, board_id, priority, agent_id: agent_id ?? null });
+    } else if (e.type === 'prompt-finished') {
+      prompts.delete(e.prompt);
+    }
+    // The task queue: slice changes the agent has to react to, oldest first. A newer change to the same
+    // slice replaces its queued task (and goes to the back); `task-done` names a task by id, so a change that
+    // arrived while the agent was working the old one is a new task and survives.
+    if (e.type === 'task-queued') {
+      const sliceId = e.payload?.sliceId;
+      tasks = tasks.filter((t) => sliceId === undefined || t.payload?.sliceId !== sliceId);
+      tasks.push({ id: e.id, at: e.at, payload: e.payload });
+    } else if (e.type === 'task-done') {
+      tasks = tasks.filter((t) => t.id !== e.task);
+    }
+    // Learnings are not about one slice (the slice is just where it was learned), so they sit beside them.
+    if (e.type === 'learning-recorded') learnings.push({ id: e.id, text: e.text, topic: e.topic, slice: e.slice, scope: e.scope ?? 'repo', tags: e.tags ?? [], curated: false });
+    else if (e.type === 'learning-retracted') learnings = learnings.filter((l) => l.id !== e.learning);
+    else if (e.type === 'learning-merged') learnings = mergeLearnings(learnings, e);
+    else if (e.type === 'learnings-curated') learnings = learnings.map((l) => ({ ...l, curated: true }));
+    if (!e.slice || !Object.hasOwn(apply, e.type)) continue;
+    apply[e.type](slices[e.slice] ??= emptySlice(), e);
+  }
+  return { slices, learnings, tasks, prompts: [...prompts.values()] };
+}
+
+// The curator (an LLM, writing events) is worth a turn once this many learnings have been recorded since
+// it last reviewed them.
+export function needsCuration(state, threshold) {
+  return state.learnings.filter((l) => !l.curated).length >= threshold && threshold > 0;
+}
+
+// Two learnings that differ only in case or whitespace are the same learning.
+export function learningKey(text) {
+  return String(text).replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+// AGENTS.md: the learnings, grouped by topic (in order of first appearance), one line each, duplicates
+// dropped. Nothing is written into the file by hand — it is regenerated from the log.
+export function renderLearnings(state) {
+  const topics = new Map();
+  const seen = new Set();
+  for (const { text, topic } of state.learnings) {
+    const key = learningKey(text);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    const name = topic?.trim() || 'General';
+    if (!topics.has(name)) topics.set(name, []);
+    topics.get(name).push(String(text).trim());
+  }
+  if (!topics.size) return '';
+  const body = [...topics].map(([name, lines]) => `## ${name}\n${lines.map((l) => `- ${l}`).join('\n')}\n`).join('\n');
+  return `<!-- Generated from the slice-state event log. Record learnings with the learn command; do not edit. -->\n\n${body}`;
+}
+
+// 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} —
+// 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' } = {}) {
+  const s = state.slices[sliceId];
+  const claim = s?.claim;
+  if (!claim) return [];
+  // Never confirmed on the board: nothing of ours to push there — the slice may belong to the winner of the race.
+  if (!claim.confirmed) return [{ type: 'release', reason: 'unconfirmed' }];
+  // Someone else moved it (a person, request-feedback's Blocked) — theirs to keep.
+  if (boardStatus && !same(boardStatus, 'InProgress')) return [{ type: 'release', reason: 'moved' }];
+  const outcome = s.pendingOutcome;
+  const unfinished = !outcome || same(outcome, 'InProgress') || same(outcome, pickupStatus);
+  if (!unfinished) return [{ type: 'push', status: outcome }];
+  // `skip`: the tree already held someone's edits at claim time, so none of it is the build's debris.
+  return [{ type: 'discard', base: claim.base, skip: !claim.cleanTree }, { type: 'push', status: pickupStatus }];
+}
+
+// Claims still open at the top of a loop iteration are leftovers: the process died mid-build, or settling
+// failed last time. Each is settled the way a finished build is. A claim held by another live process
+// belongs to it — left alone.
+export function decideRecovery(state, { isAlive, selfPid, boardStatuses = {}, pickupStatus = 'Planned' }) {
+  const result = [];
+  for (const [slice, s] of Object.entries(state.slices)) {
+    if (!s.claim) continue;
+    if (s.claim.pid !== selfPid && isAlive(s.claim.pid)) continue;
+    result.push({ slice, actions: decideSettle(state, slice, { boardStatus: boardStatuses[slice] ?? null, pickupStatus }) });
+  }
+  return result;
+}

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

@@ -0,0 +1,35 @@
+// The task queue is the event log: the realtime agent queues a slice change as `task-queued`, the loop replays
+// the log to find the oldest task still waiting, hands it to the agent, and appends `task-done` when the turn is
+// over. Nobody reads or rewrites a queue file, so there is nothing for two writers to collide on — a change that
+// lands mid-turn is just another event, and `task-done` names the task by id.
+
+import { appendEvent, readEvents } from './slice-events.js';
+import { fold } from './slice-state.js';
+
+// `payload` is the slice change ({ sliceId, sliceTitle, sliceStatus, ... }). Returns { id } of the task.
+export function queueTask({ kitDir, payload, meta }) {
+  return { id: appendEvent(kitDir, { type: 'task-queued', payload }, meta) };
+}
+
+export function pendingTasks(kitDir) {
+  return fold(readEvents(kitDir)).tasks;
+}
+
+// The oldest task waiting, or null. Handing it out does not consume it — `completeTask` does.
+export function nextTask(kitDir) {
+  return pendingTasks(kitDir)[0] ?? null;
+}
+
+export function completeTask({ kitDir, task, meta }) {
+  appendEvent(kitDir, { type: 'task-done', task }, meta);
+}
+
+// One turn for the oldest waiting task. `run(task)` is the agent turn and says whether it finished (false: it
+// timed out — the task stays queued and is handed out again; a turn that throws leaves it queued too). The
+// task is completed only after a finished turn. Returns whether a task was worked.
+export async function workNextTask({ kitDir, meta, run }) {
+  const task = nextTask(kitDir);
+  if (!task) return false;
+  if (await run(task)) completeTask({ kitDir, task: task.id, meta });
+  return true;
+}

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

@@ -78,7 +78,7 @@ function describeToolUse(block) {
 }
 
 // `slice` is set for a planned-slice build (see startRalph) — the only turns that are traced.
-function runClaude(prompt, slice = null) {
+function runClaude(prompt, slice = null, extraEnv = {}) {
   return new Promise((resolve, reject) => {
     // The prompt goes in on stdin, never as a `-p` argument: on Windows a multi-line argv entry
     // is cut at its first newline, so `claude` saw only the connect header, answered "I don't see
@@ -86,7 +86,7 @@ function runClaude(prompt, slice = null) {
     const proc = spawn('claude', [...claudeArgs, '-p'], {
       cwd: projectDir,
       stdio: ['pipe', 'pipe', 'inherit'],
-      env: claudeEnv,
+      env: { ...claudeEnv, ...extraEnv },
     });
     proc.stdin.end(inlineHeader + prompt);
     const turn = superviseTurn(proc, { timeoutMs, label: 'Claude turn', log: (line) => console.error(`[ralph] ${line}`) });
@@ -134,6 +134,8 @@ startRalph({
   projectDir,
   onTask: runClaude,
   onPlannedSlice: runClaude,
+  // The curation turn: the learnings tidied by an agent that may only merge and retract (see lib/slice-curation.js).
+  onCurate: (prompt, { env } = {}) => runClaude(prompt, null, env),
   localOnly,
 }).catch((err) => {
   console.error('[ralph] Fatal:', err);

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

@@ -102,7 +102,7 @@ function collectUsage(stream) {
 }
 
 // `slice` is set for a planned-slice build (see startRalph) — the only turns that are traced.
-function runExec(prompt, slice = null) {
+function runExec(prompt, slice = null, extraEnv = {}) {
   return new Promise((resolvePromise, reject) => {
     const full = inlineHeader + prompt;
     const promptFile = join(promptDir, 'prompt.md');
@@ -118,7 +118,7 @@ function runExec(prompt, slice = null) {
       cwd: projectDir,
       stdio: ['inherit', traced ? 'pipe' : 'inherit', 'inherit'],
       shell: true,
-      env: { ...childEnv, RALPH_PROMPT_FILE: promptFile },
+      env: { ...childEnv, RALPH_PROMPT_FILE: promptFile, ...extraEnv },
     });
     const turn = superviseTurn(proc, { timeoutMs, label: 'exec turn', viaShell: true, log: (line) => console.error(`[ralph-exec] ${line}`) });
     const usage = traced ? collectUsage(proc.stdout) : null;
@@ -141,6 +141,8 @@ startRalph({
   projectDir,
   onTask: runExec,
   onPlannedSlice: runExec,
+  // The curation turn: the learnings tidied by an agent that may only merge and retract (see lib/slice-curation.js).
+  onCurate: (prompt, { env } = {}) => runExec(prompt, null, env),
   localOnly,
 }).catch((err) => {
   console.error('[ralph] Fatal:', err);

package/shared/build-kit/ralph-local-ai.js

@@ -16,13 +16,15 @@ const kitDir = dirname(fileURLToPath(import.meta.url));
 const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
 
 
-function runLocalAi() {
+// The task goes in on stdin, as it does for the Claude runner: the loop has already picked it.
+function runLocalAi(prompt) {
   return new Promise((resolve, reject) => {
     const proc = spawn('node', [join(kitDir, 'lib', 'local-ai-agent.js')], {
       cwd: projectDir,
-      stdio: 'inherit',
+      stdio: ['pipe', 'inherit', 'inherit'],
       env: process.env,
     });
+    proc.stdin.end(prompt);
     proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`local-ai-agent exited ${code}`))));
     proc.on('error', reject);
   });
@@ -32,7 +34,7 @@ startRalph({
   kitDir,
   projectDir,
   onTask: runLocalAi,
-  // onPlannedSlice omitted — local-ai-agent manages its own task queue
+  // onPlannedSlice omitted — this runner works the queued tasks only
   localOnly: process.env.RALPH_LOCAL === '1',
 }).catch((err) => {
   console.error('[ralph] Fatal:', err);

package/shared/skills/connect/SKILL.md

@@ -287,11 +287,7 @@ Connecting is also where the session's read discipline starts. Every skill that
 
 ### The slice status comes with the outline
 
-The orientation read also tells you what you may write to. `get_board_outline` returns `sliceStatus` per column — a slice owns a column, so every element in that column shares its status. `get_nodes` does **not** carry it, so take it from the outline before any write:
-
-**Only a slice in `Created` may be written to.** Any other status — `Ready`, `Planned`, `Assigned`, `InProgress`, `Handover`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working on that slice: read its elements for context, but never change, move, rename or delete them, and never add scenarios, fields or examples to them. An element in a column with **no** `sliceStatus` is in no slice at all, which is not the same as locked — that one is writable.
-
-Never spend a `list_slices`/`get_slice_data` call to answer this; the outline already did.
+The orientation read also gives each column's `sliceStatus` (`get_nodes` does **not** carry it) — a slice owns a column, so every element in that column shares its status. It is context, not a write lock: any slice may be changed, whatever its status.
 
 `get_node` without a projection is for **one** node you did not already load — most often re-reading a node right after writing it. A step that issues it in a loop over nodes that were already in a list response is doing the same fetch N times; collapse it to the single chapter-scoped read above.
 

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -1066,11 +1066,22 @@ Send `x-agent-id` here too: a prompt the user addressed to one preferred agent (
 
 Note what this endpoint does *not* do: an agent that sends its id still gets every untargeted prompt on top of its own. A caller that wants only what was addressed to it has to hand the rest back itself (`POST /prompts/:id/status` with `status: 'ADDED'`), which is what `eventmodelers run --exclusive` does.
 
+The claim records its holder: `claimed_by` is the caller's `x-agent-id` (`null` if it sent none) and `claimed_at` the time. That is what tells a prompt an agent is working from one a crashed agent left behind. Before claiming, this endpoint puts prompts whose known holder has **no live heartbeat** (and that were claimed more than 45 s ago) back to `ADDED`; a prompt with no recorded holder is never handed back, and an agent that is still pinging keeps its prompts however long a turn takes. An agent that restarts under the same id finds what it was holding with `GET /prompts?claimed_by=<its id>&status=CLAIMED,IN_PROGRESS` and hands it back itself.
+
 **Query params**: `board_id` (required)
 **Response**: `200` — the claimed row (now `status: "CLAIMED"`), including its parsed `context` and the `hidden` flag · `404` — no `ADDED` prompts available
 
 ---
 
+### GET `/api/org/:orgId/prompts`
+List a board's prompts **with their status** — the only way to read a prompt's status. Read-only: nothing is claimed. Auth: `x-token` **and** a Supabase JWT (`Authorization: Bearer`) together, like `/prompts/next` — an agent uses the realtime token it already holds. A status write is unconditional (`CLAIMED` → `ADDED` works on a `DONE` prompt too), so an agent that wants to hand back prompts a crash left it holding looks here first and releases only the ones still `CLAIMED` / `IN_PROGRESS`.
+
+**Query params**: `board_id` (required) · `status` (optional, comma-separated subset of `ADDED`,`CLAIMED`,`IN_PROGRESS`,`DONE`) · `ids` (optional, comma-separated prompt ids, at most 200 — only these prompts of the board come back; an empty value asks about none, and the id of another board's prompt matches nothing) · `claimed_by` (optional, an agent id — only the prompts that agent holds) · `limit` (optional, default 200, max 500)
+**Response**: `200` — `{ "prompts": [ … ] }`, each row with `id`, `status`, `agent_id` (who it is addressed to), `claimed_by` / `claimed_at` (who holds it and since when), `priority`, `creation_time`, `node_id`, `comment_id`, the progress `comment` and the parsed `context`. Ordered like the claim: priority first, then oldest first.
+**Errors**: `400` missing `board_id`, unknown status (`PROMPT_STATUS_INVALID`), more than 200 ids or a bad `limit` · `403` the board is not in the token's organization
+
+---
+
 ### POST `/api/org/:orgId/prompts/:id/status`
 Set a prompt's status, optionally attaching a progress comment. Auth: `x-token` only (bot token — no user JWT needed, this is meant to be called directly by the agent working the prompt).
 
@@ -1084,6 +1095,8 @@ Set a prompt's status, optionally attaching a progress comment. Auth: `x-token`
 }
 ```
 
+Setting `ADDED` hands the prompt back to the queue and clears `claimed_by` / `claimed_at`; the other statuses leave the holder as it was.
+
 **Response**: `200` — the updated row
 **Errors**: `400` invalid/missing `status` · `403` token not for this prompt's org · `404` prompt not found · `409` (`PROMPT_STATUS_ALREADY_SET`) the prompt already carries that status — another agent already made this transition, so don't retry it
 

package/shared/skills/request-feedback/SKILL.md

@@ -16,8 +16,7 @@ Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect`
 **The default is to assume and build.** A missing example value, an unclear field type, a status
 mapping, a referenced event that isn't modeled yet, a dependency slice that isn't built yet — none of
 these is a reason to stop. Pick the most sensible interpretation from `slice.json`, its
-`specifications[]` and the surrounding model, build the slice, and record each assumption in one line
-in `progress.txt` and as a code comment. **Read `slice.json` fully, and read the build skill's own
+`specifications[]` and the surrounding model, build the slice, and record each assumption in one line as a code comment. **Read `slice.json` fully, and read the build skill's own
 instructions and reference docs, before concluding anything is missing.**
 
 Invoke `request-feedback` **only if the slice literally cannot be built**: even with sensible

package/shared/skills/ui-contract/SKILL.md

@@ -107,9 +107,11 @@ runner resolves `run --handover` over the project setting), else `"handover": tr
 `.eventmodelers/config.json` (saved by `init --handover` / `eventmodelers config --handover on|off`).
 
 - **On** — the build kit's "set the slice to `Done`" for a STATE_VIEW / STATE_CHANGE slice means
-  **`Handover`** instead: after the contract is published and the commit/merge succeeded, via
-  `update-slice-status` (mirrored in the local `index.json`). The UI kit claims `Handover` slices and sets
-  `Done` when its UI is built.
+  **`Handover`** instead: after the contract is published and the commit/merge succeeded. Where the build
+  kit's prompt says to call `update-slice-status` (a queued task), set `Handover` through it,
+  mirrored in the local `index.json`. For a run-loop build (the task request names the slice), record it
+  with `npx @eventmodelers/cli slice-status Handover` — the run loop pushes it to the board; do not call
+  `update-slice-status`. The UI kit claims `Handover` slices and sets `Done` when its UI is built.
 - **Off / unset** — nothing changes: `Done`.
 - Automations and translations have no UI → always `Done`.
 

package/stacks/axon/templates/build-kit/CLAUDE.md

@@ -33,16 +33,16 @@ Ignore case for files and slices in prompts. "CartItems" slice is the same as "c
 
 Do not change files with tests unless explicitely instructed, or the change brings the test in line with slice.json (e.g. step 4's field/spec diff): *.test.ts
 
-At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings. It is generated from the learnings recorded so far — record a new one with `npx @eventmodelers/cli learn "<one terse line>" --topic <topic>`, never by editing the file.
 
-When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
+When working from a queued task, invoke the `update-slice-status` skill with `InProgress` status before doing anything else. When the task request names the slice to build (a run-loop build), the run loop has already set it to `InProgress` and pushes the final status itself — do not call `update-slice-status`; record the outcome with `npx @eventmodelers/cli slice-status <status>`.
 
 ## Building a Slice
 
 **CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
 **ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
 
-**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
 
 When asked to build a slice, always follow this flow:
 

package/stacks/axon/templates/build-kit/lib/AGENT.md

@@ -1,12 +1,11 @@
-# Agent Learnings
+# Agent Reference
 
-Patterns and gotchas discovered during task processing. Update this file whenever you encounter something reusable.
+What task processing relies on: the shape of a task and the API facts the skills use. A reusable learning is recorded with `npx @eventmodelers/cli learn "<one terse line>"`, not added here.
 
-## tasks.json
+## Tasks
 
-- Tasks are objects with `id`, `createdAt`, and `payload` (a `SliceChangedPayload`).
-- After completing a task, remove it from the array entirely — do not add a status field.
-- Write `[]` to `tasks.json` if the last task is completed.
+- A task is a slice change the run loop queued: an `id` and a `payload` (a `SliceChangedPayload`). The task request names it.
+- You never read or write a queue file: the run loop completes the task when your turn ends.
 
 ## SliceChangedPayload fields
 
@@ -44,4 +43,4 @@ These files are always up to date — read them directly before invoking any ski
 - The `boardId` and `organizationId` from each payload provide full context — pass them to skills.
 - Node events use `node:created`, `node:changed`, `node:deleted` — always POST to `/api/org/:orgId/boards/:boardId/nodes/events`.
 - Slice metadata (title, status) lives on the SLICE_BORDER node under `meta.sliceStatus` and `meta.title`.
-- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard, not a bug. It means another agent already claimed the slice. Treat it as `ALREADY_IN_STATUS`, skip that slice, and move on to the next `Planned` one instead of erroring out.
+- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard, not a bug. It means another agent already claimed the slice. Treat it as `ALREADY_IN_STATUS`, skip that slice, and move on to the next `Planned` one instead of erroring out. This applies to queued tasks only: when the task request names the slice to build, the run loop owns its status — never call `/update-slice-status` there.