tmux-ide 2.9.14 → 2.9.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.9.14",
+  "version": "2.9.16",
   "description": "The open-source workspace for coding agents: run Claude Code, Codex and other agents in tmux with live status",
   "type": "module",
   "bin": {
@@ -70,6 +70,7 @@
     "postinstall": "node scripts/postinstall.js",
     "docs": "turbo run dev --filter=@tmux-ide/docs",
     "demo:tui": "bun --preload @opentui/solid/preload docs/scripts/render-tui-demo.tsx",
+    "demo:themes": "bun --preload @opentui/solid/preload docs/scripts/render-theme-gallery.tsx && node docs/scripts/rasterize-theme-gallery.mjs",
     "demo:font": "node docs/scripts/tui-demo-font/build.mjs",
     "readme:media": "node docs/scripts/readme-media.mjs",
     "test:tui-renderer": "bun test --preload @opentui/solid/preload --preload ./packages/daemon/test-support/opentui-renderer-preload.ts ./packages/daemon/src/tui/mirror/automatic-contrast-renderer.test.tsx ./packages/daemon/src/tui/mirror/pane-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/native-grid-projection-renderer.test.tsx ./packages/daemon/src/tui/mirror/widget-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/missions-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/recipes-gallery-renderer.test.tsx ./packages/daemon/src/tui/mirror/shell-chrome-renderer.test.tsx ./packages/daemon/src/tui/mirror/sidebar-renderer.test.tsx ./packages/daemon/src/tui/mirror/home-files-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/changes-terminal-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/activity-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/features/files/session-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-terminal-workspace-renderer.test.tsx ./packages/daemon/src/tui/mirror/testing/styled-frame-oracle.test.tsx ./packages/daemon/src/tui/mirror/runtime/terminal-transient-frame-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/terminal-draw-failure-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-view-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-root-error-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-backpressure-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-demand-cadence-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/files-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/changes-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/missions-activity-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/dialogs-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/optional-feature-registry-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/palette-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/pane-scoped-terminal-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/features/rich-preview/feature.test.ts ./packages/daemon/src/tui/mirror/runtime/rich-preview-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/application-shell-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/pane-frame-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-pane-chrome-view.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-window-strip-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/workbench-shell-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/workbench-dock-dual-host-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/agent-terminal-canvas-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/command-palette-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/opentui-insertion-stability-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-home-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-pane-header-polish-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-home-agent-roster-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-home-agent-flow-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/guided-tour-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-sidebar-catalog-renderer.test.tsx ./packages/daemon/src/tui/mirror/ui/ui-renderer.test.tsx ./packages/daemon/src/tui/mirror/ui/pane-interaction-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-machine-sidebar-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-add-machine-dialog-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-new-agent-dialog-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-switcher-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-palette-preview-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-palette-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-session-actions-renderer.test.tsx ./packages/daemon/src/tui/mirror/ui/agent-team-renderer.test.tsx ./scripts/solid-conditional-props.test.tsx",

package/packages/contracts/src/index.ts

@@ -116,6 +116,7 @@ export * from "./visual-terminal-palette.ts";
 
 export * from "./window-split-layout.ts";
 export * from "./pane-editor-context.ts";
+export * from "./native-browser.ts";
 
 export * from "./tmux-agent-open.ts";
 

package/packages/contracts/src/native-browser.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+const text = (limit: number) =>
+  z
+    .string()
+    .max(limit)
+    // Intentionally reject control characters in display text and navigation input.
+    // eslint-disable-next-line no-control-regex
+    .refine((value) => !/[\x00-\x1f\x7f]/u.test(value));
+const identity = {
+  version: z.literal(1),
+  instance: z.uuid(),
+  pane: z
+    .string()
+    .regex(/^%[0-9]+$/u)
+    .max(32),
+  tab: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  revision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+};
+/** Display state is not authority: every command echoes the exact browser revision. */
+export const NativeBrowserStateSchemaZ = z
+  .object({
+    ...identity,
+    enabled: z.boolean(),
+    url: text(16_384),
+    title: text(512),
+    loading: z.boolean(),
+    canGoBack: z.boolean(),
+    canGoForward: z.boolean(),
+  })
+  .strict();
+export const NativeBrowserCommandSchemaZ = z.discriminatedUnion("action", [
+  z.object({ ...identity, action: z.enum(["back", "forward", "reload", "stop"]) }).strict(),
+  z
+    .object({
+      ...identity,
+      action: z.literal("navigate"),
+      text: text(16_384).refine((value) => value.trim().length > 0),
+    })
+    .strict(),
+]);
+export type NativeBrowserState = z.infer<typeof NativeBrowserStateSchemaZ>;
+export type NativeBrowserCommand = z.infer<typeof NativeBrowserCommandSchemaZ>;

package/packages/contracts/src/tmux-server-scope.ts

@@ -151,6 +151,60 @@ export const TmuxServerSessionsResourceSchemaZ = z
   })
   .strict();
 
