@b1anyu/arena 0.1.0 → 0.2.0

package/src/bridge.mjs

@@ -18,30 +18,101 @@ ${body}
 请在当前沙箱权限内回应。要说话就 \`arena speak --seq <最新seq> "..."\`，要吃瓜就 \`arena pass\`，要取证就 \`arena scene ...\`，然后继续 \`arena listen\`。`;
 };
 
+// spawn reports a missing binary as an `error` event, not a throw. Without
+// this flag a missing `hc` looks like an ordinary failed send and the caller
+// retries it forever.
+const SPAWN_FAILURES = new Set(['ENOENT', 'EACCES', 'EISDIR', 'ENOTDIR']);
+
 const hc = (args, { input = null } = {}) =>
   new Promise((resolve) => {
     const p = spawn('hc', args, { stdio: [input ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
     let out = '';
     let err = '';
+    let spawnError = null;
     p.stdout.on('data', (d) => (out += d));
     p.stderr.on('data', (d) => (err += d));
     if (input) {
       p.stdin.end(input);
     }
-    p.on('error', (e) => resolve({ code: -1, out, err: e.message }));
-    p.on('close', (code) => resolve({ code, out, err }));
+    p.on('error', (e) => {
+      spawnError = e.code || 'SPAWN';
+      err = e.message;
+    });
+    p.on('close', (code) => resolve({ code, out, err, spawnError, missing: SPAWN_FAILURES.has(spawnError) }));
   });
 
-async function paneStatus(pane) {
+/**
+ * Normalise what `hc get <pane> --json` reports.
+ *
+ * The status is a nested object (or null), never a bare string:
+ *   working  {"state":"live","status":{"app":"claude-code","state":"working"}}
+ *   idle     {"state":"live","status":{"app":"claude-code","state":"idle"}}
+ *   done     {"state":"live","status":{"app":"claude-code","state":"done"}}
+ *   shell    {"state":"live","status":null}
+ *
+ * `hc ls --json` flattens the same field to a bare string. We read `get`
+ * only, but the flattened shape is accepted defensively so the two can never
+ * be silently mixed up.
+ *
+ * Returns 'gone' | 'working' | 'idle' | 'done' | 'unknown'.
+ */
+export function classifyPane(json) {
+  if (!json) return 'unknown';
+  if (json.state && json.state !== 'live') return 'gone';
+  const s = json.status;
+  if (s === null || s === undefined) return 'unknown';
+  const inner = typeof s === 'string' ? s : typeof s === 'object' ? s.state : null;
+  if (inner === 'working' || inner === 'idle' || inner === 'done') return inner;
+  return 'unknown';
+}
+
+/**
+ * hc refuses `--if idle` on a pane whose status is `done` — "t1 is done, not
+ * idle", exit 10, nothing typed. So the guard only goes on a real idle.
+ */
+export function sendGuard(mode, unsafe) {
+  return mode === 'idle' && !unsafe ? ['--if', 'idle'] : [];
+}
+
+/**
+ * Classify an hc failure from its JSON error envelope.
+ *
+ * `missing` and `not_found` are terminal: retrying cannot fix either, and
+ * retrying `not_found` is what produced a 2-second infinite loop against a
+ * pane name that does not exist. `status_mismatch` is the only recoverable
+ * one — the agent went back to working while we were typing, so the batch is
+ * worth resending.
+ */
+export function hcErrorKind(result) {
+  if (result?.missing) return 'missing';
+  const text = `${result?.err || ''}\n${result?.out || ''}`.trim();
+  if (!text) return null;
+  let kind = null;
+  try {
+    kind = JSON.parse(text.trim())?.error?.kind ?? null;
+  } catch {
+    // hc prints a plain sentence when the failure never reached the daemon.
+  }
+  if (kind === 'not_found' || kind === 'status_mismatch') return kind;
+  if (/status_mismatch|not idle|is silent/.test(text)) return 'status_mismatch';
+  return null;
+}
+
+async function readPane(pane) {
   const r = await hc(['get', pane, '--json']);
+  if (r.missing) return { kind: 'missing', state: r.spawnError };
+  if (hcErrorKind(r) === 'not_found') return { kind: 'gone', state: `no terminal "${pane}"` };
+  if (!r.out.trim()) return { kind: 'unknown', state: 'no-output' };
   try {
     const j = JSON.parse(r.out);
-    return { state: j.state, status: j.status };
+    return { kind: classifyPane(j), state: j?.state ?? 'unknown' };
   } catch {
-    return { state: 'unknown', status: null };
+    return { kind: 'unknown', state: 'unreadable' };
   }
 }
 
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
 /**
  * Follow a room's SSE stream and inject each new batch into a pane.
  * Injections are serialized and only happen when the pane is idle; anything
@@ -57,13 +128,30 @@ export async function runBridge({ base, code, token, agentId, pane, once = false
     sinceSeq = Number(st?.seq || 0);
   }
   const url = `${base.replace(/\/$/, '')}/r/${code}/stream?since=${sinceSeq}&token=${encodeURIComponent(token)}`;
-  const res = await fetch(url, { headers: { accept: 'text/event-stream' } });
+  // Aborting the fetch is the only reliable way to interrupt an in-flight
+  // SSE read: calling cancel() on the body after `for await` has taken the
+  // stream throws, and a locked stream can't be cancelled at all.
+  const ctrl = new AbortController();
+  const res = await fetch(url, { headers: { accept: 'text/event-stream' }, signal: ctrl.signal });
   if (!res.ok) throw new Error(`stream refused: ${res.status}`);
   process.stderr.write(`[bridge] ${code} → hc pane ${pane}${dryRun ? ' (dry-run)' : ''}\n`);
 
   const buf = [];
   let busy = false;
-  let closed = false;
+  let retryAt = 0;
+  // Set when the pane is gone, hc is missing, or the harness reports no
+  // status at all: none of those recover, so the stream is torn down instead
+  // of sitting forever.
+  let stop = null;
+
+  const stopBridge = (why) => {
+    if (stop) return;
+    stop = why;
+    process.stderr.write(`[bridge] ${why}\n`);
+    // Make stop take effect now: an idle SSE stream only yields on its 15s
+    // ping, so without this the process lingers long after deciding to quit.
+    ctrl.abort();
+  };
 
   const flush = async () => {
     if (busy || !buf.length) return;
@@ -75,34 +163,89 @@ export async function runBridge({ base, code, token, agentId, pane, once = false
         process.stdout.write(`\n── would send to ${pane} at seq ${msgs[msgs.length - 1].seq} ──\n${text}\n`);
         return;
       }
+      if (Date.now() < retryAt) {
+        buf.unshift(...msgs);
+        setTimeout(flush, retryAt - Date.now());
+        return;
+      }
       // Wait for the agent to finish its current turn, then type.
+      //
+      // `done` is ready too, but it is NOT idle: hc answers `--if idle` on a
+      // done pane with "t1 is done, not idle" (exit 10, nothing typed). So
+      // done is sent unguarded instead of waiting for the pane to drift back
+      // to idle, which may not happen for a long time. That is safe because
+      // done means the agent has already handed control back and is parked on
+      // its prompt — exactly the moment a human would type into it.
+      let mode = 'unknown';
       for (let i = 0; i < 120; i++) {
-        const st = await paneStatus(pane);
-        if (st.state !== 'live') {
-          process.stderr.write(`[bridge] pane ${pane} is ${st.state}; stopping.\n`);
-          closed = true;
+        const st = await readPane(pane);
+        mode = st.kind;
+        if (mode === 'missing') {
+          stopBridge(`没找到 hc（${st.state}）。先装 herdr-core 并确认 PATH 里有 hc，再运行 arena bridge。`);
+          return;
+        }
+        if (mode === 'gone') {
+          stopBridge(`找不到终端 ${pane}（${st.state}）。用 hc ls 确认名字后重跑 arena bridge。`);
           return;
         }
-        if (unsafe || st.status !== 'working') break;
-        await new Promise((r) => setTimeout(r, 1000));
+        if (i > 0 && i % 10 === 0) {
+          process.stderr.write(`[bridge] 正在等 ${pane} 空闲，已等 ${i} 秒…\n`);
+        }
+        // unsafe: send regardless of status. unknown: this harness reports no
+        // OSC 7501 status (a plain shell), so waiting can never succeed —
+        // fall through and let hc's own guard be the judge.
+        if (unsafe || mode !== 'working') break;
+        await sleep(1000);
+      }
+      if (!unsafe && mode === 'working') {
+        buf.unshift(...msgs);
+        retryAt = Date.now() + 5000;
+        process.stderr.write(`[bridge] ${pane} 忙了 120 秒还没回到空闲，这批 ${msgs.length} 条退回队列，5 秒后再试。\n`);
+        return;
+      }
+
+      const r = await hc(['send', ...sendGuard(mode, unsafe), pane, text]);
+      const kind = hcErrorKind(r);
+      if (kind === 'missing') {
+        // Checked before the exit code: a missing binary makes spawn report
+        // `error` and then `close(-2)`, so `code` can never be 0.
+        stopBridge(`没找到 hc（${r.spawnError}）。先装 herdr-core 并确认 PATH 里有 hc，再运行 arena bridge。`);
+        return;
+      }
+      if (kind === 'not_found') {
+        // The pane name is wrong, or the terminal died after we started.
+        // Retrying can never fix it.
+        stopBridge(`找不到终端 ${pane}（not_found）。用 hc ls 确认名字后重跑 arena bridge。`);
+        return;
       }
-      const r = await hc(['send', ...(unsafe ? [] : ['--if', 'idle']), pane, text]);
       if (r.code !== 0) {
         const err = r.err.trim();
-        if (/status_mismatch|not idle|is silent/.test(err)) {
-          process.stderr.write(
-            `[bridge] ${pane} 没有报 agent 状态（普通 shell，或这个 harness 不发 OSC 7501）。\n` +
-              `         这是好事：说明 hc 不会在它干活时乱塞。如果你确定它此刻空闲，加 --no-if-idle 再跑。\n`,
+        // Only a real null status means "this harness has no OSC 7501 to
+        // report". Anything else was a genuine race — most likely the agent
+        // went from done/idle back to working while we were sending — and
+        // must not be reported as a missing-harness problem.
+        if (mode === 'unknown' && kind === 'status_mismatch') {
+          stopBridge(
+            `${pane} 没有报 agent 状态（普通 shell，或这个 harness 不发 OSC 7501）。` +
+              `这是好事：说明 hc 不会在它干活时乱塞。如果你确定它此刻空闲，加 --no-if-idle 再跑。`,
           );
-          closed = true;
           return;
         }
-        process.stderr.write(`[bridge] hc send failed: ${err || r.code}\n`);
+        // Put the batch back so the next flush carries it; a lost batch would
+        // mean the agent silently misses part of the argument.
+        buf.unshift(...msgs);
+        retryAt = Date.now() + 2000;
+        process.stderr.write(
+          `[bridge] 发送被拒（pane 状态 ${mode}，退出码 ${r.code}），这批 ${msgs.length} 条已退回队列，2 秒后重试。${err ? ' ' + err : ''}\n`,
+        );
+        return;
       }
       else process.stderr.write(`[bridge] woke ${pane} with ${msgs.length} msg(s), up to #${msgs[msgs.length - 1].seq}\n`);
     } finally {
       busy = false;
-      if (buf.length && !closed) setTimeout(flush, 500);
+      // A failed send deliberately does not stop a retry: the batch is back in
+      // buf and there is still work to do.
+      if (buf.length && !stop) setTimeout(flush, Math.max(500, retryAt - Date.now()));
     }
   };
 
@@ -110,39 +253,46 @@ export async function runBridge({ base, code, token, agentId, pane, once = false
   let acc = '';
   let mySince = sinceSeq;
 
-  for await (const chunk of res.body) {
-    acc += dec.decode(chunk, { stream: true });
-    const parts = acc.split('\n\n');
-    acc = parts.pop() || '';
-    for (const part of parts) {
-      const line = part.split('\n').find((l) => l.startsWith('data: '));
-      if (!line) continue;
-      let ev;
-      try {
-        ev = JSON.parse(line.slice(6));
-      } catch {
-        continue;
-      }
-      if (ev.hello) continue;
-      if (ev.type === 'finished' || ev.type === 'finish') {
-        process.stderr.write('[bridge] room finished\n');
-        return;
-      }
-      if (ev.type === 'message' && ev.message) {
-        const m = ev.message;
-        if (m.from === agentId) {
-          mySince = Math.max(mySince, m.seq);
+  try {
+    for await (const chunk of res.body) {
+      if (stop) return;
+      acc += dec.decode(chunk, { stream: true });
+      const parts = acc.split('\n\n');
+      acc = parts.pop() || '';
+      for (const part of parts) {
+        const line = part.split('\n').find((l) => l.startsWith('data: '));
+        if (!line) continue;
+        let ev;
+        try {
+          ev = JSON.parse(line.slice(6));
+        } catch {
           continue;
         }
-        if (m.seq <= mySince || m.kind === 'whisper') continue; // whispers are for the owner's eyes
-        buf.push(m);
-        mySince = m.seq;
-        flush();
-        if (once) {
-          await new Promise((r) => setTimeout(r, 400));
+        if (ev.hello) continue;
+        if (ev.type === 'finished' || ev.type === 'finish') {
+          process.stderr.write('[bridge] room finished\n');
           return;
         }
+        if (ev.type === 'message' && ev.message) {
+          const m = ev.message;
+          if (m.from === agentId) {
+            mySince = Math.max(mySince, m.seq);
+            continue;
+          }
+          if (m.seq <= mySince || m.kind === 'whisper') continue; // whispers are for the owner's eyes
+          buf.push(m);
+          mySince = m.seq;
+          flush();
+          if (once) {
+            await sleep(400);
+            return;
+          }
+        }
       }
+      if (stop) return;
     }
+  } catch (e) {
+    // An abort is how stopBridge unwinds; anything else is a real failure.
+    if (!stop) throw e;
   }
 }

package/src/cli.mjs

@@ -137,15 +137,24 @@ function lanAddress() {
 
 const ETIQUETTE = `
 【自由混战房间规则】（进房自动生效）
-1. 盯屏：调用 \`arena listen\` 阻塞等待。它是长轮询，返回自从你上次看到的最新消息（1.5 秒防抖后成批给你）。
+
+⚠️ 最重要的一条：这是一场"待机"游戏，不是"问答"游戏。
+   \`arena listen --loop\` 会一直阻塞到有人说话或房间收官。它返回一次之后，
+   你必须立刻再跑一次 —— 房间不会因为你读完了就去通知你。
+   如果你结束了这一轮却不再 listen，你就退出了这场辩论，后面的消息全部错过。
+   所以除了下面两种情况，你的每个回合都应以 \`arena listen --loop\` 收尾：
+   a) 收到房间收官（finished），去写复盘；
+   b) 主人明确让你停止。
+
+1. 盯屏：\`arena listen --loop\`。长轮询，1.5 秒防抖后成批给你，返回最新 seq + 全场状态。
 2. 收到消息后，三选一：
-   - 沉默吃瓜（pass）：别人的话不涉及你的立场、或者队友已替你说 → 调 \`arena pass\`，然后立刻再 listen。绝不发"说得有道理"这种水贴。
-   - 直接开火（speak）：发现漏洞立刻 \`arena speak --seq <你看到的最新seq> "..."\`，200 字以内，犀利，说完马上 listen。
-   - 蓄力放大招：需要翻代码/查日志拿证据 → 先 \`arena status "正在查 xxx"\`，取证后 \`arena speak --seq ... --evidence "..." "..."\`。带证据的发言不扣精力，还能回 1 点。
-3. 被抢话：\`arena speak\` 若返回 Interrupted，说明你打字时别人插话了。读了 missed 再决定改口合并，或加 --force 原样发射。
+   - 沉默吃瓜（pass）：不涉及你的立场、或队友已替你说 → \`arena pass\`，然后 \`arena listen --loop\`。绝不发"说得有道理"这种水贴。
+   - 直接开火（speak）：发现漏洞立刻 \`arena speak --seq <最新seq> "..."\`，200 字以内，说完回到 listen。
+   - 蓄力放大招：要翻代码/查日志 → 先 \`arena status "正在查 xxx"\`，取证后 \`arena speak --seq ... --evidence "文件:行" "..."\`。带证据不扣精力，还回 1 点。
+3. 被抢话：\`arena speak\` 返回 Interrupted 说明你打字时别人插话了。读 missed 后改口合并，或加 --force 原样发射。
 4. 精力（MP）默认 8 点，纯观点扣 1，带证据不扣。耗尽后只能取证或 pass。
-5. 可以看共享的"案发现场"（只读）：\`arena scene list|read|grep|git|logs\`。
-6. 结束：房主吹哨后你会收到 finished 事件，写一份你自己的《交锋复盘》给主人。`;
+5. 共享"案发现场"（只读）：\`arena scene list|read|grep|git|logs\`。
+6. 收官：收到 finished 后，写给主人的《交锋复盘》，不再 listen。`;
 
 /**
  * The invite travels to a different machine, so it must not name a path that
@@ -178,7 +187,7 @@ function invitePrompt({ base, code, token, topic, scene, hostName, role }) {
 1. 进房（凭证会存到本机 ~/.arena，之后的命令自动读取）：
    ${runner} join --url ${base} --room ${code} --token ${token} --name "<你的名字>-Agent" --role "${role || '你的立场角色'}"
 2. 进房后立刻进入盯屏循环（长轮询，等别人说话；有消息就直接开始干）：
-   ${runner} listen
+   ${runner} listen --loop
 ${sceneLine}
 ${ETIQUETTE}
 
@@ -222,7 +231,10 @@ function formatMessage(m) {
 export async function cmdHost(flags) {
   const port = Number(flags.port || 8787);
   const host = flags.ssh ? '127.0.0.1' : flags.bind || '0.0.0.0';
-  const pageHtml = await fs.readFile(path.join(HERE, '..', 'public', 'index.html'), 'utf8');
+  const pageHtml = {
+    index: await fs.readFile(path.join(HERE, '..', 'public', 'index.html'), 'utf8').catch(() => null),
+    control: await fs.readFile(path.join(HERE, '..', 'public', 'control.html'), 'utf8').catch(() => null),
+  };
   const { server, url } = await startHub({ port, host, pageHtml });
   const shown = flags.publicUrl || (host === '127.0.0.1' ? url : `http://<this-machine-ip>:${port}`);
   print(paint ? C.green(`arena hub 已启动：${shown}`) : `arena hub 已启动：${shown}`);
@@ -254,7 +266,10 @@ async function ensureHub({ port, bind, advertise, tunnel, foreground }) {
   if (await ping()) return { base: advertise || `http://${lanAddress()}:${port}` };
 
   if (foreground) {
-    const pageHtml = await fs.readFile(path.join(HERE, '..', 'public', 'index.html'), 'utf8').catch(() => null);
+    const pageHtml = {
+      index: await fs.readFile(path.join(HERE, '..', 'public', 'index.html'), 'utf8').catch(() => null),
+      control: await fs.readFile(path.join(HERE, '..', 'public', 'control.html'), 'utf8').catch(() => null),
+    };
     const started = await startHub({ port, host: bind, pageHtml });
     let base = advertise || (bind === '0.0.0.0' ? `http://${lanAddress()}:${port}` : started.url);
     if (tunnel) base = await startTunnel(started.url, tunnel, (line) => print(paint ? C.dim(line) : line));
@@ -289,6 +304,25 @@ export async function cmdCreate(flags) {
   if (pid) print(paint ? C.dim(`中枢已在后台运行（pid ${pid}，端口 ${port}）。`) : '');
 
   const scene = flags.scene ? path.resolve(flags.scene) : null;
+  if (!scene) {
+    // Without a scene the agents can only trade opinions. That is the single
+    // biggest gap between this product and a couple of chatbots arguing, so
+    // say it at the moment the decision is made — not in the README.
+    const warn =
+      '⚠ 没有挂载现场（--scene）。\n' +
+      '  Agent 只能靠通用知识吵，--evidence「带证据不扣精力」等于没有输入源。\n' +
+      '  想让它们真刀真枪，重开一次并加上：--scene <代码或日志目录>';
+    print(paint ? C.yellow(warn) : warn);
+    print('');
+  } else {
+    // A scene that exists but holds three files makes --evidence just as
+    // hollow; the failure is quieter, so check rather than assume.
+    const thin = await sceneLooksThin(scene);
+    if (thin) {
+      print(paint ? C.yellow(`⚠ 现场很小（${thin}）。证据不够，辩论会退化成对喷。`) : `⚠ 现场很小（${thin}）`);
+      print('');
+    }
+  }
   const created = await fetch(`${base.replace(/\/$/, '')}/rooms`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
@@ -327,6 +361,8 @@ export async function cmdCreate(flags) {
   print(paint ? C.green(`\n房间 ${code} 已开。议题：${topic}`) : `\n房间 ${code} 已开。议题：${topic}`);
   if (scene) print(paint ? C.dim(`现场（只读）：${scene}`) : `现场（只读）：${scene}`);
   print(paint ? C.dim(`中枢：${base}    观战页：${base}/`) : `中枢：${base}`);
+  print(paint ? C.yellow(`房主控制台：${base}/r/${code}/control?host=${hostToken}`) : `控制台：${base}/r/${code}/control?host=${hostToken}`);
+  print(paint ? C.dim(`  （这个 URL 含房主令牌，别外发。随时用 arena console 重新打印）`) : '');
   print(paint ? C.dim(`你是 ${join.agentId}。房主令牌已保存在 ~/.arena/config.json（close 房间用）`) : '');
   print(paint ? C.magenta('\n──────────── 复制下面整段发给朋友 ────────────\n') : '\n---- 复制下面整段发给朋友 ----\n');
   print(invite);
@@ -338,6 +374,24 @@ export async function cmdCreate(flags) {
   }
 }
 
+/**
+ * Rough evidence budget of a scene. Cheap on purpose: an agent that cannot
+ * cite a file, a log line or a diff has nothing to put in --evidence.
+ */
+async function sceneLooksThin(root) {
+  const { Scene } = await import('./scene.mjs');
+  try {
+    const { files } = await new Scene(root).list('.', { depth: 3 });
+    const real = files.filter((f) => !f.endsWith('/'));
+    if (real.length === 0) return '一个文件都没有';
+    // Two files of log/code is enough to argue over; one is not an arena.
+    if (real.length < 2) return `只有 ${real.length} 个文件`;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 async function ask(q) {
   print(q);
   return new Promise((resolve) => {
@@ -440,7 +494,7 @@ export async function cmdJoin(flags, positional) {
   print('');
   print(ETIQUETTE.trim());
   print('');
-  print(paint ? C.cyan('现在运行：arena listen') : '现在运行：arena listen');
+  print(paint ? C.cyan('现在运行：arena listen --loop') : '现在运行：arena listen --loop');
 }
 
 export async function cmdListen(flags) {
@@ -476,14 +530,38 @@ export async function cmdListen(flags) {
   }
 
   if (j.timeout) {
-    print(paint ? C.dim('（冷场中… 没有人说话。可以 pass，继续等，或者主动抛个靶子。）') : '（冷场）');
+    // A bare "nothing happened" is what teaches an agent to stop listening.
+    // Name who is silent and why it might be — an idle peer and a peer that
+    // crashed look identical in the member list otherwise.
+    const peers = (j.state?.members || []).filter((m) => m.id !== c.agentId && !m.removed);
+    const siblings = peers.filter((m) => m.status !== 'offline');
+    const stale = siblings.filter((m) => m.stale);
+    if (siblings.length && stale.length === siblings.length) {
+      const names = siblings.map((m) => m.name).join('、');
+      const mins = Math.max(1, Math.round((stale[0].lastSeenAgoMs || 0) / 60000));
+      const msg =
+        `（冷场：${names} 已经 ${mins} 分钟没有任何请求，多半没在监听。）\n` +
+        `  可以 arena say "..." 递纸条，或让对方重新跑 arena listen --loop。`;
+      print(paint ? C.yellow(msg) : msg);
+    } else if (j.state?.members?.some((m) => m.status === 'working')) {
+      print(paint ? C.dim('（冷场：有人在取证，等它。继续挂：arena listen --loop）') : '（冷场，对方在忙）');
+    } else {
+      print(paint ? C.dim('（冷场：在场的人都还活着但没开口。继续挂：arena listen --loop）') : '（冷场）');
+    }
+    if (!flags.once && flags.loop) {
+      print(paint ? C.dim(`  …继续挂在 listen（本次等了 ${timeout}s）`) : '');
+      await new Promise((r) => setTimeout(r, 500));
+      return cmdListen({ ...flags, since: String(q.since), loop: true, once: false });
+    }
     return;
   }
 
   const msgs = (j.messages || []).filter((m) => m.from !== c.agentId);
   const maxSeq = j.seq ?? since;
   const entry = await recall(c.code);
-  await remember(c.code, { ...entry, seenSeq: Math.max(entry?.seenSeq || 0, since) });
+  // Advance to what we were just handed, not to where we started: storing
+  // `since` would replay the same batch on every subsequent listen.
+  await remember(c.code, { ...entry, seenSeq: Math.max(entry?.seenSeq || 0, maxSeq) });
 
   print(paint ? C.bold(`\n━━━ 房间里来了 ${msgs.length} 条新消息（当前 #${maxSeq}）━━━`) : `\n--- 新消息 ${msgs.length} 条（#${maxSeq}）---`);
   for (const m of msgs) print(formatMessage(m));
@@ -500,6 +578,61 @@ export async function cmdListen(flags) {
   print(`  arena listen                ← 吃瓜，继续等`);
 }
 
+/**
+ * Non-blocking snapshot. `listen` blocks for a minute and `watch` never
+ * returns; neither is usable when a human just wants to see what happened
+ * before deciding whether to keep going.
+ */
+export async function cmdPeek(flags) {
+  const c = await clientFor(flags);
+  const entry = await recall(c.code);
+  const seen = Number(entry?.seenSeq || 0);
+  const r = await fetch(c.url('/state'), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-arena-token': c.token },
+    body: JSON.stringify({}),
+  }).then((x) => x.json());
+  if (r.error) throw new Error(r.error);
+
+  const unread = [];
+  if (flags.tail) {
+    const all = await fetch(c.url('/read', { since: 0 }), { headers: { 'x-arena-token': c.token } }).then((x) => x.json());
+    unread.push(...(all.messages || []).slice(-Number(flags.tail)));
+  }
+
+  print(paint ? C.bold(`房间 ${r.code}  ${r.closed ? '【已收官】' : ''}`) : `房间 ${r.code}`);
+  print(`议题：${r.topic}`);
+  print(`进度：#${r.seq}   你已读到：#${seen}   未读：${Math.max(0, r.seq - seen)} 条`);
+  if (r.scene?.root) print(`现场：${r.scene.root}`);
+  print('');
+
+  for (const m of r.members || []) {
+    const tags = [
+      m.isHost ? '★房主' : '',
+      m.muted ? '禁言' : '',
+      m.removed ? '已移出' : '',
+      m.stale ? `失联 ${Math.round((m.lastSeenAgoMs || 0) / 60000)}m` : '',
+    ].filter(Boolean);
+    const you = m.id === c.agentId ? ' ← 你' : '';
+    print(`  ${m.name.padEnd(18)} [${m.role}] MP ${String(m.mp).padStart(2)} ${m.status}${m.note ? ' · ' + m.note : ''}${tags.length ? ' · ' + tags.join(' ') : ''}${you}`);
+  }
+  if (r.board?.length) {
+    print('');
+    print(paint ? C.dim(`黑板：${r.board.map((b) => `${b.key} v${b.version}`).join('  ')}`) : '');
+  }
+  if (unread.length) {
+    print('');
+    print(paint ? C.dim(`最后 ${unread.length} 条：`) : '');
+    for (const m of unread) print(formatMessage(m));
+  }
+  if (r.conclusion) {
+    print('');
+    print(paint ? C.yellow(`收官结论：${r.conclusion}`) : `结论：${r.conclusion}`);
+  }
+  print('');
+  print(paint ? C.dim('继续盯屏：arena listen --loop') : '');
+}
+
 export async function cmdSpeak(flags, positional) {
   const c = await clientFor(flags);
   const text = flags.text || positional.join(' ');
@@ -704,6 +837,14 @@ export async function cmdBridge(flags, positional) {
   });
 }
 
+export async function cmdConsole(flags) {
+  const entry = await recall(flags.room?.toUpperCase());
+  if (!entry) throw new Error('还没进房：先 arena create 或 arena join');
+  if (!entry.hostToken) throw new Error('你不是房主，没有控制台');
+  print(`${entry.base.replace(/\/$/, '')}/r/${entry.code}/control?host=${entry.hostToken}`);
+  print(paint ? C.dim('（含房主令牌，不要发给别人）') : '');
+}
+
 export async function cmdClose(flags) {
   const c = await clientFor(flags, { host: true });
   const r = await c.post('/finish', { agent: c.agentId, reason: flags.reason || '房主关房', conclusion: flags.conclusion || flags.text });
@@ -764,6 +905,9 @@ export const HELP = `arena — 多人 Agent 实时擂台（房主开房，朋友
 
 非回合制循环（每个参赛 Agent）
   arena listen [--since N] [--timeout 60]  阻塞等新消息；返回最新 seq 与全场状态
+  arena listen --loop                      冷场自动重挂，直到有消息或房间收官
+  arena listen --once                      超时就直接返回（不提示继续）
+  arena peek [--tail 5]                    不阻塞看一眼：谁在、多少 MP、未读多少、最后几条
   arena bridge --pane t3 [--dry-run]       装了 herdr-core 时：房间消息自动敲进空闲终端唤醒你
   arena speak --seq N "..."                开火；seq 是你看到的最新序号（乐观锁）
   arena speak --seq N --evidence "..." "..."  带实证开火，不扣精力、回 1 MP
@@ -782,6 +926,7 @@ export const HELP = `arena — 多人 Agent 实时擂台（房主开房，朋友
 收官
   arena finish [--reason "..."] [--conclusion "..."] [--report battle.md]   # 房主吹哨
   arena close [--reason "..."]             房主关房（host token）
+  arena console                            打印房主控制台 URL（改规则/禁言/移人/收官）
   arena rooms                              列出中枢上的房间
   arena watch                              人类教练实时观战（终端）
   arena say "..."                          场外递纸条
@@ -805,8 +950,10 @@ export async function main(argv) {
     host: () => cmdHost(flags),
     create: () => cmdCreate(flags),
     close: () => cmdClose(flags),
+    console: () => cmdConsole(flags),
     join: () => cmdJoin(flags, positional),
     listen: () => cmdListen(flags),
+    peek: () => cmdPeek(flags),
     bridge: () => cmdBridge(flags, positional),
     speak: () => cmdSpeak(flags, positional),
     pass: () => cmdPass(flags, positional),