tmux-ide 2.9.6 → 2.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.9.6",
+  "version": "2.9.8",
   "description": "The open-source workspace for coding agents: run Claude Code, Codex and other agents in tmux with live status",
   "type": "module",
   "bin": {
@@ -105,7 +105,7 @@
     "test:tui-gallery": "bun test --preload @opentui/solid/preload --preload ./packages/daemon/test-support/opentui-renderer-preload.ts ./scripts/tui-gallery/gallery.test.tsx",
     "typecheck:tui-gallery": "tsc --noEmit -p scripts/tsconfig.tui-gallery.json",
     "test:spark-qualification": "node --import tsx --test scripts/lib/spark-*.test.ts scripts/lib/spark-*.test.mjs",
-    "test:installer": "node --test scripts/install.test.mjs",
+    "test:installer": "node --test scripts/install.test.mjs scripts/lib/installer-service-qualification.test.mjs",
     "qualify:styled-ssh": "node scripts/qualify-styled-ssh.mjs"
   },
   "keywords": [

package/packages/contracts/src/index.ts

@@ -49,6 +49,7 @@ export * from "./semantic-identity.ts";
 export * from "./session-runtime.ts";
 export * from "./terminal-replica.ts";
 export * from "./terminal-delivery.ts";
+export * from "./terminal-graphics.ts";
 export * from "./terminal-runtime-inventory.ts";
 export * from "./experience-shell.ts";
 export * from "./application-shell.ts";
@@ -115,3 +116,7 @@ export * from "./window-split-layout.ts";
 export * from "./pane-editor-context.ts";
 
 export * from "./tmux-agent-open.ts";
+
+export * from "./tmux-server-diagnostics.ts";
+
+export * from "./terminal-history-anchor.ts";

package/packages/contracts/src/pane-stream.ts

@@ -18,6 +18,13 @@ import {
   TerminalAttachmentSemanticWindowIdSchemaZ,
 } from "./semantic-identity.ts";
 import { TerminalAttachmentViewerModeSchemaZ } from "./terminal-attachments.ts";
+import {
+  TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES,
+  TERMINAL_GRAPHICS_MAX_REQUEST_DIGESTS,
+  TerminalGraphicsBlobSchemaZ,
+  TerminalGraphicsDigestSchemaZ,
+  TerminalGraphicsStateSchemaZ,
+} from "./terminal-graphics.ts";
 import { WorkspaceIdSchemaZ } from "./workspace-state.ts";
 import {
   TerminalDeliveryAckSchemaZ,
@@ -341,6 +348,34 @@ export const PaneStreamClockProbeFrameSchemaZ = z
   })
   .strict();
 
+/** Ask for image bytes by digest; only after the daemon sent graphics state. */
+export const PaneStreamTerminalGraphicsRequestFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-graphics-request"),
+    pane: PaneStreamSemanticPaneIdSchemaZ,
+    digests: z
+      .array(TerminalGraphicsDigestSchemaZ)
+      .min(1)
+      .max(TERMINAL_GRAPHICS_MAX_REQUEST_DIGESTS),
+  })
+  .strict();
+
+/** The renderer's terminal cell size in device pixels (see capability 103). */
+export const PaneStreamTerminalCellPixelsFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-cell-pixels"),
+    width: z.number().int().min(1).max(1024),
+    height: z.number().int().min(1).max(1024),
+    precise: z
+      .object({
+        width: z.number().int().min(1000).max(1024000),
+        height: z.number().int().min(1000).max(1024000),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
 export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamInputFrameSchemaZ,
   PaneStreamConsumedFrameSchemaZ,
@@ -354,6 +389,8 @@ export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamAuthorityRequestFrameSchemaZ,
   PaneStreamAuthorityReleaseFrameSchemaZ,
   PaneStreamClockProbeFrameSchemaZ,
+  PaneStreamTerminalGraphicsRequestFrameSchemaZ,
+  PaneStreamTerminalCellPixelsFrameSchemaZ,
 ]);
 export type PaneStreamClientFrame = z.infer<typeof PaneStreamClientFrameSchemaZ>;
 
