tmux-ide 2.9.14 → 2.9.16

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

@@ -1,5 +1,6 @@
 import { accessSync, constants, realpathSync, statSync } from "node:fs";
 import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
 import { IdeError } from "./lib/errors.ts";
 import { resolveRuntimeNamespace, runtimeNamespaceEnvironment } from "./lib/runtime-namespace.ts";
 import {
@@ -16,14 +17,40 @@ export interface OpenBrowserOptions {
 }
 
 /** Resolve once before creating a pane; ignore relative PATH entries. */
-export function resolveTerminalBrowser(environment: NodeJS.ProcessEnv = process.env): string {
+export function resolveTerminalBrowser(
+  environment: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
   const configured = environment.TMUX_IDE_TERMINAL_BROWSER_BIN;
+  const home = environment.HOME ?? homedir();
+  // Resolve the managed alias on every invocation so an app update selects its
+  // matching browser. Native assets remain outside the universal npm package.
+  const bundled =
+    platform === "darwin" && isAbsolute(home)
+      ? [
+          join(
+            home,
+            "Library",
+            "Application Support",
+            "tmux-ide",
+            "native-alpha",
+            "TmuxIDE.app",
+            "Contents",
+            "Resources",
+            "browser",
+            "terminal-browser",
+          ),
+        ]
+      : [];
   const candidates = configured
     ? [configured]
-    : (environment.PATH ?? "")
-        .split(delimiter)
-        .filter(isAbsolute)
-        .map((dir) => join(dir, "terminal-browser"));
+    : [
+        ...bundled,
+        ...(environment.PATH ?? "")
+          .split(delimiter)
+          .filter(isAbsolute)
+          .map((dir) => join(dir, "terminal-browser")),
+      ];
   for (const candidate of candidates) {
     try {
       if (!isAbsolute(candidate)) continue;
@@ -88,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,
@@ -193,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();
@@ -203,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,
+  });
+}

package/skill/SKILL.md

@@ -1,8 +1,13 @@
+---
+name: tmux-ide
+description: "Use tmux-ide from a coding agent to report your own working/blocked/done status, read the agent fleet, message other panes, restore sessions after a crash, and set up worktrees and workspace layouts."
+---
+
 # tmux-ide — Claude Code Skill
 
 <!-- tmux-ide-skill-version: 2.6.0 -->
 
-tmux-ide is **the open-source workspace for coding agents**, built on tmux. The
+tmux-ide is **the open-source tmux workspace for coding agents**. The
 app (`tmux-ide app`) shows every agent across local and SSH machines with
 ground-truth working/blocked/done status, and drives the live tmux session.
 `tmux-ide adopt` adds the same status to plain tmux clients as tmux chrome: a