@eventmodelers/cli 1.0.85 → 1.0.86

package/cli.js

@@ -32,13 +32,14 @@ const __dirname = dirname(__filename);
 
 // Each stack is a template set under stacks/<key>/templates/{.claude,root,<kitSubdir>}.
 // Stacks with useShared:true also get shared/build-kit/* copied into their kit dir
-// first (ralph.js, ralph-claude.js, ralph-local-ai.js, ralph-exec.js, ralph.sh, realtime-agent.js,
+// (ralph.js, ralph-claude.js, ralph-local-ai.js, ralph-exec.js, ralph.sh, realtime-agent.js,
 // code-export.mjs, lib/agent.sh, lib/local-ai-agent.js, package.json, README.md) —
 // those files have no per-stack content, so they live once instead of being
 // copy-pasted into every stack (that copy-pasting is exactly how they drifted out
 // of sync before: a bugfix or default landing in one stack's copy but not another's).
-// Each stack's own templates/<kitSubdir>/* is then overlaid on top for genuine
-// per-stack differences (ralph-claude.js's build tooling, lib/prompt.md, etc.).
+// Each stack's own templates/<kitSubdir>/* supplies the genuine per-stack files
+// (lib/prompt.md, lib/backend-prompt.md, lib/AGENT.md, checks, etc.); shared/build-kit/*
+// is copied after it, so the shared runtime always wins over any copy a stack still ships.
 // modeling-kit (below) is the one kit that opts out of all of this (useShared:false)
 // — it has no cold-spawn/tasks.json runtime at all, so none of shared/build-kit/*
 // applies to it; see its own templates/kit for its (much smaller) self-contained set.
@@ -1011,10 +1012,13 @@ async function installStack(stackKey, stackCfg, options = {}) {
     mkdirSync(kitDir, { recursive: true });
     console.log(`📦 Installing agent kit into ${stackCfg.kitDirName}/...`);
 
+    copyDirContents(join(templatesSource, stackCfg.kitSubdir), kitDir, { skip: ['.eventmodelers'] });
+    // Shared runtime goes on LAST so it always wins: a stack (built-in or --git) that still
+    // ships its own ralph.js / ralph-claude.js / ... is shipping a stale copy, and letting it
+    // overlay the shared one silently drops runtime fixes (e.g. agent_id on the heartbeat).
     if (stackCfg.useShared) {
       copyDirContents(sharedBuildKit, kitDir);
     }
-    copyDirContents(join(templatesSource, stackCfg.kitSubdir), kitDir, { skip: ['.eventmodelers'] });
 
     // An outdated community/--git stack that still ships root/CLAUDE.md (the pre-fix
     // layout every built-in stack used to follow too) gets it relocated here instead
@@ -1122,6 +1126,8 @@ async function installStack(stackKey, stackCfg, options = {}) {
       // placeholder, never the literal secret (see connect/SKILL.md's Security notes).
       ensureMcpRegistered(targetDir, config.baseUrl || DEFAULT_BASE_URL);
       ensureEnvToken(targetDir, config.token);
+      // Only build stacks trace (slice build cost); they are the ones running the shared runtime.
+      if (stackCfg.useShared) await configureAgentTracing(configPath, options.print);
     }
 
     // --- 6. Install manifest (drives precise `uninstall` later) ---
@@ -1154,6 +1160,23 @@ async function installStack(stackKey, stackCfg, options = {}) {
     console.log(`  npx @eventmodelers/cli init-agents\n`);
 }
 
+// `agentTracing` in config.json: whether a build agent reports what each slice build cost to the
+// platform (see agent-tracking.md). Asked once per project; off unless the user opts in — unset
+// (e.g. --print installs) is off, and off means the runner sends nothing.
+// `reask` (a bare `init-config`) asks again even when it is already set, defaulting to the
+// current answer.
+async function configureAgentTracing(configPath, print, reask = false) {
+  const current = readJsonSafe(configPath);
+  if (print || (typeof current.agentTracing === 'boolean' && !reask)) return;
+  const agentTracing = await selectPrompt('Should EM-Studio track the agent cost of each slice?', [
+    { label: 'Yes — track the cost per slice', value: true },
+    { label: 'No — send nothing', value: false },
+  ], current.agentTracing === true ? 0 : 1);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify({ ...current, agentTracing }, null, 2));
+  console.log(`  ✓ Agent tracing ${agentTracing ? 'on' : 'off'} — change it with \`eventmodelers config --agent-tracing on|off\``);
+}
+
 // Extracted from installStack so `init-config` can reuse the exact same
 // paste/manual/instructions/skip flow without also scaffolding a stack.
 // `overrides` are values passed directly on the command line (--token, --board-id,