+/** Raw (decoded) byte limit for one session favicon on the sessions resource. */
+export const TMUX_SERVER_SESSION_FAVICON_MAX_BYTES = 32_768;
+export const TmuxServerSessionFaviconMimeSchemaZ = z.enum([
+  "image/png",
+  "image/svg+xml",
+  "image/x-icon",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+export type TmuxServerSessionFaviconMime = z.infer<typeof TmuxServerSessionFaviconMimeSchemaZ>;
+function base64DecodedLength(data: string): number {
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  return (data.length / 4) * 3 - padding;
+}
+export const TmuxServerSessionFaviconSchemaZ = z
+  .object({
+    mime: TmuxServerSessionFaviconMimeSchemaZ,
+    data: z
+      .string()
+      .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u)
+      .refine(
+        (data) => base64DecodedLength(data) <= TMUX_SERVER_SESSION_FAVICON_MAX_BYTES,
+        "favicon exceeds 32 KiB",
+      ),
+  })
+  .strict();
+export type TmuxServerSessionFavicon = z.infer<typeof TmuxServerSessionFaviconSchemaZ>;
+
+/**
+ * Version 2 of the sessions resource, served only for `?version=2`. Version 1
+ * stays byte-for-byte for clients that parse it with unknown fields denied.
+ */
+export const TmuxServerSessionsResourceV2SchemaZ = z
+  .object({
+    version: z.literal(2),
+    server: TmuxServerScopeSchemaZ,
+    sessions: z.array(
+      z
+        .object({
+          liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ,
+          sessionName: z.string().min(1).max(160),
+          workspaceName: z.string().min(1).max(160).nullable(),
+          paneCount: z.number().int().nonnegative(),
+          windowCount: z.number().int().min(1),
+          lastActivity: z.number().int().nonnegative().nullable(),
+          favicon: TmuxServerSessionFaviconSchemaZ.nullable(),
+        })
+        .strict(),
+    ),
+  })
+  .strict();
+export type TmuxServerSessionsResourceV2 = z.infer<typeof TmuxServerSessionsResourceV2SchemaZ>;
+
 /** Selector intent is interpreted only by the daemon on its own host. */
 export const TmuxServerRegistrationRequestSchemaZ = z
   .object({

package/packages/core/src/terminal-replica.ts

@@ -581,15 +581,19 @@ export async function applyTerminalReplicaUpdateCooperatively(
   }
   const authenticated = options.authenticatedFrameHash;
   const frameStart = readProfileClock(options.instrumentation);
-  const frameHash =
-    authenticated && /^[0-9a-f]{16}$/u.test(authenticated)
-      ? authenticated
-      : await hashCanonicalTerminalValueCooperatively(
-          { ...admitted, snapshot },
-          yieldControl,
-          // Bound frame hashing without scheduling a task per few cells.
-          32 * 1024,
-        );
+  const reuseAuthenticated = Boolean(authenticated && /^[0-9a-f]{16}$/u.test(authenticated));
+  if (!reuseAuthenticated) {
+    await primeTerminalReplicaRowsHashCooperatively(snapshot.grid, yieldControl);
+    await primeTerminalReplicaRowsHashCooperatively(snapshot.history, yieldControl);
+  }
+  const frameHash = reuseAuthenticated
+    ? authenticated!
+    : await hashCanonicalTerminalValueCooperatively(
+        terminalReplicaFrameIdentity({ ...admitted, snapshot }),
+        yieldControl,
+        // Bound frame hashing without scheduling a task per few cells.
+        32 * 1024,
+      );
   if (profile)
     profile.reusedAuthenticatedFrameHash = Boolean(
       authenticated && /^[0-9a-f]{16}$/u.test(authenticated),
@@ -984,11 +988,29 @@ function resolveFrameHash(
     return authenticated;
   }
   const started = readProfileClock(options.instrumentation);
-  const hash = hashStable(update);
+  const hash = hashStable(terminalReplicaFrameIdentity(update));
   addProfileDuration(profile, "updateHash", started, options.instrumentation);
   return hash;
 }
 
+/**
+ * What a frame hash covers. A seed's rows enter as their row-sequence hashes,
+ * which the replica caches per frozen row, so a seed carrying a pane's whole
+ * history is not walked cell by cell a second time (#706). Every other field
+ * enters as is. The cooperative and ordinary paths must agree: a redelivered
+ * seed whose frame hash differs is a protocol conflict, not idempotent.
+ */
+function terminalReplicaFrameIdentity(update: CanonicalTerminalReplicaUpdate): unknown {
+  if (update.type !== "terminal.seed") return update;
+  const { grid, history, ...rest } = update.snapshot;
+  return [
+    "terminal-replica-frame-v2",
+    { ...update, snapshot: rest },
+    hashTerminalReplicaRows(grid),
+    hashTerminalReplicaRows(history),
+  ];
+}
+
 function readProfileClock(
   instrumentation: TerminalReplicaApplyOptions["instrumentation"] | undefined,
 ): number | undefined {

package/packages/daemon/dist/command-center/daemon-fleet-facts-observer.js

@@ -30,7 +30,7 @@ export class DaemonFleetFactsObserver {
     #diagnosticActiveOperations = 0;
     constructor(options) {
         this.#options = options;
-        this.#intervalMs = options.intervalMs ?? 2_000;
+        this.#intervalMs = options.intervalMs ?? FLEET_FACTS_POLL_MS;
         this.#setTimer =
             options.setTimer ??
                 ((callback, delayMs) => {
@@ -461,6 +461,13 @@ export function createDefaultFleetFactsReaders() {
     };
     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/dist/command-center/tmux-servers.js

@@ -10,13 +10,16 @@ import { streamSSE } from "hono/streaming";
 import { projectApplicationShellResource } from "./resources/application-shell.js";
 import { fleetSessionIdForName } from "./resources/fleet-catalog.js";
 import { z } from "zod";
-import { TmuxAgentOpenRequestSchemaZ, TmuxAgentOpenResponseSchemaZ, WorkspaceCatalogLiveSessionIdSchemaZ, WindowLinkTargetSchemaZ, WindowSplitLayoutResourceSchemaZ, TMUX_SERVERS_API_PATH, PANE_STREAM_ISSUE_PATH, TmuxServerIdSchemaZ, TmuxServerScopeSchemaZ, TmuxServersResourceSchemaZ, TmuxServerSessionsResourceSchemaZ, WorkspaceMultiplexerMutationRequestSchemaZ, WorkspacePaneCreateMutationRequestSchemaZ, WorkspaceSessionCreateArgumentsSchemaZ, } from "@tmux-ide/contracts";
+import { TmuxAgentOpenRequestSchemaZ, TmuxAgentOpenResponseSchemaZ, WorkspaceCatalogLiveSessionIdSchemaZ, WindowLinkTargetSchemaZ, WindowSplitLayoutResourceSchemaZ, TMUX_SERVERS_API_PATH, PANE_STREAM_ISSUE_PATH, TmuxServerIdSchemaZ, TmuxServerScopeSchemaZ, TmuxServersResourceSchemaZ, TmuxServerSessionsResourceSchemaZ, TmuxServerSessionsResourceV2SchemaZ, WorkspaceMultiplexerMutationRequestSchemaZ, WorkspacePaneCreateMutationRequestSchemaZ, WorkspaceSessionCreateArgumentsSchemaZ, } from "@tmux-ide/contracts";
 import { TmuxServerRegistrationSchemaZ, TmuxServerScopeError, } from "../lib/tmux-server-owners.js";
+import { createSessionFaviconResolver } from "../lib/session-favicon.js";
 import { WorkspaceMultiplexerError } from "../lib/workspace-multiplexer-verbs.js";
 import { WorkspacePaneCreationError } from "../lib/workspace-pane-creation.js";
 import { ownerBearerMatches } from "./owner-authority.js";
 import { mountPaneStreamIssueRoute } from "./pane-stream-issue.js";
 import { projectTerminalRuntimeInventory } from "./resources/terminal-runtime-inventory.js";
+/** 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()
@@ -69,6 +72,7 @@ function failure(c, error) {
 /** Owner capability is mandatory even when the ordinary local HTTP surface is open. */
 export function mountTmuxServerRoutes(app, options) {
     const base = TMUX_SERVERS_API_PATH;
+    const resolveSessionFavicon = options.resolveSessionFavicon ?? createSessionFaviconResolver();
     const authorize = async (c, next) => {
         c.header("Cache-Control", "no-store");
         if (!ownerBearerMatches(c.req.header("Authorization"), options.ownerToken))
@@ -107,6 +111,12 @@ export function mountTmuxServerRoutes(app, options) {
         owners: options.owners,
         readBody: (request) => boundedJson(request, 8 * 1024),
     });
+    app.post(`${scoped}/native-browser`, route(async (c) => {
+        const server = scope(c);
+        const input = await boundedJson(c.req.raw, 24 * 1024);
+        const state = await options.owners.withOwner(server, (owner) => owner.nativeBrowser(input, c.req.raw.signal));
+        return c.json({ version: 1, state });
+    }));
     // Structured read only: this never acquires a channel or changes tmux geometry.
     app.post(`${scoped}/split-layout/:workspaceName`, route(async (c) => {
         const server = scope(c);
@@ -179,16 +189,48 @@ export function mountTmuxServerRoutes(app, options) {
     }));
     app.get(`${scoped}/sessions`, route(async (c) => {
         const server = scope(c);
-        return c.json(TmuxServerSessionsResourceSchemaZ.parse({
-            version: 1,
+        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(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/dist/lib/daemon-embed.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { createNativeBrowserResolver } from "./tmux-native-browser.js";
 import { createNativeSurfaceContextResolver } from "./native-surface-context.js";
 import { NativeSurfaceProviderRegistry } from "../terminal/graphics/native-surface-provider.js";
 import { TmuxServerVersionSchemaZ } from "@tmux-ide/contracts";
@@ -1397,6 +1398,20 @@ async function startEmbeddedDaemonGeneration(opts) {
                                 throw new Error("Default tmux editor context owner is unavailable");
                         },
                     }),
+                    nativeBrowser: createNativeBrowserResolver({
+                        generation: instanceId,
+                        run: fleetFactsTmuxRunner,
+                        registry: workspaceRegistry,
+                        catalog: createNativeTmuxServerCatalog(workspaceRegistry, fleetFactsTmuxRunner),
+                        inventory: terminalInventoryRuntime,
+                        assertOpen: () => {
+                            if (defaultEditorContextRetired ||
+                                serverOwners?.defaultRetired ||
+                                !initialNativeServerIdentity ||
+                                terminalInventoryRuntime?.lifecycleState() !== "ready")
+                                throw new Error("Default native browser owner is unavailable");
+                        },
+                    }),
                     catalog: createNativeTmuxServerCatalog(workspaceRegistry, fleetFactsTmuxRunner),
                     readWindowSplitLayout: async (workspaceName, input) => {
                         const target = WindowLinkTargetSchemaZ.parse(input);

package/packages/daemon/dist/lib/native-browser-rpc.js

@@ -0,0 +1,110 @@
+import { randomUUID } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { connect } from "node:net";
+import { NativeBrowserCommandSchemaZ, NativeBrowserStateSchemaZ, } from "@tmux-ide/contracts";
+import { z } from "zod";
+export const NativeBrowserEndpointSchema = z
+    .object({
+    version: z.literal(1),
+    pid: z.number().int().positive(),
+    instance: z.uuid(),
+    pane: z
+        .string()
+        .regex(/^%[0-9]+$/u)
+        .max(32),
+    socket: z.string().min(1).max(1024).refine(isAbsolute),
+})
+    .strict();
+export class NativeBrowserUnavailable extends Error {
+    constructor() {
+        super("Native browser controls are unavailable");
+    }
+}
+const responseSchema = z.discriminatedUnion("ok", [
+    z
+        .object({ id: z.string(), ok: z.literal(true), data: NativeBrowserStateSchemaZ.nullable() })
+        .strict(),
+    z.object({ id: z.string(), ok: z.literal(false), error: z.string().max(4096) }).strict(),
+]);
+/** One request, one bounded response. Mutations are never retried or refreshed. */
+export async function nativeBrowserRpc(endpoint, command, signal) {
+    const target = NativeBrowserEndpointSchema.parse(endpoint);
+    const payload = command ? NativeBrowserCommandSchemaZ.parse(command) : null;
+    if (payload && (payload.instance !== target.instance || payload.pane !== target.pane))
+        throw new NativeBrowserUnavailable();
+    signal.throwIfAborted();
+    const info = await lstat(target.socket);
+    if (!info.isSocket() || info.uid !== process.getuid?.() || (info.mode & 0o022) !== 0)
+        throw new NativeBrowserUnavailable();
+    try {
+        process.kill(target.pid, 0);
+    }
+    catch {
+        throw new NativeBrowserUnavailable();
+    }
+    signal.throwIfAborted();
+    const id = randomUUID();
+    const request = JSON.stringify({
+        id,
+        cmd: payload ? "native/1/command" : "native/1/state",
+        ...(payload ? { payload } : {}),
+    }) + "\n";
+    return new Promise((resolve, reject) => {
+        const socket = connect(target.socket);
+        let finished = false;
+        let size = 0;
+        const chunks = [];
+        const finish = (error, state = null) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve(state);
+        };
+        const abort = () => finish(new NativeBrowserUnavailable());
+        const timer = setTimeout(abort, 1500);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted) {
+            abort();
+            return;
+        }
+        socket.once("connect", () => socket.write(request));
+        socket.on("error", abort);
+        socket.once("end", () => {
+            if (!finished)
+                abort();
+        });
+        socket.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > 128 * 1024) {
+                abort();
+                return;
+            }
+            chunks.push(chunk);
+            if (!chunk.includes(10))
+                return;
+            try {
+                const bytes = Buffer.concat(chunks);
+                const newline = bytes.indexOf(10);
+                if (newline !== bytes.length - 1)
+                    throw new NativeBrowserUnavailable();
+                const reply = responseSchema.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, newline))));
+                if (reply.id !== id || !reply.ok)
+                    throw new NativeBrowserUnavailable();
+                if (reply.data &&
+                    (reply.data.instance !== target.instance || reply.data.pane !== target.pane))
+                    throw new NativeBrowserUnavailable();
+                finish(undefined, reply.data);
+            }
+            catch {
+                abort();
+            }
+        });
+    });
+}

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.
  */