@eventmodelers/cli 1.0.68 → 1.0.70

package/README.md

@@ -119,6 +119,7 @@ npx @eventmodelers/cli run --local                  # skip platform config/crede
 npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude process driven by the board's prompt queue
 npx @eventmodelers/cli run --standalone             # same, plus acting on board changes unprompted — and needs no install at all
 npx @eventmodelers/cli run --standalone --board-id <uuid>  # …from any directory, against any board (see Power users)
+npx @eventmodelers/cli run --id <id> --name <label>  # override this run's agent identity (id + display name); `init --name` persists a name instead
 npx @eventmodelers/cli fetch --context <name>                     # pull full slice detail for one context on the board into <kit-dir>/.slices/
 npx @eventmodelers/cli fetch --context <name> --slice-id <id>     # same, then print just that slice
 npx @eventmodelers/cli fetch --context <name> --slice-title <title> # same, then print just the slice matching this title
@@ -210,8 +211,10 @@ starting in one command. Resolution order for a run is `--credentials` and the i
 `--token`/`--organization-id`/`--board-id`/`--base-url` flags, then `EVENTMODELERS_*` env vars,
 then `~/.eventmodelers/boards/<board>.json`, then the usual `.eventmodelers/config.json` walk,
 and finally the account's default board. Whatever a run resolves is saved back to the
