fix(terminal): merge-time fixes for the silent-failure paths (#431)

- While another device holds the pane width (_paneWidthRefused), a resize
  now asks for the container's width without applying it locally
  (_geometryForResizeRequest: rows follow the container, columns stay at
  the PTY's). Fitting first re-wrapped the whole buffer to the container
  and back on every 30s mobile retry, and throttledResize ran the
  scrollback clear for a resize that brings no redraw. selectSession
  clears the flag, since it belongs to the previous pane. New unit tests
  run the real mixin against a fake terminal and fail without the fix.
- Session seeds _ptyCols/_ptyRows at spawn (_notePtySpawnGeometry), so a
  reattached pane reports its tmux window's real size through ptyGeometry.
- Session.resize's declined-branch comment names ptyGeometry, not the
  deleted ptyCols/ptyRows getters.
- Delete the dead terminalGeometryAgrees() and its window export.
- test/xterm-private-api.test.ts header: it pins the exact locked version,
  so any bump fails, not only a major.
- The main-terminal fit sweep also matches fitAddon?.fit?.(), and
  CLAUDE.md names the modules it actually covers.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/session.ts

@@ -1973,6 +1973,7 @@ export class Session extends EventEmitter {
           env: buildMuxAttachEnv(cliExportsTruecolor(this.mode)),
         })
       );
+      this._notePtySpawnGeometry(ptyCols, ptyRows);
     } catch (spawnErr) {
       console.error(`[Session] Failed to spawn PTY for ${options.spawnErrLabel}:`, spawnErr);
       this.emit('error', `Failed to attach to mux session: ${spawnErr}`);
@@ -2684,6 +2685,7 @@ export class Session extends EventEmitter {
             env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
           })
         );
+        this._notePtySpawnGeometry(120, 40);
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn Claude PTY:', spawnErr);
         this._status = 'stopped';
@@ -3306,6 +3308,7 @@ export class Session extends EventEmitter {
             env: buildShellEnv(this.id),
           })
         );
+        this._notePtySpawnGeometry(120, 40);
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn shell PTY:', spawnErr);
         this._status = 'stopped';
@@ -3415,6 +3418,7 @@ export class Session extends EventEmitter {
               env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
             })
           );
