handmux 0.24.0 → 0.25.0

package/dist/hooks/handmux-notify.sh

@@ -4,8 +4,8 @@
 # stdin = Claude Code 原始 payload(JSON).
 # (resume  = PostToolUse on AskUserQuestion/ExitPlanMode:答完选项/批准计划 → 状态翻回进行中、带所选项。)
 # (permreq = PermissionRequest:真实弹框一出现就发、带 tool_name → 比 permission_prompt 早亮「需要你」。)
-# 只做一件事:把本次事件写进一个本地 JSON 状态文件(键=tmux pane,值=该 pane 最新事件)。不联网、
-# 不依赖服务进程是否在跑 → 永不阻塞 Claude(始终 exit 0)。服务端按需读这个文件(见 claudeEvents.js)。
+# 只做本地落盘:更新 JSON latest state,并在启用时追加有界 Bridge event spool。不联网、
+# 不依赖服务进程是否在跑 → 永不阻塞 Claude(始终 exit 0)。服务端/Connector 稍后消费这些文件。
 # 真正的读-改-写交给同目录的 handmux-write.js(node:真 JSON 解析 + 文件锁,多 pane 并发 hook 不丢更新)。
 CFG="$(dirname "$0")/handmux-notify.env"
 [ -f "$CFG" ] && . "$CFG"
@@ -16,7 +16,49 @@ FILE="${HANDMUX_STATE:-$HOME/.claude/handmux-state.json}"
 TS=$(perl -MTime::HiRes -e 'printf "%.0f", Time::HiRes::time()*1000' 2>/dev/null)
 [ -z "$TS" ] && TS=$(( $(date +%s) * 1000 ))
 HOST=$(hostname 2>/dev/null || printf '')
