agentwire-dev 1.32.0__tar.gz → 1.34.0__tar.gz

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.32.0
+Version: 1.34.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.32.0"
+__version__ = "1.34.0"

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/__main__.py

@@ -1194,6 +1194,18 @@ def _get_venv_for_backend(backend: str) -> str:
     return "qwen"
 
 
+def _get_tts_engine(args, tts_config: dict) -> str:
+    """Resolve the TTS engine to run: --backend flag, then tts.options.backend.
+
+    The top-level tts.backend is the tier (default|custom), never an engine.
+    """
+    return (
+        getattr(args, "backend", None)
+        or (tts_config.get("options") or {}).get("backend")
+        or "chatterbox"
+    )
+
+
 def _start_tts_local(args, venv_override: str | None = None, attach: bool = True) -> int:
     """Start TTS server locally in tmux.
 
@@ -1216,7 +1228,7 @@ def _start_tts_local(args, venv_override: str | None = None, attach: bool = True
     tts_config = config.get("tts", {})
     port = args.port or tts_config.get("port", 8100)
     host = args.host or tts_config.get("host", "0.0.0.0")
-    backend = getattr(args, "backend", None) or tts_config.get("backend", "chatterbox")
+    backend = _get_tts_engine(args, tts_config)
 
     # Determine venv family
     venv = venv_override or _get_venv_for_backend(backend)
@@ -1284,7 +1296,7 @@ def _start_tts_remote(ssh_target: str, machine_id: str, args) -> int:
     tts_config = config.get("tts", {})
     port = args.port or tts_config.get("port", 8100)
     host = args.host or tts_config.get("host", "0.0.0.0")
-    backend = getattr(args, "backend", None) or tts_config.get("backend", "chatterbox")
+    backend = _get_tts_engine(args, tts_config)
 
     # Build backend flag
     backend_flag = f" --backend {backend}" if backend != "chatterbox" else ""
@@ -1392,7 +1404,7 @@ def cmd_tts_serve(args) -> int:
     tts_config = config.get("tts", {})
     port = args.port or tts_config.get("port", 8100)
     host = args.host or tts_config.get("host", "0.0.0.0")
-    backend = getattr(args, "backend", None) or tts_config.get("backend", "chatterbox")
+    backend = _get_tts_engine(args, tts_config)
 
     # Determine venv family (explicit or auto-detect from backend)
     venv = getattr(args, "venv", None)
@@ -1478,8 +1490,7 @@ def cmd_tts_restart(args) -> int:
 
     # Determine backend and venv
     if not backend:
-        config = load_config()
-        backend = config.get("tts", {}).get("backend", "chatterbox")
+        backend = _get_tts_engine(args, load_config().get("tts", {}))
 
     venv = venv_override or _get_venv_for_backend(backend)
 
@@ -4154,7 +4165,7 @@ def cmd_jump(args) -> int:
 
 
 def cmd_resize(args) -> int:
-    """Resize tmux window to fit the largest attached client."""
+    """Re-fit tmux window to its attached clients per the window-size policy."""
     json_mode = getattr(args, 'json', False)
     session = getattr(args, 'session', None)
 
@@ -4165,8 +4176,11 @@ def cmd_resize(args) -> int:
             return _output_result(False, json_mode, "Not in a tmux session. Use -s to specify session.")
 
     try:
+        # Unset any window-level window-size override (e.g. manual mode left
+        # by resize-window -x/-y) so the configured policy re-fits the window.
+        # resize-window -A would resize once but leave manual mode set (#258).
         result = subprocess.run(
-            ["tmux", "resize-window", "-A", "-t", session],
+            ["tmux", "set-option", "-w", "-t", session, "-u", "window-size"],
             capture_output=True,
             text=True,
         )
@@ -4177,7 +4191,7 @@ def cmd_resize(args) -> int:
         if json_mode:
             _output_json({"success": True, "session": session})
         else:
-            print(f"Resized {session} to fit largest client")
+            print(f"Re-fit {session} to attached clients per window-size policy")
 
         return 0
 
@@ -10469,7 +10483,7 @@ def main() -> int:
     jump_parser.set_defaults(func=cmd_jump)
 
     # === resize command (top-level) ===
-    resize_parser = subparsers.add_parser("resize", help="Resize window to fit largest client")
+    resize_parser = subparsers.add_parser("resize", help="Re-fit window to attached clients per window-size policy")
     resize_parser.add_argument("-s", "--session", help="Target session (default: auto-detect)")
     resize_parser.add_argument("--json", action="store_true", help="Output as JSON")
     resize_parser.set_defaults(func=cmd_resize)

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/mcp_server.py

@@ -1266,7 +1266,10 @@ def pane_jump(session: str | None = None, pane: int = 0) -> str:
 
 @mcp.tool()
 def pane_resize(session: str | None = None) -> str:
-    """Resize tmux window to fit the largest client.
+    """Re-fit tmux window to its attached clients per the window-size policy.
+
+    Clears any manual size pin so the configured policy (largest/latest/
+    smallest) governs again.
 
     Args:
         session: Session name (defaults to current session if in tmux)
@@ -1280,7 +1283,7 @@ def pane_resize(session: str | None = None) -> str:
 
     data = run_agentwire_cmd(args)
     if data.get("success"):
-        return "Window resized to fit largest client."
+        return "Window re-fit to attached clients per window-size policy."
     return f"Failed to resize: {data.get('error', 'Unknown error')}"
 
 

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/server.py

@@ -57,6 +57,31 @@ PASTE_CHUNK_SIZE = 128  # bytes per write
 PASTE_CHUNK_DELAY = 0.01  # seconds between chunks
 
 
+async def unpin_tmux_window(session_name: str, ssh_target: str | None = None) -> None:
+    """Clear tmux manual size mode so the window-size policy governs again.
+
+    Portal builds before v1.34 pinned windows to manual mode on every
+    browser resize (#258); this heals any window still stuck there.
+    Unsetting the window-level option restores the configured policy and
+    itself triggers a re-fit. (An explicit -A resize would not: it resizes
+    once but leaves manual mode set.)
+    """
+    cmd = ["tmux", "set-option", "-w", "-t", session_name, "-u", "window-size"]
+    if ssh_target:
+        proc = await asyncio.create_subprocess_exec(
+            "ssh", ssh_target, shlex.join(cmd),
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+    else:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+    await proc.wait()
+
+
 def _is_allowed_in_restricted_mode(tool_name: str, tool_input: dict) -> bool:
     """Check if command is allowed in restricted mode.
 
@@ -1804,10 +1829,13 @@ class AgentWireServer:
                 os.close(slave_fd)
                 os.set_blocking(master_fd, False)
 
-                # Send initial window size to trigger tmux redraw
-                winsize = struct.pack("HHHH", 24, 80, 0, 0)
+                # Set initial PTY size from browser's reported dimensions
+                winsize = struct.pack("HHHH", init_rows, init_cols, 0, 0)
                 fcntl.ioctl(master_fd, termios.TIOCSWINSZ, winsize)
-                logger.info(f"[Terminal] Set initial PTY size for SSH to 80x24 (fd={master_fd})")
+                logger.info(f"[Terminal] Set initial PTY size for SSH to {init_cols}x{init_rows} (fd={master_fd})")
+
+                # Heal windows pinned to manual size mode by pre-v1.34 portals
+                await unpin_tmux_window(session_name, ssh_target)
             else:
                 # Local session - use PTY
                 cmd = ["tmux", "attach", "-t", session_name]
@@ -1842,6 +1870,9 @@ class AgentWireServer:
                 fcntl.ioctl(master_fd, termios.TIOCSWINSZ, winsize)
                 logger.info(f"[Terminal] Set initial PTY size to {init_cols}x{init_rows} (fd={master_fd})")
 
+                # Heal windows pinned to manual size mode by pre-v1.34 portals
+                await unpin_tmux_window(session_name)
+
             # Task: Forward tmux stdout → WebSocket
             async def forward_tmux_to_ws():
                 """Read from tmux and send to WebSocket."""
@@ -1963,40 +1994,22 @@ class AgentWireServer:
                                                         await asyncio.sleep(PASTE_CHUNK_DELAY)
 
                                 elif msg_type == "resize":
-                                    # Terminal resize
+                                    # Terminal resize: update the PTY and notify the
+                                    # tmux/ssh client via SIGWINCH. The window itself
+                                    # is sized by tmux per the window-size policy —
+                                    # never force it with resize-window -x/-y, which
+                                    # pins the window into manual mode (#258).
                                     cols = payload.get("cols", 80)
                                     rows = payload.get("rows", 24)
                                     logger.info(f"[Terminal] Resize {session_name} to {cols}x{rows}")
 
-                                    if master_fd is not None:
-                                        # Local: use TIOCSWINSZ ioctl to resize PTY
-                                        winsize = struct.pack("HHHH", rows, cols, 0, 0)
-                                        fcntl.ioctl(master_fd, termios.TIOCSWINSZ, winsize)
-                                        # Send SIGWINCH to notify tmux of size change
-                                        if proc and proc.pid:
-                                            try:
-                                                os.kill(proc.pid, signal.SIGWINCH)
-                                            except (OSError, ProcessLookupError):
-                                                pass  # Process may have exited
-                                        # Explicitly resize the tmux window to match the browser.
-                                        # Using -x/-y instead of -A avoids the race condition where
-                                        # tmux hasn't yet processed SIGWINCH when resize-window runs.
-                                        resize_proc = await asyncio.create_subprocess_exec(
-                                            "tmux", "resize-window", "-t", session_name,
-                                            "-x", str(cols), "-y", str(rows),
-                                            stdout=asyncio.subprocess.DEVNULL,
-                                            stderr=asyncio.subprocess.DEVNULL,
-                                        )
-                                        await resize_proc.wait()
-                                    else:
-                                        # Remote: send tmux resize-window command
-                                        resize_cmd = f"tmux resize-window -t {session_name} -x {cols} -y {rows}\n"
-                                        resize_proc = await asyncio.create_subprocess_exec(
-                                            "ssh", ssh_target, "sh", "-c", resize_cmd,
-                                            stdout=asyncio.subprocess.DEVNULL,
-                                            stderr=asyncio.subprocess.DEVNULL,
-                                        )
-                                        await resize_proc.wait()
+                                    winsize = struct.pack("HHHH", rows, cols, 0, 0)
+                                    fcntl.ioctl(master_fd, termios.TIOCSWINSZ, winsize)
+                                    if proc and proc.pid:
+                                        try:
+                                            os.kill(proc.pid, signal.SIGWINCH)
+                                        except (OSError, ProcessLookupError):
+                                            pass  # Process may have exited
 
                             except json.JSONDecodeError:
                                 logger.warning(f"[Terminal] Invalid JSON from WebSocket: {msg.data}")

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/static/announcements.json

@@ -1,5 +1,22 @@
 {
   "announcements": [
+    {
+      "id": "2026-06-window-sizing-fix",
+      "placement": "modal",
+      "emoji": "🪟",
+      "title": "Terminal sizing now respects your tmux config",
+      "date": "2026-06-09",
+      "body": "Until now, resizing the portal terminal silently forced the whole tmux window to the browser's size — pinning it into manual mode and breaking your window-size setting (largest/smallest/latest) for every connected terminal. Fixed: the portal now behaves like any other tmux client, your policy decides, and previously stuck windows heal automatically when you open them in the portal. If you liked 'the browser always wins', set window-size latest in ~/.tmux.conf. Tip: window-size smallest keeps sessions fully visible even on a phone or tablet.",
+      "highlights": [
+        "Your window-size policy works again — for every client",
+        "Stuck windows self-heal on portal attach (agentwire resize works too)",
+        "On a tablet? Try: set -g window-size smallest"
+      ],
+      "cta": {
+        "label": "How window sizing works now",
+        "url": "https://github.com/dotdevdotdev/agentwire-dev/blob/main/docs/wiki/sessions/window-sizing.md"
+      }
+    },
     {
       "id": "evergreen-feedback-2026-06",
       "placement": "banner",

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/static/css/desktop.css

@@ -770,6 +770,25 @@ body {
     border-color: var(--accent);
 }
 
+.sidebar-notif-mute {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    color: var(--text-muted);
+    font-size: 13px;
+    cursor: pointer;
+}
+
+.sidebar-notif-mute input[type="checkbox"] {
+    accent-color: var(--accent);
+    cursor: pointer;
+}
+
+.sidebar-display-hint {
+    color: var(--text-muted);
+    font-size: 12px;
+}
+
 /* Voice Indicator States */
 #sidebarVoiceIndicator {
     display: flex;

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/static/js/desktop.js

@@ -15,6 +15,7 @@ import { SessionWindow } from './session-window.js';
 import { ArtifactWindow } from './artifact-window.js';
 import { sidebar } from './sidebar.js';
 import { buildSessionId, normalizeMachine, isLocalMachine } from './session-id.js';
+import { notificationsActive } from './notification-prefs.js';
 import { configSection } from './sidebar/config-section.js';
 import { safetySection } from './sidebar/safety-section.js';
 import { artifactsSection } from './sidebar/artifacts-section.js';
@@ -315,19 +316,16 @@ function handleSessionRenamed({ old_name, new_name }) {
  * Shows desktop notification for background session activity.
  */
 function handleWindowActivity({ session }) {
-    // Only notify if session window is not focused
-    if (desktop.getActiveWindow() !== session) {
-        // Request notification permission if needed
-        if (Notification.permission === 'granted') {
-            new Notification(`Activity in ${session}`, {
-                body: 'Session has new output',
-                icon: '/static/img/icon-192.png',
-                tag: `activity-${session}`,  // Prevent duplicate notifications
-            });
-        } else if (Notification.permission !== 'denied') {
-            Notification.requestPermission();
-        }
-    }
+    // Only notify if the session window isn't the one you're looking at.
+    if (desktop.getActiveWindow() === session) return;
+    // Respects browser permission + the Config sidebar mute toggle.
+    // Enabling is done explicitly from Config → Desktop notifications, not here.
+    if (!notificationsActive()) return;
+    new Notification(`Activity in ${session}`, {
+        body: 'Session has new output',
+        icon: '/static/img/icon-192.png',
+        tag: `activity-${session}`,  // Prevent duplicate notifications
+    });
 }
 
 // Tab / Shift+Tab to cycle open windows

agentwire_dev-1.34.0/agentwire/static/js/notification-prefs.js

@@ -0,0 +1,56 @@
+/**
+ * Desktop notification preferences — frontend-only, per-browser.
+ *
+ * Two independent layers:
+ *  - Browser permission ('default' | 'granted' | 'denied') — owned by the
+ *    browser, requested via enableNotifications(). The portal can ask but
+ *    cannot grant it; that's a per-origin browser decision.
+ *  - A local "muted" toggle — lets the user silence bubbles without revoking
+ *    the OS permission. Persisted in localStorage.
+ *
+ * Changing either dispatches `notification-pref-change` on window so the
+ * Config sidebar (and anything else) can repaint.
+ */
+
+const MUTE_KEY = 'notificationsMuted';
+export const NOTIFICATION_PREF_EVENT = 'notification-pref-change';
+
+export function notificationsSupported() {
+    return typeof window !== 'undefined' && 'Notification' in window;
+}
+
+/** 'unsupported' | 'default' | 'granted' | 'denied' */
+export function getPermission() {
+    return notificationsSupported() ? Notification.permission : 'unsupported';
+}
+
+export function isMuted() {
+    return localStorage.getItem(MUTE_KEY) === '1';
+}
+
+export function setMuted(muted) {
+    if (muted) localStorage.setItem(MUTE_KEY, '1');
+    else localStorage.removeItem(MUTE_KEY);
+    window.dispatchEvent(new CustomEvent(NOTIFICATION_PREF_EVENT));
+}
+
+/** True only when a bubble should actually be shown right now. */
+export function notificationsActive() {
+    return getPermission() === 'granted' && !isMuted();
+}
+
+/**
+ * Ask the browser for permission if it hasn't been decided yet.
+ * Returns the resulting permission string. No-op (returns current state) if
+ * already granted/denied or unsupported.
+ */
+export async function enableNotifications() {
+    if (!notificationsSupported()) return 'unsupported';
+    let perm = Notification.permission;
+    if (perm === 'default') {
+        try { perm = await Notification.requestPermission(); }
+        catch { perm = Notification.permission; }
+    }
+    window.dispatchEvent(new CustomEvent(NOTIFICATION_PREF_EVENT));
+    return perm;
+}

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/agentwire/static/js/sidebar/config-section.js

@@ -4,6 +4,9 @@ import {
     setTerminalFontSize, clearTerminalFontSize,
     FONT_SIZE_MIN, FONT_SIZE_MAX, FONT_SIZE_EVENT,
 } from '../terminal-font-prefs.js';
+import {
+    getPermission, isMuted, setMuted, enableNotifications,
+} from '../notification-prefs.js';
 
 function renderDisplayPrefs() {
     const current = getTerminalFontSize();
@@ -20,6 +23,55 @@ function renderDisplayPrefs() {
     </div>`;
 }
 
+function renderNotificationPrefs() {
+    const perm = getPermission();
+    const muted = isMuted();
+
+    let status, control = '';
+    if (perm === 'unsupported') {
+        status = '<em>not supported</em>';
+    } else if (perm === 'denied') {
+        status = '<em>blocked</em>';
+        control = '<span class="sidebar-display-hint">Allow in browser site settings</span>';
+    } else if (perm === 'default') {
+        status = '<em>off</em>';
+        control = '<button class="sidebar-display-reset" data-action="enable-notifs">Enable</button>';
+    } else { // granted
+        status = muted ? 'muted' : 'on';
+        control = `<label class="sidebar-notif-mute"><input type="checkbox" data-action="mute-notifs"${muted ? ' checked' : ''}/> Mute</label>`;
+    }
+
+    return `<div class="sidebar-display-prefs" data-notif-block>
+        <div class="sidebar-display-row">
+            <label class="sidebar-config-key">Desktop notifications</label>
+            <span class="sidebar-display-value" data-notif="status">${status}</span>
+        </div>
+        ${control ? `<div class="sidebar-display-row">${control}</div>` : ''}
+    </div>`;
+}
+
+function bindNotificationPrefs(body) {
+    const repaint = () => {
+        const block = body.querySelector('[data-notif-block]');
+        if (!block) return;
+        const tmp = document.createElement('div');
+        tmp.innerHTML = renderNotificationPrefs();
+        block.replaceWith(tmp.firstElementChild);
+        wire();
+    };
+    function wire() {
+        body.querySelector('[data-action="enable-notifs"]')?.addEventListener('click', async () => {
+            await enableNotifications();
+            repaint();
+        });
+        body.querySelector('[data-action="mute-notifs"]')?.addEventListener('change', (e) => {
+            setMuted(e.target.checked);
+            repaint();
+        });
+    }
+    wire();
+}
+
 function bindDisplayPrefs(body) {
     const slider = body.querySelector('#termFontSize');
     const valueEl = body.querySelector('[data-display="size"]');
@@ -54,11 +106,13 @@ export const configSection = {
                 else if (typeof value === 'object') display = `<code>${JSON.stringify(value)}</code>`;
                 return `<div class="sidebar-config-item"><span class="sidebar-config-key">${key}</span><span class="sidebar-config-val">${display}</span></div>`;
             }).join('');
-            body.innerHTML = renderDisplayPrefs() + itemHtml;
+            body.innerHTML = renderDisplayPrefs() + renderNotificationPrefs() + itemHtml;
             bindDisplayPrefs(body);
+            bindNotificationPrefs(body);
         } catch (e) {
-            body.innerHTML = renderDisplayPrefs() + '<div class="sidebar-empty">Failed to load config</div>';
+            body.innerHTML = renderDisplayPrefs() + renderNotificationPrefs() + '<div class="sidebar-empty">Failed to load config</div>';
             bindDisplayPrefs(body);
+            bindNotificationPrefs(body);
         }
     },
 };

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/docs/wiki/INDEX.md

@@ -22,6 +22,7 @@ How AgentWire runs AI agents — session types, REPLs, and permission models.
 
 - **[claude-code-auto-mode](sessions/claude-code-auto-mode.md)** — Auto mode session type with classifier safety net
 - **[pi](sessions/pi.md)** — Pi coding agent (multi-provider: zai, deepseek, openai, openrouter, …)
+- **[Window sizing](sessions/window-sizing.md)** — how tmux `window-size` policies interact with the portal (v1.33+ behavior change, healing stuck windows, policy picker)
 - **[Custom services](services.md)** — registered long-running sessions: autostart on portal launch, watchdog health checks + restart with backoff, `agentwire services` CLI
 - **[Council](council.md)** — multi-soul orchestrator sitting: fan a prompt out to lens sessions (brain, conscience, gut, critic, …), collect via file inbox, synthesize with attribution
 

{agentwire_dev-1.32.0 → agentwire_dev-1.34.0}/docs/wiki/quickstart.md

@@ -56,7 +56,11 @@ bind -T copy-mode-vi v send -X begin-selection
 bind -T copy-mode-vi y send -X copy-selection-and-cancel
 unbind -T copy-mode-vi MouseDragEnd1Pane
 
-# Multiple clients (portal Monitor + your terminal) without window shrinking
+# Multi-client sizing — pick the policy that fits how you view sessions:
+#   largest  = big clients win; small viewers see a cropped view
+#   smallest = fit the smallest viewer (e.g. portal on a tablet) so the
+#              window is always fully visible everywhere
+#   latest   = whoever resized last wins (tmux default)
 set -g window-size largest
 ```
 

agentwire_dev-1.34.0/docs/wiki/sessions/window-sizing.md

@@ -0,0 +1,102 @@
+# Terminal Window Sizing
+
+> How tmux window sizing works with the portal — what changed in v1.33+, why,
+> and how to pick the right policy for your setup.
+
+## TL;DR
+
+The portal used to **force** every tmux window to the browser's exact size on
+every resize. As of v1.33+ ([#258](https://github.com/dotdevdotdev/agentwire-dev/issues/258),
+[PR #263](https://github.com/dotdevdotdev/agentwire-dev/pull/263)) it no longer
+does — the portal is now a polite tmux client that reports its size and lets
+**your configured `window-size` policy** decide. Previously-stuck windows heal
+automatically the next time you open them in the portal. If you ever wrote
+workaround hooks to fight stuck windows, you can delete them.
+
+## What was happening before
+
+Every time you resized the portal's terminal window, the portal ran
+`tmux resize-window -x <cols> -y <rows>` behind the scenes. In tmux, an
+explicit `-x/-y` resize flips the window into **manual size mode** — the
+window gets nailed to those exact dimensions and tmux stops looking at
+attached clients entirely. Your `window-size largest` (or `smallest`, or
+`latest`) setting was silently ignored from then on, for *every* client:
+
+- Attach a native terminal (iTerm, Alacritty, …) next to the portal and
+  resize it — nothing happens. The window stays at whatever the portal
+  last set.
+- `window-size smallest` ("fit my tablet") never worked.
+- The pin was sticky: it survived the portal disconnecting, and even
+  un-pinning by hand didn't last, because the next portal resize re-pinned it.
+
+Manual mode is implemented as a window-level `window-size manual` option that
+overrides your global/session policy. You can see it on a stuck window with:
+
+```bash
+tmux show-options -w -t <session> window-size   # "window-size manual" = stuck
+```
+
+## What happens now
+
+1. **Portal resizes are just client resizes.** The portal updates its own
+   PTY and notifies tmux (SIGWINCH) — exactly what your native terminal does
+   when you drag its corner. tmux then sizes the window per your policy.
+2. **Stuck windows self-heal.** When the portal attaches to a session, it
+   unsets any window-level `window-size` override. Windows pinned by older
+   portal versions snap back to policy-governed sizing the moment you open
+   them in the portal.
+3. **`agentwire resize` (and the `pane_resize` MCP tool) heal too.** They
+   now clear the manual pin and re-fit per policy. (The old implementation
+   used `resize-window -A`, which — counterintuitively — resizes once but
+   *leaves* manual mode set.)
+
+## Picking your `window-size` policy
+
+Set one of these in `~/.tmux.conf` (then `tmux source-file ~/.tmux.conf`):
+
+| Policy | Behavior | Pick it when |
+|---|---|---|
+| `largest` | Window sized to the **biggest** attached client; smaller viewers see a cropped view | Your desktop terminal is primary; portal/tablet viewers just peek |
+| `smallest` | Window sized to the **smallest** attached client; always fully visible everywhere | You connect from a tablet/phone and want to see the whole window |
+| `latest` (tmux default) | Whoever resized last wins | You use one viewer at a time and want it to always fit |
+
+```tmux
+set -g window-size smallest
+```
+
+Per-session override (e.g. one session should behave differently):
+
+```bash
+tmux set -w -t <session> window-size largest
+```
+
+## What you might notice after upgrading
+
+- **The portal no longer "always wins."** Under `largest` with a bigger
+  native terminal attached, resizing the browser won't reflow the window —
+  you'll see tmux's standard smaller-client view (content with padding, or
+  cropped). That's your policy working. Want the old "browser drives the
+  window" feel? Use `latest`.
+- **A window suddenly fits properly on your phone** — that's the heal
+  kicking in.
+
+## Cleanup: workaround hooks
+
+If you added hooks like these to fight stuck windows, they're obsolete —
+delete them (they're harmless, but they hard-pin a policy at the window
+level and will override your global setting):
+
+```tmux
+# DELETE these if you have them — pre-v1.33 workarounds
+set-hook -g client-attached 'set-option -t "#{session_name}" window-size largest'
+set-hook -g after-new-session 'set-option window-size largest'
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Window ignores all client resizes | Still pinned (portal not attached since upgrade) | Open it in the portal once, or run `agentwire resize -s <session>` |
+| Window smaller than my terminal | Another (smaller) client is attached under `smallest` | Detach the other client (`tmux detach-client`), or switch policy |
+| Browser resize doesn't reflow the window | Bigger client attached under `largest` | Expected — see policy table; use `latest` for last-touch-wins |
+| `show-options -w` still says `manual` | Something re-pinned it | Check `~/.tmux.conf` for old workaround hooks (above) |