@cueloop/daemon 0.1.0-alpha.80 → 0.1.0-alpha.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.80",
+  "version": "0.1.0-alpha.81",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -27,7 +27,9 @@
     "./validate": "./src/validate.ts",
     "./paths": "./src/paths.ts",
     "./retention": "./src/retention.ts",
-    "./herdr-pane": "./src/herdr-pane.ts",
+    "./herdr-thread-surface": "./src/herdr-thread-surface.ts",
+    "./ghostty-thread-surface": "./src/ghostty-thread-surface.ts",
+    "./thread-surface-config": "./src/thread-surface-config.ts",
     "./herdr-split": "./src/herdr-split.ts",
     "./share-blob": "./src/share-blob.ts",
     "./curate": "./src/curate.ts"
@@ -36,9 +38,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.80",
+    "@cueloop/schema": "0.1.0-alpha.81",
     "@pierre/diffs": "^1.4.1",
     "effect": "^4.0.0-rc.115",
+    "smol-toml": "^1.8.0",
     "valibot": "^1.4.2"
   },
   "engines": {

package/src/api.test.ts

@@ -24,6 +24,21 @@ beforeEach(() => {
 afterEach(() => rmSync(home, { recursive: true, force: true }));
 
 describe("session lifecycle", () => {
+  test("startup retention clears native surface handles for expired Threads", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    core.store.upsert({ ...session, status: "resolved", createdAt: "2020-01-01T00:00:00Z" });
+    core.herdrSetThreadSurface(session.id, { tabId: "tab-old", paneId: "pane-old" });
+    core.ghosttySetThreadSurface(session.id, { terminalId: "terminal-old" });
+
+    const restarted = new DaemonCore(home);
+
+    expect(restarted.store.get(session.id)).toBeUndefined();
+    expect(restarted.herdrGetThreadSurface(session.id)).toBeNull();
+    expect(restarted.ghosttyGetThreadSurface(session.id)).toBeNull();
+    restarted.dispose();
+  });
+
   test("create → get → list", () => {
     // Act
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });

package/src/api.ts

@@ -52,7 +52,14 @@ import {
 import { curateDiff } from "./curate";
 import { ThreadStore, withHistory } from "./store";
 import { pruneExpiredSessions, resolveCleanupPeriodDays } from "./retention";
-import { HerdrTabStore, type HerdrTabHandle } from "./herdr-tab-store";
+import {
+  HerdrThreadSurfaceStore,
+  type HerdrThreadSurfaceHandle,
+} from "./herdr-thread-surface-store";
+import {
+  GhosttyThreadSurfaceStore,
+  type GhosttyThreadSurfaceHandle,
+} from "./ghostty-thread-surface-store";
 import { HarnessStateStore } from "./harness-state-store";
 import { DiffWatcher } from "./diff-watcher";
 import { PrReviewPoller } from "./pr-poller";
@@ -88,7 +95,8 @@ type EventListener = (event: DaemonEvent) => void;
 
 export class DaemonCore {
   readonly store: ThreadStore;
-  readonly herdrTabs: HerdrTabStore;
+  readonly herdrThreadSurfaces: HerdrThreadSurfaceStore;
+  readonly ghosttyThreadSurfaces: GhosttyThreadSurfaceStore;
   readonly harnessState: HarnessStateStore;
   private waiters = new Map<string, ((session: Thread) => void)[]>();
   private listeners = new Set<EventListener>();
@@ -111,13 +119,19 @@ export class DaemonCore {
     this.store.recover();
     this.harnessState = new HarnessStateStore(home);
     for (const session of this.store.list()) this.reconcileDeliveries(session);
-    pruneExpiredSessions(
+    this.herdrThreadSurfaces = new HerdrThreadSurfaceStore(home);
+    this.ghosttyThreadSurfaces = new GhosttyThreadSurfaceStore(home);
+    const expiredThreadIds = pruneExpiredSessions(
       this.store,
       resolveCleanupPeriodDays(),
       Date.now(),
       this.harnessState.pendingThreadIds(),
     );
-    this.herdrTabs = new HerdrTabStore(home);
+
+    for (const threadId of expiredThreadIds) {
+      this.herdrThreadSurfaces.delete(threadId);
+      this.ghosttyThreadSurfaces.delete(threadId);
+    }
     this.diffWatcher = new DiffWatcher((repoRoot) => void this.refreshDiffsForRepo(repoRoot));
     this.prPoller = new PrReviewPoller((sessionId) => void this.sessionRefreshPrDiff(sessionId));
     // resume hot-reload for diff sessions that survived a daemon restart
@@ -132,13 +146,29 @@ export class DaemonCore {
     this.prPoller.close();
   }
 
-  /** The herdr tab opened for a review, if any (adapter scratch, not on the session). */
-  herdrGetTab(sessionId: string): HerdrTabHandle | null {
-    return this.herdrTabs.get(sessionId);
+  /** The Herdr Thread surface handle, kept outside the canonical Thread. */
+  herdrGetThreadSurface(sessionId: string): HerdrThreadSurfaceHandle | null {
+    return this.herdrThreadSurfaces.get(sessionId);
+  }
+
+  herdrSetThreadSurface(sessionId: string, handle: HerdrThreadSurfaceHandle): void {
+    this.herdrThreadSurfaces.set(sessionId, handle);
+  }
+
+  ghosttyGetThreadSurface(sessionId: string): GhosttyThreadSurfaceHandle | null {
+    return this.ghosttyThreadSurfaces.get(sessionId);
+  }
+
+  ghosttySetThreadSurface(sessionId: string, handle: GhosttyThreadSurfaceHandle): void {
+    this.ghosttyThreadSurfaces.set(sessionId, handle);
   }
 
-  herdrSetTab(sessionId: string, handle: HerdrTabHandle): void {
-    this.herdrTabs.set(sessionId, handle);
+  ghosttyClaimThreadSurface(sessionId: string): boolean {
+    return this.ghosttyThreadSurfaces.claim(sessionId);
+  }
+
+  ghosttyReleaseThreadSurface(sessionId: string): void {
+    this.ghosttyThreadSurfaces.release(sessionId);
   }
 
   harnessBind(input: {
@@ -162,6 +192,10 @@ export class DaemonCore {
     return binding;
   }
 
+  harnessBindingsForSession(harness: string, harnessSessionId: string): HarnessBinding[] {
+    return this.harnessState.bindingsForSession(harness, harnessSessionId);
+  }
+
   harnessConsumeApprovedRetry(bindingId: string, messageId: string, content: string): boolean {
     const binding = this.harnessState.binding(bindingId);
 
@@ -573,7 +607,8 @@ export class DaemonCore {
     if (!this.store.delete(id)) throw new DaemonError("not_found", `no session ${id}`);
     if (session) this.untrackLiveDiffSession(session);
     this.diffRefreshGenerations.delete(id);
-    this.herdrTabs.delete(id);
+    this.herdrThreadSurfaces.delete(id);
+    this.ghosttyThreadSurfaces.delete(id);
     this.emit("inbox.changed", id);
   }
 

package/src/capabilities.ts

@@ -61,12 +61,17 @@ const PRIMITIVE_ROLES = {
   "session.sendMessage": "owner",
   "harness.bind": "owner",
   "harness.getBinding": "owner",
+  "harness.bindingsForSession": "owner",
   "harness.consumeApprovedRetry": "owner",
   "delivery.pending": "owner",
   "delivery.acknowledge": "owner",
   "session.submitRevision": "owner",
-  "herdr.getTab": "owner",
-  "herdr.setTab": "owner",
+  "herdr.getThreadSurface": "owner",
+  "herdr.setThreadSurface": "owner",
+  "ghostty.getThreadSurface": "owner",
+  "ghostty.setThreadSurface": "owner",
+  "ghostty.claimThreadSurface": "owner",
+  "ghostty.releaseThreadSurface": "owner",
 } as const satisfies Record<MethodName, Audience>;
 
 /** Whether `role` may call `method`. */

package/src/client.ts

@@ -4,7 +4,19 @@
  * autostart spawns a detached daemon when the socket is dead, then attaches.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { createConnection } from "node:net";
+import { join } from "node:path";
 import * as v from "valibot";
 import type {
   Annotation,
@@ -29,7 +41,8 @@ import {
   type Response,
 } from "./protocol";
 import type { DaemonRole } from "./capabilities";
-import type { HerdrTabHandle } from "./herdr-tab-store";
+import type { HerdrThreadSurfaceHandle } from "./herdr-thread-surface-store";
+import type { GhosttyThreadSurfaceHandle } from "./ghostty-thread-surface-store";
 import type { SharedMerge } from "./api";
 
 export type { SharedMerge } from "./api";
@@ -67,7 +80,14 @@ const EmptyResultSchema = v.object({});
 // undefined, which never equals this build - so it is treated as stale and replaced
 const PingResultSchema = v.object({ pid: v.number(), version: v.optional(v.string()) });
 const RefreshDiffResultSchema = v.object({ changed: v.boolean() });
-const HerdrTabResultSchema = v.nullable(v.object({ tabId: v.string(), paneId: v.string() }));
+const HerdrThreadSurfaceResultSchema = v.nullable(
+  v.object({
+    tabId: v.string(),
+    paneId: v.string(),
+    mode: v.optional(v.picklist(["tab", "pane"])),
+  }),
+);
+const GhosttyThreadSurfaceResultSchema = v.nullable(v.object({ terminalId: v.string() }));
 
 /**
  * The session primitives the review controller drives. DaemonClient is the local
@@ -146,6 +166,7 @@ export interface ThreadClient {
     harnessSessionId: string,
   ): Promise<HarnessBinding>;
   harnessGetBinding?(bindingId: string): Promise<HarnessBinding>;
+  harnessBindingsForSession?(harness: string, harnessSessionId: string): Promise<HarnessBinding[]>;
   harnessConsumeApprovedRetry?(
     bindingId: string,
     messageId: string,
@@ -184,14 +205,16 @@ function readOwnerToken(home: string): string | undefined {
 }
 
 export class DaemonClient implements ThreadClient {
-  private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
+  private socket: { end(): void } | null = null;
   private writer: BackpressureWriter | null = null;
+  private connectionEpoch = 0;
   private pending = new Map<number, PendingRequest>();
   /** The connected daemon's build version and pid, learned from the ping handshake. */
   private daemonVersion: string | undefined;
   private daemonPid: number | undefined;
   private nextId = 1;
   private eventListeners = new Set<(event: EventFrame) => void>();
+  private disconnectListeners = new Set<() => void>();
   private closed = false;
   private role: DaemonRole = "owner";
   private author: string | undefined;
@@ -252,11 +275,12 @@ export class DaemonClient implements ThreadClient {
     // the old daemon removes its socket in stop(); wait so the new one binds cleanly
     const deadline = Date.now() + 5_000;
 
-    while (Date.now() < deadline && existsSync(path)) await Bun.sleep(50);
+    while (Date.now() < deadline && existsSync(path)) await sleep(50);
   }
 
   /** Reset per-connection state so a fresh dial() can reuse this client instance. */
   private resetConnection(): void {
+    this.connectionEpoch += 1;
     this.socket = null;
     this.writer = null;
     this.closed = false;
@@ -267,47 +291,96 @@ export class DaemonClient implements ThreadClient {
 
   /** Spawn a detached daemon and dial the lock owner until it answers. */
   private async attachFreshDaemon(home: string, path: string): Promise<DaemonClient> {
-    spawnDaemon(home);
+    const startupLogPath = spawnDaemon(home);
     // Generous: a cold or loaded machine pays for a runtime start before the
     // socket exists, and giving up early looks to callers like a broken daemon.
     const deadline = Date.now() + Number(process.env.CUELOOP_START_TIMEOUT_MS ?? 30_000);
     let lastError: unknown;
 
-    while (Date.now() < deadline) {
-      try {
-        await this.dial(path);
-
-        return this;
-      } catch (err) {
-        lastError = err;
-        await Bun.sleep(50);
+    try {
+      while (Date.now() < deadline) {
+        try {
+          await this.dial(path);
+          if (this.daemonVersion !== DAEMON_VERSION) {
+            this.close();
+            if (typeof Bun === "undefined") {
+              throw new DaemonClientError(
+                "version_mismatch",
+                `installed cueloop is ${this.daemonVersion ?? "unknown"}, but this adapter is ${DAEMON_VERSION}; run cueloop update`,
+              );
+            }
+
+            throw new Error("daemon autostarted an older build");
+          }
+
+          return this;
+        } catch (err) {
+          if (err instanceof DaemonClientError) throw err;
+          this.socket?.end();
+          this.resetConnection();
+          lastError = err;
+          await sleep(50);
+        }
       }
+      const output = readFileSync(startupLogPath, "utf8").trim();
+      const detail = output ? `\ndaemon startup output:\n${output.slice(-4_096)}` : "";
+
+      throw new Error(`daemon did not come up at ${path}: ${String(lastError)}${detail}`);
+    } finally {
+      rmSync(startupLogPath, { force: true });
     }
-    throw new Error(`daemon did not come up at ${path}: ${String(lastError)}`);
   }
 
   private async dial(path: string): Promise<void> {
     const buffer = new LineBuffer();
-
-    this.socket = await Bun.connect({
-      unix: path,
-      socket: {
-        data: (_socket, data) => {
-          buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
+    const epoch = ++this.connectionEpoch;
+
+    const close = () => {
+      if (this.connectionEpoch !== epoch) return;
+      this.closed = true;
+      for (const pendingRequest of this.pending.values())
+        pendingRequest.reject(new Error("daemon connection closed"));
+      this.pending.clear();
+      for (const listener of this.disconnectListeners) listener();
+    };
+
+    if (typeof Bun !== "undefined") {
+      const socket = await Bun.connect({
+        unix: path,
+        socket: {
+          data: (_socket, data) => {
+            buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
+          },
+          drain: () => this.writer?.drain(),
+          close,
+          error() {},
         },
-        drain: () => {
-          this.writer?.drain();
-        },
-        close: () => {
-          this.closed = true;
-          for (const pendingRequest of this.pending.values())
-            pendingRequest.reject(new Error("daemon connection closed"));
-          this.pending.clear();
+      });
+
+      this.socket = socket;
+      this.writer = new BackpressureWriter(socket);
+    } else {
+      const socket = createConnection(path);
+
+      await new Promise<void>((resolve, reject) => {
+        socket.once("connect", resolve);
+        socket.once("error", reject);
+      });
+      socket.on("data", (data) => {
+        buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
+      });
+      socket.on("close", close);
+      socket.on("error", () => {});
+      this.socket = socket;
+      // Node queues the complete Buffer internally when write returns false.
+      this.writer = new BackpressureWriter({
+        write(data) {
+          socket.write(data);
+
+          return data.length;
         },
-        error() {},
-      },
-    });
-    this.writer = new BackpressureWriter(this.socket);
+      });
+    }
     // Verify liveness: a dead socket file accepts connects on some platforms
     // only to fail later, so a ping is the actual handshake. It also carries the
     // daemon's build version and pid, so connect() can replace a stale daemon.
@@ -339,6 +412,13 @@ export class DaemonClient implements ThreadClient {
     return () => this.eventListeners.delete(listener);
   }
 
+  /** Notify an adapter when its daemon socket closes so it can reconnect and replay Messages. */
+  onDisconnect(listener: () => void): () => void {
+    this.disconnectListeners.add(listener);
+
+    return () => this.disconnectListeners.delete(listener);
+  }
+
   private routeInboundFrame(line: string): void {
     let frame;
 
@@ -562,6 +642,13 @@ export class DaemonClient implements ThreadClient {
   harnessGetBinding(bindingId: string): Promise<HarnessBinding> {
     return this.request("harness.getBinding", { bindingId }, HarnessBindingSchema);
   }
+  harnessBindingsForSession(harness: string, harnessSessionId: string): Promise<HarnessBinding[]> {
+    return this.request(
+      "harness.bindingsForSession",
+      { harness, harnessSessionId },
+      v.array(HarnessBindingSchema),
+    );
+  }
   harnessConsumeApprovedRetry(
     bindingId: string,
     messageId: string,
@@ -591,12 +678,24 @@ export class DaemonClient implements ThreadClient {
       ThreadRecordSchema,
     );
   }
-  /** herdr adapter scratch: the tab opened for a review; local-only, off the ThreadClient contract. */
-  herdrGetTab(id: string): Promise<HerdrTabHandle | null> {
-    return this.request("herdr.getTab", { id }, HerdrTabResultSchema);
+  /** Read Herdr's local Thread surface handle, outside the ThreadClient contract. */
+  herdrGetThreadSurface(id: string): Promise<HerdrThreadSurfaceHandle | null> {
+    return this.request("herdr.getThreadSurface", { id }, HerdrThreadSurfaceResultSchema);
+  }
+  async herdrSetThreadSurface(id: string, handle: HerdrThreadSurfaceHandle): Promise<void> {
+    await this.request("herdr.setThreadSurface", { id, ...handle }, EmptyResultSchema);
+  }
+  ghosttyGetThreadSurface(id: string): Promise<GhosttyThreadSurfaceHandle | null> {
+    return this.request("ghostty.getThreadSurface", { id }, GhosttyThreadSurfaceResultSchema);
+  }
+  async ghosttySetThreadSurface(id: string, handle: GhosttyThreadSurfaceHandle): Promise<void> {
+    await this.request("ghostty.setThreadSurface", { id, ...handle }, EmptyResultSchema);
   }
-  async herdrSetTab(id: string, handle: HerdrTabHandle): Promise<void> {
-    await this.request("herdr.setTab", { id, ...handle }, EmptyResultSchema);
+  ghosttyClaimThreadSurface(id: string): Promise<boolean> {
+    return this.request("ghostty.claimThreadSurface", { id }, v.boolean());
+  }
+  async ghosttyReleaseThreadSurface(id: string): Promise<void> {
+    await this.request("ghostty.releaseThreadSurface", { id }, EmptyResultSchema);
   }
   shutdown(): Promise<void> {
     return this.request("daemon.shutdown", {}, EmptyResultSchema).then(() => undefined);
@@ -631,9 +730,37 @@ export function daemonSpawnCommand(
   return devWatch ? [execPath, "--watch", "run", mainPath] : [execPath, "run", mainPath];
 }
 
-function spawnDaemon(home: string): void {
-  Bun.spawn(daemonSpawnCommand(process.execPath, import.meta.url), {
-    env: { ...process.env, CUELOOP_HOME: home },
-    stdio: ["ignore", "ignore", "ignore"],
-  }).unref();
+function spawnDaemon(home: string): string {
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  const startupLogPath = join(
+    home,
+    `daemon-startup-${process.pid}-${randomBytes(6).toString("hex")}.log`,
+  );
+  const logFd = openSync(startupLogPath, "wx", 0o600);
+
+  try {
+    if (typeof Bun === "undefined") {
+      const child = spawn(process.env.CUELOOP_EXECUTABLE ?? "cueloop", ["daemon", "--autostart"], {
+        env: { ...process.env, CUELOOP_HOME: home },
+        stdio: ["ignore", logFd, logFd],
+        detached: true,
+      });
+
+      child.on("error", (error) => appendFileSync(startupLogPath, `${String(error)}\n`));
+      child.unref();
+    } else {
+      Bun.spawn(daemonSpawnCommand(process.execPath, import.meta.url), {
+        env: { ...process.env, CUELOOP_HOME: home },
+        stdio: ["ignore", logFd, logFd],
+      }).unref();
+    }
+  } finally {
+    closeSync(logFd);
+  }
+
+  return startupLogPath;
+}
+
+function sleep(durationMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, durationMs));
 }

package/src/ghostty-thread-surface-store.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { GhosttyThreadSurfaceStore } from "./ghostty-thread-surface-store";
+import { ghosttyThreadSurfacesPath } from "./paths";
+
+let home: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-ghostty-store-"));
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("GhosttyThreadSurfaceStore", () => {
+  test("persists terminal IDs outside Thread records and reloads them", () => {
+    const store = new GhosttyThreadSurfaceStore(home);
+
+    store.set("ses_one", { terminalId: "term-1" });
+    expect(new GhosttyThreadSurfaceStore(home).get("ses_one")).toEqual({ terminalId: "term-1" });
+    expect(JSON.parse(readFileSync(ghosttyThreadSurfacesPath(home), "utf8"))).toEqual({
+      ses_one: { terminalId: "term-1" },
+    });
+    store.delete("ses_one");
+    expect(new GhosttyThreadSurfaceStore(home).get("ses_one")).toBeNull();
+  });
+
+  test("ignores malformed scratch state", () => {
+    writeFileSync(ghosttyThreadSurfacesPath(home), '{"ses_one":{"terminalId":3}}');
+
+    expect(new GhosttyThreadSurfaceStore(home).get("ses_one")).toBeNull();
+  });
+
+  test("reserves a Thread before launch and fails closed across daemon restart", () => {
+    const store = new GhosttyThreadSurfaceStore(home);
+
+    expect(store.claim("ses_one")).toBe(true);
+    expect(store.claim("ses_one")).toBe(false);
+    expect(new GhosttyThreadSurfaceStore(home).claim("ses_one")).toBe(false);
+    store.set("ses_one", { terminalId: "term-1" });
+    expect(new GhosttyThreadSurfaceStore(home).claim("ses_one")).toBe(true);
+    store.release("ses_one");
+    expect(new GhosttyThreadSurfaceStore(home).get("ses_one")).toEqual({ terminalId: "term-1" });
+    expect(new GhosttyThreadSurfaceStore(home).claim("ses_one")).toBe(true);
+  });
+});

package/src/ghostty-thread-surface-store.ts

@@ -0,0 +1,101 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import * as v from "valibot";
+import { ghosttyThreadSurfacesPath } from "./paths";
+
+export interface GhosttyThreadSurfaceHandle {
+  terminalId: string;
+}
+
+interface GhosttyThreadSurfaceRecord {
+  terminalId?: string;
+  opening?: true;
+}
+
+const RecordSchema = v.object({
+  terminalId: v.optional(v.string()),
+  opening: v.optional(v.literal(true)),
+});
+const MapSchema = v.record(v.string(), v.unknown());
+
+export class GhosttyThreadSurfaceStore {
+  private surfaces = new Map<string, GhosttyThreadSurfaceRecord>();
+  private readonly path: string;
+
+  constructor(home: string) {
+    this.path = ghosttyThreadSurfacesPath(home);
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      const parsed = v.parse(MapSchema, JSON.parse(readFileSync(this.path, "utf8")));
+
+      for (const [threadId, value] of Object.entries(parsed)) {
+        const handle = v.safeParse(RecordSchema, value);
+
+        if (handle.success) {
+          const record = handle.output;
+
+          this.surfaces.set(
+            threadId,
+            record.opening && record.terminalId ? { terminalId: record.terminalId } : record,
+          );
+        }
+      }
+    } catch {
+      // Scratch corruption cannot change a pending Thread.
+    }
+  }
+
+  private persist(): void {
+    const tempPath = this.path + ".tmp";
+
+    writeFileSync(tempPath, JSON.stringify(Object.fromEntries(this.surfaces), null, 2));
+    renameSync(tempPath, this.path);
+  }
+
+  get(threadId: string): GhosttyThreadSurfaceHandle | null {
+    const terminalId = this.surfaces.get(threadId)?.terminalId;
+
+    return terminalId ? { terminalId } : null;
+  }
+
+  /** Persist a launch reservation before any AppleScript surface can be created. */
+  claim(threadId: string): boolean {
+    const previous = this.surfaces.get(threadId);
+
+    if (previous?.opening) return false;
+    this.surfaces.set(threadId, { ...previous, opening: true });
+
+    try {
+      this.persist();
+
+      return true;
+    } catch (error) {
+      if (previous) this.surfaces.set(threadId, previous);
+      else this.surfaces.delete(threadId);
+
+      throw error;
+    }
+  }
+
+  release(threadId: string): void {
+    const record = this.surfaces.get(threadId);
+
+    if (!record?.opening) return;
+    if (record.terminalId) this.surfaces.set(threadId, { terminalId: record.terminalId });
+    else this.surfaces.delete(threadId);
+    this.persist();
+  }
+
+  set(threadId: string, handle: GhosttyThreadSurfaceHandle): void {
+    const opening = this.surfaces.get(threadId)?.opening;
+
+    this.surfaces.set(threadId, opening ? { ...handle, opening } : handle);
+    this.persist();
+  }
+
+  delete(threadId: string): void {
+    if (this.surfaces.delete(threadId)) this.persist();
+  }
+}