@eventmodelers/cli 1.0.90 → 1.0.91

package/README.md

@@ -635,6 +635,8 @@ npx @eventmodelers/cli re-init --stack supabase      # override which stack to r
 
 `re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/`ralph.sh`/skills without re-scaffolding a project you've since built on top of.
 
+You don't have to remember to: on startup every command prints a 💡 hint (on stderr) when a newer CLI is on npm, or when a kit in the current directory was installed by an older CLI than the one running — naming the exact `re-init` command to run. The npm lookup happens at most once a day (cached in `~/.eventmodelers/update-check.json`, 1.5 s timeout, silent when offline). Set `EVENTMODELERS_NO_UPDATE_CHECK=1` to turn it off; it is also off when `CI` is set.
+
 Pass `--stack <name>` to override the stack instead of relying on the manifest — useful if the manifest is missing/stale, or you want to point a `.build-kit` install at a different built-in stack's templates. It's mutually exclusive with `--modeling`.
 
 Credentials are left alone unless you pass `--force` — same rule `init` already follows when everything required is already configured. `--global` defaults to however skills were originally installed; pass it explicitly to move them.

package/cli.js

@@ -21,6 +21,7 @@ import { randomUUID } from 'crypto';
 import { runFetch, FetchAuthError } from './lib/fetch.js';
 import { createModelingLocalAiRunner } from './lib/modeling-local-ai.js';
 import { run as runSpecKittyAdapter } from './lib/adapters/spec-kitty-adapter.js';
+import { latestPublishedVersion, updateHints } from './lib/update-check.js';
 // Not a root-level adapter like spec-kitty-adapter.js above: this is the one canonical
 // copy that every useShared:true stack also gets copied into its installed kit (see
 // copyDirContents in installStack) for ralph.js to import standalone — see
@@ -1282,6 +1283,11 @@ async function configureCredentials({ config, configPath, targetDir, requiredFie
 async function refreshSharedRuntime({ targetDir, kitDir, globalOpts, opts }) {
   console.log(`📦 Refreshing the shared runtime in ${relative(targetDir, kitDir)}/ (stack files untouched)...`);
   copyDirContents(join(__dirname, 'shared', 'build-kit'), kitDir);
+  // The kit is now this CLI's runtime — record that, so the startup "kit is outdated" hint stops.
+  const manifestPath = join(kitDir, '.eventmodelers', 'install-manifest.json');
+  if (existsSync(manifestPath)) {
+    writeFileSync(manifestPath, JSON.stringify({ ...readJsonSafe(manifestPath), version: CLI_VERSION }, null, 2));
+  }
   for (const script of ['ralph.sh', 'lib/agent.sh', 'ralph-claude.js', 'ralph-local-ai.js', 'ralph-exec.js']) {
     const p = join(kitDir, script);
     if (existsSync(p)) {
@@ -1943,13 +1949,16 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // board-change turn can just as well be the first turn a (re)spawned process
   // ever sees, so both turn builders go through this rather than buildTurn owning it.
   function withSessionHeader(body) {
+    // token= names the env var, never its value: claudeEnv already carries EVENTMODELERS_TOKEN,
+    // and a literal token here would sit in every session transcript (the connect skill treats
+    // the reference as an inline token — see its Step 0).
     // Nothing to prepend for a local model: it has no CLAUDE.md to read and no /connect to run
     // (its tools are already authenticated), and handing it the raw token would put credentials
     // in a context that has no way to use them.
     if (localRunner) return body;
     if (!firstTurn) return body;
     firstTurn = false;
-    return `MODE=modeling token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\n\n${QUESTIONING_RULE}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
+    return `MODE=modeling token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\n\n${QUESTIONING_RULE}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
   }
 
   function buildTurn(p) {
@@ -2705,7 +2714,7 @@ const program = new Command();
 program
   .name('eventmodelers')
   .description('Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack')
-  .version('1.0.0')
+  .version(CLI_VERSION)
   .option('--config <path>', 'Path to an explicit config.json, overriding directory-based resolution (individual fields can also be set via EVENTMODELERS_* env vars, which always win)')
   .option('--print', 'Print follow-up commands (e.g. claude mcp add) instead of prompting to run them');
 
@@ -2725,6 +2734,21 @@ program
 // than this generic gate can.
 const NO_INIT_REQUIRED = new Set(['init', 'init-config', 'stacks', 'status', 'config', 'uninstall', 'fetch', 'activate-context', 'set-slice-status', 'release-notes', 'run']);
 
+// Commands that install or refresh the kit themselves — a "your kit is outdated" hint in
+// front of them would only be noise.
+const NO_KIT_UPDATE_HINT = new Set(['init', 're-init', 'uninstall']);
+
+// Startup hint when this CLI is behind npm, or an installed kit here is behind this CLI.
+// Best effort and on stderr, so it never breaks piped output; EVENTMODELERS_NO_UPDATE_CHECK
+// (or CI) turns it off.
+program.hook('preAction', async (_thisCommand, actionCommand) => {
+  if (process.env.EVENTMODELERS_NO_UPDATE_CHECK || process.env.CI) return;
+  const latestVersion = await latestPublishedVersion({ cachePath: join(GLOBAL_DIR, 'update-check.json') });
+  const kitDirs = NO_KIT_UPDATE_HINT.has(actionCommand.name()) ? [] : findAllInstalledKitDirs(process.cwd());
+  const hints = updateHints({ currentVersion: CLI_VERSION, latestVersion, kitDirs });
+  if (hints.length) console.error(`${hints.join('\n')}\n`);
+});
+
 program.hook('preAction', (_thisCommand, actionCommand) => {
   if (NO_INIT_REQUIRED.has(actionCommand.name())) return;
   if (findInstalledKitDir(process.cwd())) return;

package/lib/update-check.js

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { basename, dirname, join, relative } from 'path';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/@eventmodelers/cli/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+
+// Kit dirs `re-init` can refresh, and how to ask it to.
+const REINIT_COMMANDS = {
+  '.build-kit': 'eventmodelers re-init',
+  '.agent-modeling-kit': 'eventmodelers re-init --modeling',
+};
+
+// Numeric compare of x.y.z versions — negative when a < b. Pre-release suffixes are ignored.
+export function compareVersions(a, b) {
+  const pa = String(a).split('-')[0].split('.').map(Number);
+  const pb = String(b).split('-')[0].split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return {}; }
+}
+
+// The latest published version, asked of the npm registry at most once a day — in between,
+// the answer cached at cachePath is reused. Best effort: offline, slow or broken registry
+// responses just yield whatever was cached last (or null).
+export async function latestPublishedVersion({ cachePath, now = Date.now(), fetchImpl = fetch } = {}) {
+  const cache = readJson(cachePath);
+  if (cache.latest && now - (cache.checkedAt || 0) < CHECK_INTERVAL_MS) return cache.latest;
+
+  try {
+    const res = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!res.ok) return cache.latest || null;
+    const { version } = await res.json();
+    if (!version) return cache.latest || null;
+    try {
+      mkdirSync(dirname(cachePath), { recursive: true });
+      writeFileSync(cachePath, JSON.stringify({ latest: version, checkedAt: now }));
+    } catch {}
+    return version;
+  } catch {
+    return cache.latest || null;
+  }
+}
+
+// Hint lines for everything that's behind: this CLI against npm, and each installed kit
+// against the CLI running now (its install manifest records the version that wrote it).
+export function updateHints({ currentVersion, latestVersion, kitDirs = [], cwd = process.cwd() }) {
+  const hints = [];
+  if (latestVersion && compareVersions(currentVersion, latestVersion) < 0) {
+    hints.push(`💡 A new eventmodelers CLI is available: ${currentVersion} → ${latestVersion}. Update with: npm i -g @eventmodelers/cli@latest (or use npx @eventmodelers/cli@latest)`);
+  }
+  for (const kitDir of kitDirs) {
+    const reinit = REINIT_COMMANDS[basename(kitDir)];
+    const manifestPath = join(kitDir, '.eventmodelers', 'install-manifest.json');
+    if (!reinit || !existsSync(manifestPath)) continue;
+    const kitVersion = readJson(manifestPath).version;
+    if (kitVersion && compareVersions(kitVersion, currentVersion) >= 0) continue;
+    hints.push(`💡 ${relative(cwd, kitDir) || kitDir}/ was installed by CLI ${kitVersion || '(unknown version)'} — refresh it to ${currentVersion} with: ${reinit}`);
+  }
+  return hints;
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.90",
+  "version": "1.0.91",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {
     "eventmodelers": "cli.js"
   },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "files": [
     "cli.js",
     "lib",

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]; };
+}