handmux 0.5.0

package/src/tmux/commands.js

@@ -0,0 +1,223 @@
+import { execFile } from 'node:child_process';
+import os from 'node:os';
+
+export const isPaneId = (s) => typeof s === 'string' && /^%\d+$/.test(s);
+export const isWindowId = (s) => typeof s === 'string' && /^@\d+$/.test(s);
+export const isSessionId = (s) => typeof s === 'string' && /^\$\d+$/.test(s);
+
+// Letters, digits and hyphens only (1-16 chars). A positive allowlist sidesteps tmux's target
+// syntax entirely (no '.'/':' separators, no whitespace, no control chars) and is trivial to
+// mirror on the client. Only NEW session names are validated — binding an existing PC-made name
+// (which may contain spaces) checks existence first and never calls this.
+export const isValidSessionName = (s) =>
+  typeof s === 'string' && /^[A-Za-z0-9-]{1,16}$/.test(s);
+
+// Optional startup command run in a freshly-created window/session (e.g. "claude"). It's typed via
+// send-keys + Enter, so it must be a single line: reject control chars (newline/CR/tab included) and
+// cap the length. No shell-arg restriction — it runs in the new shell exactly as if typed, same trust
+// model as the existing sendText. Empty means "no command" and is handled by the caller, not here.
+export const isValidStartupCmd = (s) =>
+  typeof s === 'string' && s.length > 0 && s.length <= 200 && [...s].every((c) => { const n = c.charCodeAt(0); return n >= 0x20 && n !== 0x7f; });
+
+export function runTmux(args) {
+  return new Promise((resolve, reject) => {
+    execFile('tmux', args, { maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) reject(new Error(stderr?.toString() || err.message));
+      else resolve(stdout.toString());
+    });
+  });
+}
+
+const lines = (out) => out.split('\n').filter((l) => l.length > 0);
+
+export async function listSessions() {
+  const out = await runTmux(['list-sessions', '-F', '#{session_id}\t#{session_name}']);
+  return lines(out).map((l) => { const [id, name] = l.split('\t'); return { id, name }; });
+}
+
+export async function listWindows(sessionId) {
+  const out = await runTmux(['list-windows', '-t', sessionId, '-F', '#{window_id}\t#{window_name}\t#{window_active}\t#{window_panes}']);
+  return lines(out).map((l) => {
+    const [id, name, active, panes] = l.split('\t');
+    return { id, name, active: active === '1', panes: Number(panes) };
+  });
+}
+
+export async function listPanes(windowId) {
+  const out = await runTmux(['list-panes', '-t', windowId, '-F', '#{pane_id}\t#{pane_active}\t#{pane_width}\t#{pane_height}\t#{pane_current_command}\t#{pane_current_path}']);
+  return lines(out).map((l) => {
+    const [id, active, width, height, command, cwd] = l.split('\t');
+    return { id, active: active === '1', width: Number(width), height: Number(height), command, cwd };
+  });
+}
+
+// All live pane ids across every session — used to reconcile the in-memory Claude paneState against
+// reality. A hard-killed pane fires no hook, so its last state would otherwise linger as a ghost.
+export async function listPaneIds() {
+  return lines(await runTmux(['list-panes', '-a', '-F', '#{pane_id}']));
+}
+
+// Every live pane across all sessions WITH its foreground command AND its tmux location, in ONE call.
+// getStates uses this to (a) catch "pane alive but Claude exited" (cmd flips from 'claude' back to the
+// shell — a hard kill / crash / Ctrl-C-out fires no SessionEnd yet the shell keeps the pane, so it
+// still EXISTS) and (b) resolve each recorded pane to its session/window for the inbox roster without a
+// per-pane display-message. The hook only records the pane id; location comes from here, always fresh.
+export async function listLivePanes() {
+  return lines(await runTmux(['list-panes', '-a', '-F',
+    '#{pane_id}\t#{pane_current_command}\t#{session_name}\t#{window_id}\t#{window_name}']))
+    .map((l) => {
+      const [id, cmd, session, window, windowName] = l.split('\t');
+      return { id, cmd, session, window, windowName };
+    });
+}
+
+// -N preserves trailing whitespace. Without it, capture-pane trims trailing cells at each line
+// end — including background-colored padding — which both drops the right-hand part of a
+// full-width highlight (Claude Code's sent-message bar) AND loses the SGR reset that closes the
+// background, so the highlight bleeds onto the rows below when re-rendered. With -N the capture
+// faithfully reproduces the pane, so the client can write it verbatim (see prepareSeed).
+export async function capturePane(paneId, linesBack) {
+  return runTmux(['capture-pane', '-p', '-e', '-N', '-S', String(-Math.abs(linesBack)), '-t', paneId]);
+}
+
+// Size AND cursor in one display-message (capture-pane carries neither the cursor position nor its
+// visibility — it snapshots cells only — so we read them here for the client to re-place xterm's own
+// cursor onto Claude's input cell). cursor_x/cursor_y are 0-based, relative to the visible screen;
+// cursor_flag is DECTCEM visibility (1 while Claude accepts input, 0 while it's working / in a dialog).
+export async function paneInfo(paneId) {
+  const out = await runTmux(['display-message', '-p', '-t', paneId,
+    '#{pane_width}\t#{pane_height}\t#{cursor_x}\t#{cursor_y}\t#{cursor_flag}']);
+  const [width, height, cx, cy, cflag] = out.trim().split('\t');
+  return {
+    width: Number(width), height: Number(height),
+    cursorX: Number(cx), cursorY: Number(cy), cursorVisible: cflag === '1',
+  };
+}
+
+// Resolve a pane to its tmux session name + window for routing a notification back to it. The hook
+// gives us only $TMUX_PANE; this turns "%263" into the session/window the phone navigates by.
+export async function paneLocation(paneId) {
+  const out = await runTmux(['display-message', '-p', '-t', paneId,
+    '#{session_name}\t#{window_id}\t#{window_name}']);
+  const [session, windowId, windowName] = out.trim().split('\t');
+  return { session, window: windowId, windowName };
+}
+
+export async function sendText(paneId, text) {
+  await runTmux(['send-keys', '-t', paneId, '-l', '--', text]);
+}
+
+export async function sendEnter(paneId) {
+  await runTmux(['send-keys', '-t', paneId, 'Enter']);
+}
+
+export async function sendKey(paneId, key) {
+  await runTmux(['send-keys', '-t', paneId, key]);
+}
+
+// Force the window to an explicit width (and optionally height) so tmux reflows to it. This
+// sets the window-size option to `manual`, so it sticks (and applies to every client on this
+// window — including the PC) until restoreWindowSize is called. Pass rows = null to change
+// only the column count and leave the height untouched.
+export async function resizeWindow(windowId, cols, rows) {
+  const args = ['resize-window', '-t', windowId, '-x', String(cols)];
+  if (rows != null) args.push('-y', String(rows));
+  await runTmux(args);
+}
+
+// Hand sizing back to the attached clients (tmux default), so the PC's terminal dictates
+// the window size again instead of the phone-sized grid left by resizeWindow.
+export async function restoreWindowSize(windowId) {
+  await runTmux(['set-window-option', '-t', windowId, 'window-size', 'latest']);
+}
+
+// Resize just one pane's width inside its window (siblings absorb the difference; the window
+// total is unchanged). Use this for a pane in a split — resizing the whole window would
+// shrink every pane. A lone pane can't be resized this way (it fills the window).
+export async function resizePane(paneId, cols) {
+  await runTmux(['resize-pane', '-t', paneId, '-x', String(cols)]);
+}
+
+// The window's exact pane arrangement, captured so "restore" can put a split back the way it
+// was after resizePane changed the ratio. resizePane doesn't touch window size, so window-size
+// latest alone can't undo it — select-layout with this string does.
+export async function getWindowLayout(windowId) {
+  const out = await runTmux(['display-message', '-p', '-t', windowId, '#{window_layout}']);
+  return out.trim();
+}
+
+export async function applyWindowLayout(windowId, layout) {
+  await runTmux(['select-layout', '-t', windowId, layout]);
+}
+
+// -d: detached (the node server has no tty). -c cwd (defaults to $HOME): start dir for the session.
+// -P -F prints the new session id so the caller can confirm/route. A duplicate name makes tmux
+// error (runTmux rejects) — the route pre-checks and returns a clean 409 before reaching here.
+// Self-guard the name even though the route validates first: this is an exported boundary to tmux,
+// and a name with target-syntax chars ('$', ':', …) would create a hard-to-address session.
+export async function newSession(name, cwd, cmd) {
+  if (!isValidSessionName(name)) throw new Error(`invalid session name: ${JSON.stringify(name)}`);
+  const out = await runTmux(['new-session', '-d', '-s', name, '-c', cwd || os.homedir(), '-P', '-F', '#{session_id}']);
+  const id = out.trim(); // e.g. "$7"
+  if (cmd) await runStartupCmd(id, cmd); // auto-run the startup command in the new session's first pane
+  return id;
+}
+
+// Type a startup command into a freshly-created window/session and press Enter — same path as a user
+// typing it. The target ($id / @id) resolves to the new shell's active pane. Runs inside the shell (we
+// don't pass it to new-window/new-session as the pane command) so the pane survives the command exiting.
+async function runStartupCmd(target, cmd) {
+  await sendText(target, cmd);
+  await sendEnter(target);
+}
+
+// Read a pane's working directory, so a new window can open in the dir you're working in.
+export async function paneCurrentPath(paneId) {
+  const out = await runTmux(['display-message', '-p', '-t', paneId, '#{pane_current_path}']);
+  return out.trim();
+}
+
+// -d: don't steal the active window from the PC (the phone navigates to it itself). -c: start dir
+// (omitted when cwd is falsy → tmux uses the session default). -n: window name (omitted when falsy →
+// tmux auto-names after the running command). -P -F prints the new window id.
+export async function newWindow(sessionId, cwd, name, cmd) {
+  const args = ['new-window', '-d', '-t', sessionId, '-P', '-F', '#{window_id}'];
+  if (cwd) args.push('-c', cwd); // tmux accepts -c in any position; push mirrors resizeWindow's style
+  if (name) args.push('-n', name);
+  const id = (await runTmux(args)).trim(); // e.g. "@32"
+  if (cmd) await runStartupCmd(id, cmd); // auto-run the startup command in the new window's pane
+  return id;
+}
+
+// rename-session keeps the session's $id — only the name changes. Self-guard the name (exported
+// boundary to tmux; a name with target-syntax chars would create a hard-to-address session). A
+// duplicate name makes tmux error (runTmux rejects); the route pre-checks and returns a clean 409.
+export async function renameSession(id, name) {
+  if (!isValidSessionName(name)) throw new Error(`invalid session name: ${JSON.stringify(name)}`);
+  await runTmux(['rename-session', '-t', id, name]);
+}
+
+// rename-window sets the name manually (and implicitly turns off that window's automatic-rename,
+// so the chosen name sticks instead of tracking the running command — the expected tmux behavior).
+export async function renameWindow(id, name) {
+  if (!isValidSessionName(name)) throw new Error(`invalid window name: ${JSON.stringify(name)}`);
+  await runTmux(['rename-window', '-t', id, name]);
+}
+
+// The number of windows in the window's session. The delete guard refuses to kill the last one
+// (killing it would take the whole session with it).
+export async function sessionWindowCount(id) {
+  const out = await runTmux(['display-message', '-p', '-t', id, '#{session_windows}']);
+  return Number(out.trim());
+}
+
+export async function killWindow(id) {
+  await runTmux(['kill-window', '-t', id]);
+}
+
+// Swap two windows' positions (indices) within a session. -d keeps the active window unchanged so
+// reordering from the phone doesn't yank the PC's focus to the swapped window. The window ids are
+// unchanged — only their order in list-windows flips.
+export async function swapWindows(a, b) {
+  await runTmux(['swap-window', '-d', '-s', a, '-t', b]);
+}