@@ -645,6 +682,21 @@ export const PaneStreamTerminalDeliveryFaultFrameSchemaZ = z
     fault: TerminalDeliveryFaultSchemaZ,
   })
   .strict();
+export const PaneStreamTerminalGraphicsFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-graphics"),
+    pane: PaneStreamSemanticPaneIdSchemaZ,
+    state: TerminalGraphicsStateSchemaZ,
+  })
+  .strict();
+export const PaneStreamTerminalGraphicsBlobFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-graphics-blob"),
+    pane: PaneStreamSemanticPaneIdSchemaZ,
+    blob: TerminalGraphicsBlobSchemaZ,
+    data: Base64SchemaZ(Math.ceil(TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES / 3) * 4).min(4),
+  })
+  .strict();
 export const PaneStreamSemanticIntentAckFrameSchemaZ = z
   .object({
     type: z.literal("semantic-intent-ack"),
@@ -749,6 +801,8 @@ export const PaneStreamServerFrameSchemaZ = z.discriminatedUnion("type", [
   PaneStreamTerminalDeliveryEnvelopeFrameSchemaZ,
   PaneStreamTerminalDeliveryChunkFrameSchemaZ,
   PaneStreamTerminalDeliveryFaultFrameSchemaZ,
+  PaneStreamTerminalGraphicsFrameSchemaZ,
+  PaneStreamTerminalGraphicsBlobFrameSchemaZ,
   PaneStreamSemanticIntentAckFrameSchemaZ,
   PaneStreamViewportAckFrameSchemaZ,
   PaneStreamAuthoritySnapshotFrameSchemaZ,

package/packages/contracts/src/terminal-graphics.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+
+/**
+ * Kitty graphics protocol side channel.
+ *
+ * Image bytes never enter the canonical terminal replica: the replica keeps
+ * the cells (including Unicode placeholder cells, which tmux retains as text)
+ * and this channel carries, per pane, the image registry those cells refer to
+ * plus best-effort cursor-anchored placements. Bytes travel separately, once
+ * per content digest, and only when a renderer asks for them.
+ *
+ * Capability: a renderer that understands these frames adds
+ * {@link TERMINAL_GRAPHICS_CAPABILITY_VERSION} to its terminal-delivery offer's
+ * `protocolVersions`. Daemons that predate the channel ignore the extra
+ * version; daemons that know it send graphics frames only to such renderers.
+ */
+export const TERMINAL_GRAPHICS_CAPABILITY_VERSION = 101;
+/** Renderers that inflate `rgba-zlib`/`rgb-zlib` themselves offer this too. */
+export const TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION = 102;
+/**
+ * Renderers that report their cell size in device pixels offer this; the
+ * daemon then marks graphics state with `cellPixels: true` and accepts
+ * `terminal-cell-pixels`, so programs size images 1:1 for the window.
+ */
+export const TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION = 103;
+/** Thousandths of a device pixel, avoiding accumulated per-cell rounding. */
+export const TERMINAL_GRAPHICS_PRECISE_PIXELS_CAPABILITY_VERSION = 104;
+/** Raw image bytes per blob frame (base64 on the wire stays below 1 MiB). */
+export const TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES = 512 * 1024;
+/** Largest single image a daemon publishes (a 4K RGBA frame is ~33 MB). */
+export const TERMINAL_GRAPHICS_MAX_IMAGE_BYTES = 64 * 1024 * 1024;
+/** What renderers without the zlib capability accept. */
+export const TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+export const TERMINAL_GRAPHICS_MAX_IMAGES = 256;
+export const TERMINAL_GRAPHICS_MAX_PLACEMENTS = 256;
+export const TERMINAL_GRAPHICS_MAX_REQUEST_DIGESTS = 64;
+
+export const TerminalGraphicsDigestSchemaZ = z.string().regex(/^[0-9a-f]{32}$/u);
+/**
+ * `*-zlib` carry raw pixels still deflated as the program sent them (`o=z`);
+ * only renderers that offered {@link TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION}
+ * receive them.
+ */
+export const TerminalGraphicsFormatSchemaZ = z.enum([
+  "png",
+  "rgba",
+  "rgb",
+  "rgba-zlib",
+  "rgb-zlib",
+]);
+export type TerminalGraphicsFormat = z.infer<typeof TerminalGraphicsFormatSchemaZ>;
+const Dimension = z.number().int().min(1).max(10_000);
+const Cells = z.number().int().min(1).max(1_000);
+const CellIndex = z.number().int().min(0).max(1_000);
+
+export const TerminalGraphicsImageSchemaZ = z
+  .object({
+    /** Program-chosen kitty image id (placeholder cells encode it in colour). */
+    imageId: z.number().int().min(0).max(0xffff_ffff),
+    digest: TerminalGraphicsDigestSchemaZ,
+    format: TerminalGraphicsFormatSchemaZ,
+    width: Dimension,
+    height: Dimension,
+    bytes: z.number().int().min(1).max(TERMINAL_GRAPHICS_MAX_IMAGE_BYTES),
+    /** The `U=1` virtual placement's cell grid, when placeholders may show it. */
+    placeholder: z.object({ columns: Cells, rows: Cells }).strict().nullable(),
+  })
+  .strict();
+export type TerminalGraphicsImage = z.infer<typeof TerminalGraphicsImageSchemaZ>;
+
+/** A cursor-anchored placement clipped to the pane viewport (best effort). */
+export const TerminalGraphicsPlacementSchemaZ = z
+  .object({
+    digest: TerminalGraphicsDigestSchemaZ,
+    row: CellIndex,
+    column: CellIndex,
+    rows: Cells,
+    columns: Cells,
+    sourceRow: CellIndex,
+    sourceColumn: CellIndex,
+    totalRows: Cells,
+    totalColumns: Cells,
+  })
+  .strict();
+export type TerminalGraphicsPlacement = z.infer<typeof TerminalGraphicsPlacementSchemaZ>;
+
+export const TerminalGraphicsStateSchemaZ = z
+  .object({
+    revision: z.number().int().nonnegative(),
+    images: z.array(TerminalGraphicsImageSchemaZ).max(TERMINAL_GRAPHICS_MAX_IMAGES),
+    placements: z.array(TerminalGraphicsPlacementSchemaZ).max(TERMINAL_GRAPHICS_MAX_PLACEMENTS),
+    /** The daemon accepts `terminal-cell-pixels` (only sent to renderers offering 103). */
+    cellPixels: z.literal(true).optional(),
+    preciseCellPixels: z.literal(true).optional(),
+  })
+  .strict();
+export type TerminalGraphicsState = z.infer<typeof TerminalGraphicsStateSchemaZ>;
+
+export const TerminalGraphicsBlobSchemaZ = z
+  .object({
+    digest: TerminalGraphicsDigestSchemaZ,
+    format: TerminalGraphicsFormatSchemaZ,
+    width: Dimension,
+    height: Dimension,
+    total: z.number().int().min(1).max(TERMINAL_GRAPHICS_MAX_IMAGE_BYTES),
+    offset: z.number().int().nonnegative().max(TERMINAL_GRAPHICS_MAX_IMAGE_BYTES),
+  })
+  .strict();
+export type TerminalGraphicsBlob = z.infer<typeof TerminalGraphicsBlobSchemaZ>;
+
+/** Hub → transport messages (in-process; the transport frames them). */
+export type TerminalGraphicsServerMessage =
+  | { readonly type: "terminal.graphics"; readonly state: TerminalGraphicsState }
+  | {
+      readonly type: "terminal.graphics.blob";
+      readonly blob: TerminalGraphicsBlob;
+      readonly bytes: Uint8Array;
+    };

package/packages/contracts/src/terminal-history-anchor.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { WorkspaceIdSchemaZ } from "./workspace-state.ts";
+import { TerminalAttachmentSemanticPaneIdSchemaZ } from "./semantic-identity.ts";
+import { TmuxServerScopeSchemaZ } from "./tmux-server-scope.ts";
+import { WorkspaceCatalogLiveSessionIdSchemaZ } from "./workspace-catalog-resource.ts";
+export const HistoryAnchorProofSchemaZ = z
+  .object({
+    workspaceName: WorkspaceIdSchemaZ,
+    semanticPaneId: TerminalAttachmentSemanticPaneIdSchemaZ,
+    generation: z.uuid(),
+    incarnation: z.string().min(1).max(256),
+    revision: z.number().int().nonnegative().safe(),
+    stateHash: z.string().regex(/^[0-9a-f]{16}$/u),
+  })
+  .strict();
+export const HistoryAnchorIdentitySchemaZ = HistoryAnchorProofSchemaZ.omit({
+  revision: true,
+  stateHash: true,
+});
+export const HistoryAnchorRequestSchemaZ = z.union([
+  z
+    .object({
+      version: z.literal(1),
+      liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ,
+      proof: HistoryAnchorProofSchemaZ,
+      operation: z
+        .object({ kind: z.literal("capture"), historyIndex: z.number().int().nonnegative().safe() })
+        .strict(),
+    })
+    .strict(),
+  z
+    .object({
+      version: z.literal(1),
+      liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ,
+      proof: HistoryAnchorIdentitySchemaZ,
+      operation: z.object({ kind: z.literal("resolve"), token: z.uuid() }).strict(),
+    })
+    .strict(),
+]);
+export const HistoryAnchorResultSchemaZ = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("captured"), token: z.uuid() }).strict(),
+  z
+    .object({
+      status: z.literal("resolved"),
+      proof: HistoryAnchorProofSchemaZ,
+      historyIndex: z.number().int().nonnegative().safe(),
+    })
+    .strict(),
+  z.object({ status: z.literal("unavailable") }).strict(),
+  z.object({ status: z.literal("stale") }).strict(),
+  z.object({ status: z.literal("lost") }).strict(),
+]);
+export const HistoryAnchorResponseSchemaZ = z
+  .object({
+    version: z.literal(1),
+    server: TmuxServerScopeSchemaZ,
+    result: HistoryAnchorResultSchemaZ,
+  })
+  .strict();
+export type HistoryAnchorRequest = z.infer<typeof HistoryAnchorRequestSchemaZ>;
+export type HistoryAnchorResult = z.infer<typeof HistoryAnchorResultSchemaZ>;

