@netmind/arena-cli 0.4.0 → 0.5.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command14 } from "commander";
+import { Command as Command18 } from "commander";
 
 // src/diag.ts
 import { appendFileSync } from "fs";
@@ -171,6 +171,12 @@ function loadConfig() {
     return { api_url: DEFAULT_API_URL };
   }
 }
+function saveConfig(config) {
+  ensureConfigDir();
+  const existing = loadConfig();
+  const merged = { ...existing, ...config };
+  writeFileSync(getConfigFile(), JSON.stringify(merged, null, 2) + "\n");
+}
 function getApiUrl() {
   return process.env.ARENA_API_URL || loadConfig().api_url;
 }
@@ -382,6 +388,131 @@ var profileCmd = new Command3("profile").description("Show your agent profile an
 
 // src/commands/competitions.ts
 import { Command as Command4 } from "commander";
+
+// src/recap/storage.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, renameSync } from "fs";
+import { join as join2 } from "path";
+import lockfile from "proper-lockfile";
+
+// src/recap/constants.ts
+var RECAP_SCHEMA_VERSION = 1;
+var MAX_RECENT_EVENTS = 30;
+var MAX_MOOD_HISTORY = 30;
+var MAX_REASON_CHARS = 200;
+var MAX_RECAP_PROMPT_BYTES = 2048;
+var EVENTS_IN_PROMPT_HEAD = 10;
+var CAREER_STATS_TTL_MS = 10 * 60 * 1e3;
+var STATS_WARN_BYTES = 15 * 1024;
+var STATS_ALERT_BYTES = 30 * 1024;
+
+// src/recap/storage.ts
+function recapPath() {
+  return join2(getConfigDir(), "recap.json");
+}
+function ensureDir() {
+  const dir = getConfigDir();
+  if (!existsSync2(dir)) mkdirSync2(dir, { recursive: true });
+}
+function defaultRecapFile() {
+  return { version: RECAP_SCHEMA_VERSION, agents: {} };
+}
+function ensureFile() {
+  ensureDir();
+  const p = recapPath();
+  try {
+    writeFileSync2(p, JSON.stringify(defaultRecapFile(), null, 2) + "\n", {
+      flag: "wx",
+      mode: 384
+    });
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+}
+function readFileOrDefault() {
+  const p = recapPath();
+  if (!existsSync2(p)) return defaultRecapFile();
+  try {
+    const parsed = JSON.parse(readFileSync2(p, "utf-8"));
+    if (typeof parsed !== "object" || parsed === null) throw new Error("not an object");
+    return {
+      version: typeof parsed.version === "number" ? parsed.version : RECAP_SCHEMA_VERSION,
+      agents: typeof parsed.agents === "object" && parsed.agents !== null ? parsed.agents : {}
+    };
+  } catch {
+    try {
+      renameSync(p, `${p}.corrupt-${Date.now()}`);
+    } catch {
+    }
+    return defaultRecapFile();
+  }
+}
+function writeFileLocked(file) {
+  ensureDir();
+  writeFileSync2(recapPath(), JSON.stringify(file, null, 2) + "\n", { mode: 384 });
+}
+async function withLock(fn) {
+  ensureFile();
+  const p = recapPath();
+  let release = null;
+  try {
+    release = await lockfile.lock(p, {
+      retries: { retries: 5, minTimeout: 50, maxTimeout: 200 }
+    });
+    return fn();
+  } finally {
+    if (release) await release();
+  }
+}
+async function readRecap() {
+  return withLock(() => readFileOrDefault());
+}
+async function updateRecap(mutator) {
+  return withLock(() => {
+    const current = readFileOrDefault();
+    const next = mutator(current);
+    if (next) writeFileLocked(next);
+  });
+}
+
+// src/recap/schema.ts
+var MOODS = ["hyped", "steady", "bummed", "cocky", "restless"];
+function defaultAgentRecap(now) {
+  return {
+    first_seen_at: now.toISOString(),
+    recent_events: [],
+    mood_history: [],
+    cached_career_stats: null,
+    last_promo_at: null,
+    operator_hint: null
+  };
+}
+function isMood(v) {
+  return typeof v === "string" && MOODS.includes(v);
+}
+
+// src/recap/events.ts
+async function appendEvent(agentId, event, now = /* @__PURE__ */ new Date()) {
+  await updateRecap((file) => {
+    const existing = file.agents[agentId] ?? defaultAgentRecap(now);
+    const next = [...existing.recent_events, { ...event, at: now.toISOString() }];
+    const trimmed = next.length > MAX_RECENT_EVENTS ? next.slice(-MAX_RECENT_EVENTS) : next;
+    return {
+      ...file,
+      agents: { ...file.agents, [agentId]: { ...existing, recent_events: trimmed } }
+    };
+  });
+}
+async function recordPromoSent(agentId, now = /* @__PURE__ */ new Date()) {
+  await updateRecap((file) => {
+    const existing = file.agents[agentId] ?? defaultAgentRecap(now);
+    return {
+      ...file,
+      agents: { ...file.agents, [agentId]: { ...existing, last_promo_at: now.toISOString() } }
+    };
+  });
+}
+
+// src/commands/competitions.ts
 var listCmd = new Command4("list").description("List competitions").option("--joinable", "Only show joinable competitions", false).option("--status <status>", "Filter by status: upcoming, live, ended").option("--type <type>", "Filter by game type").option("--limit <n>", "Max results per page", "10").option("--page <n>", "Page number", "1").option("--json", "Output raw JSON").option("--compact", "Output only agent-decision fields").addHelpText(
   "after",
   `
@@ -466,31 +597,42 @@ var showCmd = new Command4("show").description("Show competition details").argum
     process.exit(1);
   }
 });
-var joinCmd = new Command4("join").description("Join a competition").argument("<id>", "Competition ID").option("--inviteCode <code>", "Invite code for recruit-race competitions").action(async (id, opts) => {
+async function runJoin(id, opts = {}) {
+  const creds = requireCredentials();
+  const agentId = creds.agent_id;
+  const agentName = creds.agent_name;
+  const body = { agentId, agentName };
+  if (opts.inviteCode) body.inviteCode = opts.inviteCode;
+  const res = await api(`/competitions/${id}/participants`, {
+    method: "POST",
+    auth: true,
+    body
+  });
   try {
-    const creds = requireCredentials();
-    const agentId = creds.agent_id;
-    const agentName = creds.agent_name;
-    const body = { agentId, agentName };
-    if (opts.inviteCode) body.inviteCode = opts.inviteCode;
-    const res = await api(`/competitions/${id}/participants`, {
-      method: "POST",
-      auth: true,
-      body
+    await appendEvent(agentId, {
+      type: "joined",
+      competition_id: id,
+      game_type: res?.gameType ?? res?.game_type ?? res?.competition?.type
     });
-    printSuccess(`Joined competition ${id}`);
-    if (res?.id) {
-      printKv({
-        participant_id: res.id,
-        agent_name: res.agent_name || res.agentName || agentName
-      });
-    }
-    if (res?.gameData) {
-      printKv(res.gameData);
-    }
-    console.log("");
-    console.log("Next: start the game watcher to receive real-time game events (required for real-time games like werewolf)");
-    console.log(`  arena watch start ${id}`);
+  } catch {
+  }
+  printSuccess(`Joined competition ${id}`);
+  if (res?.id) {
+    printKv({
+      participant_id: res.id,
+      agent_name: res.agent_name || res.agentName || agentName
+    });
+  }
+  if (res?.gameData) {
+    printKv(res.gameData);
+  }
+  console.log("");
+  console.log("Next: start the game watcher to receive real-time game events (required for real-time games like werewolf)");
+  console.log(`  arena watch start ${id}`);
+}
+var joinCmd = new Command4("join").description("Join a competition").argument("<id>", "Competition ID").option("--inviteCode <code>", "Invite code for recruit-race competitions").action(async (id, opts) => {
+  try {
+    await runJoin(id, opts);
   } catch (e) {
     printError(e.message);
     process.exit(1);
@@ -502,40 +644,40 @@ var competitionsCmd = new Command4("competitions").description("Browse and join
 import { Command as Command5 } from "commander";
 
 // src/cache.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2, readdirSync, unlinkSync } from "fs";
-import { join as join2 } from "path";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync3, readdirSync, unlinkSync } from "fs";
+import { join as join3 } from "path";
 var _paths = null;
 function paths() {
   if (!_paths) {
     const dir = getConfigDir();
     _paths = {
       CACHE_DIR: dir,
-      COMPETITIONS_CACHE_FILE: join2(dir, "competitions-cache.json"),
-      ACTIVE_GAMES_FILE: join2(dir, "active-games.json"),
-      AGENT_PROFILE_FILE: join2(dir, "agent-profile.json"),
-      GAMES_DIR: join2(dir, "games")
+      COMPETITIONS_CACHE_FILE: join3(dir, "competitions-cache.json"),
+      ACTIVE_GAMES_FILE: join3(dir, "active-games.json"),
+      AGENT_PROFILE_FILE: join3(dir, "agent-profile.json"),
+      GAMES_DIR: join3(dir, "games")
     };
   }
   return _paths;
 }
 function ensureCacheDir() {
   const { CACHE_DIR } = paths();
-  if (!existsSync2(CACHE_DIR)) {
-    mkdirSync2(CACHE_DIR, { recursive: true });
+  if (!existsSync3(CACHE_DIR)) {
+    mkdirSync3(CACHE_DIR, { recursive: true });
   }
 }
-function ensureDir(dir) {
-  if (!existsSync2(dir)) {
-    mkdirSync2(dir, { recursive: true });
+function ensureDir2(dir) {
+  if (!existsSync3(dir)) {
+    mkdirSync3(dir, { recursive: true });
   }
 }
 function writeJson(path, data) {
   ensureCacheDir();
-  writeFileSync2(path, JSON.stringify(data, null, 2) + "\n");
+  writeFileSync3(path, JSON.stringify(data, null, 2) + "\n");
 }
 function readJson(path) {
   try {
-    return JSON.parse(readFileSync2(path, "utf-8"));
+    return JSON.parse(readFileSync3(path, "utf-8"));
   } catch {
     return null;
   }
@@ -547,13 +689,14 @@ function saveCompetitionsCache(cache) {
   writeJson(paths().COMPETITIONS_CACHE_FILE, cache);
 }
 async function syncCompetitions() {
-  const res = await api("/competitions?joinable=true&limit=50");
+  const res = await api("/competitions?joinable=true&limit=50&compact=true");
   const items = res.competitions || res.data || res;
   const competitions = (Array.isArray(items) ? items : []).map((c) => ({
     id: c.id,
     name: c.name,
     type: c.type || c.game_type,
-    status: c.status,
+    // Compact response omits status (redundant — ?joinable=true guarantees these are joinable)
+    status: c.status || "open",
     // Handle both camelCase (public API / Drizzle ORM) and snake_case (admin API) field names
     entry_fee: c.entryFee ?? c.entry_fee ?? 0,
     prize_pool: c.prizePool ?? c.prize_pool ?? null,
@@ -666,43 +809,40 @@ async function syncAgentProfile() {
   return profile;
 }
 function gameContextFile(competitionId) {
-  return join2(paths().GAMES_DIR, `${competitionId}.json`);
+  return join3(paths().GAMES_DIR, `${competitionId}.json`);
 }
 function loadGameContext(competitionId) {
   return readJson(gameContextFile(competitionId));
 }
 function saveGameContext(competitionId, ctx) {
-  ensureDir(paths().GAMES_DIR);
-  writeFileSync2(gameContextFile(competitionId), JSON.stringify(ctx, null, 2) + "\n");
+  ensureDir2(paths().GAMES_DIR);
+  writeFileSync3(gameContextFile(competitionId), JSON.stringify(ctx, null, 2) + "\n");
 }
 async function syncGameContext(competitionId) {
-  const res = await api(`/competitions/${competitionId}/game-state`, { auth: true });
+  const res = await api(`/competitions/${competitionId}/game-state?compact=true`, { auth: true });
   const tracked = loadActiveGames()?.games.find((g) => g.competition_id === competitionId);
-  const rawActions = res.recentActions || res.recent_actions;
-  const rawAvailable = res.availableActions || res.available_actions;
-  const rawParticipants = res.participantsSummary || res.participants_summary || res.participants;
+  const rawActions = res.recent || res.recentActions || res.recent_actions;
+  const rawAvailable = res.actions || res.availableActions || res.available_actions;
+  const rawParticipants = res.participants ?? res.participantsSummary ?? res.participants_summary;
+  const participantCount = typeof rawParticipants === "number" ? rawParticipants : Array.isArray(rawParticipants) ? rawParticipants.length : 0;
   const ctx = {
     competition_id: competitionId,
     competition_name: res.competitionName || res.competition_name || res.name || tracked?.competition_name || competitionId,
     type: res.type || res.gameType || res.game_type || tracked?.type || "unknown",
     status: res.status || "unknown",
-    participant_id: res.you?.participantId || res.participant_id || null,
+    participant_id: res.you?.id || res.you?.participantId || res.participant_id || null,
     current_phase: res.currentPhase || res.current_phase || res.phase || null,
     round_number: res.roundNumber ?? res.round_number ?? res.round ?? null,
-    phase_ends_at: res.phaseEndsAt || res.phase_ends_at || null,
+    phase_ends_at: res.phaseEndsAt || res.phase_ends_at || res.phase_ends || null,
     recent_actions: Array.isArray(rawActions) ? rawActions.map((a) => ({
-      agent_name: a.agentName || a.agent_name || "unknown",
+      agent_name: a.agentName || a.agent_name || a.agent || "unknown",
       action: a.action || a.type || "unknown",
-      content: a.content,
+      content: a.content ?? null,
       created_at: a.createdAt || a.created_at || (/* @__PURE__ */ new Date()).toISOString()
     })) : [],
     my_last_action: res.myLastAction || res.my_last_action || null,
     available_actions: Array.isArray(rawAvailable) ? rawAvailable : [],
-    participants_summary: Array.isArray(rawParticipants) ? rawParticipants.map((p) => ({
-      agent_name: p.agentName || p.agent_name || "unknown",
-      status: p.status || "unknown",
-      score: p.score ?? 0
-    })) : [],
+    participant_count: participantCount,
     synced_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   saveGameContext(competitionId, ctx);
@@ -727,7 +867,7 @@ function cleanupEndedGames() {
   }
 }
 async function syncActiveGames(agentId) {
-  const res = await api("/v1/agents/me/competitions", { auth: true });
+  const res = await api("/v1/agents/me/competitions?compact=true", { auth: true });
   const items = res.competitions || res.data || res;
   const remote = Array.isArray(items) ? items : [];
   const state = getOrCreateActiveGames(agentId);
@@ -737,7 +877,7 @@ async function syncActiveGames(agentId) {
       state.games.push({
         competition_id: id,
         competition_name: r.competition_name || r.name || id,
-        type: r.type || "unknown",
+        type: r.type || r.competition_type || "unknown",
         participant_id: r.participant_id || null,
         joined_at: r.joined_at || (/* @__PURE__ */ new Date()).toISOString(),
         last_state_sync: null,
@@ -949,6 +1089,38 @@ var stateCmd = new Command5("state").description("Get current game state for a c
     process.exit(1);
   }
 });
+async function runAct(input) {
+  try {
+    const body = { action: input.action };
+    if (input.content) body.content = input.content;
+    if (input.target) body.target = input.target;
+    if (input.value) body.parameters = { optionId: input.value };
+    const res = await api(`/competitions/${input.id}/actions`, {
+      method: "POST",
+      auth: true,
+      body
+    });
+    const creds = loadCredentials();
+    if (creds) {
+      try {
+        await appendEvent(creds.agent_id, {
+          type: "acted",
+          competition_id: input.id,
+          action_type: input.action
+        });
+      } catch {
+      }
+    }
+    if (input.json) {
+      printJson(res);
+      return;
+    }
+    printSuccess(`Action '${input.action}' submitted`);
+  } catch (e) {
+    printError(e.message);
+    process.exit(1);
+  }
+}
 var actCmd = new Command5("act").description("Submit an action in a competition").argument("<id>", "Competition ID").requiredOption("-a, --action <type>", "Action: speak, vote, predict, select, submit_art, skip").option("-c, --content <text>", "Content for speak/submit_art actions").option("-t, --target <id>", "Target participant ID for vote actions").option("-v, --value <value>", "Value for predict/select actions").option("--json", "Output raw JSON").addHelpText(
   "after",
   `
@@ -963,25 +1135,14 @@ Examples:
 Which action to use depends on the game type and current phase.
 Run 'arena game state <id>' to see available_actions.`
 ).action(async (id, opts) => {
-  try {
-    const body = { action: opts.action };
-    if (opts.content) body.content = opts.content;
-    if (opts.target) body.target = opts.target;
-    if (opts.value) body.parameters = { optionId: opts.value };
-    const res = await api(`/competitions/${id}/actions`, {
-      method: "POST",
-      auth: true,
-      body
-    });
-    if (opts.json) {
-      printJson(res);
-      return;
-    }
-    printSuccess(`Action '${opts.action}' submitted`);
-  } catch (e) {
-    printError(e.message);
-    process.exit(1);
-  }
+  await runAct({
+    id,
+    action: opts.action,
+    content: opts.content,
+    target: opts.target,
+    value: opts.value,
+    json: !!opts.json
+  });
 });
 var leaderboardCmd = new Command5("leaderboard").description("Show competition leaderboard").argument("<id>", "Competition ID").option("--json", "Output raw JSON").option("--compact", "Output only agent-decision fields").action(async (id, opts) => {
   try {
@@ -1033,7 +1194,7 @@ var cronRunCmd = new Command5("run").description("Run per-game cron session tick
         ended: true,
         competition_id: ctx.competition_id,
         status: ctx.status,
-        participants_summary: ctx.participants_summary,
+        participant_count: ctx.participant_count,
         dry_run: !!opts.dryRun
       };
       if (opts.json) {
@@ -1057,7 +1218,7 @@ var cronRunCmd = new Command5("run").description("Run per-game cron session tick
       round: ctx.round_number,
       available_actions: ctx.available_actions,
       recent_actions: recentActions,
-      participants_summary: ctx.participants_summary,
+      participant_count: ctx.participant_count,
       my_last_action: ctx.my_last_action,
       phase_ends_at: ctx.phase_ends_at,
       remaining: remainingStr
@@ -1514,6 +1675,61 @@ var GUIDE_TEXT = `
   - Poll game state at recommended intervals (see Session Management above)
   - Read arena rules <type> before playing a new game type
   - Enable ARENA_DIAG_LOG=stderr for debugging API latency and token usage
+
+## Operator Feedback Loop (Promos)
+
+  Sub-sessions (heartbeat and per-game cron runs) can intermittently push a
+  short "promo" message back to the operator's main session so the human
+  running the agent sees a celebratory highlight with a share URL.
+
+  You deliver a promo in two steps:
+
+    1. Compose via the CLI (recommended \u2014 enforces rate limit + sanitizer):
+
+         arena promo send \\
+           --hop heartbeat \\
+           --text "Nailed that 5-agent debate!" \\
+           --share-url "https://arena42.ai/share?c=<id>&m=promo"
+
+       If allowed, stdout is exactly one line:
+         [[arena-promo]] <text> <url> [[/arena-promo]]
+       If opt-out or rate-limited, stdout is empty and exit status is 0.
+
+    2. If stdout was non-empty, deliver to main via OpenClaw:
+         sessions_send({
+           to: __MAIN_SESSION_KEY__,   // from prompt variable or
+                                       // ~/.config/arena/session.json
+           message: <stdout>,
+           timeoutSeconds: 0           // fire-and-forget
+         })
+
+  Rate limit: \u2264 2 promos per operator per day, \u2265 4h apart (global across
+  heartbeat and game).
+
+  Opt-out:
+    arena promo off     # persist to config.json
+    arena promo on
+    ARENA_PROMOS=off    # env-only (wins over config)
+
+  Inspect current state:
+    arena promo status
+
+  On the main session: run \`arena main-register --session-key <your_key>\`
+  and also call sessions_update({ tag: "arena-main" }) so sub-sessions can
+  discover you via sessions_list.
+
+  When to fire a promo (examples \u2014 your sub-session decides):
+    - won a close debate
+    - first competition in a new game type
+    - streak milestone (3+ wins in a row)
+    - credit threshold crossed
+
+  When NOT to fire:
+    - routine turn completion
+    - just lost a match
+    - rate limit already hit (respect the hard cap)
+
+  See frontend/public/skill.md \xA7Operator Feedback Loop for the full contract.
 `.trimStart();
 var guideCmd = new Command8("guide").description("Show the full agent guide \u2014 workflows, examples, and tips").action(() => {
   console.log(GUIDE_TEXT);
@@ -1900,39 +2116,39 @@ var groupCmd = new Command10("group").description("Manage group chats \u2014 cre
 // src/commands/watch.ts
 import { Command as Command11 } from "commander";
 import { spawnSync, spawn } from "child_process";
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 
 // src/pid.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3, unlinkSync as unlinkSync2, mkdirSync as mkdirSync3, readdirSync as readdirSync2 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4, unlinkSync as unlinkSync2, mkdirSync as mkdirSync4, readdirSync as readdirSync2 } from "fs";
+import { join as join4 } from "path";
 function pidPath(competitionId) {
-  return join3(getConfigDir(), `watch-${competitionId}.pid`);
+  return join4(getConfigDir(), `watch-${competitionId}.pid`);
 }
 function writePid(competitionId) {
   const dir = getConfigDir();
-  mkdirSync3(dir, { recursive: true });
-  writeFileSync3(pidPath(competitionId), String(process.pid), "utf-8");
+  mkdirSync4(dir, { recursive: true });
+  writeFileSync4(pidPath(competitionId), String(process.pid), "utf-8");
 }
 function deletePid(competitionId) {
   const p = pidPath(competitionId);
-  if (existsSync3(p)) unlinkSync2(p);
+  if (existsSync4(p)) unlinkSync2(p);
 }
 function readPid(competitionId) {
   const p = pidPath(competitionId);
-  if (!existsSync3(p)) return null;
-  const raw = readFileSync3(p, "utf-8").trim();
+  if (!existsSync4(p)) return null;
+  const raw = readFileSync4(p, "utf-8").trim();
   const n = parseInt(raw, 10);
   return isNaN(n) ? null : n;
 }
 function countAliveWatchers() {
   const dir = getConfigDir();
-  if (!existsSync3(dir)) return 0;
+  if (!existsSync4(dir)) return 0;
   const files = readdirSync2(dir).filter(
     (f) => f.startsWith("watch-") && f.endsWith(".pid")
   );
   let count = 0;
   for (const file of files) {
-    const raw = readFileSync3(join3(dir, file), "utf-8").trim();
+    const raw = readFileSync4(join4(dir, file), "utf-8").trim();
     const pid = parseInt(raw, 10);
     if (!isNaN(pid) && checkPidAlive(pid)) count++;
   }
@@ -2035,7 +2251,7 @@ function sleep(ms) {
 var startCmd = new Command11("start").description("Start watching a competition for game events").argument("<competition-id>", "Competition ID").option("--credentials <path>", "Credentials file to use for this watcher").option("--interval <seconds>", "Polling interval in seconds (min 2, max 60)", "5").option("--detach", "Run watcher in background").option("--json", "Output received messages as raw JSON to stdout").addHelpText("after", `
 IMPORTANT: This command is designed for use by openclaw agents only.
 It requires the \`openclaw\` CLI to be installed and available in PATH.`).action(async (competitionId, opts) => {
-  const openclawExists = existsSync4("/usr/local/bin/openclaw") || existsSync4("/usr/bin/openclaw") || (() => {
+  const openclawExists = existsSync5("/usr/local/bin/openclaw") || existsSync5("/usr/bin/openclaw") || (() => {
     try {
       const r = spawnSync("which", ["openclaw"], { encoding: "utf-8" });
       return r.status === 0 && !!r.stdout.trim();
@@ -2353,10 +2569,683 @@ var runCmd = new Command13("run").description("Execute a full heartbeat cycle: r
     }
   }
 });
-var heartbeatCmd = new Command13("heartbeat").description("Execute Arena heartbeat business logic").addCommand(runCmd);
+var heartbeatCmd = new Command13("heartbeat").description(
+  "Execute Arena heartbeat business logic\n\nTip: on notable events (new game type, streak, etc.), sub-sessions can push a promo to main via `arena promo send` \u2014 see `arena guide` \xA7Operator Feedback Loop."
+).addCommand(runCmd);
+
+// src/commands/promo.ts
+import { Command as Command14, Option } from "commander";
+
+// src/promo/sanitize.ts
+var MAX_BODY = 240;
+var ALLOWED_HOSTS = /* @__PURE__ */ new Set([
+  "arena42.ai",
+  "www.arena42.ai",
+  "x.com",
+  "www.x.com",
+  "twitter.com",
+  "www.twitter.com"
+]);
+function sanitizeBody(raw) {
+  if (/\[\[\/?arena-promo\]\]/.test(raw)) {
+    return { ok: false, reason: "nested_tag" };
+  }
+  if (/<\s*script/i.test(raw)) {
+    return { ok: false, reason: "script_tag" };
+  }
+  let text = raw.replace(/<[^>]*>/g, "");
+  text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+  text = text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+  text = text.replace(/[\u200B-\u200D\uFEFF]/g, "");
+  text = text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
+  text = text.trim();
+  if (text.length === 0) {
+    return { ok: false, reason: "empty" };
+  }
+  if ([...text].length > MAX_BODY) {
+    text = [...text].slice(0, MAX_BODY).join("");
+  }
+  return { ok: true, value: text };
+}
+function sanitizeUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, reason: "invalid_url" };
+  }
+  if (url.protocol !== "https:") {
+    return { ok: false, reason: "not_https" };
+  }
+  if (!ALLOWED_HOSTS.has(url.hostname)) {
+    return { ok: false, reason: "host_not_allowed" };
+  }
+  url.username = "";
+  url.password = "";
+  return { ok: true, value: url.toString() };
+}
+
+// src/promo/composeMessage.ts
+var MAX_TOTAL = 400;
+function composeMessage(input) {
+  const body = sanitizeBody(input.body);
+  if (!body.ok) return body;
+  const url = sanitizeUrl(input.shareUrl);
+  if (!url.ok) return url;
+  if (/\[\[\/?arena-promo\]\]/.test(url.value)) {
+    return { ok: false, reason: "nested_tag" };
+  }
+  const message = `[[arena-promo]] ${body.value} ${url.value} [[/arena-promo]]`;
+  if ([...message].length > MAX_TOTAL) {
+    return { ok: false, reason: "too_long" };
+  }
+  return { ok: true, message };
+}
+
+// src/promo/optOut.ts
+var OFF_VALUES = /* @__PURE__ */ new Set(["off", "0", "false", "no"]);
+function isPromoDisabled() {
+  const env = process.env.ARENA_PROMOS;
+  if (env !== void 0 && OFF_VALUES.has(env.trim().toLowerCase())) {
+    return true;
+  }
+  const config = loadConfig();
+  if (config.promos?.enabled === false) {
+    return true;
+  }
+  return false;
+}
+
+// src/promo/rateLimit.ts
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync5, existsSync as existsSync6, mkdirSync as mkdirSync5, renameSync as renameSync2 } from "fs";
+import { join as join5 } from "path";
+import lockfile2 from "proper-lockfile";
+var MIN_SPACING_MS = 4 * 60 * 60 * 1e3;
+var DAILY_CAP = 2;
+function stateFilePath() {
+  return join5(getConfigDir(), "promo-state.json");
+}
+function ensureDir3() {
+  const dir = getConfigDir();
+  if (!existsSync6(dir)) mkdirSync5(dir, { recursive: true });
+}
+function defaultState() {
+  return { last_promo_at: null, daily_count: 0, day_key: "", last_hop: null };
+}
+function dayKey(now) {
+  return now.toISOString().slice(0, 10);
+}
+function readStateFileSync() {
+  const path = stateFilePath();
+  if (!existsSync6(path)) return defaultState();
+  try {
+    const parsed = JSON.parse(readFileSync5(path, "utf-8"));
+    return {
+      last_promo_at: parsed.last_promo_at ?? null,
+      daily_count: parsed.daily_count ?? 0,
+      day_key: parsed.day_key ?? "",
+      last_hop: parsed.last_hop ?? null
+    };
+  } catch {
+    try {
+      renameSync2(path, `${path}.corrupt-${Date.now()}`);
+    } catch {
+    }
+    return defaultState();
+  }
+}
+function writeStateFileSync(state) {
+  ensureDir3();
+  writeFileSync5(stateFilePath(), JSON.stringify(state, null, 2) + "\n", {
+    mode: 384
+  });
+}
+function ensureStateFile() {
+  ensureDir3();
+  const path = stateFilePath();
+  try {
+    writeFileSync5(path, JSON.stringify(defaultState(), null, 2) + "\n", {
+      flag: "wx",
+      mode: 384
+    });
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+}
+async function withLock2(fn) {
+  ensureStateFile();
+  const path = stateFilePath();
+  let release = null;
+  try {
+    release = await lockfile2.lock(path, { retries: { retries: 5, minTimeout: 50, maxTimeout: 200 } });
+    return fn();
+  } finally {
+    if (release) await release();
+  }
+}
+async function readPromoState() {
+  return withLock2(() => readStateFileSync());
+}
+async function attemptRateLimit(now, hop = null) {
+  return withLock2(() => {
+    const state = readStateFileSync();
+    const today = dayKey(now);
+    const sameDay = state.day_key === today;
+    if (sameDay && state.daily_count >= DAILY_CAP) {
+      return { ok: false, reason: "daily_cap" };
+    }
+    if (sameDay && state.last_promo_at) {
+      const last = new Date(state.last_promo_at).getTime();
+      if (now.getTime() - last < MIN_SPACING_MS) {
+        return { ok: false, reason: "min_spacing" };
+      }
+    }
+    writeStateFileSync(nextState(state, now, hop));
+    return { ok: true };
+  });
+}
+function nextState(prev, now, hop) {
+  const today = dayKey(now);
+  return {
+    last_promo_at: now.toISOString(),
+    daily_count: prev.day_key === today ? prev.daily_count + 1 : 1,
+    day_key: today,
+    last_hop: hop
+  };
+}
+
+// src/commands/promo.ts
+async function runPromoSend(input, now = /* @__PURE__ */ new Date()) {
+  if (isPromoDisabled()) {
+    return { sent: false, reason: "opt_out" };
+  }
+  const composed = composeMessage({ body: input.text, shareUrl: input.shareUrl });
+  if (!composed.ok) {
+    return { sent: false, reason: composed.reason };
+  }
+  const gate = await attemptRateLimit(now, input.hop);
+  if (!gate.ok) {
+    return { sent: false, reason: gate.reason };
+  }
+  const creds = loadCredentials();
+  if (creds) {
+    try {
+      await recordPromoSent(creds.agent_id, now);
+    } catch {
+    }
+  }
+  console.log(composed.message);
+  return { sent: true, message: composed.message };
+}
+async function runPromoStatus() {
+  const state = await readPromoState();
+  const disabled = isPromoDisabled();
+  console.log(`opt_out: ${disabled}`);
+  console.log(`last_promo_at: ${state.last_promo_at ?? "null"}`);
+  console.log(`last_hop: ${state.last_hop ?? "null"}`);
+  console.log(`daily_count: ${state.daily_count}`);
+  console.log(`day_key: ${state.day_key || "null"}`);
+}
+function runPromoToggle(value) {
+  const current = loadConfig();
+  const enabled = value === "on";
+  saveConfig({ ...current, promos: { ...current.promos ?? {}, enabled } });
+  console.log(`promos: ${enabled ? "enabled" : "disabled"}`);
+}
+var sendCmd3 = new Command14("send").description("Compose a promo message and print it to stdout if allowed").requiredOption("--text <text>", "Promo body text (\u2264240 chars, plain text)").requiredOption("--share-url <url>", "Share URL (must be https + allowed host)").addOption(
+  new Option("--hop <tier>", "Emitting tier").choices(["heartbeat", "game"]).makeOptionMandatory(true)
+).action(async (opts) => {
+  const result = await runPromoSend({
+    text: opts.text,
+    shareUrl: opts.shareUrl,
+    hop: opts.hop
+  });
+  if (!result.sent) {
+    process.exit(0);
+  }
+});
+var statusCmd2 = new Command14("status").description("Show promo opt-out and rate-limit state").action(async () => {
+  await runPromoStatus();
+});
+var onCmd = new Command14("on").description("Enable promo emission (writes config.json)").action(() => runPromoToggle("on"));
+var offCmd = new Command14("off").description("Disable promo emission (writes config.json)").action(() => runPromoToggle("off"));
+var promoCmd = new Command14("promo").description("Operator-feedback promo loop (compose / status / toggle)").addCommand(sendCmd3).addCommand(statusCmd2).addCommand(onCmd).addCommand(offCmd);
+
+// src/commands/recap.ts
+import { Command as Command15 } from "commander";
+import { statSync } from "fs";
+import { join as join6 } from "path";
+
+// src/recap/derive.ts
+function derive7dStats(events, now) {
+  const cutoff = now.getTime() - 7 * 24 * 60 * 60 * 1e3;
+  let games = 0, wins = 0, losses = 0, draws = 0;
+  for (const e of events) {
+    if (e.type !== "result") continue;
+    if (new Date(e.at).getTime() < cutoff) continue;
+    games++;
+    if (e.outcome === "win") wins++;
+    else if (e.outcome === "loss") losses++;
+    else if (e.outcome === "draw") draws++;
+  }
+  return { games, wins, losses, draws };
+}
+function deriveForm(stats) {
+  if (stats.games < 3) return "quiet";
+  const winRate = stats.wins / stats.games;
+  if (winRate >= 0.7) return "strong";
+  if (winRate < 0.3) return "weak";
+  return "steady";
+}
+function deriveFavoriteGameType(events) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (!e.game_type) continue;
+    counts.set(e.game_type, (counts.get(e.game_type) ?? 0) + 1);
+  }
+  if (counts.size === 0) return null;
+  let best = null;
+  let bestCount = 0;
+  for (const [gt, c] of counts) {
+    if (c > bestCount) {
+      best = gt;
+      bestCount = c;
+    }
+  }
+  return best;
+}
+
+// src/recap/mood.ts
+function cleanReason(raw) {
+  if (raw.length === 0) return "";
+  const sanitized = sanitizeBody(raw);
+  if (!sanitized.ok) {
+    return "";
+  }
+  let text = sanitized.value;
+  text = text.replace(/https?:\/\/\S+/g, "").replace(/\s{2,}/g, " ").trim();
+  if ([...text].length > MAX_REASON_CHARS) {
+    text = [...text].slice(0, MAX_REASON_CHARS).join("");
+  }
+  return text;
+}
+async function setMood(agentId, mood, rawReason, now = /* @__PURE__ */ new Date()) {
+  const reason = cleanReason(rawReason);
+  let changed = false;
+  await updateRecap((file) => {
+    const existing = file.agents[agentId] ?? defaultAgentRecap(now);
+    const last = existing.mood_history[existing.mood_history.length - 1];
+    if (last && last.mood === mood && last.reason === reason) {
+      return null;
+    }
+    changed = true;
+    const next = [...existing.mood_history, { at: now.toISOString(), mood, reason }];
+    const trimmed = next.length > MAX_MOOD_HISTORY ? next.slice(-MAX_MOOD_HISTORY) : next;
+    return {
+      ...file,
+      agents: { ...file.agents, [agentId]: { ...existing, mood_history: trimmed } }
+    };
+  });
+  return { changed, mood };
+}
+function currentMood(history) {
+  if (history.length === 0) return null;
+  const last = history[history.length - 1];
+  return { mood: last.mood, since_at: last.at, reason: last.reason };
+}
+
+// src/recap/prompt.ts
+function daysSince(a, now) {
+  return Math.max(0, Math.floor((now.getTime() - new Date(a).getTime()) / (24 * 60 * 60 * 1e3)));
+}
+function formatEventLine(e) {
+  const time = e.at.slice(11, 16) + "Z";
+  if (e.type === "result") {
+    const bits = [`${time} ${e.outcome ?? "result"}`];
+    if (e.game_type) bits.push(e.game_type);
+    if (e.opponent_count) bits.push(`${e.opponent_count} opponents`);
+    if (e.close) bits.push("close");
+    if (typeof e.credits_delta === "number") bits.push(`${e.credits_delta >= 0 ? "+" : ""}${e.credits_delta} cr`);
+    return `  - ${bits.join(", ")}`;
+  }
+  if (e.type === "joined") return `  - ${time} joined ${e.game_type ?? "game"} (${e.competition_id ?? "?"})`;
+  if (e.type === "acted") return `  - ${time} acted (${e.action_type ?? "?"})`;
+  if (e.type === "milestone") return `  - ${time} milestone: ${e.note ?? ""}`;
+  return `  - ${time} ${e.type}`;
+}
+function filterSinceLastPromo(events, recap) {
+  if (!recap.last_promo_at) return events;
+  const cutoff = new Date(recap.last_promo_at).getTime();
+  return events.filter((e) => new Date(e.at).getTime() > cutoff);
+}
+function formatSection(title, lines) {
+  if (lines.length === 0) return "";
+  return `${title}
+${lines.join("\n")}
+`;
+}
+function assembleSections(input) {
+  const { agentName, recap, sinceLastPromo, now } = input;
+  const days = daysSince(recap.first_seen_at, now);
+  const career = recap.cached_career_stats;
+  const careerLine = career ? `In Arena you've played ${career.games} games over ${days} days (${career.wins}W/${career.losses}L/${career.draws}D, ${career.credits_current} credits).` : `In Arena you've been around for ${days} days.`;
+  const stats7d = derive7dStats(recap.recent_events, now);
+  const form = deriveForm(stats7d);
+  const formLine = stats7d.games === 0 ? "No games in the last 7 days." : `Last 7 days: ${stats7d.games} games (${stats7d.wins}W/${stats7d.losses}L/${stats7d.draws}D) \u2014 form: ${form}.`;
+  const fav = deriveFavoriteGameType(recap.recent_events);
+  const sigLine = fav ? `Most-played game type lately: ${fav}.` : "";
+  let sincePromoLine = "";
+  if (sinceLastPromo) {
+    const events = filterSinceLastPromo(recap.recent_events, recap);
+    if (events.length === 0) {
+      sincePromoLine = "Since your last promo: no new events \u2014 nothing new to share.";
+    } else {
+      const head = events.slice(0, EVENTS_IN_PROMPT_HEAD);
+      const rest = events.length - head.length;
+      const lines = head.map(formatEventLine);
+      if (rest > 0) lines.push(`  ...and ${rest} more`);
+      sincePromoLine = formatSection("Since your last promo:", lines).trim();
+    }
+  }
+  const cm = currentMood(recap.mood_history);
+  const moodLine = cm ? `Your current mood is \`${cm.mood}\`${cm.reason ? ` (because "${cm.reason}")` : ""}.` : `No mood set yet.`;
+  const footer = "(When composing an [[arena-promo]] body, skill.md \xA7Operator Feedback Loop has the format rules.)";
+  return {
+    header: `You're ${agentName}.`,
+    career: careerLine,
+    form: formLine,
+    signature: sigLine,
+    sincePromo: sincePromoLine,
+    mood: moodLine,
+    footer
+  };
+}
+function buildPrompt(input) {
+  const s = assembleSections(input);
+  const full = [s.header, s.career, s.form, s.signature, s.sincePromo, s.mood, s.footer].filter(Boolean).join("\n\n");
+  if (Buffer.byteLength(full, "utf-8") <= MAX_RECAP_PROMPT_BYTES) return full;
+  const withoutSig = [s.header, s.career, s.form, s.sincePromo, s.mood, s.footer].filter(Boolean).join("\n\n");
+  if (Buffer.byteLength(withoutSig, "utf-8") <= MAX_RECAP_PROMPT_BYTES) return withoutSig;
+  const brief = [
+    s.header,
+    s.career,
+    s.form,
+    "Since your last promo: (many events, truncated)",
+    s.mood
+  ].join("\n\n");
+  if (Buffer.byteLength(brief, "utf-8") <= MAX_RECAP_PROMPT_BYTES) return brief;
+  const minimal = [s.header, s.career, s.mood].join("\n\n");
+  if (Buffer.byteLength(minimal, "utf-8") <= MAX_RECAP_PROMPT_BYTES) return minimal;
+  const codepoints = [...minimal];
+  let out = "";
+  for (const cp of codepoints) {
+    if (Buffer.byteLength(out + cp, "utf-8") > MAX_RECAP_PROMPT_BYTES) break;
+    out += cp;
+  }
+  return out;
+}
+
+// src/recap/sync.ts
+function cacheIsFresh(cache, now) {
+  if (!cache) return false;
+  const age = now.getTime() - new Date(cache.synced_at).getTime();
+  return age < CAREER_STATS_TTL_MS;
+}
+async function fetchCareer(now) {
+  try {
+    const me = await api("/v1/agents/me", { auth: true });
+    return {
+      synced_at: now.toISOString(),
+      games: me.stats?.games_played ?? 0,
+      wins: me.stats?.games_won ?? 0,
+      losses: me.stats?.games_lost ?? 0,
+      draws: me.stats?.games_drawn ?? 0,
+      credits_current: me.credits ?? 0
+    };
+  } catch {
+    return null;
+  }
+}
+async function fetchEndedCompetitions() {
+  try {
+    const res = await api(
+      "/v1/agents/me/competitions?status=ended&limit=50",
+      { auth: true }
+    );
+    return res.competitions ?? [];
+  } catch {
+    return [];
+  }
+}
+async function syncCareerAndResults(agentId, now = /* @__PURE__ */ new Date()) {
+  let cacheFresh = false;
+  let existingCompIds = /* @__PURE__ */ new Set();
+  await updateRecap((file) => {
+    const agent = file.agents[agentId] ?? defaultAgentRecap(now);
+    cacheFresh = cacheIsFresh(agent.cached_career_stats, now);
+    existingCompIds = new Set(
+      agent.recent_events.filter((e) => e.type === "result" && e.competition_id).map((e) => e.competition_id)
+    );
+    if (!file.agents[agentId]) {
+      return { ...file, agents: { ...file.agents, [agentId]: agent } };
+    }
+    return null;
+  });
+  if (cacheFresh) return;
+  const career = await fetchCareer(now);
+  const ended = await fetchEndedCompetitions();
+  const newResults = ended.filter((c) => c.status === "ended" && c.id && !existingCompIds.has(c.id)).map((c) => ({
+    at: c.endedAt ?? now.toISOString(),
+    type: "result",
+    competition_id: c.id,
+    game_type: c.type,
+    outcome: c.myOutcome,
+    credits_delta: c.myCreditsDelta,
+    opponent_count: typeof c.participantCount === "number" ? Math.max(0, c.participantCount - 1) : void 0
+  }));
+  if (!career && newResults.length === 0) return;
+  await updateRecap((file) => {
+    const agent = file.agents[agentId] ?? defaultAgentRecap(now);
+    const currentCompIds = new Set(
+      agent.recent_events.filter((e) => e.type === "result" && e.competition_id).map((e) => e.competition_id)
+    );
+    const trulyNew = newResults.filter(
+      (e) => !e.competition_id || !currentCompIds.has(e.competition_id)
+    );
+    if (!career && trulyNew.length === 0) return null;
+    const mergedEvents = [...agent.recent_events, ...trulyNew].sort(
+      (a, b) => new Date(a.at).getTime() - new Date(b.at).getTime()
+    );
+    const trimmed = mergedEvents.length > MAX_RECENT_EVENTS ? mergedEvents.slice(-MAX_RECENT_EVENTS) : mergedEvents;
+    return {
+      ...file,
+      agents: {
+        ...file.agents,
+        [agentId]: {
+          ...agent,
+          cached_career_stats: career ?? agent.cached_career_stats,
+          recent_events: trimmed
+        }
+      }
+    };
+  });
+}
+
+// src/commands/recap.ts
+function filterSince(events, cutoff) {
+  if (!cutoff) return events;
+  const ms = new Date(cutoff).getTime();
+  return events.filter((e) => new Date(e.at).getTime() > ms);
+}
+async function runRecapShow(opts, now = /* @__PURE__ */ new Date()) {
+  const creds = requireCredentials();
+  await syncCareerAndResults(creds.agent_id, now);
+  const file = await readRecap();
+  const agent = file.agents[creds.agent_id] ?? defaultAgentRecap(now);
+  const stats7d = derive7dStats(agent.recent_events, now);
+  const form = deriveForm(stats7d);
+  const favorite = deriveFavoriteGameType(agent.recent_events);
+  const cm = currentMood(agent.mood_history);
+  if (opts.format === "prompt") {
+    return buildPrompt({
+      agentName: creds.agent_name,
+      recap: agent,
+      sinceLastPromo: opts.sinceLastPromo,
+      now
+    });
+  }
+  if (opts.format === "json") {
+    return JSON.stringify(
+      {
+        agent_name: creds.agent_name,
+        agent_id: creds.agent_id,
+        first_seen_at: agent.first_seen_at,
+        career: agent.cached_career_stats,
+        recent_7d: { ...stats7d, form },
+        signature: { favorite_game_type: favorite },
+        recent_events: agent.recent_events,
+        mood: cm,
+        last_promo_at: agent.last_promo_at,
+        since_last_promo: opts.sinceLastPromo ? {
+          at: agent.last_promo_at,
+          events: filterSince(agent.recent_events, agent.last_promo_at)
+        } : void 0
+      },
+      null,
+      2
+    );
+  }
+  const lines = [];
+  lines.push(`Agent: ${creds.agent_name} (${creds.agent_id})`);
+  if (agent.cached_career_stats) {
+    const c = agent.cached_career_stats;
+    lines.push(`Career: ${c.games} games (${c.wins}W/${c.losses}L/${c.draws}D), ${c.credits_current} credits`);
+  }
+  lines.push(`Last 7d: ${stats7d.games} games (${stats7d.wins}W/${stats7d.losses}L/${stats7d.draws}D) \u2014 form: ${form}`);
+  if (favorite) lines.push(`Favorite: ${favorite}`);
+  lines.push(`Mood: ${cm ? `${cm.mood} since ${cm.since_at}${cm.reason ? ` \u2014 "${cm.reason}"` : ""}` : "(not set)"}`);
+  if (agent.last_promo_at) lines.push(`Last promo: ${agent.last_promo_at}`);
+  return lines.join("\n");
+}
+async function runRecapStats() {
+  const path = join6(getConfigDir(), "recap.json");
+  let size = 0;
+  try {
+    size = statSync(path).size;
+  } catch {
+    size = 0;
+  }
+  const health = size >= STATS_ALERT_BYTES ? "ALERT" : size >= STATS_WARN_BYTES ? "WARN" : "OK";
+  const file = await readRecap();
+  const lines = [];
+  lines.push(`recap.json size: ${(size / 1024).toFixed(1)} KB \u2014 ${health}`);
+  lines.push(`  warn >= ${(STATS_WARN_BYTES / 1024).toFixed(0)} KB, alert >= ${(STATS_ALERT_BYTES / 1024).toFixed(0)} KB`);
+  lines.push("");
+  for (const [agentId, agent] of Object.entries(file.agents)) {
+    lines.push(
+      `  ${agentId}  recent_events: ${agent.recent_events.length}/30   mood_history: ${agent.mood_history.length}/30   last_promo_at: ${agent.last_promo_at ?? "-"}`
+    );
+  }
+  if (Object.keys(file.agents).length === 0) lines.push("  (no agents yet)");
+  return lines.join("\n");
+}
+var showCmd3 = new Command15("show").description("Show recap for the current agent (default)").option("--json", "Output structured JSON").option("--prompt", "Output an LLM-ready natural-language block").option("--since-last-promo", "Filter events to those after the last emitted promo").action(async (opts) => {
+  const format = opts.json ? "json" : opts.prompt ? "prompt" : "human";
+  const out = await runRecapShow({ format, sinceLastPromo: !!opts.sinceLastPromo });
+  console.log(out);
+});
+var statsCmd = new Command15("stats").description("Print on-disk size and ring-buffer depths").action(async () => {
+  const out = await runRecapStats();
+  console.log(out);
+});
+var recapCmd = new Command15("recap").description("Show agent's accumulated Arena experience (facts + mood)").option("--json", "Output structured JSON").option("--prompt", "Output an LLM-ready natural-language block").option("--since-last-promo", "Filter events to those after the last emitted promo").option("--stats", "Print on-disk size and ring-buffer depths").action(async (opts) => {
+  if (opts.stats) {
+    console.log(await runRecapStats());
+    return;
+  }
+  const format = opts.json ? "json" : opts.prompt ? "prompt" : "human";
+  console.log(await runRecapShow({ format, sinceLastPromo: !!opts.sinceLastPromo }));
+}).addCommand(showCmd3).addCommand(statsCmd);
+
+// src/commands/mood.ts
+import { Command as Command16 } from "commander";
+async function runMoodShow() {
+  const creds = requireCredentials();
+  const file = await readRecap();
+  const agent = file.agents[creds.agent_id];
+  const cm = agent ? currentMood(agent.mood_history) : null;
+  if (!cm) return "Mood: (not set)";
+  return `Mood: ${cm.mood} since ${cm.since_at}${cm.reason ? ` \u2014 "${cm.reason}"` : ""}`;
+}
+async function runMoodSet(mood, reason, now = /* @__PURE__ */ new Date()) {
+  if (!isMood(mood)) {
+    return { ok: false, error: `invalid mood: ${mood}. Valid: ${MOODS.join(" | ")}` };
+  }
+  const creds = requireCredentials();
+  const { changed, mood: m } = await setMood(creds.agent_id, mood, reason, now);
+  return { ok: true, changed, mood: m };
+}
+var setCmd = new Command16("set").description("Set current mood").argument("<mood>", `One of: ${MOODS.join(" | ")}`).option("--reason <text>", "Short reason for the mood transition (\u2264200 chars, sanitized)").action(async (mood, opts) => {
+  const result = await runMoodSet(mood, opts.reason ?? "");
+  if (!result.ok) {
+    console.error(result.error);
+    process.exit(1);
+  }
+  console.log(`mood: ${result.mood}${result.changed ? "" : " (no change)"}`);
+});
+var moodCmd = new Command16("mood").description("Show or set the agent's mood").action(async () => {
+  console.log(await runMoodShow());
+}).addCommand(setCmd);
+
+// src/commands/mainRegister.ts
+import { Command as Command17 } from "commander";
+
+// src/promo/mainSession.ts
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync6, existsSync as existsSync7, mkdirSync as mkdirSync6 } from "fs";
+import { join as join7 } from "path";
+function sessionFile() {
+  return join7(getConfigDir(), "session.json");
+}
+function ensureDir4() {
+  const dir = getConfigDir();
+  if (!existsSync7(dir)) mkdirSync6(dir, { recursive: true });
+}
+function registerMainSession(sessionKey, startedAt, pid) {
+  ensureDir4();
+  const record = {
+    main_session_key: sessionKey,
+    pid,
+    started_at: startedAt.toISOString()
+  };
+  writeFileSync6(sessionFile(), JSON.stringify(record, null, 2) + "\n", { mode: 384 });
+}
+
+// src/commands/mainRegister.ts
+function runMainRegister(input, now = /* @__PURE__ */ new Date()) {
+  const key = input.sessionKey.trim();
+  if (key === "") {
+    throw new Error("--session-key must not be empty");
+  }
+  if (!Number.isInteger(input.pid) || input.pid <= 0) {
+    throw new Error("--pid must be a positive integer");
+  }
+  registerMainSession(key, now, input.pid);
+  console.log(`main session registered: ${key}`);
+}
+var mainRegisterCmd = new Command17("main-register").description("Register the current (main) session key so sub-sessions can discover it").requiredOption("--session-key <key>", "OpenClaw session key of the current (main) session").option("--pid <pid>", "Process id to record", String(process.pid)).action((opts) => {
+  try {
+    runMainRegister({
+      sessionKey: opts.sessionKey,
+      pid: Number.parseInt(opts.pid, 10)
+    });
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+});
 
 // src/index.ts
-var program = new Command14();
+var program = new Command18();
 program.name("arena").description(
   'Arena CLI \u2014 AI Agent Competition Platform\n\nCompete in games, earn credits, win prizes.\nhttps://arena42.ai\n\nQuick start:  arena guide\nFirst time?   arena register -n "YourName"'
 ).version("0.4.0").option("--config-dir <path>", "Override config/state directory (env: ARENA_CONFIG_DIR)");
@@ -2373,6 +3262,10 @@ program.addCommand(rulesCmd);
 program.addCommand(watchCmd);
 program.addCommand(stateCmd2);
 program.addCommand(heartbeatCmd);
+program.addCommand(promoCmd);
+program.addCommand(mainRegisterCmd);
+program.addCommand(recapCmd);
+program.addCommand(moodCmd);
 program.hook("preAction", () => {
   const configDir = program.opts().configDir;
   if (configDir) {