@@ -1254,6 +1277,43 @@ async function configureCredentials({ config, configPath, targetDir, requiredFie
   return config;
 }
 
+// `re-init` for a build kit: re-copy shared/build-kit (ralph.js, the runners, tracing, adapters)
+// over the installed kit, then re-run the config steps. Stack templates and skills are untouched.
+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);
+  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)) {
+      try { execSync(`chmod +x "${p}"`); } catch {}
+    }
+  }
+  console.log('📦 Installing kit dependencies...');
+  try {
+    execSync('npm install', { cwd: kitDir, stdio: ['ignore', 'inherit', 'inherit'] });
+  } catch {
+    console.error('  ⚠️  npm install failed in kit — run it manually');
+  }
+
+  console.log('🔐 Configuring...');
+  const configPath = globalOpts.config
+    ? resolve(targetDir, globalOpts.config)
+    : join(targetDir, '.eventmodelers', 'config.json');
+  const overrides = { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) };
+  const cfg = await configureCredentials({
+    config: loadEffectiveConfig(targetDir, kitDir, globalOpts.config).config,
+    configPath,
+    targetDir,
+    requiredFields: ['organizationId', 'boardId', 'token'],
+    overrides,
+    print: globalOpts.print,
+    force: opts.force,
+  });
+  ensureMcpRegistered(targetDir, cfg.baseUrl || DEFAULT_BASE_URL);
+  ensureEnvToken(targetDir, cfg.token);
+  await configureAgentTracing(configPath, globalOpts.print, true);
+}
+
 // Configure the MCP server registration for a project — split out of `init` into
 // its own command (`init-mcp`) since not every harness/workflow wants an
 // automatic .claude/settings.json edit or an interactive "connect elsewhere?"