package/src/trimCapture.js

@@ -0,0 +1,28 @@
+// capture-pane faithfully includes the empty grid below the cursor: a fresh shell draws its prompt
+// at the TOP of the pane and leaves every row below it blank, so the capture is "prompt + a wall of
+// blank rows". The phone bottom-anchors the capture, so that blank tail lands at the bottom of the
+// screen and pushes the real content above the viewport — you open a session and see nothing, and
+// have to scroll up (which pauses the live refresh) to find it.
+//
+// Fix at the source: cap the trailing run of blank rows so the last content row anchors near the
+// bottom. We apply this BEFORE hashing/sending, so the change-hash, the transferred body, and the
+// client's render + at-bottom logic all key off the same trimmed capture.
+//
+// A row counts as blank only if it has no glyph AND no SGR escape — a shaded/full-width padding row
+// (e.g. Claude Code's grey message bar) carries \x1b and is NEVER trimmed here; that stays for the
+// client's trimTrailingShadow (and such boxes are never the very bottom of the pane anyway).
+export const MAX_TRAILING_BLANK = 3;
+
+const isBlank = (row) => row === '' || (/^[ \t]*$/.test(row) && !row.includes('\x1b'));
+
+export function capTrailingBlankRows(ansi, max = MAX_TRAILING_BLANK) {
+  // capture-pane terminates every row with \n (including a trailing one). Peel that off so split
+  // gives exactly the rows, then restore it so the output keeps capture-pane's shape (prepareSeed
+  // drops a single trailing newline downstream).
+  const hadNL = ansi.endsWith('\n');
+  const rows = (hadNL ? ansi.slice(0, -1) : ansi).split('\n');
+  let end = rows.length;
+  while (end > 0 && isBlank(rows[end - 1])) end -= 1;
+  if (rows.length - end > max) rows.length = end + max;
+  return rows.join('\n') + (hadNL ? '\n' : '');
+}