+          this._notePtySpawnGeometry(120, 40);
         } catch (spawnErr) {
           console.error('[Session] Failed to spawn Claude PTY for runPrompt:', spawnErr);
           this.emit(
@@ -4101,6 +4105,17 @@ export class Session extends EventEmitter {
   private _ptyCols = 120;
   private _ptyRows = 40;
 
+  /**
+   * Record the geometry a PTY was just spawned at. A reattached pane keeps the
+   * tmux window's size, not the constructor's 120x40, and without this
+   * `ptyGeometry` reported the old numbers for a live pane and the dedupe in
+   * `resize()` skipped a real resize that happened to match them.
+   */
+  private _notePtySpawnGeometry(cols: number, rows: number): void {
+    this._ptyCols = cols;
+    this._ptyRows = rows;
+  }
+
   /**
    * The geometry the CLI is actually drawing for, or null when nothing is
    * drawing.
@@ -4111,11 +4126,11 @@ export class Session extends EventEmitter {
    * than wrong-sized output, because Claude Code's repaints are computed from
    * the width it was told (issue #464). Both transports report this back.
    *
-   * ⚠️ NULL WITHOUT A PANE, never the field values. `resize()` writes
-   * `_ptyCols`/`_ptyRows` only when `ptyProcess` is set, and nothing seeds them
-   * from the spawn geometry, so a session with a dead pane — or one created
-   * through the API and never started — still holds the constructor defaults
-   * of 120x40. Reporting those made a client adopt a size no process had ever
+   * ⚠️ NULL WITHOUT A PANE, never the field values. The fields are seeded at
+   * spawn (`_notePtySpawnGeometry`) and moved by `resize()`, but a session with
+   * a dead pane (or one created through the API and never started) still
+   * holds the constructor defaults of 120x40, or the size of a pane that is
+   * gone. Reporting those made a client adopt a size no process had ever
    * been told, and on anything narrower than 120 columns it claimed another
    * device owned the pane when none existed. `reconcilePtyGeometry` treats a
    * report with no finite numbers as no evidence, which is the truth here.
@@ -4211,7 +4226,7 @@ export class Session extends EventEmitter {
       if (Date.now() - this._lastDesktopActivityAt < Session.DESKTOP_CLAIM_IDLE_MS) {
         // Declined. The caller is told nothing here on purpose — the decision
         // belongs to the session, not the socket — but the caller MUST report
-        // `ptyCols`/`ptyRows` back afterwards so the asking client can adopt
+        // `ptyGeometry` back afterwards so the asking client can adopt
         // the shape it did not get. Both transports do; see issue #464.
         return;
       }

src/web/public/app.js

@@ -6652,6 +6652,10 @@ class CodemanApp {
       // Fit terminal to container BEFORE writing any buffer data.
       // If the browser was resized while viewing another session, the terminal
       // canvas may be at stale dimensions — content would render at wrong width.
+      // A width refusal belonged to the PREVIOUS session's pane, and while it
+      // stands sendResize keeps the columns it last adopted; this pane's own
+      // report re-establishes it if another device holds this one too.
+      this._paneWidthRefused = false;
       this.syncTerminalGeometry();
 
       // Also push the new dimensions to the PTY. Without this, codex/codeman

src/web/public/constants.js

@@ -1770,11 +1770,6 @@ function clampTerminalDimensions(proposed) {
   };
 }
 
-/** Whether two geometries are the same screen. Either being absent is a mismatch. */
-function terminalGeometryAgrees(a, b) {
-  return !!a && !!b && a.cols === b.cols && a.rows === b.rows;
-}
-
 /**
  * What to do when the server reports the PTY's real geometry.
  *
@@ -1829,7 +1824,6 @@ if (typeof window !== 'undefined') {
   };
   window.CodemanTerminalGeometry = {
     clampTerminalDimensions,
-    terminalGeometryAgrees,
     reconcilePtyGeometry,
     TERMINAL_MIN_COLS,
     TERMINAL_MIN_ROWS,

src/web/public/terminal-ui.js

@@ -1093,7 +1093,8 @@ Object.assign(CodemanApp.prototype, {
         // a shape the PTY is never told about, and Claude Code computes its
         // repaints from the shape it was told. Withhold both, or neither —
         // a reflow nothing is rendering for buys nothing and costs correctness.
-        const dims = this.activeSessionId && !keyboardUp && !detachedElsewhere ? this.syncTerminalGeometry() : null;
+        const dims =
+          this.activeSessionId && !keyboardUp && !detachedElsewhere ? this._geometryForResizeRequest() : null;
         // ⚠️ A null measurement is NOT a reason to report the floor. It used to
         // fall back to a bare 40x10, which tells the PTY a shape nothing measured
         // and xterm does not hold — the write-only guess this whole change exists
@@ -1112,9 +1113,12 @@ Object.assign(CodemanApp.prototype, {
             // IMPORTANT: Only clear when we're actually sending SIGWINCH (dims changed).
             // Clearing without a subsequent Ink redraw leaves the terminal blank.
             const activeResizeSession = this.activeSessionId ? this.sessions.get(this.activeSessionId) : null;
+            // Not while another device holds the width: the columns were not
+            // reflowed here, and a refused resize brings no redraw after it.
             if (
               activeResizeSession &&
               activeResizeSession.mode !== 'shell' &&
+              !this._paneWidthRefused &&
               this.terminal &&
               this.isTerminalAtBottom()
             ) {
@@ -5615,6 +5619,33 @@ Object.assign(CodemanApp.prototype, {
     return dims;
   },
 
+  /**
+   * The geometry to ASK the server for, applied locally only as far as the PTY
+   * can follow it.
+   *
+   * Ordinarily that is all of it: `syncTerminalGeometry()`. While another
+   * device holds the width (`_paneWidthRefused`, set by `_onPtyGeometryReport`)
+   * it is not. Fitting then re-wraps xterm to the container's columns, the
+   * request is refused, the report puts the PTY's columns back, and the whole
+   * buffer re-wraps twice per ask, with the viewport pointing at a different
+   * part of the scrollback in between. The mobile retry asks every 30 seconds,
+   * so that happened on a timer for as long as the refusal lasted. So the
+   * columns stay at the PTY's (the #464 invariant: the browser never draws at
+   * a width the PTY does not have), the rows follow the container (they are
+   * never adopted, see reconcilePtyGeometry), and the container's columns go
+   * out as the request. An accepted request is adopted by the report.
+   *
+   * @returns {{cols: number, rows: number}|null} the geometry to request
+   */
+  _geometryForResizeRequest() {
+    if (!this._paneWidthRefused) return this.syncTerminalGeometry();
+    const wanted = this.getTerminalDimensions();
+    if (!wanted || !this.terminal) return null;
+    if (!this._resizeTerminalTo({ cols: this.terminal.cols, rows: wanted.rows })) return null;
+    this._scheduleOverflowAffordanceSync();
+    return wanted;
+  },
+
   /**
    * Re-measure after something changed the CELL size, and tell the server.
    *
@@ -5677,8 +5708,9 @@ Object.assign(CodemanApp.prototype, {
     // a pane it does not own is not its to refit either.
     if (!this.isSoloWindow && this.detachedSessions?.has(sessionId)) return false;
     // Fit, floor, and apply in one step so the numbers below are the numbers
-    // xterm is actually holding.
-    const dims = this.syncTerminalGeometry();
+    // xterm is actually holding (or, while another device holds the width,
+    // the numbers this container would hold if the PTY followed).
+    const dims = this._geometryForResizeRequest();
     if (!dims) return false;
     // Did the dimensions actually change since the last resize we sent? Callers
     // use this to skip work (e.g. the post-resize TUI-redraw settle) when no