-per-board file (`0600`, in a `0700` directory) along with a stable agent id for the board's
-alive-ping. One machine can therefore drive several boards, across several accounts, at once.
+per-board file (`0600`, in a `0700` directory). The agent id is *not* stored there — a standalone
+run mints a fresh one each time, so two ad-hoc agents on one board stay two agents (see
+[Naming an agent](#naming-an-agent)). One machine can therefore drive several boards, across
+several accounts, at once.
 The global kit itself holds no credentials at all — the token reaches `claude` through the
 spawned process's environment.
 
@@ -395,8 +398,24 @@ npx @eventmodelers/cli init-config                      # interactive, writes to
 npx @eventmodelers/cli init-config --board-id <uuid>     # non-interactive, just overrides one field
 npx @eventmodelers/cli init-config --credentials "token=...,boardId=...,organizationId=...,baseUrl=..."  # configure ONE board (~/.eventmodelers/boards/<board>.json), no prompts
 npx @eventmodelers/cli init-config --credentials -        # same, read from stdin (keeps the token out of shell history)
+npx @eventmodelers/cli init-config --name ci-builder     # name the agent this config's runs identify as
 ```
 
+### Naming an agent
+
+Every agent identifies itself to the platform with an `agentId`, and the board's live-agent view shows that bare uuid. A **project install** mints one on first use and reuses it on every restart (`agentIds` in the project root's `.eventmodelers/config.json`). A **standalone/global run** mints a fresh one per run instead: nothing stops two ad-hoc agents running for one board, and since the heartbeat is keyed on `(token, agentId, agentType)`, a shared id would make the second agent replace the first — one agent visible however many are running, and their board writes indistinguishable.
+
+`--name` gives an agent a readable label instead of the uuid — accepted by `init`, `re-init`, and `init-config`, saved into `config.json` as `agentName`, and sent with every heartbeat from then on:
+
+```bash
+npx @eventmodelers/cli init --stack node --name ci-builder     # persisted for every later run of this kit
+npx @eventmodelers/cli init-config --name martins-laptop       # same, without re-installing
+npx @eventmodelers/cli run --name one-off-check                # override for a single run, nothing written
+npx @eventmodelers/cli run --id <id>                           # pin ONE identity across restarts
+```
+
+`run --id` is what you want when an agent has to keep the same identity every time it starts: a supervisor that already knows the id, a second agent of the same type in one *project* (which would otherwise share the project's single minted id), or an agent a board has starred as its **preferred agent** — that star addresses prompts to one id, so an agent whose id changes per run loses it on restart. `run --id`/`run --name` are per-run only: nothing is written to disk.
+
 ### Env vars and `--config` (scripted/CI installs)
 
 Every config field can be set via an `EVENTMODELERS_*` env var instead of the interactive prompts — these always win over whatever's in `config.json`, so a fully env-driven install never prompts for credentials or Claude execution settings:
@@ -410,6 +429,7 @@ Every config field can be set via an `EVENTMODELERS_*` env var instead of the in
 | `EVENTMODELERS_ANTHROPIC_BASE_URL` | `anthropicBaseUrl` |
 | `EVENTMODELERS_MODEL` | `model` |
 | `EVENTMODELERS_SUBAGENT_MODEL` | `subagentModel` |
+| `EVENTMODELERS_AGENT_NAME` | `agentName` |
 
 ```bash
 EVENTMODELERS_ORGANIZATION_ID=... EVENTMODELERS_BOARD_ID=... EVENTMODELERS_TOKEN=... \

package/cli.js

@@ -312,6 +312,7 @@ const ENV_CONFIG_MAP = {
   EVENTMODELERS_ANTHROPIC_BASE_URL: 'anthropicBaseUrl',
   EVENTMODELERS_MODEL: 'model',
   EVENTMODELERS_SUBAGENT_MODEL: 'subagentModel',
+  EVENTMODELERS_AGENT_NAME: 'agentName',
 };
 
 function applyEnvOverrides(config) {
@@ -586,6 +587,17 @@ function readJsonSafe(path) {
   }
 }
 
+// The `x-agent-id` header every platform call carries when this process knows its own id.
+// The heartbeat says an agent is alive; this says which of the calls arriving are its — the
+// platform stamps it on the board_events a write produces (so the board can show "alice moved
+// this" rather than one anonymous robot), and matches it when claiming a prompt the user
+// addressed to one preferred agent. Optional everywhere: an id-less caller behaves exactly as
+// callers did before it existed.
+function agentHeaders(cfg) {
+  const agentId = cfg?.agentId || process.env.EVENTMODELERS_AGENT_ID || '';
+  return agentId ? { 'x-agent-id': agentId } : {};
+}
+
 // Distinguishes this agent process from any other agent pinging the same
 // token/board — e.g. a build-kit and a modeling-kit install in the same project
 // share one root config.json, and without a per-agent id both would upsert the
@@ -1089,8 +1101,9 @@ async function installStack(stackKey, stackCfg, options = {}) {
 // 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,
-// --organization-id, --base-url) — the most explicit source available, so they
-// win over both the config file and env vars before we even check what's missing.
+// --organization-id, --base-url, plus --name as `agentName`) — the most explicit source
+// available, so they win over both the config file and env vars before we even check
+// what's missing. Any field is written through verbatim; only requiredFields gate the prompt.
 async function configureCredentials({ config, configPath, targetDir, requiredFields, boardIdOptional, overrides = {}, print, skipGitignore = false, force = false }) {
   config = { ...config };
   for (const [field, value] of Object.entries(overrides)) {
@@ -1377,7 +1390,7 @@ function ensureEnvToken(targetDir, token) {
 const GLOBAL_DIR = join(homedir(), '.eventmodelers');
 const GLOBAL_KIT_DIR = join(GLOBAL_DIR, 'kit');
 
-// One file per board: `{token, organizationId, boardId, baseUrl, agentId}`. Credentials
+// One file per board: `{token, organizationId, boardId, baseUrl}`. Credentials
 // ARE per board — a token is scoped to the org that owns it — so one machine can drive
 // several boards across several accounts at once, each with its own. Written 0600 in a
 // 0700 dir: unlike a project's .eventmodelers/config.json, there is no .gitignore standing
@@ -1395,16 +1408,21 @@ function boardCredentialsPath(boardId) {
 function writeBoardCredentials(config) {
   const path = boardCredentialsPath(config.boardId);
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  // agentName is stored, the agent id is not: the name is a label for whoever runs here (and
+  // this file is the only config a `run --standalone` from an arbitrary directory reads, so
+  // dropping it would lose `init-config --name` on the very next run), while the id is minted
+  // per run now — see resolveModelingCredentials for why.
+  const agentName = config.agentName ? { agentName: config.agentName } : {};
   const body = config.useBoard
     ? { boardId: config.boardId, useBoard: config.useBoard }
     : config.useGlobal
-    ? { boardId: config.boardId, useGlobal: true, agentId: config.agentId }
+    ? { boardId: config.boardId, useGlobal: true, ...agentName }
     : {
         token: config.token,
         organizationId: config.organizationId,
         boardId: config.boardId,
         baseUrl: config.baseUrl,
-        agentId: config.agentId,
+        ...agentName,
       };
   writeFileSync(path, JSON.stringify(body, null, 2), { mode: 0o600 });
 }
@@ -1586,12 +1604,18 @@ async function resolveModelingCredentials(cwd, flags, explicitConfigPath, print)
     process.exit(1);
   }
 
-  // Distinguishes this agent from any other pinging the same board, and has to stay stable
-  // across runs or the platform sees a brand-new agent on every restart. Per board, since
-  // that is the identity the alive-ping is scoped to.
-  config.agentId = stored.agentId || readJsonSafe(boardCredentialsPath(config.boardId)).agentId || randomUUID();
+  // A fresh identity for every standalone run, deliberately not persisted. A standalone agent
+  // is started ad hoc from wherever, and nothing stops two of them running for the same board —
+  // with one id stored per board they upserted the same alive row (the heartbeat is keyed on
+  // token + agent_id + agent_type), so the second agent replaced the first instead of joining
+  // it: the board showed one agent however many were running, and their writes were
+  // indistinguishable. A per-run uuid costs the identity its continuity across restarts (a
+  // restarted agent is a new row, and the old one lingers until its 45s window lapses) — pass
+  // `run --id <uuid>` when an agent needs to keep one identity, which is also what makes
+  // "preferred agent" on the board stick to it.
+  config.agentId = randomUUID();
   writeBoardCredentials(stored.useGlobal
-    ? { boardId: config.boardId, useGlobal: true, agentId: config.agentId }
+    ? { boardId: config.boardId, useGlobal: true, agentName: config.agentName }
     : config);
 
   return config;
@@ -1648,7 +1672,7 @@ async function ensureGlobalKit(baseUrl) {
 // question, sketch a screen. Without the flag that channel is still subscribed on
 // the same connection and every event on it is dropped, so the two modes differ by
 // one filter rather than by a whole second realtime stack.
-async function runModeling(kitDir, projectDir, verbose = false, standalone = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS) {
+async function runModeling(kitDir, projectDir, verbose = false, standalone = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS, identity = {}) {
   const configLibPath = join(kitDir, 'lib', 'config.js');
   if (!existsSync(configLibPath)) {
     console.error(`❌ ${relative(process.cwd(), configLibPath)} not found — --modeling needs a kit installed via \`init --modeling\`.`);
@@ -1670,12 +1694,18 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
   // ~/.eventmodelers/boards/<board>.json — one dir driving several boards must not have
   // them all upsert one shared alive row. A project install keeps its id in the project
   // root config, namespaced by agent type, as it always has.
-  if (!overrides) local.agentId = ensureAgentId(kitDir, 'MODELING');
+  // `run --id` overrides that for this run only — ensureAgentId is skipped rather than
+  // overwritten, so the project's own stable id stays on disk and the next run without the
+  // flag is the same agent the platform saw before.
+  if (!overrides) local.agentId = identity.agentId || ensureAgentId(kitDir, 'MODELING');
   if (!local.token || !local.organizationId) {
     console.error('❌ --modeling needs platform credentials in .eventmodelers/config.json (token + organizationId) — run `/connect` once or paste your config first.');
     process.exit(1);
   }
-  const cfg = { ...(await fetchPlatformConfig(local)), ...(overrides ?? {}) }; // adds realtimeProvider + its provider-specific fields (supabaseUrl/supabaseAnonKey or pocketbaseUrl), + boardId if the config has a default one
+  // The identity flags go on last: the global install's `overrides` carry the agent id
+  // resolveModelingCredentials just minted for this run, which would otherwise win back over
+  // an explicit --id.
+  const cfg = { ...(await fetchPlatformConfig(local)), ...(overrides ?? {}), ...(identity.agentId ? { agentId: identity.agentId } : {}), ...(identity.agentName ? { agentName: identity.agentName } : {}) }; // adds realtimeProvider + its provider-specific fields (supabaseUrl/supabaseAnonKey or pocketbaseUrl), + boardId if the config has a default one
   if (!cfg.boardId) {
     console.error('❌ --modeling needs a boardId — a modeling agent always runs for exactly one board. Run `/connect board=<uuid>` once, or add boardId to .eventmodelers/config.json.');
     process.exit(1);
@@ -1733,6 +1763,9 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     ...process.env,
     ...(cfg.anthropicBaseUrl ? { ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl } : {}),
     EVENTMODELERS_TOKEN: cfg.token,
+    // What the connect skill puts in `.mcp.json`'s x-agent-id header and every curl-fallback
+    // call, so the board work this agent does on the platform is attributed to this agent.
+    ...(cfg.agentId ? { EVENTMODELERS_AGENT_ID: cfg.agentId } : {}),
   };
 
   let proc = null;
@@ -1889,6 +1922,7 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
   }
 
   spawnProcess();
+  log(`agent: ${cfg.agentName ? `${cfg.agentName} (${cfg.agentId})` : cfg.agentId}`);
   log(
     standalone
       ? `standalone: ON — reacting to direct prompts AND to board changes on its own initiative (max ${maxAgents} subagent(s) per self-directed turn)`
@@ -1898,7 +1932,7 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
 
   async function getRealtimeToken() {
     const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/prompts/realtime-token`, {
-      headers: { 'x-token': cfg.token },
+      headers: { 'x-token': cfg.token, ...agentHeaders(cfg) },
     });
     if (!res.ok) throw new Error(`realtime-token: HTTP ${res.status}`);
     return (await res.json()).token;
@@ -1906,7 +1940,7 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
 
   async function fetchNextPrompt(jwtToken) {
     const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/prompts/next?board_id=${encodeURIComponent(cfg.boardId)}`, {
-      headers: { 'x-token': cfg.token, Authorization: `Bearer ${jwtToken}` },
+      headers: { 'x-token': cfg.token, Authorization: `Bearer ${jwtToken}`, ...agentHeaders(cfg) },
     });
     if (res.status === 404) return null;
     if (!res.ok) throw new Error(`prompts/next: HTTP ${res.status}`);
@@ -2279,7 +2313,7 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
       const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${realtimeToken}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: 'MODELING', agent_id: cfg.agentId }),
+        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: 'MODELING', agent_id: cfg.agentId, ...(cfg.agentName ? { agent_name: cfg.agentName } : {}) }),
         signal: AbortSignal.timeout(10_000),
       });
       if (!res.ok) log(`ping failed: ${res.status} ${await res.text().catch(() => '')}`);
@@ -2344,6 +2378,23 @@ function credentialOverridesFromOpts(opts) {
   return { token: opts.token, boardId: opts.boardId, organizationId: opts.organizationId, baseUrl: opts.baseUrl };
 }
 
+// `--name` is not a credential — it's the display name of the agent a kit runs, sent with
+// every heartbeat (POST /api/agent-alive's agent_name) so the board can show which agent is
+// live instead of a bare uuid. It belongs beside the credentials in config.json rather than
+// on every command line, so `init`/`re-init`/`init-config` persist it as `agentName` and
+// every later run of that kit's agent picks it up from the config walk (both runtimes merge
+// unknown config fields through verbatim). `run --name` is the per-run override on top, and
+// writes nothing.
+const AGENT_NAME_OPTION = [
+  '--name <name>',
+  'Human-readable name for the agent this kit runs (e.g. "ci-builder", "martins-laptop"), saved to config.json as `agentName` and sent with every heartbeat so the board shows a name instead of a bare uuid. Also settable via EVENTMODELERS_AGENT_NAME, and overridable for a single run with `run --name`.',
+];
+
+function identityOverridesFromOpts(opts) {
+  const agentName = typeof opts.name === 'string' ? opts.name.trim() : undefined;
+  return agentName ? { agentName } : {};
+}
+
 credentialFlags(program
   .command('init')
   .alias('install')
@@ -2358,7 +2409,8 @@ credentialFlags(program
   .option('--build-kit', 'Install a blank build-kit scaffold (.build-kit/ + .claude/skills/build-*/SKILL.md placeholders, all TODO-marked) for a stack not built into this CLI yet — no fixed backend. Mutually exclusive with --stack/--modeling/--bridge.')
   .option('--hooks', 'Install the slice commit-scope guard (.githooks/pre-commit, running .build-kit/lib/check-commit-scope.cjs) and wire it up via `git config core.hooksPath .githooks` — only meaningful with --stack (build-kit stacks). Off by default.')
   .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
-  .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json'))
+  .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json')
+  .option(...AGENT_NAME_OPTION))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
 
@@ -2376,7 +2428,7 @@ credentialFlags(program
         print: globalOpts.print,
         global: opts.global,
         force: opts.force,
-        credentialOverrides: credentialOverridesFromOpts(opts),
+        credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
       });
       return;
     }
@@ -2387,7 +2439,7 @@ credentialFlags(program
         print: globalOpts.print,
         global: opts.global,
         force: opts.force,
-        credentialOverrides: credentialOverridesFromOpts(opts),
+        credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
       });
       return;
     }
@@ -2406,7 +2458,7 @@ credentialFlags(program
         print: globalOpts.print,
         global: opts.global,
         force: opts.force,
-        credentialOverrides: credentialOverridesFromOpts(opts),
+        credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
         target: opts.target,
       });
       // Deliberately NOT under .bridge-kit/.eventmodelers/ — that whole name is