package/packages/contracts/src/tmux-server-diagnostics.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { TmuxServerScopeSchemaZ } from "./tmux-server-scope.ts";
+
+/** Server format output only; never accept freeform diagnostic text. */
+export const TmuxServerVersionSchemaZ = z
+  .string()
+  .max(32)
+  .regex(/^[0-9]+\.[0-9]+[a-z]?$/u);
+export const TmuxServerDiagnosticsSchemaZ = z
+  .object({
+    version: z.literal(1),
+    server: TmuxServerScopeSchemaZ,
+    tmuxVersion: TmuxServerVersionSchemaZ,
+  })
+  .strict();
+export type TmuxServerDiagnostics = z.infer<typeof TmuxServerDiagnosticsSchemaZ>;

package/packages/core/src/index.ts

@@ -19,3 +19,4 @@ export * from "./saved-machines.ts";
 
 export * from "./fleet-client-state.ts";
 export * from "./resize-transaction.ts";
+export * from "./kitty-placeholders.ts";

package/packages/core/src/kitty-placeholders.ts

@@ -0,0 +1,208 @@
+/**
+ * Kitty graphics Unicode placeholders, decoded from replica cells.
+ *
+ * A program places an image with a `U=1` virtual placement and then prints
+ * U+10EEEE cells whose combining diacritics give the image row and column and
+ * whose foreground colour gives the image id. To tmux these are ordinary text,
+ * so they survive scrolling, history, capture and reattach; renderers derive
+ * placements from the cells they already hold and stay in exact sync.
+ */
+import type {
+  TerminalGraphicsPlacement,
+  TerminalGraphicsState,
+  TerminalReplicaRow,
+} from "@tmux-ide/contracts";
+
+export const KITTY_PLACEHOLDER = 0x10eeee;
+
+type KittyCellColor =
+  | { readonly kind: "default" }
+  | { readonly kind: "indexed"; readonly index: number }
+  | { readonly kind: "rgb"; readonly value: number };
+
+// Row/column diacritics for Unicode placeholders, in protocol order (index = value).
+const DIACRITICS = [
+  "0305 030D 030E 0310 0312 033D 033E 033F 0346 034A 034B 034C 0350 0351 0352 0357 035B 0363 0364",
+  "0365 0366 0367 0368 0369 036A 036B 036C 036D 036E 036F 0483 0484 0485 0486 0487 0592 0593 0594",
+  "0595 0597 0598 0599 059C 059D 059E 059F 05A0 05A1 05A8 05A9 05AB 05AC 05AF 05C4 0610 0611 0612",
+  "0613 0614 0615 0616 0617 0657 0658 0659 065A 065B 065D 065E 06D6 06D7 06D8 06D9 06DA 06DB 06DC",
+  "06DF 06E0 06E1 06E2 06E4 06E7 06E8 06EB 06EC 0730 0732 0733 0735 0736 073A 073D 073F 0740 0741",
+  "0743 0745 0747 0749 074A 07EB 07EC 07ED 07EE 07EF 07F0 07F1 07F3 0816 0817 0818 0819 081B 081C",
+  "081D 081E 081F 0820 0821 0822 0823 0825 0826 0827 0829 082A 082B 082C 082D 0951 0953 0954 0F82",
+  "0F83 0F86 0F87 135D 135E 135F 17DD 193A 1A17 1A75 1A76 1A77 1A78 1A79 1A7A 1A7B 1A7C 1B6B 1B6D",
+  "1B6E 1B6F 1B70 1B71 1B72 1B73 1CD0 1CD1 1CD2 1CDA 1CDB 1CE0 1DC0 1DC1 1DC3 1DC4 1DC5 1DC6 1DC7",
+  "1DC8 1DC9 1DCB 1DCC 1DD1 1DD2 1DD3 1DD4 1DD5 1DD6 1DD7 1DD8 1DD9 1DDA 1DDB 1DDC 1DDD 1DDE 1DDF",
+  "1DE0 1DE1 1DE2 1DE3 1DE4 1DE5 1DE6 1DFE 20D0 20D1 20D4 20D5 20D6 20D7 20DB 20DC 20E1 20E7 20E9",
+  "20F0 2CEF 2CF0 2CF1 2DE0 2DE1 2DE2 2DE3 2DE4 2DE5 2DE6 2DE7 2DE8 2DE9 2DEA 2DEB 2DEC 2DED 2DEE",
+  "2DEF 2DF0 2DF1 2DF2 2DF3 2DF4 2DF5 2DF6 2DF7 2DF8 2DF9 2DFA 2DFB 2DFC 2DFD 2DFE 2DFF A66F A67C",
+  "A67D A6F0 A6F1 A8E0 A8E1 A8E2 A8E3 A8E4 A8E5 A8E6 A8E7 A8E8 A8E9 A8EA A8EB A8EC A8ED A8EE A8EF",
+  "A8F0 A8F1 AAB0 AAB2 AAB3 AAB7 AAB8 AABE AABF AAC1 FE20 FE21 FE22 FE23 FE24 FE25 FE26 10A0F 10A38",
+  "1D185 1D186 1D187 1D188 1D189 1D1AA 1D1AB 1D1AC 1D1AD 1D242 1D243 1D244",
+]
+  .join(" ")
+  .split(" ");
+const DIACRITIC_VALUE = new Map(DIACRITICS.map((hex, index) => [Number.parseInt(hex, 16), index]));
+
+export interface PlaceholderCell {
+  imageId: number;
+  row: number;
+  col: number;
+}
+
+/** PURE — decode one cell; null when it is not a placeholder. */
+export function decodeKittyPlaceholderCell(
+  grapheme: string,
+  foreground: KittyCellColor,
+  left: PlaceholderCell | null,
+): PlaceholderCell | null {
+  const points = [...grapheme].map((ch) => ch.codePointAt(0)!);
+  if (points[0] !== KITTY_PLACEHOLDER) return null;
+  const marks = points.slice(1).map((p) => DIACRITIC_VALUE.get(p));
+  let imageId =
+    foreground.kind === "indexed"
+      ? foreground.index
+      : foreground.kind === "rgb"
+        ? foreground.value & 0xffffff
+        : 0;
+  if (marks[2] !== undefined) imageId += marks[2] * 0x1000000;
+  const continues = left !== null && (marks[0] === undefined || marks[0] === left.row);
+  const row = marks[0] ?? (continues ? left!.row : 0);
+  const col = marks[1] ?? (continues ? left!.col + 1 : 0);
+  if (marks[2] === undefined && continues && imageId === (left!.imageId & 0xffffff))
+    imageId = left!.imageId;
+  return { imageId, row, col };
+}
+
+export interface PlaceholderRect {
+  imageId: number;
+  row: number;
+  column: number;
+  rows: number;
+  columns: number;
+  srcRow: number;
+  srcCol: number;
+}
+
+export function kittyPlaceholderRects(
+  grid: readonly {
+    readonly cells: readonly { readonly grapheme: string; readonly foreground: KittyCellColor }[];
+  }[],
+): PlaceholderRect[] {
+  // Horizontal runs: same image and source row, consecutive source columns.
+  const open: PlaceholderRect[] = [];
+  const done: PlaceholderRect[] = [];
+  for (let y = 0; y < grid.length; y += 1) {
+    const runs: PlaceholderRect[] = [];
+    let left: PlaceholderCell | null = null;
+    let run: PlaceholderRect | null = null;
+    const cells = grid[y]!.cells;
+    for (let x = 0; x < cells.length; x += 1) {
+      const cell = decodeKittyPlaceholderCell(cells[x]!.grapheme, cells[x]!.foreground, left);
+      left = cell;
+      if (
+        cell &&
+        run &&
+        cell.imageId === run.imageId &&
+        cell.row === run.srcRow &&
+        cell.col === run.srcCol + run.columns
+      ) {
+        run.columns += 1;
+        continue;
+      }
+      if (run) runs.push(run);
+      run = cell
+        ? {
+            imageId: cell.imageId,
+            row: y,
+            column: x,
+            rows: 1,
+            columns: 1,
+            srcRow: cell.row,
+            srcCol: cell.col,
+          }
+        : null;
+    }
+    if (run) runs.push(run);
+    // Merge with the rectangle directly above when it continues the image.
+    const stillOpen: PlaceholderRect[] = [];
+    for (const candidate of runs) {
+      const above = open.find(
+        (rect) =>
+          rect.imageId === candidate.imageId &&
+          rect.column === candidate.column &&
+          rect.columns === candidate.columns &&
+          rect.srcCol === candidate.srcCol &&
+          rect.row + rect.rows === y &&
+          rect.srcRow + rect.rows === candidate.srcRow,
+      );
+      if (above) {
+        above.rows += 1;
+        open.splice(open.indexOf(above), 1);
+        stillOpen.push(above);
+      } else stillOpen.push(candidate);
+    }
+    done.push(...open);
+    open.length = 0;
+    open.push(...stillOpen);
+  }
+  done.push(...open);
+  return done;
+}
+
+/**
+ * PURE — every visible image placement for one pane: placeholder rectangles
+ * resolved through the pane's image registry, then the daemon's best-effort
+ * cursor-anchored placements. Cells naming an unknown image are skipped.
+ */
+export function resolveKittyPlacements(
+  grid: readonly TerminalReplicaRow[],
+  state: TerminalGraphicsState,
+): TerminalGraphicsPlacement[] {
+  return resolveKittyImagePlacements(grid, state).map(({ placement }) => placement);
+}
+
+/**
+ * As {@link resolveKittyPlacements}, with the kitty image id each placement
+ * shows: exact for placeholder cells (they encode it); for cursor placements
+ * the first image with that content.
+ */
+export function resolveKittyImagePlacements(
+  grid: readonly TerminalReplicaRow[],
+  state: TerminalGraphicsState,
+): { placement: TerminalGraphicsPlacement; imageId: number }[] {
+  const placements: { placement: TerminalGraphicsPlacement; imageId: number }[] = [];
+  const byId = new Map(state.images.map((image) => [image.imageId, image]));
+  let scan = false;
+  for (const image of state.images) if (image.placeholder) scan = true;
+  if (scan) {
+    for (const rect of kittyPlaceholderRects(grid)) {
+      const image = byId.get(rect.imageId);
+      const virtualGrid = image?.placeholder;
+      if (!image || !virtualGrid) continue;
+      if (
+        rect.srcRow + rect.rows > virtualGrid.rows ||
+        rect.srcCol + rect.columns > virtualGrid.columns
+      )
+        continue;
+      placements.push({
+        imageId: image.imageId,
+        placement: {
+          digest: image.digest,
+          row: rect.row,
+          column: rect.column,
+          rows: rect.rows,
+          columns: rect.columns,
+          sourceRow: rect.srcRow,
+          sourceColumn: rect.srcCol,
+          totalRows: virtualGrid.rows,
+          totalColumns: virtualGrid.columns,
+        },
+      });
+    }
+  }
+  for (const placement of state.placements) {
+    const image = state.images.find((candidate) => candidate.digest === placement.digest);
+    if (image) placements.push({ placement, imageId: image.imageId });
+  }
+  return placements;
+}