@@ -1594,16 +1654,22 @@ async function resolveModelingCredentials(cwd, flags, explicitConfigPath, print,
   // common case to one keystroke. Skipped when there is no one to ask (--print, or a
   // non-interactive stdin such as CI or a process supervisor), where the resolved value
   // stands on its own exactly as before.
+  //
+  // The answer may also be the whole credentials blob from the account page — it names the
+  // board too, so it answers this question and the "where do its credentials come from" one
+  // below in a single paste.
   let boardChosen = !!(explicit.boardId || process.env.EVENTMODELERS_BOARD_ID);
+  let pasted = null;
   if (!boardChosen && interactive) {
     const answer = await prompt(boardId ? `\n  Board ID [${boardId}]: ` : '\n  Board ID: ');
     if (answer) {
-      boardId = answer;
+      pasted = parseCredentialsPaste(answer, ['organizationId', 'token', 'boardId']);
+      boardId = pasted ? pasted.boardId : answer;
       boardChosen = true;
     }
   }
 
-  let stored = boardId ? readJsonSafe(boardCredentialsPath(boardId)) : {};
+  let stored = pasted ?? (boardId ? readJsonSafe(boardCredentialsPath(boardId)) : {});
 
   // Follow a pointer left by an earlier answer: this directory (or the account config) keeps
   // resolving to one board, but the credentials pasted for it named another. Without this the
@@ -1625,7 +1691,7 @@ async function resolveModelingCredentials(cwd, flags, explicitConfigPath, print,
   // implied — explicit credentials on the command line — or when there is no one to ask:
   // --print, or a non-interactive stdin such as CI or a supervisor that would otherwise
   // hang here forever (those keep using whatever is on file, silently).
-  if (interactive && !credentialsNamed) {
+  if (!pasted && interactive && !credentialsNamed) {
     const hasAccountWide = !!(walked.token && walked.organizationId);
 
     // What "keep" would keep. A pointer entry is deliberately not offered: it says the
@@ -2836,9 +2902,9 @@ const REINITIABLE_STACKS = { ...STACKS, [MODELING_KIT.key]: MODELING_KIT, [BLANK
 
 credentialFlags(program
   .command('re-init')
-  .description('Refresh an already-installed kit from the current CLI version — re-copies skills and the kit dir (.build-kit or .agent-modeling-kit) so you pick up script/skill updates after upgrading. Unlike `init`, never touches the project root scaffold or the root CLAUDE.md router, and leaves existing credentials alone unless --force is passed.')
+  .description("Refresh an installed kit from the current CLI version. For a build kit: re-copies this CLI's shared runtime (ralph.js, ralph-claude.js, tracing, adapters) into .build-kit and re-runs the config (credentials unless complete, agent tracing) — the stack's own files and skills are left alone, so this works for --git stacks too. --stack <name> instead refreshes everything from that built-in stack; --modeling refreshes .agent-modeling-kit. Never touches the project root scaffold or the root CLAUDE.md router.")
   .option('--modeling', 'Refresh the modeling kit (.agent-modeling-kit) instead of a build kit')
-  .option('--stack <name>', `Override which stack to refresh from (${Object.keys(REINITIABLE_STACKS).join(', ')}) instead of the one recorded in install-manifest.json — use this when the manifest is missing/stale, or to switch a .build-kit install to a different stack`)
+  .option('--stack <name>', `Also refresh the stack's own files and skills from this built-in stack (${Object.keys(REINITIABLE_STACKS).join(', ')}) — or switch a .build-kit install to a different stack. Without it, only the shared runtime and the config are refreshed`)
   .option('--hooks', 'Install the slice commit-scope guard (.githooks/pre-commit) and wire it up via `git config core.hooksPath .githooks` — same as `init --hooks`, for turning it on after the fact without a full re-scaffold. Off by default.')
   .option('--global', 'Re-install skills into ~/.claude/skills/ instead of the project — defaults to however they were originally installed')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json')
@@ -2866,6 +2932,14 @@ credentialFlags(program
     }
 
     const manifest = readJsonSafe(join(kitDir, '.eventmodelers', 'install-manifest.json'));
+
+    // A build kit without --stack: refresh only what this CLI owns — the shared runtime and the
+    // config — and never the stack's own files. Works for any stack, --git ones included.
+    if (!opts.modeling && !opts.stack) {
+      await refreshSharedRuntime({ targetDir, kitDir, globalOpts, opts });
+      return;
+    }
+
     const stackKey = opts.modeling ? MODELING_KIT.key : (opts.stack || manifest.stack);
     const stackCfg = stackKey ? REINITIABLE_STACKS[stackKey] : null;
 
@@ -3110,6 +3184,9 @@ credentialFlags(program
       // (see the beta-api protected-resource-metadata incident this fixed).
       ensureMcpRegistered(targetDir, cfg.baseUrl || DEFAULT_BASE_URL);
       ensureEnvToken(targetDir, cfg.token);
+      if (existsSync(join(targetDir, STACKS.node.kitDirName))) {
+        await configureAgentTracing(configPath, globalOpts.print, !Object.values(overrides).some(Boolean));
+      }
     }
   });
 
@@ -3205,6 +3282,12 @@ credentialFlags(program
       // credentials resolved from flags/env/~/.eventmodelers — so the current directory is
       // neither read nor written, and the command works from anywhere.
       let kitDir = opts.global ? null : modelingKitDir;
+      // A pre-config.js install (the old ralph-based kit) shares the dir name but can't
+      // drive this loop — fall through to the global install rather than refusing to run.
+      if (kitDir && !existsSync(join(kitDir, 'lib', 'config.js'))) {
+        console.log(`ℹ️  Ignoring ${relative(cwd, kitDir)} — an outdated kit without lib/config.js (run \`init --modeling\` here to replace it). Using the global install.\n`);
+        kitDir = null;
+      }
       let projectDir = kitDir ? resolve(kitDir, '..') : null;
       let overrides = null;
       if (!kitDir) {
@@ -3824,10 +3907,25 @@ program
 program
   .command('config')
   .description('Print the fully resolved config (merged across the directory hierarchy + EVENTMODELERS_* env vars), with the token masked')
+  .option('--agent-tracing <on|off>', "Turn agent tracing on or off for this project (saved as `agentTracing` in the project's .eventmodelers/config.json). Off: the build agent sends no slice cost data to the platform at all.")
   .action((opts, command) => {
     const cwd = process.cwd();
     const kitDir = findInstalledKitDir(cwd);
     const explicitConfig = command.optsWithGlobals().config;
+
+    if (opts.agentTracing !== undefined) {
+      const value = String(opts.agentTracing).toLowerCase();
+      if (!['on', 'off'].includes(value)) {
+        console.error('❌ --agent-tracing takes "on" or "off"');
+        process.exit(1);
+      }
+      const configPath = explicitConfig
+        ? resolve(explicitConfig)
+        : join(kitDir ? dirname(kitDir) : cwd, '.eventmodelers', 'config.json');
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, JSON.stringify({ ...readJsonSafe(configPath), agentTracing: value === 'on' }, null, 2));
+      console.log(`✓ Agent tracing ${value} — saved to ${relative(cwd, configPath) || configPath}\n`);
+    }
     const { sources, config } = loadEffectiveConfig(cwd, kitDir, explicitConfig);
 
     const resolved = { ...config };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.85",
+  "version": "1.0.86",
   "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/ralph.js

@@ -3,7 +3,8 @@
 //
 // startRalph({ kitDir, projectDir, onTask, onPlannedSlice })
 //   onTask(prompt) — called when tasks.json has entries
-//   onPlannedSlice(prompt) — called when .slices/ has a "Planned" entry (omit to skip)
+//   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 { join, dirname } from 'path';
@@ -250,7 +251,9 @@ 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')) : {};
-      writeFileSync(sliceJsonPath, JSON.stringify({ ...existingSlice, ...slice }, null, 2), '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');
     }
   }
 
@@ -417,6 +420,17 @@ 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;
+  try {
+    return JSON.parse(readFileSync(join(kitDir, '.slices', ctx, folder, 'slice.json'), 'utf-8')).ticketNumber ?? null;
+  } catch {
+    return null;
+  }
+}
+
 // Returns the first Planned slice IN THE CURRENT CONTEXT ONLY. If the current
 // context has no planned work, returns null so the loop waits — it must NEVER
 // cross into another context to find something to build.
@@ -428,7 +442,7 @@ function getFirstPlannedSlice(kitDir) {
   try {
     const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
     const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === 'planned');
-    if (planned) return { id: planned.id ?? null, title: planned.slice || planned.id || null, ctx: currentCtx };
+    if (planned) return { id: planned.id ?? null, title: planned.slice || planned.id || null, ctx: currentCtx, ticketNumber: readTicketNumber(kitDir, currentCtx, planned.folder) };
   } catch {}
   return null;
 }
@@ -566,7 +580,14 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
       }
 
       const prompt = readFileSync(backendPromptFile, 'utf-8');
-      await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt));
+      await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt, {
+        sliceId: planned.id,
+        sliceTitle: planned.title,
+        context: planned.ctx,
+        ticketNumber: planned.ticketNumber,
+        boardId: cfg.boardId ?? null,
+        attempt: stuckSlice.count,
+      }));
       console.log(`[ralph] Slice build complete — waiting for next slice`);
       if (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
@@ -590,15 +611,23 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
 
 export { loadLocalConfig, fetchPlatformConfig, retryOn401, startRealtimeAgent };
 
+// 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
+// agent of the same type can run side by side without the two overwriting each other's
+// heartbeat row, and so the board can show a name instead of a bare uuid. An override skips
+// ensureAgentId rather than overwriting it — the project's stable id stays on disk for the next
+// 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 || '';
+  process.env.EVENTMODELERS_AGENT_ID = agentId;
+  return { agentId, agentName, agentType };
+}
+
 export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, agentType = 'BUILD', queueAllStatuses = false, localOnly = false }) {
   const local = loadLocalConfig(kitDir);
-  // 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 agent of the same
-  // type can run side by side without the two overwriting each other's heartbeat row, and so
-  // the board can show a name instead of a bare uuid. An override skips ensureAgentId rather
-  // than overwriting it — the project's stable id stays on disk for the next plain run.
-  local.agentId = process.env.RALPH_AGENT_ID || ensureAgentId(kitDir, agentType);
-  if (process.env.RALPH_AGENT_NAME) local.agentName = process.env.RALPH_AGENT_NAME;
+  Object.assign(local, resolveAgentIdentity(kitDir, agentType, local));
 
   console.log(`Ralph — kit: ${kitDir}`);
   console.log(`         project: ${projectDir}`);

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

@@ -0,0 +1,92 @@
+// What a slice costs: one trace per build turn against one slice, posted to the platform's
+// /api/org/:orgId/boards/:boardId/agent-traces. Only the runner can see what a turn cost, so it reports it.
+//
+// Best effort: each trace is appended to a local JSONL file, then POSTed once. No retries, no
+// buffering. A failed upload is logged and forgotten; the file is the record.
+
+import { randomUUID } from 'crypto';
+import { appendFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+export const newId = () => randomUUID();
+
+const n = (v) => (Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
+
+/** Claude Code's `result` message — the only one whose numbers are final. The `assistant` events
+ *  repeat one call's usage per content block AND report it mid-stream, so they cannot be used for
+ *  accounting. `modelUsage` names the dominant model, which matters when subagents ran on a
+ *  cheaper one than the lead. Cost is list price, even on a subscription. */
+export function usageFromClaudeResult(msg) {
+  const u = msg?.usage ?? {};
+  const [dominant] = Object.entries(msg?.modelUsage ?? {})
+    .sort((a, b) => (b[1]?.outputTokens ?? 0) - (a[1]?.outputTokens ?? 0))[0] ?? [];
+  return {
+    inputTokens: n(u.input_tokens),
+    outputTokens: n(u.output_tokens),
+    cacheReadTokens: n(u.cache_read_input_tokens),
+    cacheWriteTokens: n(u.cache_creation_input_tokens),
+    costUsd: Number.isFinite(msg?.total_cost_usd) ? msg.total_cost_usd : null,
+    durationMs: Number.isFinite(msg?.duration_ms) ? msg.duration_ms : null,
+    model: dominant ?? null,
+  };
+}
+
+/** A local model's per-round usage. Ollama reports it at the top level of /api/chat,
+ *  OpenAI-compatible servers under `usage`. Cost 0: a local model is genuinely free. */
+export function usageFromLocalAi(raw, durationMs) {
+  const openai = raw?.usage;
+  if (!openai && !Number.isFinite(raw?.eval_count) && !Number.isFinite(raw?.prompt_eval_count)) return null;
+  return {
+    inputTokens: n(openai ? openai.prompt_tokens : raw.prompt_eval_count),
+    outputTokens: n(openai ? openai.completion_tokens : raw.eval_count),
+    costUsd: 0,
+    durationMs: Number.isFinite(durationMs) ? durationMs : null,
+    model: typeof raw?.model === 'string' ? raw.model : null,
+  };
+}
+
+/** Records slice build turns. The agent id is the session: the platform requires one, and a
+ *  restart of the same build agent is still the same agent building the same slices. */
+export function createSliceTracer({ baseUrl, token, organizationId, agentId, traceFile, log = () => {}, enabled = true } = {}) {
+  const canUpload = !!(enabled && baseUrl && token && organizationId && agentId);
+
+  async function post(trace) {
+    // The platform files a trace under the board in its path — a turn without a board has nowhere to go.
+    if (!canUpload || !trace.boardId) return;
+    try {
+      const res = await fetch(`${baseUrl}/api/org/${organizationId}/boards/${trace.boardId}/agent-traces`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-token': token, 'x-agent-id': agentId },
+        body: JSON.stringify({ traces: [trace] }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      if (!res.ok) log(`trace: upload failed (HTTP ${res.status}${await res.text().then((t) => `: ${t}`).catch(() => '')}) — kept locally only`);
+    } catch (err) {
+      log(`trace: upload error (${err.message}) — kept locally only`);
+    }
+  }
+
+  function write(trace) {
+    if (!enabled || !traceFile) return;
+    try {
+      mkdirSync(dirname(traceFile), { recursive: true });
+      appendFileSync(traceFile, `${JSON.stringify(trace)}\n`);
+    } catch (err) {
+      if (!write.warned) { write.warned = true; log(`trace: cannot write ${traceFile} (${err.message})`); }
+    }
+  }
+
+  return {
+    /** One build turn: `{sliceId, sliceTitle, context, ticketNumber, boardId, attempt, status}` plus its usage.
+     *  ticketNumber is the slice's ticket at build time — it can change, so it travels with each turn. */
+    record({ sliceId, sliceTitle = null, context = null, ticketNumber = null, boardId = null, attempt = null, status = 'ok' }, usage) {
+      if (!sliceId || !usage) return;
+      const trace = {
+        id: newId(), occurredAt: new Date().toISOString(),
+        boardId, sliceId, sliceTitle, context, ticketNumber, agentId, sessionId: agentId, attempt, status, ...usage,
+      };
+      write(trace);
+      post(trace).catch(() => {});
+    },
+  };
+}

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

@@ -2,9 +2,10 @@
 // Ralph loop + realtime agent using Claude Code as the executor.
 // Usage: node ralph-claude.js [project_dir]
 
-import { startRalph, loadLocalConfig } from './lib/ralph.js';
+import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
+import { createSliceTracer, usageFromClaudeResult } from './lib/tracing.js';
 import { spawn } from 'child_process';
-import { dirname, resolve } from 'path';
+import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
 const kitDir = dirname(fileURLToPath(import.meta.url));
@@ -12,6 +13,23 @@ const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir,
 
 const cfg = loadLocalConfig(kitDir);
 const localOnly = process.env.RALPH_LOCAL === '1';
+// Resolved here, not left to startRalph: claudeEnv below is built at load time, and without it
+// the agent id never reached `claude`, so its MCP calls went unattributed.
+Object.assign(cfg, resolveAgentIdentity(kitDir, 'BUILD', cfg));
+
+// What each slice build turn cost — see lib/tracing.js. Off unless the project opted in
+// (`agentTracing: true`, see `eventmodelers config`); nothing is ever sent with --local.
+const tracingOn = !localOnly && cfg.agentTracing === true;
+if (!tracingOn && !localOnly) console.log('[ralph] agent tracing off — no slice cost data is sent (turn on: eventmodelers config --agent-tracing on)');
+const tracer = createSliceTracer({
+  baseUrl: cfg.baseUrl,
+  token: cfg.token,
+  organizationId: cfg.organizationId,
+  agentId: cfg.agentId,
+  traceFile: join(projectDir, '.eventmodelers', 'trace', 'slices.jsonl'),
+  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.
@@ -60,7 +78,8 @@ function describeToolUse(block) {
   }
 }
 
-function runClaude(prompt) {
+// `slice` is set for a planned-slice build (see startRalph) — the only turns that are traced.
+function runClaude(prompt, slice = null) {
   return new Promise((resolve, reject) => {
     const proc = spawn('claude', [...claudeArgs, '-p', inlineHeader + prompt], {
       cwd: projectDir,
@@ -89,6 +108,7 @@ function runClaude(prompt) {
           }
         } else if (msg.type === 'result') {
           console.log(`done (${msg.duration_ms}ms${msg.total_cost_usd ? `, $${msg.total_cost_usd.toFixed(4)}` : ''})`);
+          if (slice) tracer.record({...slice, status: msg.is_error ? 'error' : 'ok'}, usageFromClaudeResult(msg));
         }
       }
     });

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

@@ -17,7 +17,7 @@
 //        RALPH_EXEC_CMD="opencode run" node ralph-exec.js
 // Or persist it as localAi.exec in .eventmodelers/config.json.
 
-import { startRalph, loadLocalConfig } from './lib/ralph.js';
+import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
 import { spawn } from 'child_process';
 import { writeFileSync, mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
@@ -29,6 +29,8 @@ const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir,
 
 const cfg = loadLocalConfig(kitDir);
 const localOnly = process.env.RALPH_LOCAL === '1';
+// Same as ralph-claude.js: childEnv is built at load time, before startRalph resolves identity.
+Object.assign(cfg, resolveAgentIdentity(kitDir, 'BUILD', cfg));
 const execCmd = process.env.RALPH_EXEC_CMD || cfg.localAi?.exec;
 
 if (!execCmd) {

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -63,7 +63,6 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `render_screen` | `boardId`, `nodeId`, `elements[]?` (SCREEN) or `pages[]?`+`backgroundColor?` (HTML_SCREEN), `description?` | Update an existing screen's content — exactly one of `elements`/`pages` | §4 `POST .../images/:id/sketch` + `image-nodes` |
 | `add_field_examples` | `boardId`, `nodeId?`, `name?`, `cellName?`, `timelineId?` | Fill empty field examples using linked-node context | — (MCP-only convenience) |
 | `get_attribute_chain` | `boardId`, `timelineId`, `targetCellName`, `sourceCellName` | Resolve every node between two cells, ordered target→source. Both cell names must come from a node's reported `cellName` (`get_board_outline`, `get_nodes`, `get_node`) — a guessed address that happens to exist silently resolves the wrong chain | — (MCP-only convenience) |
-| `verify_screen` | `boardId`, `nodeId` | Check a screen node exists and has rendered content — works for both SCREEN and HTML_SCREEN, dispatching on the node's actual type | — (MCP-only convenience) |
 | `get_image_snapshot_description` | `boardId`, `nodeId` | Load the `{elements:[...]}` sketch description from storage | — (reads what §4 sketch endpoints write) |
 | `validate_slice_data` | `sliceData` | Offline validation of a `SliceDataOutput` payload — no board access | — (MCP-only, pure function) |
 | `commit_board_to_git` | `boardId` | Force a git-extension commit/push, bypassing the autoCommit gate | — (MCP-only; git extension) |

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-storyboarding-events/SKILL.md

@@ -231,6 +231,7 @@ mcp__eventmodelers__create_screen {
     "nodeId": "<node-uuid>",
     "chapterId": "<CHAPTER_ID>",
     "cellId": "<actorRowId>-<columnId>",
+    "title": "<Screen Title>",
     "pages": ["<div>...</div>"],
     "description": "<concise description of what this screen shows>",
     "fields": [ /* per "Mandatory Field Definitions" below — set in this same call */ ]
@@ -240,7 +241,7 @@ mcp__eventmodelers__create_screen {
 
 **Fallback (no MCP):** see `references/api-fallback.md` — "Mandatory Screen Rendering — Step B: Create the HTML_SCREEN node".
 
-The MCP `create_screen` call above already sets `meta.fields` (per "Mandatory Field Definitions" below) in the same call — no separate `node:changed` follow-up needed when using MCP.
+The MCP `create_screen` call above already sets the node's `title` and `meta.fields` (per "Mandatory Field Definitions" below) in the same call — no separate `node:changed` follow-up needed when using MCP.
 
 A storyboard screen is placed at a *provisional* position — Steps 4 and 5 wire it to its COMMAND / READMODEL once those exist, and may move it first. Pass `autoConnect: false` on `create_screen` here so the placement doesn't pre-wire the screen to whatever happens to sit in the adjacent column; the real `SCREEN → COMMAND` and `READMODEL → SCREEN` edges are created deliberately in Steps 4 and 5. When creating several screens whose HTML is already authored, put them all in one `create_screen` call's `screens` array with `autoConnect: false`.
 

package/stacks/modeling-kit/templates/.claude/skills/html-screen/SKILL.md

@@ -140,6 +140,7 @@ mcp__eventmodelers__create_screen {
     "nodeId": "<generated-uuid>",
     "chapterId": "<CHAPTER_ID>",
     "cellName": "<CELL_NAME>",
+    "title": "<Screen Title>",
     "pages": ["<div>...</div>"],
     "fields": [ /* optional — set meta.fields here too (see Step 5) instead of a separate call */ ]
   }]