@@ -2444,7 +2496,7 @@ credentialFlags(program
         print: globalOpts.print,
         global: opts.global,
         force: opts.force,
-        credentialOverrides: credentialOverridesFromOpts(opts),
+        credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
         templatesSource: join(clonedDir, 'templates'),
         hooks: opts.hooks,
       });
@@ -2457,7 +2509,7 @@ credentialFlags(program
       print: globalOpts.print,
       global: opts.global,
       force: opts.force,
-      credentialOverrides: credentialOverridesFromOpts(opts),
+      credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
       hooks: opts.hooks,
     });
   });
@@ -2474,7 +2526,8 @@ credentialFlags(program
   .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('--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'))
+  .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json')
+  .option(...AGENT_NAME_OPTION))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
     const targetDir = process.cwd();
@@ -2512,7 +2565,7 @@ credentialFlags(program
       print: globalOpts.print,
       global: opts.global !== undefined ? opts.global : !!manifest.global,
       force: opts.force,
-      credentialOverrides: credentialOverridesFromOpts(opts),
+      credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
       skipRootScaffold: true,
       hooks: opts.hooks,
     });
@@ -2642,10 +2695,11 @@ credentialFlags(program
   .command('init-config')
   .description('Configure credentials only — writes .eventmodelers/config.json in the current directory, or ~/.eventmodelers/config.json with --global')
   .option('--global', 'Write account-wide defaults (organizationId + token only) to ~/.eventmodelers/config.json instead of the project')
-  .option('--credentials <values>', 'Credentials as the comma-separated blob from app.eventmodelers.ai/account (token=...,boardId=...,organizationId=...,baseUrl=...), the equivalent JSON, or - to read either from stdin. When the blob names a board it configures THAT board (~/.eventmodelers/boards/<board>.json), which is all a later run --standalone --board-id <uuid> then needs.'))
+  .option('--credentials <values>', 'Credentials as the comma-separated blob from app.eventmodelers.ai/account (token=...,boardId=...,organizationId=...,baseUrl=...), the equivalent JSON, or - to read either from stdin. When the blob names a board it configures THAT board (~/.eventmodelers/boards/<board>.json), which is all a later run --standalone --board-id <uuid> then needs.')
+  .option(...AGENT_NAME_OPTION))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
-    const overrides = credentialOverridesFromOpts(opts);
+    const overrides = { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) };
 
     // A blob naming a board configures that board's own file rather than a project or
     // account-wide config: the per-board store is keyed by board id, and the blob is
