@eventmodelers/cli 1.0.162 → 2.0.1

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

@@ -2,17 +2,28 @@
 // Not meant to be run directly — use ralph-claude.js or ralph-local-ai.js.
 //
 // startRalph({ kitDir, projectDir, onTask, onPlannedSlice })
-//   onTask(prompt) — called when tasks.json has entries
+//   onTask(prompt) — called once per queued slice change (the oldest first; see lib/slice-tasks.js)
 //   onPlannedSlice(prompt, slice) — called when .slices/ has a "Planned" entry (omit to skip);
-//     `slice` ({sliceId, sliceTitle, context, ticketNumber, boardId, attempt}) lets a runner record what building it cost.
+//     `slice` ({sliceId, sliceTitle, context, ticketNumber, assignee, boardId, attempt}) lets a runner record what building it cost.
 //     May resolve with the agent's final reply — quoted in the note if the slice ends up auto-blocked.
 
-import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, renameSync } from 'fs';
-import { join, dirname } from 'path';
+import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { join, dirname, basename } from 'path';
 import { homedir } from 'os';
+import { execFileSync } from 'child_process';
 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 { 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 { curateIfDue } from './slice-curation.js';
+import { queueTask, workNextTask } from './slice-tasks.js';
+import { defaultAgentName, withInstanceSuffix } from './agent-name.js';
+import { acquireAgentId } from './agent-lock.js';
 import { redactConsole } from './redact.js';
 
 // Backoff for calls to the platform that failed for a reason on its side (startup).
@@ -148,11 +159,11 @@ function hasCredentials(cfg) {
 }
 
 // Distinguishes this agent process from any other agent pinging the same
-// token/board — e.g. a build-kit and a bridge-kit install in the same project
+// token/board — e.g. a build-kit and a modeling-kit install in the same project
 // share one root config.json, and without a per-agent id both would upsert the
 // same alive row and race each other. The platform already keys the alive-ping
 // on the (agent_type, agent_id) pair, so one shared file works: agentIds is
-// namespaced by agentType (BUILD/BRIDGE/MODELING/...) inside the project ROOT
+// namespaced by agentType (BUILD/MODELING/...) inside the project ROOT
 // .eventmodelers/config.json — the same file credentials already live in —
 // instead of each kit dir keeping its own separate config.json. Falls back to
 // a pre-existing kit-local agentId (older installs, before this consolidation)
@@ -191,11 +202,21 @@ function ensureAgentId(kitDir, agentType) {
 // ensureAgentId above / RALPH_AGENT_ID). The heartbeat says this agent is alive; the header says
 // which calls are its, so its board writes are attributed to it and a prompt the user addressed
 // to one preferred agent is only ever claimed by that agent.
+function agentIdOf(cfg) {
+  return cfg?.agentId || process.env.RALPH_AGENT_ID || process.env.EVENTMODELERS_AGENT_ID || '';
+}
+
 function agentHeaders(cfg) {
-  const agentId = cfg?.agentId || process.env.RALPH_AGENT_ID || process.env.EVENTMODELERS_AGENT_ID || '';
+  const agentId = agentIdOf(cfg);
   return agentId ? { 'x-agent-id': agentId } : {};
 }
 
+// What every slice-state event is stamped with: this agent, its type (this loop builds unless told otherwise) and the
+// organization and board it runs against.
+function eventMeta(cfg) {
+  return { agent_id: agentIdOf(cfg), agent_type: cfg?.agentType ?? 'BUILD', organization_id: cfg?.organizationId, board_id: cfg?.boardId };
+}
+
 async function fetchPlatformConfig(local) {
   const remote = await fetchJSON(`${local.baseUrl}/api/config`, {
     headers: { 'x-token': local.token, ...agentHeaders(local) },
@@ -220,7 +241,7 @@ function slugify(str) {
   return str.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
 }
 
-async function fetchAndPersistSlices(cfg, kitDir) {
+export async function fetchAndPersistSlices(cfg, kitDir) {
   const url = `${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata/slices`;
   const { slices } = await fetchJSON(url, {
     headers: { 'x-token': cfg.token, ...agentHeaders(cfg) },
@@ -228,6 +249,12 @@ async function fetchAndPersistSlices(cfg, kitDir) {
   const slicesDir = join(kitDir, '.slices');
   mkdirSync(slicesDir, { recursive: true });
 
+  // The board's status is an observation, not the truth for the local files: while a build holds a claim
+  // a refresh that still shows InProgress must not revert the outcome the agent recorded. The status
+  // written below is the log's (statusOf), which falls back to the board's for slices it knows nothing of.
+  const meta = eventMeta(cfg);
+  const state = observeBoard(kitDir, slices, meta, adoptAgentEdits(kitDir, fold(readEvents(kitDir)), meta));
+
   // Group by context slug
   const contexts = {};
   for (const slice of slices) {
@@ -256,7 +283,7 @@ async function fetchAndPersistSlices(cfg, kitDir) {
   //
   // This endpoint (`/slicedata/slices`) is the CHEAP summary one — `{ id, title, status }`
   // only, no commands/events/specifications/codeGen prompts. Its whole job here is to keep
-  // `status` fresh so hasPendingTasks/getFirstPlannedSliceTitle see live transitions; it must
+  // `status` fresh so the loop's pickup (getFirstPlannedSlice) sees live transitions; it must
   // NEVER clobber the richer slice.json a full fetch (`/load-slice`, `eventmodelers fetch`,
   // `eventmodelers listen`) already wrote for the same slice. So every write below merges
   // onto whatever's already on disk — spreading the existing object first, the fresh summary
@@ -280,8 +307,8 @@ async function fetchAndPersistSlices(cfg, kitDir) {
         contextName: s.contextName || contextSlug,
         contextSlug,
         folder,
-        status: s.status,
-        definition: { ...existing?.definition, id: s.id, title: s.title, status: s.status },
+        status: statusOf(state, s),
+        definition: { ...existing?.definition, id: s.id, title: s.title, status: statusOf(state, s) },
       };
     });
     writeFileSync(indexPath, JSON.stringify({ slices: indexSlices }, null, 2), 'utf-8');
@@ -292,12 +319,15 @@ async function fetchAndPersistSlices(cfg, kitDir) {
       mkdirSync(sliceDir, { recursive: true });
       const sliceJsonPath = join(sliceDir, 'slice.json');
       const existingSlice = existsSync(sliceJsonPath) ? JSON.parse(readFileSync(sliceJsonPath, 'utf-8')) : {};
-      // The summary omits ticketNumber when the slice has none, so a cleared ticket must be cleared
-      // here too — otherwise the old one survives the merge and lands on the next build's trace.
-      writeFileSync(sliceJsonPath, JSON.stringify({ ...existingSlice, ...slice, ticketNumber: slice.ticketNumber ?? null }, null, 2), 'utf-8');
+      // The summary omits ticketNumber and assignee when the slice has none, so a cleared one must be cleared
+      // here too — otherwise the old one survives the merge and lands on the next build.
+      writeFileSync(sliceJsonPath, JSON.stringify({ ...existingSlice, ...slice, status: statusOf(state, slice), ticketNumber: slice.ticketNumber ?? null, assignee: slice.assignee ?? null }, null, 2), 'utf-8');
     }
   }
 
+  // Blocked notes (reason, time) follow the log too; a no-op when nothing changed.
+  projectStatus(kitDir, state);
+
   console.log(`[agent] Persisted ${slices.length} slice(s)`);
 }
 
@@ -332,65 +362,7 @@ async function fetchFullSlice(cfg, kitDir, sliceId) {
   }
 }
 
-// tasks.json has two writers: this process, queueing slice changes, and the agent, removing
-// the task it just handled (as each stack's prompt.md tells it to). An unlocked read-modify-
-// write from both sides at once lost whichever update landed first. So the two never overlap:
-// while an onTask turn runs (see inTurn), a change is held here instead — latest per slice —
-// and written the moment the turn ends. Every write goes through a temp file and a rename,
-// so a reader never sees a half-written file either.
-let heldTasks = null; // sliceId → payload while an onTask turn runs, null otherwise
-
-function writeTasksAtomically(tasksPath, tasks) {
-  const tmp = `${tasksPath}.${process.pid}.tmp`;
-  writeFileSync(tmp, JSON.stringify(tasks, null, 2), 'utf-8');
-  renameSync(tmp, tasksPath);
-}
-
-function readTasks(tasksPath) {
-  if (!existsSync(tasksPath)) return [];
-  try {
-    const tasks = JSON.parse(readFileSync(tasksPath, 'utf-8'));
-    return Array.isArray(tasks) ? tasks : [];
-  } catch {
-    return []; // the agent left it unparseable — start over rather than wedge the queue
-  }
-}
-
-function appendTasks(kitDir, payloads) {
-  const tasksPath = join(kitDir, 'tasks.json');
-  const replaced = new Set(payloads.map((p) => p.sliceId));
-  const tasks = readTasks(tasksPath).filter((t) => !replaced.has(t.payload?.sliceId));
-  for (const payload of payloads) tasks.push({ id: randomUUID(), createdAt: new Date().toISOString(), payload });
-  writeTasksAtomically(tasksPath, tasks);
-}
-
-async function writeTask(payload, kitDir) {
-  if (heldTasks) {
-    heldTasks.set(payload.sliceId, payload);
-    console.log(`[agent] Task held until the current turn ends — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
-    return;
-  }
-  appendTasks(kitDir, [payload]);
-  console.log(`[agent] Task written — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
-}
-
-// Runs one agent turn that may rewrite tasks.json, keeping this process's own writes out of
-// its way; whatever arrived meanwhile is written as soon as it's over, success or not.
-async function inTurn(kitDir, fn) {
-  heldTasks = new Map();
-  try {
-    return await fn();
-  } finally {
-    const payloads = [...heldTasks.values()];
-    heldTasks = null;
-    if (payloads.length > 0) {
-      appendTasks(kitDir, payloads);
-      console.log(`[agent] Wrote ${payloads.length} task(s) held during the turn`);
-    }
-  }
-}
-
-async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
+async function handleSliceChanged(payload, cfg, kitDir) {
   console.log(`[agent] slice:changed — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
   // This agent's own status writes (claim → InProgress, → Done, → Blocked) come straight back
   // as slice:changed. Queuing them only buys a turn in which the agent reads its own echo and
@@ -407,17 +379,19 @@ async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
   );
   // Slices in the kit's pickup status (Planned, or Handover for UI kits) are handled by
   // onPlannedSlice directly — no task needed.
-  // queueAllStatuses opts out of that split entirely (e.g. bridge has no
-  // onPlannedSlice consumer, so a lingering Planned slice would otherwise
-  // never naturally clear its own trigger — see lib/ralph.js callers).
-  if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== readPickupStatus(kitDir).toLowerCase()) {
-    await writeTask(payload, kitDir).catch((err) => console.error('[agent] writeTask error:', err));
+  if ((payload.sliceStatus || '').toLowerCase() !== readPickupStatus(kitDir).toLowerCase()) {
+    try {
+      queueTask({ kitDir, payload, meta: eventMeta(cfg) });
+      console.log(`[agent] Task queued — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
+    } catch (err) {
+      console.error('[agent] queueTask error:', err);
+    }
   }
 }
 
 // createAdapter is the realtime transport factory — injectable so the channel handling can be
 // tested against a fake transport.
-async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllStatuses = false, createAdapter = createRealtimeAdapter } = {}) {
+async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', createAdapter = createRealtimeAdapter } = {}) {
   let realtimeToken = await retryTransient('getRealtimeToken', () => getRealtimeToken(cfg));
 
   await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
@@ -466,7 +440,7 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
       console.log(`[agent] ${ts()} Received kill (instruction: ${payload.instruction ?? 'exit'}) — shutting down`);
       process.exit(0);
     },
-    'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
+    'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir),
   }, {
     log: (msg) => console.log(`[agent] ${ts()} ${msg}`),
     refreshToken,
@@ -515,10 +489,6 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
 
 // ── Ralph loop ────────────────────────────────────────────────────────────────
 
-function hasPendingTasks(kitDir) {
-  return readTasks(join(kitDir, 'tasks.json')).length > 0;
-}
-
 // 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);
 // absent means "Planned", the backend default. `run --status-trigger <status>` (RALPH_STATUS_TRIGGER)
@@ -539,22 +509,24 @@ function readCurrentContext(kitDir) {
   try { return JSON.parse(readFileSync(ctxPath, 'utf-8')).name || null; } catch { return null; }
 }
 
-// The slice's ticket as of the last fetch, from its slice.json — a trace carries the ticket the
-// slice is built under, since it can be reassigned between builds.
-function readTicketNumber(kitDir, ctx, folder) {
-  if (!folder) return null;
+// The slice's ticket and assignee as of the last fetch, from its slice.json — a build carries the ones the slice is
+// built under, since both can change between builds. Either is null when the slice has none.
+function readSliceMeta(kitDir, ctx, folder) {
+  const none = { ticketNumber: null, assignee: null };
+  if (!folder) return none;
   try {
-    return JSON.parse(readFileSync(join(kitDir, '.slices', ctx, folder, 'slice.json'), 'utf-8')).ticketNumber ?? null;
+    const slice = JSON.parse(readFileSync(join(kitDir, '.slices', ctx, folder, 'slice.json'), 'utf-8'));
+    return { ticketNumber: slice.ticketNumber ?? null, assignee: slice.assignee ?? null };
   } catch {
-    return null;
+    return none;
   }
 }
 
 // Returns the first Planned slice, preferring the current context so a context is finished
 // before the next one starts. When the current context has no planned work, the first other
 // context that does becomes the current one (current_context.json is rewritten), so a slice
-// set to Planned in any context is eventually built.
-function getFirstPlannedSlice(kitDir) {
+// set to Planned in any context is eventually built. Ids in `skipIds` are passed over.
+function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
   const slicesDir = join(kitDir, '.slices');
   const currentCtx = readCurrentContext(kitDir);
   let others = [];
@@ -568,78 +540,61 @@ function getFirstPlannedSlice(kitDir) {
     if (!existsSync(indexPath)) continue;
     try {
       const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
-      const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === pickup);
+      const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === 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');
         console.log(`[ralph] No planned slices in context "${currentCtx}" — switching to "${ctx}".`);
       }
-      return { id: planned.id ?? null, title: planned.slice || planned.id || null, ctx, ticketNumber: readTicketNumber(kitDir, ctx, planned.folder) };
+      return { id: planned.id ?? null, title: planned.slice || planned.id || null, ctx, ...readSliceMeta(kitDir, ctx, planned.folder) };
     } catch {}
   }
   return null;
 }
 
-// If the exact same Planned slice (by id) comes back up this many times in a
-// row without its status ever leaving "Planned", onPlannedSlice is stuck on
+// 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 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);
+      } catch {}
+    }
+  } catch {}
+  return ids;
+}
+
+// If the exact same Planned slice (by id) has been built this many times without its status ever leaving "Planned", onPlannedSlice is stuck on
 // it — declining to build it, or building it but its own status change keeps
 // getting reverted (e.g. a failed check). Rather than retry it forever (or
 // crash the whole loop, which would take down every other slice with it),
 // mark it Blocked with a note explaining why and move on to other work.
 // Critical for unsupervised/CI runs, which have no human watching to notice
 // a stall. Configurable for teams that want more slack.
-const MAX_PLANNED_ATTEMPTS = Number(process.env.RALPH_MAX_PLANNED_ATTEMPTS) || 2;
+const MAX_PLANNED_ATTEMPTS = Number(process.env.RALPH_MAX_PLANNED_ATTEMPTS) || 5;
+
+// After this many builds that left a slice Planned, the loop builds any other Planned slice first
+// and comes back to the stuck one only when nothing else is waiting (until MAX_PLANNED_ATTEMPTS).
+const SWITCH_AFTER_ATTEMPTS = Math.min(2, MAX_PLANNED_ATTEMPTS);
 
 // Marks a stuck slice Blocked (locally, and on the board if credentialed) and
 // records why, so the loop can move on instead of looping or exiting.
 // `lastReply` is the build agent's final message on the last attempt (when the runner reports one),
 // so the note says what actually happened instead of only listing what might have.
-async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts, lastReply) {
+export async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts, lastReply) {
   const now = new Date().toISOString();
   const reason = `Ralph loop picked up this slice ${attempts} times in a row without its status ever leaving ` +
     `"Planned" — the build agent kept declining to build it, or kept building it but its own status change kept ` +
     `getting reverted (e.g. a failed check). Auto-blocked to stop the loop from retrying it forever.` +
     (lastReply ? ` Build agent's last reply: "${String(lastReply).replace(/\s+/g, ' ').trim().slice(0, 500)}"` : '');
 
-  const indexPath = join(kitDir, '.slices', planned.ctx, 'index.json');
-  let folder;
-  try {
-    const indexData = JSON.parse(readFileSync(indexPath, 'utf-8'));
-    const entry = (indexData.slices ?? []).find((s) => s.id === planned.id);
-    if (entry) {
-      entry.status = 'Blocked';
-      entry.blockedReason = reason;
-      entry.blockedAt = now;
-      folder = entry.folder;
-      writeFileSync(indexPath, JSON.stringify(indexData, null, 2), 'utf-8');
-    }
-  } catch (err) {
-    console.error(`[ralph] Failed to write Blocked status to ${indexPath}:`, err.message);
-  }
-
-  if (folder) {
-    const sliceJsonPath = join(kitDir, '.slices', planned.ctx, folder, 'slice.json');
-    try {
-      if (existsSync(sliceJsonPath)) {
-        const sliceData = JSON.parse(readFileSync(sliceJsonPath, 'utf-8'));
-        sliceData.status = 'Blocked';
-        sliceData.blockedReason = reason;
-        sliceData.blockedAt = now;
-        writeFileSync(sliceJsonPath, JSON.stringify(sliceData, null, 2), 'utf-8');
-      }
-    } catch (err) {
-      console.error(`[ralph] Failed to write Blocked status to ${sliceJsonPath}:`, err.message);
-    }
-  }
-
-  try {
-    const progressPath = join(dirname(kitDir), 'progress.txt');
-    const existing = existsSync(progressPath) ? readFileSync(progressPath, 'utf-8') : '';
-    const note = `\n## ${now} — Slice auto-blocked\n\nSlice: ${planned.title} (id=${planned.id}, context=${planned.ctx})\n\n- ${reason}\n---\n`;
-    writeFileSync(progressPath, existing + note, 'utf-8');
-  } catch (err) {
-    console.error('[ralph] Failed to append progress.txt note:', err.message);
-  }
+  // The status lives in the event log; index.json / slice.json show it (and the note) as a projection.
+  recordEvent(kitDir, { type: 'blocked', slice: planned.id, reason, at: now }, eventMeta(cfg));
 
   // Best-effort: also reflect Blocked on the board itself so a synced fetch
   // doesn't just pull "Planned" back down over our local fix. Never fatal —
@@ -664,6 +619,23 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts, las
     }
   }
 