package/src/uploadTypes.js

@@ -0,0 +1,28 @@
+// Extension allow-list for uploads. By extension only (not magic bytes) — this is a "be tidy"
+// guard, not a trust boundary (a token holder can write anything from the terminal anyway; see spec
+// threat model). Override the whole set with HANDMUX_UPLOAD_EXTS (comma-separated).
+export const DEFAULT_UPLOAD_EXTS = new Set([
+  // images
+  'jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'bmp', 'heic', 'heif', 'avif', 'ico', 'tiff',
+  // text / code
+  'txt', 'md', 'markdown', 'rst', 'log', 'csv', 'tsv', 'json', 'yaml', 'yml', 'toml', 'ini',
+  'conf', 'xml', 'html', 'htm', 'css', 'js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'py', 'rb', 'go',
+  'rs', 'java', 'c', 'h', 'cpp', 'sh',
+  // documents / office
+  'pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'odt', 'ods', 'odp', 'rtf',
+]);
+
+// Read HANDMUX_UPLOAD_EXTS (comma-separated) → a Set, normalising leading dots/case/whitespace.
+// Blank/absent → the default set (returned by reference so callers can `=== DEFAULT_UPLOAD_EXTS`).
+export function loadUploadExts(env = process.env) {
+  const raw = env.HANDMUX_UPLOAD_EXTS;
+  if (!raw || !raw.trim()) return DEFAULT_UPLOAD_EXTS;
+  const exts = raw.split(',').map((s) => s.trim().replace(/^\.+/, '').toLowerCase()).filter(Boolean);
+  return new Set(exts);
+}
+
+// True if `name`'s final extension is in `exts`. No extension → false.
+export function isAllowedUploadExt(name, exts) {
+  const m = /\.([A-Za-z0-9]+)$/.exec(name || '');
+  return m ? exts.has(m[1].toLowerCase()) : false;
+}

