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

package/packages/daemon/src/lib/terminal-host-color.ts

@@ -0,0 +1,43 @@
+import type { RendererNeutralColor } from "@tmux-ide/contracts";
+import type { ResolvedThemeMode } from "./theme-mode.ts";
+
+function color(red: number, green: number, blue: number): RendererNeutralColor {
+  return { space: "srgb", red, green, blue, alpha: 255 };
+}
+
+export function parseTerminalHostColor(
+  value: string | null | undefined,
+): RendererNeutralColor | null {
+  if (!value) return null;
+  const normalized = value.trim().toLowerCase();
+  const hex = /^#([\da-f]{3}|[\da-f]{6})$/u.exec(normalized)?.[1];
+  if (hex) {
+    const expanded =
+      hex.length === 3 ? `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}` : hex;
+    return color(
+      Number.parseInt(expanded.slice(0, 2), 16),
+      Number.parseInt(expanded.slice(2, 4), 16),
+      Number.parseInt(expanded.slice(4, 6), 16),
+    );
+  }
+  // OSC palette replies may use X11's rgb:RR/GG/BB form with one to four
+  // hexadecimal digits per channel. Scale each channel to a byte rather than
+  // truncating high-fidelity replies.
+  const x11 = /^rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})$/u.exec(normalized);
+  if (!x11) return null;
+  const channel = (part: string): number => {
+    const maximum = 16 ** part.length - 1;
+    return Math.round((Number.parseInt(part, 16) / maximum) * 255);
+  };
+  return color(channel(x11[1]!), channel(x11[2]!), channel(x11[3]!));
+}
+
+/** Only a reported default background determines host appearance. */
+export function terminalHostMode(background: string | null | undefined): ResolvedThemeMode | null {
+  const value = parseTerminalHostColor(background);
+  return value
+    ? 0.299 * value.red + 0.587 * value.green + 0.114 * value.blue > 127.5
+      ? "light"
+      : "dark"
+    : null;
+}

package/packages/daemon/src/lib/tmux-external-interaction-observer.ts

@@ -3,6 +3,13 @@ import { execFile } from "node:child_process";
 import { WorkspacePaneCreationReferenceSchemaZ } from "@tmux-ide/contracts";
 import { z } from "zod";
 
+import { logger } from "./log.ts";
+import {
+  boundedTmuxInteractionAppendCommand,
+  tmuxInteractionOption,
+  TMUX_INTERACTION_GAP_RECORD,
+  TMUX_INTERACTION_MAX_DRAIN_BYTES,
+} from "./tmux-interaction-retention.ts";
 import type { WorkspacePaneTmuxAuthority } from "./workspace-pane-creation.ts";
 import { createPinnedWorkspaceTmuxAsyncRunner } from "./workspace-pane-creation.ts";
 import { getDefaultWorkspaceRegistry, type WorkspaceRegistry } from "./workspace-registry.ts";
@@ -13,18 +20,72 @@ import {
   INTERNAL_SEND_OPERATION_OPTION,
 } from "./tmux-interaction-options.ts";
 
-const HOOK_MARKER = "tmux-ide-interaction-v2";
+const HOOK_MARKER = "tmux-ide-interaction-v3";
 const OWNED_HOOK_MARKER = "tmux-ide-interaction-v";
 const FIELD_SEPARATOR = "|tmux-ide-input-field-v1|";
 const EVENT_SEPARATOR = "|tmux-ide-input-event-v1|";