package/packages/daemon/dist/command-center/tmux-server-diagnostics.js

@@ -0,0 +1,24 @@
+import { TmuxServerScopeSchemaZ, TmuxServerDiagnosticsSchemaZ } from "@tmux-ide/contracts";
+import { TmuxServerScopeError } from "../lib/tmux-server-owners.js";
+/** Mount beneath the existing owner-authenticated, no-store server router. */
+export function mountTmuxServerDiagnosticsRoute(app, options) {
+    app.get(`${options.scopedPath}/diagnostics`, async (c) => {
+        const scope = TmuxServerScopeSchemaZ.safeParse({
+            serverId: c.req.param("serverId"),
+            generation: c.req.param("generation"),
+        });
+        if (!scope.success)
+            return c.json({ error: { code: "invalid-request" } }, 400);
+        try {
+            c.req.raw.signal.throwIfAborted();
+            const tmuxVersion = await options.owners.withOwner(scope.data, (owner) => owner.readServerVersion(c.req.raw.signal));
+            c.req.raw.signal.throwIfAborted();
+            return c.json(TmuxServerDiagnosticsSchemaZ.parse({ version: 1, server: scope.data, tmuxVersion }));
+        }
+        catch (error) {
+            if (error instanceof TmuxServerScopeError)
+                return c.json({ error: { code: "scope-unavailable" } }, error.code === "not-found" ? 404 : 409);
+            return c.json({ error: { code: "diagnostics-unavailable" } }, 503);
+        }
+    });
+}

