tmux-ide 2.9.10 → 2.9.12

package/packages/daemon/src/lib/tmux-server-owner.ts

@@ -1,3 +1,4 @@
+import type { LocalImageOwner } from "../terminal/graphics/local-image-owner.ts";
 import { shellEscape } from "./shell.ts";
 import {
   createNativeSplitCapabilityProbe,
@@ -68,6 +69,7 @@ import {
 } from "./tmux-server-generation-runner.ts";
 
 export interface NativeTmuxServerOwnerOptions {
+  readonly localImages?: LocalImageOwner;
   readonly environmentId: string;
   readonly serverId: string;
   readonly generation: string;
@@ -485,6 +487,7 @@ export async function createNativeTmuxServerOwner(options: NativeTmuxServerOwner
     }),
   });
   const paneStreamRuntime = createPaneStreamRuntime({
+    localImages: options.localImages,
     daemonInstanceId: generation,
     webSocketUrl: options.webSocketUrl,
     sessionRuntimeRegistry,

package/packages/daemon/src/terminal/graphics/local-image-owner.ts

@@ -0,0 +1,346 @@
+import { randomUUID } from "node:crypto";
+import { constants, type Stats } from "node:fs";
+import {
+  link,
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  realpath,
+  rename,
+  rmdir,
+  unlink,
+} from "node:fs/promises";
+import { basename, join } from "node:path";
+import { z } from "zod";
+import { LocalImageStore, type LocalImageLease } from "./local-image-store.ts";
+
+const OwnerSchema = z
+  .object({
+    generation: z.uuid(),
+    pid: z.number().int().positive().max(2147483647),
+    startedAt: z.iso.datetime(),
+  })
+  .strict();
+export type LocalImageOwnerIdentity = z.infer<typeof OwnerSchema>;
+const FileSchema = z
+  .object({
+    dev: z.number().nonnegative(),
+    ino: z.number().nonnegative(),
+    mode: z.number().int(),
+    size: z.number().nonnegative(),
+    mtimeMs: z.number(),
+    ctimeMs: z.number(),
+  })
+  .strict();
+const ManifestSchema = z
+  .object({
+    version: z.literal(1),
+    owner: OwnerSchema,
+    directory: FileSchema,
+    store: z
+      .object({ name: z.string().regex(/^local-images-[A-Za-z0-9]+$/u), identity: FileSchema })
+      .strict(),
+    files: z
+      .array(z.object({ name: z.string().regex(/^[a-f0-9]{64}$/u), identity: FileSchema }).strict())
+      .max(512),
+  })
+  .strict();
+type Manifest = z.infer<typeof ManifestSchema>;
+const record = (s: Stats) => ({
+  dev: s.dev,
+  ino: s.ino,
+  mode: s.mode,
+  size: s.size,
+  mtimeMs: s.mtimeMs,
+  ctimeMs: s.ctimeMs,
+});
+const same = (a: Pick<Stats, "dev" | "ino">, b: Pick<Stats, "dev" | "ino">) =>
+  a.dev === b.dev && a.ino === b.ino;
+const privateDir = (s: Stats) =>
+  s.isDirectory() && s.uid === process.getuid?.() && (s.mode & 0o077) === 0;
+const privateFile = (s: Stats) =>
+  s.isFile() && s.uid === process.getuid?.() && (s.mode & 0o077) === 0;
+async function directory(path: string, expected?: Pick<Stats, "dev" | "ino">) {
+  const stat = await lstat(path);
+  if (!privateDir(stat) || (expected && !same(stat, expected)))
+    throw new Error("Local image owner directory replaced");
+  return stat;
+}
+async function readManifest(path: string): Promise<{ manifest: Manifest; identity: Stats }> {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await file.stat();
+    if (!privateFile(stat) || stat.size > 256 * 1024)
+      throw new Error("Invalid local image manifest file");
+    const bytes = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = await file.read(bytes, offset, bytes.length - offset, offset);
+      if (!read.bytesRead) throw new Error("Truncated local image manifest");
+      offset += read.bytesRead;
+    }
+    const current = await lstat(path);
+    if (!same(stat, current) || current.size !== stat.size || current.mtimeMs !== stat.mtimeMs)
+      throw new Error("Local image manifest replaced");
+    const manifest = ManifestSchema.parse(JSON.parse(bytes.toString("utf8")));
+    if (new Set(manifest.files.map((f) => f.name)).size !== manifest.files.length)
+      throw new Error("Duplicate local image manifest file");
+    return { manifest, identity: stat };
+  } finally {
+    await file.close();
+  }
+}
+interface Options extends LocalImageOwnerIdentity {
+  /** Already proven private canonical root, while holding the startup claim. */
+  root: string;
+  store?: Pick<
+    Parameters<typeof LocalImageStore.create>[0],
+    "maxBytes" | "maxFiles" | "maxLeases" | "ttlMs"
+  >;
+}
+/** Per-generation lifecycle wrapper. The lease is never published before its
+ * owned file identity is persisted. A crash before journal publication leaves
+ * an unrecorded file, which cleanup deliberately preserves rather than guesses.
+ */
+export class LocalImageOwner {
+  #tail: Promise<unknown> = Promise.resolve();
+  #disposal: Promise<void> | undefined;
+  #manifestIdentity: Stats | undefined;
+  private constructor(
+    readonly path: string,
+    readonly identity: LocalImageOwnerIdentity,
+    private readonly store: LocalImageStore,
+    readonly root: string,
+    readonly rootIdentity: Stats,
+    readonly pathIdentity: Stats,
+    readonly storeIdentity: Stats,
+  ) {}
+  static async create(options: Options): Promise<LocalImageOwner> {
+    const identity = OwnerSchema.parse({
+      generation: options.generation,
+      pid: options.pid,
+      startedAt: options.startedAt,
+    });
+    const rootIdentity = await directory(options.root);
+    const root = await realpath(options.root);
+    await directory(root, rootIdentity);
+    const path = join(root, `local-images-${identity.generation}`);
+    await mkdir(path, { mode: 0o700 }); // Exclusive: never adopt another instance directory.
+    const pathIdentity = await directory(path);
+    const store = await LocalImageStore.create({
+      parent: path,
+      generation: identity.generation,
+      ...options.store,
+    });
+    const owner = new LocalImageOwner(
+      path,
+      identity,
+      store,
+      root,
+      rootIdentity,
+      pathIdentity,
+      await directory(store.directory),
+    );
+    try {
+      await owner.#persist();
+    } catch (error) {
+      await store.dispose().catch(() => {});
+      throw error;
+    }
+    return owner;
+  }
+  #serial<T>(run: () => Promise<T>): Promise<T> {
+    const result = this.#tail.then(run);
+    this.#tail = result.catch(() => {});
+    return result;
+  }
+  async #check() {
+    await directory(this.root, this.rootIdentity);
+    await directory(this.path, this.pathIdentity);
+  }
+  async #persist() {
+    await this.#check();
+    const files = await this.store.ownedFiles();
+    const manifest: Manifest = {
+      version: 1,
+      owner: this.identity,
+      directory: record(this.pathIdentity),
+      store: { name: basename(this.store.directory), identity: record(this.storeIdentity) },
+      files: files.map((f) => ({ name: basename(f.path), identity: record(f.identity) })),
+    };
+    const encoded = JSON.stringify(ManifestSchema.parse(manifest));
+    const path = join(this.path, "owner.json");
+    if (this.#manifestIdentity) {
+      const current = await readManifest(path);
+      if (
+        JSON.stringify(record(current.identity)) !== JSON.stringify(record(this.#manifestIdentity))
+      )
+        throw new Error("Local image manifest replaced");
+      // Leases are in-memory; only the owned file set is crash-recovery data.
+      // Reuse its durable record after checking identity, including on shared leases.
+      if (JSON.stringify(current.manifest) === encoded) return;
+    }
+    const temporary = join(this.path, `.owner-${randomUUID()}`);
+    const file = await open(
+      temporary,
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+      0o600,
+    );
+    const stat = await file.stat();
+    try {
+      await file.writeFile(encoded);
+      await file.sync();
+      await this.#check();
+      if (!same(await lstat(temporary), stat))
+        throw new Error("Local image manifest staging replaced");
+      if (this.#manifestIdentity) await rename(temporary, path);
+      else {
+        await link(temporary, path);
+        await unlink(temporary);
+      }
+      this.#manifestIdentity = await lstat(path);
+      if (!same(this.#manifestIdentity, stat))
+        throw new Error("Local image manifest publication replaced");
+    } finally {
+      await file.close();
+      await this.#removeStaging(temporary, stat);
+    }
+  }
+  async #removeStaging(path: string, identity: Stats): Promise<void> {
+    await this.#check();
+    let remaining: Stats;
+    try {
+      remaining = await lstat(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw error;
+    }
+    if (!remaining.isFile() || !same(remaining, identity))
+      throw new Error("Local image manifest cleanup refused replacement");
+    await unlink(path);
+  }
+  acquire(input: Parameters<LocalImageStore["acquire"]>[0]): Promise<LocalImageLease> {
+    // Store admission snapshots mutable bytes synchronously and bounds queued memory.
+    const lease = this.store.acquire(input);
+    void lease.catch(() => {});
+    return this.#serial(async () => {
+      const result = await lease;
+      try {
+        await this.#persist();
+      } catch (error) {
+        await this.store.release(result).catch(() => {});
+        throw error;
+      }
+      return result;
+    });
+  }
+  release(scope: Parameters<LocalImageStore["release"]>[0]): Promise<boolean> {
+    return this.#serial(async () => {
+      const result = await this.store.release(scope);
+      await this.#persist();
+      return result;
+    });
+  }
+  releaseClient(scope: Parameters<LocalImageStore["releaseClient"]>[0]): Promise<void> {
+    return this.#serial(async () => {
+      await this.store.releaseClient(scope);
+      await this.#persist();
+    });
+  }
+  dispose(): Promise<void> {
+    return (this.#disposal ??= this.#serial(async () => {
+      await this.#check();
+      await this.store.dispose();
+      const path = join(this.path, "owner.json");
+      const current = await readManifest(path);
+      if (
+        !this.#manifestIdentity ||
+        JSON.stringify(record(current.identity)) !== JSON.stringify(record(this.#manifestIdentity))
+      )
+        throw new Error("Local image manifest replaced");
+      await unlink(path);
+      await rmdir(this.path);
+    }));
+  }
+}
+
+/** No directory discovery. Caller supplies the exact predecessor read under the
+ * canonical claim, and its existing authoritative dead-owner check. PID reuse
+ * or uncertainty retains files even if generation/start identity differs.
+ */
+export async function cleanupLocalImageOwner(options: {
+  root: string;
+  owner: LocalImageOwnerIdentity;
+  proveDead: (owner: LocalImageOwnerIdentity) => Promise<boolean>;
+}): Promise<boolean> {
+  const owner = OwnerSchema.parse(options.owner);
+  const rootIdentity = await directory(options.root);
+  const path = join(options.root, `local-images-${owner.generation}`);
+  let pathIdentity: Stats;
+  try {
+    pathIdentity = await directory(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+  const manifestPath = join(path, "owner.json");
+  const { manifest, identity: manifestIdentity } = await readManifest(manifestPath);
+  if (
+    JSON.stringify(manifest.owner) !== JSON.stringify(owner) ||
+    !same(manifest.directory, pathIdentity)
+  )
+    return false;
+  if (!(await options.proveDead(owner))) return false;
+  try {
+    process.kill(owner.pid, 0);
+    return false;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") return false;
+  }
+  await directory(options.root, rootIdentity);
+  await directory(path, pathIdentity);
+  const storePath = join(path, manifest.store.name);
+  let storePresent = true;
+  try {
+    await directory(storePath, manifest.store.identity);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    storePresent = false;
+  }
+  for (const entry of storePresent ? manifest.files : []) {
+    await directory(options.root, rootIdentity);
+    await directory(path, pathIdentity);
+    await directory(storePath, manifest.store.identity);
+    const file = join(storePath, entry.name);
+    let stat: Stats;
+    try {
+      stat = await lstat(file);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+    if (!privateFile(stat) || JSON.stringify(record(stat)) !== JSON.stringify(entry.identity))
+      return false;
+    await unlink(file);
+  }
+  // Unknown/staging/replaced files make rmdir fail; none are removed speculatively.
+  try {
+    if (storePresent) await rmdir(storePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOTEMPTY") return false;
+    throw error;
+  }
+  const current = await readManifest(manifestPath);
+  if (JSON.stringify(record(current.identity)) !== JSON.stringify(record(manifestIdentity)))
+    return false;
+  if ((await readdir(path)).some((name) => name !== "owner.json")) return false;
+  await unlink(manifestPath);
+  try {
+    await rmdir(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOTEMPTY") return false;
+    throw error;
+  }
+  return true;
+}

package/packages/daemon/src/terminal/graphics/local-image-store.ts

@@ -0,0 +1,286 @@
+import { randomUUID, webcrypto } from "node:crypto";
+import { constants, type Stats } from "node:fs";
+import { chmod, link, lstat, mkdtemp, open, realpath, rmdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+interface Scope {
+  readonly generation: string;
+  readonly client: string;
+}
+export interface LocalImageLease extends Scope {
+  readonly id: string;
+  readonly digest: string;
+  readonly path: string;
+  readonly bytes: number;
+  readonly expiresAt: number;
+}
+interface Entry {
+  readonly path: string;
+  readonly bytes: number;
+  readonly identity: Stats;
+}
+interface Options {
+  /** Existing private, daemon-owned directory; never an application-provided path. */
+  readonly parent: string;
+  readonly generation: string;
+  readonly maxBytes?: number;
+  readonly maxFiles?: number;
+  readonly maxLeases?: number;
+  readonly ttlMs?: number;
+  readonly now?: () => number;
+}
+const IMAGE_LIMIT = 64 * 1024 * 1024;
+const same = (a: Stats, b: Stats) => a.dev === b.dev && a.ino === b.ino;
+const privateDirectory = (s: Stats) =>
+  s.isDirectory() && s.uid === process.getuid?.() && (s.mode & 0o077) === 0;
+const bounded = (value: number, max: number) =>
+  Number.isSafeInteger(value) && value > 0 && value <= max;
+const identity = (value: string) =>
+  value.length > 0 &&
+  value.length <= 512 &&
+  ![...value].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127);
+
+/** Immutable copy-reduced transport files, not a persistent asset cache. Only owner
+ * metadata crosses this API. A live daemon expires crashed clients' leases; its
+ * owner must clean abandoned instance directories after a daemon process crash.
+ * The private parent is trusted: Node has no descriptor-relative unlink primitive.
+ */
+export class LocalImageStore {
+  readonly #entries = new Map<string, Entry>();
+  readonly #leases = new Map<string, LocalImageLease>();
+  readonly #maxBytes: number;
+  readonly #maxFiles: number;
+  readonly #maxLeases: number;
+  readonly #ttl: number;
+  readonly #now: () => number;
+  readonly #timer: ReturnType<typeof setInterval>;
+  #tail: Promise<unknown> = Promise.resolve();
+  #bytes = 0;
+  #pendingBytes = 0;
+  #pending = 0;
+  #closed = false;
+  private constructor(
+    readonly directory: string,
+    readonly generation: string,
+    readonly directoryIdentity: Stats,
+    options: Options,
+  ) {
+    this.#maxBytes = options.maxBytes ?? 256 * 1024 * 1024;
+    this.#maxFiles = options.maxFiles ?? 512;
+    this.#maxLeases = options.maxLeases ?? 1024;
+    this.#ttl = options.ttlMs ?? 30_000;
+    this.#now = options.now ?? Date.now;
+    this.#timer = setInterval(() => void this.sweep().catch(() => {}), Math.min(this.#ttl, 1000));
+    this.#timer.unref();
+  }
+  static async create(options: Options): Promise<LocalImageStore> {
+    if (
+      !identity(options.generation) ||
+      !bounded(options.maxBytes ?? 256 * 1024 * 1024, 256 * 1024 * 1024) ||
+      !bounded(options.maxFiles ?? 512, 512) ||
+      !bounded(options.maxLeases ?? 1024, 1024) ||
+      !bounded(options.ttlMs ?? 30_000, 60_000)
+    )
+      throw new Error("Invalid local image store bounds");
+    const parentIdentity = await lstat(options.parent);
+    if (!privateDirectory(parentIdentity)) throw new Error("Local image parent is not private");
+    const parent = await realpath(options.parent);
+    if (!same(parentIdentity, await lstat(parent))) throw new Error("Local image parent replaced");
+    const directory = await mkdtemp(join(parent, "local-images-"));
+    await chmod(directory, 0o700);
+    const stat = await lstat(directory);
+    if (!privateDirectory(stat)) throw new Error("Local image directory is not private");
+    return new LocalImageStore(directory, options.generation, stat, options);
+  }
+  #serial<T>(run: () => Promise<T>): Promise<T> {
+    const result = this.#tail.then(run);
+    this.#tail = result.catch(() => {});
+    return result;
+  }
+  async #checkDirectory(): Promise<void> {
+    const stat = await lstat(this.directory);
+    if (!privateDirectory(stat) || !same(stat, this.directoryIdentity))
+      throw new Error("Local image directory replaced");
+  }
+  #scope(scope: Scope): void {
+    if (scope.generation !== this.generation || !identity(scope.client))
+      throw new Error("Local image scope mismatch");
+  }
+  async #checkFile(entry: Entry): Promise<void> {
+    await this.#checkDirectory();
+    const stat = await lstat(entry.path);
+    if (
+      !stat.isFile() ||
+      !same(stat, entry.identity) ||
+      stat.size !== entry.bytes ||
+      stat.mode !== entry.identity.mode ||
+      stat.mtimeMs !== entry.identity.mtimeMs ||
+      stat.ctimeMs !== entry.identity.ctimeMs
+    )
+      throw new Error("Local image file replaced");
+  }
+  acquire(
+    input: Scope & { readonly digest: string; readonly bytes: Uint8Array },
+  ): Promise<LocalImageLease> {
+    const { generation, client, digest: requestedDigest } = input;
+    this.#scope({ generation, client });
+    if (
+      this.#closed ||
+      !/^[a-f0-9]{32}$/u.test(input.digest) ||
+      !bounded(input.bytes.byteLength, Math.min(IMAGE_LIMIT, this.#maxBytes)) ||
+      this.#pending >= this.#maxLeases ||
+      input.bytes.byteLength > this.#maxBytes - this.#pendingBytes
+    )
+      return Promise.reject(new Error("Local image acquisition unavailable"));
+    // Detach caller memory before the first await; queued acquisition memory is bounded too.
+    const data = Uint8Array.from(input.bytes);
+    this.#pending++;
+    this.#pendingBytes += data.byteLength;
+    return this.#serial(async () => {
+      if (this.#closed) throw new Error("Local image store closed");
+      await this.#expire();
+      await this.#checkDirectory();
+      if (this.#leases.size >= this.#maxLeases) throw new Error("Local image lease bound");
+      const fullDigest = Buffer.from(await webcrypto.subtle.digest("SHA-256", data)).toString(
+        "hex",
+      );
+      const digest = fullDigest.slice(0, 32);
+      if (digest !== requestedDigest) throw new Error("Local image digest mismatch");
+      let entry = this.#entries.get(digest);
+      if (entry) {
+        if (entry.path !== join(this.directory, fullDigest))
+          throw new Error("Local image digest collision");
+        await this.#checkFile(entry);
+      } else {
+        if (this.#entries.size >= this.#maxFiles || data.byteLength > this.#maxBytes - this.#bytes)
+          throw new Error("Local image storage bound");
+        entry = await this.#write(fullDigest, data);
+        this.#entries.set(digest, entry);
+        this.#bytes += entry.bytes;
+      }
+      const lease = Object.freeze({
+        id: randomUUID(),
+        generation: this.generation,
+        client,
+        digest,
+        path: entry.path,
+        bytes: entry.bytes,
+        expiresAt: this.#now() + this.#ttl,
+      });
+      this.#leases.set(lease.id, lease);
+      return lease;
+    }).finally(() => {
+      this.#pending--;
+      this.#pendingBytes -= data.byteLength;
+    });
+  }
+  async #write(digest: string, data: Uint8Array): Promise<Entry> {
+    const path = join(this.directory, digest);
+    const temporary = join(this.directory, `.pending-${randomUUID()}`);
+    const file = await open(
+      temporary,
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+      0o600,
+    );
+    let temporaryIdentity = await file.stat();
+    try {
+      await file.writeFile(data);
+      await file.chmod(0o400);
+      temporaryIdentity = await file.stat();
+      await this.#checkDirectory();
+      const current = await lstat(temporary);
+      if (!same(current, temporaryIdentity) || !current.isFile())
+        throw new Error("Local image staging replaced");
+      // link is atomic and fails if a digest path already exists; never overwrite it.
+      await link(temporary, path);
+    } finally {
+      await file.close();
+      await this.#unlinkOwned(temporary, temporaryIdentity);
+    }
+    const stat = await lstat(path);
+    if (!same(stat, temporaryIdentity) || !stat.isFile() || stat.size !== data.byteLength)
+      throw new Error("Local image publication replaced");
+    return { path, bytes: data.byteLength, identity: stat };
+  }
+  async #unlinkOwned(path: string, expected: Stats, immutable = false): Promise<void> {
+    await this.#checkDirectory();
+    let stat: Stats;
+    try {
+      stat = await lstat(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw error;
+    }
+    if (
+      !stat.isFile() ||
+      !same(stat, expected) ||
+      (immutable &&
+        (stat.size !== expected.size ||
+          stat.mode !== expected.mode ||
+          stat.uid !== expected.uid ||
+          stat.mtimeMs !== expected.mtimeMs ||
+          stat.ctimeMs !== expected.ctimeMs))
+    )
+      throw new Error("Local image cleanup refused replacement");
+    await unlink(path);
+  }
+  async #collect(): Promise<void> {
+    const referenced = new Set([...this.#leases.values()].map((lease) => lease.digest));
+    for (const [digest, entry] of this.#entries) {
+      if (referenced.has(digest)) continue;
+      // Inodes can be reused after unlink. Published files must retain their
+      // immutable metadata; staging links intentionally change ctime instead.
+      await this.#unlinkOwned(entry.path, entry.identity, true);
+      this.#entries.delete(digest);
+      this.#bytes -= entry.bytes;
+    }
+  }
+  async #expire(): Promise<void> {
+    const now = this.#now();
+    for (const [id, lease] of this.#leases) if (lease.expiresAt <= now) this.#leases.delete(id);
+    await this.#collect();
+  }
+  release(scope: Scope & { readonly id: string }): Promise<boolean> {
+    return this.#serial(async () => {
+      this.#scope(scope);
+      const lease = this.#leases.get(scope.id);
+      if (!lease || lease.client !== scope.client) return false;
+      this.#leases.delete(scope.id);
+      await this.#collect();
+      return true;
+    });
+  }
+  releaseClient(scope: Scope): Promise<void> {
+    return this.#serial(async () => {
+      this.#scope(scope);
+      for (const [id, lease] of this.#leases)
+        if (lease.client === scope.client) this.#leases.delete(id);
+      await this.#collect();
+    });
+  }
+  sweep(): Promise<void> {
+    return this.#serial(() => this.#expire());
+  }
+  /** Bounded lifecycle manifest; no image bytes. Caller persists before publishing a lease. */
+  ownedFiles(): Promise<{ path: string; identity: Stats }[]> {
+    return this.#serial(async () => {
+      await this.#checkDirectory();
+      const files = [];
+      for (const entry of this.#entries.values()) {
+        await this.#checkFile(entry);
+        files.push({ path: entry.path, identity: entry.identity });
+      }
+      return files;
+    });
+  }
+  dispose(): Promise<void> {
+    this.#closed = true;
+    clearInterval(this.#timer);
+    return this.#serial(async () => {
+      this.#leases.clear();
+      await this.#collect();
+      await this.#checkDirectory();
+      await rmdir(this.directory); // Not recursive: unexpected entries must survive.
+    });
+  }
+}

