@eventmodelers/cli 1.0.85 → 1.0.87

package/README.md

@@ -125,8 +125,8 @@ npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install
 npx @eventmodelers/cli init --stack <name> --demo   # same, plus a ready-made demo model in the kit's .slices/ to build against
 npx @eventmodelers/cli re-init                      # refresh an already-installed kit's scripts/skills only — never touches the root scaffold
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
-npx @eventmodelers/cli run --local-ai [target]      # same, via a local/self-hosted model (ralph-local-ai.js)
-npx @eventmodelers/cli run --exec "<command>"        # same, via an external agent harness (ralph-exec.js)
+npx @eventmodelers/cli run --local-ai [target]      # board work only via a local/self-hosted model (ralph-local-ai.js) — does NOT build slices; build locally with --exec
+npx @eventmodelers/cli run --exec "<command>"        # same, via an external agent harness (ralph-exec.js) — agent tracing needs its JSON flag, e.g. "codex exec --json --full-auto"
 npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
 npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
 npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude process driven by the board's prompt queue

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,14 +3184,17 @@ 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));
+      }
     }
   });
 
 credentialFlags(program
   .command('run')
   .description('Start the agent loop from the installed kit dir — build-kit stacks: ralph-claude.js (default); modeling-kit: --modeling, or --standalone, which needs no install at all')
-  .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner: a build kit runs it via ralph-local-ai.js, and --modeling/--standalone via lib/modeling-local-ai.js (board tools over MCP, but no skills and no subagent fan-out — those are Claude Code features). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Claude remains the default when this flag is absent.`)
-  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent.')
+  .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner: a build kit runs it via ralph-local-ai.js, and --modeling/--standalone via lib/modeling-local-ai.js (board tools over MCP, but no skills and no subagent fan-out — those are Claude Code features). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Board work only: --local-ai never builds a Planned slice (no file, shell or git tools). To build code with a local model, use --exec with a coding harness pointed at it, e.g. "codex exec --oss --full-auto". Claude remains the default when this flag is absent.`)
+  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent. With agent tracing on, include the harness\'s JSON output flag (codex exec --json, opencode run --format json, gemini --output-format stream-json) — without it no slice cost is recorded.')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
   .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
   .option('--non-interactive', 'Never ask anything: take the board and credentials that resolve from flags, EVENTMODELERS_* env vars and the config files, and fail with the reason if they are incomplete instead of interviewing for them. A TTY was previously the only signal — right for CI or a supervisor, wrong for a loop started from a terminal, where stdin is a TTY nobody is watching and the run stops on a question. Only affects the modeling loop (--modeling/--standalone/--global).')
@@ -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. A non-Claude agent via run --exec is only traced when its command includes the harness's JSON output flag, e.g. \"codex exec --json --full-auto\".")
   .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.87",
   "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/README.md

@@ -51,7 +51,7 @@ node .build-kit/ralph-claude.js /path/to/project
 **Phase 2** — triggered when any file in `.slices/` contains `"status": "Planned"`:
 - The loop runs Claude with `backend-prompt.md`
 - Claude implements the slice in the project
-- Phase 2 is Claude-only; local-AI mode skips it (local-ai-agent handles its own queue)
+- Phase 2 (building slices) never runs with `--local-ai` — see *`--local-ai` does not build code*. Build with `--exec` instead
 
 Both phases run in a continuous loop with a 3-second idle sleep. The realtime agent runs concurrently in the same process.
 
@@ -72,6 +72,34 @@ node .build-kit/realtime-agent.js
 `ralph-local-ai.js` drives any local or self-hosted model that can do tool calling.
 Claude (`ralph-claude.js`) stays the default runner — this is opt-in.
 