+  // Always leave a comment on the slice saying why it was blocked — a Blocked slice with no
+  // explanation is a dead end for whoever finds it. Its own try block, so a failed status sync
+  // above can't skip it; without credentials there is no board to comment on, so say so loudly.
+  if (credentialed) {
+    try {
+      await fetchJSON(`${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/nodes/${planned.id}/comments`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-user-id': 'ralph-loop', ...agentHeaders(cfg) },
+        body: JSON.stringify({ text: `Slice "${planned.title}" was auto-blocked by the Ralph loop. ${reason}`, type: 'COMMENT', author: 'ralph-loop' }),
+      });
+    } catch (err) {
+      console.error(`[ralph] Failed to post the auto-block comment on "${planned.title}" — the reason is only on its blocked event:`, err.message);
+    }
+  } else {
+    console.error(`[ralph] No board credentials — could not comment on "${planned.title}"; the reason is only on its blocked event.`);
+  }
+
   console.error(`[ralph] ${reason} Marked "${planned.title}" (id=${planned.id}) as Blocked — moving on.`);
 }
 
@@ -700,66 +672,172 @@ export function resolveHandover(cfg) {
   return process.env.RALPH_HANDOVER === '1' || cfg?.handover === true;
 }
 
-function taskRequest(planned = null, cfg = null, pickupStatus = 'Planned') {
+// The board as the slice-state shell sees it. Slice status on the board is the loop's job, not the build
+// agent's: the loop claims a slice (InProgress) before the build and pushes the outcome afterwards.
+// Transient failures (network, 429, 5xx) are retried until they go through; a 4xx is a real rejection
+// (e.g. the move-into-same-status guard that lets two agents race for one slice) and surfaces.
+export function createBoard(cfg) {
+  const base = `${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}`;
+  return {
+    async setStatus(sliceId, status) {
+      let attempts = 0;
+      await retryTransient(`set "${status}" on slice ${sliceId}`, async () => {
+        attempts++;
+        try {
+          await fetchJSON(`${base}/nodes/events`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-user-id': 'ralph-loop', ...agentHeaders(cfg) },
+            body: JSON.stringify([{
+              id: randomUUID(),
+              eventType: 'node:changed',
+              nodeId: sliceId,
+              boardId: cfg.boardId,
+              timestamp: Date.now(),
+              changedAttributes: ['sliceStatus'],
+              meta: { type: 'SLICE_BORDER', sliceStatus: status },
+            }]),
+          });
+        } catch (err) {
+          // An earlier attempt may have landed with its response lost; the same-status guard then
+          // rejects the retry. A genuine lost race is rejected on the first attempt, so only a 4xx
+          // on a retry is forgiven.
+          if (attempts > 1 && err instanceof HttpError && err.status >= 400 && err.status < 500) return;
+          throw err;
+        }
+      });
+    },
+    async readStatus(sliceId) {
+      const { slices } = await retryTransient(`read slices of board ${cfg.boardId}`, () => fetchJSON(`${base}/slicedata/slices`, {
+        headers: { 'x-token': cfg.token, ...agentHeaders(cfg) },
+      }));
+      return slices.find((sl) => sl.id === sliceId)?.status ?? null;
+    },
+  };
+}
+
+function taskRequest(planned = null, cfg = null, pickupStatus = 'Planned', queued = null) {
   const task = planned
     ? `build the ${pickupStatus} slice "${planned.title}" (id=${planned.id}, context="${planned.ctx}")`
-    : 'process the pending tasks in tasks.json';
+    : `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` : '';
   return `\n\n---\n\nYour task now: ${task}, following the instructions above. Start immediately.\n${handover}`;
 }
 
