tmux-ide 2.9.15 → 2.9.16

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,
+    });
+}

package/packages/daemon/src/command-center/daemon-fleet-facts-observer.ts

@@ -90,7 +90,7 @@ export class DaemonFleetFactsObserver {
 
   constructor(options: DaemonFleetFactsObserverOptions) {
     this.#options = options;
-    this.#intervalMs = options.intervalMs ?? 2_000;
+    this.#intervalMs = options.intervalMs ?? FLEET_FACTS_POLL_MS;
     this.#setTimer =
       options.setTimer ??
       ((callback, delayMs) => {
@@ -549,6 +549,14 @@ export function createDefaultFleetFactsReaders(): Pick<
   return createSharedFleetFactsReaders(execute);
 }
 
+/**
+ * How often subscribed clients' tmux facts (sessions, panes, agent stamps) are
+ * read. Hook-stamped agent changes reach clients within one tick, so 500 ms
+ * keeps a state flip visible within 1 s (#716). One `list-panes -a` per tick,
+ * only while a client is subscribed.
+ */
+export const FLEET_FACTS_POLL_MS = 500;
+
 export const SESSION_COMPOSITION_TMUX_ARGS = [
   "list-panes",
   "-a",

package/packages/daemon/src/command-center/tmux-servers.ts

@@ -22,6 +22,7 @@ import {
   TmuxServerScopeSchemaZ,
   TmuxServersResourceSchemaZ,
   TmuxServerSessionsResourceSchemaZ,
+  TmuxServerSessionsResourceV2SchemaZ,
   WorkspaceMultiplexerMutationRequestSchemaZ,
   WorkspacePaneCreateMutationRequestSchemaZ,
   WorkspaceSessionCreateArgumentsSchemaZ,
@@ -32,6 +33,7 @@ import {
   TmuxServerScopeError,
 } from "../lib/tmux-server-owners.ts";
 import type { NativeTmuxServerOwner } from "../lib/tmux-server-owner.ts";
+import { createSessionFaviconResolver, type SessionFavicon } from "../lib/session-favicon.ts";
 import { WorkspaceMultiplexerError } from "../lib/workspace-multiplexer-verbs.ts";
 import { WorkspacePaneCreationError } from "../lib/workspace-pane-creation.ts";
 import { ownerBearerMatches } from "./owner-authority.ts";
@@ -41,7 +43,11 @@ import { projectTerminalRuntimeInventory } from "./resources/terminal-runtime-in
 export interface TmuxServerRoutesOptions {
   readonly ownerToken: string | null;
   readonly owners: TmuxServerOwners<NativeTmuxServerOwner>;
+  /** Project favicon lookup for the version 2 sessions resource. */
+  readonly resolveSessionFavicon?: (sessionPath: string) => Promise<SessionFavicon | null>;
 }
+/** Total raw favicon bytes one version 2 sessions response may carry. */
+export const SESSIONS_RESOURCE_FAVICON_BUDGET_BYTES = 512 * 1024;
 const registrationSchema = TmuxServerRegistrationSchemaZ.omit({ serverId: true }).strict();
 const workspaceSchema = z
   .string()
@@ -94,6 +100,7 @@ function failure(c: Context, error: unknown): Response {
 /** Owner capability is mandatory even when the ordinary local HTTP surface is open. */
 export function mountTmuxServerRoutes(app: Hono, options: TmuxServerRoutesOptions): void {
   const base = TMUX_SERVERS_API_PATH;
+  const resolveSessionFavicon = options.resolveSessionFavicon ?? createSessionFaviconResolver();
   const authorize = async (c: Context, next: () => Promise<void>) => {
     c.header("Cache-Control", "no-store");
     if (!ownerBearerMatches(c.req.header("Authorization"), options.ownerToken))
@@ -271,19 +278,56 @@ export function mountTmuxServerRoutes(app: Hono, options: TmuxServerRoutesOption
     `${scoped}/sessions`,
     route(async (c) => {
       const server = scope(c);
+      const v2 = c.req.query("version") === "2";
+      const { rows, favicons } = await options.owners.withOwner(server, async (owner) => {
+        const sessions = await owner.catalog();
+        const workspaces = owner.workspaceRegistry.list();
+        const rows = sessions.map((session) => {
+          const aliases = workspaces.filter(
+            (workspace) => workspace.sessionName === session.sessionName,
+          );
+          return { session, workspaceName: aliases.length === 1 ? aliases[0]!.name : null };
+        });
+        const favicons = v2
+          ? await Promise.all(
+              sessions.map((session) =>
+                resolveSessionFavicon(session.sessionPath).catch(() => null),
+              ),
+            )
+          : [];
+        return { rows, favicons };
+      });
+      if (!v2)
+        return c.json(
+          TmuxServerSessionsResourceSchemaZ.parse({
+            version: 1,
+            server,
+            sessions: rows.map(({ session, workspaceName }) => ({
+              liveSessionId: session.liveSessionId,
+              sessionName: session.sessionName,
+              paneCount: session.paneCount,
+              workspaceName,
+            })),
+          }),
+        );
+      let budget = SESSIONS_RESOURCE_FAVICON_BUDGET_BYTES;
       return c.json(
-        TmuxServerSessionsResourceSchemaZ.parse({
-          version: 1,
+        TmuxServerSessionsResourceV2SchemaZ.parse({
+          version: 2,
           server,
-          sessions: await options.owners.withOwner(server, async (owner) => {
-            const sessions = await owner.catalog();
-            const workspaces = owner.workspaceRegistry.list();
-            return sessions.map((session) => {
-              const aliases = workspaces.filter(
-                (workspace) => workspace.sessionName === session.sessionName,
-              );
-              return { ...session, workspaceName: aliases.length === 1 ? aliases[0]!.name : null };
-            });
+          sessions: rows.map(({ session, workspaceName }, index) => {
+            const found = favicons[index] ?? null;
+            const favicon = found && found.size <= budget ? found : null;
+            if (favicon) budget -= favicon.size;
+            return {
+              liveSessionId: session.liveSessionId,
+              sessionName: session.sessionName,
+              workspaceName,
+              paneCount: session.paneCount,
+              windowCount: session.windowCount,
+              lastActivity: session.lastActivity,
+              favicon: favicon ? { mime: favicon.mime, data: favicon.data } : null,
+            };
           }),
         }),
       );

package/packages/daemon/src/lib/session-favicon.ts

@@ -0,0 +1,185 @@
+import { constants, type Stats } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { extname, isAbsolute, join } from "node:path";
+import {
+  TMUX_SERVER_SESSION_FAVICON_MAX_BYTES,
+  type TmuxServerSessionFaviconMime,
+} 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",
+] as const;
+
+const MIME_BY_EXTENSION: Readonly<Record<string, TmuxServerSessionFaviconMime>> = {
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+export interface SessionFavicon {
+  readonly mime: TmuxServerSessionFaviconMime;
+  /** Base64 of the raw file bytes. */
+  readonly data: string;
+  /** Raw byte count. */
+  readonly size: number;
+}
+
+export interface SessionFaviconIo {
+  lstat(path: string): Promise<Stats>;
+  /** Reads a regular file without following a final symlink; null when refused or too large. */
+  readNoFollow(path: string, maxBytes: number): Promise<Buffer | null>;
+}
+
+export const defaultSessionFaviconIo: SessionFaviconIo = {
+  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);
+    }
+  },
+};
+
+type CacheEntry =
+  | {
+      readonly kind: "hit";
+      readonly file: string;
+      readonly mtimeMs: number;
+      readonly size: number;
+      readonly favicon: SessionFavicon;
+    }
+  | { readonly kind: "miss"; readonly at: number };
+
+export interface SessionFaviconResolverOptions {
+  readonly io?: SessionFaviconIo;
+  readonly now?: () => number;
+  readonly missTtlMs?: number;
+  readonly maxEntries?: number;
+}
+
+async function lstatOrNull(io: SessionFaviconIo, path: string): Promise<Stats | null> {
+  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: SessionFaviconResolverOptions = {}) {
+  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<string, CacheEntry>();
+
+  const remember = (sessionPath: string, entry: CacheEntry) => {
+    cache.delete(sessionPath);
+    cache.set(sessionPath, entry);
+    while (cache.size > maxEntries) cache.delete(cache.keys().next().value!);
+  };
+
+  const scan = async (sessionPath: string): Promise<CacheEntry> => {
+    const directories = new Map<string, boolean>();
+    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: string): Promise<SessionFavicon | null> => {
+    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/src/lib/skill-sync.ts

@@ -13,8 +13,8 @@ import { resolveRuntimeNamespace } from "./runtime-namespace.ts";
  *
  * 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}
@@ -73,7 +73,7 @@ export function defaultSkillSource(): string {
 // ---------------------------------------------------------------------------
 
 /**
- * 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/src/lib/tmux-server-owner.ts

@@ -97,13 +97,23 @@ function discoveredWorkspaceName(registry: WorkspaceRegistry, sessionName: strin
   throw new Error("Unable to allocate discovered workspace identity");
 }
 
+/** A live session row with the facts the native app's Home shows beside it. */
+export interface NativeLiveSessionSummary extends LiveSessionSummary {
+  /** Distinct tmux windows of the session (at least one). */
+  readonly windowCount: number;
+  /** tmux `#{session_activity}` in epoch seconds, or null when tmux reports none. */
+  readonly lastActivity: number | null;
+  /** tmux `#{session_path}`, the session's working directory. */
+  readonly sessionPath: string;
+}
+
 /** Refresh discovered live membership without changing durable workspace intent or aliases. */
 export function createNativeTmuxServerCatalog(
   workspaceRegistry: WorkspaceRegistry,
   run: (args: readonly string[], signal?: AbortSignal) => Promise<string>,
   assertOpen: () => void = () => undefined,
-): () => Promise<LiveSessionSummary[]> {
-  return async (): Promise<LiveSessionSummary[]> => {
+): () => Promise<NativeLiveSessionSummary[]> {
+  return async (): Promise<NativeLiveSessionSummary[]> => {
     assertOpen();
     const raw = await run(
       [
@@ -116,7 +126,8 @@ export function createNativeTmuxServerCatalog(
           "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(" "),
@@ -126,13 +137,20 @@ export function createNativeTmuxServerCatalog(
     assertOpen();
     const rows = new Map<
       string,
-      { summary: LiveSessionSummary; panes: Set<string>; dir: string }
+      {
+        summary: LiveSessionSummary;
+        panes: Set<string>;
+        windows: Set<string>;
+        dir: string;
+        activity: number | null;
+      }
     >();
     // Only the successful server-side zero-session branch proves emptiness.
     // 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) ||
@@ -143,6 +161,8 @@ export function createNativeTmuxServerCatalog(
         !name ||
         !pane ||
         !/^%\d+$/.test(pane) ||
+        !window ||
+        !/^@\d+$/.test(window) ||
         !dir
       )
         throw new Error("Invalid native server catalog");
@@ -151,9 +171,12 @@ export function createNativeTmuxServerCatalog(
       const row = rows.get(liveSessionId) ?? {
         summary: { liveSessionId, sessionName: name, paneCount: 0 },
         panes: new Set<string>(),
+        windows: new Set<string>(),
         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));
@@ -170,7 +193,13 @@ export function createNativeTmuxServerCatalog(
           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,
+    }));
   };
 }
 

package/packages/daemon/src/open-browser.ts

@@ -115,6 +115,54 @@ export function validateBrowserOpen(url: string | undefined, options: OpenBrowse
 }
 
 type Run = (args: readonly string[]) => string;
+
+/** 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: string): boolean {
+  return /\/[^/]+\.app\/Contents\/Resources\/browser\//u.test(executable);
+}
+
+export interface ControlsWait {
+  sleep?: (ms: number) => Promise<void>;
+  /** Milliseconds; Date.now by default. */
+  now?: () => number;
+}
+
+/** 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: Run,
+  pane: string,
+  executable: string,
+  wait: ControlsWait = {},
+): Promise<string | null> {
+  if (isBundledBrowser(executable)) return null;
+  const sleep = wait.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const now = wait.now ?? Date.now;
+  const deadline = now() + STANDALONE_WAIT_MS;
+  for (;;) {
+    let control: string;
+    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: Run,
   executable: string,
@@ -220,9 +268,37 @@ export function createBrowserPane(
   return { pane: pane!, session: createdSession!, window: createdWindow!, status: "created" };
 }
 
-export function openBrowser(url: string | undefined, options: OpenBrowserOptions = {}) {
+/** Seams for tests; the CLI uses the defaults. */
+export interface OpenBrowserDependencies {
+  notice?: (line: string) => void;
+  executable?: () => string;
+  create?: typeof createPinnedBrowserPane;
+  wait?: ControlsWait;
+}
+
+export async function openBrowser(
+  url: string | undefined,
+  options: OpenBrowserOptions = {},
+  dependencies: OpenBrowserDependencies = {},
+) {
   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: string) => process.stderr.write(`${line}\n`)))(message);
+  return result;
+}
+
+function createPinnedBrowserPane(
+  executable: string,
+  url: string | undefined,
+  options: OpenBrowserOptions,
+): { result: ReturnType<typeof createBrowserPane>; run: Run } {
   try {
     const namespace = { ...runtimeNamespaceEnvironment(resolveRuntimeNamespace()) };
     const authority = resolveWorkspacePaneTmuxAuthority();
@@ -230,7 +306,16 @@ export function openBrowser(url: string | undefined, options: OpenBrowserOptions
     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) throw error;
     throw new IdeError(

package/packages/daemon/src/terminal/pane-stream/pane-stream-websocket.ts

@@ -28,6 +28,7 @@ import { inflateSync } from "node:zlib";
 import { PaneStreamLayoutSnapshotFrameSchemaZ, type WindowLinkTopology } from "@tmux-ide/contracts";
 import type { TerminalDeliveryGraphics } from "../session-runtime/terminal-delivery-hub.ts";
 import { z } from "zod";
+import { logger } from "../../lib/log.ts";
 import {
   PANE_STREAM_MAX_HELD_DELTAS,
   PANE_STREAM_MAX_OUTPUT_BYTES,
@@ -988,6 +989,11 @@ class PreAuthAdmission implements PaneStreamPreAuthAdmission {
     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) safeCloseSocket(socket, code, reason);
@@ -1386,6 +1392,12 @@ export class PaneStreamLiveConnection {
   close(code = 1000, reason = "stream-closed"): void {
     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();
     this.#surfaceDemands.clear();

package/packages/daemon/src/terminal/session-runtime/terminal-delivery-hub.ts

@@ -12,6 +12,7 @@ import { encodeTerminalProjectionCooperatively } from "@tmux-ide/core";
 type DeliveryEnvelope = TerminalDeliveryEnvelope | TerminalProjectionEnvelope;
 import type { KittyImage } from "../graphics/kitty-graphics.ts";
 import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.ts";
+import { logger } from "../../lib/log.ts";
 import {
   MAX_RETAINED_NATIVE_BACKING_BYTES,
   takeNativeSeedBacking,
@@ -512,6 +513,11 @@ export class SessionRuntimeTerminalDeliveryHub {
     } catch (error) {
       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",
@@ -697,6 +703,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",
@@ -2008,6 +2015,7 @@ export class SessionRuntimeTerminalDeliveryHub {
     message: string,
     selectionObservation: SemanticSelectionObservation | null = null,
   ): void {
+    logDeliveryFault(client, reason);
     if (this.#observability.enabled)
       try {
         const atMicros = this.#observability.nowMicros();
@@ -2694,3 +2702,20 @@ function joinBytes(chunks: readonly Uint8Array[]): Uint8Array {
   }
   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: Pick<ClientState, "paneId" | "deliveryWorkspaceName">,
+  reason: "state-too-large" | "source-closed" | "protocol-violation",
+  cause?: "source-restarted" | "capture-unavailable",
+): void {
+  logger.info("terminal-delivery", "fault sent to client", {
+    reason,
+    ...(cause ? { cause } : {}),
+    pane: client.paneId,
+    workspace: client.deliveryWorkspaceName,
+  });
+}