@eventmodelers/cli 1.0.88 → 1.0.89

package/README.md

@@ -55,6 +55,8 @@ npx @eventmodelers/cli run
 
 `run` doesn't re-configure anything. It finds whatever kit dir `init` already created in this project and starts its agent loop (`ralph-claude.js`) against your existing `.eventmodelers/config.json`.
 
+Each agent turn is capped at 60 minutes by default so a hung agent can't stall the loop: it gets SIGTERM, then SIGKILL 10s later, and a slice that keeps timing out is Blocked by the stuck-slice guard. Change the cap with `"turnTimeoutMinutes"` in `.eventmodelers/config.json` or `RALPH_TURN_TIMEOUT_MIN` for one run; `0` turns it off.
+
 **Pulling the latest board state without starting an agent** — e.g. to inspect a context's slices, or in a script:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.88",
+  "version": "1.0.89",
   "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": {

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

@@ -0,0 +1,12 @@
+// Exponential backoff with jitter: baseMs, 2×, 4×, … capped at capMs. Half the delay is
+// fixed, half random, so agents that failed together (a platform restart takes every agent
+// on it down at once) don't all come back in the same second.
+//
+// attempt is 1-based — the delay before the first retry is between baseMs/2 and baseMs.
+
+export function backoffMs(attempt, { baseMs, capMs }) {
+  const ceiling = Math.min(capMs, baseMs * 2 ** Math.max(0, attempt - 1));
+  return Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

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

@@ -11,6 +11,7 @@ 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';
 
 // ── HTTP helpers ──────────────────────────────────────────────────────────────
 
@@ -275,6 +276,15 @@ async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
   await retryOn401('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.
+  if (payload?.agentId && cfg.agentId && payload.agentId === cfg.agentId) {
+    console.log(`[agent] Own write — not queued (slice="${payload.sliceTitle}" status="${payload.sliceStatus}")`);
+    return;
+  }
   // 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
@@ -321,11 +331,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.
-  // Capped so a non-expiry auth failure (e.g. genuinely revoked access) can't turn
-  // into a tight resubscribe loop hammering the platform forever.
+  // 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
+  // retryOn401 inside refreshToken.
   let channelErrorStreak = 0;
+  let resubscribeTimer = null;
+  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;
+    channelErrorStreak += 1;
+    const delay = backoffMs(channelErrorStreak, { baseMs: 2_000, capMs: 5 * 60_000 });
+    console.warn(`[agent] ${ts()} Channel "${channelName}": ${reason} (attempt ${channelErrorStreak}) — resubscribing in ${Math.round(delay / 1000)}s`);
+    resubscribeTimer = 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;
+      subscribeChannel();
+    }, delay);
+  };
   const subscribeChannel = () => {
-    realtime.subscribe(
+    Promise.resolve(realtime.subscribe(
       channelName,
       {
         // A kill names exactly one agent: {type: 'kill', id: '<agentId>', instruction: 'exit'}.
@@ -340,32 +372,22 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
         },
         'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
       },
-      async (status) => {
-        if (status !== 'CHANNEL_ERROR' && status !== 'TIMED_OUT') {
-          if (channelErrorStreak > 0) {
-            console.log(`[agent] ${ts()} Channel "${channelName}": ${status} — recovered after ${channelErrorStreak} failed attempt(s)`);
-          } else {
-            console.log(`[agent] ${ts()} Channel "${channelName}": ${status}`);
-          }
-          channelErrorStreak = 0;
-          return;
-        }
-        channelErrorStreak += 1;
-        console.warn(`[agent] ${ts()} Channel "${channelName}": ${status} (attempt ${channelErrorStreak}/5)`);
-        if (channelErrorStreak > 5) {
-          console.error(`[agent] ${ts()} Channel "${channelName}" failed ${channelErrorStreak} times in a row — giving up until the next scheduled token refresh (every 10min)`);
+      (status) => {
+        if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') return onChannelFailure(status);
+        if (status !== 'SUBSCRIBED' || channelErrorStreak === 0) {
+          console.log(`[agent] ${ts()} Channel "${channelName}": ${status}`);
           return;
         }
-        try {
-          await refreshToken(`channel ${status}`);
-          await new Promise((r) => setTimeout(r, 2_000));
-          console.log(`[agent] ${ts()} Resubscribing to channel "${channelName}" (attempt ${channelErrorStreak}/5)...`);
-          subscribeChannel();
-        } catch (err) {
-          console.error(`[agent] ${ts()} Token refresh after channel error failed, will not resubscribe this round:`, err);
-        }
+        console.log(`[agent] ${ts()} Channel "${channelName}": ${status} — recovered after ${channelErrorStreak} failed attempt(s)`);
+        channelErrorStreak = 0;
+        // 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.
+        retryOn401('fetchAndPersistSlices (after reconnect)', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
+          console.error(`[agent] ${ts()} Slice re-fetch after reconnect failed:`, err),
+        );
       },
-    );
+    )).catch((err) => onChannelFailure(`subscribe failed: ${err.message}`));
   };
   subscribeChannel();
 
@@ -531,15 +553,26 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
   console.error(`[ralph] ${reason} Marked "${planned.title}" (id=${planned.id}) as Blocked — moving on.`);
 }
 
