handmux 0.16.0 → 0.17.0

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-C8uRJNnP.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

@@ -26,6 +26,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 +58,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 +72,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 || '' };

package/src/claudeEvents.js

@@ -39,6 +39,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 +92,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.
@@ -163,6 +193,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 +238,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 +297,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;
 }

package/src/notifications.js

@@ -0,0 +1,51 @@
+// Per-device manual-push inbox: each subscribed device gets its own file `<NOTIF_DIR>/<pushKey>.json`, so a
+// `--device`/`--session`-scoped push only lands in the targeted devices' inboxes (delete/read are naturally
+// per-device too). NOTIF_DIR is injected by the CLI (~/.handmux/notifications) — NEVER the package-internal
+// default, which a global reinstall wipes. Low-frequency, so each op is a plain read-modify-write of one
+// device file (no in-memory state). The same push shares one record id across its target devices so a
+// notification tap's inboxId resolves on whichever device opens it.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import crypto from 'node:crypto';
+import { readJsonArray, writeJsonAtomic } from './jsonStore.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const DIR = process.env.NOTIF_DIR || path.resolve(here, '../data/notifications');
+const CAP = 100;
+const genId = () => crypto.randomBytes(9).toString('base64url');
+
+// pushKey is base64url already; sanitize anyway so a hostile value can't escape DIR. Empty → null (skip).
+function fileFor(key) {
+  const safe = String(key || '').replace(/[^A-Za-z0-9_-]/g, '');
+  return safe ? path.join(DIR, `${safe}.json`) : null;
+}
+const load = (file) => readJsonArray(file).filter((n) => n && typeof n.title === 'string');
+
+export function record(pushKeys, { title, body, tag, url } = {}) {
+  const rec = { id: genId(), ts: Date.now(), title: String(title ?? ''), body: String(body ?? '') };
+  if (tag) rec.tag = String(tag);
+  if (url) rec.url = String(url);
+  for (const key of pushKeys || []) {
+    const file = fileFor(key);
+    if (!file) continue;
+    const items = load(file);
+    items.push(rec);
+    writeJsonAtomic(file, items.length > CAP ? items.slice(items.length - CAP) : items);
+  }
+  return rec;
+}
+
+export function list(pushKey) {
+  const file = fileFor(pushKey);
+  return file ? load(file).reverse() : [];
+}
+
+export function remove(pushKey, id) {
+  const file = fileFor(pushKey);
+  if (!file) return false;
+  const items = load(file);
+  const kept = items.filter((n) => n.id !== id);
+  if (kept.length === items.length) return false;
+  writeJsonAtomic(file, kept);
+  return true;
+}