handmux 0.16.0 → 0.17.3

package/public/index.html

@@ -48,8 +48,8 @@
       @keyframes bootDot { 0%,100% { opacity: .22; transform: translateY(0); } 40% { opacity: 1; transform: translateY(-3px); } }
       @media (prefers-reduced-motion: reduce) { .boot-glow, .boot-dots i { animation: none; opacity: .8; } }
     </style>
-    <script type="module" crossorigin src="/assets/index-Cf-WEkt5.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-D5UQBvph.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-D5UQBvph.css"></noscript>
+    <script type="module" crossorigin src="/assets/index-Ddagv-Lc.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BT03K2MQ.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-BT03K2MQ.css"></noscript>
   </head>
   <body>
     <div id="boot-splash" aria-hidden="true">

package/public/sw.js

@@ -96,16 +96,28 @@ self.addEventListener('notificationclick', (event) => {
   event.notification.close();
   const d = event.notification.data || {};
   const e = encodeURIComponent;
-  const url = d.url
-    ? d.url
-    : d.session
-      ? `/#/s/${e(d.session)}/w/${e(d.window || '')}/p/${e(d.pane || '')}`
-      : '/';
+  // A deep-link target is present only for a session push or an explicit `--url`. A plain manual push
+  // (`handmux push <title> <body>`) has neither → hasTarget=false, and we must NOT navigate an open
+  // client: url would be '/', and navigating an app sitting at '/#/s/…' to '/' is a same-document
+  // navigation that pushes a spurious history entry above the app (Back then needs an extra press —
+  // reads as "a nested page opened"). Just focus it. openWindow still needs a concrete url below.
+  const hasTarget = !!(d.inboxId || d.url || d.session);
+  const url = d.inboxId
+    ? `/#/inbox/${e(d.inboxId)}`
+    : d.url
+      ? d.url
+      : d.session
+        ? `/#/s/${e(d.session)}/w/${e(d.window || '')}/p/${e(d.pane || '')}`
+        : '/';
   event.waitUntil((async () => {
     const all = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
     const open = all.find((c) => 'focus' in c);
     if (open) {
       await open.focus();
+      if (!hasTarget) return; // no deep-link → focus alone, never push a history entry
+
+      if (d.inboxId) { open.postMessage({ type: 'navigate-inbox', id: d.inboxId }); return; }
+
       // A session deep-link opens IN PLACE via postMessage (the app switches sessions and writes the hash
       // with replaceState). We deliberately do NOT navigate() an already-open client for this: a
       // same-document navigation pushes a spurious history entry ABOVE the app, so Back then needed an

package/src/agents/claude.js

@@ -10,7 +10,64 @@
 //   sessions       cwd → session resolution + the `resume` command, for orphan takeover
 import path from 'node:path';
 import os from 'node:os';
-import { resolveEncodedDirSession, isSessionUuid } from './scanUtils.js';
+import { promises as fsp } from 'node:fs';
+import { resolveEncodedDirSession, isSessionUuid, normTty } from './scanUtils.js';
+
+// The NATIVE installer names the real binary by version (~/.local/share/claude/versions/2.1.196 —
+// ~/.local/bin/claude is only a symlink to it), and tmux #{pane_current_command} follows that basename
+// ("2_1_196", dots sanitized to underscores) instead of "claude". ps can't tie it: ps `comm` shows the
+// process's self-set title ("claude"), which does NOT match tmux's report (verified live on a native-
+// install machine). Matching any semver-shaped name would misidentify any version-named binary, so we
+// corroborate with the process's REAL executable path (`lsof -d txt` on macOS, /proc/<pid>/exe on
+// Linux): a pid on the pane's tty whose exe BASENAME equals tmux's version comm, and whose path carries
+// "claude" — every official install layout carries it (Caskroom/claude-code@latest, .local/share/
+// claude/versions, node_modules/@anthropic-ai/claude-code, …), version- and layout-proof, while a
+// foreign version-named binary's path doesn't. Only then is the pane's cmd normalized to 'claude', so
+// every downstream match (identity + liveness) stays exact-name. Verdicts are cached per (tty, cmd) in
+// an injected Map — a cache miss costs one ps + one lsof per candidate pane, once per version per pane.
+const VERSION_COMM_RE = /^\d+[._]\d+[._]\d+$/;
+const CLAUDE_PATH_RE = /claude/;
+
+// The real executable path of a pid: first txt entry from lsof (resolves symlinks → the actual binary),
+// falling back to /proc on Linux where lsof output may be restricted. '' when unknowable.
+async function exePath(run, pid) {
+  const out = await run('lsof', ['-a', '-p', String(pid), '-d', 'txt', '-Fn']);
+  for (const line of String(out).split('\n')) if (line[0] === 'n') return line.slice(1).trim();
+  try { return await fsp.readlink(`/proc/${pid}/exe`); } catch { return ''; }
+}
+
+export async function resolveVersionedComms(panes, run, verdicts = new Map()) {
+  const candidates = panes.filter((p) => p && p.tty && VERSION_COMM_RE.test(p.cmd || ''));
+  if (!candidates.length) return panes;
+  const key = (p) => `${normTty(p.tty)}|${p.cmd}`;
+  for (const p of candidates) if (verdicts.get(key(p)) === true) p.cmd = 'claude';
+  const pending = candidates.filter((p) => p.cmd !== 'claude' && !verdicts.has(key(p)));
+  if (!pending.length) return panes;
+
+  const out = await run('ps', ['-Ao', 'tty=,pid=,comm=']);
+  const procs = []; // [{ tty, pid, comm }]
+  for (const line of String(out).split('\n')) {
+    const m = line.match(/^\s*(\S+)\s+(\d+)\s+(.*)$/);
+    if (!m) continue;
+    const tty = normTty(m[1]);
+    if (tty) procs.push({ tty, pid: m[2], comm: m[3].trim() });
+  }
+  for (const p of pending) {
+    let ok = false;
+    // Tie by tty + exe BASENAME (== tmux's version comm; ps comm is the self-set title and can't be
+    // trusted to match), then require the real path to carry "claude" — a random semver-named binary
+    // elsewhere is NOT Claude.
+    const want = p.cmd.replace(/_/g, '.');
+    for (const r of procs.filter((r) => r.tty === normTty(p.tty))) {
+      const exe = await exePath(run, r.pid);
+      const base = exe.split('/').pop() || '';
+      if ((base === p.cmd || base === want) && CLAUDE_PATH_RE.test(exe)) { ok = true; break; }
+    }
+    verdicts.set(key(p), ok);
+    if (ok) p.cmd = 'claude';
+  }
+  return panes;
+}
 
 // Build the 需要你 one-liner for a PermissionRequest, from the tool it's gating on (PermissionRequest
 // carries tool_name + tool_input, unlike the later permission_prompt Notification which only has an
@@ -26,6 +83,22 @@ function permMsg(body) {
   return t ? `需要你授权：${t}` : '需要你';
 }
 
+// Friendly Chinese for the StopFailure error type (matcher values, see the hooks doc). The payload shape
+// isn't verified against a live rate-limit yet, so read the type defensively from several likely fields and
+// always fall back to a bare 本轮出错 — a wrong field name degrades to the generic label, never throws.
+const STOPFAIL_LABEL = {
+  rate_limit: '触发限流', overloaded: '服务过载', authentication_failed: '认证失败',
+  oauth_org_not_allowed: '组织未授权', billing_error: '额度/账单问题', invalid_request: '请求无效',
+  model_not_found: '模型不可用', server_error: '服务端错误', max_output_tokens: '输出超长', unknown: '未知错误',
+};
+function stopFailMsg(body = {}) {
+  const type = body.error_type || body.reason || body.type
+    || (body.error && (typeof body.error === 'string' ? body.error : body.error.type)) || '';
+  if (STOPFAIL_LABEL[type]) return STOPFAIL_LABEL[type];
+  const raw = typeof body.error === 'string' ? body.error : (body.message || '');
+  return raw ? String(raw).replace(/\s+/g, ' ').trim().slice(0, 80) : '';
+}
+
 // Build the 进行中 one-liner for a resume (PostToolUse after the user answered/approved), surfacing the
 // choice they just made — AskUserQuestion stores it in tool_input.answers, keyed by question.
 function resumeMsg(body) {
@@ -42,6 +115,10 @@ function resumeMsg(body) {
 //   stop                       → done       (turn finished; carries last message)
 //   prompt                     → working    (UserPromptSubmit; carries the prompt)
 //   end                        → end        (SessionEnd; the pane's claude is gone)
+//   start                      → null       (SessionStart startup/clear/resume: (re)binds pane→session to
+//                                             the NEW transcript_path — the whole point on /clear, which
+//                                             starts a fresh session file. Neutral: a fresh/just-cleared
+//                                             session reads as present, not 进行中, until its first prompt)
 //   notify + idle_prompt       → idle       (waited ~60s; carries the notification message)
 //   notify + permission_prompt → permission (blocked on a permission/选择 gate; carries the message)
 //   resume                     → working    (PostToolUse on AskUserQuestion/ExitPlanMode: the user just
@@ -52,13 +129,23 @@ function resumeMsg(body) {
 //                                             before the permission_prompt Notification and names the tool,
 //                                             so 需要你 shows faster and says what's being asked. Verified
 //                                             NOT to fire for auto-approved tools → no false 需要你 in auto)
+//   compacting                 → compacting (PreCompact: context compaction started — a slow op, shown as
+//                                             「压缩中」; version-gated, only paired with the clearing event)
+//   compact                    → null       (PostCompact: compaction finished → clear 压缩中/进行中. null
+//                                             drops the roster entry; the pane falls back to neutral present)
+//   stopfail                   → error      (StopFailure: the turn ended on an API error — no Stop fires, so
+//                                             this is the only signal that un-sticks the pane from 进行中)
 //   anything else              → null       (ignored: auth_success, elicitation_*, etc.)
 export function classifyClaude(src, body = {}) {
   if (src === 'stop') return { kind: 'done', msg: body.last_assistant_message || '' };
   if (src === 'prompt') return { kind: 'working', msg: body.prompt || '' };
   if (src === 'resume') return { kind: 'working', msg: resumeMsg(body) };
   if (src === 'permreq') return { kind: 'permission', msg: permMsg(body) };
+  if (src === 'compacting') return { kind: 'compacting', msg: '' };   // PreCompact: 压缩上下文进行中
+  if (src === 'compact') return null;                                 // PostCompact: done → clear 压缩中/进行中
+  if (src === 'stopfail') return { kind: 'error', msg: stopFailMsg(body) }; // turn died on an API error
   if (src === 'end') return { kind: 'end' };
+  if (src === 'start') return null;                                   // SessionStart: only (re)binds pane→session
   if (src === 'notify') {
     if (body.notification_type === 'idle_prompt') return { kind: 'idle', msg: body.message || '' };
     if (body.notification_type === 'permission_prompt') return { kind: 'permission', msg: body.message || '' };
@@ -73,7 +160,9 @@ export const claude = {
   label: 'Claude Code',
   procName: 'claude',
   // Which tmux #{pane_current_command} values mean "this agent is still the pane's foreground app" (inbox
-  // liveness). Claude sets its process title to "claude", so an exact single-name match is right.
+  // liveness). Claude sets its process title to "claude", so an exact single-name match is right — for
+  // native-install machines (whose comm is the VERSION string) resolveVersionedComms below normalizes the
+  // cmd back to 'claude' at ingest, keeping every match here exact-name.
   procNames: ['claude'],
   // The `claude` CLI sets its process title to "claude" (verified via ps): match the program token at the
   // start of argv — bare "claude", "claude --continue", or an absolute path ending in /claude. Anchored so

package/src/agents/index.js

@@ -16,5 +16,7 @@ const BY_ID = new Map(AGENTS.map((a) => [a.id, a]));
 export function getAgent(id) { return BY_ID.get(id) || claude; }
 
 // The driver whose foreground process this tmux #{pane_current_command} is, or null. Used by the inbox to
-// decide a recorded pane is still running its agent (vs. the agent having exited to a shell).
+// decide a recorded pane is still running its agent (vs. the agent having exited to a shell). Matches the
+// canonical procName only — never the ambiguous extras in procNames (e.g. Codex's 'node'); native-install
+// Claude binaries (comm = version string) are normalized to 'claude' at ingest (resolveVersionedComms).
 export function agentForProc(cmd) { return AGENTS.find((a) => a.procName === cmd) || null; }

package/src/claudeEvents.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getAgent, agentForProc } from './agents/index.js';
+import { resolveVersionedComms } from './agents/claude.js';
+import { defaultRun } from './agents/scanUtils.js';
 import { claude } from './agents/claude.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -39,6 +41,14 @@ function pushKey(view, ts) { return view === 'done' ? `done:${ts}` : view; }
 // its next event, and a new prompt resets the clock.
 const WORKING_TTL_MS = 2 * 60 * 60 * 1000;
 
+// 压缩中 (compacting) clears three ways: a SUCCESSFUL compaction fires PostCompact (src 'compact' → cleared
+// the instant it finishes); a NO-OP /compact ("Not enough messages to compact") fires no PostCompact but
+// writes its <local-command-stdout> immediately, which the transcript-tail check below catches within a poll;
+// and this TTL is the ultimate backstop for a genuine crash/abort mid-compaction where neither signal comes.
+// It must stay WELL above a real compaction's duration (routinely 1-2min) so it never truncates the animation
+// of a compaction that's actually still running — real ones are cleared by PostCompact, not by this timer.
+const COMPACTING_TTL_MS = 5 * 60 * 1000;
+
 // A pane latched in `permission` (需要你) has NO hook event to close it when the user resolves the prompt:
 // approving a normal tool (Bash/Edit/…) doesn't hit our PostToolUse matcher (only AskUserQuestion|ExitPlanMode
 // do), and DENYING or ESC-interrupting fires no hook at all (verified across all hook events). So the prompt
@@ -84,8 +94,30 @@ export function permissionResolved(rec, mtimeMs, guard = PERM_RESOLVED_GUARD_MS)
 // pane to neutral (null). An unparseable/absent tail is treated as a resume (clears the stale 需要你 and
 // shows active — a truncated huge last line is a big tool_result, never the tiny interrupt marker).
 export function resolvedPermissionKind(lastLine) {
-  if (lastLine && /Request interrupted by user/.test(lastLine)) return null; // ESC → neutral
-  return { kind: 'working', msg: '' };                                       // approve / deny → 进行中
+  if (isInterruptTail(lastLine)) return null;       // ESC → neutral
+  return { kind: 'working', msg: '' };              // approve / deny → 进行中
+}
+
+// Pure: does a transcript's last line mark a user ESC-interrupt? Matches both the plain and the
+// "…for tool use" forms. Used to un-stick a 进行中 pane the instant the user aborts a turn.
+export function isInterruptTail(lastLine) {
+  return !!(lastLine && /Request interrupted by user/.test(lastLine));
+}
+
+// Pure: does a transcript's last line mark a /compact having RESOLVED — i.e. Claude wrote the command's
+// <local-command-stdout>? A NO-OP /compact ("Not enough messages to compact") writes it IMMEDIATELY, whereas
+// a real compaction stays silent for its whole (often 1-2min) run and writes it only at the very end — the
+// same moment PostCompact already clears us. So a fresh stdout tail while still 压缩中 ⇒ the compaction is
+// over (nothing to do / done) ⇒ drop the stuck state. Recognised by the system entry's subtype or the tag.
+export function isLocalCommandStdout(lastLine) {
+  if (!lastLine) return false;
+  try {
+    const o = JSON.parse(lastLine);
+    if (o && o.subtype === 'local_command') return true;
+    const c = o && o.message && o.message.content;
+    if (typeof c === 'string' && /<local-command-stdout>/.test(c)) return true;
+  } catch { /* not JSON → fall through to a raw tag match */ }
+  return /<local-command-stdout>/.test(lastLine);
 }
 
 // Truncate a Claude message to a notification-friendly one-liner.
@@ -104,12 +136,16 @@ function readStateFile(file) {
 }
 
 // Per-process event reader. Deps injected for testability:
-//   commands.listLivePanes() → [{ id, cmd, session, window, windowName }]  (one tmux call: liveness+location)
+//   commands.listLivePanes() → [{ id, cmd, tty, session, window, windowName }]  (one tmux call)
+//   run(cmd, args) → stdout   (only used by the version-named-comm corroboration; default defaultRun)
 //   push.sendToSession(session, payload, {ttl, urgency, topic})
 //   file: the hook-maintained JSON state file (DEFAULT_STATE_FILE).
 // The hook is the sole writer; the server reads the file fresh on every getStates and on every file
 // change (the watcher, for push). No persisted state of our own — the file IS the persistence.
-export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE, now = () => Date.now(), statMtime = defaultStatMtime, readTail = defaultReadTail } = {}) {
+export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE, now = () => Date.now(), statMtime = defaultStatMtime, readTail = defaultReadTail, run = defaultRun } = {}) {
+  // Cache for resolveVersionedComms verdicts ((tty|cmd) → bool) — one corroboration per version per pane,
+  // not one per poll. Per instance: prod shares one server-wide map; tests get isolation for free.
+  const commVerdicts = new Map();
   const lastPushed = {}; // pane → 'needs' | 'done' | null  (in-process push-transition dedup, by display view)
   // The dedup above is in-process ONLY: a restart (e.g. ./deploy.sh) wipes it while the hook's state
   // file on disk keeps every pane's latest 需要你/已完成. Without priming, the first read after boot
@@ -151,7 +187,13 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
     const allow = allowedSessions == null ? null : new Set(allowedSessions);
     const recorded = readStateFile(file);
     let live = null;
-    try { live = new Map((await commands.listLivePanes()).map((p) => [p.id, p])); } catch { /* tmux down */ }
+    try {
+      const panes = await commands.listLivePanes();
+      // Native-install Claude binaries report a version string as pane_current_command — corroborate via
+      // ps and normalize to 'claude' BEFORE any identity/liveness match (see agents/claude.js).
+      await resolveVersionedComms(panes, run, commVerdicts);
+      live = new Map(panes.map((p) => [p.id, p]));
+    } catch { /* tmux down */ }
 
     const out = {};
     for (const [pane, rec] of Object.entries(recorded)) {
@@ -163,6 +205,21 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
       if (c && c.kind === 'permission') {
         const tp = rec.payload && rec.payload.transcript_path;
         if (tp && permissionResolved(rec, statMtime(tp))) c = resolvedPermissionKind(readTail(tp));
+      } else if (c && c.kind === 'working') {
+        // ESC-interrupt during a turn leaves the last hook as the stale 'prompt' (working) — no Stop fires,
+        // so working would otherwise stick until WORKING_TTL_MS (2h), pinning the composer's send→stop toggle.
+        // Once the transcript has grown past the prompt event, a bounded tail read settles it: an interrupt
+        // marker → neutral (un-stick now); any other line → Claude is still producing, stay 进行中. Content is
+        // definitive so no guard window is needed; an unreadable stat/tail can't tell → keep working.
+        const tp = rec.payload && rec.payload.transcript_path;
+        if (tp && statMtime(tp) > (rec.ts || 0) && isInterruptTail(readTail(tp))) c = null;
+      } else if (c && c.kind === 'compacting') {
+        // A no-op /compact fires no PostCompact; it writes its <local-command-stdout> at once. Once the
+        // transcript has grown past the PreCompact event and its tail is that stdout, the /compact is done
+        // (nothing to compact) → drop 压缩中. A real compaction stays silent until PostCompact, so it keeps
+        // showing for its whole run. Unreadable stat/tail → can't tell → keep 压缩中 (the TTL is the backstop).
+        const tp = rec.payload && rec.payload.transcript_path;
+        if (tp && statMtime(tp) > (rec.ts || 0) && isLocalCommandStdout(readTail(tp))) c = null;
       }
       const lp = live ? live.get(pane) : null;
       // Dropped when tmux says the pane is gone or no longer running THIS agent (hard kill / crash /
@@ -193,6 +250,7 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
       // Expire a 进行中 latched past the TTL (an ESC-interrupt / walk-away that never got a Stop): drop it
       // from the roster so the stuck working pane goes away. See WORKING_TTL_MS.
       if (c.kind === 'working' && now() - (rec.ts || 0) > WORKING_TTL_MS) continue;
+      if (c.kind === 'compacting' && now() - (rec.ts || 0) > COMPACTING_TTL_MS) continue;
       const loc = lp ? { session: lp.session, window: lp.window, windowName: lp.windowName } : {};
       if (allow && !allow.has(loc.session)) continue;
       out[pane] = { ...loc, kind: c.kind, msg: c.msg || '', ts: rec.ts || 0, agent: agent.id };
@@ -251,5 +309,20 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
   }
   function stop() { if (watcher) { watcher.close(); watcher = null; } clearTimeout(deb); }
 
-  return { getStates, start, stop };
+  // The chat lens's pane→session bind: the hook state file records THIS pane's exact session (session_id +
+  // transcript_path), authoritative over the terminal-side cwd→newest-jsonl guess (which collapses distinct
+  // sessions that happen to share a cwd — see transcript.js). Returns null when hooks are off / the pane
+  // isn't a Claude pane / the recorded payload carries no session info, so callers can fall back cleanly.
+  function paneSession(pane) {
+    const rec = readStateFile(file)[pane];
+    const p = rec && rec.payload;
+    if (!p || typeof p !== 'object') return null;
+    const transcriptPath = typeof p.transcript_path === 'string' ? p.transcript_path : null;
+    const sessionId = typeof p.session_id === 'string' ? p.session_id : null;
+    const cwd = typeof p.cwd === 'string' ? p.cwd : null;
+    if (!transcriptPath && !sessionId) return null;
+    return { sessionId, transcriptPath, cwd };
+  }
+
+  return { getStates, start, stop, paneSession };
 }

package/src/cli/claudeHooks.js

@@ -7,38 +7,111 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
 import { writeJsonAtomic, deployHookScripts, removeHookScripts } from './hookScaffold.js';
 
-// The six events the inbox reads. src is the arg passed to handmux-notify.sh; only PostToolUse is scoped to
+// The seven events the inbox reads. src is the arg passed to handmux-notify.sh; only PostToolUse is scoped to
 // a matcher (the two "需要你" interaction tools) — every other Read/Bash/Edit must NOT wake the hook, or
 // many concurrent Claude panes would each spawn the hook on every tool call. Keep this table in sync with
 // the hook scripts in ../../hooks.
+//   SessionStart binds the pane→session mapping the instant a session begins — critically after /clear, which
+// starts a NEW transcript file. Without it, /clear's SessionEnd(old) drops the pane and nothing rebinds it
+// until the next prompt, so the 对话 lens goes blank / falls back to the ambiguous cwd→newest-jsonl guess.
+// Fires only at session boundaries (startup/clear/resume), never per tool call, so it adds no hot-path load;
+// classified neutral (no push, no roster entry — see agents/claude.js). Base, not version-gated: SessionStart
+// is a long-standing lifecycle hook every supported Claude recognises.
 export const HOOK_EVENTS = [
   { event: 'Stop', src: 'stop' },
   { event: 'Notification', src: 'notify' },
   { event: 'UserPromptSubmit', src: 'prompt' },
+  { event: 'SessionStart', src: 'start' },
   { event: 'SessionEnd', src: 'end' },
   { event: 'PostToolUse', src: 'resume', matcher: 'AskUserQuestion|ExitPlanMode' },
   { event: 'PermissionRequest', src: 'permreq' },
 ];
 
+// Version-gated events, only registered on a Claude Code new enough to EMIT them. Older Claude does not
+// recognise these event names — and the docs give NO guarantee it ignores unknown ones (it "likely" does,
+// but might reject the settings file) — so we NEVER write an event a version can't handle. Each carries a
+// minVersion; below it (or when the version can't be detected) the event isn't written at all → pure
+// downgrade, never an error. The pane instead self-heals via the existing idle_prompt(~60s) fallback.
+//   PreCompact  → 压缩中 shown while compaction runs (honest progress for a slow op).
+//   PostCompact → clears the 压缩中/进行中 state the instant compaction finishes.
+//   StopFailure → a turn that died on an API error (rate limit / overload / …) fires NO Stop, so without
+//                 this the pane sticks at 进行中 forever; maps to an 'error' state.
+// `pairWith` welds an invariant (learned the hard way — never light a state you can't turn off): PreCompact
+// is installed ONLY when its clearer PostCompact is also installed. minVersion is set conservatively to the
+// version we've actually verified emits these (2.1.207); lower it only after test-firing an older build.
+const COMPACT_MIN = '2.1.207';
+export const HOOK_EVENTS_EXT = [
+  { event: 'PostCompact', src: 'compact', minVersion: COMPACT_MIN },
+  { event: 'PreCompact', src: 'compacting', minVersion: COMPACT_MIN, pairWith: 'PostCompact' },
+  { event: 'StopFailure', src: 'stopfail', minVersion: COMPACT_MIN },
+];
+
 const HOOK_MARK = 'handmux-notify.sh'; // identifies our hooks among the user's own
 
+// Parse `claude --version` output ("2.1.207 (Claude Code)") → { major, minor, patch } | null.
+export function parseClaudeVersion(out) {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(String(out || ''));
+  return m ? { major: +m[1], minor: +m[2], patch: +m[3] } : null;
+}
+
+// v >= min ("X.Y.Z"), full major.minor.patch compare. A null/undefined version is always below → fail-closed.
+export function claudeVersionAtLeast(v, minStr) {
+  if (!v) return false;
+  const [a, b, c] = String(minStr).split('.').map(Number);
+  if (v.major !== a) return v.major > a;
+  if (v.minor !== b) return v.minor > b;
+  return v.patch >= c;
+}
+
+// Detect the installed Claude Code version, or null if `claude` can't be run/parsed (→ ext hooks skipped).
+export function detectClaudeVersion(exec = spawnSync) {
+  try {
+    const r = exec('claude', ['--version'], { encoding: 'utf8', timeout: 4000 });
+    if (!r || r.status !== 0 || !r.stdout) return null;
+    return parseClaudeVersion(r.stdout);
+  } catch { return null; }
+}
+
+// Drop OUR hook from settings.hooks[event] (used to prune an ext event that no longer passes the version
+// gate — e.g. Claude was downgraded after a newer install). Mutates the passed hooks object.
+function dropOurHook(hooks, event) {
+  if (!hooks[event]) return;
+  const kept = hooks[event]
+    .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !(typeof h.command === 'string' && h.command.includes(HOOK_MARK))) }))
+    .filter((g) => (g.hooks || []).length > 0);
+  if (kept.length) hooks[event] = kept; else delete hooks[event];
+}
+
 // True if `settings.hooks[event]` already has one of our hooks (command references the dest script).
 function alreadyHas(hooks, event) {
   return (hooks[event] || []).some((g) => (g.hooks || []).some(
     (h) => typeof h.command === 'string' && h.command.includes(HOOK_MARK)));
 }
 
+// Merge one event's hook group into `hooks` (mutates), idempotently — a no-op if one of ours is already
+// registered for that event, so it's safe to call on every install/sync. Shared by mergeHooks and syncHooks.
+function addHook(hooks, e, dest) {
+  if (alreadyHas(hooks, e.event)) return;
+  const groups = hooks[e.event] = [...(hooks[e.event] || [])];
+  groups.push({ matcher: e.matcher || '', hooks: [{ type: 'command', command: `${dest} ${e.src}`, async: true, timeout: 5 }] });
+}
+
 // Pure: return a NEW settings object with our six hooks merged into settings.hooks, idempotently, leaving
 // the user's own hooks and other keys untouched. `dest` is the absolute path to the copied notify script.
-export function mergeHooks(settings, dest) {
+export function mergeHooks(settings, dest, claudeVersion = null) {
   const s = { ...(settings || {}) };
   const hooks = (s.hooks && typeof s.hooks === 'object' && !Array.isArray(s.hooks)) ? { ...s.hooks } : {};
-  for (const e of HOOK_EVENTS) {
-    if (alreadyHas(hooks, e.event)) continue;
-    const groups = hooks[e.event] = [...(hooks[e.event] || [])];
-    groups.push({ matcher: e.matcher || '', hooks: [{ type: 'command', command: `${dest} ${e.src}`, async: true, timeout: 5 }] });
+  for (const e of HOOK_EVENTS) addHook(hooks, e, dest);
+  // Version-gated ext events: install only when the detected Claude is new enough AND (for a paired event)
+  // its clearer is also being installed. Anything that fails the gate is actively PRUNED, so a Claude
+  // downgrade after a newer install can't leave an unrecognised event name lingering in settings.json.
+  const enabled = new Set();
+  for (const e of HOOK_EVENTS_EXT) {
+    const ok = claudeVersionAtLeast(claudeVersion, e.minVersion) && (!e.pairWith || enabled.has(e.pairWith));
+    if (ok) { enabled.add(e.event); addHook(hooks, e, dest); } else dropOurHook(hooks, e.event);
   }
   s.hooks = hooks;
   return s;
@@ -79,7 +152,7 @@ export function hooksStatus(home = homedir()) {
 // absent the user doesn't run Claude Code, so we report 'no-claude' and do nothing.
 //   srcDir   = the bundled hooks dir (server/hooks)
 //   stateFile = the unified ~/.handmux/claude-state.json path the hook writes and the server reads
-export function installHooks(home = homedir(), { srcDir, stateFile } = {}) {
+export function installHooks(home = homedir(), { srcDir, stateFile, claudeVersion } = {}) {
   if (!fs.existsSync(claudeDir(home))) return { status: 'no-claude' };
   const hooksDir = path.join(claudeDir(home), 'hooks');
   deployHookScripts(hooksDir, srcDir, stateFile);
@@ -87,10 +160,41 @@ export function installHooks(home = homedir(), { srcDir, stateFile } = {}) {
   const dest = path.join(hooksDir, 'handmux-notify.sh');
   let settings = {};
   try { settings = JSON.parse(fs.readFileSync(settingsPath(home), 'utf8')); } catch { /* missing/corrupt → {} */ }
-  writeJsonAtomic(settingsPath(home), mergeHooks(settings, dest));
+  // Gate the version-specific events (compact pair, StopFailure) on the installed Claude. Detect when the
+  // caller didn't inject a version; a null result (no `claude` / unparseable) is fail-closed = base 6 only.
+  const version = claudeVersion !== undefined ? claudeVersion : detectClaudeVersion();
+  writeJsonAtomic(settingsPath(home), mergeHooks(settings, dest, version));
   return { status: 'installed' };
 }
 
+// Keep an ALREADY-installed user's hooks in step with this handmux version on every server start, so a plain
+// `./deploy.sh` (restart) rolls out newly-added lifecycle events (e.g. SessionStart) and refreshed hook
+// scripts — no phone re-enable needed. Two moves: (1) re-deploy the bundled hook scripts (idempotent — picks
+// up a fixed handmux-write.cjs), and (2) add any of our BASE events a prior install predates.
+//
+// Strictly opt-in-preserving: a NO-OP unless our hooks are already present ('installed'). It never enables
+// hooks for a user who hasn't opted in ('absent') and never creates ~/.claude ('no-claude'). BASE events
+// only — it deliberately does NOT touch the version-gated ext events (compact pair / StopFailure): reconciling
+// those needs the Claude version (a null read would PRUNE the ext hooks a user already has), and detecting it
+// means spawning `claude --version` on the hot startup path. So sync stays pure-fs and non-pruning; ext-event
+// rollout stays with the explicit installHooks (phone re-enable) path. settings.json is rewritten only when
+// the merge actually changes it, so a steady state writes nothing.
+export function syncHooks(home = homedir(), { srcDir, stateFile } = {}) {
+  const status = hooksStatus(home);
+  if (status !== 'installed') return { status, changed: false };
+  const hooksDir = path.join(claudeDir(home), 'hooks');
+  deployHookScripts(hooksDir, srcDir, stateFile); // refresh the deployed scripts (idempotent)
+  const dest = path.join(hooksDir, 'handmux-notify.sh');
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(settingsPath(home), 'utf8')); } catch { /* missing/corrupt → {} */ }
+  const hooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)) ? { ...settings.hooks } : {};
+  const before = JSON.stringify(hooks);
+  for (const e of HOOK_EVENTS) addHook(hooks, e, dest); // add only MISSING base events; never add/prune ext
+  const changed = JSON.stringify(hooks) !== before;
+  if (changed) writeJsonAtomic(settingsPath(home), { ...settings, hooks });
+  return { status: 'installed', changed };
+}
+
 // Uninstall: strip our hooks from settings.json and remove the copied scripts/env. Best-effort on the file
 // deletes (a missing file is fine). Leaves ~/.claude and the user's own hooks intact.
 export function uninstallHooks(home = homedir()) {

package/src/cli/state.js

@@ -20,6 +20,7 @@ export function claudeStatePath(home) { return path.join(pocketHome(home), 'clau
 // PREVIEW_STORE for the server child.
 export function pushStorePath(home) { return path.join(pocketHome(home), 'push-subs.json'); }
 export function previewStorePath(home) { return path.join(pocketHome(home), 'previews.json'); }
+export function notificationsDirPath(home) { return path.join(pocketHome(home), 'notifications'); }
 
 export function readState(home) {
   try { return JSON.parse(fs.readFileSync(statePath(home), 'utf8')); } catch { return null; }

package/src/cli/statusLine.js

@@ -62,6 +62,21 @@ export function installStatusLine(home = homedir(), { srcDir, usageFile } = {})
   return { status: 'installed' };
 }
 
+// Refresh the on-disk capturer script to the BUNDLED version without touching settings.statusLine — so an
+// npm upgrade actually reaches a user who already opted in. Critically settings-safe: a user who composed us
+// into their OWN statusline (the TEE form) still reads as 'ours' (the command contains our mark), and we must
+// NOT rewrite their command to the bare form (that would drop their downstream renderer). So this only ever
+// copies the script. No-op (returns false) when we're not installed. Idempotent; safe to call every start.
+export function refreshStatusLineScript(home = homedir(), { srcDir } = {}) {
+  if (statusLineStatus(home) !== 'ours') return false;
+  try {
+    const dest = path.join(claudeDir(home), 'hooks', SCRIPT);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(srcDir, SCRIPT), dest);
+    return true;
+  } catch { return false; }
+}
+
 // Uninstall: drop settings.statusLine only if it's ours, and remove the copied script. Leaves a foreign
 // statusLine and everything else intact.
 export function uninstallStatusLine(home = homedir()) {

package/src/cli/supervisor.js

@@ -8,7 +8,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { getDriver } from './drivers.js';
-import { writeState, clearState, claudeStatePath, pushStorePath, previewStorePath } from './state.js';
+import { writeState, clearState, claudeStatePath, pushStorePath, previewStorePath, notificationsDirPath } from './state.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const SERVER = path.resolve(here, '../server.js');
@@ -84,6 +84,7 @@ export function supervise(cfg, { home, log = console } = {}) {
       CLAUDE_STATE_FILE: claudeStatePath(home),
       PUSH_STORE: pushStorePath(home),
       PREVIEW_STORE: previewStorePath(home),
+      NOTIF_DIR: notificationsDirPath(home),
     };
     if (cfg.previewDomain) env.HANDMUX_PREVIEW_DOMAIN = cfg.previewDomain;
     if (cfg.name) env.HANDMUX_APP_NAME = cfg.name;

package/src/httpApi.js

@@ -8,6 +8,7 @@ import * as defaultCommands from './tmux/commands.js';
 import { defaultDocs, MAX_TRANSFER_BYTES } from './docs.js';
 import { defaultGit } from './git.js';
 import * as push from './push.js';
+import * as notifications from './notifications.js';
 import { createClaudeEvents } from './claudeEvents.js';
 import { homedir } from 'node:os';
 import { DEFAULT_UPLOAD_EXTS } from './uploadTypes.js';
@@ -19,6 +20,8 @@ import { fileRoutes } from './routes/files.js';
 import { pushRoutes } from './routes/push.js';
 import { systemRoutes } from './routes/system.js';
 import { previewRoutes } from './routes/previews.js';
+import { notificationRoutes } from './routes/notifications.js';
+import { transcriptRoutes } from './routes/transcript.js';
 
 // Re-exported for tests (test/keys.test.js) and any caller that imported it by this path historically.
 export { isAllowedKey } from './routes/terminal.js';
@@ -35,7 +38,7 @@ export function createApiRouter({
   const claudeEvents = events || createClaudeEvents({ commands, push });
 
   const deps = {
-    token, commands, docs, git, push, claudeEvents,
+    token, commands, docs, git, push, notifications, claudeEvents,
     uploadExts, maxUploadBytes, asrEnv, previews, previewDomain, home, stateFile,
   };
 
@@ -44,8 +47,10 @@ export function createApiRouter({
   r.use(gitRoutes(deps));
   r.use(fileRoutes(deps));
   r.use(pushRoutes(deps));
+  r.use(notificationRoutes(deps));
   r.use(systemRoutes(deps));
   r.use(previewRoutes(deps));
+  r.use(transcriptRoutes(deps));
 
   return r;
 }