+### `--local-ai` does not build code
+
+**`--local-ai` works on the board only. It never builds a slice.** Planned slices stay
+Planned. That is by design, not a bug:
+
+- **Planned slices are never handed to it.** `ralph-local-ai.js` gives `startRalph` no
+  `onPlannedSlice`, so the loop only feeds it `tasks.json` prompts.
+- **It has no coding tools.** `lib/local-ai-agent.js` exposes only the board MCP tools:
+  no file read/write, no shell, no git, no test run.
+- **Its system prompt forbids file and shell access.** Such a request is answered with
+  `Blocked: …`.
+- **A prompt stops after 12 tool-call rounds.** That is enough for board edits, but far
+  short of a slice build.
+
+Here the kit is the agent loop and the model only picks tools. Building would mean
+rewriting a full coding agent inside the kit, so it is left out on purpose.
+
+**To build with a local model, use `--exec`** with a coding harness pointed at that model
+(see *External agent commands* below):
+
+```bash
+npx @eventmodelers/cli run --exec "codex exec --oss --json --full-auto"   # Codex on local Ollama
+npx @eventmodelers/cli run --exec "opencode run --auto --format json"     # OpenCode, with an Ollama/vLLM/LM Studio provider in its config
+```
+
+Or keep Claude Code as the builder and point `anthropicBaseUrl` at a local endpoint that
+speaks the Anthropic API.
+
 ```bash
 LOCAL_AI_TARGET=ollama          # preset: ollama | vllm | lmstudio | llamacpp
 LOCAL_AI_URL=http://host:8000/v1  # any OpenAI-compatible server (overrides the preset URL)
@@ -109,6 +137,20 @@ child runs with the project dir as its cwd and inherits stdio — a harness owns
 output format, so there is no condensed per-step logging here the way `ralph-claude.js`
 has it.
 
+**Agent tracing needs the harness's JSON output flag.** With agent tracing on
+(`eventmodelers config --agent-tracing on`), slice builds are costed just like with Claude —
+but only if the harness runs in its JSON output mode. Its normal output has no token counts,
+so without the flag a turn is not traced (the runner logs a hint). Add the flag yourself:
+
+```bash
+npx @eventmodelers/cli run --exec "codex exec --json --full-auto"
+npx @eventmodelers/cli run --exec "opencode run --auto --format json"
+npx @eventmodelers/cli run --exec "gemini --yolo --output-format stream-json -p"
+```
+
+The terminal then shows the raw JSON events. Only OpenCode reports a dollar cost; Codex and
+Gemini turns record tokens and duration with no cost. See `agent-tracking.md`.
+
 Persist a default alongside the local-AI settings:
 
 ```json

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,155 @@
+// 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,
+  };
+}
+
+/** One event from an external harness's JSON output (ralph-exec.js), or null if it carries no usage.
+ *  Matched on shape, not on the command name, so a wrapper script around a harness still counts:
+ *   - Codex `codex exec --json`: `turn.completed` with `usage` (input_tokens includes the cached ones)
+ *   - OpenCode `opencode run --format json`: `step_finish` per model step, with tokens and cost
+ *   - Gemini CLI `--output-format stream-json`: the final `result` with `stats`;
+ *     `--output-format json`: one object whose `stats.models` holds tokens per model
+ *  Only OpenCode reports a cost — the others leave costUsd null rather than guessing a price. */
+export function usageFromHarnessEvent(msg) {
+  if (msg?.type === 'turn.completed' && msg.usage) {
+    const u = msg.usage;
+    const cached = n(u.cached_input_tokens);
+    return { inputTokens: Math.max(0, n(u.input_tokens) - cached), outputTokens: n(u.output_tokens), cacheReadTokens: cached };
+  }
+  if (msg?.type === 'step_finish' && msg.part?.tokens) {
+    const t = msg.part.tokens;
+    return {
+      inputTokens: n(t.input),
+      outputTokens: n(t.output) + n(t.reasoning),
+      cacheReadTokens: n(t.cache?.read),
+      cacheWriteTokens: n(t.cache?.write),
+      costUsd: Number.isFinite(msg.part.cost) ? msg.part.cost : null,
+    };
+  }
+  if (msg?.type === 'result' && msg.stats && !('total_cost_usd' in msg)) {
+    const s = msg.stats;
+    return {
+      inputTokens: n(s.input_tokens),
+      outputTokens: n(s.output_tokens),
+      durationMs: Number.isFinite(s.duration_ms) ? s.duration_ms : null,
+    };
+  }
+  if (msg?.stats?.models && typeof msg.stats.models === 'object') {
+    const models = Object.entries(msg.stats.models);
+    const tok = (key) => models.reduce((sum, [, m]) => sum + n(m?.tokens?.[key]), 0);
+    const cached = tok('cached');
+    const [dominant] = models.sort((a, b) => n(b[1]?.tokens?.candidates) - n(a[1]?.tokens?.candidates))[0] ?? [];
+    return {
+      inputTokens: Math.max(0, tok('prompt') - cached),
+      outputTokens: tok('candidates') + tok('thoughts'),
+      cacheReadTokens: cached,
+      model: dominant ?? null,
+    };
+  }
+  return null;
+}
+
+/** Sums the usage of every event in one turn. A field no event reported stays null (cost, model)
+ *  or 0 (tokens), so a harness without a cost does not show up as a free turn. */
+export function sumUsage(parts) {
+  if (!parts.length) return null;
+  const add = (key) => parts.reduce((sum, p) => sum + n(p[key]), 0);
+  const costs = parts.map((p) => p.costUsd).filter(Number.isFinite);
+  return {
+    inputTokens: add('inputTokens'),
+    outputTokens: add('outputTokens'),
+    cacheReadTokens: add('cacheReadTokens'),
+    cacheWriteTokens: add('cacheWriteTokens'),
+    costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
+    durationMs: parts.findLast((p) => Number.isFinite(p.durationMs))?.durationMs ?? null,
+    model: parts.findLast((p) => p.model)?.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));
         }
       }
     });