handmux 0.6.0 → 0.8.0

package/public/index.html

@@ -42,8 +42,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-DlO8ul0J.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-_nvN0yNe.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-_nvN0yNe.css"></noscript>
+    <script type="module" crossorigin src="/assets/index-aNwLKI4h.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CKVeisd1.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-CKVeisd1.css"></noscript>
   </head>
   <body>
     <div id="boot-splash" aria-hidden="true">

package/src/claudeEvents.js

@@ -62,7 +62,6 @@ function readStateFile(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() } = {}) {
   const lastPushed = {}; // pane → 'needs' | 'done' | null  (in-process push-transition dedup, by display view)
-  const dotClearedFor = {}; // pane → ts of the stuck 进行中 we already cleared @claude_dot for (clear once)
   // 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
   // would see an empty dedup and re-push every resting pane — a flood of "historical" notifications on
@@ -136,14 +135,8 @@ export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE,
       // (2) roster — drop ended / dead / claude-exited panes; resolve location from the live tmux row.
       if (!c || c.kind === 'end' || gone) continue;
       // Expire a 进行中 latched past the TTL (an ESC-interrupt / walk-away that never got a Stop): drop it
-      // from the roster and clear the PC @claude_dot once, so the stuck blue dot goes away. See WORKING_TTL_MS.
-      if (c.kind === 'working' && now() - (rec.ts || 0) > WORKING_TTL_MS) {
-        if (live && typeof commands.runTmux === 'function' && dotClearedFor[pane] !== rec.ts) {
-          dotClearedFor[pane] = rec.ts;
-          try { await commands.runTmux(['set-option', '-w', '-t', pane, '@claude_dot', '']); } catch { /* best effort */ }
-        }
-        continue;
-      }
+      // 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;
       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 };

package/src/cli/i18n/en.js

