tmux-ide 2.9.4 → 2.9.5

package/packages/daemon/src/terminal/mirror/stock-pane-snapshot.ts

@@ -0,0 +1,228 @@
+import type { MirrorPaneEvent } from "./events.ts";
+
+/** Identity of one pane-wide, observed-pause snapshot attempt. */
+export interface StockPaneSnapshotContext {
+  readonly paneId: string;
+  readonly incarnation: number;
+  readonly layoutGeneration: number;
+  readonly participants: readonly object[];
+}
+
+export interface StockPaneSnapshotBatch {
+  readonly participant: object;
+  /** Capture-time metadata only. Live bytes are owned by the transaction. */
+  readonly events: readonly MirrorPaneEvent[];
+}
+
+export type StockPaneSnapshotFailure =
+  | "cancelled"
+  | "context-changed"
+  | "context-unavailable"
+  | "pause-not-observed"
+  | "repaused"
+  | "overflow"
+  | "invalid-snapshot"
+  | "consumer-error";
+
+export type StockPaneSnapshotOutput = "unrelated" | "discarded" | "held" | "invalid" | "live";
+
+/**
+ * Stock control-mode output may overtake a capture reply behind sibling output.
+ * An observed pause is the lower fence for a NOHOOKS capture/cursor/continue
+ * transaction: every subsequent target byte must follow snapshot metadata.
+ *
+ * This object owns only that attempt's delivery contract. It neither sends tmux
+ * commands nor authenticates the snapshot collector. Its caller must prove the
+ * uninterrupted command transaction and retain the connection's collector lease
+ * until cancelled wire work has drained. SessionChannel owns this lifecycle.
+ */
+export class StockPaneSnapshot {
+  static readonly MAX_BYTES = 1024 * 1024;
+  static readonly MAX_CHUNKS = 512;
+
+  private phase: "awaiting-pause" | "buffering" | "publishing" | "committed" | "invalidated" =
+    "awaiting-pause";
+  private failure: StockPaneSnapshotFailure | null = null;
+  private readonly context: StockPaneSnapshotContext;
+  private readonly participants: ReadonlySet<object>;
+  private readonly maxBytes: number;
+  private readonly maxChunks: number;
+  private chunks: Uint8Array[] = [];
+  private bytes = 0;
+
+  constructor(
+    context: StockPaneSnapshotContext,
+    limits: { readonly maxBytes?: number; readonly maxChunks?: number } = {},
+  ) {
+    if (
+      !/^%(?:0|[1-9][0-9]*)$/u.test(context.paneId) ||
+      !Number.isSafeInteger(context.incarnation) ||
+      context.incarnation < 0 ||
+      !Number.isSafeInteger(context.layoutGeneration) ||
+      context.layoutGeneration < 0 ||
+      context.participants.length === 0 ||
+      new Set(context.participants).size !== context.participants.length ||
+      context.participants.some(
+        (participant) => participant === null || typeof participant !== "object",
+      )
+    )
+      throw new TypeError("stock snapshot requires exact pane and participant identities");
+    this.maxBytes = limits.maxBytes ?? StockPaneSnapshot.MAX_BYTES;
+    this.maxChunks = limits.maxChunks ?? StockPaneSnapshot.MAX_CHUNKS;
+    if (
+      !Number.isSafeInteger(this.maxBytes) ||
+      this.maxBytes < 1 ||
+      this.maxBytes > StockPaneSnapshot.MAX_BYTES ||
+      !Number.isSafeInteger(this.maxChunks) ||
+      this.maxChunks < 1 ||
+      this.maxChunks > StockPaneSnapshot.MAX_CHUNKS
+    )
+      throw new RangeError("stock snapshot buffer limits must be positive and bounded");
+    this.context = { ...context, participants: [...context.participants] };
+    this.participants = new Set(this.context.participants);
+  }
+
+  get state() {
+    return this.phase;
+  }
+
+  get failureReason(): StockPaneSnapshotFailure | null {
+    return this.failure;
+  }
+
+  get bufferedBytes(): number {
+    return this.bytes;
+  }
+
+  get bufferedChunks(): number {
+    return this.chunks.length;
+  }
+
+  private matchesContext(context: StockPaneSnapshotContext): boolean {
+    if (this.phase === "invalidated") return false;
+    if (
+      context.paneId !== this.context.paneId ||
+      context.incarnation !== this.context.incarnation ||
+      context.layoutGeneration !== this.context.layoutGeneration ||
+      context.participants.length !== this.participants.size ||
+      new Set(context.participants).size !== this.participants.size ||
+      context.participants.some((participant) => !this.participants.has(participant))
+    ) {
+      this.invalidate("context-changed");
+      return false;
+    }
+    return true;
+  }
+
+  private current(context: StockPaneSnapshotContext): boolean {
+    return this.phase !== "committed" && this.matchesContext(context);
+  }
+
+  private readCurrentContext(read: () => StockPaneSnapshotContext): boolean {
+    try {
+      return this.current(read());
+    } catch {
+      this.invalidate("context-unavailable");
+      return false;
+    }
+  }
+
+  /** Only an actual current connection's pause notification establishes the fence. */
+  observePause(context: StockPaneSnapshotContext): boolean {
+    if (!this.current(context)) return false;
+    if (this.phase !== "awaiting-pause") {
+      this.invalidate("repaused");
+      return false;
+    }
+    this.phase = "buffering";
+    return true;
+  }
+
+  acceptOutput(
+    paneId: string,
+    data: Uint8Array,
+    context: StockPaneSnapshotContext,
+  ): StockPaneSnapshotOutput {
+    if (paneId !== this.context.paneId) return "unrelated";
+    if (!this.matchesContext(context)) return "invalid";
+    if (this.phase === "committed") return "live";
+    // The caller fences all participating feeds before requesting pause. These
+    // bytes precede the observed pause and are represented by the future seed.
+    if (this.phase === "awaiting-pause") return "discarded";
+    if (data.byteLength === 0) return "held";
+    if (this.chunks.length >= this.maxChunks || this.bytes + data.byteLength > this.maxBytes) {
+      this.invalidate("overflow");
+      return "invalid";
+    }
+    this.chunks.push(data.slice());
+    this.bytes += data.byteLength;
+    return "held";
+  }
+
+  /** Revoke future routing even after commit; delivered events cannot be retracted. */
+  invalidate(reason: StockPaneSnapshotFailure = "cancelled"): void {
+    if (this.phase === "invalidated") return;
+    this.phase = "invalidated";
+    this.failure = reason;
+    this.chunks = [];
+    this.bytes = 0;
+  }
+
+  /**
+   * Publish an authenticated snapshot, then replay each retained chunk to every
+   * exact participant. Context is rechecked around callbacks. A callback may
+   * append more output, which joins this same bounded replay before commit.
+   * Failure cannot retract already delivered events: the caller must retire or
+   * reseed participants when false is returned, never release their live feeds.
+   */
+  publish(
+    batches: readonly StockPaneSnapshotBatch[],
+    currentContext: () => StockPaneSnapshotContext,
+    emit: (participant: object, event: MirrorPaneEvent) => void,
+  ): boolean {
+    if (!this.readCurrentContext(currentContext)) return false;
+    if (this.phase !== "buffering") {
+      this.invalidate(this.phase === "awaiting-pause" ? "pause-not-observed" : "invalid-snapshot");
+      return false;
+    }
+    if (
+      batches.length !== this.participants.size ||
+      new Set(batches.map((batch) => batch.participant)).size !== this.participants.size ||
+      batches.some(
+        ({ participant, events }) =>
+          !this.participants.has(participant) ||
+          events.length !== 3 ||
+          events[0]?.type !== "reset" ||
+          events[1]?.type !== "seed" ||
+          events[2]?.type !== "cursor",
+      )
+    ) {
+      this.invalidate("invalid-snapshot");
+      return false;
+    }
+    this.phase = "publishing";
+    const deliver = (participant: object, event: MirrorPaneEvent): boolean => {
+      if (!this.readCurrentContext(currentContext)) return false;
+      try {
+        emit(participant, event);
+      } catch {
+        this.invalidate("consumer-error");
+        return false;
+      }
+      return this.readCurrentContext(currentContext);
+    };
+    for (const { participant, events } of batches)
+      for (const event of events) if (!deliver(participant, event)) return false;
+    for (let index = 0; index < this.chunks.length; index += 1) {
+      const data = this.chunks[index]!;
+      for (const participant of this.context.participants) {
+        // A subscriber cannot mutate the bytes replayed to its siblings.
+        if (!deliver(participant, { type: "delta", data: data.slice() })) return false;
+      }
+    }
+    this.chunks = [];
+    this.bytes = 0;
+    this.phase = "committed";
+    return true;
+  }
+}

