@cueloop/daemon 0.1.0-alpha.37 → 0.1.0-alpha.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.37",
+  "version": "0.1.0-alpha.38",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.37",
+    "@cueloop/schema": "0.1.0-alpha.38",
     "valibot": "^1.4.2"
   },
   "engines": {

package/src/api.ts

@@ -22,6 +22,7 @@ import {
   type WorkspaceKey,
 } from "@cueloop/schema";
 import { SessionStore } from "./store";
+import { HerdrTabStore, type HerdrTabHandle } from "./herdr-tab-store";
 import { DaemonError } from "./errors";
 
 export type EventName =
@@ -40,6 +41,7 @@ type EventListener = (event: DaemonEvent) => void;
 
 export class DaemonCore {
   readonly store: SessionStore;
+  readonly herdrTabs: HerdrTabStore;
   private waiters = new Map<string, ((session: ReviewSession) => void)[]>();
   private listeners = new Set<EventListener>();
   private seq = 0;
@@ -47,6 +49,16 @@ export class DaemonCore {
   constructor(home: string) {
     this.store = new SessionStore(home);
     this.store.recover();
+    this.herdrTabs = new HerdrTabStore(home);
+  }
+
+  /** 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);
+  }
+
+  herdrSetTab(sessionId: string, handle: HerdrTabHandle): void {
+    this.herdrTabs.set(sessionId, handle);
   }
 
   onEvent(listener: EventListener): () => void {
@@ -190,6 +202,7 @@ export class DaemonCore {
   /** Remove a session for good (inbox delete); resolved or pending, both go. */
   sessionDelete(id: string): void {
     if (!this.store.delete(id)) throw new DaemonError("not_found", `no session ${id}`);
+    this.herdrTabs.delete(id);
     this.emit("inbox.changed", id);
   }
 

package/src/client.ts

@@ -14,6 +14,7 @@ import type {
   WorkspaceKey,
 } from "@cueloop/schema";
 import { BackpressureWriter, LineBuffer, type EventFrame, type Response } from "./protocol";
+import type { HerdrTabHandle } from "./herdr-tab-store";
 import { cueloopHome, socketPath } from "./paths";
 
 export type { EventFrame } from "./protocol";
@@ -225,6 +226,13 @@ export class DaemonClient implements SessionClient {
   ): Promise<ReviewSession> {
     return this.request("session.submitRevision", { id, content, addressedAnnotationIds });
   }
+  /** herdr adapter scratch: the tab opened for a review; local-only, off the SessionClient contract. */
+  herdrGetTab(id: string): Promise<HerdrTabHandle | null> {
+    return this.request("herdr.getTab", { id });
+  }
+  async herdrSetTab(id: string, handle: HerdrTabHandle): Promise<void> {
+    await this.request("herdr.setTab", { id, ...handle });
+  }
   shutdown(): Promise<void> {
     return this.request("daemon.shutdown", {});
   }

package/src/herdr-pane.test.ts

@@ -1,4 +1,4 @@
-/** Creation-side herdr pane opener: a stubbed herdr binary logs its argv, and the gating wrapper is checked for its three outcomes (no-op outside herdr, no-op on revision, full open for a new session). */
+/** Creation-side herdr pane opener: a stubbed herdr binary logs its argv, openHerdrPane returns the tab handle, and openHerdrPaneForReview opens+records for a new review, focuses a still-alive recorded tab, and reopens a dead one - collision-free by pane id. */
 
 import { afterAll, describe, expect, test } from "bun:test";
 import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -6,23 +6,30 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ReviewSession } from "@cueloop/schema";
 import { openHerdrPane, openHerdrPaneForReview } from "./herdr-pane";
+import type { HerdrTabPersistence } from "./herdr-pane";
+import type { HerdrTabHandle } from "./herdr-tab-store";
 
 const dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-pane-"));
 
 /**
- * A stub herdr binary. It appends its argv to logPath and, when the verb is
- * `tab create`, prints a JSON result carrying the pane id on stdout so the
- * helper can drive send-text and send-keys. The printed shape mirrors the
- * REAL herdr `tab create` output ({ result: { root_pane: { pane_id } } },
- * verified against herdr 0.8.0) - an earlier stub invented a different shape
- * and let a parser that never matched real herdr pass the suite.
+ * A stub herdr binary. It logs argv, prints the tab-create result carrying both
+ * pane_id and tab_id (herdr 0.8.2 shape), and answers `pane get` alive or dead
+ * per `paneAlive` so the liveness branch can be exercised.
  */
-function makeStub(name: string, paneId = "w1:p2"): { binPath: string; logPath: string } {
+function makeStub(name: string, paneAlive = false): { binPath: string; logPath: string } {
   const logPath = join(dir, `${name}.log`);
   const binPath = join(dir, `${name}.sh`);
+  const paneGet = paneAlive ? `printf '{"result":{"pane":{"pane_id":"w1:p2"}}}'` : "exit 1";
   writeFileSync(
     binPath,
-    `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nif [ "$1" = "tab" ] && [ "$2" = "create" ]; then\n  printf '{"result":{"root_pane":{"pane_id":"${paneId}"}}}'\nfi\n`,
+    `#!/bin/sh
+printf '%s\\n' "$*" >> "${logPath}"
+if [ "$1" = "tab" ] && [ "$2" = "create" ]; then
+  printf '{"result":{"root_pane":{"pane_id":"w1:p2","tab_id":"w1:t2"}}}'
+fi
+if [ "$1" = "pane" ] && [ "$2" = "get" ]; then ${paneGet}; fi
+exit 0
+`,
   );
   chmodSync(binPath, 0o755);
   return { binPath, logPath };
@@ -33,6 +40,23 @@ function readLines(logPath: string): string[] {
   return readFileSync(logPath, "utf8").split("\n").filter(Boolean);
 }
 
+/** In-memory persistence double: records what openHerdrPaneForReview saves. */
+function fakePersistence(initial: HerdrTabHandle | null = null): {
+  persistence: HerdrTabPersistence;
+  saved: () => HerdrTabHandle | null;
+} {
+  let stored = initial;
+  return {
+    persistence: {
+      herdrGetTab: async () => stored,
+      herdrSetTab: async (_sessionId, handle) => {
+        stored = handle;
+      },
+    },
+    saved: () => stored,
+  };
+}
+
 function newSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
   return {
     schemaVersion: "1",
@@ -49,12 +73,12 @@ function newSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
 }
 
 describe("openHerdrPane", () => {
-  test("creates a focused tab, types the cueloop command, and presses enter", () => {
+  test("creates a focused tab, launches the review, and returns the handle", () => {
     // Arrange
     const stub = makeStub("open");
 
     // Act
-    const ok = openHerdrPane({
+    const handle = openHerdrPane({
       sessionId: "ses_abc",
       cwd: "/repo/work",
       binPath: stub.binPath,
@@ -62,7 +86,7 @@ describe("openHerdrPane", () => {
     });
 
     // Assert
-    expect(ok).toBeTrue();
+    expect(handle).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
     expect(readLines(stub.logPath)).toEqual([
       "tab create --cwd /repo/work --label Rollout Plan --focus",
       "pane send-text w1:p2 cueloop ses_abc",
@@ -70,20 +94,18 @@ describe("openHerdrPane", () => {
     ]);
   });
 
-  test("returns false and never throws on a broken binary", () => {
-    // Act
-    const ok = openHerdrPane({
-      sessionId: "ses_abc",
-      cwd: "/repo/work",
-      binPath: join(dir, "missing-bin"),
-      label: "x",
-    });
-
-    // Assert
-    expect(ok).toBeFalse();
+  test("returns null and never throws on a broken binary", () => {
+    expect(
+      openHerdrPane({
+        sessionId: "ses_abc",
+        cwd: "/repo/work",
+        binPath: join(dir, "missing-bin"),
+        label: "x",
+      }),
+    ).toBeNull();
   });
 
-  test("bails out when tab create yields no pane id - no send-text, no send-keys", () => {
+  test("returns null when tab create yields no ids - no send-text, no send-keys", () => {
     // Arrange
     const logPath = join(dir, "nopane.log");
     const binPath = join(dir, "nopane.sh");
@@ -94,22 +116,23 @@ describe("openHerdrPane", () => {
     chmodSync(binPath, 0o755);
 
     // Act
-    const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath, label: "x" });
+    const handle = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath, label: "x" });
 
     // Assert
-    expect(ok).toBeFalse();
+    expect(handle).toBeNull();
     expect(readLines(logPath)).toEqual(["tab create --cwd /repo/work --label x --focus"]);
   });
 });
 
 describe("openHerdrPaneForReview", () => {
-  test("opens a pane for a genuinely new session inside herdr", () => {
+  test("opens and records a tab for a review with no recorded tab", async () => {
     // Arrange
     const stub = makeStub("gated-new");
     const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+    const store = fakePersistence(null);
 
     // Act
-    openHerdrPaneForReview(newSession({ id: "ses_xyz" }), env);
+    await openHerdrPaneForReview(newSession({ id: "ses_xyz" }), store.persistence, env);
 
     // Assert
     expect(readLines(stub.logPath)).toEqual([
@@ -117,35 +140,72 @@ describe("openHerdrPaneForReview", () => {
       "pane send-text w1:p2 cueloop ses_xyz",
       "pane send-keys w1:p2 enter",
     ]);
+    expect(store.saved()).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
   });
 
-  test("no-op outside herdr - no herdr process is spawned", () => {
+  test("no-op outside herdr - no herdr process is spawned", async () => {
     // Arrange
     const stub = makeStub("gated-outside");
+    const store = fakePersistence(null);
 
     // Act
-    openHerdrPaneForReview(newSession(), { HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath });
+    await openHerdrPaneForReview(newSession(), store.persistence, {
+      HERDR_PANE_ID: "w1:p1",
+      HERDR_BIN_PATH: stub.binPath,
+    });
 
     // Assert
     expect(existsSync(stub.logPath)).toBeFalse();
+    expect(store.saved()).toBeNull();
   });
 
-  test("no-op for a revision - the already open pane is reused, not spammed", () => {
+  test("focuses the recorded tab when its pane is still alive, without reopening", async () => {
     // Arrange
-    const stub = makeStub("gated-revision");
+    const stub = makeStub("gated-alive", true);
     const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
-    const revised = newSession({
-      revisions: [
-        { revision: 1, content: "# P", submittedAt: "now" },
-        { revision: 2, content: "# P2", submittedAt: "now" },
-      ],
-    });
+    const store = fakePersistence({ tabId: "w9:t9", paneId: "w9:p9" });
 
     // Act
-    openHerdrPaneForReview(revised, env);
+    await openHerdrPaneForReview(newSession(), store.persistence, env);
 
     // Assert
-    expect(existsSync(stub.logPath)).toBeFalse();
+    const lines = readLines(stub.logPath);
+    expect(lines).toContain("pane get w9:p9");
+    expect(lines).toContain("tab focus w9:t9");
+    expect(lines.some((line) => line.startsWith("tab create"))).toBeFalse();
+    expect(store.saved()).toEqual({ tabId: "w9:t9", paneId: "w9:p9" });
+  });
+
+  test("a persistence failure never escapes - review creation stays best-effort", async () => {
+    // Arrange - the daemon store rejects; the opener must still resolve quietly
+    const stub = makeStub("gated-persist-fail");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+    const persistence: HerdrTabPersistence = {
+      herdrGetTab: async () => null,
+      herdrSetTab: async () => {
+        throw new Error("disk full");
+      },
+    };
+
+    // Act & Assert - no throw
+    await openHerdrPaneForReview(newSession(), persistence, env);
+    expect(readLines(stub.logPath).some((line) => line.startsWith("tab create"))).toBeTrue();
+  });
+
+  test("reopens and re-records when the recorded pane is dead", async () => {
+    // Arrange
+    const stub = makeStub("gated-dead", false);
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+    const store = fakePersistence({ tabId: "old:t", paneId: "old:p" });
+
+    // Act
+    await openHerdrPaneForReview(newSession({ id: "ses_re" }), store.persistence, env);
+
+    // Assert
+    const lines = readLines(stub.logPath);
+    expect(lines).toContain("pane get old:p");
+    expect(lines).toContain("tab create --cwd /repo/work --label Rollout Plan --focus");
+    expect(store.saved()).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
   });
 });
 

package/src/herdr-pane.ts

@@ -1,100 +1,122 @@
 /**
- * Creation-side herdr pane opener: when a review is created from inside a
- * herdr pane, cueloop opens a NEW herdr tab that renders the review, so the
- * creator does not have to run a command by hand. This is the counterpart to
- * the reviewer-side focusHerdrPane in @cueloop/client. It lives here, beside
- * the shared review core (openReview), because both creation sites - the
- * Claude Code hook and the `cueloop session create` CLI - already depend on
- * this package and drive creation through it, so a single home reaches both
- * with no new cross-package dependency.
- *
- * A fresh tab hosts a plain shell with no command argument, so the review is
- * launched exactly as a human would: type `cueloop <sessionId>` into the new
- * pane and press enter. The herdr CLI is spawned synchronously because the
- * send-text and send-keys steps need the pane id that `tab create` returns.
- *
- * Best-effort like the rest of the herdr tier: a missing or broken binary, an
- * unexpected JSON shape, or any spawn failure is swallowed and never blocks
- * review creation. Each spawn is bounded by HERDR_SPAWN_TIMEOUT_MS so a hung
- * herdr binary cannot stall the review-creation path - a timeout kills the
- * child and reads as a non-zero exit, i.e. a best-effort bail-out.
+ * Opens a herdr tab that renders a review, from the creation sites (the Claude
+ * Code hook and `cueloop session create`) that run inside a herdr pane. On a
+ * resubmit it reopens only when the recorded pane is dead, so a live tab is
+ * focused rather than duplicated. Best-effort: any spawn failure is swallowed
+ * and never blocks review creation; each spawn is bounded by a timeout.
  */
 
 import { detectHerdr, type HerdrEnv, type ReviewSession } from "@cueloop/schema";
+import type { HerdrTabHandle } from "./herdr-tab-store";
 
-/** Upper bound per herdr spawn, so a stuck binary can never block creation. */
 const HERDR_SPAWN_TIMEOUT_MS = 2000;
 
 export interface OpenHerdrPaneOptions {
-  /** The review session id; `cueloop <sessionId>` opens it in the new pane. */
   sessionId: string;
-  /** Working directory for the new tab; the review's cwd. */
   cwd: string;
-  /** Absolute path to the herdr binary, from the ambient env contract. */
   binPath: string;
-  /** Sidebar label for the new tab. */
   label: string;
 }
 
+/** The daemon-side handle store, as the two methods this module needs. DaemonClient satisfies it. */
+export interface HerdrTabPersistence {
+  herdrGetTab(sessionId: string): Promise<HerdrTabHandle | null>;
+  herdrSetTab(sessionId: string, handle: HerdrTabHandle): Promise<void>;
+}
+
 /**
- * Open a herdr tab that renders the review. `tab create` prints a JSON result
- * shaped like `{ result: { root_pane: { pane_id } } }` (verified against
- * herdr 0.8.0; `pane get` uses a different `result.pane` nesting, which is
- * what focusHerdrPane reads). The pane id drives the two follow-up steps.
- * Returns true when the full open-and-launch sequence completed, false on any
+ * Open a focused tab and launch the review in it. `tab create` prints
+ * `{ result: { root_pane: { pane_id, tab_id } } }` (herdr 0.8.2); both ids are
+ * returned so a later resubmit can liveness-check and focus. Null on any
  * best-effort bail-out.
  */
-export function openHerdrPane(options: OpenHerdrPaneOptions): boolean {
+export function openHerdrPane(options: OpenHerdrPaneOptions): HerdrTabHandle | null {
   const { sessionId, cwd, binPath, label } = options;
   try {
     const created = Bun.spawnSync(
       [binPath, "tab", "create", "--cwd", cwd, "--label", label, "--focus"],
-      {
-        stdout: "pipe",
-        stderr: "ignore",
-        timeout: HERDR_SPAWN_TIMEOUT_MS,
-      },
+      { stdout: "pipe", stderr: "ignore", timeout: HERDR_SPAWN_TIMEOUT_MS },
     );
-    if (created.exitCode !== 0) return false;
+    if (created.exitCode !== 0) return null;
     const parsed = JSON.parse(created.stdout.toString()) as {
-      result?: { root_pane?: { pane_id?: string } };
+      result?: { root_pane?: { pane_id?: string; tab_id?: string } };
     };
     const paneId = parsed.result?.root_pane?.pane_id;
-    if (!paneId) return false;
+    const tabId = parsed.result?.root_pane?.tab_id;
+    if (!paneId || !tabId) return null;
     // A fresh tab hosts a plain shell, so the review is typed in like a human.
     const typed = Bun.spawnSync([binPath, "pane", "send-text", paneId, `cueloop ${sessionId}`], {
       stdout: "ignore",
       stderr: "ignore",
       timeout: HERDR_SPAWN_TIMEOUT_MS,
     });
-    if (typed.exitCode !== 0) return false;
-    return (
-      Bun.spawnSync([binPath, "pane", "send-keys", paneId, "enter"], {
-        stdout: "ignore",
-        stderr: "ignore",
-        timeout: HERDR_SPAWN_TIMEOUT_MS,
-      }).exitCode === 0
-    );
+    if (typed.exitCode !== 0) return null;
+    const entered = Bun.spawnSync([binPath, "pane", "send-keys", paneId, "enter"], {
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: HERDR_SPAWN_TIMEOUT_MS,
+    });
+    return entered.exitCode === 0 ? { tabId, paneId } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when the pane still exists (`herdr pane get` returns it). */
+function herdrPaneAlive(binPath: string, paneId: string): boolean {
+  try {
+    const got = Bun.spawnSync([binPath, "pane", "get", paneId], {
+      stdout: "pipe",
+      stderr: "ignore",
+      timeout: HERDR_SPAWN_TIMEOUT_MS,
+    });
+    if (got.exitCode !== 0) return false;
+    const parsed = JSON.parse(got.stdout.toString()) as { result?: { pane?: unknown } };
+    return parsed.result?.pane != null;
   } catch {
     return false;
   }
 }
 
+/** Bring an existing review tab to the front; best-effort. */
+function focusHerdrTab(binPath: string, tabId: string): void {
+  try {
+    Bun.spawnSync([binPath, "tab", "focus", tabId], {
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: HERDR_SPAWN_TIMEOUT_MS,
+    });
+  } catch {
+    // best-effort
+  }
+}
+
 /**
- * Open a pane for a freshly created review, guarded for the one case that
- * wants it: inside herdr and genuinely new. A revision reuses the pane the
- * original review already opened, so a resubmit (revisions beyond the first)
- * never spawns another tab. A no-op outside herdr keeps a plain terminal
- * byte-identical.
+ * Ensure a herdr tab is rendering this review. Inside herdr only: focus the
+ * recorded tab if its pane is still alive, otherwise open a fresh one and record
+ * its handle. No-op outside herdr.
  */
-export function openHerdrPaneForReview(session: ReviewSession, env: HerdrEnv = process.env): void {
+export async function openHerdrPaneForReview(
+  session: ReviewSession,
+  persistence: HerdrTabPersistence,
+  env: HerdrEnv = process.env,
+): Promise<void> {
   const herdr = detectHerdr(env);
   if (!herdr) return;
-  if (session.revisions.length !== 1) return;
-  openHerdrPane({
-    sessionId: session.id,
-    cwd: session.artifact.meta.cwd ?? process.cwd(),
-    binPath: herdr.binPath,
-    label: session.artifact.meta.title ?? session.id,
-  });
+  try {
+    const recorded = await persistence.herdrGetTab(session.id);
+    if (recorded && herdrPaneAlive(herdr.binPath, recorded.paneId)) {
+      focusHerdrTab(herdr.binPath, recorded.tabId);
+      return;
+    }
+    const opened = openHerdrPane({
+      sessionId: session.id,
+      cwd: session.artifact.meta.cwd ?? process.cwd(),
+      binPath: herdr.binPath,
+      label: session.artifact.meta.title ?? session.id,
+    });
+    if (opened) await persistence.herdrSetTab(session.id, opened);
+  } catch {
+    // best-effort: a herdr spawn or a daemon persistence hiccup never blocks review creation
+  }
 }

package/src/herdr-tab-store.test.ts

@@ -0,0 +1,95 @@
+/** herdr tab side-store: set/get/delete round-trips, survives a reload from disk, and ignores a corrupt file. */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HerdrTabStore } from "./herdr-tab-store";
+import { herdrTabsPath } from "./paths";
+
+let home: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-herdr-store-"));
+});
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("HerdrTabStore", () => {
+  test("set then get returns the handle; get for an unknown session is null", () => {
+    // Arrange
+    const store = new HerdrTabStore(home);
+
+    // Act
+    store.set("ses_1", { tabId: "w1:t2", paneId: "w1:p2" });
+
+    // Assert
+    expect(store.get("ses_1")).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
+    expect(store.get("ses_missing")).toBeNull();
+  });
+
+  test("handles survive a reload from disk", () => {
+    // Arrange
+    new HerdrTabStore(home).set("ses_1", { tabId: "w1:t2", paneId: "w1:p2" });
+
+    // Act - a fresh store over the same home loads the persisted file
+    const reloaded = new HerdrTabStore(home);
+
+    // Assert
+    expect(reloaded.get("ses_1")).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
+  });
+
+  test("delete removes the handle", () => {
+    // Arrange
+    const store = new HerdrTabStore(home);
+    store.set("ses_1", { tabId: "w1:t2", paneId: "w1:p2" });
+
+    // Act
+    store.delete("ses_1");
+
+    // Assert
+    expect(store.get("ses_1")).toBeNull();
+  });
+
+  test("a corrupt file starts empty instead of throwing", () => {
+    // Arrange
+    writeFileSync(herdrTabsPath(home), "not json");
+
+    // Act
+    const store = new HerdrTabStore(home);
+
+    // Assert
+    expect(store.get("ses_1")).toBeNull();
+  });
+
+  test("malformed entries are dropped, well-formed ones survive", () => {
+    // Arrange - valid JSON, but entries with the wrong shape
+    writeFileSync(
+      herdrTabsPath(home),
+      JSON.stringify({
+        ses_ok: { tabId: "w1:t2", paneId: "w1:p2" },
+        ses_partial: { tabId: "w1:t2" },
+        ses_typed: { tabId: 1, paneId: 2 },
+        ses_null: null,
+      }),
+    );
+
+    // Act
+    const store = new HerdrTabStore(home);
+
+    // Assert
+    expect(store.get("ses_ok")).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
+    expect(store.get("ses_partial")).toBeNull();
+    expect(store.get("ses_typed")).toBeNull();
+    expect(store.get("ses_null")).toBeNull();
+  });
+
+  test("a non-object top level starts empty", () => {
+    // Arrange
+    writeFileSync(herdrTabsPath(home), JSON.stringify(["not", "a", "map"]));
+
+    // Act & Assert
+    expect(new HerdrTabStore(home).get("ses_1")).toBeNull();
+  });
+});

package/src/herdr-tab-store.ts

@@ -0,0 +1,67 @@
+/**
+ * herdr adapter scratch, kept out of the core session record: the tab cueloop
+ * opened to render each review, keyed by session id. One JSON map, atomic write.
+ * The core `ReviewSession` never mentions herdr; this side-store is the whole
+ * leak boundary.
+ */
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { herdrTabsPath } from "./paths";
+
+/** The tab and its root pane: pane id checks liveness, tab id focuses it. */
+export interface HerdrTabHandle {
+  tabId: string;
+  paneId: string;
+}
+
+/** Guard a persisted entry - both ids must be present strings, or it is dropped. */
+function isHerdrTabHandle(value: unknown): value is HerdrTabHandle {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as HerdrTabHandle).tabId === "string" &&
+    typeof (value as HerdrTabHandle).paneId === "string"
+  );
+}
+
+export class HerdrTabStore {
+  private tabs = new Map<string, HerdrTabHandle>();
+  private readonly path: string;
+
+  constructor(home: string) {
+    this.path = herdrTabsPath(home);
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(this.path, "utf8"));
+      if (typeof parsed !== "object" || parsed === null) return;
+      for (const [sessionId, value] of Object.entries(parsed)) {
+        if (isHerdrTabHandle(value))
+          this.tabs.set(sessionId, { tabId: value.tabId, paneId: value.paneId });
+      }
+    } catch {
+      // absent, unreadable, or malformed: start empty - a stale tab just reopens on resubmit
+    }
+  }
+
+  private persist(): void {
+    const tempPath = this.path + ".tmp";
+    writeFileSync(tempPath, JSON.stringify(Object.fromEntries(this.tabs), null, 2));
+    renameSync(tempPath, this.path);
+  }
+
+  get(sessionId: string): HerdrTabHandle | null {
+    return this.tabs.get(sessionId) ?? null;
+  }
+
+  set(sessionId: string, handle: HerdrTabHandle): void {
+    this.tabs.set(sessionId, handle);
+    this.persist();
+  }
+
+  delete(sessionId: string): void {
+    if (this.tabs.delete(sessionId)) this.persist();
+  }
+}

package/src/paths.ts

@@ -25,3 +25,8 @@ export function pidPath(home = cueloopHome()): string {
 export function lockPath(home = cueloopHome()): string {
   return join(home, "cueloop.lock");
 }
+
+/** Adapter scratch: herdr tab handles keyed by session id, kept out of the core session record. */
+export function herdrTabsPath(home = cueloopHome()): string {
+  return join(home, "herdr-tabs.json");
+}

package/src/server.ts

@@ -283,6 +283,13 @@ export class DaemonServer {
         const params = parseParams("session.submitRevision", request.params);
         return core.sessionSubmitRevision(params.id, params.content, params.addressedAnnotationIds);
       }
+      case "herdr.getTab":
+        return core.herdrGetTab(parseParams("herdr.getTab", request.params).id);
+      case "herdr.setTab": {
+        const params = parseParams("herdr.setTab", request.params);
+        core.herdrSetTab(params.id, { tabId: params.tabId, paneId: params.paneId });
+        return {};
+      }
       default:
         throw new DaemonError("unknown_method", `unknown method ${request.method}`);
     }

package/src/validate.ts

@@ -150,6 +150,9 @@ export const Params = {
   "events.subscribe": v.object({}),
   "daemon.ping": v.object({}),
   "daemon.shutdown": v.object({}),
+  // herdr adapter scratch: the review's opened tab, kept off the session record.
+  "herdr.getTab": v.object({ id: SessionId }),
+  "herdr.setTab": v.object({ id: SessionId, tabId: NonEmpty, paneId: NonEmpty }),
 } as const;
 
 export type MethodName = keyof typeof Params;