+export interface ExternalTmuxInteractionGap {
+  readonly reason:
+    | "overflow"
+    | "read-failed"
+    | "detach-failed"
+    | "projection-failed"
+    | "hooks-replaced"
+    | "hook-repair-failed";
+  readonly recovery: "future-observations-only";
+}
+
 const RUNTIME_PANE = /^%[0-9]+$/u;
 const RETRY_MS = 1_000;
 /**
  * Hooks are shared tmux state. A config reload, another client, or a debugging
  * command can replace them without killing the daemon, so waiting forever on
- * the old signal channel is not a sufficient health check.
+ * the old signal channel is not a sufficient health check. Every check costs
+ * one tmux child process, so a check that keeps finding the hooks intact backs
+ * off (doubling from `baseMs`, capped at `maxMs`); any repair, failure, or
+ * signal-loop error returns the cadence to `baseMs`. Measured on an otherwise
+ * idle daemon the fixed one-second cadence was the daemon's only recurring
+ * spawn source (two `show-hooks` children per second).
+ */
+export interface HookHealthcheckSchedule {
+  readonly baseMs: number;
+  readonly maxMs: number;
+}
+
+export const DEFAULT_HOOK_HEALTHCHECK_SCHEDULE: HookHealthcheckSchedule = Object.freeze({
+  baseMs: 1_000,
+  maxMs: 30_000,
+});
+
+export type HookHealthcheckOutcome = "healthy" | "repaired" | "failed";
+
+/** Pure cadence rule: healthy checks double the wait up to the cap; anything else resets it. */
+export function nextHookHealthcheckDelay(
+  previousMs: number,
+  outcome: HookHealthcheckOutcome,
+  schedule: HookHealthcheckSchedule = DEFAULT_HOOK_HEALTHCHECK_SCHEDULE,
+): number {
+  const base = Math.max(1, Math.floor(schedule.baseMs));
+  const max = Math.max(base, Math.floor(schedule.maxMs));
+  if (outcome !== "healthy") return base;
+  const previous = Number.isFinite(previousMs) ? Math.max(base, Math.floor(previousMs)) : base;
+  return Math.min(previous * 2, max);
+}
+
+/**
+ * True when `show-hooks` output lists an entry of `hookName` whose body carries
+ * this observer's buffer name. Output may hold several hook arrays at once
+ * (one combined `show-hooks -g a ; show-hooks -g b` client), so the check is
+ * per hook line rather than a substring search over the whole output.
  */
-const HOOK_HEALTHCHECK_MS = 1_000;
+export function ownedHookInstalled(output: string, hookName: string, bufferName: string): boolean {
+  const row = new RegExp(`^${hookName}\\[([0-9]+)\\]\\s+(.+)$`, "u");
+  for (const line of output.split("\n")) {
+    const match = row.exec(line);
+    if (match && match[2]!.includes(bufferName)) return true;
+  }
+  return false;
+}
 
 export { INTERNAL_READ_OPERATION_OPTION, INTERNAL_SEND_OPERATION_OPTION };
 
