handmux 0.16.0 → 0.17.3

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;
+}

package/src/pendingPrompt.js

@@ -0,0 +1,163 @@
+// Parse a pending interactive PROMPT (an AskUserQuestion menu — single OR multi-question — or a tool-
+// permission menu) out of a Claude Code pane's `capture-pane` text. This is deliberately screen-scraping: a
+// pending prompt's options exist ONLY in the rendered TUI — they are NOT written to the session .jsonl until
+// AFTER the user answers (verified live), so the transcript can't be the source. Same approach amux/
+// VibeTunnel/Conductor use for the "attach to a running TUI" model; there is no structured channel short of
+// relaunching Claude via the SDK.
+//
+// Verified against a live Claude Code (2026-07-17):
+//
+//  SINGLE question / permission menu:            MULTI-question (tabbed):        REVIEW / submit screen:
+//    ☐ 颜色         ← header (optional)             ←  ☒ 水果  ☐ 颜色  ✔ Submit  →   ←  ☒ 水果  ☒ 颜色 ✔ Submit →
+//   你喜欢哪个?      ← question                      选个颜色?      ← current tab     Review your answers
+//   ❯ 1. 红色       ← ❯ marks the cursor            ❯ 1. 红                          ❯ 1. Submit answers
+//        热情、醒目   ← description (optional)          2. 蓝                            2. Cancel
+//     2. 蓝色                                       Enter to select · Tab/… · Esc    (NO footer line)
+//     4. Type something.  ← built-in meta (dropped)
+//   Enter to select · ↑/↓ to navigate · Esc to cancel
+//
+// Driving (verified live): sending the literal DIGIT of an option selects it. For a SINGLE question it
+// selects AND submits immediately; for MULTI it selects AND auto-advances to the next tab; on the review
+// screen digit 1 = "Submit answers". So the caller drives the whole flow by sending `String(option.n)` and
+// re-polling — each screen (Q1 → Q2 → review) is itself a parseable menu. Escape cancels.
+//
+// The parser ANCHORS on the ❯ cursor line, NOT a footer: the review screen has options but no footer.
+
+// Cursor-selected option line: ❯ (or ›»>) then "N.".
+const CURSOR_RE = /^\s*[❯›»>]\s*\d+\.\s/;
+// Any option row: optional cursor, then "N. label".
+const OPTION_RE = /^\s*[❯›»>]?\s*(\d+)\.\s+(.+?)\s*$/;
+// A description row: indented, not itself an option.
+const isDesc = (l) => /^\s{3,}\S/.test(l) && !OPTION_RE.test(l);
+// A horizontal rule Claude draws inside/around the card (kept within an option block so meta rows past it
+// are still seen and dropped).
+const RULE_RE = /^[\s─━—–\-_=·⎯]{8,}$/;
+// The multi-question tab strip: "←  ☒ 水果  ☐ 颜色  ✔ Submit  →".
+const TAB_BAR_RE = /✔\s*Submit|[☐☒].*[☐☒]/;
+// Claude's built-in trailing meta-options — not real answers.
+const META_LABELS = new Set(['type something', 'type something.', 'chat about this', 'chat about this.']);
+// Leading decoration on the header line.
+const HEADER_DECOR_RE = /^[\s☐☑☒◯●○·•\-*]+/;
+// A menu footer (single-question / permission), used only as a title boundary — NOT required to detect a menu.
+const FOOTER_RE = /enter to select|esc to (cancel|reject)/i;
+// A Claude activity/spinner line — the top edge of the card, above which is prior transcript.
+const ACTIVITY_RE = /^\s*[✻✳✶✽⏺]\s|worked for|cogitated|crafting|cooked for|crunched for|esc to interrupt/i;
+// The input cursor ❯ leading the user's echoed prompt (above the card).
+const PROMPT_ECHO_RE = /^\s*[❯›»>]\s*\D/; // ❯ NOT followed by a digit (that would be an option)
+const isTitleBoundary = (l) =>
+  ACTIVITY_RE.test(l) || RULE_RE.test(l) || TAB_BAR_RE.test(l) || FOOTER_RE.test(l) || PROMPT_ECHO_RE.test(l);
+
+const stripRight = (s) => String(s == null ? '' : s).replace(/\s+$/, '');
+// Strip ANSI/OSC escapes so a capture taken WITH `-e` (SGR) still parses — belt-and-suspenders even though
+// the endpoint captures plain.
+const stripAnsi = (s) => String(s || '').replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '').replace(/\x1b[[0-9;?]*[ -/]*[@-~]/g, '');
+
+// The assistant text immediately PRECEDING the menu, scraped because the turn (text + AskUserQuestion) is NOT
+// flushed to the session jsonl until AFTER the user answers (verified live: probe + out-of-order line
+// timestamps) — so the 对话 lens's transcript view structurally can't show it while the gate is up. The title
+// walk below stops at the first boundary (activity spinner / box rule / prompt echo), which is exactly where
+// the lead-in text usually sits. Walk on upward: skip boundary chrome, take the nearest content block, keep
+// its LAST lines (the freshest context, "问题的最后一行"). `fromIdx` = the first line NOT consumed by the
+// title walk, so adjacent lead-in the title already absorbed is never duplicated here.
+const LEADIN_MAX = 2;
+const MSG_MARK_RE = /^\s*⏺/; // ⏺ opens an assistant message in the scrollback — include it, stop there
+function extractLeadIn(lines, fromIdx) {
+  const block = [];
+  let i = fromIdx;
+  // Skip the chrome between the menu and the preceding text (spinner / rules / tab bar / stale footer /
+  // blanks) — but never past a ❯ prompt echo (above it is the PREVIOUS exchange, stale context) nor past a
+  // ⏺ message head (it IS the text's first line — the collect loop includes it).
+  while (i >= 0 && (!lines[i].trim() || (isTitleBoundary(lines[i]) && !PROMPT_ECHO_RE.test(lines[i]) && !MSG_MARK_RE.test(lines[i])))) i--;
+  for (; i >= 0 && block.length < 12; i--) {
+    const l = lines[i];
+    if (!l.trim()) break;                                        // blank = the block's top (last paragraph)
+    if (MSG_MARK_RE.test(l)) { block.unshift(l.trim()); break; } // the ⏺ message head: include & stop
+    if (isTitleBoundary(l)) break;                               // hard chrome (incl. ❯ echo): stop
+    block.unshift(l.trim());
+  }
+  const tail = block.slice(-LEADIN_MAX).map((l) => l.replace(/^⏺\s*/, '').trim()).filter(Boolean);
+  return tail.length ? tail.join(' ') : null;
+}
+
+// Parse the multi-question tab strip → [{ label, answered }]. ☒ = answered, ☐ = not. "✔ Submit" is excluded.
+function parseTabs(line) {
+  const tabs = [];
+  const re = /([☐☒])\s*(\S+)/g;
+  let m;
+  while ((m = re.exec(line))) tabs.push({ label: m[2], answered: m[1] === '☒' });
+  return tabs;
+}
+
+// capture-pane text → a normalized pending prompt, or null when no interactive menu is on screen.
+//   { kind:'question'|'permission', title, options:[{n,label,description}], cursor,
+//     multi, step, total, submit }
+// `n` is the digit to send to pick that option. For multi, `step`/`total` drive the "第 i/N 题" progress and
+// `submit` marks the final review screen (options are Submit answers / Cancel).
+export function parsePendingPrompt(text) {
+  const lines = stripAnsi(text).split('\n').map(stripRight);
+
+  // Anchor on the cursor-selected option (present in every menu: question, permission, review). Take the
+  // LAST one so stale menus higher in the scrollback are ignored — the live menu is at the bottom.
+  const anchor = lines.findLastIndex((l) => CURSOR_RE.test(l));
+  if (anchor < 0) return null;
+
+  // The option block = the contiguous run of option / description / rule lines around the anchor.
+  const inBlock = (l) => OPTION_RE.test(l) || isDesc(l) || RULE_RE.test(l);
+  let top = anchor;
+  let bot = anchor;
+  while (top - 1 >= 0 && inBlock(lines[top - 1])) top--;
+  while (bot + 1 < lines.length && inBlock(lines[bot + 1])) bot++;
+
+  const options = [];
+  let cursor = null;
+  for (let i = top; i <= bot; i++) {
+    const m = lines[i].match(OPTION_RE);
+    if (!m) continue;
+    const n = Number(m[1]);
+    const label = m[2].trim();
+    if (CURSOR_RE.test(lines[i])) cursor = n;
+    let description = '';
+    for (let j = i + 1; j <= bot; j++) {
+      if (OPTION_RE.test(lines[j])) break;
+      if (!isDesc(lines[j])) break;
+      description += (description ? ' ' : '') + lines[j].trim();
+    }
+    if (META_LABELS.has(label.toLowerCase())) continue; // drop Claude's built-in meta-options
+    options.push({ n, label, description });
+  }
+  if (!options.length) return null;
+
+  // Title = header/question text above the block, skipping in-card blanks, stopping at the card's top edge.
+  const head = [];
+  let headStop = top - 1;
+  for (let i = top - 1; i >= 0 && head.length < 5; i--) {
+    if (!lines[i].trim()) { headStop = i - 1; continue; }
+    if (isTitleBoundary(lines[i])) { headStop = i; break; }
+    head.unshift(lines[i]);
+    headStop = i - 1;
+  }
+  const title = head.map((l) => l.replace(HEADER_DECOR_RE, '').trim()).filter(Boolean).join(' — ') || '需要你选择';
+
+  // Multi-question: the tab strip drives progress. `answered` ☒ tabs → current step is the next unanswered.
+  const tabLine = lines.find((l) => TAB_BAR_RE.test(l));
+  const tabs = tabLine ? parseTabs(tabLine) : [];
+  const multi = tabs.length > 1;
+  const answered = tabs.filter((t) => t.answered).length;
+  const submit = /^submit answers?$/i.test(options[0].label) || (multi && answered >= tabs.length);
+
+  const kind = /do you want to proceed/i.test(title) || /^yes\b/i.test(options[0].label)
+    ? 'permission' : 'question';
+
+  const out = { kind, title, options, cursor };
+  // Lead-in context the title walk didn't absorb (it stopped at a boundary or its 5-line cap) — the
+  // assistant's last line(s) before the question, shown above the gate so the phone isn't asked blind.
+  const leadIn = extractLeadIn(lines, headStop);
+  if (leadIn) out.leadIn = leadIn;
+  if (multi) {
+    out.multi = true;
+    out.total = tabs.length;
+    out.step = Math.min(answered + 1, tabs.length);
+    out.submit = submit;
+  }
+  return out;
+}

package/src/push.js

@@ -129,6 +129,17 @@ export const sendToDevices = (keys, payload, opts = {}) =>
 export const sendToSessions = (sessions, payload, opts = {}) =>
   deliver(subs.filter((s) => s.boundSessions.some((x) => sessions.includes(x))), payload, opts);
 
+// The pushKeys a given scope resolves to (mirrors sendToDevices/sendToSessions/sendToAll targeting) — used
+// by the inbox to write a record into exactly the devices a manual push is delivered to.
+export const resolveTargetKeys = ({ devices, sessions } = {}) => {
+  const pick = (devices && devices.length)
+    ? subs.filter((s) => devices.includes(s.pushKey))
+    : (sessions && sessions.length)
+      ? subs.filter((s) => s.boundSessions.some((x) => sessions.includes(x)))
+      : subs;
+  return [...new Set(pick.map((s) => s.pushKey).filter(Boolean))];
+};
+
 // Back-compat: the /push/subscribe welcome still pushes to a single just-added subscription.
 export async function sendToOne(sub, payload, opts = {}) {
   const rec = subs.find((s) => s.subscription.endpoint === sub.endpoint)

package/src/routes/notifications.js

@@ -0,0 +1,19 @@
+// Read/delete for the manual-push inbox. Recording happens in routes/push.js (send-local). This
+// module is single-purpose: list history (newest first) and delete one entry by id.
+import express from 'express';
+
+export function notificationRoutes({ notifications }) {
+  const r = express.Router();
+
+  r.get('/notifications', (req, res) => {
+    const device = req.query.device;
+    res.json({ items: typeof device === 'string' && device ? notifications.list(device) : [] });
+  });
+
+  r.delete('/notifications/:id', (req, res) => {
+    const device = req.query.device;
+    res.json({ ok: typeof device === 'string' && device ? notifications.remove(device, req.params.id) : false });
+  });
+
+  return r;
+}

package/src/routes/push.js

@@ -2,7 +2,7 @@
 // the local script-push send entry. The push module owns the delivery contract (TTL/topic/prune).
 import express from 'express';
 
-export function pushRoutes({ push }) {
+export function pushRoutes({ push, notifications }) {
   const r = express.Router();
 
   // The client needs the VAPID public key to subscribe; 503 if the server has no keys configured.
@@ -60,9 +60,15 @@ export function pushRoutes({ push }) {
     if (hasSessions && hasDevices) return res.status(400).json({ error: 'use --session or --device, not both' });
     const payload = { title, body };
     if (typeof tag === 'string' && tag) payload.tag = tag;
-    if (typeof url === 'string' && url) payload.data = { url };
     const opts = { urgency: 'normal', ttl: 1800 };
     if (payload.tag) opts.topic = payload.tag;
+    // Record FIRST so the notification tap can deep-link to this exact message's detail page. `--url`
+    // is stored on the record (surfaced in the detail), NOT used as the tap target.
+    if (notifications) {
+      const targetKeys = push.resolveTargetKeys({ devices: hasDevices ? devices : null, sessions: hasSessions ? sessions : null });
+      const rec = notifications.record(targetKeys, { title, body, tag: payload.tag, url });
+      payload.data = { inboxId: rec.id };
+    }
     try {
       const out = hasDevices ? await push.sendToDevices(devices, payload, opts)
         : hasSessions ? await push.sendToSessions(sessions, payload, opts)

package/src/routes/transcript.js

@@ -0,0 +1,93 @@
+// Read a pane's Claude Code jsonl session and return it as normalized chat messages (the "对话" lens's
+// read-projection). Pane → cwd (tmux) → the session file under ~/.claude/projects/<encoded-cwd>/.
+// Server-side paginated — the phone must never receive the whole transcript:
+//   - Recent window (default + polling): ?pane=&limit=10&since=<hash> — the last `limit` messages, with
+//     the same content-hash `since`省流 as /history (unchanged window → 204). `hasMore`/`firstSeq` tell the
+//     client whether/where an older page starts.
+//   - History page (scroll-up, not polled): ?pane=&before=<k>&limit=10 — the last `limit` messages with
+//     `k < before`, no hash.
+// `k` = each message's global ordinal from `all.map((m,k)=>({...m,k}))` — stable because the jsonl is
+// append-only, so it doubles as the client's dedup key. `limit` clamps to [1,100], default 10. Mounted
+// under /api.
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { isPaneId } from '../tmux/commands.js';
+import { projectsDir } from '../agents/claude.js';
+import { resolveEncodedDirSession, encodeProjectDir } from '../agents/scanUtils.js';
+import { parseTranscript } from '../transcriptParse.js';
+import { parsePendingPrompt } from '../pendingPrompt.js';
+import { readClaudeContext } from '../usage.js';
+
+export function transcriptRoutes({ commands, claudeEvents }) {
+  const r = express.Router();
+
+  // The pending interactive PROMPT on the pane's screen — an AskUserQuestion menu or a tool-permission
+  // menu — scraped from `capture-pane` (its options are NOT in the .jsonl while pending; see pendingPrompt.js).
+  // Returns { prompt: {kind,title,options,cursor} | null }. Polled by the 对话 lens only while a gate is up.
+  r.get('/pending-prompt', async (req, res, next) => {
+    if (!isPaneId(req.query.pane)) return res.status(400).json({ error: 'bad pane id' });
+    try {
+      const text = await commands.capturePlain(req.query.pane);
+      return res.json({ prompt: parsePendingPrompt(text) });
+    } catch (e) { next(e); }
+  });
+
+  // The pane's CURRENT context-window occupancy (model + used %) — the number Claude Code shows before
+  // auto-compact. Joined pane→session (hook state) → the statusLine capturer's per-session snapshot. Returns
+  // { model, usedPercent } (either may be null: capturer not opted in / session hasn't rendered / no hooks).
+  // The 对话 composer polls this to show a small "模型 · 24%" chip. Best-effort: never 500 on a missing file.
+  r.get('/context', (req, res, next) => {
+    if (!isPaneId(req.query.pane)) return res.status(400).json({ error: 'bad pane id' });
+    try {
+      const hooked = claudeEvents && claudeEvents.paneSession ? claudeEvents.paneSession(req.query.pane) : null;
+      const sid = hooked && (hooked.sessionId || (hooked.transcriptPath ? path.basename(hooked.transcriptPath).replace(/\.jsonl$/, '') : null));
+      const ctx = sid ? readClaudeContext(sid) : null;
+      return res.json({ model: (ctx && ctx.model) || null, usedPercent: (ctx && typeof ctx.usedPercent === 'number') ? ctx.usedPercent : null });
+    } catch (e) { next(e); }
+  });
+
+  r.get('/transcript', async (req, res, next) => {
+    if (!isPaneId(req.query.pane)) return res.status(400).json({ error: 'bad pane id' });
+    const limit = Math.min(Math.max(Number(req.query.limit) || 10, 1), 100);
+    const before = req.query.before != null && req.query.before !== '' ? Number(req.query.before) : null;
+    try {
+      // Bind pane→session via the hook state's per-pane transcript_path (authoritative — see claudeEvents
+      // .paneSession) when available; only a pane with no hook state (hooks off / not a Claude pane) falls
+      // back to cwd→newest-jsonl, which can't tell apart two sessions that share a cwd.
+      let file = null;
+      let sessionId = null;
+      const hooked = claudeEvents && claudeEvents.paneSession ? claudeEvents.paneSession(req.query.pane) : null;
+      if (hooked && hooked.transcriptPath) {
+        file = hooked.transcriptPath;
+        sessionId = hooked.sessionId || path.basename(file).replace(/\.jsonl$/, '');
+      }
+      if (!file) {
+        const cwd = await commands.paneCurrentPath(req.query.pane);
+        const dir = projectsDir();
+        const resolved = await resolveEncodedDirSession(dir, cwd);
+        if (resolved.sessionId) {
+          file = path.join(dir, encodeProjectDir(cwd), resolved.sessionId + '.jsonl');
+          sessionId = resolved.sessionId;
+        }
+      }
+      const empty = { messages: [], hash: '', session: sessionId || null, hasMore: false, firstSeq: null };
+      if (!file) return res.json(empty);
+      let text;
+      try { text = fs.readFileSync(file, 'utf8'); } catch { return res.json(empty); }
+      const all = parseTranscript(text.split('\n')).map((m, k) => ({ ...m, k })); // k = stable global ordinal
+      const pool = before == null ? all : all.filter((m) => m.k < before);
+      const messages = pool.slice(-limit);
+      const firstSeq = messages.length ? messages[0].k : null;
+      const hasMore = pool.length > messages.length;
+      if (before == null) {
+        const hash = createHash('sha1').update(JSON.stringify(messages)).digest('hex').slice(0, 16);
+        if (req.query.since === hash) return res.status(204).end();
+        return res.json({ messages, hash, session: sessionId, hasMore, firstSeq });
+      }
+      return res.json({ messages, session: sessionId, hasMore, firstSeq });
+    } catch (e) { next(e); }
+  });
+  return r;
+}

package/src/server.js

@@ -7,6 +7,8 @@ import { loadToken } from './auth.js';
 import { createApiRouter } from './httpApi.js';
 import { loadUploadExts } from './uploadTypes.js';
 import { createClaudeEvents } from './claudeEvents.js';
+import { syncHooks } from './cli/claudeHooks.js';
+import { claudeStatePath } from './cli/state.js';
 import * as commands from './tmux/commands.js';
 import * as push from './push.js';
 import { cacheControlFor } from './staticCache.js';
@@ -32,6 +34,17 @@ const uploadExts = loadUploadExts();
 const events = createClaudeEvents({ commands, push });
 events.start();
 
+// Keep an already-opted-in user's Claude hooks in step with this handmux version on restart: newly-added
+// lifecycle events (e.g. SessionStart, which rebinds the 对话 lens after /clear) and a refreshed
+// handmux-write.cjs land via `./deploy.sh` alone — no phone re-enable. A strict no-op unless our hooks are
+// already installed; best-effort and must never block or crash startup (pure fs, no subprocess).
+try {
+  syncHooks(homedir(), {
+    srcDir: path.resolve(here, '../hooks'),
+    stateFile: process.env.CLAUDE_STATE_FILE || claudeStatePath(homedir()),
+  });
+} catch { /* best effort — hook sync never fails startup */ }
+
 // Static-site + dynamic preview. The dynamic side is enabled by HANDMUX_PREVIEW_DOMAIN (the wildcard
 // base domain, e.g. preview.example.com); unset → static only. One registry instance is shared by the
 // API (register/list/remove), the /preview static layer, and the Host-based dynamic proxy.

package/src/tmux/commands.js

@@ -78,10 +78,10 @@ export async function listPaneIds(target) {
 // 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}']))
+    '#{pane_id}\t#{pane_current_command}\t#{pane_tty}\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 };
+      const [id, cmd, tty, session, window, windowName] = l.split('\t');
+      return { id, cmd, tty, session, window, windowName };
     });
 }
 
@@ -94,6 +94,12 @@ export async function capturePane(paneId, linesBack) {
   return runTmux(['capture-pane', '-p', '-e', '-N', '-S', String(-Math.abs(linesBack)), '-t', paneId]);
 }
 
+// Plain visible-screen capture — NO SGR escapes (unlike capturePane's `-e`), so the text parses cleanly.
+// Used to scrape a pending prompt/menu off the screen (see pendingPrompt.js).
+export async function capturePlain(paneId) {
+  return runTmux(['capture-pane', '-p', '-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;

package/src/transcriptParse.js

@@ -0,0 +1,169 @@
+// Pure: a Claude Code jsonl session log (array of lines) → normalized chat messages. No I/O.
+// Only user/assistant turns become bubbles; every other top-level `type` (attachment, system, last-prompt,
+// mode, permission-mode, ai-title, file-history-snapshot, queue-operation, …) is skipped. tool_use and its
+// later tool_result are folded into ONE tool message (paired by tool_use_id); an unmatched tool_result is
+// dropped (its tool_use is in an earlier, not-yet-loaded chunk). Bad/blank lines are skipped, never thrown.
+//
+// Meta scaffolding is DROPPED so the 对话 lens shows only real turns; the reliable signal is the top-level
+// boolean flags — `isMeta` (skill/workflow injections, "Base directory for this skill…", caveats) and
+// `isCompactSummary` (the "session is being continued…" wall) — NOT text matching.
+//
+// Slash commands (`/compact`, `/model`, `/clear`, …) are NOT dropped — they surface as a quiet 'slash'
+// marker (a centered system row), because a command the user ran IS part of the conversation and hiding it
+// leaves the phone with no feedback. Claude Code logs each as a `<command-name>/x</command-name>` USER turn
+// (the canonical form; the bare "/x" input is a separate queue-operation / plain user line we still drop, to
+// avoid a double). The command's `<local-command-stdout>` echo is folded onto the preceding marker as its
+// `.result` (ANSI-stripped, capped) — and its PRESENCE means the command COMPLETED. An interactive picker
+// (bare `/model`, `/plugin`, …) still open in the terminal has written no result yet, which is exactly how
+// the UI tells a finished command from one that needs the user to drop to the terminal lens and pick.
+// Matching is a tag prefix ANCHORED at the start of a USER turn's text: an assistant reply that merely
+// mentions `<command-name>` in prose (e.g. discussing this very code) must NOT be caught.
+const KEEP = new Set(['user', 'assistant']);
+const SCAFFOLD_RE = /^\s*<(?:command-name|command-message|command-args|local-command-stdout|local-command-caveat|bash-input|bash-stdout|bash-stderr)>/;
+// Besides the <command-name> scaffold form, Claude Code ALSO logs the raw slash-command input as a plain,
+// flagless user turn (content exactly "/compact", "/model sonnet", …) — redundant with the scaffold marker,
+// and after a /compact it's the LAST turn, so leaving it in would make the 对话 lens read a trailing user
+// bubble and light the "reply coming" typing wave forever. Drop it — anchored to a single leading /command
+// token followed by whitespace/EOL, so a path-like message ("/Users/demo/foo.js …") or prose is NOT eaten.
+const SLASH_CMD_RE = /^\s*\/[a-z][\w-]*(?:\s|$)/i;
+// The canonical scaffold form of a slash command: capture the name and any args, so the marker can tell a
+// bare `/model` (may open a picker) from `/model sonnet` (applies directly). The stdout echo is a separate
+// user turn right after; its inner text (closing tag stripped, ANSI stripped, capped) becomes the result.
+const CMD_NAME_RE = /^\s*<command-name>\s*\/?([\w-]+)\s*<\/command-name>/i;
+const CMD_ARGS_RE = /<command-args>([\s\S]*?)<\/command-args>/i;
+const STDOUT_RE = /^\s*<local-command-stdout>([\s\S]*)$/i;
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const SLASH_RESULT_CAP = 140;
+const stripAnsi = (s) => (typeof s === 'string' ? s.replace(ANSI_RE, '') : '');
+
+// A file-edit diff from a jsonl line's top-level `toolUseResult`, or null if the tool didn't edit a file.
+// Non-empty structuredPatch → count +/- lines and keep the hunks (for the expandable coloured view). Empty
+// patch but a create → every content line is an addition. Anything else (Bash/Read/…) → null.
+function extractDiff(r) {
+  if (!r || typeof r !== 'object') return null;
+  const patch = Array.isArray(r.structuredPatch) ? r.structuredPatch : null;
+  if (patch && patch.length) {
+    let added = 0, removed = 0;
+    const hunks = [];
+    for (const h of patch) {
+      const lines = Array.isArray(h.lines) ? h.lines : [];
+      for (const ln of lines) { const c = typeof ln === 'string' ? ln[0] : ''; if (c === '+') added++; else if (c === '-') removed++; }
+      hunks.push({ oldStart: h.oldStart, newStart: h.newStart, lines });
+    }
+    return { added, removed, hunks };
+  }
+  if (r.type === 'create' && typeof r.content === 'string') {
+    return { added: r.content ? r.content.split('\n').length : 0, removed: 0, hunks: null, created: true };
+  }
+  return null;
+}
+
+function resultText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map((c) => (c && c.type === 'text' ? (c.text || '') : '')).join('');
+  return '';
+}
+
+// Leading text of a message's content (string as-is, or the first text item of an array) — used only to
+// probe for a scaffolding tag at the very start. tool_result-only user turns yield '' and are never matched.
+function leadingText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    const t = content.find((c) => c && c.type === 'text');
+    return t ? (t.text || '') : '';
+  }
+  return '';
+}
+
+export function parseTranscript(lines) {
+  const msgs = [];
+  const byToolId = new Map(); // tool_use_id → the tool message awaiting its result
+  let i = 0;
+  for (const raw of lines) {
+    const s = typeof raw === 'string' ? raw.trim() : '';
+    if (!s) { i++; continue; }
+    let o;
+    try { o = JSON.parse(s); } catch { i++; continue; }
+    const m = o && o.message;
+    if (!KEEP.has(o && o.type) || !m || typeof m !== 'object') { i++; continue; }
+    if (o.isMeta === true) { i++; continue; }
+    // A compaction wall (isCompactSummary): don't render the (huge) summary text as a bubble, but DO leave a
+    // quiet divider marker where it happened, so the 对话 lens shows "上下文已压缩" between the old and new
+    // context instead of the conversation silently jumping. (A no-op /compact writes no such entry → no
+    // divider, correctly.) Rendered centered like the interrupt marker.
+    if (o.isCompactSummary === true) {
+      msgs.push({ i, type: 'compact', ts: typeof o.timestamp === 'string' ? o.timestamp : undefined });
+      i++; continue;
+    }
+    // The jsonl line's wall-clock (ISO string) — carried onto each message so the 对话 lens can show a
+    // time separator between turns. Absent on some lines (older logs) → undefined; the UI shows nothing
+    // rather than a fabricated time ("有地方取就要，没有就不要").
+    const ts = typeof o.timestamp === 'string' ? o.timestamp : undefined;
+    const role = m.role === 'user' ? 'user' : 'assistant';
+    if (role === 'user') {
+      const lead = leadingText(m.content);
+      // A slash command → a quiet centered 'slash' marker (see the header note). Name + optional args.
+      const nameM = CMD_NAME_RE.exec(lead);
+      if (nameM) {
+        const argsM = CMD_ARGS_RE.exec(lead);
+        const args = argsM ? argsM[1].trim() : '';
+        const mk = { i, type: 'slash', name: '/' + nameM[1], ts };
+        if (args) mk.args = args;
+        msgs.push(mk);
+        i++; continue;
+      }
+      // Its stdout echo → fold onto the marker just pushed as `.result` (presence ⇒ the command completed).
+      const outM = STDOUT_RE.exec(lead);
+      if (outM) {
+        const last = msgs[msgs.length - 1];
+        if (last && last.type === 'slash' && last.result === undefined) {
+          const txt = stripAnsi(outM[1].replace(/<\/local-command-stdout>\s*$/i, '')).trim();
+          if (txt) last.result = txt.length > SLASH_RESULT_CAP ? txt.slice(0, SLASH_RESULT_CAP) + '…' : txt;
+        }
+        i++; continue;
+      }
+      // Other scaffolding (<command-message>, caveat, bash-*) and the bare "/x" input line: still dropped.
+      if (SCAFFOLD_RE.test(lead) || SLASH_CMD_RE.test(lead)) { i++; continue; }
+    }
+    // ESC-interrupt: Claude Code appends a standalone user line carrying a top-level `interruptedMessageId`
+    // (content is just "[Request interrupted by user…]"). It's NOT something the user typed — surface it as a
+    // quiet 'interrupt' marker (rendered as a small centered hint), never as a prominent user bubble. Detect
+    // by the structural field, falling back to the marker text for older logs.
+    if (typeof o.interruptedMessageId === 'string' || (role === 'user' && /^\[Request interrupted by user/.test(leadingText(m.content)))) {
+      msgs.push({ i, type: 'interrupt', ts });
+      i++; continue;
+    }
+    const items = typeof m.content === 'string'
+      ? [{ type: 'text', text: m.content }]
+      : Array.isArray(m.content) ? m.content : [];
+    for (const it of items) {
+      if (!it || typeof it !== 'object') continue;
+      // .trim() here is a truthiness guard only (dropping whitespace-only text items to avoid empty
+      // bubbles) — the pushed `it.text` below is the untrimmed original, so real text's internal/
+      // leading/trailing whitespace is preserved verbatim.
+      if (it.type === 'text' && it.text && it.text.trim()) {
+        msgs.push({ i, role, type: 'text', text: it.text, ts });
+      } else if (it.type === 'thinking' && it.thinking) {
+        msgs.push({ i, role: 'assistant', type: 'thinking', text: it.thinking, ts });
+      } else if (it.type === 'tool_use') {
+        const tm = { i, role: 'assistant', type: 'tool', ts, tool: { name: it.name || '', input: it.input || {}, result: null, isError: false } };
+        if (it.id) byToolId.set(it.id, tm);
+        msgs.push(tm);
+      } else if (it.type === 'tool_result') {
+        const tm = it.tool_use_id && byToolId.get(it.tool_use_id);
+        if (tm) {
+          tm.tool.result = resultText(it.content);
+          tm.tool.isError = !!it.is_error;
+          // Claude Code stores a real per-hunk diff for file edits on the SAME line's top-level
+          // `toolUseResult.structuredPatch` (hunks of {oldStart,newStart,lines[]}, each line prefixed
+          // +/-/space) — the exact data the CLI renders. Fold it into the tool message so the 对话 chip
+          // can show +A/−B and open the coloured diff, instead of the bland "…updated successfully" string.
+          // A file CREATE has an empty patch but `type:'create'` + `content` → treat every line as added.
+          tm.tool.diff = extractDiff(o.toolUseResult);
+        }
+      }
+    }
+    i++;
+  }
+  return msgs;
+}

package/src/usage.js

@@ -11,6 +11,19 @@ import { homedir } from 'node:os';
 import { pocketHome } from './cli/state.js';
 
 export function claudeUsagePath(home = homedir()) { return path.join(pocketHome(home), 'claude-usage.json'); }
+export function claudeContextDir(home = homedir()) { return path.join(pocketHome(home), 'context'); }
+
+// Per-session context-window snapshot the statusLine capturer writes to ~/.handmux/context/<sessionId>.json
+// ({ model, usedPercent, updatedAt }). null if the capturer isn't wired, the session never rendered, or the
+// id is unsafe. Used to show the CURRENT pane's context % (the global claude-usage.json can't — it's one
+// last-writer-wins snapshot across all sessions). sessionId is sanitised to keep the read inside the dir.
+export function readClaudeContext(sessionId, home = homedir()) {
+  if (typeof sessionId !== 'string' || !/^[\w-]+$/.test(sessionId)) return null;
+  try {
+    const snap = JSON.parse(fs.readFileSync(path.join(claudeContextDir(home), `${sessionId}.json`), 'utf8'));
+    return (snap && typeof snap === 'object' && !Array.isArray(snap)) ? snap : null;
+  } catch { return null; }
+}
 export function codexSessionsDir(home = homedir()) { return path.join(home, '.codex', 'sessions'); }
 
 // Claude: read the statusLine snapshot. null if the capturer isn't wired / never populated it.