botmux 2.52.0 → 2.54.0

package/dist/worker.js

@@ -32,10 +32,14 @@ import { WebSocketServer, WebSocket } from 'ws';
 import { TerminalRenderer } from './utils/terminal-renderer.js';
 import { DEFAULT_RENDER_COLS, DEFAULT_RENDER_ROWS, MAX_RENDER_COLS, MAX_RENDER_ROWS, MIN_RENDER_COLS, MIN_RENDER_ROWS, clamp, resolveRenderDimensions, } from './utils/render-dimensions.js';
 import { createCliAdapterSync } from './adapters/cli/registry.js';
-import { claudeJsonlPathForSession, resolveJsonlFromPid, findOpenClaudeSessionIds } from './adapters/cli/claude-code.js';
+import { claudeJsonlPathForSession, resolveJsonlFromPid, findOpenClaudeSessionIds, DEFAULT_CLAUDE_DATA_DIR } from './adapters/cli/claude-code.js';
 import { mtrSessionIdForBotmuxSession } from './adapters/cli/mtr.js';
 import { TmuxBackend } from './adapters/backend/tmux-backend.js';
 import { TmuxPipeBackend } from './adapters/backend/tmux-pipe-backend.js';
+import { ZellijBackend, ZELLIJ_CONFIG_KDL } from './adapters/backend/zellij-backend.js';
+import { ZellijObserveBackend } from './adapters/backend/zellij-observe-backend.js';
+import { zellijEnv } from './setup/ensure-zellij.js';
+import { isObserveBackend } from './adapters/backend/types.js';
 import { selectSessionBackend } from './adapters/backend/session-backend-selector.js';
 import { tmuxEnv } from './setup/ensure-tmux.js';
 import { IdleDetector } from './utils/idle-detector.js';
@@ -60,16 +64,35 @@ let isTmuxMode = false;
  *  web-terminal updates flow through the shared scrollback fan-out instead
  *  of per-WS attach-session PTYs. Set in spawnCli's adopt branch. */
 let isPipeMode = false;
+/** pty-under-zellij backend (BACKEND_TYPE=zellij). Behaves like the non-tmux
+ *  pty path for the worker (renderer screenshots, relay web terminal) but owns
+ *  a persistent zellij session that survives daemon restart. */
+let isZellijMode = false;
 let httpServer = null;
 let wss = null;
 const wsClients = new Set();
 const authedClients = new WeakSet();
-/** Per-WS-client tmux attach PTYs (tmux mode only). */
+/** Per-WS-client tmux/zellij attach PTYs. */
 const clientPtys = new Map();
 const writeToken = randomBytes(16).toString('hex');
+/** Lazily-written locked-mode zellij config for per-WS web-terminal attach
+ *  clients: cleared keybinds + locked mode so every keystroke passes straight
+ *  to the focused (codex) pane, never intercepted as a zellij shortcut. */
+let zellijAttachCfgPath = null;
+function ensureZellijAttachConfig() {
+    if (zellijAttachCfgPath)
+        return zellijAttachCfgPath;
+    const p = join(process.env.SESSION_DATA_DIR ?? '/tmp', '.zellij-web-attach.kdl');
+    try {
+        writeFileSync(p, ZELLIJ_CONFIG_KDL);
+    }
+    catch { /* best effort */ }
+    zellijAttachCfgPath = p;
+    return p;
+}
 let sessionId = '';
 let lastInitConfig = null;
-const CLI_DISPLAY_NAMES = { 'claude-code': 'Claude', aiden: 'Aiden', coco: 'CoCo', codex: 'Codex', 'codex-app': 'Codex App', cursor: 'Cursor', gemini: 'Gemini', opencode: 'OpenCode', antigravity: 'Antigravity', mtr: 'MTR', hermes: 'Hermes', mira: 'Mira' };
+const CLI_DISPLAY_NAMES = { 'claude-code': 'Claude', seed: 'Seed', aiden: 'Aiden', coco: 'CoCo', codex: 'Codex', 'codex-app': 'Codex App', cursor: 'Cursor', gemini: 'Gemini', opencode: 'OpenCode', antigravity: 'Antigravity', mtr: 'MTR', hermes: 'Hermes', mira: 'Mira' };
 function cliName() { return CLI_DISPLAY_NAMES[lastInitConfig?.cliId ?? ''] ?? 'CLI'; }
 let isPromptReady = false;
 /** Mutex for async flushPending — prevents concurrent flush loops. */