@@ -185,7 +246,7 @@ function hookIndexes(
 /**
  * Event-driven adapter from tmux's native send/capture hooks into the semantic
  * interaction spine. Hooks write only runtime identity, operation kind, and an
- * internal-operation marker to a tmux paste buffer, then signal a blocked
+ * internal-operation marker to bounded tmux option storage, then signal a blocked
  * `wait-for` client. No terminal input or captured output crosses this boundary.
  */
 export class TmuxExternalInteractionObserver {
@@ -200,8 +261,11 @@ export class TmuxExternalInteractionObserver {
   #installed = false;
   #loop: Promise<void> | null = null;
   #starting: Promise<void> | null = null;
-  #hookHealthcheck: ReturnType<typeof setInterval> | null = null;
-  #drainSequence = 0;
+  #hookHealthcheck: ReturnType<typeof setTimeout> | null = null;
+  readonly #healthcheckSchedule: HookHealthcheckSchedule;
+  #healthcheckDelayMs: number;
+  #lastHealthcheckOutcome: HookHealthcheckOutcome = "failed";
+  readonly #onGap: ((gap: ExternalTmuxInteractionGap) => void) | undefined;
   #tmuxWork: Promise<unknown> = Promise.resolve();
   #reconcile: Promise<void> | null = null;
   #diagnostics: ExternalTmuxObserverDiagnostics | null;
@@ -221,10 +285,19 @@ export class TmuxExternalInteractionObserver {
      */
     onObserved: (interaction: ExternalTmuxInteraction) => boolean;
     diagnostics?: ExternalTmuxObserverDiagnostics;
+    onGap?: (gap: ExternalTmuxInteractionGap) => void;
+    /** Health-check cadence bounds. Tests inject small values; production uses the default. */
+    healthcheck?: Partial<HookHealthcheckSchedule>;
   }) {
     this.#daemonInstanceId = options.daemonInstanceId;
+    this.#healthcheckSchedule = Object.freeze({
+      baseMs: options.healthcheck?.baseMs ?? DEFAULT_HOOK_HEALTHCHECK_SCHEDULE.baseMs,
+      maxMs: options.healthcheck?.maxMs ?? DEFAULT_HOOK_HEALTHCHECK_SCHEDULE.maxMs,
+    });
+    this.#healthcheckDelayMs = this.#healthcheckSchedule.baseMs;
     this.#registry = options.registry ?? getDefaultWorkspaceRegistry();
     this.#onObserved = options.onObserved;
+    this.#onGap = options.onGap;
     this.#authenticatedInternalReads = new AuthenticatedInternalReadVerifier({
       daemonInstanceId: options.daemonInstanceId,
       ownerToken: options.internalReadOwnerToken,
@@ -274,7 +347,7 @@ export class TmuxExternalInteractionObserver {
     } catch (error) {
       await this.#serializeTmux(async () => {
         await this.#removeOwnedHooks();
-        await this.#deleteBuffer(this.#bufferName);
+        await this.#deleteRetention();
       });
       if (!isTmuxServerUnavailable(error)) {
         this.#active = false;
@@ -289,13 +362,58 @@ export class TmuxExternalInteractionObserver {
     if (!this.#active || this.#abort.signal.aborted) {
       await this.#serializeTmux(async () => {
         await this.#removeOwnedHooks();
-        await this.#deleteBuffer(this.#bufferName);
+        await this.#deleteRetention();
       });
       throw new Error("tmux external interaction observer was disposed during startup");
     }
     this.#loop = this.#run();
