@eventmodelers/cli 1.0.163 → 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,14 +509,16 @@ 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;
   }
 }
 
@@ -574,7 +546,7 @@ function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
         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;
@@ -614,52 +586,15 @@ const SWITCH_AFTER_ATTEMPTS = Math.min(2, MAX_PLANNED_ATTEMPTS);
 // 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 —
@@ -695,10 +630,10 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts, las
         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 in progress.txt:`, err.message);
+      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 in progress.txt.`);
+    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.`);
@@ -737,71 +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;
-  // Builds so far per slice id that is still Planned — see MAX_PLANNED_ATTEMPTS above. An id drops
-  // out as soon as its slice leaves Planned, so only builds that failed to move it count.
-  const plannedAttempts = new Map();
   // 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;
     }
 
     let planned = null;
     if (onPlannedSlice) {
-      const stillPlanned = listPlannedIds(kitDir);
-      for (const id of plannedAttempts.keys()) if (!stillPlanned.has(id)) plannedAttempts.delete(id);
-      const stuckIds = new Set([...plannedAttempts].filter(([, n]) => n >= SWITCH_AFTER_ATTEMPTS).map(([id]) => id));
+      // 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) {
-      const attempts = plannedAttempts.get(planned.id) ?? 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);
-        plannedAttempts.delete(planned.id);
         didWork = true;
         continue;
       }
-      if (planned.id !== null) plannedAttempts.set(planned.id, attempts + 1);
 
       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: 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;
     }
@@ -822,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
@@ -845,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));
@@ -866,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;
   }
 
@@ -874,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),
   ]);
 }

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

@@ -0,0 +1,40 @@
+// When the loop spends a turn on the learnings. The curator is an LLM turn that only writes events —
+// `learn --merge` and `learn --retract` — and the loop marks the review done afterwards (`learnings-curated`),
+// whatever came of the turn: a curator that failed or timed out does not make the loop retry in a tight loop,
+// the next review comes after more learnings have piled up.
+
+import { appendEvent, readEvents } from './slice-events.js';
+import { fold, needsCuration } from './slice-state.js';
+import { curationRequest } from './slice-learnings.js';
+
+const DEFAULT_THRESHOLD = 10;
+
+// Learnings recorded since the last review before a turn is worth it: RALPH_CURATE_AFTER, 0 switches
+// curation off.
+export function curationThreshold(env = process.env) {
+  const raw = env.RALPH_CURATE_AFTER;
+  if (raw === undefined || raw === '') return DEFAULT_THRESHOLD;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 0 ? n : DEFAULT_THRESHOLD;
+}
+
+// Runs a curation turn when enough new learnings are waiting and no slice is being built. `onCurate(prompt,
+// { env })` is the runner's agent turn; `env` must reach the agent's process (EVENTMODELERS_CURATING=1 makes
+// `learn` refuse to record new learnings — the curator tidies, it does not add facts). It is passed along
+// instead of set on process.env because the runners build their child environment once, at load time.
+// Returns whether a turn was run.
+export async function curateIfDue({ kitDir, meta, onCurate, threshold = curationThreshold() }) {
+  if (!onCurate || !threshold) return false;
+  const state = fold(readEvents(kitDir));
+  if (!needsCuration(state, threshold)) return false;
+  if (Object.values(state.slices).some((s) => s.claim)) return false;
+
+  console.log(`[ralph] ${state.learnings.filter((l) => !l.curated).length} new learnings — curating them.`);
+  try {
+    await onCurate(curationRequest(state.learnings), { env: { EVENTMODELERS_CURATING: '1' } });
+  } catch (err) {
+    console.error('[ralph] The curation turn failed — the learnings stay as they are:', err.message);
+  }
+  appendEvent(kitDir, { type: 'learnings-curated' }, meta);
+  return true;
+}