handmux 0.17.7 → 0.18.0

package/src/routes/workspace.js

@@ -0,0 +1,267 @@
+import express from 'express';
+import { validateRecoveryMapping } from '../workspace/mapping.js';
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const RESTORE_FIELDS = new Set(['checkpointId', 'sessions']);
+const CHANGE_REASONS = new Set(['boot-changed', 'tmux-changed']);
+const OPERATION_STATUSES = new Set(['pending', 'running', 'succeeded', 'partial', 'failed', 'interrupted']);
+const RESULT_STATUSES = new Set(['restored', 'already-present', 'failed']);
+const RESULT_STAGES = new Set(['plan', 'topology', 'agent', 'restore', 'reconcile']);
+const WARNING_CODES = new Set(['cwd-fallback', 'layout-fallback', 'agent-warning', 'live-reconcile-failed', 'workspace-unavailable', 'restore-warning']);
+const ERROR_MESSAGES = {
+  'restore-interrupted': 'restore was interrupted; retry the restore',
+  'checkpoint-not-found': 'checkpoint is unavailable; choose another checkpoint',
+  'storage-full': 'workspace storage is full; free disk space and retry',
+  'permission-denied': 'workspace storage is not writable; check permissions and retry',
+  'plan-failed': 'restore plan is no longer usable; refresh and retry',
+  'agent-unavailable': 'agent resume failed; open the restored shell and retry manually',
+  'tmux-unavailable': 'tmux is unavailable; retry the restore',
+  'restore-failed': 'workspace restore failed; retry the restore',
+};
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function isSafeId(value) {
+  return typeof value === 'string' && SAFE_ID.test(value) && value !== '.' && value !== '..';
+}
+
+function isCheckpointMissing(error) {
+  if (error?.code === 'WORKSPACE_CHECKPOINT_NOT_FOUND' || error?.status === 404) return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return /(?:checkpoint.*(?:missing|not found)|no valid checkpoint)/i.test(message);
+}
+
+function sendFailure(res, error, { checkpoint = false } = {}) {
+  if (checkpoint && isCheckpointMissing(error)) {
+    return res.status(404).json({ error: 'checkpoint not found' });
+  }
+  return res.status(500).json({ error: 'workspace unavailable' });
+}
+
+function asyncHandler(handler, options) {
+  return async (req, res) => {
+    try {
+      await handler(req, res);
+    } catch (error) {
+      sendFailure(res, error, options);
+    }
+  };
+}
+
+function checkpointId(value, fallback) {
+  const id = value === undefined ? fallback : value;
+  return isSafeId(id) ? id : null;
+}
+
+function timestamp(value) {
+  return typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : null;
+}
+
+function count(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function displayName(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 256
+    && !/[\x00-\x1f\x7f]/.test(value) ? value : null;
+}
+
+function projectCheckpoint(row) {
+  const id = isSafeId(row?.id) ? row.id : null;
+  if (row?.status !== 'ok' || !row.value || typeof row.value !== 'object' || Array.isArray(row.value)) {
+    const corrupt = row?.status === 'corrupt';
+    return {
+      status: corrupt ? 'corrupt' : 'unavailable',
+      id,
+      capturedAt: null,
+      archivedAt: null,
+      sessionCount: 0,
+      windowCount: 0,
+      paneCount: 0,
+      agentCount: 0,
+      endedReason: null,
+      errorCode: corrupt ? 'checkpoint-corrupt' : 'checkpoint-unavailable',
+    };
+  }
+  const sessions = Array.isArray(row.value.sessions) ? row.value.sessions : [];
+  const windows = Array.isArray(row.value.windows) ? row.value.windows : [];
+  const panes = windows.flatMap((window) => Array.isArray(window?.panes) ? window.panes : []);
+  return {
+    status: 'ok',
+    id,
+    capturedAt: timestamp(row.value.capturedAt),
+    archivedAt: timestamp(row.value.archivedAt),
+    sessionCount: sessions.length,
+    windowCount: windows.length,
+    paneCount: panes.length,
+    agentCount: panes.filter((pane) => pane?.agent && typeof pane.agent === 'object' && !Array.isArray(pane.agent)).length,
+    endedReason: CHANGE_REASONS.has(row.value.environment?.endedReason) ? row.value.environment.endedReason : null,
+    errorCode: null,
+  };
+}
+
+function errorText(error) {
+  if (typeof error === 'string') return error.toLowerCase();
+  if (error instanceof Error) return error.message.toLowerCase();
+  return '';
+}
+
+function errorCode(error, { stage = null, status = null } = {}) {
+  const text = errorText(error);
+  if (status === 'interrupted' || /interrupt|process restart/.test(text)) return 'restore-interrupted';
+  if (/enospc|disk full|no space/.test(text)) return 'storage-full';
+  if (/eacces|eperm|permission|not writable/.test(text)) return 'permission-denied';
+  if (/checkpoint.*(?:missing|not found|unavailable)/.test(text)) return 'checkpoint-not-found';
+  if (stage === 'plan' || /restore plan|planning/.test(text)) return 'plan-failed';
+  if (stage === 'agent' || /\b(?:agent|claude|codex)\b|command not found|cli unavailable/.test(text)) return 'agent-unavailable';
+  if (stage === 'topology' || /\btmux\b|topology|server disappeared/.test(text)) return 'tmux-unavailable';
+  if (text || status === 'failed') return 'restore-failed';
+  return null;
+}
+
+function warningCode(warning) {
+  const text = errorText(warning);
+  if (/live reconcile|reconcile.*(?:fail|unavailable)/.test(text)) return 'live-reconcile-failed';
+  if (/\blayout\b/.test(text)) return 'layout-fallback';
+  if (/\b(?:agent|claude|codex)\b|command not found|cli unavailable/.test(text)) return 'agent-warning';
+  if (/\bcwd\b|\bdirectory\b|fallback.*home|missing.*path/.test(text)) return 'cwd-fallback';
+  if (/enospc|disk full|no space|eacces|eperm|permission|not writable/.test(text)) return 'workspace-unavailable';
+  return 'restore-warning';
+}
+
+function projectWarningCodes(value, existing) {
+  const codes = [];
+  if (Array.isArray(existing)) {
+    for (const code of existing) if (WARNING_CODES.has(code)) codes.push(code);
+  }
+  if (Array.isArray(value)) for (const warning of value) codes.push(warningCode(warning));
+  return [...new Set(codes)];
+}
+
+function projectMapping(value, id) {
+  if (!value || !id) return null;
+  try {
+    const mapping = validateRecoveryMapping(value, id);
+    const record = (entries) => Object.fromEntries(Object.entries(entries));
+    return {
+      id: mapping.id,
+      checkpointId: mapping.checkpointId,
+      restoredAt: mapping.restoredAt,
+      names: record(mapping.names),
+      runtime: {
+        sessions: record(mapping.runtime.sessions),
+        windows: record(mapping.runtime.windows),
+        panes: record(mapping.runtime.panes),
+      },
+      logical: {
+        sessions: record(mapping.logical.sessions),
+        windows: record(mapping.logical.windows),
+        panes: record(mapping.logical.panes),
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+function projectResult(result) {
+  const status = RESULT_STATUSES.has(result?.status) ? result.status : 'failed';
+  const stage = RESULT_STAGES.has(result?.stage) ? result.stage : null;
+  const code = errorCode(result?.error, { stage, status });
+  return {
+    logicalId: typeof result?.logicalId === 'string' && UUID.test(result.logicalId) ? result.logicalId : null,
+    sourceName: displayName(result?.sourceName),
+    targetName: displayName(result?.targetName),
+    status,
+    stage,
+    errorCode: code,
+    errorMessage: code ? ERROR_MESSAGES[code] : null,
+    warningCodes: projectWarningCodes(result?.warnings, result?.warningCodes),
+  };
+}
+
+function projectOperation(operation) {
+  const request = operation?.request && typeof operation.request === 'object' && !Array.isArray(operation.request)
+    ? operation.request : {};
+  const id = checkpointId(request.checkpointId, null);
+  const status = OPERATION_STATUSES.has(operation?.status) ? operation.status : 'failed';
+  const code = errorCode(operation?.error, { status });
+  return {
+    id: isSafeId(operation?.id) ? operation.id : null,
+    status,
+    request: {
+      checkpointId: id,
+      sessions: Array.isArray(request.sessions) ? request.sessions.map(displayName).filter(Boolean) : [],
+      historical: request.historical === true,
+    },
+    createdAt: timestamp(operation?.createdAt),
+    updatedAt: timestamp(operation?.updatedAt),
+    startedAt: timestamp(operation?.startedAt),
+    completedAt: timestamp(operation?.completedAt),
+    progress: {
+      completed: count(operation?.progress?.completed),
+      total: count(operation?.progress?.total),
+    },
+    summary: {
+      sessions: count(operation?.summary?.sessions),
+      windows: count(operation?.summary?.windows),
+      panes: count(operation?.summary?.panes),
+    },
+    results: Array.isArray(operation?.results) ? operation.results.map(projectResult) : [],
+    errorCode: code,
+    errorMessage: code ? ERROR_MESSAGES[code] : null,
+    warningCodes: projectWarningCodes(operation?.warnings, operation?.warningCodes),
+    mapping: projectMapping(operation?.mapping, id),
+  };
+}
+
+function parseRestoreRequest(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return null;
+  if (Object.keys(body).some((key) => !RESTORE_FIELDS.has(key))) return null;
+  const id = checkpointId(body.checkpointId, 'latest');
+  if (!id) return null;
+  const request = { checkpointId: id };
+  if (body.sessions !== undefined) {
+    if (!Array.isArray(body.sessions)
+      || body.sessions.some((name) => typeof name !== 'string' || !name || name.length > 256 || /[\x00-\x1f\x7f]/.test(name))) {
+      return null;
+    }
+    request.sessions = body.sessions;
+  }
+  return request;
+}
+
+export function workspaceRoutes({ workspace }) {
+  const r = express.Router();
+
+  r.get('/workspace/status', asyncHandler(async (_req, res) => {
+    res.json(await workspace.getProtectionStatus());
+  }));
+
+  r.get('/workspace/checkpoints', asyncHandler(async (_req, res) => {
+    const checkpoints = await workspace.listCheckpoints();
+    res.json(Array.isArray(checkpoints) ? checkpoints.map(projectCheckpoint) : []);
+  }));
+
+  r.get('/workspace/restore-plan', asyncHandler(async (req, res) => {
+    const id = checkpointId(req.query.checkpoint, 'latest');
+    if (!id) return res.status(400).json({ error: 'bad checkpoint id' });
+    // serverNow, promptEligible, pending recovery state, and mapping are runtime-authored. The route
+    // deliberately passes them through without interpreting expiresAt using a client-supplied clock.
+    res.json(await workspace.getRestorePlan({ checkpointId: id }));
+  }, { checkpoint: true }));
+
+  r.post('/workspace/restore', asyncHandler(async (req, res) => {
+    const restoreRequest = parseRestoreRequest(req.body);
+    if (!restoreRequest) return res.status(400).json({ error: 'bad request' });
+    res.status(202).json(await workspace.startRestore(restoreRequest));
+  }, { checkpoint: true }));
+
+  r.get('/workspace/restore/:operationId', asyncHandler(async (req, res) => {
+    if (!isSafeId(req.params.operationId)) return res.status(400).json({ error: 'bad operation id' });
+    const operation = await workspace.getOperation(req.params.operationId);
+    if (!operation) return res.status(404).json({ error: 'operation not found' });
+    res.json(projectOperation(operation));
+  }));
+
+  return r;
+}

package/src/server.js

@@ -16,6 +16,12 @@ import { applyAppName, applyManifestName } from './appName.js';
 import { homedir } from 'node:os';
 import { createPreviews } from './previews.js';
 import { createPreview } from './previewServer.js';
+import { createWorkspaceStore } from './workspace/store.js';
+import { createWorkspaceTmux } from './workspace/tmuxAdapter.js';
+import { createEnvironmentProvider } from './workspace/environment.js';
+import { createWorkspaceLock } from './workspace/lock.js';
+import { createGracefulShutdown, createWorkspaceBackground } from './workspace/checkpointer.js';
+import { createWorkspaceRuntime } from './workspace/runtime.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
@@ -27,21 +33,51 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const cfg = loadConfig();
 const token = loadToken();
 const uploadExts = loadUploadExts();
+const home = homedir();
+
+// One writer set is shared by background capture today and the restore runtime added on top of it. The
+// lock is filesystem-backed because the CLI may restore while this daemon is alive in another process.
+const workspaceStore = createWorkspaceStore({ home });
+const workspaceTmux = createWorkspaceTmux({ run: commands.runTmux });
+const workspaceLock = createWorkspaceLock({ dir: workspaceStore.paths.lockDir });
+const observeEnvironment = createEnvironmentProvider({
+  tmuxServerIdProvider: async () => {
+    const observed = await workspaceTmux.observeEnvironment();
+    if (observed.status === 'unknown') throw new Error('tmux environment unavailable');
+    return observed.tmuxServerId;
+  },
+});
+const stateFile = process.env.CLAUDE_STATE_FILE || claudeStatePath(home);
+const workspaceBackground = createWorkspaceBackground({
+  store: workspaceStore,
+  tmux: workspaceTmux,
+  observeEnvironment,
+  lock: workspaceLock,
+  stateFile,
+});
+const workspace = createWorkspaceRuntime({
+  store: workspaceStore,
+  tmux: workspaceTmux,
+  lock: workspaceLock,
+  checkpointer: workspaceBackground,
+  home,
+});
 
 // The inbox is driven by a JSON state file the Claude hooks maintain (server/hooks/handmux-notify.sh →
 // handmux-write.js). We only READ it. start() watches it so idle/permission push fires even when no
 // client is polling; getStates reads it fresh on each /states.
-const events = createClaudeEvents({ commands, push });
+const events = createClaudeEvents({ commands, push, file: stateFile, onStateChange: workspace.requestReconcile });
 events.start();
+workspace.start().catch(() => {});
 
 // 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(), {
+  syncHooks(home, {
     srcDir: path.resolve(here, '../hooks'),
-    stateFile: process.env.CLAUDE_STATE_FILE || claudeStatePath(homedir()),
+    stateFile,
   });
 } catch { /* best effort — hook sync never fails startup */ }
 
@@ -49,14 +85,14 @@ try {
 // 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.
 const previewDomain = process.env.HANDMUX_PREVIEW_DOMAIN || null;
-const previews = createPreviews({ home: homedir(), dynamicEnabled: !!previewDomain });
+const previews = createPreviews({ home, dynamicEnabled: !!previewDomain });
 const preview = createPreview({ previews, token, domain: previewDomain });
 
 const app = express();
 // Host-based dispatch FIRST: a request to <name>.<domain> is reverse-proxied to its dynamic preview;
 // every other Host falls straight through (next()) to the app below, unaffected.
 app.use(preview.dynamicProxy);
-app.use('/api', createApiRouter({ token, events, uploadExts, previews, previewDomain }));
+app.use('/api', createApiRouter({ token, events, uploadExts, previews, previewDomain, shortcuts: cfg.shortcuts, workspace }));
 app.use('/preview', preview.router);
 app.use(preview.refererFallback);
 
@@ -108,3 +144,8 @@ const server = app.listen(cfg.port, cfg.host, () => {
 });
 // WebSocket/HMR for dynamic previews: route raw Upgrade by Host to the right loopback port.
 server.on('upgrade', preview.onUpgrade);
+
+const shutdown = createGracefulShutdown({ events, workspace, server });
+const handleSignal = () => { shutdown().catch(() => {}); };
+process.on('SIGINT', handleSignal);
+process.on('SIGTERM', handleSignal);

package/src/shortcutConfig.js

@@ -0,0 +1,75 @@
+import { isAllowedKey } from './keyNames.js';
+
+const CTRL_C = Object.freeze({ type: 'key', key: 'C-c', label: 'Ctrl+C' });
+
+export const DEFAULT_SHORTCUTS = Object.freeze({
+  command: Object.freeze([CTRL_C]),
+  chat: Object.freeze([
+    CTRL_C,
+    Object.freeze({ type: 'key', key: 'Escape', label: 'Esc' }),
+    Object.freeze({ type: 'key', key: 'Tab', label: 'Tab' }),
+    Object.freeze({ type: 'key', key: 'BSpace', label: '⌫' }),
+    Object.freeze({ type: 'text', text: 'ok', enter: true }),
+    Object.freeze({ type: 'text', text: 'go on', enter: true }),
+    Object.freeze({ type: 'text', text: '1', enter: true }),
+    Object.freeze({ type: 'text', text: '2', enter: true }),
+    Object.freeze({ type: 'text', text: '3', enter: true }),
+    Object.freeze({ type: 'text', text: '/compact', enter: true }),
+    Object.freeze({ type: 'text', text: '/clear', enter: true }),
+    Object.freeze({ type: 'text', text: '/model', enter: true }),
+  ]),
+});
+
+const cloneItems = (items) => items.map((item) => ({ ...item }));
+const fail = (path, message) => { throw new Error(`${path}: ${message}`); };
+const isSingleLine = (value, max) => (
+  typeof value === 'string' && value.length > 0 && value.length <= max
+  && [...value].every((char) => {
+    const code = char.charCodeAt(0);
+    return code >= 0x20 && code !== 0x7f;
+  })
+);
+
+export function shortcutIdentity(item) {
+  return item.type === 'key' ? `key:${item.key}` : `text:${item.enter ? 1 : 0}:${item.text}`;
+}
+
+function normalizeMode(raw, mode) {
+  const path = `shortcuts.${mode}`;
+  if (!Array.isArray(raw)) fail(path, 'expected an array');
+  const seen = new Set();
+  return raw.map((item, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!item || typeof item !== 'object' || Array.isArray(item)) fail(itemPath, 'expected an object');
+    let normalized;
+    if (item.type === 'key') {
+      if (!isAllowedKey(item.key)) fail(`${itemPath}.key`, `unsupported key ${JSON.stringify(item.key)}`);
+      if (item.label !== undefined && !isSingleLine(item.label, 80)) {
+        fail(`${itemPath}.label`, 'expected non-empty single-line text');
+      }
+      if (item.enter !== undefined) fail(`${itemPath}.enter`, 'not valid for a key shortcut');
+      normalized = { type: 'key', key: item.key, label: item.label ?? item.key };
+    } else if (item.type === 'text') {
+      if (!isSingleLine(item.text, 500)) fail(`${itemPath}.text`, 'expected non-empty single-line text');
+      if (typeof item.enter !== 'boolean') fail(`${itemPath}.enter`, 'expected a boolean');
+      normalized = { type: 'text', text: item.text, enter: item.enter };
+    } else {
+      fail(`${itemPath}.type`, 'expected "key" or "text"');
+    }
+    const identity = shortcutIdentity(normalized);
+    if (seen.has(identity)) fail(itemPath, 'duplicate shortcut');
+    seen.add(identity);
+    return normalized;
+  });
+}
+
+export function normalizeShortcuts(raw) {
+  if (raw === undefined) {
+    return { command: cloneItems(DEFAULT_SHORTCUTS.command), chat: cloneItems(DEFAULT_SHORTCUTS.chat) };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail('shortcuts', 'expected an object');
+  return {
+    command: raw.command === undefined ? cloneItems(DEFAULT_SHORTCUTS.command) : normalizeMode(raw.command, 'command'),
+    chat: raw.chat === undefined ? cloneItems(DEFAULT_SHORTCUTS.chat) : normalizeMode(raw.chat, 'chat'),
+  };
+}

package/src/tmux/commands.js

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import os from 'node:os';
+import { parseTmuxRows, tmuxFormat } from './format.js';
 
 export const isPaneId = (s) => typeof s === 'string' && /^%\d+$/.test(s);
 export const isWindowId = (s) => typeof s === 'string' && /^@\d+$/.test(s);
@@ -32,8 +33,8 @@ const lines = (out) => out.split('\n').filter((l) => l.length > 0);
 
 export async function listSessions() {
   try {
-    const out = await runTmux(['list-sessions', '-F', '#{session_id}\t#{session_name}']);
-    return lines(out).map((l) => { const [id, name] = l.split('\t'); return { id, name }; });
+    const out = await runTmux(['list-sessions', '-F', tmuxFormat(['session_id', 'session_name'])]);
+    return parseTmuxRows(out, 2, 'session').map(([id, name]) => ({ id, name }));
   } catch (e) {
     // tmux exits non-zero with "no server running" or "no sessions" when nothing is up yet.
     const msg = e.message || '';
@@ -43,17 +44,17 @@ export async function listSessions() {
 }
 
 export async function listWindows(sessionId) {
-  const out = await runTmux(['list-windows', '-t', sessionId, '-F', '#{window_id}\t#{window_name}\t#{window_active}\t#{window_panes}']);
-  return lines(out).map((l) => {
-    const [id, name, active, panes] = l.split('\t');
-    return { id, name, active: active === '1', panes: Number(panes) };
+  const out = await runTmux(['list-windows', '-t', sessionId, '-F', tmuxFormat([
+    'window_id', 'window_name', 'window_active', 'window_panes', 'window_width', 'window_height',
+  ])]);
+  return parseTmuxRows(out, 6, 'window').map(([id, name, active, panes, width, height]) => {
+    return { id, name, active: active === '1', panes: Number(panes), width: Number(width), height: Number(height) };
   });
 }
 
 export async function listPanes(windowId) {
-  const out = await runTmux(['list-panes', '-t', windowId, '-F', '#{pane_id}\t#{pane_active}\t#{pane_width}\t#{pane_height}\t#{pane_current_command}\t#{pane_current_path}\t#{pane_left}\t#{pane_top}']);
-  return lines(out).map((l) => {
-    const [id, active, width, height, command, cwd, left, top] = l.split('\t');
+  const out = await runTmux(['list-panes', '-t', windowId, '-F', tmuxFormat(['pane_id', 'pane_active', 'pane_width', 'pane_height', 'pane_current_command', 'pane_current_path', 'pane_left', 'pane_top'])]);
+  return parseTmuxRows(out, 8, 'pane').map(([id, active, width, height, command, cwd, left, top]) => {
     return { id, active: active === '1', width: Number(width), height: Number(height), command, cwd, left: Number(left), top: Number(top) };
   });
 }
@@ -77,10 +78,9 @@ export async function listPaneIds(target) {
 // still EXISTS) and (b) resolve each recorded pane to its session/window for the inbox roster without a
 // 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#{pane_tty}\t#{session_name}\t#{window_id}\t#{window_name}']))
-    .map((l) => {
-      const [id, cmd, tty, session, window, windowName] = l.split('\t');
+  return parseTmuxRows(await runTmux(['list-panes', '-a', '-F',
+    tmuxFormat(['pane_id', 'pane_current_command', 'pane_tty', 'session_name', 'window_id', 'window_name'])]), 6, 'live pane')
+    .map(([id, cmd, tty, session, window, windowName]) => {
       return { id, cmd, tty, session, window, windowName };
     });
 }
@@ -110,8 +110,8 @@ export async function capturePlain(paneId) {
 // client translate a swipe into wheel events the app scrolls on (sendWheel) instead of a dead swipe.
 export async function paneInfo(paneId) {
   const out = await runTmux(['display-message', '-p', '-t', paneId,
-    '#{pane_width}\t#{pane_height}\t#{cursor_x}\t#{cursor_y}\t#{cursor_flag}\t#{alternate_on}\t#{mouse_any_flag}\t#{mouse_sgr_flag}']);
-  const [width, height, cx, cy, cflag, alt, mAny, mSgr] = out.trim().split('\t');
+    tmuxFormat(['pane_width', 'pane_height', 'cursor_x', 'cursor_y', 'cursor_flag', 'alternate_on', 'mouse_any_flag', 'mouse_sgr_flag'])]);
+  const [[width, height, cx, cy, cflag, alt, mAny, mSgr] = []] = parseTmuxRows(out, 8, 'pane info');
   return {
     width: Number(width), height: Number(height),
     cursorX: Number(cx), cursorY: Number(cy), cursorVisible: cflag === '1',
@@ -148,8 +148,8 @@ export function wheelSeq(dir, count, { sgr = true, col = 1, row = 1 } = {}) {
 // gives us only $TMUX_PANE; this turns "%263" into the session/window the phone navigates by.
 export async function paneLocation(paneId) {
   const out = await runTmux(['display-message', '-p', '-t', paneId,
-    '#{session_name}\t#{window_id}\t#{window_name}']);
-  const [session, windowId, windowName] = out.trim().split('\t');
+    tmuxFormat(['session_name', 'window_id', 'window_name'])]);
+  const [[session, windowId, windowName] = []] = parseTmuxRows(out, 3, 'pane location');
   return { session, window: windowId, windowName };
 }
 

package/src/tmux/format.js

@@ -0,0 +1,45 @@
+const Q_ESCAPED = new Set([
+  '|', '&', ';', '<', '>', '(', ')', '$', '`', '\\', '"', "'", '*', '?', '[', '#', ' ', '=', '%',
+]);
+
+export function tmuxFormat(fields) {
+  if (!Array.isArray(fields) || fields.length === 0) throw new Error('tmux format fields are required');
+  return fields.map((field) => {
+    if (typeof field !== 'string' || !/^@?[A-Za-z0-9_]+$/.test(field)) {
+      throw new Error(`invalid tmux format field: ${String(field)}`);
+    }
+    return `#{q:${field}}`;
+  }).join('|');
+}
+
+export function parseTmuxFields(line, columns, label = 'tmux') {
+  const value = String(line);
+  const fields = [];
+  let field = '';
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (char === '|') {
+      fields.push(field);
+      field = '';
+      continue;
+    }
+    if (char !== '\\') {
+      field += char;
+      continue;
+    }
+    if (i + 1 >= value.length) throw new Error(`invalid ${label} format: dangling escape`);
+    const escaped = value[++i];
+    if (!Q_ESCAPED.has(escaped)) throw new Error(`invalid ${label} format: unsupported escape`);
+    field += escaped;
+  }
+  fields.push(field);
+  if (fields.length !== columns) throw new Error(`invalid ${label} format: expected ${columns} fields`);
+  return fields;
+}
+
+export function parseTmuxRows(output, columns, label = 'tmux') {
+  const value = String(output ?? '');
+  if (value === '' || value === '\n' || value === '\r\n') return [];
+  return value.replace(/\r?\n$/, '').split(/\r?\n/)
+    .map((line) => parseTmuxFields(line, columns, label));
+}