package/tmux/README.md

@@ -0,0 +1,77 @@
+# tmux 页签 Claude 状态标记（事件驱动）
+
+给本机 tmux 的**每个 window 页签**前缀一个状态色点,SSH attach 时一眼看到哪个窗在跑、跑完了、还是在等你。**色值与手机端收件箱一致**(`web/src/styles.css` 的 `.inbox-dot`):
+
+| 状态 | 色点 | 何时变 |
+|---|---|---|
+| 需要你 | 🟠 橙 `#e0a020` | 出现权限/选择弹框(`permreq` / `permission_prompt`) |
+| 进行中 | 🔵 蓝 `#2f6fed` **闪** | 你发了 prompt / 答完选择(`prompt` / `resume`)。`blink` 需终端支持(iTerm2) |
+| 已完成 | 🟢 绿 `#2e7d46` | Claude 结束一轮(`stop`) |
+| 无 claude / 会话结束 | (无点) | `end` 清空 |
+
+选中的窗页签用**浅灰底 + 深色粗体**(`window-status-current-style`)明显区分。
+
+## 架构:事件驱动,不是轮询(这是重点)
+
+```
+Claude 事件 → hook(handmux-write.cjs)→ tmux set-option -w @claude_dot '#[fg=…]●'
+                                          ↓
+              window-status-format = '#{@claude_dot}#I:#W'  ← 纯查表,不跑任何 shell
+```
+
+- **写**:`server/hooks/handmux-write.cjs`(Claude hook,本来就在每个事件时跑、写状态文件)在末尾顺手把这次事件对应的色点 markup 写进**该 pane 所在窗**的 `@claude_dot` 选项(`set-option -w -t <pane>` 能直接定位到窗)。best-effort + 1s 超时,不在 tmux 就静默忽略,永不阻塞 Claude。
+- **显示**:`~/.tmux.conf` 的 `window-status-format` 只引用 `#{@claude_dot}`(tmux 会解释里面的 `#[fg=…]` 颜色,实测真彩 hex 与手机端逐字节一致)。**格式里没有 `#()`,所以每次状态栏重绘零子进程、零开销。**
+- **填底**:`tmux/claude-tab-seed.py` 一次性把当前所有 claude 窗的点按状态文件填上 —— tmux 启动 / `source-file` 时由 `~/.tmux.conf` 的 `run-shell` 调一次,重新部署后手动跑一次。之后全交给 hook。
+
+**只有状态真变化(hook 触发那一刻)才写一次 `@claude_dot` → 才重绘一次。稳态零重绘。**
+
+## 踩过的坑(别再走这两条死路)
+
+这套方案是第三版,前两版把整个 tmux 拖到「整屏卡 + 光标狂闪」,根因都已实测坐实:
+
+1. **不要在 `window-status-format` 里放 `#(脚本 …)` 主动查询。** tmux 会对【每个客户端 × 每个窗 × 每次重绘】都跑一遍脚本(spawn jq / list-panes),十几个 SSH 客户端一起跑必卡;而且 `#()` 每次返回都触发重绘 → 一直闪。**改成事件驱动:hook 推、状态栏只查表。**(隔离实测:`#{@claude_dot}` 格式空闲 3 秒输出 **0 字节**;`#()` 格式是几十~上百字节/秒不停。)
+2. **不要为了存“看过/状态”在状态栏渲染路径里写 tmux 选项。** 实测**写任何 tmux 选项都会强制整条状态栏重绘**(空闲 2s 输出 0 字节,连打 12 次 `set-option` 输出 1593 字节)。在渲染路径里每帧写 = 无休止重绘 = 卡 + 光标闪。写选项只能由**低频的事件**(hook)来做,稳态绝不写。
+
+## “已完成”绿点什么时候消失
+
+两条途径,都不在渲染路径里、都只在你的动作那一刻各跑一次,不卡:
+
+1. **看过即清** —— 你切到/聚焦那个窗时,`tmux/claude-tab-seen.sh` 把该窗的绿点清掉(进行中蓝、需要你橙是当前态,不清)。由两个 tmux 钩子触发:
+   - `after-select-window`：会话内换 window(点页签 / prefix+数字 / next-window）。
+   - `pane-focus-in`（需 `focus-events on`）：切到别的 SSH 终端、让某个窗重新获得焦点 —— 补上 after-select-window 覆盖不到的「跨终端切会话」。实测 iTerm2 等会上报焦点,此钩子能触发。
+2. **接着干自然清** —— 你在该窗发下一条 prompt → `prompt` 事件 → 点变蓝(进行中)。
+
+清掉后若 Claude 再结束一轮,hook 会重新把绿点写回来;只瞥不切、也不操作,则绿点保留(它确实还停在已完成)。
+
+## 安装
+
+> 需要 tmux ≥ 3.0 —— `window-status-format` 里引用用户选项 `#{@claude_dot}` 自 3.0 起才支持;更老的
+> tmux 不会显示色点(会忽略或原样吐出 `#{@claude_dot}`)。
+
+`handmux hooks install`(交互式)会把整套**自动**装好,无需手动改 conf:
+
+1. **hook(写点)**:脚本拷进 `~/.claude/hooks/`、注册事件。每次现调,改了即生效,已在跑的 claude 无需重启。
+2. **显示 + seed + 看过即清**:把 `claude-tab-seed.py` / `claude-tab-seen.sh` 拷进 **`~/.handmux/tmux/`**,并往 `~/.tmux.conf` 末尾追加下面这段**带标记的块**(引用那个稳定路径):
+
+```tmux
+# >>> handmux claude-dot >>>
+set -g status-style 'bg=colour236,fg=colour250'   # 默认 bg=green 会吞掉绿点,改中性深灰
+set -g window-status-current-style 'bg=colour248,fg=colour234,bold'   # 选中的窗:浅灰底+深字
+set -g window-status-format '#{@claude_dot}#I:#W#{?window_flags,#{window_flags}, }'
+set -g window-status-current-format '#{@claude_dot}#I:#W#{?window_flags,#{window_flags}, }'
+set -g focus-events on
+run-shell -b '~/.handmux/tmux/claude-tab-seed.py'
+set-hook -g after-select-window 'run-shell -b "~/.handmux/tmux/claude-tab-seen.sh #{window_id}"'
+set-hook -g pane-focus-in 'run-shell -b "~/.handmux/tmux/claude-tab-seen.sh #{window_id}"'
+# <<< handmux claude-dot <<<
+```
+
+`tmux source-file ~/.tmux.conf` 生效。这是**共享 tmux server** 的全局设置,所有 attach 的客户端(含 PC 本机)都会一起变;手机 web 不受影响(它抓的是 pane 内容,不是状态栏)。
+
+> 脚本走 **`~/.handmux/tmux/`**(实际写入的是展开后的绝对路径,随 `$HOME`、不随 handmux 装在哪),所以仓库搬家/改名都不会断 —— 这正是早期 `…/tmux-web/tmux/…` 写死 repo 路径后 `returned 127` 的教训。已自己手写过配置(conf 里已含 `@claude_dot`)的人会被识别为「已配置」,不会被覆盖。
+
+## 调一调 / 卸载
+
+- **颜色**:同时改 `handmux-write.cjs` 的 `claudeDot()` 和 `claude-tab-seed.py` 的 `DOT`(两处保持一致),hex 同手机端。
+- **不想要「进行中」闪**:两处把 `,blink` 删掉。
+- **卸载**:删 `~/.tmux.conf` 里 `# >>> handmux claude-dot >>>` 到 `# <<< handmux claude-dot <<<` 整段 + `tmux source-file`;清残留点 `for w in $(tmux list-windows -a -F '#{window_id}'); do tmux set-option -uw -t $w @claude_dot; done`;想彻底停止写点,直接 `handmux hooks uninstall`(移除 hook,不再写 `@claude_dot`)。

package/tmux/claude-tab-seed.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+# claude-tab-seed.py —— 一次性把【当前所有 Claude 窗】的状态色点写进各窗的 @claude_dot 选项。
+#
+# 平时这些点由 Claude hook（server/hooks/handmux-write.cjs）在状态变化那一刻事件驱动地写，不轮询、
+# 不卡。但 hook 只在“有新事件”时写，所以本脚本负责冷启动填底：
+#   - tmux 启动 / `source-file ~/.tmux.conf` 时由 `run-shell` 调一次；
+#   - 重新部署后手动跑一次。
+# 之后就交给 hook。整个机制零 `#()`、零轮询 —— 详见 tmux/README.md。
+#
+# 色值/分类与 hook 里的 claudeDot 保持一致；与手机端 web/src/styles.css 的 .inbox-dot 同色。
+
+import json, os, subprocess, sys
+
+F = os.environ.get("CLAUDE_STATE_FILE",
+                   os.path.expanduser("~/.handmux/claude-state.json"))
+try:
+    state = json.load(open(F))
+except Exception:
+    sys.exit(0)
+
+def tmux(*a):
+    try:
+        return subprocess.run(["tmux", *a], capture_output=True, text=True, timeout=5).stdout
+    except Exception:
+        return ""
+
+def classify(e):
+    s = e.get("src")
+    if s == "stop": return "done"
+    if s in ("prompt", "resume"): return "working"
+    if s == "permreq": return "needs"
+    if s == "notify" and (e.get("payload") or {}).get("notification_type") == "permission_prompt":
+        return "needs"
+    return None
+
+RANK = {"needs": 3, "done": 2, "working": 1}
+DOT = {
+    "needs":   "#[fg=#e0a020]●#[default] ",   # 橙
+    "done":    "#[fg=#2e7d46]●#[default] ",   # 绿
+    "working": "#[fg=#2f6fed,blink]●#[default] ",  # 蓝闪
+}
+
+# window_id -> 最高优先级 kind
+top = {}
+for line in tmux("list-panes", "-a", "-F", "#{pane_current_command} #{pane_id} #{window_id}").splitlines():
+    parts = line.split()
+    if len(parts) < 3 or parts[0] != "claude":
+        continue
+    _, pane, win = parts[0], parts[1], parts[2]
+    e = state.get(pane)
+    if not e:
+        continue
+    k = classify(e)
+    if not k:
+        continue
+    if RANK[k] > RANK.get(top.get(win, ""), 0):
+        top[win] = k
+
+# 写当前点；并清掉已不再有 claude 状态的窗的残留点
+for line in tmux("list-windows", "-a", "-F", "#{window_id}").splitlines():
+    win = line.strip()
+    if not win:
+        continue
+    if win in top:
+        tmux("set-option", "-w", "-t", win, "@claude_dot", DOT[top[win]])
+    elif tmux("show-options", "-wv", "-t", win, "@claude_dot").strip():
+        tmux("set-option", "-uw", "-t", win, "@claude_dot")

package/tmux/claude-tab-seen.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# claude-tab-seen.sh <window_id> —— 你切到/聚焦某个窗时调用:若该窗当前是「已完成」绿点,清掉它
+# (看过即清)。进行中(蓝)/需要你(橙)是当前态、不清。
+#
+# 由 ~/.tmux.conf 的 after-select-window / pane-focus-in 两个钩子触发 —— 只在你切窗、切 pane、
+# 切终端这些【用户动作】时各跑一次,不在状态栏渲染路径里,所以不轮询、不卡。清绿点会写一次
+# @claude_dot → 触发一次重绘,这是“状态真变了(你看过了)”，正是该重绘的时刻。
+#
+# 之后若 Claude 再结束一轮,hook 会重新把绿点写回来;只瞥不切则绿点保留。
+W=$1
+[ -n "$W" ] || exit 0
+case "$(tmux show-options -wv -t "$W" @claude_dot 2>/dev/null)" in
+  *2e7d46*) tmux set-option -w -t "$W" @claude_dot '' 2>/dev/null ;;   # 绿(已完成)→ 清(设空串)
+esac