+// 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.
 async function runWithRetry(label, fn) {
-  while (true) {
+  for (let attempt = 1; ; attempt++) {
     try {
       console.log(`[ralph] ${label}`);
       await fn();
-      return;
+      return true;
     } catch (err) {
-      console.error(`[ralph] Error — retrying in 60s:`, err.message);
-      await new Promise((r) => setTimeout(r, 60_000));
+      if (err?.timedOut) {
+        console.error(`[ralph] ${err.message} — back to the loop`);
+        return false;
+      }
+      const delay = backoffMs(attempt, { baseMs: 30_000, capMs: 10 * 60_000 });
+      console.error(`[ralph] Error (attempt ${attempt}) — retrying in ${Math.round(delay / 1000)}s:`, err.message);
+      await sleep(delay);
     }
   }
 }
@@ -580,7 +613,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
       }
 
       const prompt = readFileSync(backendPromptFile, 'utf-8');
-      await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt, {
+      const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt, {
         sliceId: planned.id,
         sliceTitle: planned.title,
         context: planned.ctx,
@@ -588,7 +621,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
         boardId: cfg.boardId ?? null,
         attempt: stuckSlice.count,
       }));
-      console.log(`[ralph] Slice build complete — waiting for next slice`);
+      if (built) console.log(`[ralph] Slice build complete — waiting for next slice`);
       if (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
     }

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

@@ -0,0 +1,57 @@
+// Wall-clock cap on one agent turn. Without it a hung harness (a stuck tool call, a
+// network stall, an interactive prompt nobody answers) blocks the loop forever — no
+// further tasks, no further slices, and the stuck-slice guard never gets a look in.
+//
+// RALPH_TURN_TIMEOUT_MIN (env) or turnTimeoutMinutes (.eventmodelers/config.json);
+// default 60, 0 turns the cap off.
+
+import { execFile } from 'child_process';
+
+const KILL_GRACE_MS = 10_000;
+
+export function turnTimeoutMs(cfg) {
+  const raw = process.env.RALPH_TURN_TIMEOUT_MIN ?? cfg?.turnTimeoutMinutes ?? 60;
+  const minutes = Number(raw);
+  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 {
+  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.
+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();
+}
+
+export function superviseTurn(proc, { timeoutMs, label, log, viaShell = false }) {
+  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);
+      }, timeoutMs)
+    : null;
+  proc.on('close', () => {
+    clearTimeout(timer);
+    clearTimeout(killTimer);
+  });
+  return { timedOut: () => timedOut };
+}

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

@@ -4,6 +4,7 @@
 
 import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
 import { createSliceTracer, usageFromClaudeResult } from './lib/tracing.js';