-async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false) {
+// The slice-state event store (events/, events.log) holds pids and claims of this checkout and must never be
+// versioned. AGENTS.md is rendered from the learning events and adopts what a merge brings in, so where it
+// is tracked, two branches that both regenerated it should keep both sides' lines rather than conflict:
+// `merge=union`. The rules go in .git/info/exclude and .git/info/attributes: local to this clone, never
+// tracked, so the loop does not dirty the working tree it is about to judge (a dirty tree at claim time is
+// taken for a person's own work and is never discarded). Idempotent; best effort.
+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/attributes', [`${basename(kitDir)}/AGENTS.md merge=union`]],
+  ];
+  for (const [name, lines] of rules) {
+    try {
+      // `--git-path` also resolves for a worktree, where .git is a file.
+      const path = join(projectDir, execFileSync('git', ['rev-parse', '--git-path', name], { cwd: projectDir, encoding: 'utf-8' }).trim());
+      mkdirSync(dirname(path), { recursive: true });
+      const current = existsSync(path) ? readFileSync(path, 'utf-8') : '';
+      const have = new Set(current.split('\n').map((l) => l.trim()));
+      const missing = lines.filter((l) => !have.has(l));
+      if (!missing.length) continue;
+      writeFileSync(path, `${current}${current && !current.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`, 'utf-8');
+      console.log(`[ralph] Added to .git/${name}: ${missing.join(', ')}`);
+    } catch (err) {
+      console.error(`[ralph] Could not update .git/${name}:`, err.message);
+    }
+  }
+}
+
+async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false, onCurate = null) {
   const promptFile = join(kitDir, 'lib', 'prompt.md');
   const backendPromptFile = join(kitDir, 'lib', 'backend-prompt.md');
   // --local must mean zero board contact even when .eventmodelers/config.json
   // happens to hold valid credentials — never let a locally-present token flip
   // this back on.
   const credentialed = !localOnly && hasCredentials(cfg);
+  const board = credentialed ? createBoard(cfg) : null;
+  const meta = eventMeta(cfg);
+  ensureLearningsGitRules(kitDir);
   let lastIdleCtx;
-  // Tracks consecutive sightings of the same Planned slice id — see
-  // MAX_PLANNED_ATTEMPTS above.
-  let stuckSlice = { id: null, count: 0 };
   // The build agent's final reply on the most recent planned-slice turn — quoted in the Blocked note.
   let lastReply = null;
 
   while (true) {
     let didWork = false;
 
-    if (credentialed && hasPendingTasks(kitDir)) {
-      const prompt = readFileSync(promptFile, 'utf-8') + taskRequest();
-      for (const t of readTasks(join(kitDir, 'tasks.json'))) await fetchFullSlice(cfg, kitDir, t.payload?.sliceId);
-      await runWithRetry('onTask: loading slice from board...', () => inTurn(kitDir, () => onTask(prompt)));
+    // A claim still open here is a leftover: its process died mid-build, or settling failed last time.
+    await settleLeftoverClaims({ kitDir, board, meta, pickupStatus: readPickupStatus(kitDir) });
+
+    // AGENTS.md is the projection of the learning events; anything added to it by hand (or by a pull) is adopted first.
+    syncLearnings({ kitDir, meta });
+    // Enough new learnings, and no build in progress: one agent turn tidies them (merge / retract only).
+    if (await curateIfDue({ kitDir, meta, onCurate })) didWork = true;
+
+    // The oldest queued slice change, one turn at a time. The task is completed once the turn finished; one that
+    // timed out stays queued and is handed out again.
+    const workedTask = credentialed && await workNextTask({
+      kitDir,
+      meta,
+      run: async (task) => {
+        await fetchFullSlice(cfg, kitDir, task.payload?.sliceId);
+        const prompt = readFileSync(promptFile, 'utf-8') + taskRequest(null, null, 'Planned', task);
+        return runWithRetry('onTask: loading slice from board...', () => onTask(prompt));
+      },
+    });
+    if (workedTask) {
       await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
     }
 
-    const planned = onPlannedSlice && getFirstPlannedSlice(kitDir);
+    let planned = null;
+    if (onPlannedSlice) {
+      // Attempts are the failed builds the log holds for a slice (see MAX_PLANNED_ATTEMPTS above); they
+      // survive a restart and reset once the slice moves off the status it was put back to.
+      const attemptsBySlice = fold(readEvents(kitDir)).slices;
+      const stuckIds = new Set([...listPlannedIds(kitDir)].filter((id) => (attemptsBySlice[id]?.attempts ?? 0) >= SWITCH_AFTER_ATTEMPTS));
+      // Prefer a slice that hasn't been tried to the switch point; fall back to a stuck one.
+      planned = getFirstPlannedSlice(kitDir, stuckIds) ?? (stuckIds.size ? getFirstPlannedSlice(kitDir) : null);
+    }
     if (planned) {
-      stuckSlice = planned.id !== null && planned.id === stuckSlice.id
-        ? { id: stuckSlice.id, count: stuckSlice.count + 1 }
-        : { id: planned.id, count: 1 };
-
-      if (stuckSlice.count > MAX_PLANNED_ATTEMPTS) {
-        await blockStuckSlice(kitDir, cfg, credentialed, planned, stuckSlice.count, lastReply);
-        stuckSlice = { id: null, count: 0 };
+      const attempts = fold(readEvents(kitDir)).slices[planned.id]?.attempts ?? 0;
+      if (planned.id !== null && attempts >= MAX_PLANNED_ATTEMPTS) {
+        await blockStuckSlice(kitDir, cfg, credentialed, planned, attempts, lastReply);
         didWork = true;
         continue;
       }
 
       const prompt = readFileSync(backendPromptFile, 'utf-8') + taskRequest(planned, cfg, readPickupStatus(kitDir));
       if (credentialed) await fetchFullSlice(cfg, kitDir, planned.id);
+      if (planned.id) {
+        const claimed = await claimSlice({ kitDir, planned, board, meta, cleanTree: isTreeClean(kitDir), pickupStatus: readPickupStatus(kitDir) });
+        if (claimed !== 'won') {
+          console.log(claimed === 'held'
+            ? `[ralph] Another run loop holds "${planned.title}" in this kit — waiting.`
+            : `[ralph] Could not claim "${planned.title}" — skipping it this iteration.`);
+          didWork = true;
+          await sleep(5_000);
+          continue;
+        }
+      }
       lastReply = null;
       const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, async () => { lastReply = await onPlannedSlice(prompt, {
         sliceId: planned.id,
         sliceTitle: planned.title,
         context: planned.ctx,
         ticketNumber: planned.ticketNumber,
+        assignee: planned.assignee,
         boardId: cfg.boardId ?? null,
-        attempt: stuckSlice.count,
+        attempt: attempts + 1,
       }); });
       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 (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
     }
@@ -780,7 +858,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
 
 // ── Public API ────────────────────────────────────────────────────────────────
 
-export { HttpError, loadLocalConfig, fetchPlatformConfig, retryTransient, startRealtimeAgent, writeTask, inTurn, hasPendingTasks };
+export { HttpError, loadLocalConfig, fetchPlatformConfig, retryTransient, startRealtimeAgent, ensureLearningsGitRules };
 
 // The connect line a runner puts in front of every prompt. --local must mean zero board
 // contact, so it is empty then — handed live credentials, the agent would treat itself as
@@ -803,13 +881,22 @@ export function connectHeader(cfg, localOnly) {
 // plain run. Exported so a runner can resolve it at load time, before startRalph runs — the env
 // it hands its `claude` is built then. Idempotent: ensureAgentId returns the id it persisted.
 export function resolveAgentIdentity(kitDir, agentType = 'BUILD', cfg = loadLocalConfig(kitDir)) {
-  const agentId = process.env.RALPH_AGENT_ID || ensureAgentId(kitDir, agentType);
-  const agentName = process.env.RALPH_AGENT_NAME || cfg.agentName || '';
+  // --id is the operator's choice: used as given, no lock. Otherwise the project's stable id — unless another live
+  // process is already running under it, in which case this one gets a fresh id (see agent-lock.js).
+  const pinned = process.env.RALPH_AGENT_ID;
+  const { agentId, fellBack } = pinned
+    ? { agentId: pinned, fellBack: false }
+    : acquireAgentId({ lockDir: join(dirname(kitDir), '.eventmodelers', 'locks'), stableId: ensureAgentId(kitDir, agentType) });
+  // --name, else the configured agentName, else the repository's name — never the bare uuid on the board. A name
+  // nobody gave is marked with the instance when the id fell back, so the board does not show two of the same.
+  const given = process.env.RALPH_AGENT_NAME || cfg.agentName;
+  const fallback = defaultAgentName(dirname(kitDir), agentType);
+  const agentName = given || (fellBack ? withInstanceSuffix(fallback, agentId) : fallback);
   process.env.EVENTMODELERS_AGENT_ID = agentId;
   return { agentId, agentName, agentType };
 }
 
-export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, agentType = 'BUILD', queueAllStatuses = false, localOnly = false }) {
+export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, onCurate = null, agentType = 'BUILD', localOnly = false }) {
   const local = loadLocalConfig(kitDir);
   redactConsole([local.token]);
   Object.assign(local, resolveAgentIdentity(kitDir, agentType, local));
@@ -824,7 +911,7 @@ export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, a
   // reaches out to the platform at all.
   if (localOnly || !hasCredentials(local)) {
     console.log(`         mode: local-only (no platform sync)${localOnly ? ' — forced by --local' : ''}\n`);
-    await ralphLoop(kitDir, local, onTask, onPlannedSlice, localOnly);
+    await ralphLoop(kitDir, local, onTask, onPlannedSlice, localOnly, onCurate);
     return;
   }
 
@@ -832,7 +919,7 @@ export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, a
   console.log(`         org=${cfg.organizationId}, board=${cfg.boardId}, base=${cfg.baseUrl}\n`);
 
   await Promise.all([
-    startRealtimeAgent(cfg, kitDir, { agentType, queueAllStatuses }),
-    ralphLoop(kitDir, cfg, onTask, onPlannedSlice),
+    startRealtimeAgent(cfg, kitDir, { agentType }),
+    ralphLoop(kitDir, cfg, onTask, onPlannedSlice, false, onCurate),
   ]);
 }