tmux-ide 2.9.0-beta.19 → 2.9.0-beta.21

package/packages/daemon/src/lib/workspace-promotion.ts

@@ -26,7 +26,7 @@
 import type { WorkspaceAdmissionSnapshot } from "@tmux-ide/contracts";
 
 import { createHash } from "node:crypto";
-import { realpathSync, statSync } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
 
 import {
   WorkspacePromoteMutationRequestSchemaZ,
@@ -36,10 +36,10 @@ import {
   type WorkspacePromoteMutationResult,
   type WorkspacePromotedResource,
 } from "@tmux-ide/contracts";
-import { TmuxError } from "@tmux-ide/tmux-bridge";
+import { classifyTmuxError, TmuxError } from "@tmux-ide/tmux-bridge";
 
 import {
-  createPinnedWorkspaceTmuxRunner,
+  createPinnedWorkspaceTmuxAsyncRunner,
   resolveWorkspacePaneTmuxAuthority,
   type WorkspacePaneTmuxAuthority,
 } from "./workspace-pane-creation.ts";
@@ -169,9 +169,16 @@ interface WorkspacePromotionRegistry {
   add(input: AddWorkspaceInput): Workspace;
 }
 
+/**
+ * Promotion io. `runTmux` and `canonicalProjectDir` may answer synchronously
+ * (unit fixtures) or asynchronously (the daemon default): the authority awaits
+ * both so the many tmux round-trips a multi-pane promotion performs never run
+ * on the daemon event loop synchronously, which would stall every other
+ * connected client for the whole promotion.
+ */
 export interface WorkspacePromotionIo {
-  readonly runTmux: (args: readonly string[]) => string;
-  readonly canonicalProjectDir: (path: string) => string;
+  readonly runTmux: (args: readonly string[]) => string | Promise<string>;
+  readonly canonicalProjectDir: (path: string) => string | Promise<string>;
   readonly isMissingTmuxTarget: (error: unknown) => boolean;
   readonly isTmuxUnavailable: (error: unknown) => boolean;
   readonly now: () => number;
@@ -411,10 +418,29 @@ function requestFingerprint(request: WorkspacePromoteMutationRequest): string {
   return JSON.stringify(request);
 }
 
+/**
+ * The daemon's pinned async runner keeps every promotion round-trip off the
+ * event loop; it surfaces raw child-process failures, so classify them here
+ * into the shared `TmuxError` codes the io predicates below inspect.
+ */
+function classifiedAsyncRunner(
+  tmuxAuthority: WorkspacePaneTmuxAuthority | undefined,
+): (args: readonly string[]) => Promise<string> {
+  const run = createPinnedWorkspaceTmuxAsyncRunner(
+    tmuxAuthority ?? resolveWorkspacePaneTmuxAuthority(),
+  );
+  return (args) =>
+    run(args).catch((error: unknown) => {
+      throw error instanceof TmuxError ? error : classifyTmuxError(error);
+    });
+}
+
 const DEFAULT_IO: Omit<WorkspacePromotionIo, "runTmux"> = {
-  canonicalProjectDir: (path) => {
-    const canonical = realpathSync(path);
-    if (!statSync(canonical).isDirectory()) throw new Error("project root is not a directory");
+  canonicalProjectDir: async (path) => {
+    const canonical = await realpath(path);
+    if (!(await stat(canonical)).isDirectory()) {
+      throw new Error("project root is not a directory");
+    }
     return canonical;
   },
   isMissingTmuxTarget: (error) => error instanceof TmuxError && error.code === "SESSION_NOT_FOUND",
@@ -462,11 +488,7 @@ export class WorkspacePromotionAuthority {
     this.#io = {
       ...DEFAULT_IO,
       ...options.io,
-      runTmux:
-        options.io?.runTmux ??
-        createPinnedWorkspaceTmuxRunner(
-          options.tmuxAuthority ?? resolveWorkspacePaneTmuxAuthority(),
-        ),
+      runTmux: options.io?.runTmux ?? classifiedAsyncRunner(options.tmuxAuthority),
     };
     this.#maxReplayOperations = boundedAuthorityLimit(options.maxOperations, MAX_OPERATIONS);
     this.#maxPendingOperations = boundedAuthorityLimit(
@@ -532,7 +554,7 @@ export class WorkspacePromotionAuthority {
     if (existing) return this.#replay(existing, request, fingerprint);
 
     try {
-      const session = this.#resolveSession(request.intent.sessionId);
+      const session = await this.#resolveSession(request.intent.sessionId);
 
       // Already a registry workspace — including an app-created (m32) session —
       // is idempotent, not an error. It is NOT automatically attachable though:
@@ -551,10 +573,10 @@ export class WorkspacePromotionAuthority {
           workspaceName: alreadyRegistered.name,
           sessionName: session.sessionName,
         };
-        this.#stampPaneInventory(request, session, registeredIdentity);
+        await this.#stampPaneInventory(request, session, registeredIdentity);
         this.#assertActive(request.operationId);
-        this.#verifyPromotedInventory(session.sessionId, registeredIdentity);
-        this.#publishFleetEnrollment(request, session, registeredIdentity);
+        await this.#verifyPromotedInventory(session.sessionId, registeredIdentity);
+        await this.#publishFleetEnrollment(request, session, registeredIdentity);
         return this.#succeed(request, fingerprint, alreadyRegistered.name, session.sessionName, {
           replayed: true,
         });
@@ -563,10 +585,10 @@ export class WorkspacePromotionAuthority {
       const identity = derivePromotionIdentity(session.sessionName);
       this.#assertConflictFreeIdentity(identity);
 
-      const canonicalRoot = this.#stampSession(request, session, identity);
+      const canonicalRoot = await this.#stampSession(request, session, identity);
       this.#assertActive(request.operationId);
-      this.#verifyPromotedInventory(session.sessionId, identity);
-      this.#publishFleetEnrollment(request, session, identity);
+      await this.#verifyPromotedInventory(session.sessionId, identity);
+      await this.#publishFleetEnrollment(request, session, identity);
 
       let registered: Workspace;
       try {
@@ -605,8 +627,8 @@ export class WorkspacePromotionAuthority {
     }
   }
 
-  #resolveSession(sessionId: string): SessionRecord {
-    const records = this.#listSessions();
+  async #resolveSession(sessionId: string): Promise<SessionRecord> {
+    const records = await this.#listSessions();
     const matches = records.filter(
       (record) => fleetSessionIdForName(record.sessionName) === sessionId,
     );
@@ -620,9 +642,9 @@ export class WorkspacePromotionAuthority {
     return match;
   }
 
-  #listSessions(): SessionRecord[] {
+  async #listSessions(): Promise<SessionRecord[]> {
     try {
-      return parseSessionRecords(this.#io.runTmux(["list-sessions", "-F", SESSION_FORMAT]));
+      return parseSessionRecords(await this.#io.runTmux(["list-sessions", "-F", SESSION_FORMAT]));
     } catch (error) {
       if (this.#io.isTmuxUnavailable(error)) return [];
       throw error;
@@ -648,14 +670,14 @@ export class WorkspacePromotionAuthority {
    * a newly published marker makes the soon-to-be registered workspace visible
    * to the shared FleetCatalog in the same mutation transaction.
    */
-  #publishFleetEnrollment(
+  async #publishFleetEnrollment(
     request: WorkspacePromoteMutationRequest,
     session: SessionRecord,
     identity: PromotionIdentity,
-  ): void {
+  ): Promise<void> {
     if (session.adopted) return;
     try {
-      this.#io.runTmux(["set-option", "-t", session.sessionId, ADOPTED_OPTION, "1"]);
+      await this.#io.runTmux(["set-option", "-t", session.sessionId, ADOPTED_OPTION, "1"]);
     } catch (error) {
       throw new WorkspacePromotionError(
         "stamp_failed",
@@ -671,19 +693,19 @@ export class WorkspacePromotionAuthority {
    * `set-option` failure maps to `stamp_failed`; the caller has not yet touched
    * the registry, so a failure here leaves the session harmless.
    */
-  #stampSession(
+  async #stampSession(
     request: WorkspacePromoteMutationRequest,
     session: SessionRecord,
     identity: PromotionIdentity,
-  ): string {
-    const scanned = this.#stampPaneInventory(request, session, identity);
+  ): Promise<string> {
+    const scanned = await this.#stampPaneInventory(request, session, identity);
     try {
       for (const [option, value] of [
         [SESSION_OPERATION_OPTION, request.operationId],
         [SESSION_WORKSPACE_OPTION, identity.workspaceName],
         [SESSION_PROMOTED_MARKER_OPTION, "1"],
       ] as const) {
-        this.#io.runTmux(["set-option", "-t", session.sessionId, option, value]);
+        await this.#io.runTmux(["set-option", "-t", session.sessionId, option, value]);
       }
     } catch (error) {
       throw new WorkspacePromotionError(
@@ -693,7 +715,7 @@ export class WorkspacePromotionAuthority {
       );
     }
 
-    return this.#resolveProjectDir(session, scanned);
+    return await this.#resolveProjectDir(session, scanned);
   }
 
   /**
@@ -703,15 +725,22 @@ export class WorkspacePromotionAuthority {
    * session, which may be an m32-open workspace whose provenance must never
    * acquire the promotion marker.
    */
-  #stampPaneInventory(
+  async #stampPaneInventory(
     request: WorkspacePromoteMutationRequest,
     session: SessionRecord,
     identity: PromotionIdentity,
-  ): ScanPane[] {
+  ): Promise<ScanPane[]> {
     let scanned: ScanPane[];
     try {
       scanned = parseScanPanes(
-        this.#io.runTmux(["list-panes", "-s", "-t", session.sessionId, "-F", PANE_SCAN_FORMAT]),
+        await this.#io.runTmux([
+          "list-panes",
+          "-s",
+          "-t",
+          session.sessionId,
+          "-F",
+          PANE_SCAN_FORMAT,
+        ]),
       );
     } catch (error) {
       if (error instanceof WorkspacePromotionError) throw error;
@@ -734,7 +763,7 @@ export class WorkspacePromotionAuthority {
       for (const pane of scanned) {
         if (!hasValidPaneStamp(pane.semanticPaneId)) {
           const paneStamp = `pane.promoted.${digest(`${session.sessionName}\0${pane.paneId}`)}`;
-          this.#io.runTmux([
+          await this.#io.runTmux([
             "set-option",
             "-p",
             "-t",
@@ -745,14 +774,14 @@ export class WorkspacePromotionAuthority {
           for (const [option, value] of this.#ideDefaults(pane, nowSec)) {
             // Additive: only fill an empty `@ide_*`, never clobber existing intent.
             if (value === null) continue;
-            this.#io.runTmux(["set-option", "-p", "-t", pane.paneId, option, value]);
+            await this.#io.runTmux(["set-option", "-p", "-t", pane.paneId, option, value]);
           }
         }
         if (!reconciledWindows.has(pane.windowId)) {
           reconciledWindows.add(pane.windowId);
           if (pane.semanticWindowId.length === 0) {
             const windowStamp = `window.promoted.${digest(`${session.sessionName}\0${pane.windowId}`)}`;
-            this.#io.runTmux([
+            await this.#io.runTmux([
               "set-option",
               "-w",
               "-t",
@@ -763,7 +792,7 @@ export class WorkspacePromotionAuthority {
             // Initialize chrome only when adopting a previously unstamped
             // window. Reopening an existing workspace must preserve native
             // border choices and PTY dimensions, even while stamping new panes.
-            this.#io.runTmux([
+            await this.#io.runTmux([
               "set-option",
               "-w",
               "-t",
@@ -771,7 +800,7 @@ export class WorkspacePromotionAuthority {
               "pane-border-status",
               "top",
             ]);
-            this.#io.runTmux([
+            await this.#io.runTmux([
               "set-option",
               "-w",
               "-t",
@@ -803,7 +832,7 @@ export class WorkspacePromotionAuthority {
    *   (b) then the active pane's cwd, then the remaining panes in scan order;
    *   (c) only when NOTHING resolves does promotion fail.
    */
-  #resolveProjectDir(session: SessionRecord, scanned: readonly ScanPane[]): string {
+  async #resolveProjectDir(session: SessionRecord, scanned: readonly ScanPane[]): Promise<string> {
     const active = scanned.find((pane) => pane.active);
     const candidates = [
       session.sessionPath,
@@ -813,7 +842,7 @@ export class WorkspacePromotionAuthority {
     for (const candidate of candidates) {
       if (candidate.length === 0) continue;
       try {
-        return this.#io.canonicalProjectDir(candidate);
+        return await this.#io.canonicalProjectDir(candidate);
       } catch {
         // A dead or non-directory cwd (a pruned worktree) is expected; try the
         // next candidate rather than failing the whole promotion.
@@ -866,12 +895,12 @@ export class WorkspacePromotionAuthority {
    * initial-Terminal-window assertion — a promoted session may have any number
    * of windows and multi-pane windows.
    */
-  #verifyPromotedInventory(sessionId: string, identity: PromotionIdentity): void {
+  async #verifyPromotedInventory(sessionId: string, identity: PromotionIdentity): Promise<void> {
     let panes: VerifyPane[];
     try {
       const args = ["list-panes", "-s", "-t", sessionId, "-F", PANE_VERIFY_FORMAT] as const;
-      const before = boundedTmuxOutput(this.#io.runTmux(args));
-      const after = boundedTmuxOutput(this.#io.runTmux(args));
+      const before = boundedTmuxOutput(await this.#io.runTmux(args));
+      const after = boundedTmuxOutput(await this.#io.runTmux(args));
       if (before !== after) {
         throw new WorkspacePromotionError("promotion_verification_failed", {
           reason: "inventory_changed_during_proof",

package/packages/daemon/src/terminal/mirror/session-channel.ts

@@ -1,3 +1,4 @@
+import { boundedTmuxInteractionAppendCommand } from "../../lib/tmux-interaction-retention.ts";
 import {
   decodeNativeGridCapture,
   isNativeBootstrapCapture,
@@ -1853,7 +1854,7 @@ export class SessionChannel {
     const sentinel = (kind: string): string =>
       `display-message -p -l -t ${pane.runtimeId} ` + `"%tmux-ide-atomic-v1 ${nonce} ${kind}"`;
     const observerCommands =
-      ` ; set-buffer -a -b ${observer!.bufferName} ${tmuxSingleQuote(observer!.record)}` +
+      ` ; ${boundedTmuxInteractionAppendCommand(observer!.bufferName, observer!.record)}` +
       ` ; wait-for -S ${observer!.signalChannel}`;
     const body =
       `set-option -po -t ${pane.runtimeId} ${INTERNAL_READ_OPERATION_OPTION} ${internalReadMarker}` +

package/packages/daemon/src/tui/mirror/automatic-contrast.ts

@@ -0,0 +1,180 @@
+/** Quantized sRGB contrast; Oklab matrices: https://bottosson.github.io/posts/oklab/ . */
+const LINEAR = Float64Array.from({ length: 256 }, (_, n) => {
+  const c = n / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+});
+const luminance = (rgb: number): number =>
+  0.2126 * LINEAR[(rgb >>> 16) & 255]! +
+  0.7152 * LINEAR[(rgb >>> 8) & 255]! +
+  0.0722 * LINEAR[rgb & 255]!;
+export function packedContrastRatio(a: number, b: number): number {
+  const x = luminance(a) + 0.05,
+    y = luminance(b) + 0.05;
+  return Math.max(x, y) / Math.min(x, y);
+}
+function byte(c: number): number {
+  return Math.round(
+    Math.max(0, Math.min(1, c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055)) * 255,
+  );
+}
+function candidate(L: number, a: number, b: number): number {
+  // Reduce chroma along the same hue ray until inside sRGB, then quantize.
+  let lo = 0,
+    hi = 1,
+    result = -1;
+  for (let i = 0; i < 10; i++) {
+    const scale = i === 0 ? 1 : (lo + hi) / 2;
+    const l = (L + 0.3963377774 * a * scale + 0.2158037573 * b * scale) ** 3;
+    const m = (L - 0.1055613458 * a * scale - 0.0638541728 * b * scale) ** 3;
+    const s = (L - 0.0894841775 * a * scale - 1.291485548 * b * scale) ** 3;
+    const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+    const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+    const blue = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+    if (Math.min(r, g, blue) >= 0 && Math.max(r, g, blue) <= 1) {
+      result = (byte(r) << 16) | (byte(g) << 8) | byte(blue);
+      if (i === 0) return result;
+      lo = scale;
+    } else hi = scale;
+  }
+  return result < 0 ? byte(L ** 3) * 0x10101 : result;
+}
+/** Leave passing pairs exact. Search both lightness directions with a verified endpoint fallback. */
+export function correctContrastForeground(fg: number, bg: number): number {
+  if (packedContrastRatio(fg, bg) >= 4.5) return fg;
+  const r = LINEAR[(fg >>> 16) & 255]!,
+    g = LINEAR[(fg >>> 8) & 255]!,
+    b = LINEAR[fg & 255]!;
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const bb = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  let best = 0,
+    distance = Infinity;
+  for (const end of [0, 1]) {
+    let passing = end,
+      failing = L;
+    let rgb = end === 0 ? 0 : 0xffffff;
+    if (packedContrastRatio(rgb, bg) < 4.5) continue;
+    for (let i = 0; i < 12; i++) {
+      const mid = (passing + failing) / 2;
+      const trial = candidate(mid, a, bb);
+      if (packedContrastRatio(trial, bg) >= 4.5) {
+        passing = mid;
+        rgb = trial;
+      } else failing = mid;
+    }
+    if (Math.abs(passing - L) < distance) {
+      best = rgb;
+      distance = Math.abs(passing - L);
+    }
+  }
+  return best;
+}
+
+/** Cheap high-color-churn fallback: linear-sRGB blend to the nearer passing endpoint. */
+export function fastContrastForeground(fg: number, bg: number): number {
+  if (packedContrastRatio(fg, bg) >= 4.5) return fg;
+  const y = luminance(fg),
+    base = luminance(bg);
+  const darkTarget = (base + 0.05) / 4.5 - 0.05;
+  const lightTarget = (base + 0.05) * 4.5 - 0.05;
+  const darkMix = darkTarget >= 0 ? (y - darkTarget) / y : Infinity;
+  const lightMix = lightTarget <= 1 ? (lightTarget - y) / (1 - y) : Infinity;
+  const end = darkMix <= lightMix ? 0 : 1;
+  // A small quantization margin usually avoids endpoint fallback. Always verify.
+  const amount = Math.min(1, Math.max(0, Math.min(darkMix, lightMix)) + 0.012);
+  const r = LINEAR[(fg >>> 16) & 255]!,
+    g = LINEAR[(fg >>> 8) & 255]!,
+    b = LINEAR[fg & 255]!;
+  const result =
+    (byte(r + (end - r) * amount) << 16) |
+    (byte(g + (end - g) * amount) << 8) |
+    byte(b + (end - b) * amount);
+  return packedContrastRatio(result, bg) >= 4.5 ? result : end === 0 ? 0 : 0xffffff;
+}
+
+export function createContrastPairCache(limit = 4096) {
+  const pairs = new Map<number, number>();
+  let remaining = Infinity;
+  return {
+    beginFrame() {
+      remaining = 128;
+    },
+    get size() {
+      return pairs.size;
+    },
+    correct(fg: number, bg: number): number {
+      const key = fg * 0x1000000 + bg;
+      const cached = pairs.get(key);
+      if (cached !== undefined) return cached;
+      const corrected =
+        packedContrastRatio(fg, bg) >= 4.5
+          ? fg
+          : remaining-- > 0
+            ? correctContrastForeground(fg, bg)
+            : fastContrastForeground(fg, bg);
+      if (pairs.size >= limit) pairs.clear();
+      pairs.set(key, corrected);
+      return corrected;
+    },
+  };
+}
+
+export interface ContrastBuffer {
+  readonly buffers: {
+    char: Uint32Array;
+    fg: Uint16Array;
+    bg: Uint16Array;
+    attributes: Uint32Array;
+  };
+}
+const read = (c: Uint16Array, i: number) =>
+  ((c[i]! & 255) << 16) | ((c[i + 1]! & 255) << 8) | (c[i + 2]! & 255);
+/** Final composed surface only: no canonical state or scheduling; allocation-free cache hits. */
+export function createAutomaticContrastPass() {
+  const cache = createContrastPairCache();
+  return (buffer: ContrastBuffer): void => {
+    cache.beginFrame();
+    const { char, fg, bg, attributes } = buffer.buffers;
+    for (let cell = 0; cell < char.length; cell++) {
+      const cp = char[cell]!,
+        attr = attributes[cell]!,
+        i = cell * 4;
+      // Preserve concealment, whitespace and pixel-art coverage. Grapheme IDs and
+      // wide continuations are opaque and retained byte-for-byte.
+      if (
+        attr & 64 ||
+        cp === 0 ||
+        cp === 32 ||
+        cp === 160 ||
+        (cp >= 0x2580 && cp <= 0x259f) ||
+        (cp >= 0x2800 && cp <= 0x28ff)
+      )
+        continue;
+      if ((fg[i + 3]! & 255) !== 255 || (bg[i + 3]! & 255) !== 255) continue;
+      const foreground = attr & 32 ? bg : fg;
+      const background = attr & 32 ? fg : bg;
+      const original = read(foreground, i);
+      const base = read(background, i);
+      // DIM is emulator-dependent. Materialize a deterministic 50% sRGB blend
+      // before correction and clear only the final composed DIM bit.
+      let visible = original;
+      if (attr & 2) {
+        visible =
+          (Math.round(((original >>> 16) + (base >>> 16)) / 2) << 16) |
+          (Math.round((((original >>> 8) & 255) + ((base >>> 8) & 255)) / 2) << 8) |
+          Math.round(((original & 255) + (base & 255)) / 2);
+        attributes[cell] = attr & ~2;
+      }
+      const corrected = cache.correct(visible, base);
+      if (corrected === original && !(attr & 2)) continue;
+      // RGB intent is zero. Indexed/default metadata must not override correction.
+      foreground[i] = corrected >>> 16;
+      foreground[i + 1] = (corrected >>> 8) & 255;
+      foreground[i + 2] = corrected & 255;
+      foreground[i + 3] = 255;
+    }
+  };
+}

package/packages/daemon/src/tui/mirror/open-tui-workspace-runtime-port.ts

@@ -155,7 +155,11 @@ export interface OpenTuiWorkspaceRuntimePort extends WorkspaceClientRuntimePort<
   getLayout(): OpenTuiWorkspaceLayout | null;
   getLayoutSnapshot(): OpenTuiWorkspaceLayoutSnapshot;
   onLayout(listener: (layout: OpenTuiWorkspaceLayoutSnapshot) => void): () => void;
-  fitViewport(cols: number, rows: number): Promise<"ok" | "geometry-authority-conflict">;
+  fitViewport(
+    cols: number,
+    rows: number,
+    semanticWindowId?: string,
+  ): Promise<"ok" | "geometry-authority-conflict">;
 }
 
 export interface ConnectOpenTuiWorkspaceRuntimePortOptions {
@@ -1395,8 +1399,17 @@ export async function connectOpenTuiWorkspaceRuntimePort(
       }
     }) ?? null;
   type FitResult = "ok" | "geometry-authority-conflict";
-  let pendingInitialFit: { cols: number; rows: number; result: Promise<FitResult> } | null = null;
-  const fitViewport = (cols: number, rows: number): Promise<FitResult> => {
+  let pendingInitialFit: {
+    cols: number;
+    rows: number;
+    semanticWindowId?: string;
+    result: Promise<FitResult>;
+  } | null = null;
+  const fitViewport = (
+    cols: number,
+    rows: number,
+    semanticWindowId?: string,
+  ): Promise<FitResult> => {
     if (closed) return Promise.resolve("geometry-authority-conflict");
     // Keep only the latest requested geometry while hidden seeds arrive. All
     // callers share one wait; resize storms cannot accumulate deferred work.
@@ -1404,23 +1417,31 @@ export async function connectOpenTuiWorkspaceRuntimePort(
       if (pendingInitialFit) {
         pendingInitialFit.cols = cols;
         pendingInitialFit.rows = rows;
+        pendingInitialFit.semanticWindowId = semanticWindowId;
         return pendingInitialFit.result;
       }
       const request = {
         cols,
         rows,
+        semanticWindowId,
         result: Promise.resolve<FitResult>("geometry-authority-conflict"),
       };
       pendingInitialFit = request;
       request.result = allSeeds.then((ready) => {
         pendingInitialFit = null;
-        return ready ? fitViewport(request.cols, request.rows) : "geometry-authority-conflict";
+        return ready
+          ? fitViewport(request.cols, request.rows, request.semanticWindowId)
+          : "geometry-authority-conflict";
       });
       return request.result;
     }
     if ([...endpoints.values()].some((endpoint) => !endpoint.inputReady))
       return Promise.resolve("geometry-authority-conflict");
-    return opened.fitViewport(cols, rows).catch((error: unknown) => {
+    return (
+      semanticWindowId === undefined
+        ? opened.fitViewport(cols, rows)
+        : opened.fitViewport(cols, rows, semanticWindowId)
+    ).catch((error: unknown) => {
       if (error instanceof PaneStreamOperationError && error.code === "authority-rejected")
         return "geometry-authority-conflict" as const;
       throw error;

package/packages/daemon/src/tui/mirror/pane-surface.tsx

@@ -164,9 +164,8 @@ export interface PaneSurfaceOptions extends RenderableOptions<FrameBufferRendera
   /** Bumps when canonical presentation changed without terminal cell damage. */
   presentationVersion?: number;
   /**
-   * Renderer-owned framebuffer generation. Unlike `contentVersion`, this
-   * changes when retained canonical cells are still current but the native
-   * presentation may have been invalidated by composition or visibility.
+   * Renderer-owned composition generation. Retained framebuffer cells survive
+   * visibility and position changes; the hardware cursor must be re-presented.
    */
   presentationGeneration?: string;
   /** Retained-source generation; forces a full blit even when content version restarts equal. */
@@ -641,11 +640,11 @@ class PaneSurfaceRenderable extends FrameBufferRenderable {
   set presentationGeneration(v: string) {
     if (v === this._presentationGeneration) return;
     this._presentationGeneration = v;
-    // Framebuffer validity is independent from terminal content freshness. A
-    // quiet pane must be able to repaint its retained canonical snapshot after
-    // visibility/composition changes without waiting for another terminal byte.
-    this._forceFull = true;
-    this.invalidate();
+    // Composition reuses the retained framebuffer. Geometry reallocation,
+    // source replacement and palette changes independently force a full walk.
+    // Reclaim the hardware cursor at the new absolute position on visibility.
+    this._needsCursorPresentation = true;
+    this.requestRender();
   }
   set sourceEpoch(v: number) {
     if (v === this._sourceEpoch) return;
@@ -668,6 +667,8 @@ class PaneSurfaceRenderable extends FrameBufferRenderable {
       // Detailed focus correlation never owns renderer replacement.
     }
     this._rendererEpoch = v;
+    this._forceFull = true;
+    this.invalidate();
   }
   set hostFocusTransitionOwner(v: PaneSurfaceHostFocusTransitionOwner | null | undefined) {
     if (v !== this._hostFocusTransitionOwner) this.cancelPendingFocusTransition();