@eventmodelers/cli 1.0.90 → 1.0.92

package/shared/build-kit/lib/adapters/pocketbase-realtime-adapter.js

@@ -16,18 +16,26 @@ const REALTIME_EVENTS_COLLECTION = 'realtime_events';
 // ourselves.
 const RECONNECT_INTERVALS_MS = [200, 300, 500, 1000, 1200, 1500, 2000];
 
-export async function createPocketBaseRealtimeAdapter(cfg, initialToken) {
+// deps.PocketBase is injectable for tests; by default it is the pocketbase SDK's client.
+export async function createPocketBaseRealtimeAdapter(cfg, initialToken, deps = {}) {
   const { EventSource } = await import('eventsource');
   if (!globalThis.EventSource) globalThis.EventSource = EventSource; // PocketBase's SDK assumes a browser-style global
-  const { default: PocketBase } = await import('pocketbase');
+  const PocketBase = deps.PocketBase ?? (await import('pocketbase')).default;
   const pb = new PocketBase(cfg.pocketbaseUrl);
   pb.authStore.save(initialToken, null);
 
+  // subscribe() replaces the previous listener (see realtime-adapter.js).
+  let unsubscribe = null;
+
   return {
     async subscribe(topic, handlers, onStatus) {
+      if (unsubscribe) {
+        await unsubscribe().catch(() => {});
+        unsubscribe = null;
+      }
       for (let attempt = 0; ; attempt++) {
         try {
-          await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
+          unsubscribe = await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
             if (e.action !== 'create' || e.record.topic !== topic) return;
             handlers[e.record.event]?.(e.record.payload);
           });

package/shared/build-kit/lib/adapters/realtime-adapter.js

@@ -3,7 +3,9 @@
 // record-change events for self-hosted/on-prem) and hands back one common interface:
 //
 //   subscribe(topic, handlers, onStatus?) — handlers is a { [eventName]: (payload) => void }
-//     map; onStatus?.(status) fires once the subscription is live ('SUBSCRIBED').
+//     map; onStatus?.(status) fires once the subscription is live ('SUBSCRIBED'). Calling it
+//     again replaces the previous subscription — never adds to it — and a replaced one no
+//     longer reports status.
 //   setAuth(token) — refresh the short-lived realtime token on the live connection.
 //
 // cfg.realtimeProvider absent (older servers, predating PocketBase support) means

package/shared/build-kit/lib/adapters/supabase-realtime-adapter.js

@@ -2,20 +2,31 @@
 // broadcast channel and dispatches named broadcast events to caller-supplied handlers.
 // See realtime-adapter.js for the interface both this and the PocketBase adapter implement.
 
-export async function createSupabaseRealtimeAdapter(cfg, initialToken) {
-  const { createClient } = await import('@supabase/supabase-js');
+// deps.createClient is injectable for tests; by default it is supabase-js's own.
+export async function createSupabaseRealtimeAdapter(cfg, initialToken, deps = {}) {
+  const createClient = deps.createClient ?? (await import('@supabase/supabase-js')).createClient;
   const supabase = createClient(cfg.supabaseUrl, cfg.supabaseAnonKey, {
     realtime: { params: { apikey: cfg.supabaseAnonKey } },
   });
   await supabase.realtime.setAuth(initialToken);
 
+  // supabase.channel(topic) hands back the existing channel for a topic it already knows, so
+  // re-subscribing on it would stack another set of handlers — the old channel is removed first.
+  let current = null;
+
   return {
     async subscribe(topic, handlers, onStatus) {
+      // Detach before removing: the removal itself makes the old channel report CLOSED, and a
+      // late status from a replaced channel must not count as this subscription's.
+      const previous = current;
+      current = null;
+      if (previous) await supabase.removeChannel(previous).catch(() => {});
       let channel = supabase.channel(topic, { config: { private: true } });
       for (const [event, handler] of Object.entries(handlers)) {
         channel = channel.on('broadcast', { event }, (msg) => handler(msg.payload));
       }
-      channel.subscribe((status) => onStatus?.(status));
+      current = channel;
+      channel.subscribe((status) => { if (channel === current) onStatus?.(status); });
     },
     setAuth(token) {
       return supabase.realtime.setAuth(token);

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

@@ -6,12 +6,16 @@
 //   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.
 
-import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, renameSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
 import { createRealtimeAdapter } from './adapters/realtime-adapter.js';
 import { backoffMs, sleep } from './backoff.js';
+import { redactConsole } from './redact.js';
+
+// Backoff for calls to the platform that failed for a reason on its side (startup, the channel).
+const PLATFORM_BACKOFF = { baseMs: 2_000, capMs: 5 * 60_000 };
 
 // ── HTTP helpers ──────────────────────────────────────────────────────────────
 
@@ -22,25 +26,42 @@ class HttpError extends Error {
   }
 }
 
+// Every fetchJSON call authenticates with the platform API token (x-token), and a 401 for it
+// always means that token is missing, invalid or revoked (see requireApiToken on the
+// platform) — no retry or wait can fix that, so the first one ends the process with a message
+// saying what to fix. (The alive-ping, on the short-lived realtime token, doesn't come
+// through here: a 401 there just means that token needs refreshing.)
 async function fetchJSON(url, options) {
   const res = await fetch(url, options);
+  if (res.status === 401) {
+    console.error(`[agent] 401 from ${new URL(url).pathname} — the token was rejected: ${await res.text()}`);
+    console.error('[agent] Check the token in .eventmodelers/config.json (or EVENTMODELERS_TOKEN) — shutting down');
+    process.exit(1);
+  }
   if (!res.ok) throw new HttpError(res.status, await res.text());
   return res.json();
 }
 
-// A 401 from the platform always means the token itself is missing, invalid or revoked (see
-// requireApiToken on the platform) — retrying the same token can't fix that, and neither can
-// waiting, so the first one ends the process with a message saying what to fix.
-async function exitOn401(label, fn) {
-  try {
-    return await fn();
-  } catch (err) {
-    if (err instanceof HttpError && err.status === 401) {
-      console.error(`[agent] ${label} — 401, the token was rejected: ${err.message}`);
-      console.error('[agent] Check the token in .eventmodelers/config.json (or EVENTMODELERS_TOKEN) — shutting down');
-      process.exit(1);
+// Startup can't wait for a person to notice a platform blip: a 429, a 5xx or a request that
+// never got an answer is retried with backoff until it goes through. Any other 4xx is a real
+// answer and goes straight back (a 401 has already ended the process in fetchJSON).
+function isTransient(err) {
+  if (err instanceof HttpError) return err.status === 429 || err.status >= 500;
+  // fetch() rejects with a TypeError when there's no response at all (DNS, refused, reset),
+  // and with a TimeoutError/AbortError from an AbortSignal.timeout.
+  return err instanceof TypeError || err?.name === 'TimeoutError' || err?.name === 'AbortError';
+}
+
+async function retryTransient(label, fn, { sleepFn = sleep } = {}) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (!isTransient(err)) throw err;
+      const delay = backoffMs(attempt, PLATFORM_BACKOFF);
+      console.warn(`[agent] ${label} failed (attempt ${attempt}: ${err.message}) — retrying in ${Math.round(delay / 1000)}s`);
+      await sleepFn(delay);
     }
-    throw err;
   }
 }
 
@@ -259,30 +280,79 @@ async function fetchAndPersistSlices(cfg, kitDir) {
   console.log(`[agent] Persisted ${slices.length} slice(s)`);
 }
 
-async function writeTask(payload, kitDir) {
+// 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 existing = existsSync(tasksPath) ? JSON.parse(readFileSync(tasksPath, 'utf-8')) : [];
-  const filtered = existing.filter(t => t.payload?.sliceId !== payload.sliceId);
-  const task = { id: randomUUID(), createdAt: new Date().toISOString(), payload };
-  filtered.push(task);
-  writeFileSync(tasksPath, JSON.stringify(filtered, null, 2), 'utf-8');
+  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) {
   console.log(`[agent] slice:changed — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
-  await exitOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
-    console.error('[agent] Slice persist error:', err),
-  );
   // 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
-  // skips it. Attribution decides, never a guess: only an agentId equal to ours is dropped —
-  // a person's edit or another agent's (different id), or an event with no attribution at all,
-  // is still queued, so a missing field degrades to the old behaviour rather than losing work.
+  // skips it, and re-reading the slices for them is wasted too: ralphLoop re-reads them right
+  // after every turn anyway. Attribution decides, never a guess: only an agentId equal to ours
+  // is dropped — a person's edit or another agent's, or an event with no attribution at all,
+  // is still handled, so a missing field degrades to queuing rather than losing work.
   if (payload?.agentId && cfg.agentId && payload.agentId === cfg.agentId) {
     console.log(`[agent] Own write — not queued (slice="${payload.sliceTitle}" status="${payload.sliceStatus}")`);
     return;
   }
+  await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
+    console.error('[agent] Slice persist error:', err),
+  );
   // Planned slices 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
@@ -292,15 +362,17 @@ async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
   }
 }
 
-async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllStatuses = false } = {}) {
-  let realtimeToken = await exitOn401('getRealtimeToken', () => getRealtimeToken(cfg));
+// 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 } = {}) {
+  let realtimeToken = await retryTransient('getRealtimeToken', () => getRealtimeToken(cfg));
 
-  await exitOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
+  await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
     console.error('[agent] Initial slice fetch error:', err),
   );
 
   const channelName = `board:${cfg.boardId}-slicechanged`;
-  const realtime = await createRealtimeAdapter(cfg, realtimeToken);
+  const realtime = await createAdapter(cfg, realtimeToken);
 
   // Shared by the scheduled timer, a CHANNEL_ERROR/TIMED_OUT subscribe status, and a
   // 401 from the alive-ping — whichever notices the token is bad first wins; the rest
@@ -313,7 +385,7 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
       console.log(`[agent] ${ts()} Refreshing realtime token (reason: ${reason})...`);
       refreshing = (async () => {
         try {
-          realtimeToken = await exitOn401('getRealtimeToken (refresh)', () => getRealtimeToken(cfg));
+          realtimeToken = await getRealtimeToken(cfg);
           await realtime.setAuth(realtimeToken);
           console.log(`[agent] ${ts()} Token refreshed (reason: ${reason}, took ${Date.now() - startedAt}ms)`);
         } catch (err) {
@@ -328,34 +400,33 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
   };
 
   // A subscribe that errors on a stale token needs a fresh token AND a new join
-  // attempt — setAuth alone doesn't re-join a channel that already errored out.
-  // Retried with exponential backoff (2s → 5min) rather than a fixed delay and a cap:
-  // the cap used to leave the channel dead for good — the scheduled refresh only calls
-  // setAuth, it never re-joins — while the backoff alone keeps a genuinely revoked
-  // access from hammering the platform. A revoked token ends the process anyway, via
-  // exitOn401 inside refreshToken.
+  // attempt — setAuth alone doesn't re-join a channel that already errored out, and nothing
+  // else ever re-joins it, so this retries for as long as it takes, with backoff so a
+  // lasting failure doesn't hammer the platform. (A revoked token ends the process anyway:
+  // refreshToken's fetch gets the 401.)
   let channelErrorStreak = 0;
-  let resubscribeTimer = null;
+  let resubscribePending = false;
   const onChannelFailure = (reason) => {
     // One failure can be reported more than once (a channel erroring while its retry is
     // already scheduled); a second resubscribe on top would join the channel twice.
-    if (resubscribeTimer) return;
+    if (resubscribePending) return;
+    resubscribePending = true;
     channelErrorStreak += 1;
-    const delay = backoffMs(channelErrorStreak, { baseMs: 2_000, capMs: 5 * 60_000 });
+    const delay = backoffMs(channelErrorStreak, PLATFORM_BACKOFF);
     console.warn(`[agent] ${ts()} Channel "${channelName}": ${reason} (attempt ${channelErrorStreak}) — resubscribing in ${Math.round(delay / 1000)}s`);
-    resubscribeTimer = setTimeout(async () => {
+    setTimeout(async () => {
       try {
         await refreshToken(`channel ${reason}`);
       } catch {
         // Logged by refreshToken. Rejoining on the old token is still worth a try —
         // if it fails too, that's just the next failure, with a longer delay.
       }
-      resubscribeTimer = null;
+      resubscribePending = false;
       subscribeChannel();
     }, delay);
   };
   const subscribeChannel = () => {
-    Promise.resolve(realtime.subscribe(
+    realtime.subscribe(
       channelName,
       {
         // A kill names exactly one agent: {type: 'kill', id: '<agentId>', instruction: 'exit'}.
@@ -381,11 +452,11 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
         // Broadcasts sent while the channel was down are gone. Re-read the slices once so a
         // slice set to Planned during the gap still gets built — .slices/ is what ralphLoop
         // picks Planned work from.
-        exitOn401('fetchAndPersistSlices (after reconnect)', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
+        fetchAndPersistSlices(cfg, kitDir).catch((err) =>
           console.error(`[agent] ${ts()} Slice re-fetch after reconnect failed:`, err),
         );
       },
-    )).catch((err) => onChannelFailure(`subscribe failed: ${err.message}`));
+    ).catch((err) => onChannelFailure(`subscribe failed: ${err.message}`));
   };
   subscribeChannel();
 
@@ -424,14 +495,7 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
 // ── Ralph loop ────────────────────────────────────────────────────────────────
 
 function hasPendingTasks(kitDir) {
-  const tasksPath = join(kitDir, 'tasks.json');
-  if (!existsSync(tasksPath)) return false;
-  try {
-    const tasks = JSON.parse(readFileSync(tasksPath, 'utf-8'));
-    return Array.isArray(tasks) && tasks.length > 0;
-  } catch {
-    return false;
-  }
+  return readTasks(join(kitDir, 'tasks.json')).length > 0;
 }
 
 function readCurrentContext(kitDir) {
@@ -554,9 +618,8 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
 // Returns true once fn succeeds; false for a turn that timed out (see lib/turn.js). A timeout
 // is not retried in place: re-running the same hung turn every 60s would spin forever without
 // the stuck-slice guard ever seeing it, so it goes back to ralphLoop, which recounts the slice.
-// Any other failure is retried in place with exponential backoff (30s → 10min): a harness
-// that fails fast (API outage, rate limit, broken install) used to be relaunched every 60s
-// for as long as it stayed broken.
+// Any other failure is retried in place, with backoff (30s → 10min) so a harness that keeps
+// failing fast (API outage, rate limit, broken install) isn't relaunched in a tight loop.
 async function runWithRetry(label, fn) {
   for (let attempt = 1; ; attempt++) {
     try {
@@ -592,7 +655,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
 
     if (credentialed && hasPendingTasks(kitDir)) {
       const prompt = readFileSync(promptFile, 'utf-8');
-      await runWithRetry('onTask: loading slice from board...', () => onTask(prompt));
+      await runWithRetry('onTask: loading slice from board...', () => inTurn(kitDir, () => onTask(prompt)));
       await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
     }
@@ -631,7 +694,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
         console.log(`[ralph] No planned slices in current context "${ctx}" — waiting. Switch context on the board to continue.`);
         lastIdleCtx = ctx;
       }
-      await new Promise((r) => setTimeout(r, 10_000));
+      await sleep(10_000);
     } else {
       lastIdleCtx = undefined;
     }
@@ -640,7 +703,20 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
 
 // ── Public API ────────────────────────────────────────────────────────────────
 
-export { loadLocalConfig, fetchPlatformConfig, exitOn401, startRealtimeAgent };
+export { HttpError, loadLocalConfig, fetchPlatformConfig, retryTransient, startRealtimeAgent, writeTask, inTurn, hasPendingTasks };
+
+// 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
+// already connected and go straight to board sync. The token is named, never included: the
+// prompt reaches the harness on its command line (visible to every local user in `ps`) and
+// lands in session transcripts, so it carries $EVENTMODELERS_TOKEN — the runner puts the value
+// in the child's env, connect treats the reference as the inline token, and a curl header
+// written as "x-token: $EVENTMODELERS_TOKEN" expands in the shell.
+export function connectHeader(cfg, localOnly) {
+  return !localOnly && cfg.boardId
+    ? `board=${cfg.boardId} token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
+    : '';
+}
 
 // Who this process is. RALPH_AGENT_ID/RALPH_AGENT_NAME are `eventmodelers run --id/--name`,
 // passed down as env (see cli.js's run dispatcher): a per-run identity override so a second
@@ -658,6 +734,7 @@ export function resolveAgentIdentity(kitDir, agentType = 'BUILD', cfg = loadLoca
 
 export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, agentType = 'BUILD', queueAllStatuses = false, localOnly = false }) {
   const local = loadLocalConfig(kitDir);
+  redactConsole([local.token]);
   Object.assign(local, resolveAgentIdentity(kitDir, agentType, local));
 
   console.log(`Ralph — kit: ${kitDir}`);
@@ -674,7 +751,7 @@ export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, a
     return;
   }
 
-  const cfg = await exitOn401('fetchPlatformConfig', () => fetchPlatformConfig(local));
+  const cfg = await retryTransient('fetchPlatformConfig', () => fetchPlatformConfig(local));
   console.log(`         org=${cfg.organizationId}, board=${cfg.boardId}, base=${cfg.baseUrl}\n`);
 
   await Promise.all([

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

@@ -0,0 +1,36 @@
+// Keeps secrets out of the loop's own log lines. Anything this process prints can end up in a
+// terminal scrollback, a CI log or a `docker logs` dump: an error body that echoes a header,
+// a verbose tool input with a curl command in it, a debug line with a config object. So
+// rather than trusting every call site, console output is masked on the way out:
+//   - the platform API token, by value (it's a plain uuid, so there's no pattern for it)
+//   - anything JWT-shaped (eyJ….….…) — the realtime token and Supabase keys look like that
+//
+// Output a child process writes straight to the terminal (stdio: 'inherit') never passes
+// through console here, so it isn't covered.
+
+import { format } from 'util';
+
+const JWT = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+
+// A secret shorter than this would mask ordinary text (an empty or placeholder value most of all).
+const MIN_SECRET_LENGTH = 8;
+
+export function redactString(text, secrets = []) {
+  let out = String(text).replace(JWT, '***');
+  for (const secret of secrets) {
+    if (typeof secret === 'string' && secret.length >= MIN_SECRET_LENGTH) out = out.replaceAll(secret, '***');
+  }
+  return out;
+}
+
+// Routes console.log/info/warn/error/debug through redactString. Arguments are formatted the
+// way console would format them first, so an Error or an object is masked too. Returns a
+// function that puts the originals back.
+export function redactConsole(secrets) {
+  const methods = ['log', 'info', 'warn', 'error', 'debug'];
+  const originals = Object.fromEntries(methods.map((m) => [m, console[m]]));
+  for (const m of methods) {
+    console[m] = (...args) => originals[m].call(console, redactString(format(...args), secrets));
+  }
+  return () => { for (const m of methods) console[m] = originals[m]; };
+}

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

@@ -5,7 +5,8 @@
 // RALPH_TURN_TIMEOUT_MIN (env) or turnTimeoutMinutes (.eventmodelers/config.json);
 // default 60, 0 turns the cap off.
 
-import { execFile } from 'child_process';
+import { execFileSync } from 'child_process';
+import { constants as osConstants } from 'os';
 
 const KILL_GRACE_MS = 10_000;
 
@@ -15,43 +16,78 @@ export function turnTimeoutMs(cfg) {
   return Number.isFinite(minutes) && minutes > 0 ? minutes * 60_000 : 0;
 }
 
-// Thrown (rejected) by a runner whose turn hit the cap. ralph.js's runWithRetry lets it
-// through to the outer loop instead of re-running the same turn in place, so a slice
-// that times out again is counted — and eventually Blocked — by the stuck-slice guard.
-export class TurnTimeoutError extends Error {
+// What a timed-out turn rejects with. ralph.js's runWithRetry lets it (`timedOut`) through
+// to the outer loop instead of re-running the same turn in place, so a slice that times out
+// again is counted — and eventually Blocked — by the stuck-slice guard.
+class TurnTimeoutError extends Error {
   constructor(label, timeoutMs) {
     super(`${label} timed out after ${Math.round(timeoutMs / 60_000)}min`);
     this.timedOut = true;
   }
 }
 
-// SIGTERM, then SIGKILL after a grace period. `shell: true` means proc is only the /bin/sh
-// wrapping the real command, so its children are signalled first — killing just the shell
-// would orphan the harness and leave it running. (A separate process group would be
-// cleaner, but a background group reading the terminal gets stopped by SIGTTIN, and
-// Ctrl-C would no longer reach it.)
-// The shell is only signalled once pkill has returned: killed any earlier, its children are
-// re-parented to init before pkill -P gets to look for them, and survive.
+// `shell: true` means proc is only the /bin/sh wrapping the real command, so its children are
+// signalled first — killing just the shell would orphan the harness and leave it running. (A
+// separate process group would be cleaner, but a background group reading the terminal gets
+// stopped by SIGTTIN, and Ctrl-C would no longer reach it.) pkill runs synchronously so the
+// shell is still alive, and its children still its own, when pkill -P looks for them.
 function signal(proc, sig, viaShell) {
-  const killSelf = () => { try { proc.kill(`SIG${sig}`); } catch { /* already gone */ } };
-  if (viaShell && proc.pid) execFile('pkill', [`-${sig}`, '-P', String(proc.pid)], killSelf);
-  else killSelf();
+  if (viaShell && proc.pid) {
+    try { execFileSync('pkill', [`-${sig}`, '-P', String(proc.pid)]); } catch { /* no children left */ }
+  }
+  try { proc.kill(`SIG${sig}`); } catch { /* already gone */ }
+}
+
+// SIGTERM, then SIGKILL once the grace period is up.
+function stop(turn) {
+  signal(turn.proc, 'TERM', turn.viaShell);
+  turn.killTimer = setTimeout(() => signal(turn.proc, 'KILL', turn.viaShell), KILL_GRACE_MS);
 }
 
+// Stopping the loop has to stop its turn too: a SIGTERM from systemd, Docker or `kill` reaches
+// this process alone (only Ctrl-C signals the whole foreground group), and node's default —
+// exit on the spot — left the running agent orphaned, still editing the project. So every
+// live turn is stopped the way a timeout stops it, and the process exits once they're gone.
+// A second signal doesn't wait out the grace period: it SIGKILLs what's left and exits.
+const liveTurns = new Set();
+let exitCode = null; // set once a shutdown signal has arrived
+
+function exitOnSignal(sig) {
+  const code = 128 + osConstants.signals[sig];
+  if (liveTurns.size === 0) process.exit(code);
+  if (exitCode !== null) {
+    for (const t of liveTurns) signal(t.proc, 'KILL', t.viaShell);
+    process.exit(code);
+  }
+  exitCode = code;
+  for (const t of liveTurns) {
+    t.log(`Received ${sig} — stopping ${t.label} before exiting (send it again to exit now)`);
+    stop(t);
+  }
+  // Backstop: a child whose close never fires mustn't keep the process up forever.
+  setTimeout(() => process.exit(code), KILL_GRACE_MS + 2_000);
+}
+
+for (const sig of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(sig, () => exitOnSignal(sig));
+
+// Returns timeoutError(): the error to reject with once the turn has closed, or null when it
+// didn't hit the cap.
 export function superviseTurn(proc, { timeoutMs, label, log, viaShell = false }) {
+  const turn = { proc, label, log, viaShell, killTimer: null };
   let timedOut = false;
-  let killTimer;
   const timer = timeoutMs
     ? setTimeout(() => {
         timedOut = true;
         log(`${label} exceeded ${Math.round(timeoutMs / 60_000)}min — stopping it`);
-        signal(proc, 'TERM', viaShell);
-        killTimer = setTimeout(() => signal(proc, 'KILL', viaShell), KILL_GRACE_MS);
+        stop(turn);
       }, timeoutMs)
     : null;
+  liveTurns.add(turn);
   proc.on('close', () => {
     clearTimeout(timer);
-    clearTimeout(killTimer);
+    clearTimeout(turn.killTimer);
+    liveTurns.delete(turn);
+    if (exitCode !== null && liveTurns.size === 0) process.exit(exitCode);
   });
-  return { timedOut: () => timedOut };
+  return { timeoutError: () => (timedOut ? new TurnTimeoutError(label, timeoutMs) : null) };
 }

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

@@ -2,9 +2,9 @@
 // Ralph loop + realtime agent using Claude Code as the executor.
 // Usage: node ralph-claude.js [project_dir]
 
-import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
+import { startRalph, loadLocalConfig, resolveAgentIdentity, connectHeader } from './lib/ralph.js';
 import { createSliceTracer, usageFromClaudeResult } from './lib/tracing.js';
-import { turnTimeoutMs, superviseTurn, TurnTimeoutError } from './lib/turn.js';
+import { turnTimeoutMs, superviseTurn } from './lib/turn.js';
 import { spawn } from 'child_process';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -31,21 +31,8 @@ const tracer = createSliceTracer({
   log: (line) => console.log(`[ralph] ${line}`),
   enabled: tracingOn,
 });
-// --local must mean zero board contact — never hand Claude live board
-// credentials via the inline header, even if config.json has them, or it'll
-// treat them as already-connected and skip straight to board sync.
-// The token itself stays out of the prompt: `-p` is argv, visible to every local
-// user in `ps`, and the prompt lands in session transcripts. The header names the
-// env var instead (set in claudeEnv below) — connect treats it as the inline token,
-// and a curl header written as "x-token: $EVENTMODELERS_TOKEN" expands in the shell.
-const inlineHeader = !localOnly && cfg.boardId
-  ? `board=${cfg.boardId} token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
-  : '';
+const inlineHeader = connectHeader(cfg, localOnly);
 const timeoutMs = turnTimeoutMs(cfg);
-// The model can still surface the token (e.g. a Bash command it expanded by hand), and
-// --verbose logs tool input and assistant text as is — mask it before it hits the log.
-const redact = (s) => (cfg.token ? String(s).split(cfg.token).join('***') : s);
-
 // --verbose here (set via `eventmodelers run --verbose`, passed down as RALPH_VERBOSE)
 // logs full tool input and assistant reasoning text; the default (condensed) mode logs
 // only the high-level step — a skill name, or a bare tool name — mirroring `run --modeling`'s
@@ -109,9 +96,9 @@ function runClaude(prompt, slice = null) {
 
         if (msg.type === 'assistant') {
           for (const block of msg.message?.content ?? []) {
-            if (block.type === 'text' && block.text && verbose) console.log(redact(block.text));
+            if (block.type === 'text' && block.text && verbose) console.log(block.text);
             if (block.type === 'tool_use') {
-              if (verbose) console.log(`→ ${redact(describeToolUse(block))}`);
+              if (verbose) console.log(`→ ${describeToolUse(block)}`);
               else if (block.name === 'Skill') console.log(`→ Skill: ${block.input?.skill ?? ''}`);
               else console.log(`→ ${block.name}`);
             }
@@ -124,7 +111,8 @@ function runClaude(prompt, slice = null) {
     });
 
     proc.on('close', (code) => {
-      if (turn.timedOut()) reject(new TurnTimeoutError('Claude turn', timeoutMs));
+      const timeout = turn.timeoutError();
+      if (timeout) reject(timeout);
       else if (code === 0) resolve();
       else reject(new Error(`Claude exited ${code}`));
     });