package/packages/daemon/dist/command-center/tmux-server-history-anchor.js

@@ -0,0 +1,48 @@
+import { HistoryAnchorRequestSchemaZ, HistoryAnchorResponseSchemaZ, TmuxServerScopeSchemaZ, } from "@tmux-ide/contracts";
+import { TmuxServerScopeError } from "../lib/tmux-server-owners.js";
+/** Mounted below owner-authenticated no-store middleware. Never opens a runtime. */
+export function mountTmuxServerHistoryAnchorRoute(app, options) {
+    app.post(`${options.scopedPath}/history-anchor`, async (c) => {
+        const scope = TmuxServerScopeSchemaZ.safeParse({
+            serverId: c.req.param("serverId"),
+            generation: c.req.param("generation"),
+        });
+        if (!scope.success)
+            return c.json({ error: { code: "invalid-request" } }, 400);
+        let body;
+        try {
+            body = HistoryAnchorRequestSchemaZ.parse(await options.readBody(c.req.raw));
+        }
+        catch {
+            return c.json({ error: { code: "invalid-request" } }, 400);
+        }
+        if (body.proof.generation !== scope.data.generation)
+            return c.json({ error: { code: "stale-generation" } }, 409);
+        try {
+            c.req.raw.signal.throwIfAborted();
+            const result = await options.owners.withOwner(scope.data, async (owner) => {
+                const sessions = await owner.catalog();
+                c.req.raw.signal.throwIfAborted();
+                const workspace = owner.workspaceRegistry.get(body.proof.workspaceName);
+                if (!workspace ||
+                    !sessions.some((row) => row.sessionName === workspace.sessionName && row.liveSessionId === body.liveSessionId))
+                    return { status: "stale" };
+                const result = owner.sessionRuntimeRegistry.historyAnchor(workspace.sessionName, HistoryAnchorRequestSchemaZ.parse({
+                    ...body,
+                    proof: { ...body.proof, workspaceName: workspace.sessionName },
+                }));
+                // Delivery aliases are transport addresses, not canonical session names.
+                return result.status === "resolved"
+                    ? { ...result, proof: { ...result.proof, workspaceName: body.proof.workspaceName } }
+                    : result;
+            });
+            c.req.raw.signal.throwIfAborted();
+            return c.json(HistoryAnchorResponseSchemaZ.parse({ version: 1, server: scope.data, result }));
+        }
+        catch (error) {
+            if (error instanceof TmuxServerScopeError)
+                return c.json({ error: { code: "scope-unavailable" } }, error.code === "not-found" ? 404 : 409);
+            return c.json({ error: { code: "history-unavailable" } }, 503);
+        }
+    });
+}