@@ -2662,9 +2716,6 @@ credentialFlags(program
         process.exit(1);
       }
       if (!parsed.baseUrl) parsed.baseUrl = DEFAULT_BASE_URL;
-      // Preserved across re-configuration: the platform keys a board's alive-ping on it, so
-      // regenerating it would present a long-running agent as a brand-new one.
-      parsed.agentId = readJsonSafe(boardCredentialsPath(parsed.boardId)).agentId || randomUUID();
       writeBoardCredentials(parsed);
       console.log('\n  ✓ Saved credentials for board ' + parsed.boardId + ' to ' + boardCredentialsPath(parsed.boardId));
       console.log('\n  Start the agent from anywhere with:\n');
@@ -2688,6 +2739,11 @@ credentialFlags(program
       if (pasted.token) base.token = pasted.token;
       if (overrides.organizationId) base.organizationId = overrides.organizationId;
       if (overrides.token) base.token = overrides.token;
+      // Carried through the same narrowing: this branch rebuilds the file from scratch, so
+      // an already-configured agentName has to be read back in or a later `init-config
+      // --global` (e.g. rotating the token) would silently drop it.
+      if (existing.agentName) base.agentName = existing.agentName;
+      if (overrides.agentName) base.agentName = overrides.agentName;
 
       const configured = await configureCredentials({
         config: base,
@@ -2708,7 +2764,9 @@ credentialFlags(program
       // configureCredentials' generic paste/manual flow may have picked up
       // boardId/baseUrl too (e.g. from a pasted JSON blob) — strip them back out
       // before the final write, since --global only ever persists identity.
-      writeFileSync(configPath, JSON.stringify({ organizationId: configured.organizationId, token: configured.token }, null, 2));
+      // --name is the one non-credential that belongs here: it names the agent, not the
+      // project, so an account-wide default is as portable as the org/token beside it.
+      writeFileSync(configPath, JSON.stringify({ organizationId: configured.organizationId, token: configured.token, ...(configured.agentName ? { agentName: configured.agentName } : {}) }, null, 2));
       console.log(`\n  ✓ Saved account-wide defaults to ${configPath}`);
     } else {
       const targetDir = process.cwd();
@@ -2724,7 +2782,11 @@ credentialFlags(program
         boardIdOptional: true,
         overrides,
         print: globalOpts.print,
-        force: true,
+        // Same reasoning as the --global branch above: a bare `init-config` means "re-ask
+        // me", but an invocation that already carries its answers on the command line —
+        // credentials, or just a --name to record — must not stop to prompt, or every
+        // non-interactive caller hangs (a closed stdin crashes outright).
+        force: !Object.values(overrides).some(Boolean),
       });
 
       // Keep `.mcp.json` in sync — this command can change `baseUrl` (e.g.
@@ -2747,6 +2809,8 @@ credentialFlags(program
   .option('--global', 'Run the modeling agent from the global install (~/.eventmodelers/kit), initializing it on first use, and ignore any kit in this directory. This is also what --modeling/--standalone fall back to on their own when nothing is installed here — pass it explicitly to prefer the global install over a local one. Credentials come from the flags below, EVENTMODELERS_* env vars, or ~/.eventmodelers/boards/<board>.json, so nothing is written into the current directory.')
   .option('--local', 'Skip platform config/credential lookup entirely and run the local-only loop (no board sync, no realtime agent) — even if .eventmodelers/config.json has credentials (build-kit stacks only)')
   .option('--verbose', 'Log every tool call\'s full input (commands, skill args, file paths) and assistant reasoning text. Default is condensed, high-level per-step logging only.')
+  .option('--id <id>', 'Pin the agent id this run identifies itself with on the platform. A project install otherwise mints one id per project and reuses it on every restart; --global/--standalone mints a fresh one per run, since two ad-hoc agents for one board must not share a row (the heartbeat is keyed on token + agent_id + agent_type, so the second would replace the first). Pass this when an agent has to keep ONE identity across restarts — a supervisor that already knows the id, or a board where it is the starred "preferred agent". Per-run only: nothing is written to disk.')
+  .option('--name <name>', 'A human-readable name for this agent, sent with every heartbeat so the board shows which agent is live rather than a bare uuid (e.g. "ci-builder", "martins-laptop"). Per-run only, like --id: the persistent name is `agentName` in config.json (set via `init --name` / `init-config --name`), and this overrides it for one run without writing anything.')
   .option('--credentials <values>', 'Credentials as the comma-separated blob from app.eventmodelers.ai/account (token=...,boardId=...,organizationId=...,baseUrl=...), the equivalent JSON, or - to read either from stdin. Saved to ~/.eventmodelers/boards/<board>.json, so it is only needed once per board, and passing it skips the first-run question. The individual flags below override single fields of it.'))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
@@ -2758,6 +2822,23 @@ credentialFlags(program
     if (command.getOptionValueSource('maxAgents') === 'cli' && !opts.standalone) {
       console.log('ℹ️  --max-agents only applies to --standalone turns; ignoring it here.');
     }
+    // --id/--name are what the platform will see for this run, so a blank one is a
+    // mistake worth failing on rather than silently falling back to the stored identity.
+    const identity = {
+      agentId: opts.id === undefined ? null : String(opts.id).trim(),
+      agentName: opts.name === undefined ? null : String(opts.name).trim(),
+    };
+    for (const [flag, value] of [['--id', identity.agentId], ['--name', identity.agentName]]) {
+      if (value === '') {
+        console.error(`❌ ${flag} needs a non-empty value.`);
+        process.exit(1);
+      }
+    }
+    // ralph.sh has no realtime agent and never pings /api/agent-alive, so there is no
+    // identity for either flag to override there.
+    if ((identity.agentId || identity.agentName) && opts.bash) {
+      console.log('ℹ️  --id/--name only apply to agents that ping the platform; the --bash loop does not, so they are ignored here.');
+    }
     // Both kit dirs can be installed side by side (e.g. running a build-kit and a
     // modeling-kit agent from the same project). findInstalledKitDir only ever
     // returns its first fixed-order match, which would silently prefer one stack
@@ -2821,7 +2902,7 @@ credentialFlags(program
       const shown = relative(cwd, kitDir);
       await new Promise((res) => process.stdout.write(`▶ Starting modeling loop (warm Claude process) for ${shown && !shown.startsWith('..') ? shown : kitDir}...\n\n`, res));
       try {
-        await runModeling(kitDir, projectDir, !!opts.verbose, !!opts.standalone, overrides, maxAgents);
+        await runModeling(kitDir, projectDir, !!opts.verbose, !!opts.standalone, overrides, maxAgents, identity);
       } catch (err) {
         console.error('[modeling] Fatal:', err);
         process.exit(1);
@@ -2866,7 +2947,9 @@ credentialFlags(program
       // their own separate output paths with no stream-json parsing to gate. RALPH_LOCAL is
       // read by all three runners (ralph.js's startRalph, and ralph.sh directly) to force the
       // local-only branch even when .eventmodelers/config.json has valid credentials.
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '' } });
+      // RALPH_AGENT_ID/RALPH_AGENT_NAME (--id/--name) are read in ralph.js's startRalph, so
+      // they reach both node runners but not ralph.sh, which has no heartbeat to identify.
+      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '' } });
     } catch (err) {
       process.exit(err.status || 1);
     }