package/packages/daemon/src/terminal/mirror/mirror-service.ts

@@ -237,14 +237,31 @@ export class MirrorService {
     }
   }
 
-  async describeSessionAuthority(session: string): Promise<{
+  async describeSessionAuthority(
+    session: string,
+    expectedSemanticPaneIds?: readonly string[],
+  ): Promise<{
     readonly description: MirrorSessionDescription;
     readonly runtimeSessionId: string;
   }> {
     const entry = await this.acquire(session);
     try {
       const identity = await entry.channel.attachedSessionIdentity();
-      return { description: entry.channel.describe(), runtimeSessionId: identity.runtimeSessionId };
+      let description = entry.channel.describe();
+      if (
+        expectedSemanticPaneIds?.some(
+          (id) => !description.panes.some((pane) => pane.semanticPaneId === id),
+        )
+      ) {
+        // A mutation receipt and fresh catalog can precede debounced mirror
+        // discovery. Join the verified native inventory before declaring a
+        // requested pane absent; never substitute receipt IDs for tmux truth.
+        await entry.channel.describeTrustedInventory(identity.runtimeSessionId, true);
+        description = entry.channel.describe();
+      }
+      if (this.disposed || entry.retired || this.channels.get(session) !== entry)
+        throw new Error("Mirror authority retired during description");
+      return { description, runtimeSessionId: identity.runtimeSessionId };
     } finally {
       this.release(session, entry);
     }