package/packages/daemon/dist/command-center/tmux-servers.js

@@ -1,3 +1,5 @@
+import { mountTmuxServerHistoryAnchorRoute } from "./tmux-server-history-anchor.js";
+import { mountTmuxServerDiagnosticsRoute } from "./tmux-server-diagnostics.js";
 import { WindowSplitLayoutUnavailable } from "../terminal/mirror/window-split-authority.js";
 import { streamTmuxInteractions } from "./tmux-server-interaction-events.js";
 import { mountTmuxServerNativeBackingRoute } from "./tmux-server-native-backing.js";
@@ -10,6 +12,7 @@ import { z } from "zod";
 import { TmuxAgentOpenRequestSchemaZ, TmuxAgentOpenResponseSchemaZ, WorkspaceCatalogLiveSessionIdSchemaZ, WindowLinkTargetSchemaZ, WindowSplitLayoutResourceSchemaZ, TMUX_SERVERS_API_PATH, PANE_STREAM_ISSUE_PATH, TmuxServerIdSchemaZ, TmuxServerScopeSchemaZ, TmuxServersResourceSchemaZ, TmuxServerSessionsResourceSchemaZ, WorkspaceMultiplexerMutationRequestSchemaZ, WorkspacePaneCreateMutationRequestSchemaZ, WorkspaceSessionCreateArgumentsSchemaZ, } from "@tmux-ide/contracts";
 import { TmuxServerRegistrationSchemaZ, TmuxServerScopeError, } from "../lib/tmux-server-owners.js";
 import { WorkspaceMultiplexerError } from "../lib/workspace-multiplexer-verbs.js";