+# Capture the owning Claude process rather than this short-lived Hook process. The fingerprint lets the
+# Connector reject an offline event after tmux has reused the pane for a different Claude generation.
+# Missing/incomplete identity is intentionally tolerated for older Claude/platform variants: the writer
+# then omits the additive field and the legacy latest-state path keeps working.
+CLAUDE_PID=''
+CLAUDE_STARTED_AT=''
+CLAUDE_TTY=''
+# Claude runs configured hooks asynchronously and may reparent the short-lived shell before it starts, so
+# PPID is not authoritative. Resolve the exact `claude` process on this tmux pane's TTY first;
+# retain ancestor walking only as a fallback for platforms where tmux/targeted ps is unavailable.
+PANE_TTY=$(tmux display-message -p -t "$PANE" '#{pane_tty}' 2>/dev/null || printf '')
+if [ -n "$PANE_TTY" ]; then
+  # During an async Hook Claude may block waiting for the child and temporarily lose the foreground `+`.
+  # Prefer the sole exact process; if more than one exact Claude shares the TTY, require one foreground owner.
+  CLAUDE_PROCESSES=$(ps -t "${PANE_TTY#/dev/}" -o pid=,stat=,comm= 2>/dev/null || printf '')
+  CLAUDE_PID=$(printf '%s\n' "$CLAUDE_PROCESSES" \
+    | awk '$3 == "claude" { count += 1; only = $1 } END { if (count == 1) print only }')
+  if [ -z "$CLAUDE_PID" ]; then
+    CLAUDE_PID=$(printf '%s\n' "$CLAUDE_PROCESSES" \
+      | awk '$3 == "claude" && $2 ~ /\+/ { count += 1; only = $1 } END { if (count == 1) print only }')
+  fi
+fi
+if [ -z "$CLAUDE_PID" ]; then
+  ANCESTOR_PID=$PPID
+  ANCESTOR_DEPTH=0
+  while [ -n "$ANCESTOR_PID" ] && [ "$ANCESTOR_PID" -gt 1 ] 2>/dev/null && [ "$ANCESTOR_DEPTH" -lt 32 ]; do
+    ANCESTOR_COMMAND=$(ps -p "$ANCESTOR_PID" -o comm= 2>/dev/null || printf '')
+    ANCESTOR_COMMAND=${ANCESTOR_COMMAND##*/}
+    if [ "$ANCESTOR_COMMAND" = 'claude' ]; then
+      CLAUDE_PID=$ANCESTOR_PID
+      break
+    fi
+    ANCESTOR_PID=$(ps -p "$ANCESTOR_PID" -o ppid= 2>/dev/null | tr -d ' ')
+    ANCESTOR_DEPTH=$((ANCESTOR_DEPTH + 1))
+  done
+fi
+if [ -n "$CLAUDE_PID" ]; then
+  # `lstart` follows the process locale on macOS; force C so standalone Node can parse it consistently.
+  CLAUDE_STARTED_AT=$(LC_ALL=C ps -p "$CLAUDE_PID" -o lstart= 2>/dev/null || printf '')
+  CLAUDE_TTY=$(ps -p "$CLAUDE_PID" -o tty= 2>/dev/null || printf '')
+fi
 # payload 经 stdin 原样流给 node(不在 shell 里转义,避免坏数据);pane 含 '%' 直接进 JSON 字段,
 # 不再进 URL → 彻底告别旧的 "%110 被 url-decode 丢弃" 那类坑。
-node "$(dirname "$0")/handmux-write.cjs" "$FILE" "$PANE" "$1" "$TS" "$HOST" 2>/dev/null || true
+node "$(dirname "$0")/handmux-write.cjs" "$FILE" "$PANE" "$1" "$TS" "$HOST" \
+  "${HANDMUX_CLAUDE_EVENTS:-}" "$CLAUDE_PID" "$CLAUDE_STARTED_AT" "$CLAUDE_TTY" 2>/dev/null || true
 exit 0

package/dist/hooks/handmux-write.cjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// handmux hook writer. Updates ONE JSON state file keyed by tmux pane id with this pane's latest
-// Claude event:  { "%pane": { ts, src, host, payload }, ... }.  Invoked by handmux-notify.sh:
-//   node handmux-write.cjs <file> <pane> <src> <ts> <host>     (stdin = Claude's raw hook payload JSON)
+// handmux hook writer. Updates one JSON latest-state file keyed by tmux pane and, when configured,
+// appends the same effective lifecycle edge to a bounded durable Connector spool. Invoked by notify.sh:
+//   node handmux-write.cjs <file> <pane> <src> <ts> <host> <event-dir>
+//     [claude-pid] [claude-lstart] [claude-tty]
 //
 // .cjs (not .js): runs standalone via `node <file>`, including from ~/.claude/hooks (no package.json) —
 // .cjs forces CommonJS everywhere; a bare .js under the server tree ("type":"module") would be ESM and
@@ -16,9 +17,37 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const [, , file, pane, src, ts, host = ''] = process.argv;
+const crypto = require('node:crypto');
+
+const [
+  , , file, pane, src, ts, host = '', eventDirectory = '',
+  claudePid = '', claudeStartedAt = '', claudeTty = '',
+] = process.argv;
 if (!file || !pane || !src) process.exit(0);
 
+function processFingerprint() {
+  const pid = Number(String(claudePid).trim());
+  const startedAt = Date.parse(String(claudeStartedAt).trim());
+  const rawTty = String(claudeTty).trim();
+  if (!Number.isSafeInteger(pid) || pid <= 0 || !Number.isFinite(startedAt)
+    || !rawTty || rawTty === '?' || rawTty === '??') return undefined;
+  return {
+    pid,
+    startedAt,
+    tty: rawTty.startsWith('/dev/') ? rawTty : `/dev/${rawTty}`,
+  };
+}
+
+const sourceProcess = processFingerprint();
+
+function sameSourceProcess(previous) {
+  const prior = previous?.process;
+  if (!sourceProcess || !prior) return true; // retain compatibility with rows from older Hook versions
+  return prior.pid === sourceProcess.pid
+    && prior.startedAt === sourceProcess.startedAt
+    && prior.tty === sourceProcess.tty;
+}
+
 let payload = {};
 try { payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { /* unreadable stdin → {} */ }
 
@@ -51,6 +80,116 @@ function ensurePrivateDirectory(directory) {
   }
 }
 
+const MAX_EVENT_SPOOL_BYTES = 16 * 1024 * 1024;
+
+function readEvent(fileName) {
+  try {
+    const value = JSON.parse(fs.readFileSync(fileName, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch { return null; }
+}
+
+function allocateSequence(minimum = 0) {
+  if (!eventDirectory) return null;
+  ensurePrivateDirectory(eventDirectory);
+  const sequenceFile = path.join(eventDirectory, '.sequence');
+  let current = Number.isSafeInteger(minimum) && minimum > 0 ? minimum : 0;
+  try {
+    const parsed = Number(fs.readFileSync(sequenceFile, 'utf8'));
+    if (Number.isSafeInteger(parsed) && parsed >= 0) current = Math.max(current, parsed);
+  } catch { /* first event */ }
+  if (current === 0) {
+    try {
+      for (const name of fs.readdirSync(eventDirectory)) {
+        const match = /^event-(\d+)-/.exec(name);
+        if (match) current = Math.max(current, Number(match[1]) || 0);
+      }
+    } catch { /* empty spool */ }
+  }
+  const next = current + 1;
+  const temporary = `${sequenceFile}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, String(next), { mode: 0o600 });
+  fs.renameSync(temporary, sequenceFile);
+  fs.chmodSync(sequenceFile, 0o600);
+  return next;
+}
+
+function safeSequence(minimum = 0) {
+  try { return allocateSequence(minimum); } catch { return null; }
+}
+
+function writeGapMarker(value) {
+  if (!value || !value.paneId) return;
+  const paneKey = crypto.createHash('sha256').update(String(value.paneId)).digest('hex').slice(0, 16);
+  const marker = path.join(eventDirectory, `gap-${paneKey}.json`);
+  const temporary = `${marker}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify({
+    version: 1,
+    type: 'gap',
+    agent: 'claude',
+    eventId: `claude-gap-${Date.now()}-${process.pid}`,
+    paneId: value.paneId,
+    sessionId: typeof value.sessionId === 'string' ? value.sessionId : undefined,
+    ...(value.process ? { process: value.process } : {}),
+  }), { mode: 0o600 });
+  fs.renameSync(temporary, marker);
+  fs.chmodSync(marker, 0o600);
+}
+
+function pruneEventSpool() {
+  const entries = [];
+  let total = 0;
+  for (const name of fs.readdirSync(eventDirectory)) {
+    if (!/^event-\d+-\d+\.json$/.test(name)) continue;
+    const eventFile = path.join(eventDirectory, name);
+    try {
+      const size = fs.statSync(eventFile).size;
+      entries.push({ name, file: eventFile, size });
+      total += size;
+    } catch { /* concurrently consumed */ }
+  }
+  entries.sort((first, second) => first.name.localeCompare(second.name));
+  const gaps = new Map();
+  for (const entry of entries) {
+    if (total <= MAX_EVENT_SPOOL_BYTES) break;
+    const dropped = readEvent(entry.file);
+    if (dropped?.paneId) gaps.set(dropped.paneId, {
+      paneId: dropped.paneId,
+      sessionId: dropped.sessionId,
+      process: dropped.process,
+    });
+    try { fs.unlinkSync(entry.file); total -= entry.size; } catch { /* already consumed */ }
+  }
+  for (const gap of gaps.values()) writeGapMarker(gap);
+}
+
+function writeBridgeEvent(sequence, rawTs, payload) {
+  if (!eventDirectory || !Number.isSafeInteger(sequence)) return;
+  const sessionId = typeof payload?.session_id === 'string' ? payload.session_id : undefined;
+  const event = {
+    version: 1,
+    type: 'event',
+    agent: 'claude',
+    eventId: `claude-hook-${sequence}`,
+    sequence,
+    paneId: pane,
+    src,
+    sourceOccurredAt: Number(rawTs) || 0,
+    ...(sessionId ? { sessionId } : {}),
+    ...(sourceProcess ? { process: sourceProcess } : {}),
+    payload,
+  };
+  const final = path.join(
+    eventDirectory,
+    `event-${String(sequence).padStart(16, '0')}-${process.pid}.json`,
+  );
+  const temporary = `${final}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(event), { mode: 0o600 });
+  fs.renameSync(temporary, final);
+  fs.chmodSync(final, 0o600);
+  pruneEventSpool();
+}
+
 try {
   ensurePrivateDirectory(path.dirname(file));
   if (fs.existsSync(file)) fs.chmodSync(file, 0o600);
@@ -60,7 +199,12 @@ function update() {
   let obj = {};
   try { const j = JSON.parse(fs.readFileSync(file, 'utf8')); if (j && typeof j === 'object' && !Array.isArray(j)) obj = j; }
   catch { /* fresh / corrupt / half-written → start clean */ }
-  const prevSrc = obj[pane] && obj[pane].src;
+  const previous = obj[pane];
+  const prevSrc = previous && previous.src;
+  const sequenceFloor = Object.values(obj).reduce((maximum, value) => (
+    Number.isSafeInteger(value?.sequence) ? Math.max(maximum, value.sequence) : maximum
+  ), 0);
+  let applied = true;
   if (isIdle) {
     // idle after a resting state (done/needs/nothing) is just the "still waiting" reminder → drop and
     // leave the file as it was (recording it would bump ts and re-surface an already-cleared 已完成).
@@ -68,7 +212,15 @@ function update() {
     // no Stop hook fires there, so idle is the only signal the turn ended. Without this the pane would
     // stay latched at 进行中 forever; treat it as a soft end and clear the pane.
     if (prevSrc === 'prompt' || prevSrc === 'resume') { delete obj[pane]; }
-    else return;                                             // resting → drop without writing
+    else applied = false;                                    // resting → drop without writing
+  } else if (src === 'notify' && payload?.notification_type === 'permission_prompt'
+    && prevSrc === 'permreq'
+    && sameSourceProcess(previous)
+    && (!previous?.payload?.session_id || !payload?.session_id
+      || previous.payload.session_id === payload.session_id)) {
+    // PermissionRequest is the authoritative opening edge. Claude later emits a generic Notification for
+    // the same blocked gate; retaining the earlier detailed row also prevents a second canonical unread.
+    applied = false;
   } else if (src === 'end') {
     // SessionEnd drops the pane on a clean exit. But /clear (and /resume) END the old session AND START a
     // new one — SessionEnd(old) + SessionStart(new) fire as two async hooks, in either order. A late end for
@@ -77,23 +229,36 @@ function update() {
     const curSid = obj[pane] && obj[pane].payload && obj[pane].payload.session_id;
     const endSid = payload && payload.session_id;
     if (!curSid || !endSid || curSid === endSid) delete obj[pane];
+    else applied = false;
   } else {
-    obj[pane] = { ts: Number(ts) || 0, src, host, payload };
+    // sequence is allocated under the same pane-state lock, so independently spawned async hooks share
+    // one durable source order. Existing readers ignore the additive field.
+    const sequence = safeSequence(sequenceFloor);
+    obj[pane] = {
+      ts: Number(ts) || 0, src, host, payload, agent: 'claude',
+      ...(sourceProcess ? { process: sourceProcess } : {}),
+      ...(sequence === null ? {} : { sequence }),
+    };
   }
+  if (!applied) return;
+  const sequence = src === 'end' || isIdle ? safeSequence(sequenceFloor) : obj[pane]?.sequence;
   const tmp = `${file}.${process.pid}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify(obj), { mode: 0o600 });
   fs.renameSync(tmp, file);                                   // atomic: a torn write can't corrupt the file
   fs.chmodSync(file, 0o600);
+  try { writeBridgeEvent(sequence, ts, payload); } catch { /* latest snapshot still recovers */ }
 }
 
 const lock = `${file}.lock`;
 let held = false;
-for (let i = 0; i < 60 && !held; i++) {                       // ~0.9s budget, then write lockless (best-effort)
+for (let i = 0; i < 60 && !held; i++) {                       // ~0.9s budget; never corrupt order locklessly
   try { fs.closeSync(fs.openSync(lock, 'wx', 0o600)); held = true; } // O_EXCL → atomic "I hold it"
   catch {
     try { if (Date.now() - fs.statSync(lock).mtimeMs > 3000) fs.unlinkSync(lock); } catch { /* steal a stale lock */ }
     nap(15);
   }
 }
-try { update(); } catch { /* best effort */ }
-if (held) { try { fs.unlinkSync(lock); } catch { /* ignore */ } }
+if (held) {
+  try { update(); } catch { /* best effort */ }
+  try { fs.unlinkSync(lock); } catch { /* ignore */ }
+}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -22,13 +22,14 @@
     "pwa"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.16.0"
   },
   "bin": {
     "handmux": "bin/handmux.js"
   },
   "files": [
     "bin/handmux.js",
+    "bin/node-version.js",
     "dist",
     "README.md",
     "README.zh-CN.md",
@@ -65,7 +66,7 @@
     "@types/busboy": "^1.5.4",
     "@types/compression": "^1.8.1",
     "@types/express": "4.17.25",
-    "@types/node": "20.19.43",
+    "@types/node": "22.20.1",
     "@types/supertest": "7.2.1",
     "@types/web-push": "^3.6.4",
     "@types/ws": "^8.18.1",
@@ -74,6 +75,12 @@
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {
+      "version": "0.25.0",
+      "date": "2026-09-01",
+      "zh": "Pi 原生接入 · 多 Agent 对话更可靠",
+      "en": "Native Pi support · more reliable agent chat"
+    },
     {
       "version": "0.24.0",
       "date": "2026-08-11",
@@ -115,12 +122,6 @@
       "date": "2026-07-27",
       "zh": "实时终端长时间运行更流畅",
       "en": "Smoother long-running live terminals"
-    },
-    {
-      "version": "0.20.1",
-      "date": "2026-07-26",
-      "zh": "聊天发送修复 · 电脑键盘不中断",
-      "en": "Reliable chat sending · uninterrupted desktop input"
     }
   ]
 }