tmux-ide 2.9.6 → 2.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.9.6",
+  "version": "2.9.7",
   "description": "The open-source workspace for coding agents: run Claude Code, Codex and other agents in tmux with live status",
   "type": "module",
   "bin": {

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,18 @@ 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();
+
 export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamInputFrameSchemaZ,
   PaneStreamConsumedFrameSchemaZ,
@@ -354,6 +373,7 @@ export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamAuthorityRequestFrameSchemaZ,
   PaneStreamAuthorityReleaseFrameSchemaZ,
   PaneStreamClockProbeFrameSchemaZ,
+  PaneStreamTerminalGraphicsRequestFrameSchemaZ,
 ]);
 export type PaneStreamClientFrame = z.infer<typeof PaneStreamClientFrameSchemaZ>;
 
@@ -645,6 +665,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 +784,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,92 @@
+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;
+/** 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. */
+export const TERMINAL_GRAPHICS_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);
+export const TerminalGraphicsFormatSchemaZ = z.enum(["png", "rgba", "rgb"]);
+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),
+  })
+  .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,190 @@
+/**
+ * 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[] {
+  const placements: TerminalGraphicsPlacement[] = [];
+  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({
+        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,
+      });
+    }
+  }
+  placements.push(...state.placements);
+  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,

package/packages/daemon/dist/lib/canonical-daemon-bootstrap.js

@@ -32,6 +32,13 @@ function spawnOwner(entryPath, cwd) {
         });
     });
 }
+class ShutdownTransportError extends Error {
+    original;
+    constructor(original) {
+        super("Canonical daemon shutdown transport failed.", { cause: original });
+        this.original = original;
+    }
+}
 async function shutdownOlderOwner(info) {
     const headers = { "content-type": "application/json" };
     if (info.authToken)
@@ -45,6 +52,8 @@ async function shutdownOlderOwner(info) {
             expectedInstanceId: info.instanceId,
         }),
         signal: AbortSignal.timeout(2_000),
+    }).catch((error) => {
+        throw new ShutdownTransportError(error);
     });
     const envelope = (await response.json().catch(() => null));
     // The authenticated handler verifies expectedInstanceId before reporting this
@@ -141,7 +150,18 @@ async function replaceOlderCanonicalDaemon(deps, info, timeoutMs, expectedProduc
             "tmux-ide --headless --supervised <id> before restarting it. " +
             "The existing daemon has been left running.", { reason: "canonical-record-invalid" });
     }
-    await deps.shutdownOlderOwner(info);
+    let transportFailure;
+    try {
+        await deps.shutdownOlderOwner(info);
+    }
+    catch (error) {
+        if (!(error instanceof ShutdownTransportError))
+            throw error;
+        transportFailure = error;
+    }
+    // A competing upgrader may close the authenticated owner's listener before
+    // removing its record. Observe retirement, without repeating the mutation.
+    // A transport failure alone never authorizes starting a replacement.
     const deadline = deps.now() + timeoutMs;
     while (deps.now() < deadline) {
         const state = deps.inspect();
@@ -153,6 +173,8 @@ async function replaceOlderCanonicalDaemon(deps, info, timeoutMs, expectedProduc
             return;
         await deps.sleep(25);
     }
+    if (transportFailure)
+        throw transportFailure.original;
     throw new DaemonBootstrapError("control-timeout", "The older canonical daemon did not retire after accepting the version upgrade.", { reason: "protocol-mismatch" });
 }
 async function assertServerIntent(deps, info, identity, intent) {

package/packages/daemon/dist/lib/daemon-embed.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { TmuxServerVersionSchemaZ } from "@tmux-ide/contracts";
 import { createNativeSplitCapabilityProbe, createNativeSplitReadiness, } from "./native-split-capability.js";
 import { executeCanonicalSplitMutation } from "./canonical-split-mutation.js";
 import { createGuardedNativeSplitResize } from "./guarded-native-split-resize.js";
@@ -956,6 +957,7 @@ async function startEmbeddedDaemonGeneration(opts) {
         let paneStreamRuntime = null;
         let serverOwners = null;
         let defaultEditorContextRetired = false;
+        const defaultDiagnosticsLifetime = new AbortController();
         const defaultSessionCreator = createNativeTmuxSessionCreator({
             generation: instanceId,
             registry: workspaceRegistry,
@@ -1287,6 +1289,24 @@ async function startEmbeddedDaemonGeneration(opts) {
                 stateDirectory: resolveRuntimeNamespace().runtimeDir,
                 webSocketBaseUrl: canonicalDaemonUrl("ws", bindHostname, port),
                 defaultOwner: {
+                    readServerVersion: async (signal) => {
+                        const assertCurrent = () => {
+                            if (defaultEditorContextRetired ||
+                                serverOwners?.defaultRetired ||
+                                !initialNativeServerIdentity)
+                                throw new Error("Default tmux diagnostics owner is unavailable");
+                        };
+                        assertCurrent();
+                        const combined = AbortSignal.any([
+                            defaultDiagnosticsLifetime.signal,
+                            ...(signal ? [signal] : []),
+                        ]);
+                        combined.throwIfAborted();
+                        const output = await fleetFactsTmuxRunner(["display-message", "-p", "#{version}"], combined);
+                        combined.throwIfAborted();
+                        assertCurrent();
+                        return TmuxServerVersionSchemaZ.parse(output.trim());
+                    },
                     get interactionObservation() {
                         return interactionObservation;
                     },
@@ -1375,6 +1395,7 @@ async function startEmbeddedDaemonGeneration(opts) {
                     paneStreamRuntime,
                     dispose: async () => {
                         defaultEditorContextRetired = true;
+                        defaultDiagnosticsLifetime.abort();
                         sessionMonitor?.stop();
                         paneSourceCredentials.dispose();
                         const transportResults = await Promise.allSettled([