@@ -147,6 +170,11 @@ let bridgeJsonlDir;
  *  follow the new jsonl. */
 let bridgeCliPid;
 let bridgeCliCwd;
+/** Claude-family data root the bridge resolves JSONL / pid-state / tasks
+ *  against. `~/.claude` for Claude Code; Seed CLI's `.claude-runtime`. Set at
+ *  bridge start (from the adapter's claudeDataDir); defaults to `~/.claude` so
+ *  the adopt path and any non-seed caller behave exactly as before. */
+let bridgeDataDir = DEFAULT_CLAUDE_DATA_DIR;
 /** Last sessionId we observed via the pid resolver — used to detect
  *  rotations cheaply (string compare instead of stat()ing every jsonl). */
 let bridgeObservedCliSessionId;
@@ -425,7 +453,7 @@ function bridgeAbsorbBaseline() {
 function bridgeMarkStalePidStateForAcceptedSid(acceptedSid) {
     if (bridgeCliPid === undefined || bridgeCliCwd === undefined)
         return;
-    const pidResolved = resolveJsonlFromPid(bridgeCliPid, bridgeCliCwd);
+    const pidResolved = resolveJsonlFromPid(bridgeCliPid, bridgeCliCwd, bridgeDataDir);
     if (pidResolved && pidResolved.cliSessionId !== acceptedSid) {
         bridgeStalePidStateSessionId = pidResolved.cliSessionId;
     }
@@ -888,7 +916,7 @@ function maybeFollowQuietRotation() {
 function maybeFollowSessionRotationViaPid() {
     if (!bridgeCliPid || !bridgeCliCwd)
         return 'unavailable';
-    const resolved = resolveJsonlFromPid(bridgeCliPid, bridgeCliCwd);
+    const resolved = resolveJsonlFromPid(bridgeCliPid, bridgeCliCwd, bridgeDataDir);
     if (!resolved)
         return 'unavailable';
     if (bridgeObservedCliSessionId !== resolved.cliSessionId) {
@@ -1060,6 +1088,7 @@ function startBridgeWatcher(jsonlPath, opts) {
     bridgeJsonlDir = dirname(jsonlPath);
     bridgeCliPid = opts?.cliPid;
     bridgeCliCwd = opts?.cliCwd;
+    bridgeDataDir = opts?.dataDir ?? DEFAULT_CLAUDE_DATA_DIR;
     const mode = opts?.mode ?? 'baseline-existing';
     // Pid-state record ranks above the path the adopt scan computed. If
     // Claude was launched with `--resume` (or the adopt scan picked a
@@ -1067,7 +1096,7 @@ function startBridgeWatcher(jsonlPath, opts) {
     // and we swap to it before baseline so we don't waste a baseline on
     // a frozen file.
     if (bridgeCliPid && bridgeCliCwd) {
-        const resolved = resolveJsonlFromPid(bridgeCliPid, bridgeCliCwd);
+        const resolved = resolveJsonlFromPid(bridgeCliPid, bridgeCliCwd, bridgeDataDir);
         if (resolved) {
             bridgeObservedCliSessionId = resolved.cliSessionId;
             bridgeRememberSessionIdForPath(resolved.path);
@@ -1092,10 +1121,10 @@ function startBridgeWatcher(jsonlPath, opts) {
     // continuously for the active session, so this catches the rotation
     // even between writes). `findOpenClaudeSessionIds` unions both.
     if (bridgeCliPid !== undefined && bridgeJsonlDir && bridgeCliCwd) {
-        const sids = findOpenClaudeSessionIds(bridgeCliPid);
+        const sids = findOpenClaudeSessionIds(bridgeCliPid, bridgeDataDir);
         const candidates = [];
         for (const sid of sids) {
-            const path = claudeJsonlPathForSession(sid, bridgeCliCwd);
+            const path = claudeJsonlPathForSession(sid, bridgeCliCwd, bridgeDataDir);
             bridgeRememberSessionIdForPath(path);
             if (existsSyncSafe(path))
                 candidates.push(path);
@@ -2736,19 +2765,22 @@ function stopScreenUpdates() {
 }
 // ─── PTY Management ──────────────────────────────────────────────────────────
 function spawnCli(cfg) {
-    // ── Adopt mode: pipe-pane the user's existing tmux pane (no attach) ──
-    if (cfg.adoptMode && cfg.adoptTmuxTarget) {
+    // ── Adopt mode: observe the user's existing pane (no attach / non-invasive) ──
+    // tmux: pipe-pane (raw stream). zellij: dump-screen poll + action drive.
+    if (cfg.adoptMode && (cfg.adoptTmuxTarget || cfg.adoptZellijPaneId)) {
         // We mark BOTH isTmuxMode and isPipeMode: the former keeps idle/spawn
-        // logic on the tmux track; the latter tells the WS handler to route
+        // logic on the observe track; the latter tells the WS handler to route
         // updates through the shared scrollback fan-out (because there is no
         // PTY-per-WS — we don't attach to anything).
         isTmuxMode = true;
         isPipeMode = true;
         const cols = cfg.adoptPaneCols ?? PTY_COLS;
         const rows = cfg.adoptPaneRows ?? PTY_ROWS;
-        const pipeBe = new TmuxPipeBackend(cfg.adoptTmuxTarget);
-        backend = pipeBe;
-        pipeBe.spawn('', [], {
+        const observeBe = cfg.adoptZellijPaneId
+            ? new ZellijObserveBackend(cfg.adoptZellijSession ?? '', cfg.adoptZellijPaneId, { cliPid: cfg.adoptCliPid })
+            : new TmuxPipeBackend(cfg.adoptTmuxTarget);
+        backend = observeBe;
+        observeBe.spawn('', [], {
             cwd: cfg.workingDir,
             cols,
             rows,
@@ -2756,9 +2788,9 @@ function spawnCli(cfg) {
         });
         // Seed the shared scrollback with the pane's current screen so any
         // already-connected (or future) WS clients render meaningful content
-        // immediately, instead of waiting for the next byte tmux pipes through.
+        // immediately, instead of waiting for the next observe tick.
         try {
-            const initial = pipeBe.captureCurrentScreen();
+            const initial = observeBe.captureCurrentScreen();
             if (initial.length > 0)
                 onPtyData(initial);
         }
@@ -2932,14 +2964,19 @@ function spawnCli(cfg) {
     // the worker re-probes here. If tmux can't start a server we silently
     // fall back to PTY rather than letting attach-session / new-session spam
     // the daemon error log every poll cycle.
-    let useTmux = cfg.backendType === 'tmux';
-    if (useTmux && !TmuxBackend.isAvailable()) {
+    let effectiveBackend = cfg.backendType;
+    if (effectiveBackend === 'tmux' && !TmuxBackend.isAvailable()) {
         log('tmux backend requested but functional probe failed — falling back to PTY backend');
-        useTmux = false;
+        effectiveBackend = 'pty';
     }
-    const selectedBackend = selectSessionBackend({ sessionId: cfg.sessionId, useTmux });
+    if (effectiveBackend === 'zellij' && !ZellijBackend.isAvailable()) {
+        log('zellij backend requested but functional probe failed (need zellij >= 0.44) — falling back to PTY backend');
+        effectiveBackend = 'pty';
+    }
+    const selectedBackend = selectSessionBackend({ sessionId: cfg.sessionId, backendType: effectiveBackend });
     isTmuxMode = selectedBackend.isTmuxMode;
     isPipeMode = selectedBackend.isPipeMode;
+    isZellijMode = selectedBackend.isZellijMode;
     backend = selectedBackend.backend;
     const adapterSessionId = cfg.resume
         ? (cfg.originalSessionId ?? cfg.sessionId)
@@ -2949,9 +2986,15 @@ function spawnCli(cfg) {
     // actually committed (rather than trusting a fixed sleep), so wire it up now.
     // Codex's adapter uses ~/.codex/history.jsonl (a fixed global path) directly,
     // so it needs no per-session wiring here.
-    if (cfg.cliId === 'claude-code') {
+    //
+    // `claudeDataDir` is the Claude-family marker: set for claude-code AND its
+    // forks (Seed → `.claude-runtime`), undefined for everything else. Every
+    // JSONL/pid/bridge gate below keys off it instead of `cliId === 'claude-code'`,
+    // so a fork inherits the whole submit-confirm + bridge-fallback machinery.
+    const claudeDataDir = cliAdapter.claudeDataDir;
+    if (claudeDataDir) {
         backend.claudeJsonlPath =
-            claudeJsonlPathForSession(cfg.cliSessionId ?? adapterSessionId, cfg.workingDir);
+            claudeJsonlPathForSession(cfg.cliSessionId ?? adapterSessionId, cfg.workingDir, claudeDataDir);
     }
     const args = cliAdapter.buildArgs({
         sessionId: adapterSessionId,
@@ -2971,12 +3014,13 @@ function spawnCli(cfg) {
         args.push(...extra.split(/\s+/).filter(Boolean));
     // Claude Code 在 root/sudo 下会拒绝 --dangerously-skip-permissions 并立即 exit。
     // botmux 必须带这个 flag（话题里没法弹交互式审批），所以为 root 自动注入
-    // IS_SANDBOX=1 走 Claude Code 的受控环境逃生舱。用户显式设了就尊重不覆盖。
-    const injectClaudeSandbox = cfg.cliId === 'claude-code' &&
+    // IS_SANDBOX=1 走 Claude Code 的受控环境逃生舱。Seed 是 Claude Code fork，同样
+    // 受此限制 → 按 claude 家族判断。用户显式设了就尊重不覆盖。
+    const injectClaudeSandbox = !!claudeDataDir &&
         process.getuid?.() === 0 &&
         !process.env.IS_SANDBOX;
     if (injectClaudeSandbox) {
-        log('Detected root user — injecting IS_SANDBOX=1 for Claude Code');
+        log('Detected root user — injecting IS_SANDBOX=1 for Claude-family CLI');
     }
     // Claude Code 2.1.x：`--resume` 一个「空闲 >70min 且累计 >10 万 token」的会话会弹
     // 交互式菜单（Resume from summary / full / Don't ask again），botmux 无法导航 →
@@ -2984,7 +3028,8 @@ function spawnCli(cfg) {
     // 而 return null → 菜单不弹、按 full session 原样续（走 summary 会触发 /compact，
     // 破坏 bridge 的会话连续性追踪）。用户显式设了就尊重。注意：该 key 必须同时进
     // BOTMUX_INJECTED_ENV_KEYS 白名单，否则 tmux backend 不会把它透传进 pane。
-    const claudeResumeTokenThreshold = cfg.cliId === 'claude-code'
+    // Seed 是 Claude Code fork，同样有 resume-summary 菜单 → 按 claude 家族判断。
+    const claudeResumeTokenThreshold = claudeDataDir
         ? process.env.CLAUDE_CODE_RESUME_TOKEN_THRESHOLD ?? '2147483647'
         : undefined;
     // Predict reattach vs fresh so the log line tells the truth. When a bmx-*
@@ -2993,9 +3038,13 @@ function spawnCli(cfg) {
     // is misleading and has cost real debugging time. (CliId-mismatch reattach
     // is now blocked upstream in restoreActiveSessions / killStalePids.)
     const willReattachTmux = isTmuxMode && TmuxBackend.hasSession(TmuxBackend.sessionName(cfg.sessionId));
+    const willReattachZellij = isZellijMode && ZellijBackend.hasSession(ZellijBackend.sessionName(cfg.sessionId));
     if (willReattachTmux) {
         log(`Re-attaching to existing tmux session: ${TmuxBackend.sessionName(cfg.sessionId)} (requested CLI: ${cliAdapter.resolvedBin})`);
     }
+    else if (willReattachZellij) {
+        log(`Re-attaching to existing zellij session: ${ZellijBackend.sessionName(cfg.sessionId)} (requested CLI: ${cliAdapter.resolvedBin})`);
+    }
     else {
         log(`Spawning fresh CLI: ${cliAdapter.resolvedBin} ${args.join(' ')} (cwd: ${cfg.workingDir})`);
     }
@@ -3021,6 +3070,12 @@ function spawnCli(cfg) {
         childEnv.IS_SANDBOX = '1';
     if (claudeResumeTokenThreshold)
         childEnv.CLAUDE_CODE_RESUME_TOKEN_THRESHOLD = claudeResumeTokenThreshold;
+    // Adapter-supplied env: points Claude-family forks at their data root (Seed's
+    // CLAUDE_CONFIG_DIR → `.claude-runtime`). Keys here are also in the tmux
+    // passthrough whitelist (BOTMUX_INJECTED_ENV_KEYS) so the tmux backend forwards
+    // them past the server's global env.
+    if (cliAdapter.spawnEnv)
+        Object.assign(childEnv, cliAdapter.spawnEnv);
     backend.spawn(cliAdapter.resolvedBin, args, {
         cwd: cfg.workingDir,
         cols: PTY_COLS,
@@ -3051,10 +3106,47 @@ function spawnCli(cfg) {
     // "no rotation at all". The pinned claudeJsonlPath above is still the
     // initial guess; the resolver corrects it on first write when Claude was
     // started with `--resume`.
-    if (cfg.cliId === 'claude-code' && cliPid) {
+    if (claudeDataDir && cliPid) {
         backend.cliPid = cliPid;
         backend.cliCwd = cfg.workingDir;
     }
+    // Async pid fallback: tmux/pty resolve the CLI pid synchronously above, but
+    // zellij's CLI subprocess starts AFTER spawn() returns (the zellij server
+    // forks the pane asynchronously), so getChildPid() is null right now. Without
+    // the marker, an in-CLI `botmux send` walks ancestor pids, finds no match,
+    // and reports "无法推断 session-id". Retry briefly (non-blocking — a sync wait
+    // would lose zellij's initial render since node-pty doesn't buffer pre-listener
+    // output) until the pid appears, then write the marker + wire claude-family pid.
+    if (!cliPid) {
+        let attempts = 0;
+        const resolveCliPidLate = () => {
+            if (!backend)
+                return;
+            const pid = backend.getChildPid?.();
+            if (pid) {
+                if (process.env.SESSION_DATA_DIR && !cliPidMarker) {
+                    try {
+                        const markersDir = join(process.env.SESSION_DATA_DIR, '.botmux-cli-pids');
+                        mkdirSync(markersDir, { recursive: true });
+                        cliPidMarker = join(markersDir, String(pid));
+                        writeFileSync(cliPidMarker, cfg.sessionId);
+                        log(`CLI PID marker written (async): ${pid}`);
+                    }
+                    catch (err) {
+                        log(`Failed to write CLI PID marker (async): ${err.message}`);
+                    }
+                }
+                if (claudeDataDir) {
+                    backend.cliPid = pid;
+                    backend.cliCwd = cfg.workingDir;
+                }
+                return;
+            }
+            if (++attempts < 25)
+                setTimeout(resolveCliPidLate, 120); // ~3s budget
+        };
+        setTimeout(resolveCliPidLate, 120);
+    }
     // On tmux re-attach, keep awaitingFirstPrompt = true so screen updates are
     // suppressed until the idle detector fires markNewTurn() — this prevents the
     // full tmux scrollback history from leaking into the streaming card.
@@ -3066,13 +3158,14 @@ function spawnCli(cfg) {
     // the file Claude creates on first submit isn't absorbed as history,
     // and baseline-existing on resume so prior-run turns ARE absorbed (we
     // don't want to re-emit yesterday's conversation as fresh turns).
-    if (cfg.cliId === 'claude-code' && adapterSessionId) {
+    if (claudeDataDir && adapterSessionId) {
         const claudeBridgeSessionId = cfg.cliSessionId ?? adapterSessionId;
-        const claudeJsonl = claudeJsonlPathForSession(claudeBridgeSessionId, cfg.workingDir);
+        const claudeJsonl = claudeJsonlPathForSession(claudeBridgeSessionId, cfg.workingDir, claudeDataDir);
         startBridgeWatcher(claudeJsonl, {
             cliPid: cliPid ?? undefined,
             cliCwd: cfg.workingDir,
             mode: cfg.resume ? 'baseline-existing' : 'fresh-empty',
+            dataDir: claudeDataDir,
         });
     }
     // Structured transcript bridge fallback: if the model finishes without
@@ -3301,6 +3394,84 @@ function startWebServer(host, preferredPort) {
                     }
                 });
             }
+            else if (lastInitConfig?.adoptMode && lastInitConfig?.adoptZellijPaneId) {
+                // ── Zellij-adopt per-WS attach ──
+                // Each WS client gets its own `zellij attach` PTY sized to the browser.
+                // zellij sizes the (shared) pane to the SMALLEST attached client, so
+                // when the user's terminal is detached the web client governs the size
+                // → fully browser-responsive (申晗's insight, verified), never resizing
+                // the user's terminal beyond min(theirs, browser). Locked-mode config
+                // (cleared keybinds) makes every keystroke reach the codex pane instead
+                // of being swallowed as a zellij shortcut. Bonus: raw byte stream — none
+                // of the dump-screen snapshot / \r\n / fixed-width machinery the relay
+                // needs. (The Lark screenshot card still uses the dump-screen
+                // ObserveBackend; unaffected.) Deferred until first resize, same as tmux.
+                const zSession = lastInitConfig.adoptZellijSession ?? '';
+                const cfgPath = ensureZellijAttachConfig();
+                let cp = null;
+                const pendingInput = [];
+                const startAttach = (cols, rows) => {
+                    if (cp)
+                        return;
+                    cp = pty.spawn('zellij', ['--config', cfgPath, 'attach', zSession], {
+                        name: 'xterm-256color',
+                        cols,
+                        rows,
+                        env: zellijEnv(),
+                    });
+                    clientPtys.set(ws, cp);
+                    cp.onData((d) => {
+                        if (ws.readyState === WebSocket.OPEN)
+                            ws.send(d);
+                    });
+                    cp.onExit(() => {
+                        clientPtys.delete(ws);
+                        if (ws.readyState === WebSocket.OPEN)
+                            ws.close();
+                    });
+                    for (const data of pendingInput)
+                        cp.write(data);
+                    pendingInput.length = 0;
+                };
+                const spawnTimer = setTimeout(() => startAttach(150, 40), 500);
+                ws.on('message', (raw) => {
+                    try {
+                        const msg = JSON.parse(String(raw));
+                        if (msg.type === 'resize' && msg.cols > 0 && msg.rows > 0) {
+                            if (!cp) {
+                                clearTimeout(spawnTimer);
+                                startAttach(msg.cols, msg.rows);
+                            }
+                            else
+                                cp.resize(msg.cols, msg.rows);
+                        }
+                        else if (msg.type === 'input' && typeof msg.data === 'string') {
+                            if (!authedClients.has(ws)) {
+                                // Read-only: only let mouse events (scroll/select) through.
+                                if (!/^\x1b\[([<M])/.test(msg.data))
+                                    return;
+                            }
+                            if (cp)
+                                cp.write(msg.data);
+                            else
+                                pendingInput.push(msg.data);
+                        }
+                    }
+                    catch { /* ignore non-JSON or bad messages */ }
+                });
+                ws.on('close', () => {
+                    clearTimeout(spawnTimer);
+                    wsClients.delete(ws);
+                    const existing = clientPtys.get(ws);
+                    if (existing) {
+                        try {
+                            existing.kill();
+                        }
+                        catch { /* already dead */ }
+                        clientPtys.delete(ws);
+                    }
+                });
+            }
             else {
                 // ── Shared relay (PtyBackend OR tmux pipe mode) ──
                 // History seed: prefer tmux's authoritative capture-pane in pipe mode
@@ -3308,8 +3479,20 @@ function startWebServer(host, preferredPort) {
                 // stream, which scrolls stale Ink redraw/spinner frames into scrollback
                 // at any size mismatch and produces the stacked-footer history garble.
                 // See chooseWebTerminalSeed for the full rationale.
+                // Adopt observes a pane we CANNOT resize (tmux adopt has
+                // ownsSession=false so resize() is a no-op; zellij drives via
+                // dump-screen). The client's FitAddon sizes its xterm to the browser,
+                // but the snapshot lines carry the PANE's width — any mismatch wraps the
+                // full-width TUI box lines and garbles the layout (the misalignment 申晗
+                // saw). Pin the client xterm to the pane's fixed size via a botmux OSC
+                // (sent BEFORE the seed so the client resizes before rendering it).
+                if (lastInitConfig?.adoptMode && isObserveBackend(backend)) {
+                    const sz = backend.getPaneSize();
+                    if (sz && sz.cols > 0 && sz.rows > 0)
+                        ws.send(`\x1b]1989;${sz.cols};${sz.rows}\x07`);
+                }
                 const seed = chooseWebTerminalSeed({
-                    canCapture: isPipeMode && backend instanceof TmuxPipeBackend,
+                    canCapture: isPipeMode && isObserveBackend(backend),
                     capture: () => backend.captureCurrentScreen(),
                     scrollback,
                     onError: log,
@@ -3502,8 +3685,24 @@ term.onData(function(d){
   }
   if(ws_&&ws_.readyState===1)ws_.send(JSON.stringify({type:'input',data:d}));
 });
-function sendResize(){if(ws_&&ws_.readyState===1)ws_.send(JSON.stringify({type:'resize',cols:term.cols,rows:term.rows}))}
-window.addEventListener('resize',function(){fit.fit();sendResize()});
+var fixedSize=false,_lastC=0,_lastR=0,_rzT=0;
+function sendResize(){
+  if(!ws_||ws_.readyState!==1)return;
+  // Dedup: a fit that lands on the same grid must NOT re-emit a resize — for a
+  // zellij/tmux attach client that would reflow the shared pane for nothing.
+  if(term.cols===_lastC&&term.rows===_lastR)return;
+  _lastC=term.cols;_lastR=term.rows;
+  ws_.send(JSON.stringify({type:'resize',cols:term.cols,rows:term.rows}));
+}
+// Debounce viewport resize: mobile fires a burst of window.resize as the address
+// bar / on-screen keyboard show & hide, and an un-debounced fit→resize on each
+// reflows the (shared) zellij pane every frame — the status bar toggles and the
+// text re-wraps, i.e. the flicker 申晗 saw. Coalesce to the settled size.
+function onViewportResize(){
+  clearTimeout(_rzT);
+  _rzT=setTimeout(function(){if(!fixedSize){try{fit.fit()}catch(e){}}sendResize()},250);
+}
+window.addEventListener('resize',onViewportResize);
 (function connect(){
   var t=new URLSearchParams(location.search).get('token')||'';
   // Derive base from the current path so the WS connects to the same prefix the
@@ -3516,6 +3715,10 @@ window.addEventListener('resize',function(){fit.fit();sendResize()});
   ws.onopen=function(){el.textContent='connected';el.className='ok';sendResize()};
   ws.onmessage=function(e){
     var data=typeof e.data==='string'?e.data:new TextDecoder().decode(e.data);
+    // botmux OSC 1989: pin the xterm to the adopted pane's fixed size (the pane
+    // can't be resized, so FitAddon-to-browser would wrap the snapshot lines).
+    var _fs=data.match(/\\x1b\\]1989;(\\d+);(\\d+)\\x07/);
+    if(_fs){fixedSize=true;var _c=+_fs[1],_r=+_fs[2];if(_c>0&&_r>0){try{term.resize(_c,_r)}catch(ex){}}data=data.replace(_fs[0],'')}
     // Intercept OSC 52 clipboard sequence from tmux (set-clipboard on)
     var m=data.match(/\\x1b\\]52;[^;]*;([A-Za-z0-9+/=]+)(?:\\x07|\\x1b\\\\)/);
     if(m){try{_clipBuf=new TextDecoder().decode(Uint8Array.from(atob(m[1]),function(c){return c.charCodeAt(0)}));_doCopy(_clipBuf);_showCopied()}catch(ex){}}