package/packages/daemon/src/terminal/session-runtime/causal-cell-ledger.ts

@@ -63,7 +63,7 @@ function colorsEqual(
   );
 }
 
-function cellsEqual(
+export function cellsEqual(
   left: TerminalReplicaSnapshot["grid"][number]["cells"][number] | undefined,
   right: TerminalReplicaSnapshot["grid"][number]["cells"][number] | undefined,
 ): boolean {

package/packages/daemon/src/terminal/session-runtime/registry.ts

@@ -1,3 +1,4 @@
+import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.ts";
 import type { OwnedNativePlanCompletion } from "../../lib/owned-native-interaction-bindings.ts";
 import type {
   NativeBackingIdentity,
@@ -119,14 +120,56 @@ export interface TrustedSessionInventoryCandidate {
   readonly token: object;
 }
 
+interface RuntimeListenerCounts {
+  readonly authority: number;
+  readonly mirrorSubscriptions: number;
+  readonly replicaSubscriptions: number;
+  readonly deliveryConnections: number;
+}
+// Final-disposal observations for owners still held by this runtime/registry.
+// This is not a historical count of owners retired by earlier incarnation changes.
+interface ListenerDisposalSummary {
+  readonly sessions: number;
+  readonly owners: number;
+  readonly failures: number;
+  readonly canonical: number;
+  readonly raw: number;
+  readonly upstream: number;
+  readonly authority: number;
+  readonly consumerHandles: number;
+  readonly deliveryConnections: number;
+  readonly deliverySources: number;
+  readonly pendingDeliverySources: number;
+  readonly pendingSourceCloses: number;
+  readonly pendingDeliveryClients: number;
+}
+const emptyListenerDisposal = (): ListenerDisposalSummary => ({
+  sessions: 0,
+  owners: 0,
+  failures: 0,
+  canonical: 0,
+  raw: 0,
+  upstream: 0,
+  authority: 0,
+  consumerHandles: 0,
+  deliveryConnections: 0,
+  deliverySources: 0,
+  pendingDeliverySources: 0,
+  pendingSourceCloses: 0,
+  pendingDeliveryClients: 0,
+});
+
 export interface SessionRuntimeQualificationSnapshot {
   readonly generation: SessionRuntimeGeneration;
   readonly controlChannels: number;
+  readonly mirrorListeners: ReturnType<MirrorService["qualificationListeners"]>;
+  readonly listenerDisposal: ListenerDisposalSummary | null;
   readonly controllerLeases: number;
   readonly sessions: readonly {
     readonly session: string;
     readonly consumers: number;
     readonly retained: boolean;
+    readonly listeners: RuntimeListenerCounts;
     readonly delivery: TerminalDeliveryMetrics;
     readonly convergence: TerminalDeliveryConvergenceSnapshot;
     readonly replicas: Readonly<Record<string, TerminalReplicaQualificationSnapshot>>;
@@ -272,6 +315,7 @@ export class SessionRuntimeRegistry implements PaneStreamMirror {
   readonly #observability: SessionRuntimeObservability;
   readonly #createTraceCorrelator: (scheduler: SessionRuntimeScheduler) => RuntimeTraceCorrelator;
   readonly #sessions = new Map<string, SessionRuntime>();
+  #listenerDisposal: ListenerDisposalSummary | null = null;
   readonly #proofPrewarmOwnership = new Map<SessionRuntime, { owned: boolean; claims: number }>();
   readonly #trustedInventoryTokens = new WeakMap<
     object,
@@ -310,30 +354,47 @@ export class SessionRuntimeRegistry implements PaneStreamMirror {
       ...(this.#observability.enabled
         ? {
             nowMicros: () => this.#observability.nowMicros(),
-            onInputWrite: (_session, action, startedAtMicros, endedAtMicros, pendingBeforeSend) => {
-              for (const traceId of action.traceIds ?? []) {
-                const trace = this.#observability.beginTrace(
-                  "terminal-input-to-paint",
-                  { generation: this.generation, incarnation: null },
-                  traceId,
-                );
-                this.#observability.recordSpan(
-                  "tmux",
-                  "control-write",
-                  startedAtMicros,
-                  endedAtMicros,
-                  trace,
-                );
-                this.#observability.recordSpan(
-                  "tmux",
-                  pendingBeforeSend === 0
-                    ? "control-queue-empty-at-send"
-                    : "control-queue-nonempty-at-send",
-                  endedAtMicros,
-                  endedAtMicros,
-                  trace,
-                );
-              }
+            captureInputWrite: (session, action, semanticPaneId) => {
+              const runtime = this.#sessions.get(session);
+              const binding = runtime?.captureInputDispatch(semanticPaneId);
+              return (startedAtMicros, endedAtMicros, pendingBeforeSend, paneCurrent) => {
+                const incarnation =
+                  paneCurrent && this.#sessions.get(session) === runtime
+                    ? (binding?.() ?? null)
+                    : null;
+                for (const traceId of action.traceIds ?? []) {
+                  const trace = this.#observability.beginTrace(
+                    "terminal-input-to-paint",
+                    {
+                      generation: this.generation,
+                      incarnation,
+                      controlDispatch: Object.freeze({
+                        workspaceName: session,
+                        nativePaneId: action.pane,
+                        semanticPaneId: paneCurrent ? semanticPaneId : null,
+                        scope: "dispatch-time" as const,
+                      }),
+                    },
+                    traceId,
+                  );
+                  this.#observability.recordSpan(
+                    "tmux",
+                    "control-write",
+                    startedAtMicros,
+                    endedAtMicros,
+                    trace,
+                  );
+                  this.#observability.recordSpan(
+                    "tmux",
+                    pendingBeforeSend === 0
+                      ? "control-queue-empty-at-send"
+                      : "control-queue-nonempty-at-send",
+                    endedAtMicros,
+                    endedAtMicros,
+                    trace,
+                  );
+                }
+              };
             },
           }
         : {}),
@@ -981,6 +1042,8 @@ export class SessionRuntimeRegistry implements PaneStreamMirror {
     return Object.freeze({
       generation: this.generation,
       controlChannels: this.activeControlChannelCount(),
+      mirrorListeners: this.#mirror.qualificationListeners(),
+      listenerDisposal: this.#listenerDisposal,
       controllerLeases: this.activeControllerLeaseCount(),
       sessions: Object.freeze(
         [...this.#sessions.values()].map((runtime) => runtime.qualificationSnapshot()),
@@ -996,7 +1059,30 @@ export class SessionRuntimeRegistry implements PaneStreamMirror {
       this.#stopExitObserver();
       this.#disposePromise = (async () => {
         await this.#semanticMutations?.dispose();
-        await Promise.allSettled([...this.#sessions.values()].map((runtime) => runtime.dispose()));
+        const runtimes = [...this.#sessions.values()];
+        const results = await Promise.allSettled(runtimes.map((runtime) => runtime.dispose()));
+        const final = { ...emptyListenerDisposal(), sessions: runtimes.length };
+        runtimes.forEach((runtime, index) => {
+          const counts = runtime.listenerDisposal;
+          if (!counts || results[index]?.status === "rejected") final.failures += 1;
+          if (counts)
+            for (const key of [
+              "owners",
+              "failures",
+              "canonical",
+              "raw",
+              "upstream",
+              "authority",
+              "consumerHandles",
+              "deliveryConnections",
+              "deliverySources",
+              "pendingDeliverySources",
+              "pendingSourceCloses",
+              "pendingDeliveryClients",
+            ] as const)
+              final[key] += counts[key];
+        });
+        this.#listenerDisposal = Object.freeze(final);
         this.#sessions.clear();
         this.#proofPrewarmOwnership.clear();
         await this.#mirror.dispose();
@@ -1099,6 +1185,7 @@ export class SessionRuntimeRegistry implements PaneStreamMirror {
 class SessionRuntime {
   readonly #mirror: MirrorService;
   readonly #consumers = new Set<SessionRuntimeConsumerImpl>();
+  listenerDisposal: ListenerDisposalSummary | null = null;
   readonly #consumersByClientId = new Map<string, SessionRuntimeConsumerImpl>();
   readonly #terminalReplicas = new Map<string, SessionRuntimeTerminalReplicaOwner>();
   readonly #terminalReplicaClocks = new Map<string, { epoch: number; revision: number }>();
@@ -1275,11 +1362,44 @@ class SessionRuntime {
     return this.#consumers.size > 0;
   }
 
+  private listenerCounts(): RuntimeListenerCounts {
+    const counts = {
+      authority: this.#authorityListeners.size,
+      mirrorSubscriptions: 0,
+      replicaSubscriptions: 0,
+      deliveryConnections: 0,
+    };
+    for (const consumer of this.#consumers) {
+      const handles = consumer.qualificationListeners();
+      counts.mirrorSubscriptions += handles.mirrorSubscriptions;
+      counts.replicaSubscriptions += handles.replicaSubscriptions;
+      counts.deliveryConnections += handles.deliveryConnections;
+    }
+    return Object.freeze(counts);
+  }
+
+  captureInputDispatch(semanticPaneId: string | null): () => string | null {
+    const owner =
+      this.#disposed || semanticPaneId === null
+        ? undefined
+        : this.#terminalReplicas.get(semanticPaneId);
+    const incarnation = owner?.inputDispatchIncarnation() ?? null;
+    return () =>
+      !this.#disposed &&
+      semanticPaneId !== null &&
+      owner !== undefined &&
+      this.#terminalReplicas.get(semanticPaneId) === owner &&
+      owner.inputDispatchIncarnation() === incarnation
+        ? incarnation
+        : null;
+  }
+
   qualificationSnapshot(): SessionRuntimeQualificationSnapshot["sessions"][number] {
     return Object.freeze({
       session: this.session,
       consumers: this.#consumers.size,
       retained: this.#retention !== null,
+      listeners: this.listenerCounts(),
       delivery: this.#terminalDeliveryHub.metrics(),
       convergence: this.#terminalDeliveryHub.convergenceSnapshot(),
       replicas: Object.freeze(
@@ -1777,8 +1897,10 @@ class SessionRuntime {
             current.epoch += 1;
             this.#terminalReplicaClocks.set(semanticPaneId, current);
           },
-          onFault: () => {
+          onFault: (error) => {
             if (this.#terminalReplicas.get(semanticPaneId) !== candidate) return;
+            if (error instanceof StockCaptureTabUnavailableError)
+              this.#terminalDeliveryHub.failPaneCapture(semanticPaneId, error);
             this.#outputTraces?.clearPane(semanticPaneId);
             this.#terminalReplicas.delete(semanticPaneId);
             this.#restartBarrier = this.#restartBarrier.then(async () => {
@@ -1896,22 +2018,51 @@ class SessionRuntime {
     this.#trustedInventoryRuntimeSessionId = null;
     this.#trustedInventoryEpoch += 1;
     const consumers = [...this.#consumers];
-    await Promise.allSettled(consumers.map((consumer) => consumer.close()));
+    const consumerResults = await Promise.allSettled(consumers.map((consumer) => consumer.close()));
     this.#clearController();
     this.#authority.dispose();
     this.#authorityListeners.clear();
     this.#completedHandoffs.clear();
     this.#releasedLeases.clear();
     this.#outputTraces?.clear();
-    await Promise.allSettled(
-      [...this.#terminalReplicas.values()].map((owner) => owner.dispose("runtime-disposed")),
+    const owners = [...this.#terminalReplicas.values()];
+    const results = await Promise.allSettled(
+      owners.map((owner) => owner.dispose("runtime-disposed")),
     );
+    const final = {
+      ...emptyListenerDisposal(),
+      sessions: 1,
+      owners: owners.length,
+      failures: [...results, ...consumerResults].filter((result) => result.status === "rejected")
+        .length,
+    };
+    for (const owner of owners) {
+      const counts = owner.qualificationSnapshot().listeners;
+      final.canonical += counts.canonical;
+      final.raw += counts.raw;
+      final.upstream += counts.upstream;
+    }
+    for (const consumer of consumers) {
+      const counts = consumer.qualificationListeners();
+      final.failures += counts.closeFailures;
+      final.consumerHandles +=
+        counts.mirrorSubscriptions + counts.replicaSubscriptions + counts.deliveryConnections;
+    }
+    final.authority = this.#authorityListeners.size;
     this.#terminalReplicas.clear();
     await this.#terminalDeliveryHub.close();
     await this.#startPromise?.catch(() => undefined);
     await this.#restartBarrier;
     await this.#retention?.close();
     this.#retention = null;
+    const delivery = this.#terminalDeliveryHub.metrics();
+    final.deliveryConnections = delivery.connections;
+    final.deliverySources = delivery.sourceSubscriptions;
+    final.pendingDeliverySources = delivery.pendingSourceSubscriptions;
+    final.pendingSourceCloses = delivery.pendingSourceCloses;
+    final.pendingDeliveryClients = delivery.pendingClients;
+    final.failures += delivery.sourceCloseFailures;
+    this.listenerDisposal = Object.freeze(final);
   }
 
   #assertConnected(clientId: string): void {
@@ -2218,6 +2369,17 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
     return connection;
   }
 
+  #closeFailures = 0;
+
+  qualificationListeners() {
+    return Object.freeze({
+      closeFailures: this.#closeFailures,
+      mirrorSubscriptions: this.#subscriptions.size,
+      replicaSubscriptions: this.#replicaSubscriptions.size,
+      deliveryConnections: this.#deliveryConnections.size,
+    });
+  }
+
   async close(): Promise<void> {
     if (this.#closed) return;
     this.#closed = true;
@@ -2230,9 +2392,18 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
     // Authority retirement is synchronous. A slow/frozen mirror subscription
     // must never keep controller leases or previously issued handles alive.
     this.#runtime.release(this);
-    await Promise.allSettled(subscriptions.map((subscription) => subscription.close()));
-    await Promise.allSettled(replicaSubscriptions.map((subscription) => subscription.close()));
-    await Promise.allSettled(deliveryConnections.map((connection) => connection.close()));
+    const mirrorResults = await Promise.allSettled(
+      subscriptions.map((subscription) => subscription.close()),
+    );
+    const replicaResults = await Promise.allSettled(
+      replicaSubscriptions.map((subscription) => subscription.close()),
+    );
+    const deliveryResults = await Promise.allSettled(
+      deliveryConnections.map((connection) => connection.close()),
+    );
+    this.#closeFailures += [...mirrorResults, ...replicaResults, ...deliveryResults].filter(
+      (result) => result.status === "rejected",
+    ).length;
   }
 
   #assertOpen(): void {

package/packages/daemon/src/terminal/session-runtime/runtime-observability.ts

@@ -9,6 +9,13 @@ import { z } from "zod";
 export interface SessionRuntimeTraceAuthority {
   readonly generation: SessionRuntimeGeneration;
   readonly incarnation: string | null;
+  /** Current dispatch target only; neither admission authority nor native acceptance. */
+  readonly controlDispatch?: Readonly<{
+    workspaceName: string;
+    nativePaneId: string;
+    semanticPaneId: string | null;
+    scope: "dispatch-time";
+  }>;
 }
 
 export interface SessionRuntimeTraceContext {

package/packages/daemon/src/terminal/session-runtime/stock-capture-fidelity.ts

@@ -0,0 +1,13 @@
+import { STOCK_CAPTURE_TAB_UNAVAILABLE } from "@tmux-ide/contracts";
+
+export class StockCaptureTabUnavailableError extends Error {
+  constructor() {
+    super(STOCK_CAPTURE_TAB_UNAVAILABLE);
+    this.name = "StockCaptureTabUnavailableError";
+  }
+}
+
+/** ANSI capture drops stored tab widths. Live HT is cursor motion, not capture paint. */
+export function assertStockCaptureRepresentable(chunks: readonly Uint8Array[]): void {
+  if (chunks.some((chunk) => chunk.includes(9))) throw new StockCaptureTabUnavailableError();
+}