@@ -80,11 +80,11 @@ export default {
   'hooks.removed': '✓ Agent hooks removed.',
   'hooks.usage': 'usage: handmux hooks install|uninstall',
 
-  // tmux status-dot offer
-  'tmuxdot.tip': '  Tip: to show a Claude status dot on each tmux window, run `handmux hooks install` from an interactive terminal — it wires {conf} for you (see tmux/README.md in the handmux package).',
-  'tmuxdot.confirm': 'Also show a per-window Claude status dot in tmux? (adds a block to ~/.tmux.conf)',
-  'tmuxdot.added': '✓ tmux dot added → {path}',
-  'tmuxdot.apply': '  Apply with: tmux source-file ~/.tmux.conf  (it changes the shared tmux server — all clients, including your PC).',
+  // Claude statusLine usage capturer (powers the phone Usage page's 5h/weekly bars)
+  'statusline.confirmEnable': "Show Claude's 5h/weekly usage on the phone? (installs a Claude statusLine)",
+  'statusline.installed': '✓ Claude statusLine installed → ~/.claude/settings.json',
+  'statusline.reload': '  Open a new Claude session to load it; the Usage page fills in as it reports.',
+  'statusline.foreignHint': 'You already have a Claude statusLine — leaving it untouched. To also feed the phone Usage page, pipe it through our capturer:',
 
   // service
   'service.usage': 'usage: handmux service install [start-flags] | handmux service uninstall',

package/src/cli/i18n/zh.js

@@ -79,11 +79,11 @@ export default {
   'hooks.removed': '✓ agent hooks 已移除。',
   'hooks.usage': '用法:handmux hooks install|uninstall',
 
-  // tmux 状态点
-  'tmuxdot.tip': '  提示:想在每个 tmux 窗口上显示 Claude 状态点,请在交互终端里运行 `handmux hooks install` —— 它会替你写好 {conf}(见 handmux 包内的 tmux/README.md)。',
-  'tmuxdot.confirm': '同时在 tmux 里显示每个窗口的 Claude 状态点吗?(会往 ~/.tmux.conf 加一段)',
-  'tmuxdot.added': '✓ tmux 状态点已添加 → {path}',
-  'tmuxdot.apply': '  生效方式:tmux source-file ~/.tmux.conf  (它改的是共享 tmux 服务器 —— 对所有客户端生效,包括你的电脑)。',
+  // Claude statusLine 用量捕获(点亮手机用量页的 5h/周额度条)
+  'statusline.confirmEnable': '在手机上显示 Claude 的 5h/周额度?(会安装一个 Claude statusLine)',
+  'statusline.installed': '✓ Claude statusLine 已安装 → ~/.claude/settings.json',
+  'statusline.reload': '  新开一个 Claude 会话以加载;用量页会随上报逐渐填上。',
+  'statusline.foreignHint': '你已经有自己的 Claude statusLine —— 保持不动。想同时点亮手机用量页,把它接到我们的捕获器后面:',
 
   // service
   'service.usage': '用法:handmux service install [start-flags] | handmux service uninstall',

package/src/cli/setupWizard.js

@@ -124,7 +124,10 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
     log.log(t('setup.tunnel2'));
     log.log(t('setup.tunnel3'));
     log.log(t('setup.tunnel4'));
-    const curPick = { none: '1', cloudflare: '2', 'cloudflare-named': '3', ssh: '4' }[cur.tunnel] || '3';
+    // Default to the CURRENT tunnel when re-running; for a brand-new user (no config) default to '2'
+    // (cloudflare quick tunnel — zero-config, instant public URL) rather than '3' (cloudflare-named),
+    // which a bare-Enter newcomer can't complete without a Cloudflare login + their own domain.
+    const curPick = { none: '1', cloudflare: '2', 'cloudflare-named': '3', ssh: '4' }[cur.tunnel] || '2';
     const pick = await ask(rl, t('setup.choose'), curPick);
     const tunnel = { 1: 'none', 2: 'cloudflare', 3: 'cloudflare-named', 4: 'ssh' }[pick];
     if (!tunnel) { log.error(t('setup.invalid')); return null; }

package/src/cli/statusLine.js

@@ -0,0 +1,79 @@
+// Install/uninstall the handmux Claude statusLine — the capturer that snapshots the 5h/weekly rate-limit %
+// (from Claude Code's statusLine stdin, the only documented local source) to ~/.handmux/claude-usage.json
+// for the phone's Usage page. Opt-in, and NON-DESTRUCTIVE by design: Claude allows exactly one statusLine,
+// so if the user already has their OWN we NEVER clobber it — we report 'foreign' and the CLI prints a
+// one-line compose snippet instead. We only ever write settings.statusLine when it's absent or already ours.
+//
+// Iron rule (same as claudeHooks): only ever touch ~/.handmux/ and — after opt-in — ~/.claude/. Never
+// create ~/.claude.
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+
+const STATUS_MARK = 'handmux-statusline.cjs'; // identifies our statusLine command among the user's own
+const SCRIPT = 'handmux-statusline.cjs';
+
+function claudeDir(home = homedir()) { return path.join(home, '.claude'); }
+function settingsPath(home = homedir()) { return path.join(claudeDir(home), 'settings.json'); }
+
+function readSettings(home) {
+  try { return JSON.parse(fs.readFileSync(settingsPath(home), 'utf8')); } catch { return {}; }
+}
+function writeJsonAtomic(file, obj) {
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+function isOurs(sl) {
+  return !!(sl && typeof sl.command === 'string' && sl.command.includes(STATUS_MARK));
+}
+
+// 'no-claude' → ~/.claude absent. 'ours' → our statusLine is installed. 'foreign' → the user has their own
+// statusLine (we must not touch it). 'absent' → Claude Code is here but no statusLine configured.
+export function statusLineStatus(home = homedir()) {
+  if (!fs.existsSync(claudeDir(home))) return 'no-claude';
+  const sl = readSettings(home).statusLine;
+  if (isOurs(sl)) return 'ours';
+  if (sl && (sl.command || sl.type)) return 'foreign';
+  return 'absent';
+}
+
+// The exact command a user with an EXISTING statusline appends to capture without changing their display:
+// pipe their statusline's stdin through our capturer in TEE mode first. Returned so the CLI can print it.
+export function composeHint(home = homedir(), { usageFile } = {}) {
+  const dest = path.join(claudeDir(home), 'hooks', SCRIPT);
+  return `HANDMUX_STATUS_TEE=1 node ${dest} ${usageFile} | <your existing statusline>`;
+}
+
+// Install (opt-in): copy the capturer to ~/.claude/hooks/ and point settings.statusLine at it — but ONLY
+// when it's safe (absent or already ours). A 'foreign' statusLine is left untouched. Returns { status }.
+//   srcDir    = bundled hooks dir (server/hooks)
+//   usageFile = ~/.handmux/claude-usage.json (the snapshot the server reads)
+export function installStatusLine(home = homedir(), { srcDir, usageFile } = {}) {
+  if (!fs.existsSync(claudeDir(home))) return { status: 'no-claude' };
+  const status = statusLineStatus(home);
+  // Always deploy the capturer script (it's ours, inert until invoked) so the compose one-liner works even
+  // in the foreign case. Only the settings.statusLine write is gated on not clobbering the user's own.
+  const hooksDir = path.join(claudeDir(home), 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const dest = path.join(hooksDir, SCRIPT);
+  fs.copyFileSync(path.join(srcDir, SCRIPT), dest);
+  if (status === 'foreign') return { status: 'foreign', script: dest }; // never touch their statusLine
+  const settings = readSettings(home);
+  settings.statusLine = { type: 'command', command: `node ${dest} ${usageFile}` };
+  writeJsonAtomic(settingsPath(home), settings);
+  return { status: 'installed' };
+}
+
+// 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()) {
+  const settings = readSettings(home);
+  if (isOurs(settings.statusLine)) {
+    delete settings.statusLine;
+    if (fs.existsSync(settingsPath(home))) writeJsonAtomic(settingsPath(home), settings);
+  }
+  try { fs.unlinkSync(path.join(claudeDir(home), 'hooks', SCRIPT)); } catch { /* already gone */ }
+  return { status: 'absent' };
+}

package/src/cli/updateCheck.js

@@ -14,7 +14,7 @@ import { pocketHome } from './state.js';
 import { t } from './i18n/index.js';
 
 export const PKG_NAME = 'handmux';
-export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // refresh the cached "latest" at most once a day
+export const CHECK_INTERVAL_MS = 60 * 60 * 1000; // refresh the cached "latest" at most once an hour
 
 export function updateCachePath(home) { return path.join(pocketHome(home), 'update-check.json'); }
 
@@ -60,6 +60,24 @@ export function fetchLatestVersion({ timeoutMs = 4000, run = spawnSync } = {}) {
   } catch { return null; }
 }
 
+// Non-blocking refresh for the long-running server: query npm asynchronously (never stalls the event loop
+// the way the CLI's spawnSync path would) and persist the same {checkedAt, latest} cache the CLI reads. The
+// /api/version route calls this when the cache is stale, so the phone opening the app keeps `latest` current
+// without the user re-running the CLI. Best-effort: npm missing/offline/blocked leaves the prior latest.
+export function refreshLatestAsync(home, { now = Date.now(), spawnFn = spawn, timeoutMs = 4000 } = {}) {
+  try {
+    const child = spawnFn('npm', ['view', PKG_NAME, 'version'], { timeout: timeoutMs });
+    let out = '';
+    child.stdout?.on('data', (d) => { out += d; });
+    child.on('close', (code) => {
+      const v = String(out).trim();
+      const latest = (code === 0 && parts(v)) ? v : (readCache(home)?.latest ?? null);
+      writeCache(home, { checkedAt: now, latest });
+    });
+    child.on('error', () => { /* npm missing/offline — leave the cache untouched */ });
+  } catch { /* best effort */ }
+}
+
 // The hidden `__update-check` worker (runs detached, prints nothing): refresh the cache. On a failed fetch
 // keep the previously-known latest but still stamp checkedAt, so a flaky network doesn't re-spawn every run.
 export function runUpdateCheck(home, { now = Date.now(), ...opts } = {}) {

package/src/git.js

@@ -3,13 +3,37 @@ import { homedir } from 'node:os';
 import { join, basename, isAbsolute } from 'node:path';
 import { execFile } from 'node:child_process';
 import { isUnder } from './docPath.js';
+import { defaultExtraRoots } from './docs.js';
 
 // 只读子命令白名单：命令层硬过滤，杜绝任何写操作混入。
 const READONLY = new Set(['rev-parse', 'status', 'log', 'for-each-ref', 'diff', 'show', 'diff-tree']);
 const MAX_BUFFER = 8 * 1024 * 1024;
 
-export function createGit({ home } = {}) {
+export function createGit({ home, extraRoots = [] } = {}) {
   const realHomeP = fs.realpath(home);
+  // Same multi-root allow-list as createDocs: $HOME plus a few roots OUTSIDE it (/tmp, $TMPDIR) so a repo
+  // an agent is working in under /tmp is reachable from the phone. Resolved once — realpath'd, deduped,
+  // missing ones skipped, extras already inside home dropped (home covers them). Keeps git browsing in
+  // lock-step with the file/doc browser; git.js used to be home-only, which rejected legit repos under
+  // /tmp with a red "outside home".
+  const rootsP = (async () => {
+    const rh = await realHomeP;
+    const out = [rh];
+    for (const r of extraRoots) {
+      if (typeof r !== 'string' || !r) continue;
+      let real;
+      try { real = await fs.realpath(r); } catch { continue; } // not present on this host → skip
+      if (isUnder(real, rh) || out.includes(real)) continue;   // already covered by home / dup
+      out.push(real);
+    }
+    return out;
+  })();
+  // The allowed root that contains `real` (longest match wins should roots ever nest), or null.
+  const rootOf = (real, roots) => {
+    let best = null;
+    for (const r of roots) if (isUnder(real, r) && (!best || r.length > best.length)) best = r;
+    return best;
+  };
 
   function git(cwd, args) {
     const sub = args[0];
@@ -23,10 +47,9 @@ export function createGit({ home } = {}) {
 
   async function resolveRepo(rawPath) {
     if (typeof rawPath !== 'string' || !isAbsolute(rawPath)) return { error: 'not absolute', status: 400 };
-    const rh = await realHomeP;
     let real;
     try { real = await fs.realpath(rawPath); } catch { return { error: 'not found', status: 404 }; }
-    if (!isUnder(real, rh)) return { error: 'outside home', status: 400 };
+    if (!rootOf(real, await rootsP)) return { error: 'outside home', status: 400 };
     return { real };
   }
 
@@ -182,4 +205,4 @@ export function createGit({ home } = {}) {
   return { resolveRepo, isRepo, detectRepos, status, log, branches, diff, commit };
 }
 
-export const defaultGit = createGit({ home: homedir() });
+export const defaultGit = createGit({ home: homedir(), extraRoots: defaultExtraRoots() });

package/src/httpApi.js

@@ -24,10 +24,20 @@ import { hooksStatus, installHooks } from './cli/claudeHooks.js';
 import { codexHooksStatus, installCodexHooks } from './cli/codexHooks.js';
 import { claudeStatePath } from './cli/state.js';
 import { scanOrphans, takeoverOrphan, defaultProjectsDir } from './orphans.js';
+import { getUsageCached } from './usage.js';
+import { readFileSync } from 'node:fs';
+import { readCache, isNewer, shouldRefresh, refreshLatestAsync } from './cli/updateCheck.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const HOOKS_SRC = resolvePath(here, '../hooks'); // server/hooks (bundled scripts)
 
+// The installed CLI version (server/package.json) — read once. The phone compares this against the cached
+// npm "latest" to surface an update hint ("run `handmux update` on your computer"); see the /version route.
+const PKG_VERSION = (() => {
+  try { return JSON.parse(readFileSync(resolvePath(here, '../package.json'), 'utf8')).version || null; }
+  catch { return null; }
+})();
+
 // Summarize inbox-hook state across every coding agent for the phone: 'installed' if any agent is wired,
 // 'absent' if an agent is present but none wired (→ offer the one-tap enable), 'no-claude' if there's no
 // agent at all (→ hide the prompt).
@@ -39,10 +49,24 @@ function combinedHooksStatus(home) {
   return 'no-claude';
 }
 
-const ALLOWED_KEYS = new Set([
-  'Up', 'Down', 'Left', 'Right', 'Space', 'Enter', 'Escape', 'Tab', 'BTab', 'BSpace',
-  'C-c', 'C-d', 'C-z', 'C-l', 'C-r', 'C-o', 'C-e',
-]);
+// Keys the mobile keyboard may send via /keys. A controlled vocabulary of named tmux keys, PLUS
+// live-modifier combinations (Ctrl/Alt + a single letter or digit) so the keyboard's Ctrl modifier
+// can compose any readline/tmux binding (C-r, C-w, C-a, the tmux prefix, …) without enumerating each
+// one here. tmux send-keys key names are themselves a closed set, so this stays a strict allowlist
+// (never a passthrough): a key either names an approved token or matches the modifier shape, or it's
+// rejected. The old fixed C-c/C-d/C-z/C-l/C-r/C-o/C-e all still match `C-[a-z0-9]`.
+const NAMED = 'Up|Down|Left|Right|Space|Enter|Escape|Tab|BTab|BSpace|Home|End|PageUp|PageDown';
+// A named tmux key with any (optional) modifier prefixes, in the canonical C- M- S- order buildChord emits.
+// Covers the plain keys (Up, Tab, …) AND modifier combos on them — C-Up, M-Up, S-Left, C-Tab, C-S-Up, … —
+// so the 按键 editor can bind e.g. Ctrl+Arrow or Ctrl+Tab, not just Ctrl + a letter.
+const NAMED_KEY = new RegExp(`^(?:C-)?(?:M-)?(?:S-)?(?:${NAMED})$`);
+// Ctrl and/or Alt + one letter or digit — C-r, C-a, M-b, C-M-k. Must carry a modifier (never a bare char;
+// Shift+letter folds to the uppercase character, so no S- here).
+const CHAR_KEY = /^(?:C-)?(?:M-)?[a-z0-9]$/;
+export function isAllowedKey(k) {
+  if (typeof k !== 'string') return false;
+  return NAMED_KEY.test(k) || (CHAR_KEY.test(k) && k.includes('-'));
+}
 
 // Pause between typing the text and pressing Enter on a /send. A TUI like Claude Code needs a
 // beat to ingest the pasted line; without it, the Enter can fold into the input as a newline
@@ -270,11 +294,26 @@ export function createApiRouter({
     } catch (e) { next(e); }
   });
 
+  // First free filename in `dir`: the name as-is, else Finder-style "base (1).ext", "base (2).ext", …
+  // (the suffix goes before the extension). Bounded; a pathological fallback keeps it from looping.
+  async function freeUploadName(dir, name) {
+    const dot = name.lastIndexOf('.');
+    const base = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : '';
+    let cand = name;
+    for (let n = 1; n <= 999; n++) {
+      try { await fsp.access(joinPath(dir, cand)); } // exists → try the next suffix
+      catch { return cand; }                          // ENOENT → free
+      cand = `${base} (${n})${ext}`;
+    }
+    return `${base} (${randomBytes(3).toString('hex')})${ext}`;
+  }
+
   // Upload a file into a directory under $HOME. Multipart streamed via busboy (the file never fully
   // buffers in memory, and the size cap aborts mid-stream). Guards, in order: target dir must be a
   // non-hidden subdir of home (resolveUploadDir); filename sanitised to a dotless basename; extension
-  // in the allow-list; no overwrite of an existing name. The client appends `dir` BEFORE the file
-  // part, so the field is known by the time the file event fires.
+  // in the allow-list. A name clash auto-suffixes (never overwrites). The client appends `dir` BEFORE
+  // the file part, so the field is known by the time the file event fires.
   r.post('/upload', (req, res) => {
     let bb;
     // defParamCharset:'utf8' — browsers put a non-ASCII (e.g. Chinese) filename into the multipart
@@ -306,11 +345,13 @@ export function createApiRouter({
         const target = stash ? await docs.resolveStashDir(dir) : await docs.resolveUploadDir(dir);
         if (target.error) { file.resume(); return done(target.status, { error: target.error }); }
 
-        const dest = joinPath(target.real, name);
-        try { await fsp.access(dest); file.resume(); return done(409, { error: 'exists' }); }
-        catch { /* name free → proceed */ }
+        // Finder-style de-dup: never 409 / overwrite on a name clash — pick the first free "base (n).ext".
+        // Resolved up front for the response; re-resolved at link time if the race is lost (see below).
+        const origName = name;
+        let finalName = await freeUploadName(target.real, origName);
+        let dest = joinPath(target.real, finalName);
 
-        tmp = joinPath(target.real, `.${name}.uploading-${randomBytes(6).toString('hex')}`);
+        tmp = joinPath(target.real, `.${finalName}.uploading-${randomBytes(6).toString('hex')}`);
         ws = createWriteStream(tmp);
         ws.on('error', () => { file.resume(); cleanup().finally(() => done(500, { error: 'write failed' })); });
         ws.on('finish', async () => {
@@ -319,13 +360,22 @@ export function createApiRouter({
           // maxUploadBytes is allowed; only strictly-larger trips it.)
           if (file.truncated) { await cleanup(); return done(413, { error: 'too large' }); }
           try {
-            // link (NOT rename): if the name appeared meanwhile (a concurrent upload won the race)
-            // link throws EEXIST → the loser gets 409. So we NEVER silently overwrite another file.
-            try { await fsp.link(tmp, dest); }
-            catch (e) { if (e.code === 'EEXIST') { await cleanup(); return done(409, { error: 'exists' }); } throw e; }
+            // link (NOT rename): if the name appeared meanwhile (a concurrent upload won the race) link
+            // throws EEXIST → we pick the NEXT free suffix and retry, so we still never overwrite another
+            // file, and a clash auto-suffixes rather than 409s.
+            let linked = false;
+            for (let attempt = 0; attempt < 6 && !linked; attempt++) {
+              try { await fsp.link(tmp, dest); linked = true; }
+              catch (e) {
+                if (e.code !== 'EEXIST') throw e;
+                finalName = await freeUploadName(target.real, origName);
+                dest = joinPath(target.real, finalName);
+              }
+            }
+            if (!linked) { await cleanup(); return done(409, { error: 'exists' }); }
             await cleanup(); // link made dest a second name for the data; drop the temp name
             const st = await fsp.stat(dest);
-            done(201, { name, size: st.size, path: dest }); // absolute path: the dock pastes it into the box
+            done(201, { name: finalName, size: st.size, path: dest }); // absolute path: the dock pastes it in
           } catch { await cleanup(); done(500, { error: 'finalize failed' }); }
         });
         file.pipe(ws);
@@ -436,7 +486,7 @@ export function createApiRouter({
   r.post('/keys', async (req, res, next) => {
     const { pane, keys } = req.body || {};
     if (!isPaneId(pane)) return res.status(400).json({ error: 'bad pane id' });
-    if (!Array.isArray(keys) || keys.some((k) => !ALLOWED_KEYS.has(k))) {
+    if (!Array.isArray(keys) || keys.some((k) => !isAllowedKey(k))) {
       return res.status(400).json({ error: 'disallowed key' });
     }
     try {
@@ -456,6 +506,18 @@ export function createApiRouter({
     res.json({ asr: isAsrConfigured(asrEnv), claudeHooks: combinedHooksStatus(home) });
   });
 
+  // Update hint for the phone: is the globally-installed CLI behind the latest npm release? `current` is
+  // this server's version; `latest` comes from the same cache the CLI maintains (~/.handmux/update-check.json).
+  // We never block on the network here — if the cache is stale we kick a best-effort async refresh (throttled
+  // to once an hour, like the CLI) and return the currently-known value. The upgrade itself is a computer-side
+  // `handmux update`; the phone only shows the notice.
+  r.get('/version', (req, res) => {
+    const cache = readCache(home);
+    if (shouldRefresh(cache)) refreshLatestAsync(home);
+    const latest = cache?.latest ?? null;
+    res.json({ current: PKG_VERSION, latest, updateAvailable: !!(latest && PKG_VERSION && isNewer(latest, PKG_VERSION)) });
+  });
+
   // One-tap enable from the phone: install the hooks for every present agent (Claude Code, Codex) on the
   // host (token-gated, like every API here). Opt-in — the inbox only offers this when status is 'absent'.
   // Never creates ~/.claude or ~/.codex; a user's own Codex `notify` is left untouched (see codexHooks.js).
@@ -530,6 +592,13 @@ export function createApiRouter({
     try { res.json(await claudeEvents.getStates(allowed)); } catch (e) { next(e); }
   });
 
+  // Agent usage/quota for the Usage page. Disk-only, no credentials: Claude's 5h/weekly % from the
+  // statusLine snapshot (if the capturer is opted in), Codex's rate_limits + tokens from its newest
+  // rollout. Either side is null when unavailable. Cached briefly (see usage.js); never throws.
+  r.get('/usage', (req, res, next) => {
+    try { res.json(getUsageCached(home)); } catch (e) { next(e); }
+  });
+
   // Orphan Claude sessions: `claude` processes running on this host but NOT inside a tmux pane, so
   // handmux can't steer them. Surfaced at the bottom of the Inbox with a "takeover" (spawn
   // `claude --resume` in tmux). Best-effort process scan (see orphans.js); never throws.

package/src/uploadTypes.js

@@ -4,6 +4,8 @@
 export const DEFAULT_UPLOAD_EXTS = new Set([
   // images
   'jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'bmp', 'heic', 'heif', 'avif', 'ico', 'tiff',
+  // video
+  'mp4', 'm4v', 'mov', 'webm', 'mkv', 'avi', 'wmv', 'flv', '3gp', 'ogv', 'mpeg', 'mpg',
   // text / code
   'txt', 'md', 'markdown', 'rst', 'log', 'csv', 'tsv', 'json', 'yaml', 'yml', 'toml', 'ini',
   'conf', 'xml', 'html', 'htm', 'css', 'js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'py', 'rb', 'go',

package/src/usage.js

@@ -0,0 +1,94 @@
+// Usage/quota reader for the phone's Usage page. Purely reads what each agent already puts on disk — no
+// API calls, no credentials:
+//   • Claude — the snapshot the statusLine capturer writes to ~/.handmux/claude-usage.json. Claude Code's
+//     statusLine stdin is the ONLY documented local source of the 5h/weekly rate-limit % (see
+//     server/hooks/handmux-statusline.cjs). Absent until the user opts the capturer in → returns null.
+//   • Codex — the newest rollout's most recent `token_count` event, which carries `rate_limits` (used %,
+//     reset, window) and cumulative token usage. Always available once Codex has run, no wiring needed.
+import fs from 'node:fs';
+import path from 'node:path';
+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 codexSessionsDir(home = homedir()) { return path.join(home, '.codex', 'sessions'); }
+
+// Claude: read the statusLine snapshot. null if the capturer isn't wired / never populated it.
+export function readClaudeUsage(home = homedir()) {
+  try {
+    const snap = JSON.parse(fs.readFileSync(claudeUsagePath(home), 'utf8'));
+    return (snap && typeof snap === 'object' && !Array.isArray(snap)) ? snap : null;
+  } catch { return null; }
+}
+
+// The rollout tree is date-nested (sessions/YYYY/MM/DD/rollout-<ISO>-<uuid>.jsonl) and every path segment
+// sorts lexically = chronologically, so the newest rollout is the lexically-largest entry at each level —
+// found without walking the whole tree.
+function newestRollout(dir) {
+  const maxEntry = (d, pred) => {
+    let names;
+    try { names = fs.readdirSync(d); } catch { return null; }
+    names = names.filter((n) => !n.startsWith('.') && (!pred || pred(n))).sort();
+    return names.length ? names[names.length - 1] : null;
+  };
+  const y = maxEntry(dir); if (!y) return null;
+  const m = maxEntry(path.join(dir, y)); if (!m) return null;
+  const d = maxEntry(path.join(dir, y, m)); if (!d) return null;
+  const dayDir = path.join(dir, y, m, d);
+  const f = maxEntry(dayDir, (n) => n.startsWith('rollout-') && n.endsWith('.jsonl'));
+  return f ? path.join(dayDir, f) : null;
+}
+
+// One Codex rate-limit window → our shape, or null if absent (secondary is often null on plans without it).
+function codexWindow(w) {
+  if (!w || typeof w.used_percent !== 'number') return null;
+  return {
+    usedPercent: w.used_percent,
+    windowMinutes: typeof w.window_minutes === 'number' ? w.window_minutes : null,
+    resetsAt: typeof w.resets_at === 'number' ? w.resets_at : null,
+  };
+}
+
+// Codex: scan the newest rollout from the end for the last `token_count` event (carries the account-wide
+// rate_limits + the session's cumulative tokens). null if Codex hasn't run or the rollout has none yet.
+export function readCodexUsage(home = homedir()) {
+  const f = newestRollout(codexSessionsDir(home));
+  if (!f) return null;
+  let lines;
+  try { lines = fs.readFileSync(f, 'utf8').split('\n'); } catch { return null; }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const ln = lines[i];
+    if (!ln || ln.indexOf('token_count') === -1) continue;
+    let rec; try { rec = JSON.parse(ln); } catch { continue; }
+    const p = rec.payload;
+    if (!p || p.type !== 'token_count') continue;
+    const info = p.info || {};
+    const tu = info.total_token_usage || {};
+    const rl = p.rate_limits || {};
+    return {
+      updatedAt: Date.parse(rec.timestamp) || null,
+      rateLimits: { primary: codexWindow(rl.primary), secondary: codexWindow(rl.secondary) },
+      tokens: {
+        total: tu.total_tokens ?? null,
+        input: tu.input_tokens ?? null,
+        cachedInput: tu.cached_input_tokens ?? null,
+        output: tu.output_tokens ?? null,
+        reasoning: tu.reasoning_output_tokens ?? null,
+      },
+      contextWindow: typeof info.model_context_window === 'number' ? info.model_context_window : null,
+    };
+  }
+  return null;
+}
+
+export function getUsage(home = homedir()) {
+  return { claude: readClaudeUsage(home), codex: readCodexUsage(home) };
+}
+
+// Small TTL cache so a phone that re-polls doesn't rescan the rollout every few seconds.
+let _cache = { at: 0, home: null, data: null };
+export function getUsageCached(home = homedir(), { ttlMs = 15000, now = Date.now() } = {}) {
+  if (_cache.data && _cache.home === home && (now - _cache.at) < ttlMs) return _cache.data;
+  _cache = { at: now, home, data: getUsage(home) };
+  return _cache.data;
+}