tmux-ide 2.9.15 → 2.9.17

package/packages/daemon/src/lib/tmux-server-owners.ts

@@ -59,6 +59,8 @@ export class TmuxServerOwners<T extends DisposableTmuxServerOwner> {
   #disposed = false;
   #disposePromise: Promise<void> | null = null;
   constructor(readonly options: TmuxServerOwnersOptions<T>) {}
+  #queuedRefresh: Promise<readonly TmuxServerDescriptor[]> | null = null;
+  #queuedRefreshTail: Promise<unknown> | null = null;
   #serial<R>(work: () => Promise<R>): Promise<R> {
     const run = this.#tail.then(() => {
       if (this.#disposed) throw new TmuxServerScopeError("disposed");
@@ -178,11 +180,25 @@ export class TmuxServerOwners<T extends DisposableTmuxServerOwner> {
     this.#entries.set(scope.serverId, { registration, scope, observation, owner });
   }
   refresh(): Promise<readonly TmuxServerDescriptor[]> {
-    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: TmuxServerScope): T {
     const scope = TmuxServerScopeSchemaZ.parse(scopeInput);

package/packages/daemon/src/lib/tui-binary.ts

@@ -43,9 +43,19 @@ 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: Record<string, TuiPlatformTag> = {
   "darwin-arm64": "darwin-arm64",
@@ -162,9 +172,19 @@ interface DownloadLimits {
   readonly minBinaryBytes: number;
   readonly maxCompressedBytes: number;
   readonly maxBinaryBytes: number;
-  readonly timeoutMs: number;
 }
 
+interface DownloadPolicy {
+  readonly stallTimeoutMs: number;
+  readonly deadline: number;
+  readonly totalTimeoutMs: number;
+  readonly maxAttempts: number;
+  readonly retryDelayMs: number;
+}
+
+/** A failure a retry cannot fix: the release asset is missing or breaks a hard limit. */
+class PermanentDownloadError extends Error {}
+
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
 function checksumPath(path: string): string {
@@ -269,36 +289,61 @@ function purgeCachedBinary(path: string): void {
   }
 }
 
+function isTransientHttpStatus(status: number): boolean {
+  return status === 408 || status === 429 || status >= 500;
+}
+
 async function readBoundedResponse(
   fetchImpl: FetchLike,
   url: string,
   maxBytes: number,
-  timeoutMs: number,
+  policy: DownloadPolicy,
 ): Promise<Buffer> {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let total = 0;
+  let timeoutMessage: string | null = null;
+  const abortWith = (message: () => string) => () => {
+    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: Buffer[] = [];
-    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));
       }
@@ -307,12 +352,39 @@ async function readBoundedResponse(
     }
     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: FetchLike,
+  url: string,
+  maxBytes: number,
+  policy: DownloadPolicy,
+  log: (msg: string) => void,
+): Promise<Buffer> {
+  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));
+    }
   }
 }
 
@@ -333,8 +405,11 @@ export async function downloadTuiBinary(
     home?: string;
     tag?: TuiPlatformTag | null;
     fetch?: FetchLike;
-    timeoutMs?: number;
-    limits?: Partial<Omit<DownloadLimits, "timeoutMs">>;
+    stallTimeoutMs?: number;
+    totalTimeoutMs?: number;
+    maxAttempts?: number;
+    retryDelayMs?: number;
+    limits?: Partial<DownloadLimits>;
   } = {},
 ): Promise<{ path: string; bytes: number }> {
   if (resolveRuntimeNamespace().development)
@@ -356,13 +431,17 @@ export async function downloadTuiBinary(
     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 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),
-    limits.timeoutMs * 2 + 5_000,
-  );
+    totalTimeoutMs + TUI_DOWNLOAD_LOCK_MARGIN_MS,
+  ).finally(() => clearTimeout(lockNotice));
   const suffix = `${process.pid}.${randomUUID()}.tmp`;
   const binaryTmp = `${dest}.${suffix}`;
   const checksumTmp = `${checksumPath(dest)}.${suffix}`;
@@ -372,22 +451,35 @@ export async function downloadTuiBinary(
     purgeCachedBinary(dest);
 
     const fetchImpl = opts.fetch ?? globalThis.fetch;
+    // Starts after the lock so the budget matches what a lock waiter allows for.
+    const policy: DownloadPolicy = {
+      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: Buffer;
     let gz: Buffer;
     try {
-      manifestBytes = await readBoundedResponse(
+      manifestBytes = await readWithRetries(
         fetchImpl,
         checksumUrl,
         MAX_CHECKSUM_MANIFEST_BYTES,
-        limits.timeoutMs,
+        policy,
+        log,
       );
-      gz = await readBoundedResponse(fetchImpl, url, limits.maxCompressedBytes, limits.timeoutMs);
+      log(`downloading ${url}`);
+      gz = await readWithRetries(fetchImpl, url, limits.maxCompressedBytes, policy, log);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(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}). ` +
-          `Check that the release published both exact-version assets.`,
+        `could not download the TUI binary and checksum for v${version} (${message}). ${hint}`,
         { cause: error },
       );
     }

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

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