tmux-ide 2.9.15 → 2.9.17

package/packages/daemon/dist/lib/session-favicon.js

@@ -0,0 +1,152 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { extname, isAbsolute, join } from "node:path";
+import { TMUX_SERVER_SESSION_FAVICON_MAX_BYTES, } from "@tmux-ide/contracts";
+/** Project-relative favicon locations, first match wins. */
+export const SESSION_FAVICON_CANDIDATES = [
+    "favicon.svg",
+    "favicon.png",
+    "favicon.ico",
+    "public/favicon.svg",
+    "public/favicon.png",
+    "public/favicon.ico",
+    "app/icon.svg",
+    "app/icon.png",
+    "app/favicon.ico",
+    "src/app/icon.svg",
+    "src/app/icon.png",
+    "src/app/favicon.ico",
+    "static/favicon.svg",
+    "static/favicon.png",
+    "static/favicon.ico",
+    "assets/favicon.svg",
+    "assets/favicon.png",
+    "assets/favicon.ico",
+    "apple-touch-icon.png",
+    "public/apple-touch-icon.png",
+    "icon.svg",
+    "icon.png",
+];
+const MIME_BY_EXTENSION = {
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+};
+export const defaultSessionFaviconIo = {
+    lstat: (path) => lstat(path),
+    readNoFollow: async (path, maxBytes) => {
+        let handle;
+        try {
+            handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        }
+        catch {
+            return null;
+        }
+        try {
+            const stats = await handle.stat();
+            if (!stats.isFile() || stats.size > maxBytes)
+                return null;
+            const bytes = await handle.readFile();
+            return bytes.byteLength > maxBytes ? null : bytes;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    },
+};
+async function lstatOrNull(io, path) {
+    try {
+        return await io.lstat(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Finds a session's project favicon from its working directory. Only regular
+ * files and real directories inside the session path are considered; symlinks
+ * are never followed. Hits are revalidated by mtime and size, misses are
+ * remembered briefly, and the cache is bounded (least recently used first).
+ */
+export function createSessionFaviconResolver(options = {}) {
+    const io = options.io ?? defaultSessionFaviconIo;
+    const now = options.now ?? Date.now;
+    const missTtlMs = options.missTtlMs ?? 30_000;
+    const maxEntries = options.maxEntries ?? 256;
+    const cache = new Map();
+    const remember = (sessionPath, entry) => {
+        cache.delete(sessionPath);
+        cache.set(sessionPath, entry);
+        while (cache.size > maxEntries)
+            cache.delete(cache.keys().next().value);
+    };
+    const scan = async (sessionPath) => {
+        const directories = new Map();
+        for (const candidate of SESSION_FAVICON_CANDIDATES) {
+            const mime = MIME_BY_EXTENSION[extname(candidate)];
+            if (!mime)
+                continue;
+            const slash = candidate.lastIndexOf("/");
+            if (slash >= 0) {
+                const parts = candidate.slice(0, slash).split("/");
+                let real = true;
+                for (let index = 1; index <= parts.length && real; index += 1) {
+                    const directory = parts.slice(0, index).join("/");
+                    let known = directories.get(directory);
+                    if (known === undefined) {
+                        const stats = await lstatOrNull(io, join(sessionPath, directory));
+                        known = stats !== null && stats.isDirectory() && !stats.isSymbolicLink();
+                        directories.set(directory, known);
+                    }
+                    real = known;
+                }
+                if (!real)
+                    continue;
+            }
+            const file = join(sessionPath, candidate);
+            const stats = await lstatOrNull(io, file);
+            if (!stats || !stats.isFile() || stats.size > TMUX_SERVER_SESSION_FAVICON_MAX_BYTES)
+                continue;
+            const bytes = await io.readNoFollow(file, TMUX_SERVER_SESSION_FAVICON_MAX_BYTES);
+            if (!bytes)
+                continue;
+            return {
+                kind: "hit",
+                file,
+                mtimeMs: stats.mtimeMs,
+                size: stats.size,
+                favicon: { mime, data: bytes.toString("base64"), size: bytes.byteLength },
+            };
+        }
+        return { kind: "miss", at: now() };
+    };
+    return async (sessionPath) => {
+        if (!sessionPath || !isAbsolute(sessionPath) || sessionPath.includes("\0"))
+            return null;
+        const cached = cache.get(sessionPath);
+        if (cached?.kind === "miss" && now() - cached.at < missTtlMs) {
+            remember(sessionPath, cached);
+            return null;
+        }
+        if (cached?.kind === "hit") {
+            const stats = await lstatOrNull(io, cached.file);
+            if (stats &&
+                stats.isFile() &&
+                stats.mtimeMs === cached.mtimeMs &&
+                stats.size === cached.size) {
+                remember(sessionPath, cached);
+                return cached.favicon;
+            }
+        }
+        const entry = await scan(sessionPath);
+        remember(sessionPath, entry);
+        return entry.kind === "hit" ? entry.favicon : null;
+    };
+}

package/packages/daemon/dist/lib/skill-sync.js

@@ -13,8 +13,8 @@ import { resolveRuntimeNamespace } from "./runtime-namespace.js";
  *
  * The dir is FULLY MANAGED: overwriting our own `~/.claude/skills/tmux-ide` is
  * correct, and this NEVER touches anything outside it (user-authored skills in
- * sibling dirs are safe). The version marker is line 2 of SKILL.md, an HTML
- * comment ({@link VERSION_MARKER_RE}); {@link parseSkillVersion} reads it and
+ * sibling dirs are safe). The version marker is an HTML comment under
+ * SKILL.md's frontmatter ({@link VERSION_MARKER_RE}); {@link parseSkillVersion} reads it and
  * {@link rewriteVersionMarker} substitutes it at copy time.
  *
  * The parse/render helpers are PURE and tested against fixtures; {@link syncSkill}
@@ -66,7 +66,7 @@ export function defaultSkillSource() {
 // Pure — version marker
 // ---------------------------------------------------------------------------
 /**
- * The version marker line (an HTML comment on line 2 of SKILL.md). The sync
+ * The version marker line (an HTML comment under SKILL.md's frontmatter). The sync
  * machinery reads it to know which version an installed copy is, and rewrites it
  * to the installed package version at copy time.
  */

package/packages/daemon/dist/lib/tmux-server-owner.js

@@ -69,7 +69,8 @@ export function createNativeTmuxServerCatalog(workspaceRegistry, run, assertOpen
                 "list-panes",
                 "-a",
                 "-F",
-                "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}\t#{pane_id}\t#{session_path}",
+                // session_path stays last: tmux rejects tabs in session names but not in paths.
+                "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}\t#{pane_id}\t#{window_id}\t#{session_activity}\t#{session_path}",
             ]
                 .map(shellEscape)
                 .join(" "),
@@ -80,7 +81,8 @@ export function createNativeTmuxServerCatalog(workspaceRegistry, run, assertOpen
         // Command errors, unsupported formats and unwitnessed blank output stay failures.
         const lines = raw.trim() === "tmux-ide-empty-catalog-v1" ? [] : raw.trim().split("\n");
         for (const line of lines) {
-            const [pid, id, created, name, pane, dir] = line.split("\t");
+            const [pid, id, created, name, pane, window, activity, ...pathParts] = line.split("\t");
+            const dir = pathParts.join("\t");
             if (!pid ||
                 !/^\d+$/.test(pid) ||
                 !id ||
@@ -90,6 +92,8 @@ export function createNativeTmuxServerCatalog(workspaceRegistry, run, assertOpen
                 !name ||
                 !pane ||
                 !/^%\d+$/.test(pane) ||
+                !window ||
+                !/^@\d+$/.test(window) ||
                 !dir)
                 throw new Error("Invalid native server catalog");
             if (!isVisibleFleetSession(name))
@@ -98,9 +102,12 @@ export function createNativeTmuxServerCatalog(workspaceRegistry, run, assertOpen
             const row = rows.get(liveSessionId) ?? {
                 summary: { liveSessionId, sessionName: name, paneCount: 0 },
                 panes: new Set(),
+                windows: new Set(),
                 dir,
+                activity: activity && /^\d+$/.test(activity) ? Number(activity) : null,
             };
             row.panes.add(pane);
+            row.windows.add(window);
             rows.set(liveSessionId, row);
         }
         const names = new Set([...rows.values()].map(({ summary }) => summary.sessionName));
@@ -115,7 +122,13 @@ export function createNativeTmuxServerCatalog(workspaceRegistry, run, assertOpen
                     projectDir: dir,
                     persistence: "volatile",
                 });
-        return [...rows.values()].map(({ summary, panes }) => ({ ...summary, paneCount: panes.size }));
+        return [...rows.values()].map(({ summary, panes, windows, dir, activity }) => ({
+            ...summary,
+            paneCount: panes.size,
+            windowCount: windows.size,
+            lastActivity: activity,
+            sessionPath: dir,
+        }));
     };
 }
 /** One proven server incarnation. Never elects an endpoint or changes ambient tmux authority. */

package/packages/daemon/dist/lib/tmux-server-owners.js

@@ -24,6 +24,8 @@ export class TmuxServerOwners {
     constructor(options) {
         this.options = options;
     }
+    #queuedRefresh = null;
+    #queuedRefreshTail = null;
     #serial(work) {
         const run = this.#tail.then(() => {
             if (this.#disposed)
@@ -134,12 +136,29 @@ export class TmuxServerOwners {
         this.#entries.set(scope.serverId, { registration, scope, observation, owner });
     }
     refresh() {
-        return this.#serial(async () => {
+        // A refresh still waiting its turn has not probed anything yet, so it is
+        // as fresh for a later caller as a new one: share it instead of queuing
+        // another full refresh behind it (#709). Once it starts, callers queue anew.
+        // Share it only while nothing has been queued behind it, so a refresh
+        // stays ordered after any mutation queued before the caller asked.
+        if (this.#queuedRefresh && this.#tail === this.#queuedRefreshTail)
+            return this.#queuedRefresh;
+        const queued = this.#serial(async () => {
+            if (this.#queuedRefresh === queued)
+                this.#queuedRefresh = null;
             // Sequential admission bounds subprocess work and avoids alias races.
             for (const entry of this.#entries.values())
                 await this.#refresh(entry);
             return this.list();
         });
+        this.#queuedRefresh = queued;
+        this.#queuedRefreshTail = this.#tail;
+        const settle = () => {
+            if (this.#queuedRefresh === queued)
+                this.#queuedRefresh = null;
+        };
+        queued.then(settle, settle);
+        return queued;
     }
     current(scopeInput) {
         const scope = TmuxServerScopeSchemaZ.parse(scopeInput);

package/packages/daemon/dist/lib/tui-binary.js

@@ -26,8 +26,18 @@ export const MIN_TUI_BINARY_BYTES = 10 * 1024 * 1024;
 /** Hard download/decompression ceilings: release binaries are currently ~70MB. */
 export const MAX_TUI_COMPRESSED_BYTES = 128 * 1024 * 1024;
 export const MAX_TUI_BINARY_BYTES = 256 * 1024 * 1024;
-export const TUI_DOWNLOAD_TIMEOUT_MS = 30_000;
+/** Abort a request when no bytes arrive for this long; a slow transfer never trips it. */
+export const TUI_DOWNLOAD_STALL_TIMEOUT_MS = 30_000;
+/** One budget for the manifest, the binary, and every retry: ~145 KB/s at the size ceiling. */
+export const TUI_DOWNLOAD_TOTAL_TIMEOUT_MS = 15 * 60_000;
+/** Attempts per file; only transient failures are retried. */
+export const TUI_DOWNLOAD_MAX_ATTEMPTS = 3;
+export const TUI_DOWNLOAD_RETRY_DELAY_MS = 1_000;
 const MAX_CHECKSUM_MANIFEST_BYTES = 4 * 1024;
+/** A second installer says why it is quiet once the wait is longer than a lock handover. */
+const TUI_DOWNLOAD_LOCK_NOTICE_MS = 2_000;
+/** Lets a lock waiter outlast the holder's verify and install after its download budget. */
+const TUI_DOWNLOAD_LOCK_MARGIN_MS = 5_000;
 const SUPPORTED = {
     "darwin-arm64": "darwin-arm64",
     "linux-x64": "linux-x64",
@@ -109,6 +119,9 @@ export function findDownloadedTui(version = getCurrentVersion(), options = {}) {
         purgeCachedBinary(path);
     return null;
 }
+/** A failure a retry cannot fix: the release asset is missing or breaks a hard limit. */
+class PermanentDownloadError extends Error {
+}
 function checksumPath(path) {
     return `${path}.sha256`;
 }
@@ -198,32 +211,53 @@ function purgeCachedBinary(path) {
         }
     }
 }
-async function readBoundedResponse(fetchImpl, url, maxBytes, timeoutMs) {
+function isTransientHttpStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+async function readBoundedResponse(fetchImpl, url, maxBytes, policy) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let total = 0;
+    let timeoutMessage = null;
+    const abortWith = (message) => () => {
+        timeoutMessage = message();
+        controller.abort();
+    };
+    const overallTimer = setTimeout(abortWith(() => `download did not finish within ${policy.totalTimeoutMs}ms`), Math.max(0, policy.deadline - Date.now()));
+    const onStall = abortWith(() => `download stalled: no data for ${policy.stallTimeoutMs}ms after ${total} bytes`);
+    let stallTimer = setTimeout(onStall, policy.stallTimeoutMs);
+    const markProgress = () => {
+        clearTimeout(stallTimer);
+        stallTimer = setTimeout(onStall, policy.stallTimeoutMs);
+    };
     try {
         const response = await fetchImpl(url, { signal: controller.signal });
         if (!response.ok) {
-            throw new Error(`HTTP ${response.status} ${response.statusText}`);
+            const message = `HTTP ${response.status} ${response.statusText}`;
+            if (isTransientHttpStatus(response.status))
+                throw new Error(message);
+            throw new PermanentDownloadError(message);
         }
+        markProgress();
         const declaredLength = Number(response.headers.get("content-length"));
         if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
-            throw new Error(`declared size ${declaredLength} exceeds ${maxBytes} bytes`);
+            throw new PermanentDownloadError(`declared size ${declaredLength} exceeds ${maxBytes} bytes`);
         }
         if (!response.body)
             throw new Error("response has no body");
         const chunks = [];
-        let total = 0;
         const reader = response.body.getReader();
         try {
             while (true) {
                 const { done, value } = await reader.read();
                 if (done)
                     break;
+                if (value.byteLength === 0)
+                    continue;
+                markProgress();
                 total += value.byteLength;
                 if (total > maxBytes) {
                     await reader.cancel();
-                    throw new Error(`download exceeds ${maxBytes} bytes`);
+                    throw new PermanentDownloadError(`download exceeds ${maxBytes} bytes`);
                 }
                 chunks.push(Buffer.from(value));
             }
@@ -234,13 +268,33 @@ async function readBoundedResponse(fetchImpl, url, maxBytes, timeoutMs) {
         return Buffer.concat(chunks, total);
     }
     catch (error) {
-        if (controller.signal.aborted) {
-            throw new Error(`download timed out after ${timeoutMs}ms`, { cause: error });
-        }
+        if (timeoutMessage)
+            throw new Error(timeoutMessage, { cause: error });
         throw error;
     }
     finally {
-        clearTimeout(timer);
+        clearTimeout(overallTimer);
+        clearTimeout(stallTimer);
+        // Releases the connection of any response whose body was not fully read.
+        controller.abort();
+    }
+}
+async function readWithRetries(fetchImpl, url, maxBytes, policy, log) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await readBoundedResponse(fetchImpl, url, maxBytes, policy);
+        }
+        catch (error) {
+            const delayMs = policy.retryDelayMs * attempt;
+            if (error instanceof PermanentDownloadError ||
+                attempt >= policy.maxAttempts ||
+                Date.now() + delayMs >= policy.deadline) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            log(`download attempt ${attempt}/${policy.maxAttempts} failed (${message}); retrying`);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
     }
 }
 /**
@@ -270,10 +324,11 @@ export async function downloadTuiBinary(opts = {}) {
         minBinaryBytes: opts.limits?.minBinaryBytes ?? MIN_TUI_BINARY_BYTES,
         maxCompressedBytes: opts.limits?.maxCompressedBytes ?? MAX_TUI_COMPRESSED_BYTES,
         maxBinaryBytes: opts.limits?.maxBinaryBytes ?? MAX_TUI_BINARY_BYTES,
-        timeoutMs: opts.timeoutMs ?? TUI_DOWNLOAD_TIMEOUT_MS,
     };
+    const totalTimeoutMs = opts.totalTimeoutMs ?? TUI_DOWNLOAD_TOTAL_TIMEOUT_MS;
     mkdirSync(dirname(dest), { recursive: true });
-    const releaseLock = await acquirePrivateOperationLock(downloadLockPath(dest), limits.timeoutMs * 2 + 5_000);
+    const lockNotice = setTimeout(() => log("waiting for another tmux-ide download of this version to finish"), TUI_DOWNLOAD_LOCK_NOTICE_MS);
+    const releaseLock = await acquirePrivateOperationLock(downloadLockPath(dest), totalTimeoutMs + TUI_DOWNLOAD_LOCK_MARGIN_MS).finally(() => clearTimeout(lockNotice));
     const suffix = `${process.pid}.${randomUUID()}.tmp`;
     const binaryTmp = `${dest}.${suffix}`;
     const checksumTmp = `${checksumPath(dest)}.${suffix}`;
@@ -283,17 +338,28 @@ export async function downloadTuiBinary(opts = {}) {
             return { path: dest, bytes: cached.bytes };
         purgeCachedBinary(dest);
         const fetchImpl = opts.fetch ?? globalThis.fetch;
+        // Starts after the lock so the budget matches what a lock waiter allows for.
+        const policy = {
+            stallTimeoutMs: opts.stallTimeoutMs ?? TUI_DOWNLOAD_STALL_TIMEOUT_MS,
+            deadline: Date.now() + totalTimeoutMs,
+            totalTimeoutMs,
+            maxAttempts: opts.maxAttempts ?? TUI_DOWNLOAD_MAX_ATTEMPTS,
+            retryDelayMs: opts.retryDelayMs ?? TUI_DOWNLOAD_RETRY_DELAY_MS,
+        };
         log(`downloading checksum manifest ${checksumUrl}`);
         let manifestBytes;
         let gz;
         try {
-            manifestBytes = await readBoundedResponse(fetchImpl, checksumUrl, MAX_CHECKSUM_MANIFEST_BYTES, limits.timeoutMs);
-            gz = await readBoundedResponse(fetchImpl, url, limits.maxCompressedBytes, limits.timeoutMs);
+            manifestBytes = await readWithRetries(fetchImpl, checksumUrl, MAX_CHECKSUM_MANIFEST_BYTES, policy, log);
+            log(`downloading ${url}`);
+            gz = await readWithRetries(fetchImpl, url, limits.maxCompressedBytes, policy, log);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`could not download the TUI binary and checksum for v${version} (${message}). ` +
-                `Check that the release published both exact-version assets.`, { cause: error });
+            const hint = error instanceof PermanentDownloadError
+                ? "Check that the release published both exact-version assets."
+                : "Check your network connection, then retry with `tmux-ide update --tui-binary`, or run the installer again if tmux-ide is not installed yet.";
+            throw new Error(`could not download the TUI binary and checksum for v${version} (${message}). ${hint}`, { cause: error });
         }
         const manifest = parseChecksumManifest(manifestBytes, { version, tag });
         if (sha256(gz) !== manifest.compressedSha256) {

package/packages/daemon/dist/native/TmuxIdeNotifier.app/Contents/Info.plist

@@ -21,9 +21,9 @@
   <key>CFBundlePackageType</key>
   <string>APPL</string>
   <key>CFBundleShortVersionString</key>
-  <string>2.9.15</string>
+  <string>2.9.17</string>
   <key>CFBundleVersion</key>
-  <string>2.9.15</string>
+  <string>2.9.17</string>
   <key>LSMinimumSystemVersion</key>
   <string>11.0</string>
   <key>LSUIElement</key>

package/packages/daemon/dist/native/TmuxIdeNotifier.app/Contents/_CodeSignature/CodeResources

@@ -6,11 +6,11 @@
 	<dict>
 		<key>Resources/AppIcon.icns</key>
 		<data>
-		0kJOhKI63m7RQF/lR1nMjIIiACY=
+		/fan3KhjkAUR40oxTxGrk4b03wY=
 		</data>
 		<key>Resources/Assets.car</key>
 		<data>
-		g6ppKlYeW830G3DwzRm9o0xINW8=
+		YZSYPnzkfPLVemp3jiRDnR5WhhQ=
 		</data>
 	</dict>
 	<key>files2</key>
@@ -19,14 +19,14 @@
 		<dict>
 			<key>hash2</key>
 			<data>
-			YXdi2fa2PvtRaeXueLC7n1If41ofraB5MVZULmdCcC8=
+			zDoKzf7n2cp6cQedgfmNiTPwTj+gON7DS7H8ihtNVCE=
 			</data>
 		</dict>
 		<key>Resources/Assets.car</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			lo9t3TSww0mSpC4nN+YoeeUgaXGcFCrv53qBXtKpzEY=
+			zV9+zCqfvUhHrz90MuHUjqBvx93oA7g6BxgO8hDUlN8=
 			</data>
 		</dict>
 	</dict>

package/packages/daemon/dist/open-browser.js

@@ -76,6 +76,42 @@ export function validateBrowserOpen(url, options) {
             exitCode: 2,
         });
 }
+/** Printed when the opened browser never publishes tmux-ide's native controls. */
+export const NO_NATIVE_CONTROLS_NOTICE = "This browser has no tmux-ide controls; install the native app for back/forward/reload.";
+/** A browser bundled in a native app publishes its controls; a standalone one may not. */
+function isBundledBrowser(executable) {
+    return /\/[^/]+\.app\/Contents\/Resources\/browser\//u.test(executable);
+}
+/** How long a standalone browser has to publish its controls. */
+const STANDALONE_WAIT_MS = 2000;
+/**
+ * Watches the new pane for @tmux_ide_browser_control, which only a browser with
+ * native controls sets. A browser bundled in an app is never reported: if it is
+ * slow, its controls appear when it is ready. A standalone browser gets 2 s of
+ * wall-clock time, however slow tmux answers, and then the notice. Returns
+ * null once the option appears or when the pane is already gone.
+ */
+export async function nativeControlsNotice(run, pane, executable, wait = {}) {
+    if (isBundledBrowser(executable))
+        return null;
+    const sleep = wait.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = wait.now ?? Date.now;
+    const deadline = now() + STANDALONE_WAIT_MS;
+    for (;;) {
+        let control;
+        try {
+            control = run(["display-message", "-p", "-t", pane, "#{@tmux_ide_browser_control}"]).trim();
+        }
+        catch {
+            return null;
+        }
+        if (control)
+            return null;
+        if (now() >= deadline)
+            return NO_NATIVE_CONTROLS_NOTICE;
+        await sleep(250);
+    }
+}
 export function createBrowserPane(run, executable, url, options, environment, cwd, namespace) {
     validateBrowserOpen(url, options);
     const inheritedPane = /^%\d+$/u.test(environment.TMUX_PANE ?? "")
@@ -163,9 +199,16 @@ export function createBrowserPane(run, executable, url, options, environment, cw
         });
     return { pane: pane, session: createdSession, window: createdWindow, status: "created" };
 }
-export function openBrowser(url, options = {}) {
+export async function openBrowser(url, options = {}, dependencies = {}) {
     validateBrowserOpen(url, options);
-    const executable = resolveTerminalBrowser();
+    const executable = (dependencies.executable ?? resolveTerminalBrowser)();
+    const { result, run } = (dependencies.create ?? createPinnedBrowserPane)(executable, url, options);
+    const message = await nativeControlsNotice(run, result.pane, executable, dependencies.wait);
+    if (message)
+        (dependencies.notice ?? ((line) => process.stderr.write(`${line}\n`)))(message);
+    return result;
+}
+function createPinnedBrowserPane(executable, url, options) {
     try {
         const namespace = { ...runtimeNamespaceEnvironment(resolveRuntimeNamespace()) };
         const authority = resolveWorkspacePaneTmuxAuthority();
@@ -173,7 +216,8 @@ export function openBrowser(url, options = {}) {
         const run = createPinnedWorkspaceTmuxRunner(authority, {
             timeoutMs: 10_000,
         });
-        return createBrowserPane(run, executable, url, options, process.env, process.cwd(), namespace);
+        const result = createBrowserPane(run, executable, url, options, process.env, process.cwd(), namespace);
+        return { result, run };
     }
     catch (error) {
         if (error instanceof IdeError)

package/packages/daemon/dist/terminal/pane-stream/pane-stream-websocket.js

@@ -6,6 +6,7 @@ import { PANE_STREAM_INPUT_LIFETIME_CAPABILITY_VERSION, PANE_STREAM_INPUT_BYTES_
 import { inflateSync } from "node:zlib";
 import { PaneStreamLayoutSnapshotFrameSchemaZ } from "@tmux-ide/contracts";
 import { z } from "zod";
+import { logger } from "../../lib/log.js";
 import { PANE_STREAM_MAX_HELD_DELTAS, PANE_STREAM_MAX_OUTPUT_BYTES, PANE_STREAM_MAX_PANES, PANE_STREAM_MAX_SEED_BYTES, PANE_STREAM_PROTOCOL_VERSION, PANE_STREAM_REDEEM_PATH, PANE_STREAM_WEBSOCKET_SUBPROTOCOL, TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES, TERMINAL_DELIVERY_BINARY_CAPABILITY_VERSION, TERMINAL_DELIVERY_BINARY_LOCAL_CAPABILITY_VERSION, TERMINAL_GRAPHICS_BINARY_CAPABILITY_VERSION, TERMINAL_GRAPHICS_LOCAL_CAPABILITY_VERSION, encodeTerminalGraphicsBinary, encodeTerminalDeliveryBinaryChunk, TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION, TERMINAL_GRAPHICS_PRECISE_PIXELS_CAPABILITY_VERSION, TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES, TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION, PaneStreamClientFrameSchemaZ, PaneStreamLoopbackWebSocketUrlSchemaZ, PaneStreamRedeemFrameSchemaZ, PaneStreamServerFrameSchemaZ, sharedMonotonicMicros, } from "@tmux-ide/contracts";
 import { canonicalOriginOrNull, digestSecret, digestsEqual, rawDataByteLength, rawDataToBuffer, safeCloseSocket, strictJsonParse, } from "../attachments/admission-util.js";
 import { SessionRuntimeControllerLeaseError } from "../session-runtime/registry.js";
@@ -547,6 +548,11 @@ class PreAuthAdmission {
         this.#open = false;
         this.#cancelDeadline();
         const socket = this.#socket;
+        logger.info("pane-stream", "admission closed", {
+            code,
+            reason,
+            hostClientId: this.hostClientId,
+        });
         this.#detach();
         this.#onRelease(this);
         if (socket)
@@ -825,6 +831,12 @@ export class PaneStreamLiveConnection {
         if (this.#closed)
             return;
         this.#recordDiagnosticLifecycle("pane-stream-terminal", code, reason);
+        logger.info("pane-stream", "stream closed", {
+            code,
+            reason,
+            session: this.#descriptor.sessionName,
+            clientId: this.#clientId,
+        });
         this.#closed = true;
         for (const demand of this.#surfaceDemands.values())
             demand.close();

package/packages/daemon/dist/terminal/session-runtime/terminal-delivery-hub.js

@@ -2,6 +2,7 @@ import { prepareProjection } from "./terminal-projection-delivery.js";
 import { TerminalProjectionEnvelopeSchemaZ, TerminalProjectionReceiptSchemaZ, TerminalProjectionMaterializeSchemaZ, } from "@tmux-ide/contracts";
 import { encodeTerminalProjectionCooperatively } from "@tmux-ide/core";
 import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.js";
+import { logger } from "../../lib/log.js";
 import { MAX_RETAINED_NATIVE_BACKING_BYTES, takeNativeSeedBacking, } from "./native-seed-backing.js";
 import { WorkspaceIdSchemaZ, TERMINAL_GRAPHICS_CAPABILITY_VERSION, TERMINAL_DELIVERY_PATCH_TO_SEED_BYTES, TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES, TerminalDeliveryEnvelopeSchemaZ, TerminalDeliveryAckSchemaZ, TerminalDeliveryNackSchemaZ, TerminalDeliveryOfferSchemaZ, TerminalDeliveryVisibilitySchemaZ, } from "@tmux-ide/contracts";
 import { TerminalDeliveryStateTooLargeError, terminalReplicaRowsEqual, TERMINAL_COMPACT_COOPERATIVE_SEED_CELLS, applyTerminalReplicaUpdate, applyTerminalReplicaUpdateCooperatively, terminalReplicaUpdateNeedsCooperativeReduction, encodeBinarySemanticTerminalUpdate, encodeBinarySemanticTerminalUpdateCooperatively, encodeCompactSemanticTerminalUpdate, encodeCompactSemanticTerminalUpdateCooperatively, terminalSemanticUpdateNeedsCooperativeEncoding, encodeAnsiTerminalRepresentation, encodeSemanticTerminalUpdate, hashTerminalDeliveryRepresentation, negotiateTerminalDelivery, preaccountSemanticTerminalUpdateBytes, } from "@tmux-ide/core";
@@ -196,6 +197,7 @@ export class SessionRuntimeTerminalDeliveryHub {
             if (!(error instanceof StockCaptureTabUnavailableError))
                 throw error;
             // Negotiation still settles this pane; no invented canonical seed is published.
+            logDeliveryFault({ paneId: semanticPaneId, deliveryWorkspaceName: address }, "source-closed", "capture-unavailable");
             await accept({
                 type: "terminal.delivery.fault",
                 reason: "source-closed",
@@ -350,6 +352,7 @@ export class SessionRuntimeTerminalDeliveryHub {
             this.#cancelEncoding(client);
             client.outgoing.length = 0;
             client.inFlight = null;
+            logDeliveryFault(client, "source-closed", "source-restarted");
             this.#enqueue(client, {
                 type: "terminal.delivery.fault",
                 reason: "source-closed",
@@ -1442,6 +1445,7 @@ export class SessionRuntimeTerminalDeliveryHub {
         this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
     }
     #fault(client, reason, message, selectionObservation = null) {
+        logDeliveryFault(client, reason);
         if (this.#observability.enabled)
             try {
                 const atMicros = this.#observability.nowMicros();
@@ -2038,3 +2042,15 @@ function joinBytes(chunks) {
     }
     return joined;
 }
+/**
+ * One info line per fault a client is sent, so a client's drop has a daemon-side
+ * record. Ids and fixed reasons only: the fault message can carry source text.
+ */
+function logDeliveryFault(client, reason, cause) {
+    logger.info("terminal-delivery", "fault sent to client", {
+        reason,
+        ...(cause ? { cause } : {}),
+        pane: client.paneId,
+        workspace: client.deliveryWorkspaceName,
+    });
+}