+import { WorkspacePaneCreationError } from "../lib/workspace-pane-creation.js";
 import { ownerBearerMatches } from "./owner-authority.js";
 import { mountPaneStreamIssueRoute } from "./pane-stream-issue.js";
 import { projectTerminalRuntimeInventory } from "./resources/terminal-runtime-inventory.js";
@@ -54,6 +57,8 @@ function failure(c, error) {
         return c.json({ error: { code: "split-layout-stale" } }, 409);
     if (error instanceof TmuxServerScopeError)
         return c.json({ error: { code: error.code } }, error.code === "not-found" ? 404 : error.code === "capacity" ? 429 : 409);
+    if (error instanceof WorkspacePaneCreationError && error.code === "harness_unavailable")
+        return c.json({ error: { code: "harness_unavailable" } }, 409);
     if (error instanceof WorkspaceMultiplexerError)
         return c.json({ error: { code: error.code } }, 409);
     if (error instanceof z.ZodError || error instanceof SyntaxError || error instanceof TypeError)
@@ -90,6 +95,12 @@ export function mountTmuxServerRoutes(app, options) {
         return c.json({ removed: true });
     }));
     const scoped = `${base}/:serverId/:generation`;
+    mountTmuxServerHistoryAnchorRoute(app, {
+        scopedPath: scoped,
+        owners: options.owners,
+        readBody: (request) => boundedJson(request, 4096),
+    });
+    mountTmuxServerDiagnosticsRoute(app, { scopedPath: scoped, owners: options.owners });
     mountTmuxServerEditorContextRoute(app, {
         scopedPath: scoped,
         owners: options.owners,