-    this.#hookHealthcheck = setInterval(() => void this.reconcileHooks(), HOOK_HEALTHCHECK_MS);
-    this.#hookHealthcheck.unref?.();
+    this.#scheduleHealthcheck();
+  }
+
+  /** Wait before the next scheduled hook health check. Exposed for tests. */
+  get healthcheckDelayMs(): number {
+    return this.#healthcheckDelayMs;
+  }
+
+  #scheduleHealthcheck(): void {
+    if (this.#hookHealthcheck) clearTimeout(this.#hookHealthcheck);
+    this.#hookHealthcheck = null;
+    if (!this.#active || this.#abort.signal.aborted) return;
+    const timer = setTimeout(() => {
+      if (this.#hookHealthcheck === timer) this.#hookHealthcheck = null;
+      void this.#runScheduledHealthcheck();
+    }, this.#healthcheckDelayMs);
+    timer.unref?.();
+    this.#hookHealthcheck = timer;
+  }
+
+  async #runScheduledHealthcheck(): Promise<void> {
+    const delayBefore = this.#healthcheckDelayMs;
+    let outcome: HookHealthcheckOutcome;
+    try {
+      await this.reconcileHooks();
+      outcome = this.#lastHealthcheckOutcome;
+    } catch {
+      if (!this.#abort.signal.aborted) this.#reportGap("hook-repair-failed");
+      outcome = "failed";
+    }
+    // A signal-path reset that landed during this check wins over the outcome.
+    if (this.#healthcheckDelayMs === delayBefore) {
+      this.#healthcheckDelayMs = nextHookHealthcheckDelay(
+        delayBefore,
+        outcome,
+        this.#healthcheckSchedule,
+      );
+    }
+    if (this.#hookHealthcheck === null) this.#scheduleHealthcheck();
+  }
+
+  /** Something failed on the signal path: verify the hooks promptly again. */
+  #resetHealthcheckBackoff(): void {
+    const base = this.#healthcheckSchedule.baseMs;
+    if (this.#healthcheckDelayMs === base) return;
+    this.#healthcheckDelayMs = base;
+    if (this.#hookHealthcheck) this.#scheduleHealthcheck();
   }
 
   setDiagnostics(diagnostics: ExternalTmuxObserverDiagnostics | null): void {
@@ -303,17 +421,17 @@ export class TmuxExternalInteractionObserver {
   }
 
   async dispose(): Promise<void> {
-    if (!this.#active && !this.#loop && !this.#starting) return;
+    if (!this.#active && !this.#loop && !this.#starting && !this.#installed) return;
     const starting = this.#starting;
     this.#active = false;
     this.#abort.abort();
-    if (this.#hookHealthcheck) clearInterval(this.#hookHealthcheck);
+    if (this.#hookHealthcheck) clearTimeout(this.#hookHealthcheck);
     this.#hookHealthcheck = null;
     await Promise.allSettled([starting, this.#loop]);
     this.#loop = null;
     await this.#serializeTmux(async () => {
       await this.#removeOwnedHooks();
-      await this.#deleteBuffer(this.#bufferName);
+      await this.#deleteRetention();
     });
   }
 
@@ -326,20 +444,30 @@ export class TmuxExternalInteractionObserver {
     await this.#removeOwnedHooks(signal);
     await this.#deleteOwnedBuffers(signal);
     signal?.throwIfAborted();
+    // The small named buffer indexes retention options for crash cleanup;
+    // event data lives only in bounded options, never in this buffer.
+    await this.#io.runTmux(["set-buffer", "-b", this.#bufferName, "retention-owner"], signal);
     const hook = (
       operationKind: ExternalTmuxInteraction["operationKind"],
       markerOption: string,
       consumeMarker: boolean,
     ) => {
-      const data = `#{pane_id}${FIELD_SEPARATOR}#{q:${markerOption}}${FIELD_SEPARATOR}${operationKind}${EVENT_SEPARATOR}`;
+      // Reject arbitrary option text before expansion into a tmux command.
+      // Bound markers at the producer, including across multibyte input.
+      const validMarker = `#{&&:#{m/r:^[A-Za-z0-9:._-]*$,#{${markerOption}}},#{e|<=:#{n:${markerOption}},160}}`;
+      const marker = `#{?${validMarker},#{${markerOption}},}`;
+      const data = `#{pane_id}${FIELD_SEPARATOR}${marker}${FIELD_SEPARATOR}${operationKind}${EVENT_SEPARATOR}`;
       // Expand pane/marker identity at hook invocation, then schedule the
       // append+signal as a background tmux-native command list. No shell and
       // no second tmux client sit on the invoking command queue. The tiny
       // synchronous native cleanup runs only after the record string has been
       // captured, so a marker is single-use without racing the async drain.
-      const publish =
-        `run-shell -b -C "set-buffer -a -b '${this.#bufferName}' '${data}'` +
-        ` ; wait-for -S '${this.#signalChannel}'"`;
+      // Escape only the retention format for evaluation in the queued native
+      // command; capture pane and marker immediately, before consuming it.
+      const append = boundedTmuxInteractionAppendCommand(this.#bufferName, "RECORD")
+        .replace("#{=", "##{=")
+        .replace("RECORD", data);
+      const publish = `run-shell -b -C "${append} ; wait-for -S '${this.#signalChannel}'"`;
       // Hook commands inherit the triggering pane as their target, so cleanup
       // needs neither format expansion nor a nested command queue.
       const consume = consumeMarker ? ` ; set-option -pu '${markerOption}'` : "";
@@ -371,7 +499,7 @@ export class TmuxExternalInteractionObserver {
   /**
    * Restore product hooks when external tmux configuration removed them.
    * Public only so the lifecycle is hermetically testable; the production
-   * observer invokes it from a cheap one-second health check.
+   * observer invokes it from the backed-off health check.
    */
   reconcileHooks(options: { readonly allowInactive?: boolean } = {}): Promise<void> {
     if (!this.#active && options.allowInactive !== true) return Promise.resolve();
@@ -380,15 +508,20 @@ export class TmuxExternalInteractionObserver {
       const finish = this.#beginDiagnostic("healthcheck");
       try {
         if (await this.#ownedHooksPresent(this.#abort.signal)) {
+          this.#lastHealthcheckOutcome = "healthy";
           finish(true);
           return;
         }
+        // Hooks that were installed and are now gone dropped every interaction
+        // since their removal; the repair restores future observation only.
+        if (this.#installed) this.#reportGap("hooks-replaced");
         this.#installed = false;
         try {
           await this.#install(this.#abort.signal);
         } catch {
           this.#installed = false;
         }
+        this.#lastHealthcheckOutcome = this.#installed ? "repaired" : "failed";
         finish(this.#installed);
       } catch (error) {
         finish(false);
@@ -402,38 +535,57 @@ export class TmuxExternalInteractionObserver {
     return settled;
   }
 
-  /** Atomically detach and drain the current event buffer. */
+  /** Atomically detach and drain the current bounded event batch. */
   drain(): Promise<boolean> {
     return this.#serializeTmux(() => this.#drain());
   }
 
   async #drain(): Promise<boolean> {
     const finish = this.#beginDiagnostic("drain");
-    const drainName = `${this.#bufferName}-drain-${++this.#drainSequence}`;
+    const option = tmuxInteractionOption(this.#bufferName);
+    // A single reusable detached slot bounds retained storage even if deletion
+    // fails. Native synchronous commands execute consecutively in one queue.
+    const drainName = `${option}-drain`;
     try {
       await this.#io.runTmux(
-        ["set-buffer", "-b", this.#bufferName, "-n", drainName],
+        ["set-option", "-gF", drainName, `#{${option}}`, ";", "set-option", "-g", option, ""],
         this.#abort.signal,
       );
     } catch {
+      this.#reportGap("detach-failed");
       finish(false);
       return false;
     }
-    let raw: string;
-    try {
-      raw = await this.#io.runTmux(["show-buffer", "-b", drainName], this.#abort.signal);
-    } catch {
+    let raw: string | undefined;
+    // Retry the same immutable detached batch once. Never accumulate an
+    // unbounded collection of failed batches or spin until a server recovers.
+    for (let attempt = 0; attempt < 2 && !this.#abort.signal.aborted; attempt += 1) {
+      try {
+        raw = await this.#io.runTmux(["show-options", "-gv", drainName], this.#abort.signal);
+        break;
+      } catch {
+        // Exhaustion is surfaced below, without terminal content or errors.
+      }
+    }
+    await this.#deleteOption(drainName);
+    if (raw === undefined) {
+      this.#reportGap("read-failed");
+      finish(false);
+      return false;
+    }
+    if (Buffer.byteLength(raw, "utf8") > TMUX_INTERACTION_MAX_DRAIN_BYTES) {
+      this.#reportGap("overflow");
       finish(false);
       return false;
-    } finally {
-      await this.#deleteBuffer(drainName);
     }
+    if (raw.includes(TMUX_INTERACTION_GAP_RECORD)) this.#reportGap("overflow");
     let consumed = false;
     try {
       for (const record of parseTmuxInputHookRecords(raw)) {
         consumed = (await this.#project(record)) || consumed;
       }
     } catch (error) {
+      this.#reportGap("projection-failed");
       finish(false);
       throw error;
     }
@@ -452,6 +604,7 @@ export class TmuxExternalInteractionObserver {
         await this.drain();
       } catch {
         this.#installed = false;
+        this.#resetHealthcheckBackoff();
         await this.#io.delay(RETRY_MS, this.#abort.signal);
       }
     }
@@ -527,16 +680,54 @@ export class TmuxExternalInteractionObserver {
   }
 
   async #ownedHooksPresent(signal?: AbortSignal): Promise<boolean> {
-    for (const hookName of ["after-send-keys", "after-capture-pane"] as const) {
-      let output: string;
-      try {
-        output = await this.#io.runTmux(["show-hooks", "-g", hookName], signal);
-      } catch {
-        return false;
-      }
-      if (!output.includes(this.#bufferName)) return false;
+    // One client verifies both hook arrays: tmux runs the `;`-separated list in
+    // a single command queue and prints each array's lines in order.
+    let output: string;
+    try {
+      output = await this.#io.runTmux(
+        ["show-hooks", "-g", "after-send-keys", ";", "show-hooks", "-g", "after-capture-pane"],
+        signal,
+      );
+    } catch {
+      return false;
+    }
+    return (
+      ownedHookInstalled(output, "after-send-keys", this.#bufferName) &&
+      ownedHookInstalled(output, "after-capture-pane", this.#bufferName)
+    );
+  }
+
+  #reportGap(reason: ExternalTmuxInteractionGap["reason"]): void {
+    if (this.#abort.signal.aborted) return;
+    const gap: ExternalTmuxInteractionGap = { reason, recovery: "future-observations-only" };
+    logger.warn(
+      "tmux-interaction-observer",
+      "Interaction observation gap; missing history cannot be replayed",
+      {
+        daemonInstanceId: this.#daemonInstanceId,
+        ...gap,
+      },
+    );
+    try {
+      this.#onGap?.(gap);
+    } catch {
+      /* Reporting cannot create operation authority. */
     }
-    return true;
+  }
+
+  async #deleteOption(name: string, signal?: AbortSignal): Promise<void> {
+    try {
+      await this.#io.runTmux(["set-option", "-gu", name], signal);
+    } catch {
+      /* Best effort. */
+    }
+  }
+
+  async #deleteRetention(): Promise<void> {
+    const option = tmuxInteractionOption(this.#bufferName);
+    await this.#deleteOption(option);
+    await this.#deleteOption(`${option}-drain`);
+    await this.#deleteBuffer(this.#bufferName);
   }
 
   async #deleteOwnedBuffers(signal?: AbortSignal): Promise<void> {
@@ -547,7 +738,12 @@ export class TmuxExternalInteractionObserver {
       return;
     }
     for (const name of output.split("\n")) {
-      if (name.startsWith(OWNED_HOOK_MARKER)) await this.#deleteBuffer(name, signal);
+      if (!name.startsWith(OWNED_HOOK_MARKER) || name === this.#bufferName) continue;
+      if (/^[A-Za-z0-9._-]{1,256}$/u.test(name)) {
+        await this.#deleteOption(tmuxInteractionOption(name), signal);
+        await this.#deleteOption(`${tmuxInteractionOption(name)}-drain`, signal);
+      }
+      await this.#deleteBuffer(name, signal);
     }
   }
 

package/packages/daemon/src/lib/tmux-interaction-retention.ts

@@ -0,0 +1,24 @@
+const EVENT_SEPARATOR = "|tmux-ide-input-event-v1|";
+
+// ASCII metadata only. The native producer retains a prefix plus the newest
+// record; truncation inserts a framed gap, never an invented interaction.
+// Keep this within tmux's supported format-width range: larger widths can
+// silently disable truncation. Live tests cover tmux 3.4 and 3.7c.
+export const TMUX_INTERACTION_RETAINED_CHARS = 8_192;
+export const TMUX_INTERACTION_GAP_RECORD = `${EVENT_SEPARATOR}gap${EVENT_SEPARATOR}`;
+export const TMUX_INTERACTION_MAX_DRAIN_BYTES =
+  TMUX_INTERACTION_RETAINED_CHARS + TMUX_INTERACTION_GAP_RECORD.length + 1_024;
+
+export function tmuxInteractionOption(bufferName: string): string {
+  if (!/^[A-Za-z0-9._-]{1,256}$/u.test(bufferName)) throw new TypeError("Invalid observer name");
+  return `@${bufferName}`;
+}
+
+/** One native command, also used by atomic NOHOOKS recovery (fixed ordinals). */
+export function boundedTmuxInteractionAppendCommand(bufferName: string, record: string): string {
+  const option = tmuxInteractionOption(bufferName);
+  if (!/^[A-Za-z0-9%:._|-]{1,1024}$/u.test(record)) {
+    throw new TypeError("Invalid observer metadata");
+  }
+  return `set-option -gF '${option}' '#{=/${TMUX_INTERACTION_RETAINED_CHARS}/${TMUX_INTERACTION_GAP_RECORD}:${option}}${record}'`;
+}