+import { turnTimeoutMs, superviseTurn, TurnTimeoutError } from './lib/turn.js';
 import { spawn } from 'child_process';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -33,9 +34,17 @@ const tracer = createSliceTracer({
 // --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=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
+  ? `board=${cfg.boardId} token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
   : '';
+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
@@ -86,6 +95,7 @@ function runClaude(prompt, slice = null) {
       stdio: ['inherit', 'pipe', 'inherit'],
       env: claudeEnv,
     });
+    const turn = superviseTurn(proc, { timeoutMs, label: 'Claude turn', log: (line) => console.error(`[ralph] ${line}`) });
 
     let buffer = '';
     proc.stdout.on('data', (chunk) => {
@@ -99,9 +109,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(block.text);
+            if (block.type === 'text' && block.text && verbose) console.log(redact(block.text));
             if (block.type === 'tool_use') {
-              if (verbose) console.log(`→ ${describeToolUse(block)}`);
+              if (verbose) console.log(`→ ${redact(describeToolUse(block))}`);
               else if (block.name === 'Skill') console.log(`→ Skill: ${block.input?.skill ?? ''}`);
               else console.log(`→ ${block.name}`);
             }
@@ -113,7 +123,11 @@ function runClaude(prompt, slice = null) {
       }
     });
 
-    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Claude exited ${code}`))));
+    proc.on('close', (code) => {
+      if (turn.timedOut()) reject(new TurnTimeoutError('Claude turn', timeoutMs));
+      else if (code === 0) resolve();
+      else reject(new Error(`Claude exited ${code}`));
+    });
     proc.on('error', reject);
   });
 }

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

@@ -19,6 +19,7 @@
 
 import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
 import { createSliceTracer, usageFromHarnessEvent, sumUsage } from './lib/tracing.js';
+import { turnTimeoutMs, superviseTurn, TurnTimeoutError } from './lib/turn.js';
 import { spawn } from 'child_process';
 import { writeFileSync, mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
@@ -42,10 +43,12 @@ if (!execCmd) {
 }
 
 // Same rule as ralph-claude.js: --local must mean zero board contact, so credentials
-// never reach the child even when config.json has them.
+// never reach the child even when config.json has them. Also as there: the token is
+// passed by env var name, never by value — the prompt goes on the command line.
 const inlineHeader = !localOnly && cfg.boardId
-  ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
+  ? `board=${cfg.boardId} token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
   : '';
+const timeoutMs = turnTimeoutMs(cfg);
 
 const childEnv = {
   ...process.env,
@@ -122,8 +125,10 @@ function runExec(prompt, slice = null) {
       shell: true,
       env: { ...childEnv, RALPH_PROMPT_FILE: promptFile },
     });
+    const turn = superviseTurn(proc, { timeoutMs, label: 'exec turn', viaShell: true, log: (line) => console.error(`[ralph-exec] ${line}`) });
     const usage = traced ? collectUsage(proc.stdout) : null;
     proc.on('close', (code) => {
+      if (turn.timedOut()) return reject(new TurnTimeoutError('exec turn', timeoutMs));
       if (traced) {
         const u = usage();
         if (u) tracer.record({ ...slice, status: code === 0 ? 'ok' : 'error' }, { ...u, durationMs: u.durationMs ?? Date.now() - startedAt });

package/shared/skills/connect/SKILL.md

@@ -61,6 +61,8 @@ If an inline `board=<uuid>` is found, use it as `BOARD_ID` — **it takes priori
 
 (`agent=<uuid>` is not one of the four required values — it is optional, and its absence never makes this skill ask anything.)
 
+**`token=$EVENTMODELERS_TOKEN` is an inline token too.** The build loop passes the env var's *name*, not its value, so the secret never sits in the prompt. Treat it exactly like a literal inline token: `TOKEN` is `$EVENTMODELERS_TOKEN` (it counts toward "all four inline" below). Keep using the reference, never its value — write curl headers as `-H "x-token: $EVENTMODELERS_TOKEN"` (double quotes, so the shell expands it), don't `echo` or print it, and hand it to a subagent as `token=$EVENTMODELERS_TOKEN` (it inherits the same environment). MCP calls need nothing extra — `.mcp.json` already reads the same variable.
+
 **All four inline means this skill is already finished — stop here.** `token=`, `board=`, `org=` and `baseUrl=` arriving together is the shape a parent agent hands a subagent, and it resolves every required value in this one step. Do not walk the config file (Step 1), do not ask anything (Step 2), do not persist (Step 3), and do not make the verify call (Step 4): the parent resolved these values against this board and verified them there, so a subagent verifying them again learns nothing it wasn't just told and pays a round trip for it. Step 3.5 is a no-op too whenever `.mcp.json` already carries an `eventmodelers` entry — read the file, don't rewrite it, and don't re-register a server the session is already connected to. Print `Connected — board <BOARD_ID>` and return to the skill that invoked you.
 
 ---