@@ -3180,6 +3263,7 @@ program
           'x-token': cfg.token,
           'x-board-id': cfg.boardId,
           'x-user-id': 'cli-set-slice-status',
+          ...agentHeaders(cfg),
         },
         body: JSON.stringify([{
           id: randomUUID(),

package/lib/adapters/spec-kitty-adapter.js

@@ -48,8 +48,12 @@ function slugify(text) {
 async function fetchFullSliceData(cfg, contextName) {
   const baseUrl = cfg.baseUrl || DEFAULT_BASE_URL;
   const url = `${baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata?contextName=${encodeURIComponent(contextName)}`;
+  const agentId = cfg.agentId || process.env.EVENTMODELERS_AGENT_ID || '';
   const res = await fetch(url, {
-    headers: { 'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'spec-kitty-adapter' },
+    headers: {
+      'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'spec-kitty-adapter',
+      ...(agentId ? { 'x-agent-id': agentId } : {}),
+    },
   });
   if (!res.ok) throw new Error(`slicedata fetch failed for context "${contextName}": HTTP ${res.status}`);
   return res.json();

package/lib/fetch.js

@@ -72,7 +72,13 @@ function sliceFolderName(title) {
 // { cwd, kitDir, cfg: { token, organizationId, boardId, baseUrl }, opts: { context, sliceId?, sliceTitle? } }
 export async function runFetch({ cwd, kitDir, cfg, opts = {} }) {
   const baseUrl = cfg.baseUrl || DEFAULT_BASE_URL;
-  const headers = { 'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'cli-fetch' };
+  // x-agent-id when we know it (see cli.js's agentHeaders) — a read doesn't write anything, but
+  // sending it everywhere keeps one rule instead of a per-call judgment about which calls count.
+  const agentId = cfg.agentId || process.env.EVENTMODELERS_AGENT_ID || '';
+  const headers = {
+    'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'cli-fetch',
+    ...(agentId ? { 'x-agent-id': agentId } : {}),
+  };
 
   // assertBoardAccess (the guard every one of these routes runs behind) only ever
   // answers 401/403 for credential/board-access problems — a 404 here always means

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.68",
+  "version": "1.0.70",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

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

@@ -148,9 +148,18 @@ function ensureAgentId(kitDir, agentType) {
   return agentId;
 }
 
+// `x-agent-id` on every platform call this loop makes, when it knows its own agent id (see
+// ensureAgentId above / RALPH_AGENT_ID). The heartbeat says this agent is alive; the header says
+// which calls are its, so its board writes are attributed to it and a prompt the user addressed
+// to one preferred agent is only ever claimed by that agent.
+function agentHeaders(cfg) {
+  const agentId = cfg?.agentId || process.env.RALPH_AGENT_ID || process.env.EVENTMODELERS_AGENT_ID || '';
+  return agentId ? { 'x-agent-id': agentId } : {};
+}
+
 async function fetchPlatformConfig(local) {
   const remote = await fetchJSON(`${local.baseUrl}/api/config`, {
-    headers: { 'x-token': local.token },
+    headers: { 'x-token': local.token, ...agentHeaders(local) },
   });
   return { ...local, ...remote };
 }
@@ -160,7 +169,7 @@ async function fetchPlatformConfig(local) {
 async function getRealtimeToken(cfg) {
   const { token } = await fetchJSON(
     `${cfg.baseUrl}/api/org/${cfg.organizationId}/prompts/realtime-token`,
-    { headers: { 'x-token': cfg.token } },
+    { headers: { 'x-token': cfg.token, ...agentHeaders(cfg) } },
   );
   return token;
 }
@@ -172,7 +181,7 @@ function slugify(str) {
 async function fetchAndPersistSlices(cfg, kitDir) {
   const url = `${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata/slices`;
   const { slices } = await fetchJSON(url, {
-    headers: { 'x-token': cfg.token, 'x-board-id': cfg.boardId },
+    headers: { 'x-token': cfg.token, 'x-board-id': cfg.boardId, ...agentHeaders(cfg) },
   });
   const slicesDir = join(kitDir, '.slices');
   mkdirSync(slicesDir, { recursive: true });
@@ -367,7 +376,7 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
       const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${realtimeToken}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: agentType, agent_id: cfg.agentId }),
+        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: agentType, agent_id: cfg.agentId, ...(cfg.agentName ? { agent_name: cfg.agentName } : {}) }),
         signal: AbortSignal.timeout(10_000),
       });
       if (!res.ok) {
@@ -489,7 +498,7 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
     try {
       await fetchJSON(`${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/nodes/events`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'ralph-loop' },
+        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'ralph-loop', ...agentHeaders(cfg) },
         body: JSON.stringify([{
           id: randomUUID(),
           eventType: 'node:changed',
@@ -583,10 +592,17 @@ export { loadLocalConfig, fetchPlatformConfig, retryOn401, startRealtimeAgent };
 
 export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, agentType = 'BUILD', queueAllStatuses = false, localOnly = false }) {
   const local = loadLocalConfig(kitDir);
-  local.agentId = ensureAgentId(kitDir, agentType);
+  // 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;
 
   console.log(`Ralph — kit: ${kitDir}`);
   console.log(`         project: ${projectDir}`);
+  console.log(`         agent: ${local.agentName ? `${local.agentName} (${local.agentId})` : local.agentId}`);
 
   // localOnly (set via `eventmodelers run --local`) forces this branch even when
   // credentials are present — it skips fetchPlatformConfig's network call to

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

@@ -31,6 +31,9 @@ const claudeEnv = {
   ...process.env,
   ...(cfg.anthropicBaseUrl ? { ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl } : {}),
   ...(cfg.token ? { EVENTMODELERS_TOKEN: cfg.token } : {}),
+  // Lets the skills this agent runs send x-agent-id on their own calls (connect puts it in
+  // `.mcp.json` and in every curl fallback), so their board writes are attributed to this agent.
+  ...(cfg.agentId ? { EVENTMODELERS_AGENT_ID: cfg.agentId } : {}),
 };
 
 // Collapses whitespace/newlines to a single line and truncates past `max` chars — a long

package/shared/skills/connect/SKILL.md

@@ -9,7 +9,7 @@ description: Resolve eventmodelers connection config (token, boardId, baseUrl) f
 
 **This should happen once per session, not once per skill.** If `TOKEN`/`BOARD_ID`/`ORG_ID`/`BASE_URL` are already resolved and verified from earlier in the current session — including earlier in the *same turn*, e.g. one skill internally invoking a second skill (`add-next-slice` → `html-screen`) — every subsequent "invoke `connect`" instruction is satisfied immediately by reusing those values. Do not re-run Steps 0–4 below. Only re-run this skill from scratch when a value actually needs to change: a fresh `401`/`403`/access-denied response from some other call, a different `board_id` on this turn, or a new inline param that overrides what's already resolved.
 
-**Subagents are a fresh session — hand them the resolved values.** When you spawn a subagent to do board work, put the already-resolved credentials inline in its prompt (`token=… board=… org=… baseUrl=…`). Its `connect` then satisfies everything at Step 0 and skips Steps 1–4 entirely: no config-file walk, no MCP re-registration, no verify call. Spawning three subagents without passing them down means paying the whole resolve-and-verify round three more times for values you already have.
+**Subagents are a fresh session — hand them the resolved values.** When you spawn a subagent to do board work, put the already-resolved credentials inline in its prompt (`token=… board=… org=… baseUrl=…`, plus `agent=…` when you have an `AGENT_ID` — a subagent's writes are still this agent's writes, and it cannot read your environment). Its `connect` then satisfies everything at Step 0 and skips Steps 1–4 entirely: no config-file walk, no MCP re-registration, no verify call. Spawning three subagents without passing them down means paying the whole resolve-and-verify round three more times for values you already have.
 
 This skill also registers the **eventmodelers MCP server** for the project (Step 3.5) so other skills can call MCP tools (`mcp__eventmodelers__*`) instead of raw curl. MCP is the preferred transport; curl remains a fallback for hosts without MCP support, or for the one or two endpoints (documented in `learn-eventmodelers-api`) the MCP server doesn't expose.
 
@@ -25,17 +25,24 @@ After running, the following variables are available for the rest of the session
 | `BOARD_ID` | `x-board-id` | Target board UUID |
 | `ORG_ID` | — | Organization UUID (used in all board-scoped URLs) |
 | `BASE_URL` | — | Base URL, e.g. `http://localhost:3000` |
+| `AGENT_ID` | `x-agent-id` | This agent process's own id, when running as one (Step 0.5). Optional — skip the header when there is no value. |
 
 Every curl-fallback call in every skill must include these headers:
 ```
 x-token: <TOKEN>
 x-board-id: <BOARD_ID>
 x-user-id: <skill-name>   ← set by each skill individually
+x-agent-id: <AGENT_ID>    ← only when AGENT_ID resolved; omit the line entirely otherwise
 ```
 
+`x-agent-id` is what makes the board say *which* agent did something: the platform stamps it on
+every change the call writes, so the canvas shows this agent by name (rather than one anonymous
+robot standing in for every agent at once), and a prompt a user addressed to one preferred agent
+is only handed to the agent that claims it with that id.
+
 All board-scoped URLs follow the pattern: `<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/...`
 
-When calling MCP tools instead, no `x-*` headers are needed — the MCP server resolves `ORG_ID` from `TOKEN` itself and every tool takes `boardId` as an explicit argument. See `learn-eventmodelers-api` for the full tool catalog.
+When calling MCP tools instead, no `x-*` headers are needed per call — the MCP server resolves `ORG_ID` from `TOKEN` itself and every tool takes `boardId` as an explicit argument. (`x-agent-id` rides along with the registered server config from Step 3.5, so MCP writes are attributed too.) See `learn-eventmodelers-api` for the full tool catalog.
 
 ---
 
@@ -49,13 +56,38 @@ Before reading the config file, scan the prompt/arguments that invoked this skil
 | `token=<uuid>` | `token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
 | `org=<uuid>` | `org=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
 | `baseUrl=<url>` | `baseUrl=http://localhost:3000` |
+| `agent=<uuid>` | `agent=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (the agent id a parent agent hands a subagent, so the subagent's board writes are attributed to the same agent) |
+
+If an inline `board=<uuid>` is found, use it as `BOARD_ID` — **it takes priority over the config file**. Same for `token`, `org`, `baseUrl`, and `agent` (as `AGENT_ID`, which then makes Step 0.5 a no-op). Record which values came from inline params so they are not overwritten in Step 3.
 
-If an inline `board=<uuid>` is found, use it as `BOARD_ID` — **it takes priority over the config file**. Same for `token`, `org`, and `baseUrl`. Record which values came from inline params so they are not overwritten in Step 3.
+(`agent=<uuid>` is not one of the four required values — it is optional, and its absence never makes this skill ask anything.)
 
 **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.
 
 ---
 
+## Step 0.5 — Resolve `AGENT_ID` (agents only)
+
+Optional, and only ever relevant when this session *is* an agent's session (`eventmodelers run`
+spawned it). Resolve in this order and stop at the first hit:
+
+1. `$EVENTMODELERS_AGENT_ID` — the CLI exports it for the agent it runs. This is the normal case.
+2. `agentIds.MODELING` (or `agentIds.BUILD` for a build kit) in the project root's
+   `.eventmodelers/config.json` — the id the CLI minted once for this project and reuses on every
+   restart.
+
+If neither exists, there is no `AGENT_ID`: this is a human's session, not an agent's. Leave it
+unset and omit the `x-agent-id` header everywhere. Never invent one, and never reuse another
+agent's id — the id is what the board attributes work to.
+
+```bash
+agent_id="${EVENTMODELERS_AGENT_ID:-}"
+[ -z "$agent_id" ] && [ -n "$config_file" ] && agent_id="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("agentIds",{}).get("MODELING",""))' "$config_file" 2>/dev/null)"
+echo "${agent_id:-<none>}"
+```
+
+---
+
 ## Step 1 — Read config file
 
 Search for `.eventmodelers/config.json` starting from the current working directory and walking up through all parent directories. This is the same file every kit installed in this project reads and writes, so credentials only need to be entered once per project:
@@ -164,17 +196,25 @@ The eventmodelers backend exposes the same board capabilities as an MCP server a
        "eventmodelers": {
          "type": "http",
          "url": "<BASE_URL>/mcp",
-         "headers": { "x-token": "${EVENTMODELERS_TOKEN}" }
+         "headers": { "x-token": "${EVENTMODELERS_TOKEN}", "x-agent-id": "${EVENTMODELERS_AGENT_ID}" }
        }
      }
    }
    ```
+   Keep the `x-agent-id` line in even when this session has no `AGENT_ID`: an unset variable
+   reaches the server as the literal `${EVENTMODELERS_AGENT_ID}` text, which it ignores (it only
+   accepts a uuid), so the entry is the same for a human session and an agent's. Writing one
+   `.mcp.json` for both is what keeps a second agent from inheriting the first one's id.
 3. Read the existing `.claude/settings.local.json` if present and merge in — never clobber `permissions`/`enabledMcpjsonServers` or anything else already there. Ensure it has `EVENTMODELERS_TOKEN` set under `env` (create the file with just this key if it doesn't exist yet):
    ```json
    {
      "env": { "EVENTMODELERS_TOKEN": "<TOKEN>" }
    }
    ```
+   Do **not** write `EVENTMODELERS_AGENT_ID` into this file. It is per running agent process, not
+   per project: the CLI exports it for the agent it spawns, and a value frozen into a shared
+   settings file would hand every session — including a second agent and the user's own — the
+   same agent identity.
    A plain `.env` file does **not** work here — Claude Code never sources one, so a `${EVENTMODELERS_TOKEN}` placeholder in `.mcp.json` would be left unexpanded (sent as the literal `${EVENTMODELERS_TOKEN}` text), which fails auth and pushes the client into an OAuth flow the eventmodelers server can't satisfy for this client. `.claude/settings.local.json`'s `env` block — alongside the inherited shell environment — is the only thing Claude Code actually resolves `.mcp.json` placeholders against.
 4. Ensure `.claude/settings.local.json` is listed in `.gitignore` (same check-then-append pattern as Step 3 uses for `.eventmodelers/config.json`) — it now holds the same secret and must never be committed. (Gitignored by Claude Code's own convention already, but don't rely on that silently.)
 

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

@@ -90,6 +90,7 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 |---|---|---|
 | `Authorization` | Some routes | Supabase JWT bearer token |
 | `x-user-id` | Node operations | User identifier |
+| `x-agent-id` | Optional | The agent process making the call — the uuid it also sends as `agent_id` on its heartbeat (`$EVENTMODELERS_AGENT_ID`, resolved by the `connect` skill). Stored on the `board_events` rows a write produces and broadcast with them, so the board shows *which* agent touched an element instead of one anonymous agent for all of them, and it decides who may claim a prompt addressed to a preferred agent. Send it on every call; a value that isn't uuid-shaped is ignored. |
 | `x-causation-id` | Optional | Event causation tracing |
 | `x-correlation-id` | Optional | Correlation tracing |
 
@@ -324,6 +325,8 @@ The node's content lives in `meta.description` (a plain string of markdown sourc
 
 All node endpoints require header: `x-user-id`
 
+Also send `x-agent-id` (`$EVENTMODELERS_AGENT_ID`) on every write — that is what attributes the change to this agent by name on the board. See **Authentication & Headers** above.
+
 ### POST `/api/org/:orgId/boards/:boardId/nodes/events`
 Submit node change events.
 
@@ -855,6 +858,8 @@ element was selected) plus the `focusArea`, and nothing else.
 ### GET `/api/org/:orgId/prompts/next`
 Claim the next pending (`ADDED`) prompt for a board — atomically flips it to `CLAIMED` and returns it. This is what a running modeling agent's warm loop polls. Auth: `x-token` **and** a Supabase JWT (`Authorization: Bearer`) together.
 
+Send `x-agent-id` here too: a prompt the user addressed to one preferred agent (`prompts.agent_id`) is only ever handed to the agent claiming with that id, and a caller without the header claims untargeted prompts only. Addressing one is `POST /api/org/:orgId/prompts` with `agent_id: "<uuid>"` — the board's prompts panel does it when someone stars an agent.
+
 **Query params**: `board_id` (required)
 **Response**: `200` — the claimed row (now `status: "CLAIMED"`), including its parsed `context` and the `hidden` flag · `404` — no `ADDED` prompts available
 
@@ -902,16 +907,20 @@ Exchange an `x-token` for a short-lived Supabase-compatible JWT, used to subscri
 ### POST `/api/agent-alive`
 Record a heartbeat ping for a running modeling/build agent. Auth: Supabase JWT (`Authorization: Bearer`) — exchange the `x-token` for one first via `GET /api/org/:orgId/prompts/realtime-token` above; a raw `x-token` alone is not accepted here.
 
-**Body**: `{ token: string, board_id?: string, agent_type: 'MODELING' | 'BUILD', agent_id: string }`
+**Body**: `{ token: string, board_id?: string, agent_type: 'MODELING' | 'BUILD', agent_id: string, agent_name?: string }`
 **Response**: `200` — `{ ok: true }`
 **Errors**: `400` `agent_id`/`agent_type` missing · `404` token not found
 
+`agent_id` is the client's own stable id (the heartbeat is keyed on `token` + `agent_id` + `agent_type`); `agent_name` is an optional display name for it, so the board can show which agent is live instead of a bare uuid. Both are overridable per run via `eventmodelers run --id/--name`.
+
+The same `agent_id` belongs in the `x-agent-id` header of every board call this agent makes: the heartbeat says the agent is alive, the header says which of the incoming calls are its. Without it a write is attributed to "some agent", every live agent shares one presence identity on the board, and prompts addressed to a preferred agent are never claimed.
+
 ---
 
 ### GET `/api/org/:orgId/boards/:boardId/agent-alive`
 Check whether an agent has pinged for a board within the last 45s. Auth: `x-token` (bot) or a Supabase JWT (`Authorization: Bearer`) — either works.
 
-**Response**: `200` — `{ alive: boolean, agentTypes: string[] }`
+**Response**: `200` — `{ alive: boolean, agentTypes: string[], agents: { agentId: string, agentType: string, agentName: string | null }[] }` — one `agents` entry per live agent process, `agentTypes` the de-duplicated set of their types
 
 ---
 

package/stacks/modeling-kit/templates/kit/lib/config.js

@@ -89,7 +89,8 @@ function hasCredentials(cfg) {
 
 async function fetchPlatformConfig(local) {
   const remote = await fetchJSON(`${local.baseUrl}/api/config`, {
-    headers: { 'x-token': local.token },
+    // x-agent-id when this install knows its agent id — see the CLI's agentHeaders.
+    headers: { 'x-token': local.token, ...(local.agentId || process.env.EVENTMODELERS_AGENT_ID ? { 'x-agent-id': local.agentId || process.env.EVENTMODELERS_AGENT_ID } : {}) },
   });
   return { ...local, ...remote };
 }

package/stacks/react/templates/build-kit/lib/ralph.js

@@ -153,9 +153,18 @@ function ensureAgentId(kitDir, agentType) {
   return agentId;
 }
 
+// `x-agent-id` on every platform call this loop makes, when it knows its own agent id (see
+// ensureAgentId above / RALPH_AGENT_ID). The heartbeat says this agent is alive; the header says
+// which calls are its, so its board writes are attributed to it and a prompt the user addressed
+// to one preferred agent is only ever claimed by that agent.
+function agentHeaders(cfg) {
+  const agentId = cfg?.agentId || process.env.RALPH_AGENT_ID || process.env.EVENTMODELERS_AGENT_ID || '';
+  return agentId ? { 'x-agent-id': agentId } : {};
+}
+
 async function fetchPlatformConfig(local) {
   const remote = await fetchJSON(`${local.baseUrl}/api/config`, {
-    headers: { 'x-token': local.token },
+    headers: { 'x-token': local.token, ...agentHeaders(local) },
   });
   return { ...local, ...remote };
 }
@@ -169,7 +178,7 @@ function slugify(str) {
 async function fetchAndPersistSlices(cfg, kitDir) {
   const url = `${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata/slices`;
   const { slices } = await fetchJSON(url, {
-    headers: { 'x-token': cfg.token, 'x-board-id': cfg.boardId },
+    headers: { 'x-token': cfg.token, 'x-board-id': cfg.boardId, ...agentHeaders(cfg) },
   });
   const slicesDir = join(kitDir, '.slices');
   mkdirSync(slicesDir, { recursive: true });
@@ -391,7 +400,7 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
     try {
       await fetchJSON(`${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/nodes/events`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'ralph-loop' },
+        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'ralph-loop', ...agentHeaders(cfg) },
         body: JSON.stringify([{
           id: randomUUID(),
           eventType: 'node:changed',